agents-can-communicate 0.3.1 → 0.4.1

package/node_modules/@agents-can-communicate/hook-runner/src/owner-context.mjs

@@ -0,0 +1,30 @@
+import { assertPortableId } from "@agents-can-communicate/protocol";
+
+export const ownerHeader = binding => "ACC CLI (append): --session "
+  + assertPortableId(binding.accSessionId, "sessionId") + " --generation "
+  + assertPortableId(binding.generation, "generation");
+
+export function ownerOnlyOutcome(inject, owner, budgetBytes) {
+  if (Buffer.byteLength(owner, "utf8") > budgetBytes) {
+    return { stdout: "", stderr: "acc: context budget cannot fit owner arguments; increase contextBudgetBytes" };
+  }
+  return { stdout: "", ...inject(owner) };
+}
+
+// This is ownership context only. No peer projection, receipt, new session or
+// inherited environment belongs here. A client may deliver the line after the
+// tool has closed its owner; owned CLI operations must still validate the pair.
+export async function appendToolOwner(result, { event, binding, context, adapter }) {
+  if (event.kind !== "beforeTool" || result.decision !== "allow" || binding === null
+    || typeof adapter.injectToolOwnerOutcome !== "function") return result;
+  const current = await context.service.locateSession(binding.accSessionId, context.descriptor.id);
+  if (current?.record.state !== "open" || current.record.generation !== binding.generation) return result;
+
+  const owner = ownerHeader(binding);
+  const injected = adapter.injectToolOwnerOutcome({ owner, tool: event.tool });
+  if (injected === null) return result;
+  const fitted = ownerOnlyOutcome(() => injected, owner,
+    context.descriptor.policy?.contextBudgetBytes ?? 6_000);
+  return { ...result, stdout: fitted.stdout,
+    stderr: [result.stderr, fitted.stderr].filter(Boolean).join("\n") };
+}

package/node_modules/@agents-can-communicate/hook-runner/src/process-table.mjs

@@ -20,7 +20,7 @@ export async function readProcessTable({ run: exec = run,
   timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
   try {
     const { stdout } = await exec("ps", ["-o", "pid=,ppid=,comm=", "-A"],
-      { timeout: timeoutMs });
+      { timeout: timeoutMs, killSignal: "SIGKILL" });
     const table = new Map();
     for (const line of stdout.split("\n")) {
       const match = LINE.exec(line);

package/node_modules/@agents-can-communicate/hook-runner/src/runner.mjs

@@ -1,3 +1,4 @@
+import { retireNativeBinding } from "./native-retirement.mjs";
 import { createHash, randomBytes } from "node:crypto";
 import { realpath } from "node:fs/promises";
 import path from "node:path";
@@ -5,7 +6,8 @@ import path from "node:path";
 import { clearSessionBinding, effectiveCapabilities, loadSessionBinding, storeSessionBinding }
   from "@agents-can-communicate/adapter-sdk";
 import { createCoordinationService } from "@agents-can-communicate/core";
-import { createId } from "@agents-can-communicate/protocol";
+import { readInstalledLivePolicy } from "@agents-can-communicate/installer";
+import { AccError, createId } from "@agents-can-communicate/protocol";
 import { openFilesystemStore } from "@agents-can-communicate/storage-filesystem";
 import { createGitProbe, discoverWorkspace, platformDataHome, runtimePaths }
   from "@agents-can-communicate/cli";
@@ -14,6 +16,8 @@ import { resolveClientPid } from "./client-pid.mjs";
 import { probeClientVersion as defaultProbeClientVersion } from "./client-version.mjs";
 import { establishNativeBinding, livePolicyFrom } from "./native-binding.mjs";
 import { readProcessTable as defaultReadProcessTable } from "./process-table.mjs";
+import { withSessionLifecycle } from "./session-lifecycle.mjs";
+import { appendToolOwner, ownerHeader, ownerOnlyOutcome } from "./owner-context.mjs";
 
 // Kept cohesive above 300 lines because every handler shares one fail-open
 // hook boundary, binding lifecycle, and client-specific outcome contract.
@@ -24,6 +28,10 @@ import { readProcessTable as defaultReadProcessTable } from "./process-table.mjs
 // let a call through than to make someone's session sit waiting on us.
 const DEFAULT_BUDGET_MS = 5_000;
 
+function assertHookBudget(deadline, message = "hook deadline expired") {
+  if (Date.now() >= deadline) throw new Error(message);
+}
+
 const byteLength = value => Buffer.byteLength(value, "utf8");
 
 function compactInboxRecovery(messages) {
@@ -171,17 +179,20 @@ export function participantFor(adapterId, harnessSessionId, env = {}) {
   return `${adapterId}-${suffix}`;
 }
 
-async function openContext({ cwd, dataHome, runtime, env }) {
+async function openContext({ cwd, dataHome, runtime, env, deadline }) {
+  assertHookBudget(deadline);
   const descriptor = await discoverWorkspace({ cwd, env: env ?? {},
-    gitProbe: createGitProbe() });
+    gitProbe: createGitProbe({ deadlineAt: deadline }) });
+  assertHookBudget(deadline);
+  const resolvedDataHome = dataHome ?? platformDataHome({ env: env ?? {} });
   const paths = runtimePaths({
-    dataHome: dataHome ?? platformDataHome({ env: env ?? {} }),
+    dataHome: resolvedDataHome,
     workspaceId: descriptor.id,
     workspaceRoots: descriptor.roots,
   });
   const store = await openFilesystemStore({ root: paths.root, clock: runtime.clock,
-    ids: runtime.ids, workspaceId: descriptor.id });
-  return { descriptor, paths, env: env ?? {}, realpath: runtime.realpath ?? realpath,
+    ids: runtime.ids, workspaceId: descriptor.id, deadlineAt: deadline });
+  return { descriptor, paths, dataHome: resolvedDataHome, env: env ?? {}, realpath: runtime.realpath ?? realpath,
     service: createCoordinationService({ store, clock: runtime.clock, ids: runtime.ids }) };
 }
 
@@ -207,12 +218,17 @@ async function projectTurn({ binding, context, adapter, adapterId }) {
     exceptSessionId: binding.accSessionId });
   const messages = delivery.queuedMessages;
 
-  // Solo costs nothing: nothing to say means nothing printed, not a banner
-  // announcing that nobody else is here. But something already said to you is
-  // not nothing - the check used to run before the inbox was read, so the
-  // answer to your own request vanished the moment the agent working on it
-  // closed and left you as the only session.
-  if (sync.solo && messages.length === 0) return { stdout: "" };
+  // Only this hook's payload selected the binding. Supply its own pair as
+  // trusted context, outside peer bodies, rather than exporting inheritable
+  // credentials or teaching the CLI to guess from a public roster.
+  const owner = ownerHeader(binding);
+  const totalBudget = context.descriptor.policy?.contextBudgetBytes ?? 6_000;
+  // A peer can join after this prompt has begun. The current turn must already
+  // have its own arguments when it needs inbox/reply, without reattaching or
+  // waiting for another user prompt. Solo emits identity, not a peer notice.
+  if (sync.solo && messages.length === 0) {
+    return ownerOnlyOutcome(text => adapter.injectOutcome?.(text), owner, totalBudget);
+  }
 
   // The ceiling a team agreed on in `acc.workspace.json`, or the default when
   // there is no config. Validated by the protocol and, until now, never read:
@@ -222,10 +238,18 @@ async function projectTurn({ binding, context, adapter, adapterId }) {
   const canOfferNextTurn = effective.delivery.nextTurn === true && hasStructuredRenderer;
   const projectionInput = { ...sync, messages: canOfferNextTurn ? messages : [],
     liveOfferedMessageIds: delivery.liveOfferedMessageIds,
+    reminderMessageIds: delivery.reminderMessageIds,
     roomMessageIds: delivery.roomMessageIds,
     currentParticipantId: mine?.participantId };
+  // Credentials alone cannot replace the command that reaches a queued body.
+  // If both cannot fit, preserve recovery and explain the missing owner pair.
+  const minimumBodyBytes = messages.length === 0 ? 1
+    : byteLength(compactInboxRecovery(messages.slice(0, 1)));
+  const ownerFits = byteLength(owner) + 1 + minimumBodyBytes <= totalBudget;
+  const ownerWarning = ownerFits ? null
+    : "acc: context budget cannot fit owner arguments with coordination context; increase contextBudgetBytes";
   const projectionOptions = {
-    budgetBytes: context.descriptor.policy?.contextBudgetBytes };
+    budgetBytes: ownerFits ? totalBudget - byteLength(owner) - 1 : totalBudget };
   // Delivery is state, not text parsing. Peer-controlled bodies can imitate
   // another message's visible header, so only projector metadata proves
   // which complete groups survived the byte budget. A custom adapter without
@@ -246,10 +270,17 @@ async function projectTurn({ binding, context, adapter, adapterId }) {
       + `${messages[0].messageId} with acc inbox --message ${messages[0].messageId}` : null;
   const visibleDegradation = degradation === null ? "" : `ACC: ${degradation.slice(5)}`;
   const budgetBytes = projectionOptions.budgetBytes ?? 6_000;
-  const projected = degradation === null ? projection.text
+  const body = degradation === null ? projection.text
     : fitDegradation(projection.text, visibleDegradation, messages, budgetBytes);
+  // Own claims make sync non-solo but produce no peer context. They cannot
+  // remove this turn's identity or consume a nonexistent body separator.
+  if (body === "" && messages.length === 0) {
+    return ownerOnlyOutcome(text => adapter.injectOutcome?.(text), owner, totalBudget);
+  }
+  const projected = body === "" ? "" : ownerFits ? `${owner}\n${body}` : body;
   if (projected === "") {
-    return degradation === null ? { stdout: "" } : { stdout: "", stderr: degradation };
+    return { stdout: "", stderr: messages.length === 0 ? ""
+      : [ownerWarning, degradation].filter(Boolean).join("\n") };
   }
 
   // The renderer returns ids as metadata, never as text to parse. A peer body
@@ -269,20 +300,24 @@ async function projectTurn({ binding, context, adapter, adapterId }) {
   // callback proves that the bytes crossed.
   const outcome = { stdout: "", ...adapter.injectOutcome?.(projected) };
   const writableOffers = outcome.stdout === "" ? [] : offerInputs;
-  if (degradation === null) return { ...outcome, offerInputs: writableOffers };
   return { ...outcome,
-    stderr: [outcome.stderr, degradation].filter(Boolean).join("\n"),
+    stderr: [outcome.stderr, ownerWarning, degradation].filter(Boolean).join("\n"),
     offerInputs: writableOffers };
 }
 
 // One bounded, fail-open native handshake for this exact session generation.
-// The policy comes only from the environment an owned shell bootstrap
-// exported; an ordinary launch has none and stays durable.
+// New adapters read durable consent from their installation record; legacy
+// adapters keep the environment exported by an owned shell bootstrap.
 async function bindNative({ adapter, event, hookBinding, clientVersion, platform, context, paths,
   deadline }) {
+  assertHookBudget(deadline);
+  const livePolicy = adapter?.nativeDelivery?.policySource === "installation-record"
+    ? await readInstalledLivePolicy({ dataHome: context.dataHome, adapterId: adapter.id })
+    : livePolicyFrom(context.env);
+  assertHookBudget(deadline);
   return establishNativeBinding({ adapter, event, hookBinding, clientVersion, platform,
-    livePolicy: livePolicyFrom(context.env), service: context.service, runtimeDir: paths.root,
-    clock: context.service.clock,
+    livePolicy, service: context.service, runtimeDir: paths.root,
+    clock: context.service.clock, env: context.env,
     timeoutMs: Math.max(1, Math.min(750, deadline - Date.now())) });
 }
 
@@ -293,11 +328,12 @@ const HANDLERS = {
     // certified facts before any probe, PID lookup, resume, or open can fail;
     // keep only the generation identity needed for a successful resume.
     if (binding !== null) {
-      await storeSessionBinding({ runtimeDir: paths.root, harnessSessionId: event.sessionId,
+      await storeSessionBinding({ runtimeDir: paths.root, deadlineAt: deadline, harnessSessionId: event.sessionId,
         accSessionId: binding.accSessionId, generation: binding.generation });
     }
     const clientVersion = await probeClientVersion(adapter,
       { timeoutMs: Math.max(1, Math.min(1_000, deadline - Date.now())) });
+    assertHookBudget(deadline);
     const clientFacts = { clientVersion, platform };
     const capabilities = effectiveCapabilities(adapter, clientFacts);
     // Once per session, never per turn. A client that cannot be found yields
@@ -305,7 +341,9 @@ const HANDLERS = {
     // behaviour every session had before this existed.
     const command = adapter.client?.command ?? null;
     const pid = command === null ? null
-      : resolveClientPid({ table: await readProcessTable(), from: process.pid, command });
+      : resolveClientPid({ table: await readProcessTable({
+        timeoutMs: Math.max(1, Math.min(1_000, deadline - Date.now())) }), from: process.pid, command });
+    assertHookBudget(deadline);
     const clientPid = Number.isInteger(pid) && pid > 0 ? pid : undefined;
     const native = hookBinding => bindNative({ adapter, event, hookBinding, ...clientFacts,
       context, paths, deadline });
@@ -317,6 +355,16 @@ const HANDLERS = {
       checkoutRoot: context.descriptor.git?.worktreeRoot ?? context.descriptor.roots[0],
       branch: context.descriptor.git?.branch ?? null,
     };
+    if (event.kind === "beforeTurn" && binding !== null) {
+      // A real prompt may continue after finish closed this native owner's
+      // record. Recheck after the probes: a CLI replacement can run outside
+      // the native lifecycle lock. Never adopt that replacement's identity.
+      const previous = await context.service.locateSession(binding.accSessionId);
+      if (previous?.record.state !== "closed"
+        || previous.record.generation !== binding.generation) {
+        throw new Error("the completed hook owner changed during turn registration");
+      }
+    }
     if (binding !== null) {
       const resumed = await context.service.resumeSession({
         sessionId: binding.accSessionId,
@@ -326,13 +374,21 @@ const HANDLERS = {
       if (resumed !== null) {
         const hookBinding = { accSessionId: resumed.sessionId, generation: resumed.generation,
           ...clientFacts, clientPid };
-        await storeSessionBinding({ runtimeDir: paths.root, harnessSessionId: event.sessionId,
+        await storeSessionBinding({ runtimeDir: paths.root, deadlineAt: deadline, harnessSessionId: event.sessionId,
           ...hookBinding });
         return { accSessionId: resumed.sessionId, generation: resumed.generation,
           ...clientFacts, capabilities, nativeBinding: await native(hookBinding) };
       }
     }
+    // Persist ownership before creating its session. If the hook dies after
+    // creation, the next start resumes this exact pair. If creation never
+    // happened (or it was closed), a retry allocates a NEW pair, never revives it.
+    const opening = { sessionId: context.service.ids.next("session"),
+      generation: context.service.ids.next("generation") };
+    await storeSessionBinding({ runtimeDir: paths.root, deadlineAt: deadline, harnessSessionId: event.sessionId,
+      accSessionId: opening.sessionId, generation: opening.generation });
     const session = await context.service.openSession({
+      ...opening,
       workspaceId: context.descriptor.id,
       participantId: participantFor(adapterId, event.sessionId, context.env),
       displayName: participantFor(adapterId, event.sessionId, context.env),
@@ -348,7 +404,7 @@ const HANDLERS = {
     });
     const hookBinding = { accSessionId: session.sessionId, generation: session.generation,
       ...clientFacts, clientPid };
-    await storeSessionBinding({ runtimeDir: paths.root, harnessSessionId: event.sessionId,
+    await storeSessionBinding({ runtimeDir: paths.root, deadlineAt: deadline, harnessSessionId: event.sessionId,
       ...hookBinding });
     return { accSessionId: session.sessionId, generation: session.generation,
       ...clientFacts, capabilities, nativeBinding: await native(hookBinding) };
@@ -361,27 +417,59 @@ const HANDLERS = {
     return {};
   },
 
-  async sessionEnd({ binding, context, event, paths }) {
+  async sessionEnd({ binding, context, event, paths, adapter, deadline }) {
     if (binding === null) return {};
-    await context.service.closeSession({ sessionId: binding.accSessionId,
-      generation: binding.generation });
-    await clearSessionBinding({ runtimeDir: paths.root, harnessSessionId: event.sessionId });
+    await retireNativeBinding({ adapter, service: context.service, sessionId: binding.accSessionId,
+      generation: binding.generation, runtimeDir: paths.root,
+      timeoutMs: Math.max(1, Math.min(200, deadline - Date.now())) });
+    const owner = { sessionId: binding.accSessionId, generation: binding.generation };
+    const current = await context.service.locateSession(binding.accSessionId);
+    if (current?.record.generation === binding.generation && current.record.state === "open") {
+      await context.service.closeSession(owner);
+    } else {
+      // Close may have committed before this hook died. Retire only the old
+      // endpoint and binding; do not close a replacement or repeat a close event.
+      await context.service.clearDeliveryBinding(owner);
+    }
+    await clearSessionBinding({ runtimeDir: paths.root, deadlineAt: deadline, harnessSessionId: event.sessionId });
     return {};
   },
 
   async beforeTurn(input) {
     const { binding, context, adapter, event, paths, deadline } = input;
-    if (binding === null) return {};
+    if (binding === null) {
+      // SessionStart can be skipped when an automatic runtime refresh races
+      // process admission. A genuine prompt is the next safe proof that this
+      // native conversation exists, and it is already inside the same
+      // lifecycle mutex as startup. Reuse that opening path so publication,
+      // crash recovery, client facts, and the native handshake stay atomic.
+      const started = await HANDLERS.sessionStart(input);
+      const fresh = await loadSessionBinding({ runtimeDir: paths.root,
+        harnessSessionId: event.sessionId });
+      const turn = await projectTurn({ ...input, binding: fresh });
+      return { ...turn, nativeBinding: started.nativeBinding };
+    }
+    const current = await context.service.locateSession(binding.accSessionId);
+    if (current?.record.state === "closed" && current.record.generation === binding.generation) {
+      // finish ends an ACC incarnation, not the native conversation. Only a
+      // genuine new user turn can start another one; tool hooks cannot. Reuse
+      // the crash-safe opening path, retaining its full published client facts
+      // and its single native handshake rather than binding a second time.
+      const started = await HANDLERS.sessionStart(input);
+      const fresh = await loadSessionBinding({ runtimeDir: paths.root,
+        harnessSessionId: event.sessionId });
+      const turn = await projectTurn({ ...input, binding: fresh });
+      return { ...turn, nativeBinding: started.nativeBinding };
+    }
     // A turn is the clearest sign a session is alive. Never a reason to fail:
     // this runs in front of somebody's prompt.
     await context.service.heartbeatSession({ sessionId: binding.accSessionId,
-      generation: binding.generation }).catch(() => null);
+      generation: binding.generation });
     // A native transport that became ready only after SessionStart is picked
     // up here and a live lease is renewed: bounded, fail-open, never on a guard.
-    const nativeBinding = livePolicyFrom(context.env) === "off" ? undefined
-      : await bindNative({ adapter, event, hookBinding: binding,
-        clientVersion: binding.clientVersion, platform: binding.platform, context, paths,
-        deadline });
+    const nativeBinding = await bindNative({ adapter, event, hookBinding: binding,
+      clientVersion: binding.clientVersion, platform: binding.platform, context, paths,
+      deadline });
     const turn = await projectTurn(input);
     return nativeBinding === undefined ? turn : { ...turn, nativeBinding };
   },
@@ -458,42 +546,49 @@ export async function runHook({ adapterId, payload, adapters, dataHome, env,
   probeClientVersion = defaultProbeClientVersion,
   platform = `${process.platform}-${process.arch}` }) {
   const deadline = Date.now() + budgetMs;
-  const result = { stdout: "", exitCode: 0, decision: "allow", sessions: [], deadlineAt: deadline,
+  const fallback = { stdout: "", exitCode: 0, decision: "allow", sessions: [], deadlineAt: deadline,
     commitOffers: async () => {} };
-  let timer = null;
-  try {
+  const execute = async () => {
+    assertHookBudget(deadline);
     const adapter = adapters?.[adapterId];
     if (adapter === undefined) throw new Error(`no adapter named ${adapterId}`);
 
     const event = await adapter.normalizeHook(payload);
-    const context = await openContext({ cwd: event.cwd, dataHome, runtime, env });
-    const binding = await loadSessionBinding({ runtimeDir: context.paths.root,
-      harnessSessionId: event.sessionId }).catch(() => null);
-
+    const context = await openContext({ cwd: event.cwd, dataHome, runtime, env, deadline });
     const handler = HANDLERS[event.kind];
-    const work = handler === undefined
-      ? Promise.resolve({})
-      : handler({ event, context, adapter, adapterId, binding, paths: context.paths,
+    const lifecycle = ["sessionStart", "sessionEnd", "beforeTurn"].includes(event.kind);
+    const invoke = async () => {
+      assertHookBudget(deadline);
+      if (lifecycle) {
+        // A previous holder may have died after journalling its session while
+        // this process waited. Recover that write before interpreting its binding.
+        const store = await openFilesystemStore({ root: context.paths.root, clock: runtime.clock,
+          ids: runtime.ids, workspaceId: context.descriptor.id, deadlineAt: deadline });
+        context.service = createCoordinationService({ store, clock: runtime.clock, ids: runtime.ids });
+      }
+      const binding = await loadSessionBinding({ runtimeDir: context.paths.root,
+        harnessSessionId: event.sessionId });
+      assertHookBudget(deadline);
+      const result = handler === undefined ? {} : await handler({ event, context, adapter, adapterId,
+        binding, paths: context.paths,
         readProcessTable, probeClientVersion, platform, deadline });
-
-    // The loser of a race is not cancelled, so the timer is cleared explicitly:
-    // an outstanding one keeps the process alive long past its answer.
-    const budget = new Promise(resolve => {
-      timer = setTimeout(() => resolve({ timedOut: true }), budgetMs);
-    });
-    Object.assign(result, await Promise.race([work, budget]));
-
+      return appendToolOwner(result, { event, binding, context, adapter });
+    };
+    const work = lifecycle
+      ? withSessionLifecycle({ root: context.paths.root, sessionId: event.sessionId,
+        clock: runtime.clock, deadlineAt: deadline }, invoke)
+      : invoke();
+    // Keep the late continuation's result private. Once the budget wins, it
+    // cannot change the fail-open answer or restore withdrawn output/offers.
+    const result = { ...fallback, ...await work };
+    assertHookBudget(deadline);
     const offerInputs = result.offerInputs ?? [];
     let commitPromise = null;
     result.commitOffers = () => {
       if (commitPromise !== null) return commitPromise;
       commitPromise = (async () => {
         for (const input of offerInputs) {
-          const remaining = deadline - Date.now();
-          if (remaining <= 0) throw new Error("hook budget exhausted before offer commit");
-          // The durable transaction owns deadline cancellation. Racing it here
-          // would only reject the public promise while the losing writer kept
-          // waiting and could publish later.
+          assertHookBudget(deadline, "hook budget exhausted before offer commit");
           await context.service.recordOfferSucceeded({ ...input, deadlineAt: deadline });
         }
       })();
@@ -503,18 +598,28 @@ export async function runHook({ adapterId, payload, adapters, dataHome, env,
 
     const status = await context.service.collectStatus({
       workspaceId: context.descriptor.id });
+    assertHookBudget(deadline);
     result.sessions = status.participants.filter(p => p.presence !== "offline");
     result.service = context.service;
+    return result;
+  };
+
+  let timer;
+  try {
+    // One budget covers normalization, discovery, recovery, handling and the
+    // final status read. Store/binding deadlines fence undecided writes; an
+    // activated journal still completes under its writer lock after expiry.
+    const budget = new Promise(resolve => {
+      timer = setTimeout(() => resolve({ ...fallback, timedOut: true }),
+        Math.max(0, deadline - Date.now()));
+    });
+    return await Promise.race([execute(), budget]);
   } catch (error) {
-    result.failed = true;
-    result.reason = error.message;
-    result.decision = "allow";
-    result.stdout = "";
-    // A later failure may happen after a turn prepared offer inputs. Once the
-    // fail-open path withdraws stdout, no transport boundary remains to commit.
-    result.commitOffers = async () => {};
+    return { ...fallback, failed: true, reason: error.message,
+      ...(error instanceof AccError && error.details?.reasonCode === "workspace_contains_runtime"
+        ? { failureCode: "workspace_contains_runtime" } : {}),
+      ...(Date.now() >= deadline ? { timedOut: true } : {}) };
   } finally {
-    if (timer !== null) clearTimeout(timer);
+    clearTimeout(timer);
   }
-  return result;
 }

package/node_modules/@agents-can-communicate/hook-runner/src/session-lifecycle.mjs

@@ -0,0 +1,13 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+
+import { withWriterMutex } from "@agents-can-communicate/storage-filesystem";
+
+// Binding ownership spans load, resume/open/close, and publication. The store's
+// writer lock protects each record, but cannot protect this whole hook sequence.
+// Use the same crash-safe mutex in a separate directory to avoid nested locks.
+export function withSessionLifecycle({ root, sessionId, clock, deadlineAt }, operation) {
+  const key = createHash("sha256").update(String(sessionId)).digest("hex");
+  return withWriterMutex({ locks: path.join(root, "lifecycle-locks", key) },
+    { root, clock, deadlineAt }, operation);
+}

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

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

package/node_modules/@agents-can-communicate/installer/src/apply.mjs

@@ -42,10 +42,12 @@ export async function applyPlan({ plan, adapters, context, dataHome, dryRun = fa
         // a fixed order; an explicit off takes a recorded one back first so the
         // record written below describes the machine as it now is.
         const notes = [];
+        let retainedMechanisms = [];
         if (operation.deactivation !== undefined) {
           const report = await deactivateNative({ nativeActivation: operation.deactivation,
             ...activation });
           notes.push(...describeTeardown(report));
+          retainedMechanisms = report.retainedMechanisms;
         }
         let native = null;
         let appendedRcBlock = false;
@@ -55,13 +57,19 @@ export async function applyPlan({ plan, adapters, context, dataHome, dryRun = fa
           native = applied.nativeActivation;
           appendedRcBlock = applied.appendedRcBlock;
         }
+        if (retainedMechanisms.length > 0) {
+          native = { ...(native ?? operation.deactivation),
+            mechanisms: [...(native?.mechanisms ?? []), ...retainedMechanisms] };
+        }
         // Recorded after the write, so a record never claims an install that
         // did not happen. The reverse order would leave uninstall trying to
         // remove files nothing created.
         await recordInstall({ dataHome, adapterId: adapter.id,
           version: operation.clientVersion ?? null, accVersion,
-          artifacts: operation.artifacts, createdDirectories, nativeActivation: native });
+          artifacts: operation.artifacts, createdDirectories,
+          deliveryPolicy: operation.livePolicy, nativeActivation: native });
         results.operations.push({ ...operation, applied: true, appendedRcBlock,
+          needsAction: outcome.needsAction ?? [],
           changes: outcome.changes ?? [], diagnostics: [
             ...(operation.deliveryDiagnostic === undefined
               ? [] : [operation.deliveryDiagnostic]),
@@ -69,14 +77,19 @@ export async function applyPlan({ plan, adapters, context, dataHome, dryRun = fa
             ...notes,
           ] });
       } else {
+        // Config ownership can veto removal. Ask before teardown or recorded
+        // artifact deletion; an adapter-local check would run after those writes.
+        await adapter.preflightUninstall?.(context);
         // Keep the record until every cleanup step succeeds. It is both the
         // authority for deletion and the only durable recipe a retry has when
         // the client or one of ACC's own artifacts is already gone.
         const notes = [];
+        let retainedMechanisms = [];
         if (operation.deactivation !== undefined) {
           const report = await deactivateNative({ nativeActivation: operation.deactivation,
             ...activation });
           notes.push(...describeTeardown(report));
+          retainedMechanisms = report.retainedMechanisms;
         }
         const owned = await removeOwnedArtifacts({ dataHome, adapterId: adapter.id });
         // What ownership held back is passed on, because the adapter would
@@ -86,7 +99,9 @@ export async function applyPlan({ plan, adapters, context, dataHome, dryRun = fa
         const outcome = await adapter.uninstall({ ...context, keep: owned.kept });
         const directories = await removeEmptyOwnedDirectories({ home: context.home,
           directories: owned.createdDirectories });
-        await finalizeRemoval({ dataHome, adapterId: adapter.id });
+        await finalizeRemoval({ dataHome, adapterId: adapter.id,
+          retainedNativeActivation: retainedMechanisms.length === 0 ? null
+            : { ...operation.deactivation, mechanisms: retainedMechanisms } });
         results.operations.push({ ...operation, applied: true,
           changes: outcome.changes ?? [], removed: owned.removed, kept: owned.kept,
           removedDirectories: directories.removed, keptDirectories: directories.kept,

package/node_modules/@agents-can-communicate/installer/src/bootstrap-runtime.mjs

@@ -4,7 +4,7 @@ import { createReadStream } from "node:fs";
 import { mkdir, readFile, realpath, rename, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 
-import { evaluateNativeEligibility } from "@agents-can-communicate/adapter-sdk";
+import { evaluateNativeEligibility, ownVersion } from "@agents-can-communicate/adapter-sdk";
 
 // The launch-time check behind an owned shell shim. It answers one closed
 // question - may this exact executable receive native delivery? - from the
@@ -13,9 +13,10 @@ import { evaluateNativeEligibility } from "@agents-can-communicate/adapter-sdk";
 // command untouched, and this module is what makes "cannot decide" cheap.
 //
 // The cache key is the executable's identity - resolved path, symlink target,
-// inode, size, mtime, and full sha256 - so an upgrade or replacement is a miss
-// and an unchanged binary skips the version spawn and the probe. A cached
-// failure is short-lived; a repaired client is never disabled for long.
+// inode, size, mtime, and full sha256 - plus platform and this ACC runtime's
+// version. A vendor upgrade, replacement, or changed certification contract is
+// therefore a miss. A cached failure is short-lived; a repaired client is
+// never disabled for long.
 
 export const BOOTSTRAP_CACHE_SCHEMA = 1;
 export const SUPPORTED_TTL_MS = 6 * 60 * 60 * 1_000;
@@ -86,7 +87,7 @@ const closedOutcome = (supported, reasonCode) => Object.freeze({ supported, reas
 
 export async function checkNativeBootstrap({ adapter, realExecutable, platform, dataHome,
   timeoutMs = DEFAULT_TIMEOUT_MS, clock = { now: () => new Date().toISOString() },
-  readVersion = defaultReadVersion }) {
+  readVersion = defaultReadVersion, accVersion }) {
   try {
     if (adapter?.nativeDelivery === undefined || typeof adapter.probeNativeDelivery !== "function") {
       return closedOutcome(false, "native_delivery_unsupported");
@@ -94,8 +95,12 @@ export async function checkNativeBootstrap({ adapter, realExecutable, platform,
     const identity = await executableIdentity(realExecutable);
     const file = cachePathFor(dataHome, adapter.id);
     const now = Date.parse(clock.now());
+    const runtimeVersion = accVersion === undefined
+      ? await ownVersion(import.meta.url) : accVersion;
+    const runtimeVersionKnown = typeof runtimeVersion === "string" && runtimeVersion !== "";
     const cached = await loadCache(file);
     if (cached !== null && cached.adapterId === adapter.id && cached.platform === platform
+      && runtimeVersionKnown && cached.accVersion === runtimeVersion
       && sameIdentity(cached.identity, identity) && Date.parse(cached.expiresAt) > now) {
       return closedOutcome(cached.supported, cached.reasonCode);
     }
@@ -131,6 +136,7 @@ export async function checkNativeBootstrap({ adapter, realExecutable, platform,
     // Never command output, never a message body.
     await saveCache(file, {
       schemaVersion: BOOTSTRAP_CACHE_SCHEMA, adapterId: adapter.id, platform, identity,
+      accVersion: runtimeVersionKnown ? runtimeVersion : null,
       clientVersion, supported, reasonCode: outcomeReason,
       protocolContract: supported ? eligibility.protocolContract : null,
       modes: supported ? [...eligibility.modes] : [],

package/node_modules/@agents-can-communicate/installer/src/detect.mjs

@@ -66,7 +66,7 @@ async function detectNative(adapter, entry, { context, platform, probeTimeoutMs,
     const facts = { realExecutable, probe: null, eligibility: null };
     try {
       facts.probe = await withTimeout(Promise.resolve(adapter.probeNativeDelivery({
-        realExecutable, timeoutMs: probeTimeoutMs })), probeTimeoutMs,
+        realExecutable, timeoutMs: probeTimeoutMs, env: context?.env })), probeTimeoutMs,
       `${adapter.id} native probe`);
     } catch {
       facts.probe = null;

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

@@ -12,3 +12,4 @@ export { BLOCK_BEGIN, BLOCK_END, SHIM_MARKER, SHIM_POLICIES, SUPPORTED_SHELLS,
   shellLiteral, uninstallShellBootstrap, validateShimEntry } from "./shell-bootstrap.mjs";
 export { LIVE_POLICIES, describeActivation, describeDeactivation, livePolicyOf, rcFileFor,
   resolveExecutable, shellOf, shimDirFor } from "./native-activation.mjs";
+export { readInstalledLivePolicy } from "./live-policy.mjs";

package/node_modules/@agents-can-communicate/installer/src/live-policy.mjs

@@ -0,0 +1,21 @@
+import { loadOwnership } from "./ownership.mjs";
+
+export const LIVE_POLICIES = Object.freeze(["off", "actionable", "all"]);
+
+export const livePolicyOf = install => {
+  if (Object.hasOwn(install ?? {}, "deliveryPolicy")) {
+    return LIVE_POLICIES.includes(install.deliveryPolicy) ? install.deliveryPolicy : "off";
+  }
+  return LIVE_POLICIES.includes(install?.nativeActivation?.livePolicy)
+    ? install.nativeActivation.livePolicy : "off";
+};
+
+export async function readInstalledLivePolicy({ dataHome, adapterId }) {
+  try {
+    const record = await loadOwnership({ dataHome });
+    const install = record.installs.find(entry => entry.adapterId === adapterId);
+    return livePolicyOf(install);
+  } catch {
+    return "off";
+  }
+}