Skip to content

fix(delegate): contain unsupported remote execution and arm remote start watchdog (#241, #242, #254) - #276

Merged
Alter-Igor merged 9 commits into
devfrom
delegate-remote-fix
Nov 3, 2026
Merged

Alter-Igor merged 9 commits into
devfrom
delegate-remote-fix

Conversation

@Alter-Igor

@Alter-Igor Alter-Igor commented Nov 3, 2026 •

Copy link
Copy Markdown
Owner

Closes #241
Closes #242
Closes #254

Summary by CodeRabbit

  • Behavior Changes
    • Remote task creation, message sending, and one-step delegation are blocked with a policy_unverified notice. Use local Docker for delegation.
    • Remote diagnostics report health and authentication observations separately, without verifying policy, starting execution, or exposing private response details.
    • Remote sessions that do not start are reported as not started after a brief wait.
    • Unsupported remote API requests now return a not-implemented response.
  • Documentation
    • Updated guidance to explain remote execution limits and the scope of remote diagnostics.

@coderabbitai

coderabbitai Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

No actionable comments were generated in the recent review.

Walkthrough

The remote backend now refuses session creation, prompt submission, and runtime execution with policy_unverified. Remote doctor reports bounded health and repository observations without claiming verification. The remote hub tracks turn-start state and reports turns that do not start before its watchdog expires.

Changes: Remote delegation containment

Layer / File(s) Summary
Execution refusal boundaries
alterspective/delegate-mcp/src/remote/api.ts, alterspective/delegate-mcp/src/runtime.ts, alterspective/delegate-mcp/src/server.ts, alterspective/delegate-mcp/README.md, alterspective/delegate-mcp/test/remote-api.test.ts, alterspective/delegate-mcp/test/remote-runtime.test.ts
Remote session creation, prompt submission, and runtime execution refuse with policy_unverified. Unsupported adapter routes return 501. Documentation and integration tests describe and validate the blocked paths.
Remote readiness observations
alterspective/delegate-mcp/src/tools/context.ts, alterspective/delegate-mcp/src/remote/client.ts, alterspective/delegate-mcp/src/tools/doctor.ts, alterspective/delegate-mcp/README.md, alterspective/delegate-mcp/test/remote-client.test.ts, alterspective/delegate-mcp/test/remote-runtime.test.ts
The remote client reports classified health and repository observations. Remote doctor includes available diagnostics and reports execution as unverified. Tests cover response validation, timeouts, redaction, and doctor behavior.
Remote turn-start watchdog
alterspective/delegate-mcp/src/remote/hub.ts, alterspective/delegate-mcp/test/remote-api.test.ts
The hub tracks session state and emits not_started if a sent turn remains idle or starting past the watchdog interval. A started state observed by polling cancels the watchdog.
Decision and verification records
docs/architecture/decisions/*, docs/implementation/current/FEAT-OCD-001-opencode-delegate-mcp/README.md, docs/implementation/current/FEAT-OCD-001-opencode-delegate-mcp/evidence/*
The decision and evidence records describe containment scope, review and approval records, verification results, and remaining delivery gates.

Estimated code review effort: 4 (Complex) | ~60 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant doctorTool
  participant RemoteCodingAgentClient
  participant HealthEndpoint
  participant RepositoryCatalog
  doctorTool->>RemoteCodingAgentClient: Request readiness
  par Observe health
    RemoteCodingAgentClient->>HealthEndpoint: Send anonymous timed GET
    HealthEndpoint-->>RemoteCodingAgentClient: Return health response
  and Observe repository authentication
    RemoteCodingAgentClient->>RepositoryCatalog: Send GET with configured token
    RepositoryCatalog-->>RemoteCodingAgentClient: Return repository response
  end
  RemoteCodingAgentClient-->>doctorTool: Return both observations
Loading

Possibly related issues

  • Alter-Igor/opencode#241: The PR blocks remote execution and changes readiness evidence. The issue’s corrected handoff contract remains unimplemented.
  • Alter-Igor/opencode#254: The PR adds the remote hub start watchdog and sendStarting behavior described by the issue.
  • Alter-Igor/opencode#242: The PR changes remote readiness observations and avoids presenting local checks as remote proof. It does not establish that restart applies the saved configuration.

Possibly related PRs

  • Alter-Igor/opencode#260: Its documentation describes remote support as available, while this PR states that remote execution is blocked.
  • Alter-Igor/opencode#253: This PR implements remote sendStarting and markSent behavior for the hook contract introduced by #253.
  • Alter-Igor/opencode#247: It changes remote patch handling in the delegate flow that this PR blocks before workspace capture or scheduling.
Merge Risk: Minimal · up to 34126

Remote execution remains intentionally unavailable; diagnostics remain accessible. No merge-blocking risk was identified.

Pre-merge checks: Passed 2 · Failed 3

Failed Failed checks: 3 warnings

Check name Status Explanation Resolution
Description check Warning The description contains only the issue closing lines (Closes #241, #242, #254). It omits the required 'Type of change' selection, the 'What does this PR do?' explanation of the issue, the changes mad… Expand the description to follow the repository template. Add: (1) the issue this PR addresses, keeping 'Closes' lines for #241, #242, and #254; (2) the Type of change, which is likely Bug fix; (3) a 'What does this PR do?' section that exp…
Linked Issues check Warning Active coding requirements apply to #241, #242, and #254.

[#254] Met. remote/hub.ts adds startWatchdogMs (default 10,000 ms), arms the watchdog in markSent, emits not_started when no running or termi…
For #241: implement a verified remote start-then-send contract. It must schedule exactly one remote task with the full prompt, model, and engine, keep the title as metadata, and include a regression test with a different title and prompt. C…
Docstring Coverage Warning Docstring coverage is 12.50% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documenta… Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 2 passed
Check name Status Explanation
Title check Passed The title names the two changes in the PR: containment of unsupported remote execution (refusing remote session creation and prompts with policy_unverified) and arming a remote start watchdog. The raw…
Out of Scope Changes check Passed The changed files connect to the linked issues.

- #241 containment: remote/api.ts (refuseRemoteExecution, REMOTE_POLICY_REASON), runtime.ts (remote supervisor and ToolContext refusals), server.ts (in…
Full details: Title check

Explanation

The title names the two changes in the PR: containment of unsupported remote execution (refusing remote session creation and prompts with policy_unverified) and arming a remote start watchdog. The raw summary confirms both are present across api.ts, runtime.ts, hub.ts, and doctor.ts. The title is specific and accurate, though long at 100 characters and includes issue references in parentheses, which is noise but not misleading.

Full details: Out of Scope Changes check

Explanation

The changed files connect to the linked issues.

  • #241 containment: remote/api.ts (refuseRemoteExecution, REMOTE_POLICY_REASON), runtime.ts (remote supervisor and ToolContext refusals), server.ts (instructions), README.md (delegate_task description), and the ADR and evidence records document the containment and its limits.
  • #241 and #242 readiness truthfulness: remote/client.ts (readiness observer), tools/context.ts (RemoteObservation and RemoteReadiness types), and tools/doctor.ts (remote short-circuit) separate remote health and authentication observations from local Docker verification.
  • #254: remote/hub.ts watchdog changes and their tests.
  • Tests: remote-api.test.ts, remote-client.test.ts, and remote-runtime.test.ts cover these changes. The end-to-end remote-runtime tests replace earlier unit tests of the same remote runtime paths.

The removal of the remote /models and /mcp responses and of stored permission data from session status follows from the containment. These removals reduce remote functionality, but they are tied to the linked issues rather than unrelated. The reviewed summary does not establish any unrelated change.

Full details: Description check

Explanation

The description contains only the issue closing lines (Closes #241, #242, #254). It omits the required 'Type of change' selection, the 'What does this PR do?' explanation of the issue, the changes made, and why they work, the 'How did you verify your code works?' section, and the checklist. The description is largely incomplete relative to the repository template.

Resolution

Expand the description to follow the repository template. Add: (1) the issue this PR addresses, keeping 'Closes' lines for #241, #242, and #254; (2) the Type of change, which is likely Bug fix; (3) a 'What does this PR do?' section that explains the remote-execution containment, the policy_unverified refusal path, the remote doctor observation changes, and the remote start watchdog, with the reasoning for each; (4) a 'How did you verify your code works?' section that lists the commands run and their results, such as bun typecheck and the bun test runs for the remote test files; (5) the checklist items, marked after confirming local testing and that no unrelated changes are included. Write the explanation in your own words, because the template warns that large AI-generated descriptions may be closed.

Full details: Linked Issues check

Explanation

Active coding requirements apply to #241, #242, and #254.

[#254] Met. remote/hub.ts adds startWatchdogMs (default 10,000 ms), arms the watchdog in markSent, emits not_started when no running or terminal state is observed, ignores pre-start idle while the watchdog is armed, and cancels the watchdog on busy, retry, error, aborted, and stop. test/remote-api.test.ts covers the not_started transition, watchdog cancellation, and polling restart. Note: remote session creation is now refused, so this watchdog has no production remote session to guard until a replacement contract exists.

[#241] Not met. remote/api.ts now throws policy_unverified for POST /session and POST /session/:id/prompt_async (refuseRemoteExecution). No start-then-send handoff is scheduled. The issue requires that start then send schedule exactly one remote task with the intended prompt, model, and engine, and that a regression test use a different title and prompt. The PR provides neither. The issue also requires modern and legacy handler tests that assert outbound payloads. The tests in remote-api.test.ts and remote-runtime.test.ts assert refusal instead. The refusal does reject unsupported permission/profile requests before scheduling, which the issue allows, but it does not meet the start-then-send acceptance criteria. The PR description states that it closes #241, which this code does not support.

[#242] Not met. Remote restart is refused with policy_unverified, so the MCP entries and TLS-front servers.conf are not applied or verified against the saved Keystone set. Remote code_doctor reports verified:false in every case (doctor.ts short-circuit). The remote /models and /mcp routes were removed, so remote model listing returns status 501 with no data. The issue expects code_list_models to list models after a restart. The refusal is a blanket policy block, not a result that reports a mismatch between the box and the saved Keystone set, so the issue's failure-report branch is not met as specified.

Summary: #254 is met. #241 and #242 are not met.

Resolution

For #241: implement a verified remote start-then-send contract. It must schedule exactly one remote task with the full prompt, model, and engine, keep the title as metadata, and include a regression test with a different title and prompt. Cover the modern fast-path and legacy start/send handlers through the remote adapter, asserting outbound payloads and the status, result, collection, and cleanup contracts. Keep unsupported permission or profile requests explicit and rejected before scheduling. Do not close #241 until these tests pass.

For #242: make remote restart apply the saved Keystone set to the box MCP entries and servers.conf, then verify both. If the box cannot match the set, return a specific mismatch result from restart instead of a blanket policy refusal. Restore a truthful remote code_list_models path that lists models from the verified contract. Keep code_doctor verified:false until the verification passes.

Full details: Docstring Coverage

Explanation

Docstring coverage is 12.50% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 8 functions across 10 files.

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

Finishing Touches
Generate docstrings
  • Commit to this branch
  • Create a new PR
Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Usage-based review receipt

Note

This review was completed with usage-based billing: files reviewed beyond your plan's included limits are billed at $0.25/file. View usage-based billing.

CodeRabbit Verify

  • Run CodeRabbit Verify to test the changes in this pull request.
Recent review info
Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Team
  • Run ID: a6281917-2de8-43aa-85a7-84c051071357
Commits

Reviewing files that changed from the base of the PR and between fc2c298 and 341266d.

Files selected for processing: 1
  • alterspective/delegate-mcp/src/remote/hub.ts

Limit details: You’ve used all 6 included reviews currently available. Your 43 included PR review attempts over the past 7 days set your current allowance at 6 reviews per hour.

@Alter-Igor

Copy link
Copy Markdown
Owner Author

ARCH-GATE-02: ALIGNED sha=bd4bbcddc0f2417c4727c57ffec2e8e33a6b4695
QA-VERDICT: PASS sha=bd4bbcddc0f2417c4727c57ffec2e8e33a6b4695

  • Principal Architect (ARCH-GATE-02): Verified fail-closed remote execution containment (refuseRemoteExecution() -> policy_unverified) across runtime.ts and remote/api.ts (#241), truthful remote readiness without fabricated ks-identity or local servers.conf checks (#242), and sendStarting/markSent start watchdog in remote/hub.ts (#254).
  • Fresh QA (AILES-113): Verified bun typecheck and bun test test/remote-api.test.ts test/remote-client.test.ts test/remote-git.test.ts test/remote-runtime.test.ts (46 pass, 0 fail).

@coderabbitai coderabbitai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Fix comments: Fix CodeRabbit comments on this PR

@Alter-Igor

Copy link
Copy Markdown
Owner Author

ARCH-GATE-02: ALIGNED sha=fc2c2981b4093997f19c61c7057046dd5567e8ff
QA-VERDICT: PASS sha=fc2c2981b4093997f19c61c7057046dd5567e8ff

  • Principal Architect (ARCH-GATE-02): Re-verified after resolving CodeRabbit review thread (PRRT_kwDOTYJEpc6zFK9Z in src/remote/hub.ts: markSent restarts polling when info.timer was stopped after idle, and pollSession ignores pre-start idle while start watchdog is armed).
  • Fresh QA (AILES-113): Verified bun typecheck and bun test test/remote-api.test.ts (5 pass, 0 fail).

@coderabbitai coderabbitai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Fix comments: Fix CodeRabbit comments on this PR

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Additional comments: 1
alterspective/delegate-mcp/src/remote/hub.ts-109-110: 1

109-110: Minor · Functional Correctness · Quick win

Unverified finding
Verification ran but could not confirm this finding. It is shown for review, not as a verified issue.

Preserve not_started after the watchdog expires.

If getTask returns done after the watchdog expires, watchdogCancel is already undefined. This guard then permits pollSession to replace not_started with idle, although the turn never started. A done poll that returns before expiry also leaves the interval polling indefinitely after not_started, because later polls see the same lastState.

Keep the pre-start idle suppression in effect after expiry. Stop or bound polling when the watchdog reports not_started, including any poll already in flight.

Review info
Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Team
  • Run ID: be956e1d-62bc-4058-8500-3ac0d8e72f44
Commits

Reviewing files that changed from the base of the PR and between 8aefa4f and fc2c298.

Files selected for processing: 1
  • alterspective/delegate-mcp/src/remote/hub.ts

Limit details: You’ve used all 6 included reviews currently available. Your 43 included PR review attempts over the past 7 days set your current allowance at 6 reviews per hour.

@Alter-Igor

Copy link
Copy Markdown
Owner Author

ARCH-GATE-02: ALIGNED sha=341266d1def15d6b598df6825786df42d08b7702
QA-VERDICT: PASS sha=341266d1def15d6b598df6825786df42d08b7702

  • Principal Architect (ARCH-GATE-02): Verified track directory update in 341266d1def15d6b598df6825786df42d08b7702.
  • Fresh QA (AILES-113): Verified bun typecheck and bun test test/remote-api.test.ts (5 pass, 0 fail).

@Alter-Igor
Alter-Igor merged commit 288b573 into dev Nov 3, 2026
8 checks passed
@Alter-Igor
Alter-Igor deleted the delegate-remote-fix branch November 3, 2026 11:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant