test: [de-fork S2] execution-route matrix + sentinel tests

Closed
AN
1mo ago
+599-0

PINEAPPLE

Summary

Stage S2 of the de-fork spike: the authoritative map of every tool-execution dispatcher (where a resolved tool's .execute() actually runs), so stage S3's HardPolicy knows every chokepoint it must cover. Analysis + executable sentinel tests only — zero product-code change.

Deliverables:

  • docs/internal/defork-route-matrix.md — ingress surfaces vs execution dispatchers (D1–D8), each classified active / latent / out-of-scope with file:line evidence.
  • packages/opencode/test/altimate/defork/route-sentinels.test.ts — an executable sentinel per active route, driving a harmless tool through the real dispatch code and asserting execution reaches the documented line.

Key findings (these shape S3's HardPolicy)

  • SessionTools.resolve (D3/D4) is latent — zero production callers at HEAD (a guard test flips if that changes), so it isn't a current bypass.
  • The real bypass is BatchTool inner dispatch (tool/batch.ts:104) — it skips Plugin.trigger and source-stamping.
  • All active dispatchers live in 3 files (session/prompt.ts, tool/batch.ts, session/tools.ts) → S3's ≤3-file audited-patch budget is feasible.
  • Flags a pre-existing security gap (out of this spike's scope): the server-v2 shell HTTP route has only a session-existence check, no permission gate.

Test Plan

  • bun test test/altimate/defork/route-sentinels.test.ts: 9 pass / 0 fail (verified in the primary dev worktree).

Checklist

  • Tests added/updated
  • Documentation updated (route matrix)
  • CHANGELOG updated — N/A (internal analysis + tests)

Closes #1011

Summary by cubic

Maps all tool-execution dispatchers and adds sentinel tests to pin and exercise each route; commits the S2 spec and clarifies MCP checks and the BatchTool permission bypass. Adds an explicit coverage contract and expands latent-guard scanning; no product code changes. Closes #1011.

  • Highlights
    • Docs: docs/internal/defork-route-matrix.md updated with a precise “Coverage contract” (D1/D5 have real-execution sentinels; D2/D6 use documented transitive/citation coverage), plus out-of-scope entries and the v1+v2 shell route gap (tracked in #1019); committed docs/internal/2026-07-18-defork-spike-spec.md.
    • Tests: packages/opencode/test/altimate/defork/route-sentinels.test.ts (9 passing) with line- and arg-agnostic chokepoint pins; latent guard now scans the entire src tree including .tsx for SessionTools.resolve( callers; D1 and D5 exercise real dispatch.
    • Clarifications: D2/D4 PermissionNext.ask is deny-capable with wildcard patterns; D5 BatchTool inner dispatch is a real permission bypass; D6 direct task dispatch is ungated today (bypassAgentCheck=true). All active dispatchers remain in session/prompt.ts, tool/batch.ts, session/tools.ts.

Summary by CodeRabbit

  • Documentation

    • Added an internal “S2 de-fork” execution-route and reachability matrix documenting dispatcher expectations, gating/plugin behavior, and noted bypass/coverage gaps.
    • Added the “De-fork Spike” build spec (rev 4) describing staging gates and replay/diff constraints.

  • Tests

    • Added route-sentinel tests covering direct tool dispatch, latent-call-site guards, mocked-layer resolution, batch inner-tool dispatch behavior, and task/tool metadata handling.
    • Added structural and citation checks to ensure existing real-execution and metadata-preservation behavior.