agents-can-communicate 0.3.0 → 0.4.0

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

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 
-import { AccError, EXIT } from "@agents-can-communicate/protocol";
+import { AccError, EXIT, assertPortableId } from "@agents-can-communicate/protocol";
 
 const SCHEMA_VERSION = 1;
 
@@ -23,11 +23,32 @@ const fileFor = (runtimeDir, harnessSessionId) => path.join(runtimeDir, "binding
  */
 const isPid = value => Number.isInteger(value) && value > 0;
 
+function assertIdentity(record, harnessSessionId) {
+  if (record?.schemaVersion !== SCHEMA_VERSION) {
+    throw new AccError(EXIT.DATA, "unknown session binding schemaVersion",
+      { schemaVersion: record?.schemaVersion });
+  }
+  assertPortableId(record.accSessionId, "binding session id");
+  assertPortableId(record.generation, "binding generation");
+  if (typeof record.harnessSessionId !== "string" || record.harnessSessionId === ""
+    || harnessSessionId !== undefined && record.harnessSessionId !== harnessSessionId) {
+    throw new AccError(EXIT.DATA, "session binding names a different or invalid harness session", {});
+  }
+}
+
+function assertBindingDeadline(deadlineAt) {
+  if (deadlineAt !== undefined && Date.now() >= deadlineAt) {
+    throw new AccError(EXIT.CONFLICT, "hook deadline expired before binding publication", {});
+  }
+}
+
 export async function storeSessionBinding({ runtimeDir, harnessSessionId, accSessionId,
-  generation, clientVersion, platform, clientPid }) {
+  generation, clientVersion, platform, clientPid, deadlineAt }) {
+  assertBindingDeadline(deadlineAt);
   const file = fileFor(runtimeDir, harnessSessionId);
-  await mkdir(path.dirname(file), { recursive: true });
   const record = { schemaVersion: SCHEMA_VERSION, harnessSessionId, accSessionId, generation };
+  assertIdentity(record);
+  await mkdir(path.dirname(file), { recursive: true });
   if (typeof clientVersion === "string" && clientVersion !== "") record.clientVersion = clientVersion;
   if (typeof platform === "string" && platform !== "") record.platform = platform;
   // The vendor process this session runs in, resolved once at SessionStart.
@@ -45,6 +66,7 @@ export async function storeSessionBinding({ runtimeDir, harnessSessionId, accSes
   await writeFile(temporary, `${JSON.stringify(record, null, 2)}\n`, "utf8");
   // Replace rather than append: re-attaching supersedes the old generation, and
   // two live bindings for one harness session would be worse than none.
+  assertBindingDeadline(deadlineAt);
   await rename(temporary, file);
 }
 
@@ -66,10 +88,7 @@ export async function loadSessionBinding({ runtimeDir, harnessSessionId }) {
     throw new AccError(EXIT.DATA, "session binding is not valid JSON",
       { file, cause: error.message });
   }
-  if (record?.schemaVersion !== SCHEMA_VERSION) {
-    throw new AccError(EXIT.DATA, "unknown session binding schemaVersion",
-      { file, schemaVersion: record?.schemaVersion });
-  }
+  assertIdentity(record, harnessSessionId);
   const binding = { accSessionId: record.accSessionId, generation: record.generation };
   if (typeof record.clientVersion === "string") binding.clientVersion = record.clientVersion;
   if (typeof record.platform === "string") binding.platform = record.platform;
@@ -77,7 +96,8 @@ export async function loadSessionBinding({ runtimeDir, harnessSessionId }) {
   return binding;
 }
 
-export async function clearSessionBinding({ runtimeDir, harnessSessionId }) {
+export async function clearSessionBinding({ runtimeDir, harnessSessionId, deadlineAt }) {
+  assertBindingDeadline(deadlineAt);
   await rm(fileFor(runtimeDir, harnessSessionId), { force: true });
 }
 
@@ -107,7 +127,7 @@ export async function listSessionBindings({ runtimeDir }) {
     if (!name.endsWith(".json")) continue;
     const record = await readFile(path.join(dir, name), "utf8")
       .then(JSON.parse).catch(() => null);
-    if (record?.schemaVersion !== SCHEMA_VERSION) continue;
+    try { assertIdentity(record); } catch { continue; }
     bindings.push({ harnessSessionId: record.harnessSessionId,
       accSessionId: record.accSessionId, generation: record.generation,
       ...(typeof record.clientVersion === "string"

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

@@ -4,8 +4,9 @@ import path from "node:path";
 // Two clients keep configuration ACC must add to in TOML, and ACC ships without
 // dependencies. Parsing and re-emitting the file would mean writing a TOML
 // round-tripper and losing the user's comments and formatting to it. Instead ACC
-// owns a delimited region and never reads the rest: install replaces the region,
-// uninstall deletes it, and everything outside comes back byte for byte.
+// offers a delimited-region default. Clients that relocate comments must pass
+// an ownership-aware cleanup callback; a comment boundary alone cannot establish
+// ownership after the client has rewritten its configuration.
 export const BEGIN = "# >>> agents-can-communicate (managed; edits here are overwritten)";
 export const END = "# <<< agents-can-communicate";
 
@@ -40,17 +41,18 @@ export const tomlString = value =>
 
 /**
  * Replace ACC's region in a TOML file, creating the file if needed.
+ * Clients that rewrite comments must supply their own ownership-aware cleanup.
  *
  * The block goes at the end because a table header there closes whatever table
  * preceded it: appended anywhere else, the user's last section would swallow
  * ACC's keys.
  */
-export async function writeTomlBlock(file, body) {
+export async function writeTomlBlock(file, body, strip = stripBlock) {
   const existing = await readFile(file, "utf8").catch(error => {
     if (error.code === "ENOENT") return "";
     throw error;
   });
-  const withoutOurs = stripBlock(existing);
+  const withoutOurs = strip(existing);
   const separator = withoutOurs === "" || withoutOurs.endsWith("\n") ? "" : "\n";
   await mkdir(path.dirname(file), { recursive: true });
   await writeFile(file, `${withoutOurs}${separator}${renderBlock(body)}\n`);
@@ -58,13 +60,13 @@ export async function writeTomlBlock(file, body) {
 }
 
 /** Remove ACC's region, reporting whether anything was there. */
-export async function removeTomlBlock(file) {
+export async function removeTomlBlock(file, strip = stripBlock) {
   const existing = await readFile(file, "utf8").catch(error => {
     if (error.code === "ENOENT") return null;
     throw error;
   });
   if (existing === null) return false;
-  const stripped = stripBlock(existing);
+  const stripped = strip(existing);
   if (stripped === existing) return false;
   await writeFile(file, stripped);
   return true;

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

@@ -1,10 +1,12 @@
 {
   "name": "@agents-can-communicate/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "private": true,
   "type": "module",
   "exports": {
-    ".": "./src/index.mjs"
+    ".": "./src/index.mjs",
+    "./managed-entry": "./src/managed-runtime/entry.mjs",
+    "./managed-worker": "./src/managed-runtime/worker.mjs"
   },
   "files": [
     "src/"

package/node_modules/@agents-can-communicate/cli/src/args.mjs

@@ -1,18 +1,19 @@
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
 
-// Commands the model is offered stay few and high level; attach, heartbeat, and
-// detach exist for adapters and are deliberately not advertised as model tools.
+// Native adapters manage session lifecycle automatically. Manual CLI sessions
+// use attach, heartbeat, and detach; both paths are described in command help.
 //
 // `--session` and `--generation` are optional on every agent-facing command:
-// the CLI works out which session is calling it (see session-owner.mjs). They
-// stay accepted because an adapter, a script, or an agent holding a session id
-// from `acc status --json` has a reason to be explicit. They remain required on
-// attach, heartbeat and detach, which are the adapter's own lifecycle calls.
+// an operator may instead configure the explicit owner pair in the environment
+// (see session-owner.mjs). Public status/sync also work without an owner pair.
+// A public session id alone proves nothing. Heartbeat and detach always require
+// both arguments; attach creates and returns the pair.
 export const COMMANDS = Object.freeze({
   attach: { required: ["participant"], optional: ["harness", "cadence", "parent", "session"] },
   heartbeat: { required: ["session", "generation"], optional: [] },
   detach: { required: ["session", "generation"], optional: [] },
-  sync: { required: [], optional: ["session", "cursor", "limit", "scope"] },
+  sync: { required: [], optional: ["session", "generation", "cursor", "limit", "scope",
+    "message", "type"], flags: ["current"] },
   work: { required: [], optional: ["session", "generation", "summary", "mode",
     "state"], repeated: ["hint"], flags: ["clear"] },
   claim: { required: ["resource"],
@@ -25,8 +26,8 @@ export const COMMANDS = Object.freeze({
     optional: ["claim", "resource", "session", "generation", "authority", "reason"] },
   message: { required: ["subject", "body"],
     optional: ["session", "generation", "type", "obligation", "client-message-id"],
-    repeated: ["to"] },
-  inbox: { required: [], optional: ["session", "generation", "message"] },
+    repeated: ["to", "supersedes", "withdraws"] },
+  inbox: { required: [], optional: ["session", "generation", "message", "cursor", "limit"] },
   reply: { required: ["message", "body"],
     optional: ["session", "generation", "subject", "client-message-id"] },
   // Asking another agent to do something as a message with a reply obligation.
@@ -36,13 +37,13 @@ export const COMMANDS = Object.freeze({
   finish: { required: ["goal"], optional: ["session", "generation", "status", "to",
     "client-message-id"],
     repeated: ["completed", "remaining", "blocker"] },
-  status: { required: [], optional: ["participant"], flags: ["all"] },
+  status: { required: [], optional: ["session", "generation", "participant"], flags: ["all"] },
   doctor: { required: [], optional: ["home"], flags: ["repair"] },
   // The one command with a subcommand. Kept as an explicit list rather than a
   // free positional: `acc config delete` should fail at the parser, not deep
   // inside a handler that has already decided what to do.
-  config: { required: [], optional: [], flags: ["yes", "force"],
-    subcommands: ["init", "validate"] },
+  config: { required: [], optional: [], subcommands: ["init", "validate"],
+    subcommandOptions: { init: { flags: ["yes", "force"] }, validate: { flags: [] } } },
   // No `--yes`: neither of these ever asked, so the flag agreed to nothing. It
   // was accepted and read by nobody, which is a promise that a confirmation
   // exists to be skipped.
@@ -57,7 +58,7 @@ export const COMMANDS = Object.freeze({
   uninstall: { required: [], optional: ["home"], repeated: ["adapter"], flags: ["dry-run"] },
   // Asking npm whether there is a newer ACC. The one command that touches the
   // network, and never on the hook path.
-  update: { required: [], optional: [], flags: ["apply"] },
+  update: { required: [], optional: ["auto", "pin"], flags: ["check", "apply"] },
   // The two things a person types first after installing from a registry. The
   // CLI answered neither: `acc --version` and `acc --help` were both "unknown
   // command", and `acc` on its own asked for a command without naming one.
@@ -65,10 +66,8 @@ export const COMMANDS = Object.freeze({
   version: { required: [], optional: [] },
 });
 
-// Spelled as the commands they mean, and only in first position. A message body
-// legitimately begins with "--" - exchanging diffs is the point of this tool -
-// so reading them anywhere in the argv would make `acc message --body "--help"`
-// print the help instead of sending it.
+// Leading aliases select a command. Command-local help is recognized while
+// consuming options below, never by searching inside their values.
 const ALIASES = Object.freeze({ "--help": "help", "-h": "help",
   "--version": "version", "-v": "version", "-V": "version" });
 
@@ -80,26 +79,39 @@ function usage(message, details = {}) {
 
 const camel = name => name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
 
+export function commandSpec(name, subcommand) {
+  const spec = COMMANDS[name];
+  return { ...spec, ...spec.subcommandOptions?.[subcommand] };
+}
+
 export function parseArgs(argv) {
   if (!Array.isArray(argv) || argv.length === 0) {
     usage("a command is required - `acc help` lists them");
   }
   const [first, ...rest] = argv;
-  const command = ALIASES[first] ?? first;
-  const spec = COMMANDS[command];
-  if (spec === undefined) {
+  let command = Object.hasOwn(ALIASES, first) ? ALIASES[first] : first;
+  let helpRequested = false;
+  if (command === "help" && rest[0] !== undefined && !rest[0].startsWith("-")) {
+    command = rest.shift();
+    helpRequested = true;
+  }
+  let spec = COMMANDS[command];
+  if (!Object.hasOwn(COMMANDS, command)) {
     usage(`unknown command: ${command} - \`acc help\` lists them`, { command });
   }
 
   let tokens = rest;
   let subcommand;
   if (spec.subcommands !== undefined) {
-    [subcommand, ...tokens] = rest;
-    if (subcommand === undefined || !spec.subcommands.includes(subcommand)) {
+    if (rest[0] !== undefined && !rest[0].startsWith("-")) {
+      [subcommand, ...tokens] = rest;
+    }
+    if (subcommand !== undefined && !spec.subcommands.includes(subcommand)) {
       usage(`${command} requires one of: ${spec.subcommands.join(", ")}`,
         { command, subcommand: subcommand ?? null });
     }
   }
+  spec = commandSpec(command, subcommand);
 
   const repeated = new Set(spec.repeated ?? []);
   const flags = new Set([...(spec.flags ?? []), "json"]);
@@ -117,6 +129,12 @@ export function parseArgs(argv) {
 
   for (let index = 0; index < tokens.length; index += 1) {
     const token = tokens[index];
+    // A preceding value-taking option has already consumed its value. In
+    // particular, `--body --help` still sends the literal text "--help".
+    if (token === "--help" || token === "-h") {
+      helpRequested = true;
+      continue;
+    }
     if (!token.startsWith("--") || token.length === 2) usage(`unexpected argument: ${token}`);
     const separator = token.indexOf("=");
     const name = separator === -1 ? token.slice(2) : token.slice(2, separator);
@@ -146,6 +164,15 @@ export function parseArgs(argv) {
     else options[key] = value;
   }
 
+  if (helpRequested) {
+    return { command: "help", options: { helpCommand: command,
+      ...(subcommand === undefined ? {} : { subcommand }),
+      ...(options.json === true ? { json: true } : {}) } };
+  }
+  if (spec.subcommands !== undefined && subcommand === undefined) {
+    usage(`${command} requires one of: ${spec.subcommands.join(", ")}`,
+      { command, subcommand: null });
+  }
   for (const name of spec.required ?? []) {
     if (!Object.hasOwn(options, camel(name))) {
       usage(`${command} requires --${name}`, { command, option: name });

package/node_modules/@agents-can-communicate/cli/src/doctor-command.mjs

@@ -10,6 +10,7 @@ import { ALL_ADAPTERS, clientContext, probeTimeout } from "./install-command.mjs
 import { describePresence } from "./main.mjs";
 import { platformPaths } from "./platform-paths.mjs";
 import { noticeUpdate } from "./update-check.mjs";
+import { readControl } from "./managed-runtime/state.mjs";
 import { diagnoseFilesystemStore, repairFilesystemStore }
   from "@agents-can-communicate/storage-filesystem";
 
@@ -229,9 +230,13 @@ export async function runDoctor({ options, context, runtime }) {
   const running = typeof runtime?.version === "function"
     ? await runtime.version().catch(() => null)
     : null;
-  const update = await noticeUpdate({ dataHome, running, env: runtime?.env ?? {},
-    now: Date.parse(clock.now()), get: runtime?.fetch,
-    io: { readFile, writeFile, mkdir } });
+  const manager = runtime?.managerRoot ? await readControl(runtime.managerRoot) : null;
+  const update = manager === null
+    ? await noticeUpdate({ dataHome, running, env: runtime?.env ?? {},
+      now: Date.parse(clock.now()), get: runtime?.fetch, io: { readFile, writeFile, mkdir } })
+    : { checked: false, running, latest: manager.pending?.version ?? null,
+      newer: manager.pending !== null, auto: manager.auto, pin: manager.pin,
+      pending: manager.pending?.version ?? null, phase: manager.phase, notice: manager.notice };
 
   // Before the store is read for anything else. `collectStatus` reads every
   // record, so on the store this command exists to describe it threw first and
@@ -285,7 +290,7 @@ export async function runDoctor({ options, context, runtime }) {
     remediation: [...adapters.flatMap(adapter => adapter.remediation),
       // Said here rather than in its own line of prose, because this list is
       // what a reader acts on and an upgrade is one more thing to run.
-      ...(update.newer ? [`acc update --apply  # ${update.latest} is on npm, `
+      ...(update.newer ? [`acc update  # ${update.latest} is on npm, `
         + `you have ${running}`] : [])],
   };
   const installed = adapters.filter(adapter => adapter.installed).length;
@@ -303,6 +308,8 @@ export async function runDoctor({ options, context, runtime }) {
   // claims that "active" means a model read anything.
   ...adapters.filter(adapter => adapter.present)
     .map(adapter => `  ${adapter.displayName} native delivery: ${describeNative(adapter.nativeDelivery)}`),
+  ...(manager === null ? [] : [`  automatic updates ${manager.auto ? "on" : "off"}; ACC ${manager.active.version}`
+    + (manager.pin ? `; pinned to ${manager.pin}` : ""), ...(manager.notice ? [`  ${manager.notice}`] : [])]),
   ...data.remediation.map(line => `  ${line}`),
   // `0 of 4` is a true line that reads as a broken machine, and on an
   // MCP-only one it would read that way on every run forever. The server needs

package/node_modules/@agents-can-communicate/cli/src/git-probe.mjs

@@ -16,9 +16,15 @@ export function hermeticEnv(env = process.env) {
   return Object.fromEntries(Object.entries(env).filter(([key]) => !key.startsWith("GIT_")));
 }
 
-export function createGitProbe({ run } = {}) {
-  const exec = run ?? (async (cwd, args) =>
-    (await execFileAsync("git", args, { cwd, env: hermeticEnv() })).stdout.trim());
+export function createGitProbe({ run, deadlineAt } = {}) {
+  const exec = async (cwd, args) => {
+    const remaining = deadlineAt === undefined ? 0 : deadlineAt - Date.now();
+    if (deadlineAt !== undefined && remaining <= 0) throw new Error("Git probe deadline expired");
+    return run === undefined
+      ? (await execFileAsync("git", args, { cwd, env: hermeticEnv(), timeout: remaining,
+        killSignal: "SIGKILL" })).stdout.trim()
+      : run(cwd, args);
+  };
 
   return async function gitProbe({ cwd }) {
     const commonDir = await exec(cwd, ["rev-parse", "--path-format=absolute",

package/node_modules/@agents-can-communicate/cli/src/help.mjs

@@ -1,4 +1,10 @@
-import { COMMANDS } from "./args.mjs";
+import { CLAIM_ENFORCEMENTS, CLAIM_MODES, GENERIC_MESSAGE_KINDS, HANDOFF_STATUSES,
+  INTENT_MODES, INTENT_STATES, MESSAGE_KINDS, OBLIGATIONS } from "@agents-can-communicate/protocol";
+import { LIVE_POLICIES } from "@agents-can-communicate/installer";
+
+import { COMMANDS, commandSpec } from "./args.mjs";
+import { ALL_ADAPTERS } from "./install-command.mjs";
+import { needsOwner } from "./session-owner.mjs";
 
 /**
  * What `acc` says to a person who has just installed it.
@@ -7,15 +13,14 @@ import { COMMANDS } from "./args.mjs";
  * is always listed. Only the heading a command sits under and its one line are
  * written here, and the tests prove both cover every command in the table.
  *
- * The required options are deliberately not repeated: the parser already
- * answers `acc claim` with "claim requires --resource", which is the same
- * answer at the moment it is actually needed.
+ * Per-command help also reads the parser's option table, and exposes the
+ * protocol's enum choices before a caller has to attempt a mutation.
  */
 const GROUPS = Object.freeze([
   ["Set up", ["install", "uninstall", "doctor", "config"]],
   ["In a session", ["status", "sync", "work", "claim", "release", "inbox", "reply",
     "ack", "message", "request", "finish"]],
-  ["Driven by adapters, not by people", ["attach", "heartbeat", "detach"]],
+  ["Session lifecycle", ["attach", "heartbeat", "detach"]],
   ["About acc", ["help", "version", "update"]],
 ]);
 
@@ -25,22 +30,22 @@ const SUMMARY = Object.freeze({
   doctor: "clients, versions, install health, and what to run next",
   config: "write or check acc.workspace.json (init | validate)",
   status: "who else is here, what they hold, how protected this workspace is",
-  sync: "what has happened since a cursor; silent while you are alone",
+  sync: "events since a cursor, or bounded message history",
   work: "publish what this session is doing, or --clear when it has stopped",
   claim: "reserve a resource; exit 5 when someone else already holds it",
   release: "give a claim back",
   ack: "answer a message that asked for one, so it stops asking",
   message: "send a typed message to named participants",
-  inbox: "read only unresolved messages addressed to this participant",
+  inbox: "list pending message headers; --message reads one complete message",
   reply: "reply to one message and acknowledge it in the same operation",
   request: "ask another agent to do something in a reply-required message",
   finish: "write the handoff and release what this session held",
-  attach: "open a session; an adapter calls this, not a person",
+  attach: "open a manual session and return its session/generation pair",
   heartbeat: "say the session is still alive",
   detach: "close a session",
-  help: "this list",
+  help: "list commands, or inspect one with acc help <command>",
   version: "print the version that is installed",
-  update: "ask npm whether a newer acc exists; --apply installs it",
+  update: "install a newer acc and refresh clients; --check only reports",
 });
 
 /** The same list `acc help --json` returns, so a tool can read it too. */
@@ -59,6 +64,96 @@ export function describeCommands() {
 const DOCS = "https://github.com/automatis-tools/agents-can-communicate"
   + "/blob/main/docs/CLI.md";
 
+const ADAPTER_IDS = Object.freeze(ALL_ADAPTERS().map(adapter => adapter.id));
+const CHOICES = Object.freeze({
+  work: { mode: INTENT_MODES, state: INTENT_STATES },
+  claim: { mode: CLAIM_MODES, enforcement: CLAIM_ENFORCEMENTS },
+  finish: { status: HANDOFF_STATUSES },
+  message: { type: GENERIC_MESSAGE_KINDS, obligation: OBLIGATIONS },
+  sync: { scope: ["delta", "full", "history"], type: MESSAGE_KINDS },
+  install: { delivery: LIVE_POLICIES, adapter: ADAPTER_IDS },
+  uninstall: { adapter: ADAPTER_IDS },
+});
+
+const NOTES = Object.freeze({
+  attach: ["Native hooks already manage their own session. Attach only for a manual CLI session.",
+    "Keep the returned session and generation together for subsequent calls.",
+    "--cadence is a positive interval in milliseconds."],
+  work: ["Provide --summary unless using --clear. Default mode: edit; default state: active."],
+  claim: ["--lease is in seconds. Default mode: exclusive; default enforcement: advisory.",
+    "For files, use file:src/a.mjs or file:src/**. A claim may conflict with a peer."],
+  release: ["Provide --claim or --resource. Releasing another owner's claim requires human or policy authority."],
+  message: ["Default type: note. question/request require --to and obligation reply; note uses none.",
+    "decision permits none, or acknowledge when addressed. Use reply for answers and finish for handoffs.",
+    "For decisions, repeat --supersedes or --withdraws with 1..16 prior decision IDs; never combine the two.",
+    "Changes inherit target recipients and authors, including offline participants. Any peer may record a change; competing branches remain visible."],
+  inbox: ["Without --message, returns read-only {items, nextCursor} summary pages, newest first.",
+    "Default: 20 items, at most 12000 bytes of formatted page JSON. --limit accepts 1..500.",
+    "Continue with --cursor <nextCursor>; omit it to see new arrivals. Listing never retrieves bodies.",
+    "Replaced decisions leave the pending list without changing receipts; exact inbox and history retain them.",
+    "--message reads one complete addressed message, including acknowledged mail; do not combine with cursor or limit.",
+    "Exact reads return a one-item array. Acknowledged inspection leaves the receipt unchanged."],
+  sync: ["Default delta uses 16-digit event cursors. full adds an unbounded diagnostic snapshot.",
+    "history lists read-only message summaries, newest first: default 20 items, at most 12000 bytes of formatted page JSON.",
+    "With history, --type filters before paging; --cursor takes the complete message ID in nextCursor.",
+    "history --type decision --current lists terminal decisions and withdrawals, including conflicts. Current means no recorded successor, not consensus.",
+    "history --message reads one complete historical message without changing receipts; do not combine with cursor, limit, or type."],
+  reply: ["Returns the outgoing message/delivery plus the original acknowledged receipt."],
+  finish: ["Default status: partial. Records a handoff, releases claims, and closes this ACC session."],
+  config: ["init writes optional workspace configuration; validate only checks it.",
+    "Use acc config <subcommand> --help for its options."],
+  update: ["Run acc update to install the latest release and refresh client integrations.",
+    "Use acc update --check to only report whether a newer release exists.",
+    "Automatic updates are on after acc install; activation waits for active clients and ACC processes.",
+    "--auto on|off changes automatic updates; --pin VERSION holds an exact stable version; --pin none follows stable releases.",
+    "--apply remains accepted as a compatibility alias for acc update."],
+});
+
+const CONFIG_HELP = Object.freeze({
+  init: { summary: "write optional workspace configuration",
+    notes: ["init requires confirmation or --yes. --force bypasses the active-session check; an existing config is never overwritten."] },
+  validate: { summary: "check optional workspace configuration",
+    notes: ["Checks acc.workspace.json in the selected directory without writing it."] },
+});
+
+export function describeCommand(name, subcommand) {
+  const spec = commandSpec(name, subcommand);
+  const detail = name === "config" ? CONFIG_HELP[subcommand] : undefined;
+  return { name, summary: detail?.summary ?? SUMMARY[name],
+    ...(subcommand === undefined ? {} : { subcommand }),
+    required: spec.required ?? [], optional: spec.optional ?? [],
+    repeated: spec.repeated ?? [], flags: spec.flags ?? [],
+    subcommands: spec.subcommands ?? [], choices: CHOICES[name] ?? {},
+    notes: [...(detail?.notes ?? NOTES[name] ?? []), ...(needsOwner(name)
+      ? ["Use your own --session and --generation from the ACC hook or manual attach; never a peer's pair."]
+      : [])] };
+}
+
+export function commandHelpText(command) {
+  const { name, summary, subcommand, subcommands, choices, notes } = command;
+  const suffix = subcommand !== undefined ? ` ${subcommand}`
+    : subcommands.length > 0 ? ` <${subcommands.join("|")}>` : "";
+  const lines = [`acc ${name} - ${summary}`, "", `Usage: acc ${name}${suffix} [options]`, ""];
+  for (const [key, label] of [["required", "Required"], ["optional", "Optional"],
+    ["repeated", "Repeatable"], ["flags", "Flags"]]) {
+    if (command[key].length === 0) continue;
+    lines.push(`${label}:`);
+    for (const option of command[key]) {
+      const value = key === "flags" ? "" : ` <${choices[option]?.join("|") ?? "value"}>`;
+      lines.push(`  --${option}${value}`);
+    }
+    lines.push("");
+  }
+  const globals = ["--json", "--help", "-h"];
+  if (!["install", "uninstall", "update", "help", "version"].includes(name)) {
+    globals.push("--cwd <path>");
+    if (name !== "config" || subcommand !== "validate") globals.push("--workspace <config>");
+  }
+  lines.push(`Global: ${globals.join(", ")}`, "", ...notes,
+    `Full reference: ${DOCS}`);
+  return lines.join("\n");
+}
+
 export function helpText() {
   const width = Math.max(...Object.keys(COMMANDS).map(name => name.length)) + 4;
   const lines = ["acc - coordinate the agent sessions you already opened", ""];
@@ -69,10 +164,10 @@ export function helpText() {
     }
     lines.push("");
   }
-  // A URL rather than a path: only `docs/CAPABILITIES.md` is packed, so a
-  // reference to `docs/CLI.md` would name a file the installed package does not
-  // have. The test alongside holds this to the repository the manifest names.
-  lines.push("Every command takes --json for machine output and --cwd to choose the workspace.",
+  // The longer reference is linked to the repository named in the manifest;
+  // installed command help supplies local syntax without needing that link.
+  lines.push("Every command takes --json for machine output.",
+    "Use acc <command> --help or acc help <command> for options and accepted values.",
     `Full reference: ${DOCS}`);
   return lines.join("\n");
 }