# Issue 17418 — proof audit pass 1, corrected-head delta

Issue: [#17418](https://git.cafe/pingdotgg/t3code/issues/17418). Immutable review scope: [e54e71d725](https://git.cafe/pingdotgg/t3code/commit/e54e71d725) → [03bd4fbf94](https://git.cafe/pingdotgg/t3code/commit/03bd4fbf94). Supersedes the earlier intermediate-head delta. This is a proposed evidence matrix, not executed verification. All rows are PENDING. No browser, server, tests, fixture changes, or repository edits were performed by this reviewer. Only committed objects were inspected for conclusions; concurrent working files were not treated as final.

Original matrix is retained verbatim below for traceability. The following corrections override conflicting original requirements:

- Command discovery now uses initialization commands; the original supportedCommands()/future commands_changed concern describes the earlier implementation, not this head. Verify the actual installed Claude/SDK initialization barrier with a controlled delayed session.start runtime transcript; do not carry the old race forward as a reproduced defect or declare it resolved from mocks alone.
- Hook execution is enabled only through WorkspaceScanRunsHooks, default false, supplied by the workspace RPC from the actual session's orchestration operate scope. Read-only inventory can succeed without hook commands.
- Hook-enabled failure/timeout settles with compact plus machine commands, workspace skills, and slashCommandsPending=false. Original V5/D3's universal pending=true and automatic cooldown retry expectation is superseded. Hook-free probe failure remains pending=true. Settled fallback means usable inventory, not proof that mod discovery succeeded.
- hooksSkipped is an optional wire field, replacing the intermediate WeakSet. Hook-free publications carry true; full publications omit it. hasCurrent returns false for true even within TTL; hasComplete remains true so usable commands do not trigger the pending retry loop. Read-only scans preserve an existing complete full inventory, including when stale or explicitly fresh.

## Sensible minimum capture plan

No visual code changed. Retain V1–V7 as explicit coverage/accountability rows, but replace the blanket V4 cross-product requirement: one real web configuration at normal desktop width/theme is the required integrated recording. Combine V1–V3, revised V5, and V8 where practical; use a narrow/dark settled still only if readily available, not four repeated interaction runs. V4 can be a labeled frame from that recording. V6 shares the web renderer; a separate shell run is optional regression coverage, never claim executed without evidence. V7 remains a separate mobile renderer/shared-runtime consumer: record one available native platform if authorized/available; explicitly mark each unrun OS/theme as unverified. Narrow web is not native proof. This reduction trades breadth for the changed server/shared-client integration, and does not convert any unrun original row into PASS.

Use labeled base/head segments for the original defect. Every interaction/time transition below requires a RECORDING, not stills. Server-only branches require timestamped runtime transcripts and focused deterministic tests where appropriate, not browser screenshots. A single combined transcript can cover multiple rows. No permission or launch is requested from this review; the separate evidence agent owns execution.

## Added delta rows (exact additions: D5–D11 and V8)

| ID | Changed branch / seeded state | Minimum required observable proof | Evidence |
|---|---|---|---|
| D5 | Actual RPC authorization → WorkspaceScanRunsHooks; read-only, operate, and absent/default service context | Same instance/cwd fixture: read-only RPC does not invoke SessionStart, including fresh=true; operate RPC discovers handoffs and increments hook count; default context also skips hooks. Record granted scope names (no tokens), RPC input, output commands, pending/provenance, hook count, and cleanup. Do not substitute client-disabled controls for server authorization. Health/instance refresh remains hook-free. | Server runtime transcript; focused authorization/default-context tests. No browser needed. |
| D6 | Published hook-free cache → operate reuse; full cache → read-only reuse | Read-only scan publishes hooksSkipped=true and complete built-ins; second read-only call reuses it. Operate non-fresh call within the same TTL rescans with hooks, publishes handoffs and clears/omits hooksSkipped. Subsequent calls from both scopes reuse full inventory. Serialize actual RPC/provider-stream payloads, counts, checkedAt and instance/cwd. | Server runtime transcript plus deterministic registry test. Client gate is separately V8. |
| D7 | In-flight claim precedence and late completion | Hold/release scans explicitly: read-only joins read-only; operate supersedes in-flight hook-free; read-only, including fresh=true, cannot replace in-flight full; non-fresh operate joins full; fresh operate can supersede full. Complete older scans after newer claims and confirm older results/finalizers cannot publish or clear newer ownership. Include replaced instance/cwd isolation as focused existing regression evidence, no provider cross-product. | Deferred/barrier-controlled focused tests plus runtime RPC/publication transcript for read-only→operate overlap and late hook-free completion. No sleeps in tests. |
| D8 | Existing complete full inventory, then read-only stale/fresh request | After full handoffs inventory, expire TTL; read-only normal and fresh=true calls preserve the selected instance/cwd's full commands and provenance without launching hook-free replacement. Operate refresh can still update it. Check other-instance invalidation separately if fresh=true touches shared inventory; do not infer that selected-inventory preservation means no other state changes. | Server runtime transcript with scan counts, clock/checkedAt, requests, and published inventory; focused test. |
| D9 | Hook-enabled timeout/error fallback vs hook-free failure | Controlled hook beyond probe deadline: abort/cleanup, one hook invocation, compact + machine commands (deduped) and cwd skills, pending=false, hooksSkipped omitted; repeated normal menu requests must not cause seconds-scale hook retry storm. Successful hook-free scan has hooksSkipped=true and pending=false; failing hook-free probe remains pending=true. Demonstrate explicit fresh retry or expiry permits operate recovery; fallback pending=false does not mean handoffs was found. | Runtime deadline/abort/count transcript; TestClock/barrier-focused tests. UI editability/recovery is revised V5, record once, not all themes. |
| D10 | Initialization barrier / health separation | Real installed Claude+SDK versions and effective instance environment/cwd; delayed session.start registers command before initialization resolves and head inventory includes it; health checks never run it and retain usage behavior. Record no prompted model call, no allowed tools, managed-MCP behavior from focused existing checks; verify query abort on success and timeout. SDK-mocked tests alone cannot establish actual initialization ordering. | Real controlled delayed-hook runtime transcript plus focused existing probe tests; no fake delayed commands_changed requirement. |
| D11 | Optional hooksSkipped wire compatibility and inventory scope | Decode/round-trip snapshots with field absent/true/false; absent retains legacy hasCurrent behavior; true makes current=false but complete=true; full publication removes true. Establish actual previous-client decoder tolerance of new field rather than assuming it. Older clients that ignore true can suppress an operate refresh until legacy TTL (five minutes), fresh action, or another updated client; document this limitation, do not claim compatibility fixes old client freshness. New client + old server sees absent and cannot infer missing provenance. Shared inventory intentionally lets read-only callers consume full commands previously discovered by an operator; no new hook execution or scope elevation follows from receiving names. | Focused contract/shared-runtime tests and payload transcript. Actual old-client decoding result or explicit UNVERIFIED; no invented backwards-compatibility guarantee. |
| V8 | Read-only publication → operator client freshness, same environment/instance/cwd, within five-minute TTL | Seed via read-only RPC; show hook-free complete snapshot reaches updated client. In operator session, open/type /hand normally: client issues workspace RPC despite recent checkedAt, server runs hooks, stream publishes full snapshot, menu gains handoffs, choose/insert/send marker. No manual fresh=true workaround and no five-minute wait. Keep built-ins usable meanwhile. Hold read-only client through publication/reopen to establish no request/retry storm; pair recording with RPC counts/provenance trace. Repeat native only if available, otherwise mark unverified shared-consumer integration. | Browser RECORDING plus correlated server/RPC transcript, one desktop web configuration minimum. Native recording is separate coverage. |

## Evidence acceptance and current status

Each executed row must link evidence and identify exact build SHA, runtime OS, Claude/SDK versions, environment, instance, cwd, scope class and fixture identity (redacted where necessary). Separate tests, runtime transcripts, and visual recordings; none substitutes for the others on a mixed row. Use synthetic fixture output, never tokens or real conversations. The central acceptance case is D5+D6+V8: correct scope at the RPC, provenance preserved on the wire, and updated client actually requesting richer inventory. Unit helper assertions alone do not prove that path.

Source inspection confirms the intended branches and added mocked tests, not successful execution. No runtime evidence or captures are attached by this reviewer. Original source-risk wording and expectations overridden above must not be quoted as findings on this head.

## FRICTION

- Read-only review only: no servers, browsers, tests or repository edits. All execution remains pending with the separately running evidence agent.
- Final immutable head inspected is 03bd4fbf94; earlier f8fe323dfa observations are superseded where corrected. No mutable files were used as final evidence.
- Runtime hook/SDK initialization ordering, real authorization, concurrency and old-client decode tolerance remain unverified until transcripts/tests are supplied.
- Optional wire field preserves decoding shape only if actual legacy decoders tolerate it; it cannot repair freshness decisions in already shipped clients.
- Timeout now intentionally settles fallback and suppresses immediate automatic retry; evidence must not present missing mod commands as successful mod discovery.
- V1–V7 remain visible in the retained original matrix. Reduced capture requirements above are deliberate; missing desktop/native/width/theme coverage must stay explicitly unverified.
- No PR was created or worked on. Artifact upload is the only external write; no credentials or user data are included.

---

# Original matrix (historical, verbatim; overrides above apply)

# Issue 17418 — read-only proof audit, pass 1

Issue: [#17418](https://git.cafe/pingdotgg/t3code/issues/17418)
Scope: [e54e71d725](https://git.cafe/pingdotgg/t3code/commit/e54e71d725) → [1fa8ee05f7](https://git.cafe/pingdotgg/t3code/commit/1fa8ee05f7), fix/issue-17418. Complete diff: ClaudeProvider.ts and ClaudeCapabilitiesProbe.test.ts only. No PR. This is a proposed evidence matrix, not completed verification. No captures, browsers, servers, tests, agents, or repo edits were performed in this pass.

## Verdict and priority

The matrix is NOT empty. Although implemented on the server, this changes visible provider slash-command discovery in the composer. Lead with the real app: Claude selected, project cwd containing the mod, `/hand` yields no `/handoffs` on base; typing and sending full `/handoffs` nevertheless yields HANDOFFS_FIXTURE_OK. On head the menu must discover it, selection must insert `/handoffs `, and sending must yield the same marker. Do not substitute a CLI transcript or mocked menu for this proof.

Timing concern to resolve before declaring proof complete: the installed SDK's supportedCommands() awaits initialization and returns latestCommands ?? init.commands; it does not wait for a future commands_changed event. The new mock updates commands in Promise.resolve().then(...) before the initialization continuation runs, so it does not exercise a genuinely delayed session.start registration. A delayed hook push can still race the immediate supportedCommands() read and final abort. This is a source-backed risk, not a reproduced failure. Need an event/deferred-controlled late-registration test and a real delayed-registration probe transcript; no sleeps in the test.

## Real-app route and fixture seeding

Reuse the lead's existing server/browser. Do not launch either or consume pairing credentials. Use the existing isolated `.t3` environment, never live ~/.t3/userdata. Open the lead's Claude thread through /<environmentId>/<threadId> (draft alternative /draft/<draftId>, new-thread entry /new). Select the Claude provider instance configured by the lead to load /home/ubuntu/wt/issue-17418/.t3/repro-mod. Verify the selected instance's actual resolved environment loads this mod; presence on disk alone is insufficient.

Existing fixture hooks/register.ts registers handoffs from session.start with description “Issue 17418 fixture command”; command.run returns HANDOFFS_FIXTURE_OK. hooks/hooks.json loads ./register.ts. No fixture edits are authorized for this review. Lead can seed additional controlled cases in its sandbox: delayed/erroring hook, mod-free cwd, second provider/cwd. Use distinct fresh workspace snapshots or the app's cwd-scoped provider refresh to avoid claiming cached discovery as fresh discovery. Record environment, provider instance, cwd, thread, Claude/SDK version and snapshot completion with evidence; redact credentials and real chat content.

## Minimum meaningful fixture matrix

V4 = web 1440 px light, 1440 px dark, 390 px light, 390 px dark (CSS viewport width; record height and scale). Every visible web row below gets V4 coverage. Combine rows in one continuous recording per configuration where possible; avoid separate redundant files. Before/after pairs use the same configuration and fixture. Static rows require stills only. Interaction/time rows require recordings, not isolated stills. Native mobile is not proven by 390 px web.

| ID | Affected path / seeded state | Required observable proof | Evidence | Width/theme/platform |
|---|---|---|---|---|
| V1 | Base/head existing Claude thread; fresh workspace snapshot; real repro mod | Base `/hand` lacks handoffs while full `/handoffs` executes marker. Head `/hand` offers handoffs and fixture description; keyboard selection inserts `/handoffs ` without premature execution; send returns marker. Clear/retype and dismiss/reopen menu. | RECORDING, labeled before/after | V4; run once with keyboard and once pointer/touch selection within these recordings |
| V2 | Same head thread, fresh/in-flight discovery → complete; repeat typing; completed warm cache; later stale snapshot refresh | Menu updates when workspace command data arrives; no duplicate handoffs, frozen composer, repeated hook storm or falsely successful completion. Warm typing reuses snapshot; refresh preserves working menu. Pair recording with hook invocation/probe transcript. | RECORDING (time/loading/cache transitions) | V4, can extend V1 |
| V3 | Head menu settled with nonmatching prefix, mid-message `text /hand`, then start-of-prompt `/hand`; mod-free cwd or second provider; return to fixture cwd/Claude | No phantom command for nonmatch, no provider command offered mid-message, no cross-cwd/provider leakage; returning restores handoffs. Built-in /compact and existing skill/file-command coexistence remain intact. | RECORDING (query/position/provider/cwd interactions) | V4, combine transitions; no need to repeat every other provider driver |
| V4 | Settled successful command menu | Readable `/handoffs` plus fixture description, selected row visible, no clipping/overflow in narrow or dark layout. | STILL only | V4; may extract labeled stills from V1 recordings |
| V5 | Workspace probe failure/timeout or failing hook → pending fallback → successful retry | Preserve built-ins/skills; do not mark incomplete discovery successful; no invented slash-specific error/loading UI. Retry after existing cooldown can discover handoffs; composer remains editable. Capture diagnostic transcript alongside UI. | RECORDING (error/recovery/time) | V4; lead must seed deterministic failure in sandbox |
| V6 | Electron desktop composer using same environment/provider/cwd | Discover `/hand`, choose and execute handoffs; focus and insertion work inside shell. Shares web renderer; reuse V1/V4 visual matrix for renderer rather than inventing an Electron-only layout change. | RECORDING | Desktop 1440 light/dark; web 390 covers responsive renderer, not native shell |
| V7 | Native iOS and Android composer connected to same isolated server, matching project cwd | Real workspace snapshot reaches separate mobile menu; `/hand` discovery, tap inserts `/handoffs `, send returns marker; provider/cwd switch does not leak commands. | RECORDING | Native ~390 logical width light/dark per OS; if unavailable explicitly report unverified, never claim web substitutes |

## Nonvisual companion checks (no screenshots)

| ID | Changed data branch / caller | Minimum proof |
|---|---|---|
| D1 | buildClaudeCapabilitiesProbeQueryOptions default/healthCheck=true, driver capabilities cache, periodic health refresh | Hooks remain disabled; init.commands used; usage still requested, including optional usage failure behavior; no SessionStart invocation on health ticks. Existing MCP empty map/strict managed-MCP exception, no allowed tools and no prompted model call remain intact. Focused test + runtime hook-count/probe transcript. |
| D2 | workspace healthCheck=false / ClaudeDriver.snapshotForCwd | Hooks enabled subject to actual user's effective settings; supportedCommands data parsed/deduped; no usage call; cwd and instance environment retained; abort/cleanup on success and timeout. Immediate and genuinely delayed mod registration; existing user/repo commands still present. Focused tests + real probe transcript. |
| D3 | probe error, timeout, disabled provider, no cwd | Error maps to compact fallback with slashCommandsPending=true; disabled snapshot returns unchanged; absent cwd uses machine list and must not falsely promise workspace mods. Existing retry policy unchanged. Focused tests, recording covered by V5. |
| D4 | parser/dedupe and skill collision | handoffs once; command name/description preserved; if same-name visible skill exists, existing skill suppression remains; hide-skills preference exposes provider command. Check existing focused helper tests; add a fixture only if collision is a realistic changed-data concern, not a new layout matrix. |

## Coverage derivation / exclusions

Changed builder now conditionally omits disableAllHooks for workspace calls; renamed includeUsage to healthCheck preserves the two existing callers' true/false roles; command source becomes init.commands for health, supportedCommands() for workspace; final parsed slashCommands changes. Driver snapshotForCwd → provider workspace snapshots → client-runtime cwd resolution → web ChatComposer/useComposerMenuItems/ComposerCommandMenu and mobile use-composer-command-menu are the visible consumers. Selection expands provider command text, then normal send executes it.

Empty/loading/error are existing menu or pending-snapshot states, not new UI branches: do not require a fictional slash-command spinner/error banner. Web command menu isLoading concerns existing path/PR searches; mobile has analogous path/PR loading. Width/theme branches belong to shared menu rendering, no CSS changed. Desktop wraps web; mobile has its own renderer and must be acknowledged separately. Local/remote/tunnel carry the same typed provider snapshot; one existing remote/native connection is enough transport evidence, no protocol diff warrants a full topology cross-product. Other providers, settings screens, global command palette, MCP tools and schedules have no changed rendering or command-discovery entry point here. Managed MCP and authentication/usage status are nonvisual regression checks, not new capture rows. OS-specific Claude binary/MCP detection paths are unchanged; report actual runtime OS/version and do not claim macOS issue reproduction from Linux alone.

## FRICTION

- No captures or test/runtime verification were authorized for this reviewer; all matrix rows remain pending lead execution.
- Lead reports a base real-app repro; this pass has not independently observed it. Existing server/browser were intentionally untouched.
- The existing mod fixture is present and its registration/marker were inspected, but provider attachment and actual selected thread/route were not read from the running app. Lead must confirm them.
- Source inspection exposes a late commands_changed race that the new microtask mock cannot disprove. Passing that test alone is insufficient proof.
- Deterministic failure/delay fixtures, Electron, iOS and Android availability are not established; missing coverage must be declared rather than silently collapsed into web.
- No PR exists, so there is no PR to link. This artifact contains only synthetic fixture details and source-derived requirements, no credentials or user data.