agents-can-communicate 0.8.4 → 0.9.0

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

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/core",
-  "version": "0.8.4",
+  "version": "0.9.0",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/core/src/delivery-bindings.mjs

@@ -91,6 +91,13 @@ export function createDeliveryBindingService(ports, sessions) {
   async function clearDeliveryBinding(input) {
     const { sessionId, generation } = input;
     const endpointScoped = Object.hasOwn(input, "opaqueEndpointRef");
+    // Every hook clears when live delivery is not running, and on Windows that
+    // is every hook. Absent, or retired for this generation, is a state the
+    // update below leaves exactly as it is, so it is read first without the
+    // writer lock; a record read this way is as current as one read under it.
+    const seen = await store.ephemeral.get("deliveryBinding", sessionId);
+    if (seen === null || seen === undefined) return;
+    if (seen.generation === generation && seen.retiredAt !== null && seen.retiredAt !== undefined) return;
     await store.ephemeral.update("deliveryBinding", sessionId, async current => {
       if (current === null || current === undefined) return null;
       if (current.generation !== generation) throw conflict(sessionId);

package/node_modules/@agents-can-communicate/core/src/materialisation.mjs

@@ -21,9 +21,19 @@ export async function isMaterialised(store, workspaceId) {
   return (await store.snapshot(workspaceId, { kinds: ["workspace"] })).workspace !== null;
 }
 
-export async function materialise({ store, clock, ids }, { workspaceId, descriptor, reason }) {
+/**
+ * `opening` is a second live session that opens here, in the transaction that
+ * materialises, instead of first writing an ephemeral copy of itself to be
+ * copied and retired a moment later. It opens only while the session it joins
+ * is still live under the lock; otherwise it would be a lone session, which
+ * leaves no durable trace, and nothing is written: the result is false and the
+ * caller opens it ephemerally.
+ */
+export async function materialise({ store, clock, ids },
+  { workspaceId, descriptor, reason, opening = null }) {
   const now = clock.now();
   const staged = [];
+  let joined = true;
 
   await store.transaction(async tx => {
     // Ephemeral writers use this same mutex. Reading before taking it could
@@ -31,6 +41,13 @@ export async function materialise({ store, clock, ids }, { workspaceId, descript
     for (const entry of EPHEMERAL_KINDS) {
       staged.push({ ...entry, records: await store.ephemeral.list(entry.kind) });
     }
+    if (opening !== null && tx.get("workspace", workspaceId) === null
+      && !staged.find(entry => entry.kind === "session").records.some(record =>
+        record.state === "open" && record.sessionId !== opening.session.sessionId)) {
+      joined = false;
+      staged.length = 0;
+      return;
+    }
     const actorSessionId = staged.find(entry => entry.kind === "session")?.records.at(-1)?.sessionId
       ?? "session_bootstrap";
     // Asked again inside the lock. `ensureMaterialised` asks before taking it,
@@ -53,8 +70,14 @@ export async function materialise({ store, clock, ids }, { workspaceId, descript
         payload: { reason } });
     }
 
+    // The opening session's own ephemeral copy - left by a process that died
+    // mid-open - is what the opening replaces, not a session to promote first:
+    // promoting it would record the session opening twice.
+    const own = opening === null ? null : staged.find(entry => entry.kind === "session")
+      .records.find(record => record.sessionId === opening.session.sessionId) ?? null;
     for (const entry of staged) {
       for (const record of entry.records) {
+        if (record === own) continue;
         // Whoever got here first may have promoted this record already, and
         // promoting is a copy: the ephemeral and durable shapes are the same,
         // so the one already there is the one this would write.
@@ -66,11 +89,25 @@ export async function materialise({ store, clock, ids }, { workspaceId, descript
           payload: { sessionId: record.sessionId } });
       }
     }
+
+    if (opening !== null) {
+      const { participant, session } = opening;
+      const current = tx.get("session", session.sessionId) ?? own;
+      opening.assertAvailable(current);
+      if (tx.get("participant", participant.participantId) === null) {
+        tx.put("participant", participant.participantId, participant);
+      }
+      tx.put("session", session.sessionId, session, tx.generationOf("session", session.sessionId));
+      tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"), workspaceId,
+        actorSessionId: session.sessionId, type: "session.opened", occurredAt: now,
+        payload: { replaced: current?.generation ?? null } });
+    }
   // The promoted kinds are named by the loop above, not written literally in
   // the body, so they are derived rather than repeated: a new ephemeral kind
   // added to that list is read here without anyone remembering to say so.
   }, { kinds: ["workspace", ...EPHEMERAL_KINDS.map(entry => entry.kind)] });
 
+  if (!joined) return false;
   // The ephemeral copies are retired only after the durable transaction
   // committed, so a crash in between leaves a recoverable duplicate rather than
   // a hole.
@@ -79,6 +116,7 @@ export async function materialise({ store, clock, ids }, { workspaceId, descript
       await store.ephemeral.delete(entry.kind, record[entry.key]);
     }
   }
+  return true;
 }
 
 export async function ensureMaterialised(ports, { workspaceId, descriptor, reason }) {

package/node_modules/@agents-can-communicate/core/src/session-opening.mjs

@@ -100,6 +100,17 @@ export function createSessionOpener(ports, locate) {
     };
     if (await isMaterialised(store, workspaceId)) return openDurable();
 
+    // Another live session already here makes this the second, which
+    // materialises the workspace: this one opens in that same transaction
+    // rather than as an ephemeral copy to be copied and retired at once. The
+    // look is taken without the lock; materialise asks again under it.
+    const joining = (await store.ephemeral.list("session")).some(item => item.state === "open"
+      && item.sessionId !== sessionId);
+    if (joining && await materialise(ports, { workspaceId, descriptor: input.descriptor,
+      reason: "second_live_session", opening: { participant, session, assertAvailable } })) {
+      return session;
+    }
+
     // Preparing a participant must not rename one that already exists, or
     // recreate an ephemeral copy after promotion has taken ownership.
     await store.ephemeral.update("participant", participant.participantId, async current =>

package/node_modules/@agents-can-communicate/core/src/sessions.mjs

@@ -92,8 +92,14 @@ export function createSessionService(ports) {
     // presence transitions surface through cursor sync. Read and validate under
     // the writer lock, so a pending heartbeat cannot restore an old generation.
     // Promoted copies may await cleanup; their durable record already owns writes.
-    const ephemeral = await store.ephemeral.update("session", sessionId, async current =>
-      current !== null && !await isMaterialised(store, current.workspaceId) ? beat(current) : null);
+    // The update below writes only a lone session's ephemeral record. A session
+    // with none, or in a materialised workspace, is durable - and stays so: a
+    // workspace never returns to ephemeral - so it goes straight to the durable
+    // record rather than taking the writer lock to find nothing.
+    const seen = await store.ephemeral.get("session", sessionId);
+    const ephemeral = seen === null || await isMaterialised(store, seen.workspaceId) ? null
+      : await store.ephemeral.update("session", sessionId, async current =>
+        current !== null && !await isMaterialised(store, current.workspaceId) ? beat(current) : null);
     if (ephemeral !== null) return ephemeral;
     return store.transaction(tx => {
       const beaten = beat(tx.get("session", sessionId));

package/node_modules/@agents-can-communicate/delivery-router/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/delivery-router",
-  "version": "0.8.4",
+  "version": "0.9.0",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/delivery-router/src/native-reason.mjs

@@ -1,7 +1,9 @@
 import { listSessionBindings, loadNativeAttempt } from "@agents-can-communicate/adapter-sdk";
 
 /**
- * Why a session has no live transport, as its own last native attempt said.
+ * Why a session has no live transport, as its own last native attempt said:
+ * `{ reasonCode, launchOption? }`, the option being the client launch option
+ * that attempt named as the cause.
  *
  * The same record `acc doctor` reads, found through the hook-owner file that
  * names this exact session generation. Null when none says: an attempt that
@@ -14,5 +16,7 @@ export async function lastNativeReason({ runtimeDir, sessionId, generation }) {
   if (owners.length !== 1) return null;
   const attempt = await loadNativeAttempt({ runtimeDir,
     harnessSessionId: owners[0].harnessSessionId, accSessionId: sessionId, generation });
-  return attempt !== null && attempt.state !== "active" ? attempt.reasonCode : null;
+  if (attempt === null || attempt.state === "active") return null;
+  return { reasonCode: attempt.reasonCode,
+    ...(attempt.launchOption ? { launchOption: attempt.launchOption } : {}) };
 }

package/node_modules/@agents-can-communicate/delivery-router/src/router.mjs

@@ -1,4 +1,5 @@
-import { NATIVE_REASON_CODES, evaluateVersionContract } from "@agents-can-communicate/adapter-sdk";
+import { NATIVE_REASON_CODES, evaluateVersionContract, isLaunchOption }
+  from "@agents-can-communicate/adapter-sdk";
 
 import { lastNativeReason } from "./native-reason.mjs";
 import { refreshExpiredBinding } from "./refresh-binding.mjs";
@@ -51,13 +52,16 @@ export function createDeliveryRouter({ service, adapters, clock, readLivePolicy,
   const registry = adaptersById(adapters);
 
   // A session that bound no live transport may have said why: the reason its
-  // own last native attempt recorded, from the closed vocabulary only.
+  // own last native attempt recorded, from the closed vocabulary only, and the
+  // client launch option behind it when the attempt named one.
   async function withoutLiveTransport(participantId, target) {
-    const reason = await Promise.resolve()
+    const found = await Promise.resolve()
       .then(() => readNativeReason({ sessionId: target.sessionId, generation: target.generation }))
       .catch(() => null);
-    return { ...durable(participantId, "no_live_transport"),
-      ...(NATIVE_REASON_CODES.includes(reason) ? { nativeReasonCode: reason } : {}) };
+    const reason = found?.reasonCode;
+    if (!NATIVE_REASON_CODES.includes(reason)) return durable(participantId, "no_live_transport");
+    return { ...durable(participantId, "no_live_transport"), nativeReasonCode: reason,
+      ...(isLaunchOption(found.launchOption) ? { nativeLaunchOption: found.launchOption } : {}) };
   }
 
   // Read at offer time, not from the binding: consent withdrawn after a session

package/node_modules/@agents-can-communicate/hook-runner/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/hook-runner",
-  "version": "0.8.4",
+  "version": "0.9.0",
   "private": true,
   "type": "module",
   "exports": {

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

@@ -1,4 +1,4 @@
-import path from "node:path";
+import { splitWindowsCommandLine } from "@agents-can-communicate/adapter-sdk";
 
 // Deep enough for a client that wraps its hook in a shell and a launcher, short
 // enough that a table which disagrees with itself cannot spin.
@@ -8,11 +8,35 @@ const MAX_HOPS = 16;
 // interpreter. Gemini CLI is one, measured on 0.60.0. For these, the script the
 // interpreter was given names the client.
 const SCRIPT_HOSTS = new Set(["node"]);
+// What scriptsOf reports for a script inside the client's own package.
+const CLIENT_PACKAGE = Symbol("client package");
 const SCRIPT_EXTENSION = /\.[mc]?js$/;
 
+// Either separator: `ps` names POSIX paths, Win32_Process names Windows ones,
+// and the host running the walk may be either.
+const basename = value => value.split(/[\\/]/).at(-1);
+
+/** An image name as the client's command: Windows adds `.exe` in any case. */
+function imageName(comm) {
+  const name = basename(comm);
+  return /\.exe$/i.test(name) ? name.slice(0, -4).toLowerCase() : name;
+}
+
+/** The words of a command line: Windows quotes paths with spaces. */
+const wordsOf = entry => (/\.exe$/i.test(entry.comm) ? splitWindowsCommandLine(entry.args)
+  : entry.args.trim().split(/\s+/));
+
 /** What the script a script host runs could be called, without extensions. */
-function scriptsOf(entry) {
-  if (!SCRIPT_HOSTS.has(path.basename(entry.comm)) || typeof entry.args !== "string") return [];
+function scriptsOf(entry, clientPackage) {
+  if (!SCRIPT_HOSTS.has(imageName(entry.comm)) || typeof entry.args !== "string") return [];
+  if (/\.exe$/i.test(entry.comm)) {
+    // Windows: the client is node.exe running its package's entry file, whose
+    // own name (`index.js`) says nothing; the package directory does.
+    const script = wordsOf(entry).slice(1).find(word => !word.startsWith("-"));
+    const inPackage = typeof clientPackage === "string" && typeof script === "string"
+      && script.replaceAll("\\", "/").includes(`/node_modules/${clientPackage}/`);
+    return inPackage ? [CLIENT_PACKAGE] : [];
+  }
   // `args` starts with the interpreter as it was invoked, which is the comm
   // itself on macOS; past it, the first word that is no option is the script -
   // unless an option written without `=` came right before it, since that word
@@ -26,7 +50,7 @@ function scriptsOf(entry) {
   for (const word of rest.trim().split(/\s+/)) {
     if (word === "") continue;
     if (word.startsWith("-")) { afterBareOption = !word.includes("="); continue; }
-    candidates.push(path.basename(word).replace(SCRIPT_EXTENSION, ""));
+    candidates.push(basename(word).replace(SCRIPT_EXTENSION, ""));
     if (!afterBareOption) break;
     afterBareOption = false;
   }
@@ -44,16 +68,51 @@ function scriptsOf(entry) {
  *
  * Null is a first-class answer: it means judge this session by age alone.
  */
-export function resolveClientPid({ table, from, command, maxHops = MAX_HOPS }) {
+export function resolveClientPid({ table, from, command, clientPackage, maxHops = MAX_HOPS }) {
+  return resolveClient({ table, from, command, clientPackage, maxHops })?.pid ?? null;
+}
+
+// What an adapter's identifyClientProcess said about one ancestor, or null.
+// It reads a vendor's command line, so a throw is a "no", never a failed hook.
+function recognised(identify, entry) {
+  if (typeof identify !== "function") return null;
+  try {
+    const answer = identify({ comm: entry.comm, args: typeof entry.args === "string" ? entry.args : "" });
+    return answer !== null && typeof answer === "object" ? answer : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The client this hook runs under: its pid, its process-table entry, and what
+ * the adapter recognised it as - another product it serves, and that
+ * product's version when the process names it. Null when nobody knows.
+ *
+ * At each ancestor the adapter's own identifier is asked first; the declared
+ * command still matches whatever it does not recognise. Antigravity 2.0 runs
+ * hooks under a language server that names its version on its command line,
+ * where Antigravity CLI runs them under `agy`.
+ */
+export function resolveClient({ table, from, command, clientPackage, identify,
+  maxHops = MAX_HOPS }) {
   const seen = new Set();
   let current = from;
   for (let hop = 0; hop < maxHops; hop += 1) {
     const entry = table.get(current);
     if (entry === undefined || seen.has(current)) return null;
     seen.add(current);
+    const product = recognised(identify, entry);
+    if (product !== null) {
+      return { pid: current, entry, certificationName: product.certificationName,
+        version: product.version };
+    }
     // `ps` reports some entries bare (`claude`) and some with a path
     // (`/bin/zsh`), so the comparison has to be on the basename.
-    if (path.basename(entry.comm) === command || scriptsOf(entry).includes(command)) return current;
+    if (imageName(entry.comm) === command
+      || scriptsOf(entry, clientPackage).some(name => name === command || name === CLIENT_PACKAGE)) {
+      return { pid: current, entry, certificationName: undefined, version: undefined };
+    }
     if (entry.ppid === current || entry.ppid <= 1) return null;
     current = entry.ppid;
   }

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

@@ -1,4 +1,8 @@
 import { execFile } from "node:child_process";
+import { readFile as readText } from "node:fs/promises";
+import path from "node:path";
+
+import { resolveExecutable, runExecutable } from "@agents-can-communicate/adapter-sdk";
 
 const VERSION = /(?:^|[^0-9A-Za-z])v?(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)(?:\b|$)/;
 
@@ -8,6 +12,7 @@ export function parseClientVersion(output) {
 
 /** Probe the client binary once when its real session starts. */
 export function probeClientVersion(adapter, { timeoutMs = 1_000 } = {}) {
+  if (process.platform === "win32") return probeOnWindows(adapter, timeoutMs);
   return new Promise(resolve => {
     execFile(adapter.client.command, adapter.client.versionArgs ?? ["--version"], {
       timeout: timeoutMs,
@@ -19,3 +24,78 @@ export function probeClientVersion(adapter, { timeoutMs = 1_000 } = {}) {
     });
   });
 }
+
+/**
+ * The executable a client process runs, when `ps` names it by absolute path and
+ * that path is the client's command: a desktop app starts its own build by full
+ * path (Claude.app's claude, ChatGPT.app's codex), and asking that file is
+ * asking the session's own build. Null otherwise, and always on Windows, whose
+ * process names carry no path.
+ */
+export function ownExecutable(entry, command) {
+  if (process.platform === "win32" || typeof entry?.comm !== "string") return null;
+  return path.isAbsolute(entry.comm) && path.basename(entry.comm) === command ? entry.comm : null;
+}
+
+/** That executable's `--version`, parsed like the PATH probe's; null on any failure. */
+export function probeExecutableVersion(file, versionArgs = ["--version"], { timeoutMs = 1_000 } = {}) {
+  return new Promise(resolve => {
+    execFile(file, versionArgs, { timeout: timeoutMs, killSignal: "SIGKILL", windowsHide: true },
+      (error, stdout, stderr) => resolve(error === null ? parseClientVersion(`${stdout}${stderr}`) : null));
+  });
+}
+
+// A package script the npm .cmd shim runs: `"%dp0%\<path inside the prefix>"`.
+const SHIM_TARGET = /"%dp0%\\([^"%]+\.(?:c|m)?js)"/gi;
+const DEPTH = 6;
+
+/**
+ * The version of the package an npm .cmd shim runs, or null when the file is no
+ * such shim. npm writes a .cmd per bin that runs node on the package's script;
+ * the package whose `bin` names that script is the client, and its version is
+ * what the client's --version prints - without starting cmd.exe, node and, for
+ * Codex, the native binary behind it.
+ */
+export async function npmShimVersion(file, { readFile = readText } = {}) {
+  try {
+    const targets = [...String(await readFile(file, "utf8")).matchAll(SHIM_TARGET)];
+    if (targets.length !== 1) return null;
+    const script = path.win32.join(path.win32.dirname(file), targets[0][1]);
+    let directory = path.win32.dirname(script);
+    for (let depth = 0; depth < DEPTH; depth += 1) {
+      const manifest = await readFile(path.win32.join(directory, "package.json"), "utf8")
+        .then(JSON.parse, error => (error.code === "ENOENT" ? null : Promise.reject(error)));
+      if (manifest !== null) {
+        const bins = typeof manifest.bin === "string" ? [manifest.bin] : Object.values(manifest.bin ?? {});
+        const runs = bins.some(bin => typeof bin === "string"
+          && path.win32.resolve(directory, bin).toLowerCase() === path.win32.resolve(script).toLowerCase());
+        return runs ? parseClientVersion(String(manifest.version)) : null;
+      }
+      const parent = path.win32.dirname(directory);
+      if (parent === directory) return null;
+      directory = parent;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// Windows finds `codex.cmd` or `claude.exe`, never the bare name, and starts a
+// .cmd only through cmd.exe.
+async function probeOnWindows(adapter, timeoutMs) {
+  const started = Date.now();
+  try {
+    const file = await resolveExecutable(adapter.client.command);
+    if (file === null) return null;
+    if (/\.cmd$/i.test(file)) {
+      const packaged = await npmShimVersion(file);
+      if (packaged !== null) return packaged;
+    }
+    const { stdout, stderr } = await runExecutable(file, adapter.client.versionArgs ?? ["--version"],
+      { timeout: Math.max(1, timeoutMs - (Date.now() - started)), killSignal: "SIGKILL" });
+    return parseClientVersion(`${stdout}${stderr}`);
+  } catch {
+    return null;
+  }
+}

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

@@ -1,5 +1,5 @@
 import { storeNativeAttempt } from "@agents-can-communicate/adapter-sdk";
-import { readInstalledLivePolicyState } from "@agents-can-communicate/installer";
+import { readInstalledLivePolicyState } from "@agents-can-communicate/installer/hook-support";
 
 import { establishNativeBinding } from "./native-binding.mjs";
 
@@ -45,6 +45,7 @@ export async function bindNative({ adapter, event, hookBinding, clientVersion, p
         reasonCode: result.reasonCode, policy, policySource, policyStatus,
         clientProcess: Number.isInteger(hookBinding.clientPid) && hookBinding.clientPid > 0
           ? "identified" : "unknown",
+        ...(result.launchOption === undefined ? {} : { launchOption: result.launchOption }),
       } }).catch(() => {});
   }
   return result;
@@ -57,6 +58,7 @@ function asHint(value) {
   if (typeof value === "string") return { line: value, release: async () => {} };
   if (value !== null && typeof value === "object" && typeof value.line === "string") {
     return { line: value.line,
+      ...(usableHint(value.userMessage) ? { userMessage: value.userMessage } : {}),
       release: typeof value.release === "function" ? value.release : async () => {} };
   }
   if (value !== null && typeof value === "object" && typeof value.release === "function") {
@@ -66,7 +68,8 @@ function asHint(value) {
 }
 
 function usableHint(line) {
-  return line !== "" && !/[\r\n]/.test(line) && Buffer.byteLength(line, "utf8") <= HINT_MAX_BYTES;
+  return typeof line === "string" && line !== "" && !/[\r\n]/.test(line)
+    && Buffer.byteLength(line, "utf8") <= HINT_MAX_BYTES;
 }
 
 // An adapter may release with a synchronous function. Calling `.catch` on its
@@ -91,6 +94,8 @@ export function callRelease(release) {
  * A string has nothing reserved. `{ line, release }` has reserved an ask; this
  * function calls `release` when it drops the line, including when the adapter
  * answers after the budget. The caller releases a line it does not deliver.
+ * `{ line, userMessage }` also asks for a line the user sees and the model
+ * does not, held to the same bound; one that does not fit is dropped alone.
  */
 export async function nativeActivationHintFor({ adapter, event, nativeBinding, binding, context,
   paths, deadline }) {

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

@@ -37,8 +37,11 @@ function discardEndpoint(adapter, handshake, runtimeDir) {
 export async function establishNativeBinding({ adapter, event, hookBinding, clientVersion,
   platform, livePolicy, service, runtimeDir, clock, env,
   timeoutMs = DEFAULT_TIMEOUT_MS, heartbeatCadenceMs = DEFAULT_CADENCE_MS }) {
-  const outcome = (state, reasonCode, modes = []) =>
-    Object.freeze({ state, reasonCode, modes: Object.freeze([...modes]) });
+  // A refusal may name the client launch option behind it; see
+  // validateNativeHandshake, which admits only a bare option token.
+  const outcome = (state, reasonCode, modes = [], launchOption = null) =>
+    Object.freeze({ state, reasonCode, modes: Object.freeze([...modes]),
+      ...(launchOption === null ? {} : { launchOption }) });
   const sessionId = hookBinding?.accSessionId;
   const generation = hookBinding?.generation;
   if (typeof sessionId !== "string" || typeof generation !== "string") return outcome("off", null);
@@ -80,7 +83,7 @@ export async function establishNativeBinding({ adapter, event, hookBinding, clie
     if (!verdict.ok) {
       await discardEndpoint(adapter, handshake, runtimeDir);
       return outcome(STATIC_REASONS.has(verdict.reasonCode) ? "unsupported" : "degraded",
-        verdict.reasonCode);
+        verdict.reasonCode, [], verdict.launchOption ?? null);
     }
     const now = Date.parse(clock.now());
     const lease = Date.parse(verdict.leaseUntil);

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

@@ -1,11 +1,39 @@
-import { assertPortableId } from "@agents-can-communicate/protocol";
+import { AccError, EXIT, assertPortableId } from "@agents-can-communicate/protocol";
 
-const shellQuote = value => `'${value.replaceAll("'", "'\\''")}'`;
+const posixQuote = value => `'${value.replaceAll("'", "'\\''")}'`;
+// The model appends the header in whatever shell its client gives it, and on
+// Windows that can be cmd.exe, PowerShell or Git Bash. Double quotes are the one
+// quoting all three read alike, for a value with none of what one of them acts
+// on inside double quotes: a double quote - PowerShell also ends a string at
+// U+201C to U+201E, which NTFS allows in names - $ and a backtick, which
+// PowerShell and bash expand, and %, which cmd expands. Single quotes are no
+// answer: cmd takes them as part of the path. Such a value is refused rather
+// than handed to a model that would read it as something else.
+const DOUBLE_QUOTE_BREAKERS = /["\u201C-\u201E$`%]/;
+const windowsQuote = value => {
+  if (!DOUBLE_QUOTE_BREAKERS.test(value)) return `"${value}"`;
+  throw new AccError(EXIT.USAGE, `${value} has a double quote, $, \` or % in it, which no quoting `
+    + "reads alike in cmd, PowerShell and Git Bash, and ACC's hooks will not hand the model a "
+    + "command line it would read differently; rename the directory",
+  { value, reasonCode: "workspace_path_unquotable" });
+};
 
-export const ownerHeader = (binding, cwd, workspaceRef) => "ACC CLI (append): --session "
-  + assertPortableId(binding.accSessionId, "sessionId") + " --generation "
-  + assertPortableId(binding.generation, "generation") + " --cwd " + shellQuote(cwd)
-  + (workspaceRef === undefined ? "" : " --workspace " + shellQuote(workspaceRef));
+// Before anything opens: a session that attached and could then never be told
+// its CLI arguments would look live to its peers, and every one of its turns
+// would fail before their messages reached it.
+export function assertOwnerQuotable(cwd, workspaceRef, platform = process.platform) {
+  if (platform !== "win32") return;
+  windowsQuote(cwd);
+  if (workspaceRef !== undefined) windowsQuote(workspaceRef);
+}
+
+export const ownerHeader = (binding, cwd, workspaceRef, platform = process.platform) => {
+  const quote = platform === "win32" ? windowsQuote : posixQuote;
+  return "ACC CLI (append): --session "
+    + assertPortableId(binding.accSessionId, "sessionId") + " --generation "
+    + assertPortableId(binding.generation, "generation") + " --cwd " + quote(cwd)
+    + (workspaceRef === undefined ? "" : " --workspace " + quote(workspaceRef));
+};
 
 export function ownerOnlyOutcome(inject, owner, budgetBytes) {
   if (Buffer.byteLength(owner, "utf8") > budgetBytes) {

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

@@ -1,50 +1,3 @@
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-
-const run = promisify(execFile);
-
-// A hook runs in front of someone's turn. Reading the table is worth a few
-// hundred milliseconds once per session and nothing at all if it is slow.
-const DEFAULT_TIMEOUT_MS = 1_000;
-
-const LINE = /^\s*(\d+)\s+(\d+)\s+(.+?)\s*$/;
-// A pid, then the whole rest of the line: a command line has spaces anywhere.
-const ARGS_LINE = /^\s*(\d+)\s+(.+?)\s*$/;
-// Command lines are long; measured at 231 KB for 1,137 processes on a desktop
-// Mac, a quarter of execFile's default buffer.
-const ARGS_BUFFER = 16 * 1024 * 1024;
-
-/**
- * Every process on this machine, as pid -> parent, executable and, when it
- * could be read, command line.
- *
- * Returns an empty map rather than throwing when the platform has no `ps`
- * (Windows) or the call fails. An empty table resolves no client, which is the
- * "nobody knows" answer the caller already handles. The command lines are read
- * at the same time and within the same timeout; they only name a client that
- * is a script, so when that read fails every entry keeps what it had before.
- */
-export async function readProcessTable({ run: exec = run,
-  timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
-  const options = { timeout: timeoutMs, killSignal: "SIGKILL" };
-  const [tree, commandLines] = await Promise.all([
-    exec("ps", ["-o", "pid=,ppid=,comm=", "-A"], options).then(({ stdout }) => stdout, () => null),
-    exec("ps", ["-A", "-o", "pid=,args="], { ...options, maxBuffer: ARGS_BUFFER })
-      .then(({ stdout }) => stdout, () => ""),
-  ]);
-  if (typeof tree !== "string") return new Map();
-  const args = new Map();
-  for (const line of String(commandLines).split("\n")) {
-    const match = ARGS_LINE.exec(line);
-    if (match !== null) args.set(Number(match[1]), match[2]);
-  }
-  const table = new Map();
-  for (const line of tree.split("\n")) {
-    const match = LINE.exec(line);
-    if (match === null) continue;
-    const pid = Number(match[1]);
-    table.set(pid, { ppid: Number(match[2]), comm: match[3],
-      ...(args.has(pid) ? { args: args.get(pid) } : {}) });
-  }
-  return table;
-}
+// The table lives in the adapter SDK, which adapters that read a process's
+// arguments share with the hook runner; this keeps the runner's own name.
+export { readProcessTable } from "@agents-can-communicate/adapter-sdk";