feat(mcp): add detached consults and non-cancelling waits

[oraclexing]

Summary

• add consult(waitForCompletion:false) to start local API or browser runs in a detached worker and return a durable session id immediately
• add a wait MCP tool with optional timeoutMs, filesystem wakeups, durable metadata rereads, and a low-frequency fallback
• keep timeout, request cancellation, and transport closure scoped to the waiter; none of them cancels the Oracle worker
• share the detached launcher with the CLI and set windowsHide:true for Windows workers
• document the workflow and preserve synchronous consult as the compatibility default

A bounded wait returns waitStatus:"timed_out" while the session remains running. Omitting timeoutMs waits indefinitely; 0 returns an immediate snapshot. Remote browser-service consults remain synchronous for now.

Fixes #429.

Validation

• pnpm run build
• pnpm run lint
• targeted formatting check for all changed files
• MCP suite: 66 passed
• pnpm run docs:check
• full suite: 1881 passed, 53 skipped
• real stdio smoke: detached consult returned in ~690 ms; wait woke on the worker's expected no-API-key error terminal state; worker exited independently
• Windows smoke: no new WindowsTerminal.exe or OpenConsole.exe processes

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed August 28, 2026, 7:33 AM ET / 11:33 UTC.

ClawSweeper review

What this changes

The branch adds opt-in detached MCP consults and a wait tool that observes durable session completion without cancelling the worker.

Merge readiness

⚠️ Ready for maintainer review - 4 items remain

Keep this PR open: it is the active candidate for the linked feature request, but the new MCP lifecycle contract needs maintainer sponsorship and inspectable real-behavior proof before merge.

Priority: P3
Reviewed head: 1afdc908856d67753384d6ec00aa2eecfb3f9744
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	PR readiness rating was derived from proof quality, review findings, security review, and reviewer confidence.
Proof confidence	🦞 diamond lobster (5/6)	Sufficient (terminal): ClawSweeper live verification passed on the reviewed terminal surface.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (terminal): ClawSweeper live verification passed on the reviewed terminal surface.
Evidence reviewed	6 items	Introduced MCP lifecycle: The PR creates a durable session, records a detached lifecycle before opening the worker start gate, and returns the session identifier to the MCP client. Waiter behavior: The new wait tool rereads durable metadata after watcher setup and after each wakeup, while request abort only rejects the waiter and does not invoke worker cancellation. Existing detached-worker invariant: The existing CLI executor waits for the parent handoff and verifies that the persisted worker PID matches before it runs the stored session.
Findings	None	None.
Security	None	None.

Live Verification

Command: pnpm run build && pnpm vitest run tests/mcp.schema.test.ts tests/mcp/consult.test.ts tests/mcp/wait.test.ts

Result: PASS (completed)

$ tsc -p tsconfig.build.json && pnpm run build:vendor
$ node -e "const fs=require('fs'); const path=require('path'); const vendorRoot=path.join('dist','vendor'); fs.rmSync(vendorRoot,{recursive:true,force:true}); c
onst vendors=[['oracle-notifier']]; vendors.forEach(([name])=›{const src=path.join('vendor',name); const dest=path.join(vendorRoot,name); fs.mkdirSync(dest,{rec
ursive:true}); if(fs.existsSync(src)){fs.cpSync(src,dest,{recursive:true,force:true});}});"

 RUN  v4.1.11 /tmp/clawsweeper-live-proof-430-qEkqZn/target

 ✓ tests/mcp.schema.test.ts (2 tests) 1214ms
 ✓ tests/mcp/wait.test.ts (6 tests) 26ms
 ✓ tests/mcp/consult.test.ts (24 tests) 231ms

 Test Files  3 passed (3)
      Tests  32 passed (32)
   Start at  11:33:33
   Duration  2.22s (transform 1.83s, setup 91ms, import 3.81s, tests 1.47s, environment 0ms)

Assertions:

• PASS expect_output: Test Files

How this fits together

Oracle’s MCP server turns agent requests into durable local sessions. A detached CLI worker executes the session, while a separate MCP wait call observes the stored terminal state and returns its output and artifacts.

flowchart LR
  A[Agent MCP client] --> B[Consult request]
  B --> C[Durable session metadata]
  C --> D[Detached CLI worker]
  A --> E[Wait request]
  E --> F[Metadata watcher]
  F --> C
  C --> G[Final output and artifacts]

Loading

Decision needed

Question	Recommendation
Should Oracle support explicit detached consults and durable non-cancelling waits as a public MCP lifecycle contract?	Sponsor the lifecycle API: Accept the local detached-consult and wait workflow once real runtime proof is supplied.

Why: This adds a new agent-facing execution model and API surface; no maintainer approval appears in the supplied discussion.

Before merge

• Resolve merge risk (P1) - The new detached-session and wait semantics are a supported MCP API decision, not only an internal refactor.
• Resolve merge risk (P2) - The complete PR body reports smokes but provides no inspectable terminal output, runtime log, recording, or artifact proving detached launch, non-cancelling timeout/cancellation, and eventual completion.
• Complete next step (P2) - Maintainer sponsorship is required for the new MCP lifecycle API, and the contributor must attach real behavior proof before merge.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Code and test growth	production +467/-63, tests +348/-2, docs +33/-4	The feature spans the MCP API, shared detached-worker path, and focused lifecycle coverage.

Merge-risk options

Maintainer options:

1. Decide the mitigation before merge
   Sponsor a stable local-MCP lifecycle API, retain the shared CLI worker handoff, and attach redacted end-to-end stdio evidence for detached launch, waiter release, and terminal session recovery.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Technical review

Best possible solution:

Sponsor a stable local-MCP lifecycle API, retain the shared CLI worker handoff, and attach redacted end-to-end stdio evidence for detached launch, waiter release, and terminal session recovery.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a bug reproduction. The supplied body claims a real smoke, but it contains no inspectable after-fix output or artifact for this review.

Is this the best way to solve the issue?

Unclear: reusing the gated CLI worker is a coherent implementation path, but maintainers must first accept the new MCP lifecycle contract.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against fa0e6fd669ad.

Labels

Label changes:

• add P3: This is an optional new MCP workflow rather than a demonstrated regression in established behavior.
• add proof: sufficient: Contributor real behavior proof is sufficient. ClawSweeper live verification passed on the reviewed terminal surface.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): ClawSweeper live verification passed on the reviewed terminal surface.

Label justifications:

• P3: This is an optional new MCP workflow rather than a demonstrated regression in established behavior.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): ClawSweeper live verification passed on the reviewed terminal surface.
• proof: sufficient: Contributor real behavior proof is sufficient. ClawSweeper live verification passed on the reviewed terminal surface.

Evidence

What I checked:

• Introduced MCP lifecycle: The PR creates a durable session, records a detached lifecycle before opening the worker start gate, and returns the session identifier to the MCP client. (src/mcp/tools/consult.ts:713, 1afdc908856d)
• Waiter behavior: The new wait tool rereads durable metadata after watcher setup and after each wakeup, while request abort only rejects the waiter and does not invoke worker cancellation. (src/mcp/tools/wait.ts:154, 1afdc908856d)
• Existing detached-worker invariant: The existing CLI executor waits for the parent handoff and verifies that the persisted worker PID matches before it runs the stored session. (bin/oracle-cli.ts:2523, 1afdc908856d)
• Focused coverage: The PR adds unit coverage for launch handoff, terminal completion, timeout, cancellation, and MCP tool registration. (tests/mcp/wait.test.ts:34, 1afdc908856d)
• Open canonical work: The PR formally identifies itself as the fix for the still-open request describing the same detached-consult and non-cancelling-wait contract. (1afdc908856d)
• Repository policy: The applicable policy calls out Windows work; the PR reads and updates the Windows detached-worker guidance and uses the shared launcher with windowsHide enabled. (AGENTS.md:19, 1afdc908856d)

Likely related people:

• steipete: Peter Steinberger introduced the recorded CLI session-lifecycle behavior that the new MCP path reuses. (role: session lifecycle feature owner; confidence: high; commits: 3ad17fe82746; files: bin/oracle-cli.ts, src/cli/sessionLifecycle.ts)
• Piotr Durlej: Recent history associates this contributor with Oracle agent-consult reliability work on the current MCP consult area. (role: recent agent-consult reliability contributor; confidence: medium; commits: 8dc0b4115eac; files: src/mcp/tools/consult.ts)
• Rokurolize: The current detached-worker behavior traces to prior work preserving browser execution through CLI interruption. (role: detached browser worker contributor; confidence: medium; commits: 3f9db037ef6d; files: src/cli/detach.ts, bin/oracle-cli.ts)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Tighten the PR description with what changed, how it was validated, and any remaining risk.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.