@staix/agent-hub 0.20.0 → 0.21.0

package/docs/verification/2026-10-28-claude-2.1.311-2.1.312-permission-transport.json

@@ -0,0 +1,403 @@
+{
+  "date": "2026-10-28",
+  "producer": "claude-permission-transport-native.py",
+  "sourceHead": "f7450129",
+  "account": false,
+  "inference": false,
+  "fixtureMcp": true,
+  "productionDaemon": false,
+  "hostWrapperRewriting": false,
+  "certified": true,
+  "cases": [
+    {
+      "version": "2.1.311",
+      "binarySha256": "85d8c08707fcfd1e78ffa0204eefbc6ec9e4fe22f375fb2767ef85d957ed3161",
+      "case": "allow",
+      "nativeExit": 0,
+      "stoppedExternally": false,
+      "mcpCalls": 1,
+      "fileWritten": true,
+      "toolResultErrors": [
+        null
+      ],
+      "resultFrame": [
+        {
+          "is_error": false,
+          "denials": 0
+        }
+      ],
+      "elapsedSeconds": 0.309,
+      "requests": 2,
+      "passed": true,
+      "nativeGroupEmpty": true,
+      "binaryUnchanged": true
+    },
+    {
+      "version": "2.1.311",
+      "binarySha256": "85d8c08707fcfd1e78ffa0204eefbc6ec9e4fe22f375fb2767ef85d957ed3161",
+      "case": "deny",
+      "nativeExit": 0,
+      "stoppedExternally": false,
+      "mcpCalls": 1,
+      "fileWritten": false,
+      "toolResultErrors": [
+        true
+      ],
+      "resultFrame": [
+        {
+          "is_error": false,
+          "denials": 1
+        }
+      ],
+      "elapsedSeconds": 0.315,
+      "requests": 2,
+      "passed": true,
+      "nativeGroupEmpty": true,
+      "binaryUnchanged": true
+    },
+    {
+      "version": "2.1.311",
+      "binarySha256": "85d8c08707fcfd1e78ffa0204eefbc6ec9e4fe22f375fb2767ef85d957ed3161",
+      "case": "missing-tool",
+      "nativeExit": 1,
+      "stoppedExternally": false,
+      "mcpCalls": 0,
+      "fileWritten": false,
+      "toolResultErrors": [
+        true
+      ],
+      "resultFrame": [],
+      "elapsedSeconds": 0.311,
+      "requests": 1,
+      "passed": true,
+      "nativeGroupEmpty": true,
+      "binaryUnchanged": true
+    },
+    {
+      "version": "2.1.311",
+      "binarySha256": "85d8c08707fcfd1e78ffa0204eefbc6ec9e4fe22f375fb2767ef85d957ed3161",
+      "case": "hook-deny",
+      "nativeExit": 0,
+      "stoppedExternally": false,
+      "mcpCalls": 1,
+      "fileWritten": false,
+      "toolResultErrors": [
+        true
+      ],
+      "resultFrame": [
+        {
+          "is_error": false,
+          "denials": 1
+        }
+      ],
+      "elapsedSeconds": 0.315,
+      "requests": 2,
+      "passed": true,
+      "nativeGroupEmpty": true,
+      "binaryUnchanged": true
+    },
+    {
+      "version": "2.1.311",
+      "binarySha256": "85d8c08707fcfd1e78ffa0204eefbc6ec9e4fe22f375fb2767ef85d957ed3161",
+      "case": "hook-allow",
+      "nativeExit": 0,
+      "stoppedExternally": false,
+      "mcpCalls": 1,
+      "fileWritten": true,
+      "toolResultErrors": [
+        null
+      ],
+      "resultFrame": [
+        {
+          "is_error": false,
+          "denials": 0
+        }
+      ],
+      "elapsedSeconds": 0.312,
+      "requests": 2,
+      "passed": true,
+      "nativeGroupEmpty": true,
+      "binaryUnchanged": true
+    },
+    {
+      "version": "2.1.311",
+      "binarySha256": "85d8c08707fcfd1e78ffa0204eefbc6ec9e4fe22f375fb2767ef85d957ed3161",
+      "case": "mcp-error",
+      "nativeExit": 0,
+      "stoppedExternally": false,
+      "mcpCalls": 1,
+      "fileWritten": false,
+      "toolResultErrors": [
+        true
+      ],
+      "resultFrame": [
+        {
+          "is_error": false,
+          "denials": 0
+        }
+      ],
+      "elapsedSeconds": 0.31,
+      "requests": 2,
+      "passed": true,
+      "nativeGroupEmpty": true,
+      "binaryUnchanged": true
+    },
+    {
+      "version": "2.1.311",
+      "binarySha256": "85d8c08707fcfd1e78ffa0204eefbc6ec9e4fe22f375fb2767ef85d957ed3161",
+      "case": "disconnect",
+      "nativeExit": 0,
+      "stoppedExternally": false,
+      "mcpCalls": 1,
+      "fileWritten": false,
+      "toolResultErrors": [
+        true
+      ],
+      "resultFrame": [
+        {
+          "is_error": false,
+          "denials": 0
+        }
+      ],
+      "elapsedSeconds": 0.246,
+      "requests": 2,
+      "passed": true,
+      "nativeGroupEmpty": true,
+      "binaryUnchanged": true
+    },
+    {
+      "version": "2.1.311",
+      "binarySha256": "85d8c08707fcfd1e78ffa0204eefbc6ec9e4fe22f375fb2767ef85d957ed3161",
+      "case": "pending",
+      "nativeExit": null,
+      "stoppedExternally": true,
+      "mcpCalls": 1,
+      "fileWritten": false,
+      "toolResultErrors": [],
+      "resultFrame": [],
+      "elapsedSeconds": 25.016,
+      "requests": 1,
+      "passed": true,
+      "nativeGroupEmpty": true,
+      "binaryUnchanged": true
+    },
+    {
+      "version": "2.1.311",
+      "binarySha256": "85d8c08707fcfd1e78ffa0204eefbc6ec9e4fe22f375fb2767ef85d957ed3161",
+      "case": "deadline",
+      "nativeExit": 0,
+      "stoppedExternally": false,
+      "mcpCalls": 1,
+      "fileWritten": false,
+      "toolResultErrors": [
+        true
+      ],
+      "resultFrame": [
+        {
+          "is_error": false,
+          "denials": 1
+        }
+      ],
+      "elapsedSeconds": 0.422,
+      "requests": 2,
+      "passed": true,
+      "nativeGroupEmpty": true,
+      "binaryUnchanged": true
+    },
+    {
+      "version": "2.1.312",
+      "binarySha256": "6b5ec691195e551b02c41df9f7d723f4ea61eaa03c2df90acefe3736f1aeb620",
+      "case": "allow",
+      "nativeExit": 0,
+      "stoppedExternally": false,
+      "mcpCalls": 1,
+      "fileWritten": true,
+      "toolResultErrors": [
+        null
+      ],
+      "resultFrame": [
+        {
+          "is_error": false,
+          "denials": 0
+        }
+      ],
+      "elapsedSeconds": 0.315,
+      "requests": 2,
+      "passed": true,
+      "nativeGroupEmpty": true,
+      "binaryUnchanged": true
+    },
+    {
+      "version": "2.1.312",
+      "binarySha256": "6b5ec691195e551b02c41df9f7d723f4ea61eaa03c2df90acefe3736f1aeb620",
+      "case": "deny",
+      "nativeExit": 0,
+      "stoppedExternally": false,
+      "mcpCalls": 1,
+      "fileWritten": false,
+      "toolResultErrors": [
+        true
+      ],
+      "resultFrame": [
+        {
+          "is_error": false,
+          "denials": 1
+        }
+      ],
+      "elapsedSeconds": 0.308,
+      "requests": 2,
+      "passed": true,
+      "nativeGroupEmpty": true,
+      "binaryUnchanged": true
+    },
+    {
+      "version": "2.1.312",
+      "binarySha256": "6b5ec691195e551b02c41df9f7d723f4ea61eaa03c2df90acefe3736f1aeb620",
+      "case": "missing-tool",
+      "nativeExit": 1,
+      "stoppedExternally": false,
+      "mcpCalls": 0,
+      "fileWritten": false,
+      "toolResultErrors": [
+        true
+      ],
+      "resultFrame": [],
+      "elapsedSeconds": 0.318,
+      "requests": 1,
+      "passed": true,
+      "nativeGroupEmpty": true,
+      "binaryUnchanged": true
+    },
+    {
+      "version": "2.1.312",
+      "binarySha256": "6b5ec691195e551b02c41df9f7d723f4ea61eaa03c2df90acefe3736f1aeb620",
+      "case": "hook-deny",
+      "nativeExit": 0,
+      "stoppedExternally": false,
+      "mcpCalls": 1,
+      "fileWritten": false,
+      "toolResultErrors": [
+        true
+      ],
+      "resultFrame": [
+        {
+          "is_error": false,
+          "denials": 1
+        }
+      ],
+      "elapsedSeconds": 0.306,
+      "requests": 2,
+      "passed": true,
+      "nativeGroupEmpty": true,
+      "binaryUnchanged": true
+    },
+    {
+      "version": "2.1.312",
+      "binarySha256": "6b5ec691195e551b02c41df9f7d723f4ea61eaa03c2df90acefe3736f1aeb620",
+      "case": "hook-allow",
+      "nativeExit": 0,
+      "stoppedExternally": false,
+      "mcpCalls": 1,
+      "fileWritten": true,
+      "toolResultErrors": [
+        null
+      ],
+      "resultFrame": [
+        {
+          "is_error": false,
+          "denials": 0
+        }
+      ],
+      "elapsedSeconds": 0.304,
+      "requests": 2,
+      "passed": true,
+      "nativeGroupEmpty": true,
+      "binaryUnchanged": true
+    },
+    {
+      "version": "2.1.312",
+      "binarySha256": "6b5ec691195e551b02c41df9f7d723f4ea61eaa03c2df90acefe3736f1aeb620",
+      "case": "mcp-error",
+      "nativeExit": 0,
+      "stoppedExternally": false,
+      "mcpCalls": 1,
+      "fileWritten": false,
+      "toolResultErrors": [
+        true
+      ],
+      "resultFrame": [
+        {
+          "is_error": false,
+          "denials": 0
+        }
+      ],
+      "elapsedSeconds": 0.317,
+      "requests": 2,
+      "passed": true,
+      "nativeGroupEmpty": true,
+      "binaryUnchanged": true
+    },
+    {
+      "version": "2.1.312",
+      "binarySha256": "6b5ec691195e551b02c41df9f7d723f4ea61eaa03c2df90acefe3736f1aeb620",
+      "case": "disconnect",
+      "nativeExit": 0,
+      "stoppedExternally": false,
+      "mcpCalls": 1,
+      "fileWritten": false,
+      "toolResultErrors": [
+        true
+      ],
+      "resultFrame": [
+        {
+          "is_error": false,
+          "denials": 0
+        }
+      ],
+      "elapsedSeconds": 0.247,
+      "requests": 2,
+      "passed": true,
+      "nativeGroupEmpty": true,
+      "binaryUnchanged": true
+    },
+    {
+      "version": "2.1.312",
+      "binarySha256": "6b5ec691195e551b02c41df9f7d723f4ea61eaa03c2df90acefe3736f1aeb620",
+      "case": "pending",
+      "nativeExit": null,
+      "stoppedExternally": true,
+      "mcpCalls": 1,
+      "fileWritten": false,
+      "toolResultErrors": [],
+      "resultFrame": [],
+      "elapsedSeconds": 25.011,
+      "requests": 1,
+      "passed": true,
+      "nativeGroupEmpty": true,
+      "binaryUnchanged": true
+    },
+    {
+      "version": "2.1.312",
+      "binarySha256": "6b5ec691195e551b02c41df9f7d723f4ea61eaa03c2df90acefe3736f1aeb620",
+      "case": "deadline",
+      "nativeExit": 0,
+      "stoppedExternally": false,
+      "mcpCalls": 1,
+      "fileWritten": false,
+      "toolResultErrors": [
+        true
+      ],
+      "resultFrame": [
+        {
+          "is_error": false,
+          "denials": 1
+        }
+      ],
+      "elapsedSeconds": 0.417,
+      "requests": 2,
+      "passed": true,
+      "nativeGroupEmpty": true,
+      "binaryUnchanged": true
+    }
+  ]
+}

package/docs/verification/2026-10-28-claude-implementer-permission-triage.md

@@ -0,0 +1,123 @@
+# Claude implementer permission triage
+
+Date: 2026-10-28. Scope: agent-hub task 544, source inspection, isolated fake fixtures and a model-free native transport comparison. Reported target: Claude Code 2.1.312, explicitly trusted but not receipt-verified, using `ask-when-needed`.
+
+The reported symptoms are a permission-tool harness error before `bun test test/ci-watch.test.ts` executes, and approval-waiting notices when the person's console appears empty, followed by expiry. This report does not treat those observations as a reproduced native defect. No production source, permission ceiling, COMPAT entry, installed native binary or account configuration changes in this triage.
+
+## Evidence status
+
+| Evidence | Status and limit |
+| --- | --- |
+| Version admission, wrapper and approval source paths | Read at the triage base `f7450129` |
+| Opt-in deterministic fake diagnostic cases | Corrected committed-head run at `9263ff67db8273a7f0b71c83d63a843ae5a628e0`: 15 pass, 0 fail, 116 assertions across the diagnostic and two related suites. Initial fixture-only assertion failures are corrected |
+| Installed native generic permission transport | 2.1.311 and 2.1.312 each 9/9 pass using the existing Python fixture MCP and loopback provider; no production-daemon or host-wrapper rewrite claim |
+| Native Bash transport and plain command replacement | Strict production-name/schema comparison: 18 transport cases and 4 allow/deny replacement cases passed across 2.1.311 and 2.1.312; no production-daemon or host-wrapper execution claim |
+| Native production-daemon task/host-wrapper rewrite at 2.1.312 | Unverified |
+| Person's reported incident and console connection identity | Not independently reproduced |
+| Real provider, model, credentials or account interaction | Not run |
+| Exact-head gate and hosted CI | Recorded separately by the implementer after verification |
+
+## Source-backed conclusions
+
+There is no verified-only host-wrapper gate. `assessVersion` in `src/adapters/compat.ts` admits the person's exact machine trust as `ok: true, state: "trusted"`. `proveClaudeImplementer` in `src/adapters/claude-implementer.ts` checks that admission and the binary fingerprint; it does not require the verdict's state to be `verified`. The adapter's native argv retains `default`, the strict MCP inventory and the permission prompt tool for both admitted states.
+
+`automaticImplementerShell` in `src/hub/daemon.ts` has no independent native-version predicate. Its gates are current child/generation, isolated execution root, an owned public task, `ask-when-needed`, closed command/input shape, current branch/default-branch evidence, public metadata, action-policy checks and the required host confinement. `taskShellCommand` recognizes `bun test test/ci-watch.test.ts` lexically. Recognition alone grants nothing. Executable test/build/check requests require `sandboxAvailable()`; an unsupported host follows the ordinary person approval path. This is expected behavior, not evidence that the trusted version was silently disabled.
+
+A failure can occur before any console approval exists. The production MCP handler in `src/adapters/claude-channel.ts` requires `tool_name`, an object `input` and a nonempty `tool_use_id`; invalid arguments return a fixed denial before requesting the daemon. The daemon also refuses an unavailable or stale owned-child/root binding before entering `requestPermission`. The 2.1.309/2.1.310 receipts prove their observed native schema and rewrite behavior, not 2.1.312's behavior. The generic native transport probe below observes the expected request schema, but a production-daemon or host-wrapper incompatibility in the reported incident remains unverified.
+
+Approval transport uses one shared daemon map. `requestPermission` registers the row before `writeStatus` and the `permission` push, and a fresh console's `tail` request replays all still-pending pushes. The console-role `status` RPC exposes body-free approval ids/times through `status.attentionItems`; the console-role `ui_snapshot` RPC exposes the full pending rows as `permissions`, projected from the same map. The internal attention input has an `approvals` array, but that is not a field of the ordinary status RPC. Expiry removes the row before emitting closure and resolving the native request as a denial.
+
+The console keeps actionable approval rows from `permission` and `permission_closed` pushes. Status attention metadata does not contain the full title/options needed to reconstruct those rows. A deliberately omitted push therefore leaves the controlled fixture's approval panel empty until a valid push is supplied. This is a push-omission characteristic, not a reproduced product defect or the established cause of the reported incident. Source ordering shows `runConsole` installs `client.onPush` before sending `tail`, and the daemon replays still-pending rows on that subscription; no normal console-startup race was found. An expired/cancelled request, another project/instance connection, pre-queue native failure or an actual missing push must be distinguished using the same request id and daemon instance.
+
+`OwnedPrintChild` ignores native stderr, and `ClaudeImplementerPeer` reduces an unsuccessful native result to the fixed `Claude implementer turn failed` outcome. Consequently the generic delivery failure alone does not establish which native permission-harness stage failed. Do not infer a host wrapper refusal, a missing person answer or a native compatibility defect from that generic outcome.
+
+## Isolated fake fixture
+
+The opt-in diagnostic producer uses a fresh HOME, CLAUDE_CONFIG_DIR, AGENTHUB_HOME and AMEM_HOME; a disposable Git repository and separate non-default-branch worktree; an outside-project Git shim with system/global config disabled; a fake native executable answering only its synthetic version and recording argv/launch metadata; and actual daemon, control-client, MCP channel and console code. Memory, inference, MLX and automatic Pi startup are disabled. A fixed host default-branch test port prevents a GitHub query. No installed Claude binary, personal authentication file or provider is selected, and an issued wrapper ticket is never redeemed.
+
+The fake reports 2.1.312 while that version is unverified. If a later dated receipt verifies it, the fixture uses a synthetic unverified version to retain its admission-policy test without blocking legitimate COMPAT updates. This is not a native compatibility assertion.
+
+| Case | Required observation |
+| --- | --- |
+| Trusted, unverified fake version | Startup admitted with native `default` and the fixed prompt-tool argv; no bypass mode |
+| Closed test command | On a sandbox-capable host, host protocol 1 rewrites the command; without the host sandbox, ordinary approval expires as deny, with no rewrite |
+| Real daemon manual approval | Same request id appears in the live console push, `ui_snapshot.permissions`, status attention metadata and a fresh console's tail replay, then is withdrawn on its fixture deadline |
+| Missing `tool_use_id` | Actual production source MCP handler returns `invalid native permission request`, with no approval row or permission push |
+| Deliberately withheld console push | Real-shaped fake `status.attentionItems` alone supplies no actionable approval row; a later valid push makes the request visible |
+
+The console case deliberately omits a permission push. It lives outside the automatic regression suite and is not evidence of a normal transport or startup failure. It adds no production repair or broader authorization. The host command case tests policy using a fake native. Neither certifies the installed 2.1.312 permission dispatcher, real model tool selection or a person's live approval interaction.
+
+## Installed native transport comparison
+
+The original Write mode of `claude-permission-transport-native.py` ran sequentially on the
+installed 2.1.311 control and 2.1.312 target with fresh private homes and a synthetic
+loopback provider. Each passed all 9 allow/deny/hook/MCP-error/disconnect/pending/
+deadline cases. All 18 owned native groups were established empty and all binary
+hashes were unchanged. No account or inference call occurred. The sanitized
+[transport receipt](2026-10-28-claude-2.1.311-2.1.312-permission-transport.json)
+contains counts, fixed outcomes and binary hashes only.
+
+| Version | SHA-256 | Cases |
+| --- | --- | --- |
+| 2.1.311 | `85d8c08707fcfd1e78ffa0204eefbc6ec9e4fe22f375fb2767ef85d957ed3161` | 9/9 |
+| 2.1.312 | `6b5ec691195e551b02c41df9f7d723f4ea61eaa03c2df90acefe3736f1aeb620` | 9/9 |
+
+Host admission observed memory-pressure level 1, zero swap, thermal state 0 and
+76.4% CPU idle on 18 logical CPUs; no other local build/test job was running.
+Each native case retained the producer's 25-second bound and owned-group cleanup.
+This reproduced normal permission behavior, not the reported harness error. The
+fixture MCP is deliberately separate from the production SDK channel and daemon
+policy. No COMPAT value is changed and no new host-wrapper receipt is claimed.
+
+## Native Bash transport and rewrite comparison
+
+The producer now accepts optional `--tool Write|Bash`, `--rewrite-bash`, `--server-name`, `--permission-tool` and `--require-tool-use-id` flags. The default remains the original nine-case Write table, original request/response checks, permission mode, isolated environment, 25-second external deadline, owned-group cleanup and binary fence. The optional modes ran sequentially at committed producer head `243d4b535404d911ea2b1c728352d4abd82e5ea6`. Strict Bash transport passed all 18 cases, and exact-command replacement passed all 4 allow/deny cases across the two binaries.
+
+| Mode | Cases per supplied binary | Observed behavior |
+| --- | --- | --- |
+| Default or `--tool Write` | 9 | Original Write allow/deny/hook/MCP-error/disconnect/pending/deadline behavior |
+| `--tool Bash` | 9 | Same case table using an explicitly asked Bash command that only prints `probe` into the fixture target |
+| `--tool Bash --rewrite-bash` | 2 | Allow and deny only; original native command is exactly `bun test test/ci-watch.test.ts` |
+
+The server/tool names default to `fixture`/`approve` and accept only bounded ASCII letters, digits, underscores and hyphens with an initial letter. `--server-name agent-hub --permission-tool hub_permission_request` selects the exact production namespace `mcp__agent-hub__hub_permission_request`. The strict-schema flag adds required `tool_use_id`, the production name/id length bounds and `additionalProperties: false`; the default keeps the original two-field requirement. Bash settings ask for Bash with no newly granted `permission.allow` entry, matching the earlier wrapper fixture. These flags select a production-name/schema comparison; the fixture remains separate from the production MCP implementation.
+
+In rewrite mode a private executable named `bun` is prepended to the native fixture PATH. A dummy `test/ci-watch.test.ts` exists under the disposable work directory for command-shape fidelity. If the original command runs, the shim records an execution marker and fails. Only the allow MCP server receives the replacement command, a harmless `printf` writer to the fixture target. The returned `updatedInput` is retained and checked exactly, the original `tool_name`, input and `tool_use_id` remain required, the original-execution marker must stay absent in both cases, and the target may contain `probe` only for allow. The final cleanup rechecks the original-execution marker. No repository test command or real Bun test is intended to run, and this probe imports neither `HostShellWrapper` nor the current daemon.
+
+This isolates native Bash argument replacement from the host's command-admission and sandbox policy. The successful run establishes only that specific fixture exchange on the supplied binaries, not production SDK/daemon behavior, a new trusted/verified version, real account behavior or a complete host-wrapper receipt. The original fake Bun execution marker remained absent in all four rewrite cases; the replacement wrote the fixture target only for allow. All 22 owned native groups were empty and binary hashes unchanged. The model-free comparison did not reproduce the reported harness failure.
+
+The sanitized [Bash transport receipt](2026-10-28-claude-2.1.311-2.1.312-bash-permission.json) contains fixed outcomes, counts, timings, producer hash and native binary hashes, with no command text, prompt, token, session id or path. Native admission at the start observed memory pressure 1, zero swap, thermal state 0, CPU idle 73.29%, load 5.88 on 18 logical CPUs, and no other local repository test/build job. The single worker ran sequentially, then released the slot.
+
+## Commands for the implementer
+
+Explicit fake diagnostic command, after committing the intended files and taking the permitted remote slot. The first remote run accepted this explicit regular `.ts` path; the corrected diagnostic passed the committed-head rerun above:
+
+```sh
+env -u AGENTHUB_HOME bun test ./docs/verification/claude-implementer-permission-triage.ts
+```
+
+Native Bash reproduction commands, after host-resource admission and review of the explicit installed paths, using two different new private output directories:
+
+```sh
+python3 docs/verification/claude-permission-transport-native.py "$BASH_TRANSPORT_OUTPUT" --tool Bash --server-name agent-hub --permission-tool hub_permission_request --require-tool-use-id --claude "$CLAUDE_CONTROL_BINARY" --claude "$CLAUDE_2312_BINARY"
+python3 docs/verification/claude-permission-transport-native.py "$BASH_REWRITE_OUTPUT" --tool Bash --rewrite-bash --server-name agent-hub --permission-tool hub_permission_request --require-tool-use-id --claude "$CLAUDE_CONTROL_BINARY" --claude "$CLAUDE_2312_BINARY"
+```
+
+The required repository gate remains `scripts/check.sh --changed` at that committed head. Any macOS host-wrapper positive branch must be reported separately from the Linux branch that deliberately asks without `sandbox-exec`.
+
+The existing [host-wrapper receipt](2026-10-26-headless-claude-shell-context.md) names 2.1.309 and 2.1.310, not 2.1.311. Its unchanged `claude-shell-wrapper-native.py` explicitly accepts only those two versions, so it cannot be invoked with 2.1.312 as a valid reproduction command. The task description's reference to a 2.1.311 wrapper receipt is not supported by that checked-in document. No newer wrapper receipt was found in `docs/verification/` at this base.
+
+Before proposing any verified-version bump, adapt and review that wrapper producer for the new binaries, then repeat both the wrapper and [generic transport](2026-10-23-headless-claude-permissions.md) procedures. The wrapper procedure must retain strict MCP, empty settings sources, synthetic loopback provider, isolated homes, the external deadline, exact original request/rewritten reply checks, replay effect count, owned cleanup and binary fences. It imports current production code and requires the pinned local dependencies. This triage does not run it with the Mac's stale ancestor dependency installation and does not claim a new wrapper receipt.
+
+## Remaining unknowns
+
+- The exact 2.1.312 native permission request, schema validation result, MCP reply and native tool-result error from the reported incident.
+- Whether the failing command reached `permission_request` and the wrapper proof, reached the manual queue, or failed before either.
+- Whether the reportedly empty console was attached to the same daemon instance and request id while the row was still pending.
+- Whether a controlled missed-push case occurs in normal use, beyond the deterministic console fixture.
+- Production-daemon/native host-wrapper behavior on 2.1.312 and a real person's account-backed approval leg. Generic Write and strict-schema Bash transport, including exact-command replacement, passed the isolated comparison above.
+
+## Disposition
+
+No production defect was reproduced, so this triage makes no source repair or permission relaxation. The trusted-versus-verified hypothesis is contradicted by the source and isolated admission fixture. The generic native-schema/replacement hypothesis did not reproduce in the 2.1.311/2.1.312 comparison. Ordinary daemon approval registration, inventory, push, late subscription and expiry passed the fake task fixture. The deliberately omitted-push case demonstrates a UI information boundary, not an observed normal-use defect.
+
+The incident remains unresolved without its original native tool-result error and the matching daemon instance/request id. The exact sanitized error and timing were requested from the reporting implementer. A subsequent incident should correlate whether a permission row was created, the live console's project/instance, and whether its tail received that same row before expiry. No additional prompt/body logging is proposed here. Existing native stderr suppression and fixed failure outcomes limit retrospective attribution.

package/docs/verification/2026-10-28-jcode-0.99.1-usage.md

@@ -0,0 +1,41 @@
+# Jcode 0.99.1 usage and context receipt (#801)
+
+Date: 2026-10-28. Refs #801. Installed release build, read through `--quiet version --json`: `semver` 0.99.1, `version` `v0.99.1 (7206efd0c)`. Host macOS arm64, Bun 1. The receipt records event shapes and counters only: no prompt, no model output beyond the fixed word the fake replied with, no credential, no account identifier.
+
+## What was run
+
+An isolated `HOME` and `JCODE_HOME` (fresh directories under the scratch area, an empty `mcp.json`, no credentials, no account), `JCODE_NO_TELEMETRY=1` and `JCODE_DISABLE_CLAUDE_MCP=1` as the adapter sets them. One `openai-compatible` profile `fakegw` (added with `jcode provider add ... --no-api-key`, written only into the isolated `config.toml`) pointed at a local server on `127.0.0.1` that streamed a fixed reply and a final `usage` chunk whose numbers the probe chose, so each number Jcode reported could be compared with the number sent. No real provider, key or model was involved.
+
+`jcode serve` and `jcode acp` were started with the argv `jcodeCommand` builds (`--socket`, `--cwd`, `--no-update`, `--no-selfdev`, `--model`, `--provider-profile`, `--temporary-server`, `--mcp-tools eager`), a session was created, and three prompts were sent. Before the run the SHA-256 of the four real config files directly in `~/.jcode` (`auth.json`, `auth-refresh-state.json`, `config.toml`, `mcp.json`) was taken and compared after the last leg: unchanged. No process whose command line named the sandbox was left running.
+
+## Shapes observed on the ACP stream
+
+Per prompt, in this order: `available_commands_update` (first prompt only), `agent_message_chunk`, one `usage_update` per provider call, then the `session/prompt` result.
+
+- **`usage_update`**: `{ sessionUpdate: "usage_update", used: <integer>, size: <integer> }` inside `session/update` params that carry the ACP `sessionId`. Nothing else. In Jcode's own source (`src/cli/acp.rs`) it is written on each `TokenUsage` server event: `used` is `effective_context_tokens_from_usage` of that provider call (`crates/jcode-compaction-core/src/lib.rs`): the input count alone for OpenAI-named providers and when the cache is a subset of it, and the input plus the cache read and cache creation counts for Anthropic or Claude named providers and when the numbers show split accounting (a cache creation, or a cache read above the input). `size` is the model's context limit (200000 for the fake model, which falls to Jcode's default). The source was read on GitHub at the default branch; the installed 0.99.1 binary's behaviour was observed only for the input-only case the fake gateway produced. The sequence of one two-call turn (a tool call, then the answer) was `used` 1000 then 1100 for provider inputs 1000 and 1100: occupancy of the last call, not an accumulated sum.
+- **Prompt result**: `{ stopReason: "end_turn", usage: { inputTokens, outputTokens, cachedReadTokens, totalTokens } }`. `cachedWriteTokens` is in the source and absent when the provider reports no cache write. For the same two-call turn the result said `inputTokens` 2100 and `outputTokens` 40: the sum of the two calls (1000 + 1100, 10 + 30), so it is per turn, not a session total. A turn whose provider call reported no usage chunk had no `usage` member at all.
+- **`totalTokens` adds the cached read on top of the input**: sent input 1234, output 56, cached 100; Jcode reported `inputTokens` 1234, `outputTokens` 56, `cachedReadTokens` 100, `totalTokens` 1390 (input + output + cached). For OpenAI-style providers the input already contains the cached part, so that total counts it twice. The hub never reads `totalTokens` from Jcode.
+- **No other usage or context message** appeared: no ACP method other than `session/update`, and no `usage_update` carrying `totalTokens` or any ratio, window or reset.
+- **`jcode usage --json`** (the account usage command) under the same isolated home printed `{ "providers": [] }`: no provider connected, so no sample of a limit. From Jcode's source its schema is `providers: [{ provider_name, limits: [{ name, usage_percent, resets_at, reset_in }], extra_info: [[key, value]], banked_reset?, error }]`. `name` is free text and no window length is given.
+
+## What the hub does with it
+
+| Jcode record | Host projection | Why |
+| --- | --- | --- |
+| `usage_update` `{used, size}` | `ContextReading` source `jcode_usage_update`, bound to the adapter's own ACP session id, with the measurement time | live-session occupancy, the same kind as Kimi's and Codex's readings |
+| prompt result `usage` | one `usage` event per prompt, source `jcode_acp`: `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens` when present, task attribution, no `totalTokens` | per-turn consumption in the provider's own buckets |
+| `usage_update` | never a `tokens` event, a hub token window or a quota window | occupancy is not consumption |
+| prompt result `usage` | never a context reading, never a quota window | consumption is not occupancy and says nothing of a limit |
+
+A reading with a malformed field (`used` or `size` not a non-negative safe integer, `size` not positive), for another session than the daemon's current one, older than `context.stale_min`, or from a peer that is not attached, is unknown in `ahub status`, the console and the dashboard: never zero and never healthy. A result without both `inputTokens` and `outputTokens` as non-negative safe integers writes no usage record; a present but malformed cache bucket is dropped alone.
+
+## Not supported, and why
+
+- **Native quota windows.** Jcode declares no quota reader. `jcode usage --json` gives a free-text `name`, a percentage and a reset time but no window length, so mapping it to the hub's window ids would parse vendor prose, which #801 rules out. With no account it returned no provider at all, so there is no sample of a real limit either. `ahub budget` keeps `no reading` for Jcode, and the manual `ahub budget set` path is unchanged. Revisit when Jcode names the window length (and an account is available to record a real sample).
+- **Served-model evidence.** The ACP stream carries no served model in either record, so the usage event has none; the hub does not infer one from the requested model.
+- **Real account and provider.** Every number above came from a local fake gateway. A real provider's cache semantics (Anthropic reports cache apart from input, OpenAI includes it) are taken from Jcode's own documentation and source, not observed here, which is why the hub records the buckets and never a derived total.
+- **The TUI form.** `jcode --resume` runs the same ACP-owned session; the TUI's own context display was not read.
+
+## Decision
+
+The two measurements with structured evidence (occupancy, and per-turn token buckets) are supported on 0.99.1. Everything else stays unknown. `docs/verification/2026-10-26-jcode-0.99.1.md` remains the contract receipt a later version repeats; a later version repeats this receipt's probe too before its usage readings are claimed.