agents-can-communicate 0.4.1 → 0.4.2

package/README.md

@@ -73,8 +73,8 @@ Run `acc doctor` from the project if a peer is missing. A directory containing A
 state, commonly your home directory, cannot be used as a workspace; start the client in a
 project directory. See [Troubleshooting](docs/TROUBLESHOOTING.md).
 
-Already using ACC? Follow the [upgrade guide](docs/UPGRADING.md), including the 0.4.0 →
-0.4.1 update and the data-format boundary when moving from 0.3.1.
+Already using ACC? Follow the [upgrade guide](docs/UPGRADING.md), including the 0.4.0/0.4.1 →
+0.4.2 update and the data-format boundary when moving from 0.3.1.
 
 ## When messages arrive
 
@@ -95,9 +95,16 @@ mutations. It adds no automatic peer-message injection or idle delivery. A reloc
 **Optional live delivery can start a turn in an idle Codex or Claude Code session.** It is
 experimental, off by default, and can spend model tokens. On Apple Silicon Macs, Codex
 0.152.1 or newer requires an already-running LocalDaemon and a verified session;
-Claude Code 2.1.258 or newer requires zsh and shows its development-channel warning at
-startup. Messages arriving mid-turn wait for the turn to finish. The receiving session's
+Claude Code 2.1.258 or newer requires zsh and client-side Channels activation; check its
+startup notice for ACC and accept the development warning when shown. An MCP connection
+alone does not verify inbound delivery. Messages arriving mid-turn wait for the turn to
+finish. The receiving session's
 opt-in policy and current reachability determine whether delivery can proceed.
+`acc install` reports each client's delivery state and can save Codex consent before its
+service is available. `acc doctor` also names each session’s last native binding result,
+including missing launch consent, an unidentified client process or a failed handshake.
+It distinguishes a disabled policy from an unavailable service or a missing live channel
+in the current project.
 
 A Codex thread retained by LocalDaemon can receive opted-in messages after its terminal
 exits. Turning ACC delivery off prevents new native offers; already accepted queue entries

package/docs/ARCHITECTURE.md

@@ -68,7 +68,13 @@ livePolicy · opaqueEndpointRef · leaseUntil
 
 Core validates identity and expiry but never interprets the opaque endpoint. That remains
 inside the owning adapter. `acc status` reports available modes, policy, reachability, and
-lease without exposing the endpoint.
+lease without exposing the endpoint. The hook runner also replaces one optional native
+attempt diagnostic beside its session-owner file: closed policy/process/handshake
+metadata with a timestamp, never vendor output. Doctor joins it only to the current open
+generation and reports it separately from transport and receipt facts. It is not journalled
+or projected into agent context; session restart replaces it and SessionEnd attempts bounded
+cleanup. Doctor ignores closed or superseded generations even if cleanup could not finish. Diagnostic disk I/O runs in an
+unreferenced worker, so a stalled write cannot hold the hook process open.
 
 ## Certified capability versus current reachability
 

package/docs/CLI.md

@@ -239,8 +239,9 @@ external AI client. An addressed handoff requires acknowledgement; a room handof
 `--delivery off|actionable|all` is a per-client recipient policy request, not a capability
 switch, and the default is `off`. `--adapter` is repeatable to name several clients. An
 explicit `--delivery` applies uniformly and never prompts; omitting it on an interactive
-terminal asks one default-No question per eligible client, and on a non-interactive run or a
-`--dry-run` it keeps fresh clients off. A recorded opt-in is kept on upgrade. If the detected
+terminal asks one default-No question per supported client. Codex can save consent while
+its local service is unavailable or has no loaded session; this does not activate delivery.
+A non-interactive run or a `--dry-run` keeps fresh clients off. A recorded opt-in is kept on upgrade. If the detected
 client cannot receive native delivery - unsupported, below the captured minimum, a
 prerelease, known-bad, a wrong platform, or an unsupported shell - installation keeps the
 effective policy off and prints the reason. Claude Code shell activation writes an owned
@@ -248,7 +249,26 @@ zsh PATH block and a shim that `exec`s the real client; `ACC_BYPASS=1` bypasses
 activation. Codex LocalDaemon delivery uses recorded installation consent without changing
 ordinary launch arguments. Its opt-in remains active when shim variables are absent or
 bypassed; `acc install --adapter codex --delivery off` disables new native offers. ACC never
-starts or stops the vendor daemon. See [delivery consent](CONFIGURATION.md#keep-delivery-consent-user-owned).
+starts or stops the vendor daemon. The install summary names each client's requested policy,
+activation state and verified fallback. `doctor` separates protocol readiness, recorded
+consent and a live channel in the current workspace, with a next step for missing activation.
+A supported version or an installed plugin alone is not an active delivery channel.
+`runtime: active` means ACC has a reachable local transport binding. Claude can still
+block inbound Channels messages while its MCP server and tools remain connected;
+doctor therefore also names the client-side startup check.
+In doctor JSON, `nativeDelivery.activation` distinguishes missing launch setup from a
+recorded setup (or `not_required` for a pre-existing service). `policy` is the installed
+choice; `sessionPolicy` describes a native binding when one is visible. Existing Claude
+sessions can retain their launch policy after a different choice is installed for new
+sessions; Codex checks current recorded consent before new offers.
+`nativeDelivery.sessions` lists each current session's identity, present transport state
+and `lastAttempt`: timestamp, startup/turn event, effective policy and its source, whether
+that policy was missing/invalid/off, whether a client process was identified, and the closed
+handshake result/reason. `lastAttempt: null` means no usable attempt was observed for this
+generation; it does not prove hooks are disabled. A past successful handshake is separate
+from current transport reachability. ACC replaces this small diagnostic beside the
+hook-owner file outside the repository; it never adds attempt history to agent context.
+See [delivery consent](CONFIGURATION.md#keep-delivery-consent-user-owned).
 
 An initial `acc install` enables automatic updates. Reinstalling preserves an explicit
 `acc update --auto off` choice. A full uninstall pauses updates; reinstalling restores

package/docs/GETTING_STARTED.md

@@ -15,7 +15,7 @@ pair or session-bound ACC MCP tools. See [CLI ownership](CLI.md#coordinate-from-
 
 ACC requires macOS or Linux and Node.js 24 or newer.
 
-Already using ACC? Follow the [upgrade guide](UPGRADING.md) for the 0.4.0 → 0.4.1
+Already using ACC? Follow the [upgrade guide](UPGRADING.md) for the 0.4.0/0.4.1 → 0.4.2
 update or the data-format boundary when upgrading from 0.3.1.
 
 ```bash
@@ -44,8 +44,16 @@ state directory is in `sandbox_workspace_write.writable_roots` in the config it
 ACC keeps those user settings unchanged. Installed files alone do not establish that hooks
 are active; `acc doctor` leaves current readiness unverified and directs you to Codex.
 
-If you opt into Claude Code's experimental idle delivery, Claude also shows its own
-development-channel warning at every startup. The feature is off by default, can spend
+Read the delivery summary for each client. Live delivery needs an explicit opt-in and a
+verified channel in the current session. Codex can save your choice even when its local
+service is not running yet. Declining uses the reported fallback: `acc inbox`, or next-turn
+hooks only where the exact client version and platform are certified.
+
+If you opt into Claude Code's experimental idle delivery, check Claude's Channels startup
+notice for ACC and accept its development-channel warning when shown. If it reports Channels
+unavailable or blocked, a connected MCP server does not make inbound delivery work;
+see [troubleshooting](TROUBLESHOOTING.md#i-enabled-live-delivery-but-got-fallback).
+The feature is off by default, can spend
 model tokens, and currently requires Apple Silicon macOS, zsh, and Claude Code 2.1.258 or
 newer. You do not need it for durable messages or supported next-turn delivery.
 

package/docs/RELEASING.md

@@ -1,7 +1,7 @@
 # Releasing
 
 Use this procedure to build one auditable npm artifact, verify that exact tarball, and keep
-its evidence tied to the commit that supplied its bytes. The package is currently `0.4.1`;
+its evidence tied to the commit that supplied its bytes. The package is currently `0.4.2`;
 the commands derive the version from `package.json` so the filename cannot drift.
 
 ```mermaid

package/docs/TROUBLESHOOTING.md

@@ -94,13 +94,51 @@ For Codex, use your ordinary launch command with 0.152.1 or newer on Apple Silic
 macOS. Its LocalDaemon must already be running, and trusted hooks must establish
 the receiver's exact thread and workspace. Embedded sessions, an absent socket,
 ambiguous recipients or failed identity checks retain durable inbox access.
-`acc doctor` reports current eligibility. ACC preserves requested consent through
-a temporary daemon outage and does not start the daemon for you.
+`acc doctor` reports readiness, consent and the current workspace's live channel separately.
+`native_endpoint_unavailable` means the local service endpoint is missing or is not a safe socket;
+`native_session_unavailable` means the service answered but has no loaded thread to probe.
+An interactive install can save consent in either case. ACC preserves it through a temporary
+outage and does not start the daemon for you.
+
+Check `acc doctor --json` and `acc status --json` while both clients are open. If policy is
+`off`, opt in with `acc install --adapter codex --delivery actionable` (or select another
+adapter). This can spend model tokens. If policy is enabled but runtime is `waiting` and
+`deliveryBindings` is empty, no live channel is bound in this workspace. Start a new client
+session, check its integration prompts and re-run doctor. A healthy store, online peers,
+or a connected MCP server does not by itself establish automatic delivery. `lifecycle:
+manual` can also mean the current version has no certified session-end hook; it does not
+prove that no hooks ran.
 
 For Claude Code, open a fresh interactive zsh after installation so its launcher
-is on PATH, and accept its visible development-channel warning. A failed channel
-connection may remain in Claude's `~/.claude/mcp-needs-auth-cache.json` for about
-fifteen minutes; remove only the `acc` entry and restart if that is the cause.
+is on PATH. Check Claude's **Channels startup notice for ACC**, and accept the
+development-channel warning when it appears. A successful bootstrap cache means the
+executable passed ACC's compatibility probe. `/mcp` showing `connected` and two tools
+means the MCP server connected. Even `runtime: active` in ACC's doctor JSON describes
+the local transport; none of these proves that Claude enabled inbound channel messages.
+
+If Claude says `--dangerously-load-development-channels ignored` or `Channels are not
+currently available`, it has not enabled that delivery path. On a fresh 2.1.266 test
+profile, the first launch showed those messages and the next launch showed the development
+warning; restarting once can recheck availability, but is not a guaranteed fix. If it
+remains unavailable, follow Claude's notice. Organization policy can also block Channels;
+an administrator must enable them where required. ACC does not override that policy.
+See [Claude's Channels documentation](https://code.claude.com/docs/en/channels).
+
+If `deliveryBindings` is empty, ACC has not bound a local transport either. Read the
+per-session lines in `acc doctor`, or `nativeDelivery.sessions[].lastAttempt` in JSON:
+
+- An absent launch policy means that hook did not receive delivery consent, even if an
+  earlier bootstrap probe succeeded. For Claude, open a new terminal and client through
+  the installed launcher.
+- `client_process_unknown` means ACC could not identify the client process. A new client
+  session repeats that lookup.
+- `handshake_failed` or `handshake_timeout` means the session could not bind the local
+  channel. Check the client's integration/channel setup; the next ordinary turn retries.
+- No attempt observed can mean no native hook ran, an older runtime wrote the owner, or
+  diagnostic persistence failed. Check hook activation and the runtime versions in doctor.
+
+The timestamp describes the last attempt for that exact generation. A past successful
+handshake does not establish a currently reachable channel or client-side admission.
 
 Closing a Codex terminal can leave its daemon thread loaded and eligible. Use
 `acc install --adapter codex --delivery off` to stop new ACC native offers.

package/docs/UPGRADING.md

@@ -1,12 +1,13 @@
-# Upgrading to 0.4.1
+# Upgrading to 0.4.2
 
-## From 0.4.0
+## From 0.4.1 or 0.4.0
 
-This patch keeps the existing workspace data format. It fixes Grok CLI ownership,
-relocated Grok profiles, automatic-update preferences after reinstall, and the warning
-when a client starts in a directory containing ACC's own state.
+This patch keeps the existing workspace data format. It makes installation and delivery
+diagnostics clearer, records the last native binding attempt per session, and restores
+hook participation after detaching a solo session without restarting the conversation.
+It also includes the 0.4.1 Grok, reinstall-preference and workspace-warning fixes.
 
-Close the participating clients and persistent ACC MCP processes, then run:
+Close participating clients and persistent ACC MCP processes, then run:
 
 ```bash
 acc update
@@ -14,17 +15,28 @@ acc version
 acc doctor
 ```
 
-After publication, `acc version` should report 0.4.1. A managed update refreshes the
-installed integrations and skills. Restart the clients and complete any hook/trust
-review they request. Existing managed installations activate the selected runtime
-through `acc update`; use the npm install steps below for pre-0.4 or unmanaged
-installations. When pinned to 0.4.0, select 0.4.1 or clear the pin first.
-
-In Grok, the refreshed skill runs public status through the terminal before its first
-owned command. The hook reminder after that result supplies the session's own CLI
-arguments. Grok still reads peer messages explicitly through inbox; this patch does not
-add external wake or certify guards. Start clients in a project directory, rather than
-in a home directory containing ACC state.
+After publication, `acc version` should report 0.4.2. If a pin keeps an older version,
+select 0.4.2 or clear it first. A managed update refreshes installed integrations and
+skills; use the npm instructions below for unmanaged or pre-0.4 installations. Start
+clients again and complete any hook/trust review they request.
+
+Run `acc doctor` in the project after the new clients have started (or submitted a normal
+turn). Its per-session lines now explain missing launch consent, an unidentified client
+process and a failed or timed-out handshake. `nativeDelivery.sessions[].lastAttempt` in
+`acc doctor --json` provides the same closed metadata and timestamp. Existing owners may
+have no attempt record until a new hook runs; missing metadata does not prove hooks are
+disabled. A previous successful handshake and a connected MCP server do not prove that
+Claude admitted inbound Channels messages. See [delivery troubleshooting](TROUBLESHOOTING.md#i-enabled-live-delivery-but-got-fallback).
+
+Upgrading preserves delivery consent. If doctor reports native delivery off and you want
+automatic peer requests, use `acc install --adapter codex --delivery actionable` (or the
+relevant adapter); this can spend model tokens. Codex can save that consent before its
+local service/session becomes available. ACC does not start the vendor daemon, and it
+keeps durable inbox access when no verified live channel is bound.
+
+In Grok, public status supplies the session's own CLI arguments through the next tool
+hook. Grok still uses explicit inbox reads; this patch adds no external wake or guards.
+Start clients in a project directory, rather than a home directory containing ACC state.
 
 ## From 0.3.1
 
@@ -47,7 +59,7 @@ restores access; deleting or editing the record is not a remedy.
 2. Install the released package, then refresh the client integrations:
 
    ```bash
-   npm install --global agents-can-communicate@0.4.1
+   npm install --global agents-can-communicate@0.4.2
    acc version
    acc install
    ```
@@ -97,7 +109,7 @@ acc update                    # download and apply, or report what is keeping it
 acc update --check            # check without installing or changing update settings
 acc update --auto off         # disable background updates
 acc update --auto on          # enable them again
-acc update --pin 0.4.1        # stay on this exact stable version
+acc update --pin 0.4.2        # stay on this exact stable version
 acc update --pin none         # follow stable releases again
 ```
 

package/node_modules/@agents-can-communicate/adapter-claude-code/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-claude-code",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-claude-code/src/adapter.mjs

@@ -11,9 +11,9 @@ import { bindNativeSession, offerMessage, planNativeActivation, probeNativeDeliv
 export const CLAUDE_CODE_VERSION = "2.1.233";
 export const CLAUDE_CHANNEL_MINIMUM = "2.1.258";
 export const CLAUDE_DELIVERY_FALLBACK = Object.freeze({
-  diagnostic: "Claude Code native delivery is off: the 2.1.252 capture stopped at the "
-    + "development-channel security warning before the ACC MCP child started; messages "
-    + "stay durable for certified next-turn delivery or acc inbox",
+  diagnostic: "Claude Code native delivery requires client-side Channels activation; "
+    + "a successful bootstrap or connected ACC MCP server does not prove inbound delivery "
+    + "is enabled. Messages remain durable for certified next-turn delivery or acc inbox",
 });
 
 /**

package/node_modules/@agents-can-communicate/adapter-claude-code/src/install.mjs

@@ -1,6 +1,9 @@
 import { cp, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 
+// Kept together above 300 lines: source and cache publication, vendor registry
+// merges and their exact uninstall share one ownership transaction and helpers.
+
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
 import { fileURLToPath } from "node:url";
 
@@ -19,6 +22,9 @@ const manifest = fileURLToPath(new URL("../plugin/.claude-plugin/plugin.json",
 const PLUGIN_NAME = "agents-can-communicate";
 const MARKETPLACE = "acc-local";
 const QUALIFIED = `${PLUGIN_NAME}@${MARKETPLACE}`;
+const CHANNEL_ACTIVATION_CHECK = "Check Claude's Channels startup notice for ACC; "
+  + "an MCP connection does not verify inbound delivery. If Channels are unavailable "
+  + "or blocked, resolve that client warning before expecting live messages.";
 
 /**
  * How this client actually installs a plugin.
@@ -244,6 +250,7 @@ export async function installClaudePlugin({ configDir, runner, cli, preserveVers
     changes: [source, cached, marketplaceFile(configDir),
       knownMarketplacesPath(configDir), installedPluginsPath(configDir), file,
       ...(live ? [mcpPath(source), mcpPath(cached)] : [])],
+    needsAction: live ? [CHANNEL_ACTIVATION_CHECK] : [],
     diagnostics: live
       ? ["native channel wired; Claude's experimental development-channel warning still applies"]
       : [] };
@@ -290,7 +297,10 @@ export async function detectClaude({ configDir }) {
   const registered = Object.hasOwn(
     (await readJson(installedPluginsPath(configDir), { plugins: {} })).plugins ?? {},
     QUALIFIED);
+  const channelConfigured = enabled && registered
+    && (await readJson(mcpPath(sourceDir(configDir)), null))?.mcpServers?.["acc-channel"] != null;
   return { ok: true, changes: [],
+    needsAction: channelConfigured ? [CHANNEL_ACTIVATION_CHECK] : [],
     diagnostics: [enabled && registered
       ? "acc plugin registered and enabled"
       : "acc plugin not registered"] };

package/node_modules/@agents-can-communicate/adapter-codex/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-codex",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-codex/src/app-server-client.mjs

@@ -65,7 +65,7 @@ export async function probeCodexQueue(peer, { threadId, minimum = MINIMUM_VERSIO
       const loaded = await pageAll(peer, "thread/loaded/list", {});
       threadId = loaded.find(id => typeof id === "string" && id !== "");
       if (threadId === undefined) return { supported: false, serverVersion,
-        reasonCode: "feature_probe_failed" };
+        reasonCode: "native_session_unavailable" };
     }
     queueEntries(await peer.request("thread/queue/list", { threadId }));
   } catch (error) {

package/node_modules/@agents-can-communicate/adapter-codex/src/native-delivery.mjs

@@ -35,7 +35,7 @@ export async function probeNativeDelivery({ timeoutMs = 750, env = process.env,
   const unsupported = (reasonCode, clientVersion = null) => ({ supported: false, clientVersion,
     protocolContract: PROTOCOL_CONTRACT, executableFingerprint: null, modes: [], reasonCode });
   const socketPath = controlSocketPath(env);
-  if (!await socketIsReady(socketPath)) return unsupported("feature_probe_failed");
+  if (!await socketIsReady(socketPath)) return unsupported("native_endpoint_unavailable");
   try {
     return await usingPeer(socketPath, timeoutMs, open, async peer => {
       const probe = await probeCodexQueue(peer);

package/node_modules/@agents-can-communicate/adapter-gemini-cli/extension/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Coordinate this Gemini CLI session with other AI agent sessions working in the same workspace.",
   "contextFileName": "skills/acc/SKILL.md"
 }

package/node_modules/@agents-can-communicate/adapter-gemini-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-gemini-cli",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-grok/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-grok",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-kimi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-kimi",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-sdk",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-sdk/src/index.mjs

@@ -23,3 +23,5 @@ export { formatJsonAs, jsonStyleOf, mergeOwnedConfig, mergeOwnedEntries, ownedEn
 export { clearSessionBinding, listSessionBindings, loadSessionBinding,
   storeSessionBinding }
   from "./session-binding.mjs";
+
+export { clearNativeAttempt, loadNativeAttempt, storeNativeAttempt } from "./native-attempt.mjs";

package/node_modules/@agents-can-communicate/adapter-sdk/src/native-attempt-writer.mjs

@@ -0,0 +1,64 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { parentPort, workerData } from "node:worker_threads";
+
+import { assertPortableId } from "@agents-can-communicate/protocol";
+import { withWriterMutex } from "@agents-can-communicate/storage-filesystem";
+import { loadNativeAttempt, nativeAttemptFrom } from "./native-attempt.mjs";
+
+const keyFor = harnessSessionId => createHash("sha256").update(String(harnessSessionId))
+  .digest("hex").slice(0, 32);
+const fileFor = (runtimeDir, harnessSessionId) =>
+  path.join(runtimeDir, "native-attempts", `${keyFor(harnessSessionId)}.json`);
+const checkDeadline = deadline => {
+  if (Date.now() >= deadline) throw new Error("native diagnostic deadline expired");
+};
+
+// The caller stops waiting after 250 ms at most. An in-flight filesystem call
+// may complete later, so retain this SEPARATE mutex until its continuation is
+// finished. Unique staging names also isolate cleanup after stale-lock recovery.
+// No diagnostic operation can touch the authoritative hook-owner file.
+async function boundedWrite(input, operation) {
+  const deadline = input.deadlineAt;
+  try {
+    checkDeadline(deadline);
+    await withWriterMutex({ locks: path.join(input.runtimeDir, "native-attempt-locks",
+      keyFor(input.harnessSessionId)) }, { root: input.runtimeDir,
+      clock: { now: () => new Date().toISOString() }, deadlineAt: deadline },
+    () => operation(deadline));
+    return true;
+  } catch { return false; }
+}
+
+async function storeNativeAttempt(input) {
+  return boundedWrite(input, async deadline => {
+    const { runtimeDir, harnessSessionId, accSessionId, generation } = input;
+    assertPortableId(accSessionId, "native diagnostic session id");
+    assertPortableId(generation, "native diagnostic generation");
+    const attempt = nativeAttemptFrom(input.nativeAttempt);
+    if (attempt === null) return;
+    const file = fileFor(runtimeDir, harnessSessionId);
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    checkDeadline(deadline);
+    await mkdir(path.dirname(file), { recursive: true });
+    try {
+      checkDeadline(deadline);
+      await writeFile(temporary, JSON.stringify({ schemaVersion: 1, accSessionId, generation,
+        attempt }) + "\n", "utf8");
+      checkDeadline(deadline);
+      await rename(temporary, file);
+    } finally { await rm(temporary, { force: true }).catch(() => {}); }
+  });
+}
+
+async function clearNativeAttempt(input) {
+  return boundedWrite(input, async deadline => {
+    if (await loadNativeAttempt(input) === null) return;
+    checkDeadline(deadline);
+    await rm(fileFor(input.runtimeDir, input.harnessSessionId), { force: true });
+  });
+}
+
+const operation = workerData.operation === "clear" ? clearNativeAttempt : storeNativeAttempt;
+parentPort.postMessage(await operation(workerData.input));

package/node_modules/@agents-can-communicate/adapter-sdk/src/native-attempt.mjs

@@ -0,0 +1,65 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { Worker } from "node:worker_threads";
+
+import { NATIVE_REASON_CODES, TIMESTAMP } from "./native-vocabulary.mjs";
+
+// Optional diagnostic metadata beside the hook-owner file, never an event
+// history or injected context. Copy only closed values: vendor errors, prompts,
+// endpoints and extra properties must not survive persistence or doctor reads.
+export function nativeAttemptFrom(value) {
+  if (!value || typeof value.at !== "string" || !TIMESTAMP.test(value.at)
+    || !Number.isFinite(Date.parse(value.at))
+    || !["sessionStart", "beforeTurn"].includes(value.event)
+    || !["active", "off", "degraded", "unsupported"].includes(value.state)
+    || !(value.reasonCode === null || NATIVE_REASON_CODES.includes(value.reasonCode))
+    || !["off", "actionable", "all"].includes(value.policy)
+    || !["bootstrap-environment", "installation-record"].includes(value.policySource)
+    || !["enabled", "off", "missing", "invalid", "unavailable"].includes(value.policyStatus)
+    || !["identified", "unknown"].includes(value.clientProcess)) return null;
+  return { at: value.at, event: value.event, state: value.state, reasonCode: value.reasonCode,
+    policy: value.policy, policySource: value.policySource, policyStatus: value.policyStatus,
+    clientProcess: value.clientProcess };
+}
+
+const keyFor = harnessSessionId => createHash("sha256").update(String(harnessSessionId))
+  .digest("hex").slice(0, 32);
+const fileFor = (runtimeDir, harnessSessionId) =>
+  path.join(runtimeDir, "native-attempts", `${keyFor(harnessSessionId)}.json`);
+export async function loadNativeAttempt({ runtimeDir, harnessSessionId, accSessionId, generation }) {
+  try {
+    const record = JSON.parse(await readFile(fileFor(runtimeDir, harnessSessionId), "utf8"));
+    return record.schemaVersion === 1 && record.accSessionId === accSessionId
+      && record.generation === generation ? nativeAttemptFrom(record.attempt) : null;
+  } catch { return null; }
+}
+
+// Isolate filesystem requests as well as JS waiting: even a stuck fs request
+// must not keep the vendor's short-lived hook process alive after its output.
+// The unreferenced worker owns its mutex through any late I/O continuation.
+async function writeDiagnostic(operation, input) {
+  const deadlineAt = Math.min(input.deadlineAt ?? Infinity, Date.now() + 250);
+  if (Date.now() >= deadlineAt) return false;
+  let worker;
+  let timer;
+  try {
+    worker = new Worker(new URL("./native-attempt-writer.mjs", import.meta.url), {
+      workerData: { operation, input: { runtimeDir: input.runtimeDir,
+        harnessSessionId: input.harnessSessionId, accSessionId: input.accSessionId,
+        generation: input.generation, nativeAttempt: nativeAttemptFrom(input.nativeAttempt), deadlineAt } },
+    });
+    const result = new Promise(resolve => {
+      worker.once("message", value => resolve(value === true));
+      worker.once("error", () => resolve(false));
+      worker.once("exit", () => resolve(false));
+      timer = setTimeout(() => resolve(false), Math.max(0, deadlineAt - Date.now()));
+    });
+    worker.unref();
+    return await result;
+  } catch { return false; }
+  finally { clearTimeout(timer); }
+}
+
+export const storeNativeAttempt = input => writeDiagnostic("store", input);
+export const clearNativeAttempt = input => writeDiagnostic("clear", input);

package/node_modules/@agents-can-communicate/adapter-sdk/src/native-vocabulary.mjs

@@ -23,6 +23,7 @@ export const NATIVE_REASON_CODES = Object.freeze([
   "native_delivery_unsupported", "platform_not_captured", "version_unavailable",
   "prerelease_not_captured", "below_minimum_version", "known_bad_version",
   "feature_probe_failed", "probe_timeout", "probe_version_mismatch", "protocol_mismatch",
+  "native_endpoint_unavailable", "native_session_unavailable",
   "handshake_failed", "handshake_timeout", "handshake_version_mismatch",
   "session_generation_stale", "client_process_unknown", "unsupported_shell",
   // The current session's canonical workspace identity could not be verified.

package/node_modules/@agents-can-communicate/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/cli",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "private": true,
   "type": "module",
   "exports": {