fix: recover Doable MCP authentication in place

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to Doable Agent Plugins are documented here.
 
+## [0.2.4] - 2026-09-07
+
+### Changed
+
+- Preflight copied context requests against their exact Round and organization
+  before reading local state or scanning source.
+- Recover missing, stale, invalid, or wrong-organization MCP connections in the
+  original conversation. Claude Code users reconnect `doable` once in `/mcp`;
+  they no longer restart the host or paste the request again.
+- Apply the same live-connection preflight to coding-agent-origin feature tests
+  before workspace setup or suite lookup.
+
 ## [0.2.3] - 2026-08-21
 
 ### Changed

PRIVACY.md

@@ -4,7 +4,7 @@ Repository inspection happens inside the coding agent selected by the customer a
 
 ## Doable Code Context
 
-`doable-code-context` performs remote operations only through the configured Doable MCP connection. The coding agent host owns that connection's credential; the Skill and bundled helper neither read nor persist it.
+`doable-code-context` performs remote operations only through the configured Doable MCP connection. The coding-agent host owns that connection's credential. During recovery, the Skill may direct the host to configure a user-supplied key in its user-scoped MCP credential/configuration store, but the bundled helper never reads or persists it and no credential may enter the project workspace or a remote Doable payload.
 
 Its local `.doable/workspace-candidate.json`, `.doable/workspace-private.json`, and `.doable/requests/` records may contain real repository identities, explicitly user-supplied artifact roots, local paths, Git provenance, exact evidence locators, and frozen Doable questions. They are written with private permissions and ignored by Git. Artifact roots are never serialized into the remote workspace profile.
 

README.md

@@ -7,7 +7,7 @@ Official agent plugins for [Doable](https://getdoable.ai), supporting Codex, Cla
 
 | Plugin | Version | Purpose | Network |
 | --- | --- | --- | --- |
-| `doable-code-context` | `0.2.3` | Resolve context requests or start a managed feature-testing workflow | Configured Doable MCP |
+| `doable-code-context` | `0.2.4` | Resolve context requests or start a managed feature-testing workflow | Configured Doable MCP |
 
 ## Workflow
 
@@ -25,8 +25,10 @@ Use **Doable Code Context** for the connected pre-TRD workflow:
    https://github.com/getdoable/doable-agent-plugins#install.
    ```
 
-3. Paste that prompt once. The coding agent checks the Skill and this
-   organization's API Key, connects the workspace if needed, confirms the agreed
+3. Paste that prompt once. Before using local state or scanning code, the coding
+   agent verifies the live MCP connection against that exact Round and organization.
+   It recovers a missing or stale connection in the same conversation, connects the
+   workspace if needed, confirms the agreed
    branch/commit, then pulls that Round and answers from the private
    repositories. If a word in the brief could mean more than one thing in the
    code, it asks the user locally. After the first paste, new questions from the
@@ -49,9 +51,9 @@ All remote operations use the separately configured Doable MCP connection. The b
 - Codex, Claude Code, or Cursor with Agent Skills or plugin support;
 - Node.js 20 or newer;
 - Git for repository-bound evidence;
-- an authenticated Doable MCP connection configured in the coding agent.
+- a Doable organization API key available when the coding agent first connects.
 
-Never paste an API key into chat or save it under `.doable/`. The MCP connection owns organization authentication; the helper never reads a credential or calls the Doable API directly.
+The MCP connection owns organization authentication; the helper never reads a credential or calls the Doable API directly. Prefer the coding-agent host's masked credential input. If a key is supplied during connection recovery, the agent must treat it as a secret, store it only in the host's user-scoped MCP credential/configuration store, and never echo it or write it under the project workspace.
 
 ## Install
 
@@ -85,11 +87,11 @@ In a new Cursor Agent chat, install the plugin:
 /add-plugin doable-code-context@https://github.com/getdoable/doable-agent-plugins
 ```
 
-## Connect Doable MCP once
+## Connect Doable MCP
 
-The plugin supplies Skills and the local privacy helper; it does not bundle or duplicate the remote MCP server. Get the organization API key from Doable Settings and configure the official Streamable HTTP endpoint once in the coding-agent host.
+The plugin supplies Skills and the local privacy helper; it does not bundle or duplicate the remote MCP server. On every entry path, the Skill first verifies the active connection against Doable. A copied Round also verifies the exact `DQ-...` code and organization before any workspace inspection. If recovery is needed, the coding agent configures the user-scoped connection and resumes the original request after the connection refreshes.
 
-Keep the key in the host environment or credential store. Never paste it into chat, commit it, add it to a project-level MCP file, or save it under `.doable/`.
+Keep the key in the host environment or user-scoped credential store. Never commit it, add it to a project-level MCP file, save it under `.doable/`, or print it in agent output.
 
 ### Codex
 
@@ -130,7 +132,7 @@ Make `DOABLE_API_KEY` available to the Cursor process and add the server to the
 }
 ```
 
-Restart the coding-agent host after changing its environment. Confirm that the `doable` tools are connected before starting a context request.
+When configuring the environment ahead of time, launch the coding-agent host from that environment. If Claude Code updates an existing MCP connection during a request, open `/mcp` and reconnect `doable` once; the Skill then retries the original preflight and continues without a restart, a new session, or another copy-paste.
 
 ## Use Doable Code Context
 

SECURITY.md

@@ -12,6 +12,6 @@ Include the plugin version, coding-agent host, and sanitized reproduction steps.
 
 ## Security boundary
 
-`doable-code-context` contains no bundled MCP server, credential store, standalone CLI package, runtime dependency, or telemetry. Its helper has no network or credential primitives: it validates local/private versus remote/sanitized schemas, writes private state atomically with mode `0600`, and checks content-derived payload digests around calls made through the separately configured Doable MCP connection.
+`doable-code-context` contains no bundled MCP server, credential store, standalone CLI package, runtime dependency, or telemetry. Its helper has no network or credential primitives: it validates local/private versus remote/sanitized schemas, writes private state atomically with mode `0600`, and checks content-derived payload digests around calls made through the separately configured Doable MCP connection. Connection recovery may place a user-supplied key only in the coding-agent host's user-scoped MCP credential/configuration store; it must never echo the key or put it in a workspace file, project-scoped MCP file, shell history, or command-line argument.
 
 Never commit `.doable/workspace-candidate.json`, `.doable/workspace-private.json`, or `.doable/requests/`. Rotate a Doable API key if it is pasted into a conversation, terminal transcript, issue, or log.

TESTING.md

@@ -6,25 +6,27 @@ For every scenario, confirm that the agent inspects only evidence needed for the
 
 ## Connected workflow
 
-1. **Demand-driven setup** — Paste a round prompt in a workspace with no `.doable` state. Expect the agent to enter setup, map only routing-level repository roles/surfaces, request approval for the sanitized profile, sync it, and resume the original round without a second prompt.
-2. **Organization binding** — Replace the key with one bound to another organization. Expect setup or pull to stop; state must never be rebound silently.
-3. **Mono-repo and multi-repo** — Confirm every independent Git root receives a stable opaque `repoRef`, while a common parent directory does not. Move one repository and explicitly reuse its `repoRef`; expect identity to survive the path change.
-4. **Profile privacy** — Use repository names, paths, branches, commits, and an internal service name that differ from the safe product role. Capture the PUT body and confirm none appears remotely. The local state must retain them.
-5. **Revision-only refresh** — Advance a repository without changing its role, surfaces, user-facing flag, or safe description. Expect a sync without new user approval. Change a material field and expect approval to be required.
-6. **Watch one Round** — Pull a valid `DQ-...` code. Confirm `Next action: answer` while `open_for_agent` has open questions, `wait` for `ready_to_create` / `needs_attention`, and `stop` for `creating` / `consumed` / `cancelled`. A later pull may add `established_context` plus new open questions; the candidate must cover only the new open IDs. Do not treat `ready_to_create` as finished.
-7. **Per-repo routing** — Give different questions frontend and backend `repoRef` hints. Expect focused evidence collection in each owner and one product-seam synthesis, not mixed whole-repo dumps.
-8. **Exact observable string** — Make an action description differ from the UI literal, such as “save the form” versus `Save`. Expect the finding and anchor to use the verified literal only.
-9. **Existence versus absence** — Ask whether a validation exists. Positive evidence may establish existence. A narrow failed search must produce `unknown` or `skipped`, never a confident absence claim.
-10. **Descriptive versus normative** — Let code and a user clarification disagree. Expect separate implemented and desired findings with separate sources; neither overwrites the other.
+1. **Copied-Round authentication preflight** — Paste a Round prompt with no working `doable` connection. Expect `get_code_context_connection` with the exact `round_code` before the agent uses `.doable` state or scans code; it may read only an optional `workspace.clientRef` for that preflight. After the user supplies the target organization's key once, expect the agent to configure only the host's user-scoped MCP connection. In Claude Code, the only remaining user action is `/mcp` → reconnect `doable`; the agent then retries and resumes the original Round without a restart, new session, or second prompt.
+2. **Coding-agent-origin authentication preflight** — Start a feature-testing request without a copied Round. Expect `get_code_context_connection` before local workspace setup or remote suite search. Recover the connection once and resume the original feature request automatically.
+3. **Demand-driven setup** — Paste a round prompt in a workspace with no `.doable` state. Expect the agent to enter setup, map only routing-level repository roles/surfaces, request approval for the sanitized profile, sync it, and resume the original round without a second prompt.
+4. **Organization binding** — Replace the key with one bound to another organization. Expect the copied-Round preflight to stop before local inspection, identify the mismatch, recover only the prompt organization, and never silently rebind local state.
+5. **Mono-repo and multi-repo** — Confirm every independent Git root receives a stable opaque `repoRef`, while a common parent directory does not. Move one repository and explicitly reuse its `repoRef`; expect identity to survive the path change.
+6. **Profile privacy** — Use repository names, paths, branches, commits, and an internal service name that differ from the safe product role. Capture the PUT body and confirm none appears remotely. The local state must retain them.
+7. **Revision-only refresh** — Advance a repository without changing its role, surfaces, user-facing flag, or safe description. Expect a sync without new user approval. Change a material field and expect approval to be required.
+8. **Watch one Round** — Pull a valid `DQ-...` code. Confirm `Next action: answer` while `open_for_agent` has open questions, `wait` for `ready_to_create` / `needs_attention`, and `stop` for `creating` / `consumed` / `cancelled`. A later pull may add `established_context` plus new open questions; the candidate must cover only the new open IDs. Do not treat `ready_to_create` as finished.
+9. **Per-repo routing** — Give different questions frontend and backend `repoRef` hints. Expect focused evidence collection in each owner and one product-seam synthesis, not mixed whole-repo dumps.
+10. **Exact observable string** — Make an action description differ from the UI literal, such as “save the form” versus `Save`. Expect the finding and anchor to use the verified literal only.
+11. **Existence versus absence** — Ask whether a validation exists. Positive evidence may establish existence. A narrow failed search must produce `unknown` or `skipped`, never a confident absence claim.
+12. **Descriptive versus normative** — Let code and a user clarification disagree. Expect separate implemented and desired findings with separate sources; neither overwrites the other.
     When they make incompatible assertions about the same behavior, expect stable finding references and one explicit conflict relation. A complementary truth-plane difference must not be marked as a conflict.
-11. **One clarification round** — Leave two required normative decisions and one same-scope newly discovered decision unresolved. Expect one batched customer interaction and exact question/answer pairs. Adjacent out-of-scope discoveries stay local.
-12. **Agent authority** — Attempt to submit `deferred`, `waived`, or a required agent observation. Expect local validation to reject it. `skipped` remains available with a bounded reason for platform review.
-13. **Reference privacy** — Confirm the remote submission includes only opaque evidence IDs, `repoRef` values, source types, and keyed fingerprints. Exact files, symbols, lines, revisions, and source content remain local.
-14. **Idempotent retry** — Submit the same candidate twice. Expect one network submission and a local same-digest receipt. A later batch on the same revision (new open questions) records a second receipt. Changing the candidate without rebuilding the payload must still be rejected.
-15. **Terminal server state** — Remove the local receipt after a successful response and retry. Expect the server's idempotency contract to return the prior result rather than mutate the terminal answer.
-16. **No TRD side effect** — Completing an answer batch must keep watching until `Next action: stop`. The plugin must not create a TRD, generate cases, or run tests. `ready_to_create` is not completion.
-17. **Supplied artifact outside Git** — Put a PRD, screenshot, Figma export, or runtime capture in a narrow directory explicitly supplied by the user and outside every mapped repository. Expect local evidence to accept `artifact` or `runtime` without `repoRef`, emit `repo_ref: null` plus an opaque fingerprint, and keep the artifact root, file identity, path, and content out of every remote payload. Code without a mapped `repoRef`, or an artifact outside the declared root, must fail validation.
-18. **Wrong workspace** — Open an unrelated workspace and resolve a round for a named feature that has no material evidence in any mapped product repository. Expect the agent to stop with a concise wrong-workspace warning. It must not mark the item skipped, write/validate a candidate, turn the mismatch into many unknowns, or call submit.
-19. **Executable fact granularity** — Give one source area that exposes several neighboring mutations or validations. Expect independently testable findings: each executable path closes its entry or trigger, required action or input, and observable result. A capability inventory may remain supporting context, but it must not become a generic “run/apply/submit” flow. Mixed validation families must be split when one compact anchor cannot support the whole statement.
-20. **Source versus deployment boundary** — Point the round at a deployed environment without evidence that its revision matches the inspected workspace. Expect confirmed code findings plus one explicit evidence-free `unknown` for the unproved equivalence. Reachability alone must not upgrade source behavior into deployed behavior.
-21. **Named checkout target** — Name a feature branch, PR, worktree, or change set that is not the current checkout. Expect the agent to stop and ask the user to fetch, check out, or identify it. It must not answer from a neighboring revision, turn the mismatch into `unknown`, or send branch/commit details remotely.
+13. **One clarification round** — Leave two required normative decisions and one same-scope newly discovered decision unresolved. Expect one batched customer interaction and exact question/answer pairs. Adjacent out-of-scope discoveries stay local.
+14. **Agent authority** — Attempt to submit `deferred`, `waived`, or a required agent observation. Expect local validation to reject it. `skipped` remains available with a bounded reason for platform review.
+15. **Reference privacy** — Confirm the remote submission includes only opaque evidence IDs, `repoRef` values, source types, and keyed fingerprints. Exact files, symbols, lines, revisions, and source content remain local.
+16. **Idempotent retry** — Submit the same candidate twice. Expect one network submission and a local same-digest receipt. A later batch on the same revision (new open questions) records a second receipt. Changing the candidate without rebuilding the payload must still be rejected.
+17. **Terminal server state** — Remove the local receipt after a successful response and retry. Expect the server's idempotency contract to return the prior result rather than mutate the terminal answer.
+18. **No TRD side effect** — Completing an answer batch must keep watching until `Next action: stop`. The plugin must not create a TRD, generate cases, or run tests. `ready_to_create` is not completion.
+19. **Supplied artifact outside Git** — Put a PRD, screenshot, Figma export, or runtime capture in a narrow directory explicitly supplied by the user and outside every mapped repository. Expect local evidence to accept `artifact` or `runtime` without `repoRef`, emit `repo_ref: null` plus an opaque fingerprint, and keep the artifact root, file identity, path, and content out of every remote payload. Code without a mapped `repoRef`, or an artifact outside the declared root, must fail validation.
+20. **Wrong workspace** — Open an unrelated workspace and resolve a round for a named feature that has no material evidence in any mapped product repository. Expect the agent to stop with a concise wrong-workspace warning. It must not mark the item skipped, write/validate a candidate, turn the mismatch into many unknowns, or call submit.
+21. **Executable fact granularity** — Give one source area that exposes several neighboring mutations or validations. Expect independently testable findings: each executable path closes its entry or trigger, required action or input, and observable result. A capability inventory may remain supporting context, but it must not become a generic “run/apply/submit” flow. Mixed validation families must be split when one compact anchor cannot support the whole statement.
+22. **Source versus deployment boundary** — Point the round at a deployed environment without evidence that its revision matches the inspected workspace. Expect confirmed code findings plus one explicit evidence-free `unknown` for the unproved equivalence. Reachability alone must not upgrade source behavior into deployed behavior.
+23. **Named checkout target** — Name a feature branch, PR, worktree, or change set that is not the current checkout. Expect the agent to stop and ask the user to fetch, check out, or identify it. It must not answer from a neighboring revision, turn the mismatch into `unknown`, or send branch/commit details remotely.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "doable-agent-plugins",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "private": true,
   "description": "Official installable agent plugins for Doable.",
   "license": "MIT",