# 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

1. `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.
2. 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.
3. 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.
4. 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.

```text
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:

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

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

repository: git diff --check
exit 0
```