[bradygaster]

What

A credential-gated live variant of the golden conformance trace (test-fixtures/spec/suite-v0.2/golden-trace.json, decoupling §14.4, G1–G9) on the real claude-agent-sdk harness, with its host-feature matrix and specification documentation. Repairs bc26ccf2 and 550f5955 address the existing findings, including the independent review's short-tool-timeout cancellation false positive. Independent acceptance, required hosted validation, and strengthened live verification remain pending.

Why

Part of #2441, after #2451. The golden trace previously ran against a fake harness. The original live smoke result did not adequately prove replay continuity, cursor filtering, or cancellation of an executing long-running command. This repair strengthens those assertions rather than treating the earlier pass as promotion evidence.

How

The test drives the real Agent SDK through LocalSquadBackend:

1. A turn requests one foreground Bash command: touch squad-golden-marker.txt && exec sleep 60.
2. Before approval, the action must equal that exact command label. Test-owned interception also captures the actual full SDK tool input and binds it to the approval hash: the command must match exactly, run_in_background must be explicitly false, and timeout must be explicitly 120000 milliseconds, comfortably beyond the ten-second cancellation deadline. Any mismatch fails into cleanup without approval; raw tool arguments are not exposed in the production broker.
3. A replacement client verifies the saved replay prefix, unique event IDs, the empty cursor suffix while awaiting approval, resumable, lastAcceptedSeq, and the retained approval.
4. The broker approves the harness-supplied ID/hash; the marker signals command startup.
5. Cancellation must settle the harness within 10 seconds, well below its 60-second command. The final history and nonempty cursor suffix must preserve the fixture's backend events in order.
6. finally cancels and settles the harness before deleting its working directory, including assertion and polling failures.

The fixture's ordered events and terminal cancelled state remain required. New non-live deterministic tests reject the one-second timeout from an abort-ignoring transport, background execution, and omitted timeout before any approval; an abort-honouring long-timeout control is included. No runtime source, dependency versions, feature gates, or required checks are changed or disabled.

Live tests require explicit SQUAD_REAL_CLI_TESTS=1 plus supported API credentials and the optional Agent SDK. Opting in without the prerequisites now fails with the harness's descriptive error rather than silently skipping. No paid live API calls were made during this repair.

Evidence

The author's original 2026-11-10 direct-API smoke run passed in 8.1 seconds with Agent SDK 0.3.317. It is retained as historical evidence only: its weaker assertions did not establish replay continuity or prompt cancellation of an executing sleep. The strengthened golden trace awaits a new authorized credentialed run and is not yet promotion evidence.

Repair validation:

• SKIP_BUILD_BUMP=1 npm run build — passed, SDK and CLI.
• npm run lint — passed, both package typechecks.
• node scripts/render-host-feature-matrix.mjs — passed, regenerated reference.
• node scripts/render-host-feature-matrix.mjs --check — passed, generated page current.
• git diff --check — passed.
• node --input-type=module inline deterministic smoke — passed against the built real adapter/backend with an injected scripted SDK and a real local foreground command: exact approval, full replay, empty/nonempty cursor suffixes, unique IDs, command-start signal, bounded abort/settlement, and golden event order. This was not Vitest execution or live-SDK/model evidence.
• Follow-up node ../pr-2452-cycle3-smoke.mjs — passed using the actual candidate input guard and golden-test callback with all 23 golden assertions plus an independent real-process oracle. The abort-honouring, explicit 120-second foreground control passed in 19 ms without tool timeout. Short-timeout/abort-ignoring, background, and missing-timeout variants were rejected before approval/process start with completed cleanup. A counterfactual bypass of only the new guard reproduced the old false-positive pass in 1005 ms via tool timeout, demonstrating that the negative distinguishes the defect. No model/API calls; not a Vitest-suite or live-SDK run.
• node node_modules/typescript/bin/tsc --ignoreConfig --noEmit --target ES2022 --module NodeNext --moduleResolution NodeNext --esModuleInterop --skipLibCheck --strict --noUncheckedIndexedAccess --resolveJsonModule test/claude-agent-sdk-harness.test.ts — standalone test-file check reported the same two pre-existing TS2554 diagnostics as the bc26ccf2 baseline (old three-argument respondApproval calls); an in-memory compiler-host comparison confirmed no new diagnostics. Package typechecks above passed.
• SQUAD_REAL_CLI_TESTS=0 npm test -- --run test/claude-agent-sdk-harness.test.ts test/harness-contract.test.ts test/test-reconciliation.test.ts — blocked at runner startup, missing locked vite; no assertions ran. The full Vitest suite and matrix tests remain pending hosted validation.
• npm exec --no -- eslint test/claude-agent-sdk-harness.test.ts — blocked at startup, missing js-yaml; full npm run lint:eslint was not run locally.
• npm run lint:docs — blocked, missing markdownlint-cli2.

Dependency recovery was bounded: npm ci --ignore-scripts --no-audit --no-fund --fetch-retries=0 --fetch-timeout=20000 received a proxy 404 for locked Vite 8.3.6; the official registry alternative failed at the network/TLS layer. Matching same-repository package payloads (version and lockfile integrity verified) recovered the successful build/typechecks. No package versions were substituted or manifests modified. Normal required hosted CI is pending; missing local checks are not claimed as passes or waived.

---

⚠️ Quick Check

• If SDK/CLI source files changed: completed the applicable Changeset step below (npx changeset add / .changeset/*.md, direct CHANGELOG.md entry for maintainers, or skip-changelog label for no user-facing changes)

No SDK/CLI source files changed: tests, specification, matrix JSON, and generated reference only; changeset not required.

PR Readiness Checklist

The PR readiness bot will validate these automatically after push.
Check each item before requesting review. See CONTRIBUTING.md for full details.

Branch & Commit

• Branch created from dev (not main)
• Branch is up to date with dev (git fetch upstream && git rebase upstream/dev)
• Verified diff contains only intended changes (git diff --cached --stat)
• PR is not in draft mode (mark ready when checks pass)
• Commit history is clean (squash fixups before review)

Current dev 675c9e97 is an ancestor. The original author commit and two fast-forward review-repair commits are retained without rewriting the active author branch.

Build & Test

• npm run build passes
• npm test passes (all tests green)
• npm run lint passes (type check clean)
• npm run lint:eslint passes
• For migration PRs (>20 files): include test output summary in PR description

Four files only; migration summary is not applicable. Required hosted tests/lint remain pending; see exact local results above.

Changeset

• Changeset added via npx changeset add (if packages/squad-sdk/src/ or packages/squad-cli/src/ changed)
• Or direct CHANGELOG.md entry (maintainers only — write-protected for external contributors)
• Or skip-changelog label applied (if no user-facing changes)

Not applicable: no SDK/CLI source changes. No skip label or waiver applied.

Docs

• README section updated (if new feature/module)
• Docs feature page (if new user-facing capability)

No new product feature/module; README and feature-page additions are not applicable. Specification §12 and generated matrix reference explain the strengthened trace and pending live verification.

Exports

• package.json subpath exports updated (if new module)

Not applicable: no new SDK module or export.

---

Breaking Changes

None.

Waivers

None. Required hosted checks, independent review, and authorized strengthened live verification remain pending. No merge or ready action is requested.

[github-actions]

🟡 Impact Analysis — PR #2452

Risk tier: 🟡 MEDIUM

📊 Summary

Metric	Count
Files changed	4
Files added	0
Files modified	4
Files deleted	0
Modules touched	3

🎯 Risk Factors

• 4 files changed (≤5 → LOW)
• 3 modules touched (2-4 → MEDIUM)

📦 Modules Affected

docs (2 files)

• docs/specification/client-backend-decoupling-v0.2.md
• docs/src/content/docs/reference/host-feature-matrix.md

root (1 file)

• test-fixtures/spec/suite-v0.2/host-feature-matrix.json

tests (1 file)

• test/claude-agent-sdk-harness.test.ts

---

This report is generated automatically for every PR. See #733 for details.

[github-actions]

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit 550f595

PR Scope: 🔧 Infrastructure

⚠️ 3 item(s) to address before review

Status	Check	Details
❌	Single commit	3 commits — consider squashing before review
✅	Not in draft	Ready for review
✅	Branch up to date	Up to date with dev
❌	Copilot review	No Copilot review yet — it may still be processing
✅	Changeset present	No source files changed — changeset not required
✅	Scope clean	No .squad/ or docs/proposals/ files
✅	No merge conflicts	No merge conflicts
✅	Copilot threads resolved	0 active Copilot thread(s) resolved (3 outdated skipped)
❌	CI passing	2 check(s) failing: test, docs-quality

Files Changed (4 files, +262 −6)

File	+/−
docs/specification/client-backend-decoupling-v0.2.md	+13 −1
docs/src/content/docs/reference/host-feature-matrix.md	+2 −1
test-fixtures/spec/suite-v0.2/host-feature-matrix.json	+13 −2
test/claude-agent-sdk-harness.test.ts	+234 −2

Total: +262 −6

---

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

[Copilot]

🟡 Changes recommended

The harness tests can pass despite replay/cursor regressions or ineffective cancellation, and failure paths can leave SDK subprocesses running.

3 open issues

• Replay test does not verify event continuity or cursor handling · New
• Test cancellation during a confirmed long-running command · New
• Ensure query cancellation and settlement on test failures · New

What changed in this PR

Adds a live golden-trace test for the Claude Agent SDK harness through LocalSquadBackend, addressing the remaining Phase 1 testing item in #2441 after #2451.

Changes:

• Adds a credential-gated test covering approval, client reconnect, approved command execution, and cancellation.
• Records the reported live run in the host feature matrix and regenerated reference documentation.
• Updates the decoupling specification to reference the live trace.

File	Description
test/​claude-agent-sdk-harness.test.ts	Adds the live G1–G9 golden-trace scenario.
test-fixtures/​spec/​suite-v0.2/​host-feature-matrix.json	Records Claude golden-trace evidence and live-run details.
docs/​src/​content/​docs/​reference/​host-feature-matrix.md	Reflects the updated matrix evidence.
docs/​specification/​client-backend-decoupling-v0.2.md	Documents live Claude harness coverage of the trace.

_{Review effort: Balanced (auto)}

[bradygaster]

Independent phase2 runtime review

Reviewed bc26ccf, base 675c9e9 (ancestor verified), in a new detached checkout. Read all four changed files, the golden fixture/promotion requirements, complete paginated feedback, and the directly coupled approval, replay and cancellation implementations. This is a COMMENT, not approval or a merge/ready action.

Original findings

• 4521743483, exact action allowlist: addressed as requested. Unexpected-action mutation failed before approval; cleanup settled. This does not assert that a summary validates omitted Bash execution options.
• 4521767729, replay/cursor: addressed. Complete saved records/unique IDs and exact empty/nonempty suffixes are checked. Independent mutations that ignored the cursor or reidentified the prefix were rejected.
• 4521767767, executing-command cancellation: partially addressed; still open. See verified short-timeout false positive. All 23 current golden assertions pass despite an abort-ignoring transport when the exact command has a 1-second Bash timeout. This is the remaining existing-thread gap, not a duplicate new finding.
• 4521767800, finally cleanup: addressed for the reported preapproval failure path. Actual callback failures on unexpected action and replay mutations cancelled/settled the real harness before directory removal; activeTurns was zero. This does not claim forced cleanup of a permanently unresponsive external SDK.

No unrelated runtime redesign or later-Claude-feature requirement identified. Threads left unresolved; no original reviewer acceptance impersonated. The spec/matrix now correctly qualify the historical smoke and leave strengthened live promotion evidence pending.

Independent validation

• SKIP_BUILD_BUMP=1 npm run build — passed.
• npm run lint — passed (both package typechecks).
• node scripts/render-host-feature-matrix.mjs --check and git diff --check — passed.
• node ../pr-2452-review-repro.mjs (from review checkout) — baseline passed; action/cursor/reidentification negatives rejected with cleanup verified; short-timeout cancellation mutation exposed the false positive. Actual callback/assertions with a scripted transport and local foreground child; not Vitest or live model evidence.
• SQUAD_REAL_CLI_TESTS=0 npm test -- --run test/claude-agent-sdk-harness.test.ts test/harness-contract.test.ts test/test-reconciliation.test.ts test/squad-20-host-feature-matrix.test.ts — blocked at startup: missing locked vite; no Vitest assertions ran. Reused an isolated copy of matching repair dependencies; no installs/version substitutions.

Latest hosted snapshot: docs-quality, samples-build, Policy Gates, sdk-exports-validation, gh-aw compilation and upgrade matrices passed; main test job still running, no current failure observed. Local full tests/ESLint/docs lint are not claimed passed. No credential reads or paid calls, source edits, commits, pushes, PR-body edits or thread resolutions. Remaining promotion blockers: the cancellation-proof gap, completed required hosted checks, and an authorized strengthened direct-API/Bedrock/Vertex live run.