agents-can-communicate 0.6.2 → 0.7.0

package/README.md

@@ -119,7 +119,9 @@ Automatic updates are enabled on first install. Use `acc update --auto off` to d
 [update controls](docs/UPGRADING.md) for details.
 
 MIT-licensed and permanently noncommercial. Try it on one real task and
-[tell us where you still had to carry messages yourself](https://github.com/automatis-tools/agents-can-communicate/issues).
+[tell us how it went](https://github.com/automatis-tools/agents-can-communicate/discussions/categories/show-and-tell),
+including where you still had to carry messages yourself. Bugs belong in
+[issues](https://github.com/automatis-tools/agents-can-communicate/issues).
 
 [Documentation](docs/index.md) ·
 [Contributing](https://github.com/automatis-tools/agents-can-communicate/blob/main/AGENTS.md)

package/bin/entrypoints/hook-output.mjs

@@ -38,6 +38,15 @@ function boundedDiagnostic(label, error) {
   return `${line}\n`;
 }
 
+async function releaseActivation(release) {
+  if (typeof release !== "function") return;
+  try {
+    await release();
+  } catch {
+    // The line was not delivered. Releasing its reservation is not the hook.
+  }
+}
+
 function tryWrite(stream, output) {
   if (output === "") return;
   try {
@@ -62,6 +71,9 @@ export async function completeHookOutput(result,
     await writeOutput(stdout, result.stdout ?? "", { deadlineAt: result.deadlineAt });
   } catch (error) {
     tryWrite(stderr, boundedDiagnostic("stdout write failed", error));
+    // The bytes did not cross, so a reserved activation line is not an ask.
+    // release may return nothing or throw; neither may fail this hook.
+    await releaseActivation(result.releaseActivationAsk);
     return { exitCode: 0, wroteStdout: false, committedOffers: false };
   }
 

package/docs/CAPABILITIES.md

@@ -60,7 +60,7 @@ The limitations belong next to the adapters they affect:
 
 | Adapter | Exact limitation and evidence |
 |---|---|
-| Antigravity CLI | 1.2.7 on darwin-arm64, captured in print mode, and every later release by the forward rule. Only `SessionStart`, `PreInvocation`, `PostInvocation` and `Stop` load; `SessionEnd`, `PreToolUse` and `PostToolUse` are accepted into the config file and silently dropped, so there is no tool guard and no session-end deregistration - a session goes offline by presence age or an explicit `acc finish`. Payloads carry no `hook_event_name`, so each registered command passes its own event name. The end-of-turn `Stop` continuation reaches the model and is a bounded nudge, not a gate: ACC continues a turn at most once and fails open, and the client caps consecutive continuations itself (vendor 1.1.9). `agy agentapi send-message` can wake an idle session - captured - but only with that session's language-server address and CSRF token, which exist in the agent's own shell and in no hook. ACC does not take that token, so live push and reply routing are false. A peer message that arrives while the model writes its last answer is carried by the `Stop` continuation instead. A write that parses can register nothing, so install and doctor read `agy -p "/hooks"` back instead of trusting the file. Live push (1.2.7, darwin-arm64, TUI only, experimental, recorded opt-in) runs through a relay the agent starts once per conversation from its own shell - the only process holding the session endpoint - after ACC's context asks it to; the operator approves that command at the client's permission prompt. An idle session wakes; a busy one sees the message after its running answer, or at the next model invocation when the turn waits on a tool. Print mode and the first session in a folder trusted at that launch get no relay. |
+| Antigravity CLI | 1.2.7 on darwin-arm64, captured in print mode, and every later release by the forward rule. Only `SessionStart`, `PreInvocation`, `PostInvocation` and `Stop` load; `SessionEnd`, `PreToolUse` and `PostToolUse` are accepted into the config file and silently dropped, so there is no tool guard and no session-end deregistration - a session goes offline by presence age or an explicit `acc finish`. Payloads carry no `hook_event_name`, so each registered command passes its own event name. The end-of-turn `Stop` continuation reaches the model and is a bounded nudge, not a gate: ACC continues a turn at most once and fails open, and the client caps consecutive continuations itself (vendor 1.1.9). `agy agentapi send-message` can wake an idle session - captured - but only with that session's language-server address and CSRF token, which exist in the agent's own shell and in no hook. ACC does not take that token, so live push and reply routing are false. A peer message that arrives while the model writes its last answer is carried by the `Stop` continuation instead. A write that parses can register nothing, so install and doctor read `agy -p "/hooks"` back instead of trusting the file. Live push (1.2.7, darwin-arm64, TUI only, experimental, recorded opt-in) runs through a relay the agent starts once per conversation from its own shell - the only process holding the session endpoint - after ACC's context asks it to, up to three times while none is serving; the operator approves that command at the client's permission prompt. An idle session wakes; a busy one sees the message after its running answer, or at the next model invocation when the turn waits on a tool. Print mode and the first session in a folder trusted at that launch get no relay. |
 | Codex | Next-turn context, captured on 0.147.0, requires plugin trust. The observed stock 0.153.4 upgrade from ACC 0.3.1 to 0.4 required fresh review of five modified hook definitions; a subsequent restart retained all five active (activation evidence, not new event certification). LocalDaemon native delivery was captured through the installed package on 0.152.1 and 0.153.4, darwin-arm64; minimum 0.152.1, recorded opt-in, current feature probe and exact thread/cwd/process/version/protocol checks are required. Ordinary launch preserves the receiver workspace without ACC arguments or daemon ownership. Embedded or unreachable sessions keep their inbox. Native `replyRoute` remains false. |
 | Claude Code | 2.1.233 next-turn delivery waits for the next user prompt. A 2.1.258 Channel capture proved idle offer, busy queue-after-turn, explicit reply, duplicate suppression, and durable fallback, so `delivery.livePush` and `delivery.replyRoute` are live capabilities behind the native contract (experimental, off until opted in; Claude's development-channel warning is vendor-owned and visible). |
 | Gemini CLI | Package-shipped next-turn certification starts at 0.57.0. Its TUI has no captured external wake or queue interface and `--acp` changes launch ownership, so native delivery is fallback-only; live push and reply routing remain false. |

package/docs/CLI.md

@@ -101,6 +101,43 @@ delivery bindings. Default `sync` reads events after a 16-digit event cursor (10
 default, up to 500). `--scope history` discovers historical message headers and reads
 selected records; `--scope full` adds an unbounded snapshot for explicit workspace forensics.
 
+### Retention
+
+A workspace keeps what it is told to keep. `acc prune` reports what it no longer needs and
+reclaims it only when asked:
+
+```bash
+acc prune
+acc prune --apply
+acc prune --class claims --apply
+acc prune --before event_cursor
+```
+
+**`prune` changes nothing without `--apply`.** The reporting run is the default because this
+is the one command that takes records out of the store.
+
+| Class | Reclaimed when | Threshold |
+|---|---|---|
+| `sessions` | presence is `offline` | a confirmed dead pid, or 24 hours without a heartbeat |
+| `intents` | the session they belong to is reclaimed | - |
+| `claims` | the lease has expired | leases default to 30 minutes (`--lease-seconds`) |
+| `participants` | no session of theirs survives and no surviving message names them | - |
+
+`--before` takes a 16-digit cursor, the same one `sync` returns, and trims the event log to
+it. Messages recorded at or below that point go too, but only once nobody is owed them: a
+receipt that is still `queued`, `offered` or `retrieved` keeps its message, because offered is
+not read and retrieved is not model attention. A recipient that no longer exists cannot
+acknowledge anything, and does not hold a message forever.
+
+After a trim, `sync` reports `trimmedThrough`. A caller whose cursor precedes it was served a
+short page and can tell. **An ACC older than this feature cannot**: it will serve the same
+cursor without reporting the boundary, which is why trimming history is never automatic.
+
+Two classes need no operator at all. A retired transaction journal and a superseded retention
+marker have no reader, so a bounded pass reclaims them once a day when a store is opened, and
+`acc doctor --repair` reclaims them without that bound. `acc doctor` reports what is still
+held.
+
 ### Claims
 
 ```bash

package/docs/GETTING_STARTED.md

@@ -146,8 +146,8 @@ until a running turn finishes. Codex requires 0.152.1 or newer, LocalDaemon infr
 recorded opt-in, and a verified session. Supported explicit setup can prepare a missing
 service. Start the client with your normal command. A loaded daemon thread can receive
 messages after its terminal exits. Antigravity CLI 1.2.7 and later has one too: with delivery enabled,
-ACC's context asks the agent once per conversation to start a relay from its own shell, and
-you approve that command at the client's prompt.
+ACC's context asks the agent to start a relay from its own shell, up to three times while
+none is running, and you approve that command at the client's prompt.
 [Capabilities](CAPABILITIES.md) explains policy, versions and fallback.
 
 Delivery evidence is deliberately narrow: `queued -> offered -> retrieved -> acknowledged`.

package/docs/TROUBLESHOOTING.md

@@ -278,9 +278,10 @@ Live delivery needs four things, and `acc doctor` shows each:
 - the live policy is on: `acc install --adapter antigravity --delivery actionable` (or `all`);
 - the session is interactive - print mode ends with its turn and never runs a relay;
 - the session attached to ACC at all (see the section above);
-- the agent started the relay. ACC's context asks once per conversation; if the command was
-  declined, or never approved at the permission prompt, nothing asks again. Ask the agent to
-  run `sh "~/.gemini/config/acc/acc-relay.sh" start`, or start a new conversation.
+- the agent started the relay. While none is running, ACC's context asks up to three times
+  in that conversation. A declined prompt and an ignored ask look the same, so the line can
+  return after a decline; after the third ask it stays quiet. Run
+  `sh "~/.gemini/config/acc/acc-relay.sh" start` to start it directly.
 
 `acc doctor` reports how many relays are running and, per session, whether a live transport is
 active. A relay ends with its client; nothing is left running after the TUI exits or after

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

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-antigravity",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-antigravity/plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "acc",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Coordinate this Antigravity CLI session with other AI agent sessions working in the same workspace."
 }

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

@@ -84,9 +84,9 @@ export function createAntigravityAdapter() {
     probeNativeDelivery, planNativeActivation, bindNativeSession, refreshNativeSession,
     offerMessage,
     deliveryFallback: { diagnostic:
-      `Antigravity CLI next-turn and live delivery are certified for ${ANTIGRAVITY_CLI_VERSION} and `
-      + "later stable releases on darwin-arm64; live delivery also needs the agent to start "
-      + "ACC's relay once per conversation, and every other case keeps durable acc inbox access" },
+      `Antigravity CLI next-turn and live delivery are certified from ${ANTIGRAVITY_CLI_VERSION} `
+      + "onward; live delivery also needs the agent to start ACC's relay once per conversation, "
+      + "and an older client keeps durable acc inbox access" },
 
     startSession: async () => ({ ok: true, changes: [], diagnostics: [] }),
 

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

@@ -654,7 +654,8 @@ export async function doctorAntigravity(context) {
     diagnostics.push("registered per workspace; a session opened anywhere else loads nothing");
   }
   diagnostics.push(`live delivery starts when the agent runs sh "${relayShimPath(context.home)}" `
-    + "start once in a conversation; ACC asks it to, in its context line, when the policy is on");
+    + "start once in a conversation; while none is serving, ACC asks for that in its context "
+    + "line, up to three times, when the policy is on");
   diagnostics.push(`antigravity relays running on this machine: ${await runningRelays({
     dataHome: context.dataHome })}`);
   return { ok: true, changes: [], diagnostics };

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

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { execFile } from "node:child_process";
-import { lstat, mkdir, open } from "node:fs/promises";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, rm } from "node:fs/promises";
 import net from "node:net";
 import path from "node:path";
 
@@ -144,27 +145,72 @@ export async function offerMessage({ binding, message, runtimeDir, timeoutMs = 8
   }
 }
 
+const ASK_LIMIT = 3;
 const HINT = home => "ACC: live delivery is on but not running in this conversation. To let "
   + `peers reach you while idle, run once: sh "${path.join(home, ".gemini", "config", "acc",
     "acc-relay.sh")}" start`;
 
+// Each ask is its own file, created exclusively. A counter read and then
+// rewritten lets overlapping calls all observe the same count and each return
+// a hint. An empty file at the unsuffixed hash is the old one-ask marker: it
+// is not one of these three, so it does not spend the budget. The path is a
+// reservation: the caller deletes it when the line is not delivered.
+async function claimAsk(directory, marker) {
+  try {
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+  } catch {
+    return null;
+  }
+  for (let n = 1; n <= ASK_LIMIT; n += 1) {
+    const slot = `${marker}.${n}`;
+    let handle;
+    try {
+      handle = await open(slot, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL
+        | constants.O_NOFOLLOW, 0o600);
+      return slot;
+    } catch (error) {
+      if (error?.code === "EEXIST") continue;
+      return null;
+    } finally {
+      await handle?.close().catch(() => {});
+    }
+  }
+  return null;
+}
+
+function releaseAsk(slot) {
+  return rm(slot, { force: true }).catch(() => {});
+}
+
+async function relayAlreadyServing({ runtimeDir, conversationId, clientPid, isAlive }) {
+  for (const record of await listRegistrations({ runtimeDir })) {
+    if (record.conversationId !== conversationId) continue;
+    if (await serving(record, { timeoutMs: 100, isAlive, clientPid }) === null) return true;
+  }
+  return false;
+}
+
 export async function nativeActivationHint({ event, nativeBinding, runtimeDir, clientPid, env,
-  argvOf = argvDefault }) {
+  argvOf = argvDefault, isAlive = defaultAlive }) {
   // Only a degraded binding can be helped by starting a relay: "off" means the
   // live policy is off, "unsupported" that the contract does not admit this
-  // client, and "active" that a relay already serves it.
+  // client, and "active" that a relay already serves it. Those calls spend
+  // none of the asks recorded below.
   if (nativeBinding?.state !== "degraded") return null;
   const home = env?.HOME;
   if (typeof event?.sessionId !== "string" || typeof home !== "string" || home === "") return null;
   if (!Number.isInteger(clientPid) || isPrintMode(await argvOf(clientPid).catch(() => []))) return null;
+  // The runner asks only when its own handshake failed. A relay can still be
+  // serving under a stale degraded binding; telling the agent to start it again
+  // would be wrong, and the check does not spend an ask.
+  if (await relayAlreadyServing({ runtimeDir, conversationId: event.sessionId, clientPid,
+    isAlive })) return null;
   const asked = path.join(path.dirname(relayDir(runtimeDir)), "antigravity-asked");
   const marker = path.join(asked, createHash("sha256").update(event.sessionId).digest("hex"));
-  try {
-    await mkdir(asked, { recursive: true, mode: 0o700 });
-    const handle = await open(marker, "wx", 0o600);
-    await handle.close();
-  } catch {
-    return null;
-  }
-  return HINT(home);
+  // A decline and an ignored ask leave the same trace, so neither can stop the
+  // line by itself. Three exclusive creates are the bound. The file reserves
+  // the number now; release gives it back when the runner does not deliver.
+  const slot = await claimAsk(asked, marker);
+  if (slot === null) return null;
+  return { line: HINT(home), release: () => releaseAsk(slot) };
 }

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

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

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

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

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

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

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

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

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

@@ -52,8 +52,8 @@ export function createGeminiCliAdapter() {
       delivery: { nextTurn: true },
     },
     deliveryFallback: { diagnostic:
-      "Gemini CLI next-turn delivery is certified only for 0.57.0 on darwin-arm64; "
-      + "other or unknown versions keep durable acc inbox access, and live push is unavailable" },
+      "Gemini CLI next-turn delivery is certified from 0.57.0 onward, on every platform; "
+      + "an older client keeps durable acc inbox access, and live push is unavailable" },
 
     startSession: async () => ({ ok: true, changes: [], diagnostics: [] }),
     endSession: async () => ({ ok: true, changes: [], diagnostics: [] }),

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

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

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

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

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

@@ -41,8 +41,8 @@ export function createKimiAdapter() {
       delivery: { nextTurn: true },
     },
     deliveryFallback: { diagnostic:
-      "Kimi Code next-turn delivery is certified only for 0.36.1 on darwin-arm64; "
-      + "other or unknown versions keep durable acc inbox access, and live push is unavailable" },
+      "Kimi Code next-turn delivery is certified from 0.36.1 onward, on every platform; "
+      + "an older client keeps durable acc inbox access, and live push is unavailable" },
 
     startSession: async () => ({ ok: true, changes: [], diagnostics: [] }),
     heartbeat: async () => ({ ok: true, changes: [], diagnostics: [] }),

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

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

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

@@ -15,7 +15,7 @@ const checkDeadline = deadline => {
   if (Date.now() >= deadline) throw new Error("native diagnostic deadline expired");
 };
 
-// The caller stops waiting after 250 ms at most. An in-flight filesystem call
+// The caller stops waiting after 1.5 s at most. An in-flight filesystem call
 // may complete later, so retain this SEPARATE mutex until its continuation is
 // finished. Unique staging names also isolate cleanup after stale-lock recovery.
 // No diagnostic operation can touch the authoritative hook-owner file.

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

@@ -39,7 +39,9 @@ export async function loadNativeAttempt({ runtimeDir, harnessSessionId, accSessi
 // must not keep the vendor's short-lived hook process alive after its output.
 // The unreferenced worker owns its mutex through any late I/O continuation.
 async function writeDiagnostic(operation, input) {
-  const deadlineAt = Math.min(input.deadlineAt ?? Infinity, Date.now() + 250);
+  // Same ceiling as the hook runner's diagnostic budget. A caller cannot wait
+  // longer than this, and a shorter deadlineAt is still honored.
+  const deadlineAt = Math.min(input.deadlineAt ?? Infinity, Date.now() + 1_500);
   if (Date.now() >= deadlineAt) return false;
   let worker;
   let timer;

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

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

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

@@ -40,6 +40,12 @@ export const COMMANDS = Object.freeze({
     repeated: ["completed", "remaining", "blocker"] },
   status: { required: [], optional: ["session", "generation", "participant"], flags: ["all"] },
   doctor: { required: [], optional: ["home"], flags: ["repair"] },
+  // `--apply` rather than `--dry-run`: this is the one command that takes
+  // records out of the store, so the reporting run is what happens by
+  // default and meaning it is what has to be said out loud.
+  // No `--session`: this acts on the workspace, not as a participant in it, so
+  // a session id would be a credential nothing reads.
+  prune: { required: [], optional: ["before"], repeated: ["class"], flags: ["apply"] },
   // 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.

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

@@ -267,7 +267,19 @@ export async function runDoctor({ options, context, runtime }) {
   // command documented as saying "what to run next" said it only to `--json`.
   // A person running `acc doctor` on a client wired to an older plugin was told
   // the store was healthy and nothing else.
-  const text = [`store healthy; ${describePresence(status.counts)}; `
+  // Named rather than left to be inferred: staging files are reclaimed a
+  // bounded amount at a time, so a store still carrying a large accumulation
+  // should say so instead of reading as if nothing were held.
+  const held = [
+    report.staged > 0 ? `${report.staged} staged` : null,
+    report.partials > 0 ? `${report.partials} partial` : null,
+    // A retired journal entry has no reader at all, so a count above zero says
+    // the automatic pass has not caught up rather than that anything is wrong.
+    report.retired > 0 ? `${report.retired} retired journal` : null,
+    report.trimmedThrough === null ? null : `history from ${report.trimmedThrough}`,
+  ].filter(Boolean);
+  const staging = held.length === 0 ? "" : ` (${held.join(", ")})`;
+  const text = [`store healthy${staging}; ${describePresence(status.counts)}; `
     + `protection ${status.protection}; ${installed} of ${adapters.length} adapter(s) installed`,
   ...adapters.filter(adapter => (adapter.present || adapter.installed)
     && adapter.nativeDelivery.reasonCode === "native_delivery_unsupported"

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

@@ -17,7 +17,7 @@ import { needsOwner } from "./session-owner.mjs";
  * protocol's enum choices before a caller has to attempt a mutation.
  */
 const GROUPS = Object.freeze([
-  ["Set up", ["install", "uninstall", "doctor", "config"]],
+  ["Set up", ["install", "uninstall", "doctor", "config", "prune"]],
   ["In a session", ["status", "sync", "work", "claim", "release", "inbox", "reply",
     "ack", "message", "request", "finish"]],
   ["Session lifecycle", ["attach", "heartbeat", "detach"]],
@@ -30,6 +30,7 @@ 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",
+  prune: "report what this workspace no longer needs; --apply to reclaim it",
   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",

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

@@ -379,6 +379,24 @@ const HANDLERS = Object.freeze({
   uninstall: async ({ options, runtime }) =>
     runInstallCommand({ options, runtime, action: "uninstall" }),
 
+  prune: async ({ options, context }) => {
+    const result = await context.service.prune({
+      classes: options.class, before: options.before,
+      apply: options.apply === true, limit: Infinity });
+    const named = Object.entries(result.counts)
+      .map(([name, count]) => `${count} ${name}`).join(", ");
+    // The reporting run says what it would do; the applying run says what the
+    // store gave back, which is not the same number - a record and the markers
+    // it owns leave together.
+    const text = result.applied
+      ? `reclaimed ${result.reclaimed} file(s) from ${named}`
+        + (result.trimmedThrough === null ? "" : `; history starts after ${result.trimmedThrough}`)
+        + (result.skipped > 0 ? `; ${result.skipped} changed and were left` : "")
+        + (result.remaining ? "; more remains, run it again" : "")
+      : `would prune ${named}; nothing was changed, add --apply to act`;
+    return { data: result, text };
+  },
+
   doctor: async ({ options, context, runtime }) => runDoctor({ options, context, runtime }),
 
   update: async ({ options, runtime }) => runUpdateCommand({ options, runtime }),

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

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

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

@@ -3,6 +3,7 @@ import { AccError, EXIT } from "@agents-can-communicate/protocol";
 import { overlaps } from "./claims.mjs";
 import { classifySessionPresence } from "./sessions.mjs";
 import { decisionView, isCurrentDecision } from "./decision-state.mjs";
+import { isCurrentIntent } from "./intents.mjs";
 
 export const ATTENTION_PRIORITY = Object.freeze({
   reply_required: 1,
@@ -65,7 +66,11 @@ function expiredClaims(snapshot, session, now) {
 }
 
 function claimConflicts(snapshot, session, now) {
-  const mine = (snapshot.intents ?? []).find(intent => intent.sessionId === session?.sessionId);
+  // Both kinds read resourceHints as a statement of what a session means to
+  // touch. Finishing that work retracts the statement, so a done record must
+  // not keep raising conflicts on either side of it.
+  const mine = (snapshot.intents ?? []).find(intent => intent.sessionId === session?.sessionId
+    && isCurrentIntent(intent));
   if (mine === undefined) return [];
   return (snapshot.claims ?? []).filter(claim => claim.ownerSessionId !== session.sessionId
     && Date.parse(claim.expiresAt) > Date.parse(now)
@@ -78,7 +83,7 @@ function claimConflicts(snapshot, session, now) {
 function claimContended(snapshot, session, now) {
   if (session == null) return [];
   const peerIntents = (snapshot.intents ?? [])
-    .filter(intent => intent.sessionId !== session.sessionId);
+    .filter(intent => intent.sessionId !== session.sessionId && isCurrentIntent(intent));
   return (snapshot.claims ?? []).filter(claim => claim.ownerSessionId === session.sessionId
     && Date.parse(claim.expiresAt) > Date.parse(now)).flatMap(claim => {
     const peer = peerIntents.find(intent => intent.resourceHints

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

@@ -3,6 +3,22 @@ import { AccError, EXIT, SCHEMA_VERSION, validateRecord }
 
 import { isMaterialised } from "./materialisation.mjs";
 
+/**
+ * Does this record still answer "what is this session doing now?".
+ *
+ * `clearIntent` marks a durable intent done instead of erasing it, so the
+ * workspace keeps what each session worked on. That leaves every reader to
+ * exclude the finished ones, and this is the single place that decides which
+ * states count - status and attention disagreeing about the same record is
+ * exactly the defect this exists to prevent.
+ *
+ * Stopped is not finished. A blocked or waiting session still owns its work and
+ * the resourceHints that announce it, so only "done" gives them up.
+ */
+export function isCurrentIntent(intent) {
+  return intent.state !== "done";
+}
+
 // Intent answers "what is this session doing now?". It is awareness, not
 // authorisation: an edit intent never substitutes for a claim, which is why
 // resourceHints are advisory strings rather than reservations.