Task 3 — Diagnostic contract remediation report

Date: 2026-08-04

Scope

This remediation is limited to the four approved review findings for the workspace diagnostic extension. It does not add registry routes, change workspace publication, alter session startup, or expand transport support.

Changes

RuntimeBindings now has an explicit vectorWriter binding. The new resolveRuntimeBindings() resolves DWH, vector reader, vector writer, and embedding bindings together. The diagnoser takes the writer credential only from bindings.vectorWriter, never from vector-reader values.
Direct PostgreSQL and SSH-tunnelled direct probes accept an absent CA binding while retaining certificate verification through the runtime system trust store. A supplied CA still uses verified private-CA trust. REST private-CA refusal is unchanged.
A reversible vector probe now requires an authenticated POST declaration with a response map containing operation. The adapter requires the successful JSON response to echo create or remove respectively, so an arbitrary 2xx or an upsert-only response cannot activate the write probe.
For DWH and vector REST diagnostics declared with auth: none, the resolver no longer requires an API-key file and the adapter sends no credential. Credential-backed diagnostics continue to require their local secret file.

TDD evidence

The first focused RED run failed for the intended missing behavior:

resolveRuntimeBindings is not a function for unauthenticated resolver bindings;
schema accepted a reversible probe without a response contract; and
existing diagnostic fixtures rejected the new response declaration until schema support was implemented.

The focused GREEN run passed 43/43 tests across:

test/workspaces-bindings.test.ts
test/workspaces-schema.test.ts
test/workspaces-diagnostics.test.ts

The regression coverage includes resolver-to-diagnoser writer propagation without manually inserting the writer key into vector-reader bindings, no-CA direct/SSH system-trust requests, operation-echo validation for create/remove, and auth: none bindings without secret files.

Documentation and design

docs/workspace-diagnostic-protocol.md now documents the verified system-trust fallback, no-secret auth: none behavior, and required reversible response contract.
docs/superpowers/specs/2026-08-03-git-workspace-registry-design.md now records the same response, CA, SSH, and authentication rules.

Final verification

The initial sandboxed full suite could not bind its local SSE listener (listen EPERM: operation not permitted 127.0.0.1). It was rerun unchanged with local-listener permission.

backend: npx vitest run
31 test files passed; 329 tests passed

backend: npx tsc --noEmit -p .
exit 0

repository: git diff --check
exit 0

Expected test harness stderr from existing Pi/process failure-path tests remained present; no test failed and no diagnostic secret was emitted.

Blockers

None.

Round 2 remediation

The final review found two remaining contract gaps. The binding resolver already treated auth: none as credential-free, but the runtime renderer and diagnostic connector still required the API-key file. Rendering and connector construction now make that requirement conditional on the declared REST authentication mode, so a DWH/vector auth: none workspace passes resolver, runtime rendering, and diagnostics with no API-key file.

SSH forwarding previously changed the PostgreSQL connection host to 127.0.0.1 without retaining the original target for TLS hostname validation. Forwarded probes now carry SSH_TARGET_HOST as tlsServername into the PostgreSQL TLS options; private CA and verified system trust behavior are unchanged.

TDD RED: the new end-to-end no-key test failed at the unconditional runtime API_KEY_FILE requirement, while the SSH test showed no tlsServername on the loopback probe or database-client request. TDD GREEN: the focused backend workspace tests passed 40/40.

Round 2 final verification:

backend: npx vitest run
31 test files passed; 332 tests passed

backend: npx tsc --noEmit -p .
exit 0

repository: git diff --check
exit 0

4.2 KiB Raw Blame History