chainlesschain 0.162.180 → 0.162.181

package/src/lazy-dispatch.js

@@ -6,6 +6,10 @@ import { pathToFileURL } from "node:url";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { readFileSync } from "node:fs";
+import {
+  startDefaultEventRuntimeHost,
+  stopDefaultEventRuntimeHost,
+} from "./lib/event-runtime-host.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const manifest = JSON.parse(
@@ -29,7 +33,28 @@ export function resolveCommandToken(argv = []) {
   return null;
 }
 
-export async function runCli(argv) {
+export async function withDefaultEventRuntimeLifecycle(
+  task,
+  { hostOptions = {} } = {},
+) {
+  if (typeof task !== "function") {
+    throw new TypeError("Event Runtime lifecycle task must be a function");
+  }
+  const host = startDefaultEventRuntimeHost({
+    ...hostOptions,
+    // Let the selected command finish registering its handlers before the
+    // first claim. Resident commands then run on the normal interval; short
+    // commands receive a bounded final drain in the finally block.
+    immediate: false,
+  });
+  try {
+    return await task(host);
+  } finally {
+    if (host) await stopDefaultEventRuntimeHost({ drain: true });
+  }
+}
+
+async function dispatchCli(argv) {
   const args = argv.slice(2);
 
   // Resolve the command before deciding whether help/version needs the eager
@@ -95,6 +120,10 @@ export async function runCli(argv) {
   }
 }
 
+export async function runCli(argv) {
+  return withDefaultEventRuntimeLifecycle(() => dispatchCli(argv));
+}
+
 export class LazyDispatch {
   constructor(manifest) {
     this.manifest = manifest;

package/src/lib/agent-authority.js

@@ -154,6 +154,28 @@ export function canManageSession(envelope = {}) {
   );
 }
 
+/**
+ * True when this envelope may answer a human-interaction request. A local UI
+ * owns this authority. A remote peer must be authenticated and explicitly
+ * paired for prompt/approve/manage control; observe-only peers cannot answer.
+ */
+export function canAnswerInteraction(envelope = {}) {
+  if (envelope.origin === ORIGIN.USER) return true;
+  if (envelope.origin !== ORIGIN.REMOTE || envelope.authenticated !== true) {
+    return false;
+  }
+  const scopes = normalizeScopes(envelope);
+  return scopes.has("prompt") || scopes.has("approve") || scopes.has("manage");
+}
+
+export function assertCanAnswerInteraction(envelope = {}) {
+  if (canAnswerInteraction(envelope)) return;
+  const who = envelope.origin || "unknown";
+  throw new Error(
+    `origin "${who}" is not authorized to answer interaction requests`,
+  );
+}
+
 /**
  * Throw a clear, log-safe error when an envelope is NOT allowed to approve.
  * Callers gate every "resolve a permission" seam through this so the rule

package/src/lib/agent-core.js

@@ -51,5 +51,7 @@ export {
   _resetFileFreshness,
   _getSharedCodeIntel,
   disposeSharedCodeIntel,
+  emitToolHookLifecycle,
+  emitToolBatchHookLifecycle,
   _resetSubtreeInstructionLoaders,
 } from "../runtime/agent-core.js";

package/src/lib/agent-sandbox.js

@@ -1,4 +1,5 @@
 /** OS-isolated shell execution for the coding agent. */
+import fs from "node:fs";
 import path from "node:path";
 import { proxyEnv } from "./sandbox-egress-proxy.js";
 import executionBroker from "./process-execution-broker/index.js";
@@ -29,6 +30,166 @@ function resolvePolicyPaths(entries, cwd) {
   });
 }
 
+function pathEntryExists(candidate, fsImpl) {
+  try {
+    fsImpl.lstatSync(candidate);
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT" || error?.code === "ENOTDIR") return false;
+    throw error;
+  }
+}
+
+/**
+ * Resolve a path for policy comparison without requiring the final target to
+ * exist. Existing ancestors are resolved through symlinks/junctions before the
+ * missing suffix is appended. This is important for writes: checking only the
+ * lexical target lets `workspace/link/new-file` escape when `link` points
+ * outside the workspace.
+ */
+function canonicalPolicyPath(candidate, fsImpl) {
+  const absolute = path.resolve(candidate);
+  let existing = absolute;
+  const missing = [];
+
+  while (!pathEntryExists(existing, fsImpl)) {
+    const parent = path.dirname(existing);
+    if (parent === existing) {
+      throw new Error(`No existing ancestor for path: ${absolute}`);
+    }
+    missing.unshift(path.basename(existing));
+    existing = parent;
+  }
+
+  const realpath =
+    typeof fsImpl.realpathSync?.native === "function"
+      ? fsImpl.realpathSync.native
+      : fsImpl.realpathSync;
+  if (typeof realpath !== "function") {
+    throw new Error("Filesystem realpath support is unavailable");
+  }
+  return path.resolve(realpath(existing), ...missing);
+}
+
+function pathIsWithin(candidate, root) {
+  const relative = path.relative(root, candidate);
+  return (
+    relative === "" ||
+    (relative !== ".." &&
+      !relative.startsWith(`..${path.sep}`) &&
+      !path.isAbsolute(relative))
+  );
+}
+
+function normalizeWorkspaceRoots(entries, cwd) {
+  const roots =
+    Array.isArray(entries) && entries.length > 0 ? entries : [cwd];
+  return stringList(roots).map((entry) => path.resolve(cwd, entry));
+}
+
+/**
+ * Resolve and authorize one built-in agent file-tool path.
+ *
+ * The workspace roots are always allowed. A normalized sandbox policy may add
+ * explicit read/write roots and may deny narrower paths. Both existing targets
+ * and the nearest existing ancestor are realpath-resolved, so an in-workspace
+ * symlink/junction cannot redirect a read or write outside the declared roots.
+ *
+ * @returns {{
+ *   ok:boolean,
+ *   path?:string,
+ *   canonicalPath?:string,
+ *   reason?:string,
+ *   error?:string
+ * }}
+ */
+export function resolveSandboxPolicyPath(
+  requestedPath,
+  {
+    access = "read",
+    cwd = process.cwd(),
+    workspaceRoots = null,
+    sandbox = null,
+    policy = sandbox?.policy || null,
+    fsImpl = null,
+  } = {},
+) {
+  if (access !== "read" && access !== "write") {
+    return {
+      ok: false,
+      reason: "invalid-access",
+      error: `Unsupported filesystem access mode: ${access}`,
+    };
+  }
+  if (
+    typeof requestedPath !== "string" ||
+    requestedPath.length === 0 ||
+    requestedPath.includes("\0")
+  ) {
+    return {
+      ok: false,
+      reason: "invalid-path",
+      error: "A non-empty filesystem path is required",
+    };
+  }
+
+  const resolvedCwd = path.resolve(cwd);
+  const resolvedPath = path.resolve(resolvedCwd, requestedPath);
+  const effectiveFs = fsImpl || fs;
+  const normalizedPolicy = policy || {};
+  const policyAllows =
+    access === "write"
+      ? normalizedPolicy.allowWrite
+      : normalizedPolicy.allowRead;
+  const policyDenies =
+    access === "write"
+      ? normalizedPolicy.denyWrite
+      : normalizedPolicy.denyRead;
+  const allowedInputs = [
+    ...normalizeWorkspaceRoots(workspaceRoots, resolvedCwd),
+    ...resolvePolicyPaths(policyAllows, resolvedCwd),
+  ];
+  const deniedInputs = resolvePolicyPaths(policyDenies, resolvedCwd);
+
+  try {
+    const canonicalPath = canonicalPolicyPath(resolvedPath, effectiveFs);
+    const allowedRoots = allowedInputs.map((root) =>
+      canonicalPolicyPath(root, effectiveFs),
+    );
+    if (!allowedRoots.some((root) => pathIsWithin(canonicalPath, root))) {
+      return {
+        ok: false,
+        path: resolvedPath,
+        canonicalPath,
+        reason: "outside-workspace",
+        error: `${access} path resolves outside the allowed workspace roots`,
+      };
+    }
+
+    const deniedRoots = deniedInputs.map((root) =>
+      canonicalPolicyPath(root, effectiveFs),
+    );
+    if (deniedRoots.some((root) => pathIsWithin(canonicalPath, root))) {
+      return {
+        ok: false,
+        path: resolvedPath,
+        canonicalPath,
+        reason: "denied-by-policy",
+        error: `${access} path is denied by the sandbox filesystem policy`,
+      };
+    }
+
+    return { ok: true, path: resolvedPath, canonicalPath };
+  } catch (error) {
+    return {
+      ok: false,
+      path: resolvedPath,
+      reason: "realpath-failed",
+      error: `Unable to safely resolve filesystem path: ${error.message}`,
+    };
+  }
+}
+
 export function normalizeSandboxPolicy(settings = {}, cwd = process.cwd()) {
   const filesystem = settings.filesystem || {};
   const network = settings.network || {};

package/src/lib/agent-team/team-runner.js

@@ -14,6 +14,8 @@
  * status panel. A total-time / total-task budget bounds a runaway graph.
  */
 
+import { emitHooksV2Event } from "../hooks-v2-producers.js";
+
 export class TeamRunner {
   /**
    * @param {TaskLeaseRegistry} registry
@@ -33,6 +35,8 @@ export class TeamRunner {
     // Lease-renewal heartbeat cadence while a task runs (default ttl/3).
     this.renewEveryMs = opts.renewEveryMs;
     this.onEvent = typeof opts.onEvent === "function" ? opts.onEvent : () => {};
+    this.emitHook =
+      typeof opts.emitHook === "function" ? opts.emitHook : emitHooksV2Event;
     this.maxTasks = opts.maxTasks > 0 ? opts.maxTasks : 1000;
     this._now = opts.now || registry._now || (() => Date.now());
     // Team-wide token/USD/time/task budget (null → unbounded). Consulted before
@@ -80,8 +84,26 @@ export class TeamRunner {
       return m;
     }
     if (m.state === state) return m; // no transition
+    const previousState = m.state;
     m.state = state;
     this._emit("teammate:state", { holder, state, ...extra });
+    // Initial registration starts in `idle`; the hook is reserved for a real
+    // transition back to idle after a teammate has participated in the run.
+    if (state === "idle" && previousState !== null) {
+      try {
+        this.emitHook("TeammateIdle", {
+          schema_version: 1,
+          holder,
+          state,
+          previous_state: previousState,
+          completed: m.completed,
+          failed: m.failed,
+          ...extra,
+        });
+      } catch {
+        /* hook observer is best-effort */
+      }
+    }
     return m;
   }
 

package/src/lib/artifact-store.js

@@ -40,6 +40,41 @@ export const MAX_ARTIFACT_BYTES = 100 * 1024 * 1024; // 100 MB
 /** Default retention before `clean` removes an artifact. */
 export const DEFAULT_TTL_DAYS = 30;
 
+/**
+ * Metadata safe to return across the agent/session protocol boundary.
+ *
+ * The persisted index deliberately retains sourcePath for local artifact
+ * management, but absolute source paths are host details and must not enter
+ * model transcripts or remote-session payloads.
+ */
+export function publicArtifactMetadata(entry) {
+  if (!entry || typeof entry !== "object") return null;
+  const {
+    id,
+    title,
+    kind,
+    mime,
+    size,
+    sha256,
+    file,
+    sessionId,
+    createdAt,
+    expiresAt,
+  } = entry;
+  return {
+    id,
+    title,
+    kind,
+    mime,
+    size,
+    sha256,
+    file,
+    sessionId,
+    createdAt,
+    expiresAt,
+  };
+}
+
 const MIME_BY_EXT = Object.freeze({
   ".md": "text/markdown",
   ".markdown": "text/markdown",

package/src/lib/async-hook-supervisor.cjs

@@ -32,7 +32,10 @@
  * testable with fake child processes (no real shell).
  */
 
-const { tryParseDecision } = require("./hook-runner.cjs");
+const {
+  tryParseDecision,
+  resolveHookSandboxPolicy,
+} = require("./hook-runner.cjs");
 
 const DEFAULT_TIMEOUT_MS = 60000;
 const MAX_TIMEOUT_MS = 600000;
@@ -359,6 +362,7 @@ class AsyncHookSupervisor {
 
     let child;
     try {
+      const sandboxPolicy = resolveHookSandboxPolicy(hook, opts);
       const spawnOptions = {
         cwd: opts.cwd || process.cwd(),
         shell: true,
@@ -370,6 +374,7 @@ class AsyncHookSupervisor {
           ...process.env,
           CLAUDE_HOOK_EVENT: hook.event || payload.hook_event_name || "",
         },
+        ...(sandboxPolicy ? { sandboxPolicy } : {}),
       };
       if (typeof this._deps.run !== "function") {
         throw new Error("async hook process runner unavailable");
@@ -384,10 +389,15 @@ class AsyncHookSupervisor {
         pluginSource: hook.pluginSource || null,
       });
     } catch (err) {
+      const sandboxDenied =
+        err?.code === "ERR_PROCESS_SANDBOX_BOUNDARY_UNSATISFIED";
       this._record(hook, {
         ok: false,
         exitCode: null,
-        error: `hook spawn failed: ${err.message}`,
+        error: sandboxDenied
+          ? `hook sandbox denied: ${err.message}`
+          : `hook spawn failed: ${err.message}`,
+        sandboxDenied,
         started,
       });
       return;
@@ -483,6 +493,7 @@ class AsyncHookSupervisor {
       error: fields.error || null,
       additionalContext: fields.additionalContext || null,
       blocked: !!fields.blocked,
+      ...(fields.sandboxDenied === true ? { sandboxDenied: true } : {}),
       asyncRewake: hook.asyncRewake === true,
       ts: now,
       ms: fields.started != null ? now - fields.started : 0,

package/src/lib/audit-mtc.js

@@ -322,11 +322,12 @@ export function closeBatch(dir, opts = {}) {
   // across processes. Without it, two concurrent closes (e.g. overlapping
   // `cc audit mtc reconcile` runs) both scan the same staging events, allocate
   // the same batch id, and the defensive rmSync(finalDir) lets the second
-  // silently overwrite the first's audit batch. Best-effort lock (never hangs);
-  // generous timeout since the section includes Merkle assembly + signing.
+  // silently overwrite the first's audit batch. Audit ledger state is critical:
+  // bounded contention must fail closed rather than assemble an unlocked batch.
   ensureDirs(dir);
   return withFileLock(batchesDir(dir), () => _closeBatchImpl(dir, opts), {
     timeoutMs: 15000,
+    failIfUnavailable: true,
   });
 }
 

package/src/lib/background-agent-supervisor.js

@@ -20,6 +20,7 @@ import {
   finishAgentWorktree,
   validateAgentWorktree,
 } from "./agent-worktree.js";
+import { rejectPendingBackgroundInteractions } from "./background-interaction-journal.js";
 import executionBroker from "./process-execution-broker/index.js";
 
 export const DEFAULT_HEARTBEAT_INTERVAL_MS = 5000;
@@ -464,6 +465,67 @@ export function effectiveBackgroundAgentState(state, options = {}) {
         /* best-effort */
       }
     }
+    if (
+      options.persist !== false &&
+      state.sessionId &&
+      !isSameProcess(state.pid, state.startedAt)
+    ) {
+      const pending = state.pendingQuestion;
+      const requestId = pending?.requestId || pending?.intId;
+      try {
+        const recovery = rejectPendingBackgroundInteractions(
+          state.sessionId,
+          state.id,
+          {
+            fallbackRequest: requestId
+              ? {
+                  requestId,
+                  binding: pending.binding,
+                  payload: {
+                    kind: "question",
+                    question: pending.question || pending.prompt || "",
+                    options: pending.options || null,
+                    multiSelect: pending.multiSelect === true,
+                    timeoutMs: pending.timeoutMs,
+                  },
+                  createdAt: pending.askedAt,
+                }
+              : null,
+            code: "INTERACTION_WORKER_LOST",
+            message:
+              "The background worker was lost before the interaction settled",
+          },
+        );
+        const recoveredRecord = requestId
+          ? recovery.journal.get(requestId)
+          : null;
+        if (
+          recovery.changed ||
+          (recoveredRecord && recoveredRecord.status !== "pending")
+        ) {
+          next = {
+            ...next,
+            phase: null,
+            pendingQuestion: null,
+            interactionRecovery: {
+              status: "rejected",
+              requestIds: recovery.rejected.map((record) => record.requestId),
+              recoveredAt: t,
+            },
+          };
+        }
+      } catch (error) {
+        next = {
+          ...next,
+          interactionRecovery: {
+            status: "failed",
+            code: error?.code || "INTERACTION_RECOVERY_FAILED",
+            message: error?.message || String(error),
+            recoveredAt: t,
+          },
+        };
+      }
+    }
     if (options.persist !== false) {
       try {
         writeBackgroundAgentState(next);
@@ -838,11 +900,17 @@ export function launchBackgroundAgent({
   };
   writeBackgroundAgentState(state);
   let child;
+  let workerLogFd;
   try {
+    // Preserve loader/bootstrap failures that happen before the worker can
+    // open its own append handle. This also gives detached Windows targets
+    // concrete inheritable stdout/stderr handles instead of relying on the
+    // hosted process' possibly absent standard handles.
+    workerLogFd = openSync(job.logFile, "a");
     child = _deps.spawn(process.execPath, [worker, jobFile], {
       cwd,
       detached: true,
-      stdio: "ignore",
+      stdio: ["ignore", workerLogFd, workerLogFd],
       windowsHide: true,
       origin: "background-agent:worker",
       policy: "allow",
@@ -853,6 +921,10 @@ export function launchBackgroundAgent({
     rmSync(jobFile, { force: true });
     rmSync(statePath(id), { force: true });
     throw error;
+  } finally {
+    if (Number.isInteger(workerLogFd)) {
+      closeSync(workerLogFd);
+    }
   }
   // Async spawn failures (EPERM, cwd raced away between the check and the
   // spawn, …) arrive as an 'error' event on the detached child. Reap them
@@ -875,13 +947,42 @@ export function launchBackgroundAgent({
         /* best-effort */
       }
     });
+    child.on("exit", (code, signal) => {
+      try {
+        rmSync(jobFile, { force: true });
+        const current = readBackgroundAgentState(id);
+        // A healthy worker persists completed/failed before exiting. If the
+        // process (or its platform wrapper) exits while the state still says
+        // running, bootstrap or finalization failed and the session must not
+        // remain a phantom live task until heartbeat reconciliation.
+        if (current && current.status === "running") {
+          writeBackgroundAgentState({
+            ...current,
+            status: "failed",
+            endedAt: Date.now(),
+            exitCode: Number.isInteger(code) ? code : null,
+            signal: signal || null,
+            lostReason: `worker-exited-before-finalize: exit=${
+              Number.isInteger(code) ? code : "null"
+            } signal=${signal || "none"}`,
+          });
+        }
+      } catch {
+        /* best-effort */
+      }
+    });
   }
   child.unref();
   const current = readBackgroundAgentState(id) || state;
   const withPid = {
     ...current,
-    pid: child.pid,
-    workerPid: child.pid,
+    // A platform wrapper (notably the Windows Job Object adapter) can return
+    // from spawn after the real worker has already claimed the state file.
+    // Preserve that authoritative process.pid instead of racing it back to
+    // the wrapper pid. With an ordinary direct spawn both fields are still
+    // null here and are initialized from child.pid as before.
+    pid: current.pid ?? child.pid,
+    workerPid: current.workerPid ?? child.pid,
   };
   writeBackgroundAgentState(withPid);
   return withPid;