chainlesschain 0.166.1 → 0.166.3

package/src/commands/team.js

@@ -24,7 +24,14 @@ import { TeamRunner } from "../lib/agent-team/team-runner.js";
 import { TeamWorktreeCoordinator } from "../lib/agent-team/team-worktree.js";
 import { TeamBudget } from "../lib/agent-team/team-budget.js";
 import { TeamMailbox } from "../lib/agent-team/team-mailbox.js";
+import { TeamSessionMessageAdapter } from "../lib/agent-team/team-session-message-adapter.js";
 import { TeamAgentStreamParser } from "../lib/agent-team/team-agent-stream.js";
+import { TeamMessageBridge } from "../lib/agent-team/team-message-bridge.js";
+import {
+  computeTeamGraphAuthorityDigest,
+  computeTeamGraphRevisionDigest,
+  projectTeamGraphCollaboration,
+} from "../lib/agent-team/team-graph-projection.js";
 import { resolveTeamTaskContract } from "../lib/agent-team/team-task-contract.js";
 import {
   TeamScopeLock,
@@ -727,6 +734,7 @@ export function buildTeamAgentPrompt(prompt, { inbox = [] } = {}) {
   const messages = inbox
     .slice(-MAX_TEAM_AGENT_INBOX_MESSAGES)
     .map((message) => ({
+      id: Number.isSafeInteger(message?.id) ? message.id : null,
       from: String(message?.from || "unknown").slice(0, 128),
       to: String(message?.to || "").slice(0, 128),
       subject:
@@ -1016,7 +1024,7 @@ export function makeShellRunTask() {
 }
 
 /** Spawn a headless `cc agent -p` for one prompt in `cwd`; resolve on exit 0. */
-export function spawnAgent(prompt, cwd, opts = {}) {
+function spawnAgentProcess(prompt, cwd, opts = {}) {
   return new Promise((resolve, reject) => {
     const parser = new TeamAgentStreamParser({
       maxLineBytes: opts.maxStreamLineBytes,
@@ -1043,7 +1051,11 @@ export function spawnAgent(prompt, cwd, opts = {}) {
     try {
       child = _deps.spawn(process.execPath, args, {
         cwd,
-        env: { ...process.env, CLAUDECODE: "1" },
+        env: {
+          ...process.env,
+          CLAUDECODE: "1",
+          ...(opts.childEnv || {}),
+        },
         windowsHide: true,
         detached:
           opts.managedCheckpoint === true
@@ -1311,6 +1323,33 @@ export function spawnAgent(prompt, cwd, opts = {}) {
   });
 }
 
+export function spawnAgent(prompt, cwd, opts = {}) {
+  if (!opts.messageBridge) return spawnAgentProcess(prompt, cwd, opts);
+  return (async () => {
+    let bridge;
+    try {
+      bridge = new TeamMessageBridge(opts.messageBridge);
+      await bridge.start();
+    } catch (error) {
+      throw teamAgentError(
+        "TEAM_AGENT_MESSAGE_BRIDGE_FAILED",
+        error?.message || "Could not start teammate message bridge",
+      );
+    }
+    try {
+      return await spawnAgentProcess(bridge.decoratePrompt(prompt), cwd, {
+        ...opts,
+        childEnv: {
+          ...(opts.childEnv || {}),
+          ...bridge.childEnvironment(),
+        },
+      });
+    } finally {
+      await bridge.close();
+    }
+  })();
+}
+
 /** Real executor: hand a task's `prompt` to a headless `cc agent -p` in cwd. */
 function applyBudgetReservation(contract, budgetReservation) {
   const effectiveContract = { ...contract };
@@ -1333,7 +1372,14 @@ export function makeAgentRunTask(opts = {}) {
   return function runTask({
     key,
     task,
+    holder,
     inbox = [],
+    sendMessage = null,
+    messageAuthority = null,
+    recipientState = null,
+    requestFollowupWake = null,
+    requestHandoff = null,
+    mailbox = null,
     budgetReservation = null,
     signal = null,
   }) {
@@ -1357,8 +1403,23 @@ export function makeAgentRunTask(opts = {}) {
     );
     return spawnAgent(buildTeamAgentPrompt(prompt, { inbox }), process.cwd(), {
       ...effectiveContract,
-      sessionId: opts.sessionIdForTask?.(key) || null,
+      sessionId: opts.sessionIdForTask?.(key, task) || null,
       signal,
+      ...(mailbox && holder
+        ? {
+            messageBridge: {
+              mailbox,
+              holder,
+              sendMessage,
+              assertAuthority: messageAuthority,
+              recipientState,
+              requestFollowupWake,
+              requestHandoff,
+              onMutation: opts.onMailboxMutation,
+              durable: opts.mailboxDurable === true,
+            },
+          }
+        : {}),
     });
   };
 }
@@ -2109,8 +2170,17 @@ export function registerTeamCommand(program, { logger } = {}) {
           return;
         }
         const ttlMs = limits.ttlMs;
+        const stateId = resumeSnapshot?.stateId || `team_state_${randomUUID()}`;
+        const messageStatePath = options.state
+          ? `${options.state}.${stateId}.messages.json`
+          : null;
         let reg;
-        let mailbox = new TeamMailbox();
+        let mailbox = options.state
+          ? new TeamSessionMessageAdapter({
+              statePath: messageStatePath,
+              teamId: stateId,
+            })
+          : new TeamMailbox();
         let budget = new TeamBudget({
           maxTasks: limits.maxTasks,
           maxTokens: limits.maxTokens,
@@ -2130,7 +2200,32 @@ export function registerTeamCommand(program, { logger } = {}) {
             const isV2 = snap && snap.version >= 2 && snap.registry;
             reg = TaskLeaseRegistry.restore(isV2 ? snap.registry : snap);
             if (isV2) {
-              if (snap.mailbox) mailbox = TeamMailbox.restore(snap.mailbox);
+              if (snap.mailbox?.authority === "session-message-fabric") {
+                if (
+                  !sameFilesystemPath(
+                    path.resolve(snap.mailbox.statePath),
+                    path.resolve(messageStatePath),
+                  )
+                ) {
+                  throw new Error(
+                    "Team message authority path does not match the trusted state identity",
+                  );
+                }
+                mailbox = TeamSessionMessageAdapter.restore(snap.mailbox, {
+                  statePath: messageStatePath,
+                  teamId: stateId,
+                });
+              } else if (snap.mailbox && options.state) {
+                mailbox = TeamSessionMessageAdapter.migrateLegacy(
+                  snap.mailbox,
+                  {
+                    statePath: messageStatePath,
+                    teamId: stateId,
+                  },
+                );
+              } else if (snap.mailbox) {
+                mailbox = TeamMailbox.restore(snap.mailbox);
+              }
               budget = TeamBudget.restore(snap.budget, {
                 // Resume flags may only tighten prior caps; omitted flags keep
                 // the persisted authority.
@@ -2234,6 +2329,11 @@ export function registerTeamCommand(program, { logger } = {}) {
             }),
           ]),
         );
+        const sessionTaskKeyFor = (key, task = reg.getTask(key)) =>
+          task?.metadata?.teamFollowup?.sessionTaskKey || key;
+        const taskContractFor = (key, task = reg.getTask(key)) =>
+          taskContracts.get(key) ||
+          taskContracts.get(sessionTaskKeyFor(key, task));
         if ((options.agent || options.exec) && !options.worktree) {
           const isolatedTask = reg
             .list()
@@ -2301,7 +2401,6 @@ export function registerTeamCommand(program, { logger } = {}) {
             );
           }
         }
-        const stateId = resumeSnapshot?.stateId || `team_state_${randomUUID()}`;
         let controlCursor = resumeSnapshot?.controlCursor || null;
         let adjudicationCursor = resumeSnapshot?.adjudicationCursor || null;
         let adjudicationRunId = resumeSnapshot?.adjudicationRunId || null;
@@ -2480,37 +2579,40 @@ export function registerTeamCommand(program, { logger } = {}) {
             checkpointRequired:
               options.agent === true || options.managedCheckpoint === true,
             worktreeRequired: options.worktree === true,
-            units: reg.list().map((task) => ({
-              key: task.key,
-              branch: options.worktree
-                ? priorUnits.get(task.key)?.branch ||
-                  branchPlanner.branchFor(task.key)
-                : null,
-              worktreePath: options.worktree
-                ? priorUnits.get(task.key)?.worktreePath || null
-                : null,
-              sessionId: options.agent
-                ? priorUnits.get(task.key)?.sessionId ||
-                  _deps.collaborationStore.createSessionId(runId, task.key)
-                : null,
-              status:
-                String(task.status || "").toLowerCase() === "completed"
-                  ? "completed"
-                  : "pending",
-              permissionMode: taskContracts.get(task.key)?.permissionMode,
-              resourceBudget: {
-                maxTurns: taskContracts.get(task.key)?.maxTurns,
-                maxCostUsd: taskContracts.get(task.key)?.maxBudgetUsd,
-                maxTokens: taskContracts.get(task.key)?.maxTokens,
-                maxWallMs: taskContracts.get(task.key)?.maxWallMs,
-              },
-              checkpointRequired:
-                taskContracts.get(task.key)?.checkpointRequired === true ||
-                options.managedCheckpoint === true,
-              worktreeRequired:
-                taskContracts.get(task.key)?.worktreeRequired === true,
-              scopePaths: task.metadata?.scopePaths || [],
-            })),
+            units: reg
+              .list()
+              .filter((task) => !task.metadata?.teamFollowup)
+              .map((task) => ({
+                key: task.key,
+                branch: options.worktree
+                  ? priorUnits.get(task.key)?.branch ||
+                    branchPlanner.branchFor(task.key)
+                  : null,
+                worktreePath: options.worktree
+                  ? priorUnits.get(task.key)?.worktreePath || null
+                  : null,
+                sessionId: options.agent
+                  ? priorUnits.get(task.key)?.sessionId ||
+                    _deps.collaborationStore.createSessionId(runId, task.key)
+                  : null,
+                status:
+                  String(task.status || "").toLowerCase() === "completed"
+                    ? "completed"
+                    : "pending",
+                permissionMode: taskContracts.get(task.key)?.permissionMode,
+                resourceBudget: {
+                  maxTurns: taskContracts.get(task.key)?.maxTurns,
+                  maxCostUsd: taskContracts.get(task.key)?.maxBudgetUsd,
+                  maxTokens: taskContracts.get(task.key)?.maxTokens,
+                  maxWallMs: taskContracts.get(task.key)?.maxWallMs,
+                },
+                checkpointRequired:
+                  taskContracts.get(task.key)?.checkpointRequired === true ||
+                  options.managedCheckpoint === true,
+                worktreeRequired:
+                  taskContracts.get(task.key)?.worktreeRequired === true,
+                scopePaths: task.metadata?.scopePaths || [],
+              })),
           });
         } catch (err) {
           (log.error || console.error)(
@@ -2522,8 +2624,27 @@ export function registerTeamCommand(program, { logger } = {}) {
         const collaborationUnits = new Map(
           collaborationRun.units.map((unit) => [unit.key, unit]),
         );
+        const teamGraphRunId =
+          resumeSnapshot?.graphProjection?.runId || `team:${stateId}`;
+        const teamGraphRevisionDigest =
+          resumeSnapshot?.graphProjection?.revisionDigest ||
+          computeTeamGraphRevisionDigest(reg);
+        const teamGraphAuthorityDigest =
+          resumeSnapshot?.graphProjection?.authorityDigest ||
+          computeTeamGraphAuthorityDigest({
+            stateId,
+            permissionMode: options.agent ? permissionMode : "default",
+            worktreeRequired: options.worktree === true,
+            checkpointRequired:
+              options.agent === true || options.managedCheckpoint === true,
+            holders: Array.from(
+              { length: Math.min(teammates, Math.max(1, reg.list().length)) },
+              (_, index) => `teammate-${index + 1}`,
+            ),
+          });
         const settleGovernance = (key, status, extra = {}) => {
-          const unit = collaborationUnits.get(key);
+          const governanceKey = sessionTaskKeyFor(key);
+          const unit = collaborationUnits.get(governanceKey);
           let sideEffects = null;
           if (unit?.sessionId) {
             try {
@@ -2536,7 +2657,7 @@ export function registerTeamCommand(program, { logger } = {}) {
           }
           const updated = _deps.collaborationStore.updateUnit(
             collaborationRun.id,
-            key,
+            governanceKey,
             {
               status,
               ...extra,
@@ -2544,7 +2665,7 @@ export function registerTeamCommand(program, { logger } = {}) {
             },
             { returnUnit: true },
           );
-          if (updated) collaborationUnits.set(key, updated);
+          if (updated) collaborationUnits.set(governanceKey, updated);
         };
 
         // Persist a snapshot after each task settles so a crash mid-run is
@@ -2575,6 +2696,14 @@ export function registerTeamCommand(program, { logger } = {}) {
             adjudicationRunId,
             adjudicationCursor,
             execution: executionContract,
+            graphProjection: projectTeamGraphCollaboration({
+              runId: teamGraphRunId,
+              mailbox,
+              registry: reg,
+              recipients: mailbox.status?.().recipients || [],
+              revisionDigest: teamGraphRevisionDigest,
+              authorityDigest: teamGraphAuthorityDigest,
+            }),
           });
         };
 
@@ -2661,8 +2790,15 @@ export function registerTeamCommand(program, { logger } = {}) {
               runInWorktree: async ({
                 key,
                 task,
+                holder,
                 cwd,
                 inbox = [],
+                sendMessage = null,
+                messageAuthority = null,
+                recipientState = null,
+                requestFollowupWake = null,
+                requestHandoff = null,
+                mailbox: taskMailbox = null,
                 budgetReservation = null,
                 signal = null,
                 managedCheckpoint = false,
@@ -2672,7 +2808,7 @@ export function registerTeamCommand(program, { logger } = {}) {
                   throw new Error(`task "${key}" has no \`prompt\` to --agent`);
                 }
                 const contract = applyBudgetReservation(
-                  taskContracts.get(key),
+                  taskContractFor(key, task),
                   budgetReservation,
                 );
                 return spawnAgent(
@@ -2687,8 +2823,25 @@ export function registerTeamCommand(program, { logger } = {}) {
                       ? false
                       : contract.checkpointRequired,
                     managedCheckpoint,
-                    sessionId: collaborationUnits.get(key)?.sessionId,
+                    sessionId: collaborationUnits.get(
+                      sessionTaskKeyFor(key, task),
+                    )?.sessionId,
                     signal,
+                    ...(taskMailbox && holder
+                      ? {
+                          messageBridge: {
+                            mailbox: taskMailbox,
+                            holder,
+                            sendMessage,
+                            assertAuthority: messageAuthority,
+                            recipientState,
+                            requestFollowupWake,
+                            requestHandoff,
+                            onMutation: persist,
+                            durable: Boolean(options.state),
+                          },
+                        }
+                      : {}),
                   },
                 );
               },
@@ -2706,9 +2859,12 @@ export function registerTeamCommand(program, { logger } = {}) {
           runTask = makeShellRunTask(log);
         } else if (options.agent)
           runTask = makeAgentRunTask({
-            contractForTask: (key) => taskContracts.get(key),
+            contractForTask: (key, task) => taskContractFor(key, task),
             worktreeEnabled: false,
-            sessionIdForTask: (key) => collaborationUnits.get(key)?.sessionId,
+            sessionIdForTask: (key, task) =>
+              collaborationUnits.get(sessionTaskKeyFor(key, task))?.sessionId,
+            onMailboxMutation: persist,
+            mailboxDurable: Boolean(options.state),
           });
         else runTask = async () => ({ dryRun: true });
 
@@ -2767,7 +2923,7 @@ export function registerTeamCommand(program, { logger } = {}) {
           }
           const binding = adjudicationBindingFor(
             task,
-            collaborationUnits.get(key) || null,
+            collaborationUnits.get(sessionTaskKeyFor(key, task)) || null,
           );
           const opened = adjudicationStore.openCase(binding, {
             anchor: adjudicationCursor,
@@ -2794,9 +2950,10 @@ export function registerTeamCommand(program, { logger } = {}) {
           runTask,
           budget,
           budgetForTask: options.agent
-            ? (task) => taskContracts.get(task.key)
+            ? (task) => taskContractFor(task.key, task)
             : () => ({ reserveUsage: false }),
           mailbox,
+          realtimeMessaging: options.agent === true,
           scopeLock,
           recorder,
           beforeTask: ({ key }) => {
@@ -2823,9 +2980,14 @@ export function registerTeamCommand(program, { logger } = {}) {
                 ? "pending"
                 : retry
                   ? "pending"
-                  : status;
+                  : options.agent === true && status === "completed"
+                    ? "running"
+                    : status;
             settleGovernance(key, governanceStatus, {
-              endedAt: governanceStatus === "pending" ? null : Date.now(),
+              endedAt:
+                governanceStatus === "pending" || governanceStatus === "running"
+                  ? null
+                  : Date.now(),
             });
             ensureTaskAdjudicationCase(key);
             persist();
@@ -2833,6 +2995,14 @@ export function registerTeamCommand(program, { logger } = {}) {
           onLeaseChanged: () => {
             persist();
           },
+          onFollowupMutation: () => {
+            persist();
+          },
+          onHandoffMutation: () => {
+            persist();
+          },
+          graphRevisionDigest: teamGraphRevisionDigest,
+          graphAuthorityDigest: teamGraphAuthorityDigest,
           onEvent: (e) => {
             if (options.json) console.log(JSON.stringify(e));
             else if (e.type === "task:claimed")
@@ -2939,18 +3109,32 @@ export function registerTeamCommand(program, { logger } = {}) {
         persist();
         let governanceFailed = false;
         try {
-          // Reconcile only units whose authoritative registry state differs.
-          // Per-task hooks already durably settled the common path.
+          // Follow-up wake tasks are new lease-bound turns in the same durable
+          // collaboration session/unit as their source task. Aggregate every
+          // such turn before making the unit terminal; otherwise the first
+          // completed turn would freeze governance before a later follow-up.
+          const tasksByGovernanceKey = new Map(
+            [...collaborationUnits.keys()].map((key) => [key, []]),
+          );
           for (const task of reg.list()) {
-            const state = String(task.status || "").toLowerCase();
+            const governanceKey = sessionTaskKeyFor(task.key, task);
+            tasksByGovernanceKey.get(governanceKey)?.push(task);
+          }
+          for (const [key, tasks] of tasksByGovernanceKey) {
+            const states = tasks.map((task) =>
+              String(task.status || "").toLowerCase(),
+            );
             const status =
-              state === "completed"
+              states.length > 0 &&
+              states.every((state) => state === "completed")
                 ? "completed"
-                : state === "cancelled" || state === "pending"
+                : states.some(
+                      (state) => state === "cancelled" || state === "pending",
+                    )
                   ? "cancelled"
                   : "failed";
-            if (collaborationUnits.get(task.key)?.status === status) continue;
-            settleGovernance(task.key, status, {
+            if (collaborationUnits.get(key)?.status === status) continue;
+            settleGovernance(key, status, {
               endedAt: Date.now(),
             });
           }

package/src/data/changelog.json

@@ -1,6 +1,32 @@
 {
   "source": "CHANGELOG.md",
   "releases": [
+    {
+      "productVersion": null,
+      "cliVersion": "0.166.3",
+      "cliVersions": ["0.1.2", "0.2.2", "0.166.2", "0.166.3"],
+      "date": "2026-08-25",
+      "title": "",
+      "sections": [
+        {
+          "heading": "Added - cc CLI 0.166.3 + Agent Protocol 0.1.2 + Agent SDKs 0.2.2: scoped approvals and durable team authority",
+          "body": "> `chainlesschain` **0.166.2 -> 0.166.3**,\n> `@chainlesschain/agent-protocol` **0.1.1 -> 0.1.2**,\n> `@chainlesschain/agent-sdk` **0.2.1 -> 0.2.2**, and\n> `chainlesschain-agent-sdk` **0.2.1 -> 0.2.2** (release candidate,\n> 2026-08-25).\n\n- **Canonical approval contract**: the protocol package exports schema-derived\n  JavaScript validators and deterministic TypeScript/Python bindings for\n  `acceptOnce`, `acceptForTurn`, `acceptForSession`, `decline`, and `cancel`.\n  Shared valid/invalid fixtures keep the protocol, both SDKs, and CLI App\n  Server on one wire contract.\n- **Fail-closed, exactly scoped grants**: approval responses bind the request,\n  requested permission, tool, arguments, working directory, and policy digest.\n  Turn grants stay in memory; session grants become effective only after a\n  tamper-evident authority event is persisted and verified. Expired, corrupt,\n  mismatched, widened, or persistence-failed grants never silently authorize a\n  call.\n- **N-1 SDK compatibility**: boolean callbacks normalize to one-shot canonical\n  decisions with the request binding, while direct boolean responses retain\n  the legacy wire for older callers. Invalid or throwing callbacks decline\n  safely in both TypeScript and Python.\n- **Durable Team messaging and custody**: state-backed Team runs now use the\n  `SessionMessageFabric` authority for bounded cross-process delivery,\n  offline/reconnect, receipts, fencing, dead letters, rate limits, and legacy\n  mailbox migration. Idle follow-up turns and offer/accept/commit handoffs keep\n  stable message identity while transferring attempt/lease custody explicitly.\n- **Release validation**: publication requires the exact release commit to pass\n  Agent Protocol and Python SDK conformance, Linux/Windows/macOS `CLI CI` and\n  `CLI Strict Sandbox`, and the desktop E2E matrix before immutable OIDC tags\n  are created."
+        }
+      ]
+    },
+    {
+      "productVersion": null,
+      "cliVersion": "0.166.2",
+      "cliVersions": ["0.166.1", "0.166.2"],
+      "date": "2026-08-25",
+      "title": "",
+      "sections": [
+        {
+          "heading": "Added - cc CLI 0.166.2: lease-bound real-time team messaging",
+          "body": "> `chainlesschain` **0.166.1 -> 0.166.2** (CLI-only release candidate,\n> 2026-08-25). `@chainlesschain/agent-protocol` remains **0.1.1**,\n> `@chainlesschain/agent-sdk` remains **0.2.1**, and\n> `chainlesschain-agent-sdk` remains **0.2.1**.\n\n- **Live teammate tools**: real `cc team --agent` children receive host-owned\n  `team_send`, `team_receive`, `team_ack`, and `team_followup` tools over a\n  private local bridge instead of relying only on a startup inbox snapshot.\n- **Retry-safe delivery**: the bounded mailbox persists at-least-once delivery\n  receipts, stable-consumer ACKs, idempotent message keys, payload digests,\n  causation/correlation metadata, processed/dead-letter states, and monotonic\n  cursors across team-state restore.\n- **Attempt-scoped authority**: every bridge operation revalidates the current\n  holder, task, attempt, lease, and fencing token; stale attempts fail closed,\n  bridge credentials never enter the prompt, and nested subagents cannot\n  inherit the parent-bound tools.\n- **Honest durability and wake semantics**: `--state` checkpoints every bridge\n  mutation, runs without state declare process-local delivery, and follow-up\n  results distinguish an active target from a request queued for a future turn.\n- **Release validation**: publication requires this candidate's exact commit\n  to pass the complete Linux, Windows, and macOS `CLI CI` and\n  `CLI Strict Sandbox` matrices before an immutable npm tag is created."
+        }
+      ]
+    },
     {
       "productVersion": null,
       "cliVersion": "0.166.1",