chainlesschain 0.163.8 → 0.165.1

package/src/lib/session-anti-rollback-anchor.js

@@ -35,6 +35,17 @@ export const SESSION_ANTI_ROLLBACK_DETECTED_CODE =
 export const SESSION_ANTI_ROLLBACK_UNAVAILABLE_CODE =
   "CC_SESSION_ANTI_ROLLBACK_UNAVAILABLE";
 
+// Test-only seams for deterministic durability failures. Production callers
+// never assign these hooks; keeping them immediately before the two fsync
+// boundaries lets tests exercise the real append and rollback path without
+// replacing node:fs for the namespace or lock stores.
+export const _sessionAntiRollbackFaultHooks = Object.seal({
+  afterRecordOpen: null,
+  beforeRecordFsync: null,
+  beforeRecordDirectoryFsync: null,
+  beforeRecordRollback: null,
+});
+
 const NAMESPACE_VERSION = 1;
 const ANCHOR_SCHEMA = "chainlesschain.session-anti-rollback-anchor/v1";
 const GENERATION_SCHEMA = "chainlesschain.session-generation-authority/v1";
@@ -59,12 +70,19 @@ function anchorError(code, message, cause = null, details = {}) {
 
 function unavailable(cause, filePath = null) {
   if (cause?.code === SESSION_ANTI_ROLLBACK_DETECTED_CODE) return cause;
-  return anchorError(
+  const error = anchorError(
     SESSION_ANTI_ROLLBACK_UNAVAILABLE_CODE,
     "Session anti-rollback witness is unavailable; canonical session access is denied",
     cause,
     filePath ? { filePath } : {},
   );
+  for (const key of ["commitState", "rollbackState", "persistenceTarget"]) {
+    if (cause?.[key] != null) error[key] = cause[key];
+  }
+  if (cause?.rollbackCause) {
+    error.rollbackErrorCode = cause.rollbackCause?.code || null;
+  }
+  return error;
 }
 
 function rollback(sessionId, message, current = null, candidate = null) {
@@ -628,11 +646,173 @@ function appendRecord(location, record) {
   return appendRecordAtPath(location.recordPath, record, null);
 }
 
+function settleExistingRecord(location, record) {
+  if (isAffectedWindowsZeroDeviceStatRuntime()) {
+    return withTrustedFileParentSync(
+      fs,
+      location.recordPath,
+      ({ canonicalPath, parentDevice }) =>
+        settleExistingRecordAtPath(canonicalPath, record, parentDevice),
+    );
+  }
+  return settleExistingRecordAtPath(location.recordPath, record, null);
+}
+
+function runFaultHook(name, payload) {
+  if (process.env.CC_SESSION_ANTI_ROLLBACK_FAULT_INJECTION !== "1") return;
+  const hook = _sessionAntiRollbackFaultHooks[name];
+  if (typeof hook === "function") hook(payload);
+}
+
+function fsyncDirectory(directory) {
+  const descriptor = fs.openSync(directory, "r");
+  try {
+    fs.fsyncSync(descriptor);
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+
+function settleExistingRecordAtPath(recordPath, record, parentDevice) {
+  let descriptor = null;
+  try {
+    let flags = fs.constants.O_RDWR;
+    if (typeof fs.constants.O_NOFOLLOW === "number") {
+      flags |= fs.constants.O_NOFOLLOW;
+    }
+    descriptor = fs.openSync(recordPath, flags);
+    const opened = fs.fstatSync(descriptor, { bigint: true });
+    const published = fs.lstatSync(recordPath, { bigint: true });
+    const identityMatches =
+      parentDevice === null
+        ? String(opened.dev) === String(published.dev) &&
+          String(opened.ino) === String(published.ino)
+        : samePathHandleStableFileIdentity(published, opened, parentDevice);
+    if (
+      !opened.isFile() ||
+      published.isSymbolicLink() ||
+      !published.isFile() ||
+      !identityMatches
+    ) {
+      throw new Error("session anti-rollback record identity changed");
+    }
+    runFaultHook("beforeRecordFsync", {
+      recordPath,
+      record,
+      createsRecord: false,
+      unchanged: true,
+    });
+    fs.fsyncSync(descriptor);
+    const after = fs.lstatSync(recordPath, { bigint: true });
+    const afterIdentityMatches =
+      parentDevice === null
+        ? String(opened.dev) === String(after.dev) &&
+          String(opened.ino) === String(after.ino)
+        : samePathHandleStableFileIdentity(after, opened, parentDevice);
+    if (after.isSymbolicLink() || !after.isFile() || !afterIdentityMatches) {
+      throw new Error("session anti-rollback record identity changed");
+    }
+    // A complete revision-1 line can survive a process death before either
+    // the file fsync or the first directory-entry barrier. Replaying the exact
+    // candidate must settle both boundaries before reporting success.
+    if (record.revision === "1" && process.platform !== "win32") {
+      runFaultHook("beforeRecordDirectoryFsync", {
+        recordPath,
+        record,
+        createsRecord: false,
+        recoveredCompleteRecord: true,
+      });
+      fsyncDirectory(path.dirname(recordPath));
+    }
+  } catch (cause) {
+    if (cause && typeof cause === "object" && !cause.commitState) {
+      cause.commitState = "unknown";
+      cause.rollbackState = "not-required";
+      cause.persistenceTarget = recordPath;
+    }
+    throw cause;
+  } finally {
+    if (descriptor !== null) fs.closeSync(descriptor);
+  }
+}
+
+function rollbackRecordAppend({
+  recordPath,
+  opened,
+  initialSize,
+  createsRecord,
+  parentDevice,
+}) {
+  runFaultHook("beforeRecordRollback", {
+    recordPath,
+    initialSize,
+    createsRecord,
+  });
+  let descriptor = null;
+  try {
+    let flags = fs.constants.O_RDWR;
+    if (typeof fs.constants.O_NOFOLLOW === "number") {
+      flags |= fs.constants.O_NOFOLLOW;
+    }
+    descriptor = fs.openSync(recordPath, flags);
+    const rollbackOpened = fs.fstatSync(descriptor, { bigint: true });
+    const published = fs.lstatSync(recordPath, { bigint: true });
+    const identityMatches =
+      !published.isSymbolicLink() &&
+      published.isFile() &&
+      String(opened.dev) === String(rollbackOpened.dev) &&
+      String(opened.ino) === String(rollbackOpened.ino) &&
+      (parentDevice === null
+        ? String(rollbackOpened.dev) === String(published.dev) &&
+          String(rollbackOpened.ino) === String(published.ino)
+        : samePathHandleStableFileIdentity(
+            published,
+            rollbackOpened,
+            parentDevice,
+          ));
+    if (!identityMatches) {
+      throw new Error("session anti-rollback rollback record identity changed");
+    }
+    fs.ftruncateSync(descriptor, initialSize);
+    fs.fsyncSync(descriptor);
+  } finally {
+    if (descriptor !== null) fs.closeSync(descriptor);
+  }
+  if (createsRecord) {
+    fs.unlinkSync(recordPath);
+    if (process.platform !== "win32") {
+      fsyncDirectory(path.dirname(recordPath));
+    }
+  }
+}
+
+function rollbackEmptyCreatedRecord(recordPath) {
+  const published = fs.lstatSync(recordPath, { bigint: true });
+  if (
+    published.isSymbolicLink() ||
+    !published.isFile() ||
+    published.size !== 0n
+  ) {
+    throw new Error(
+      "session anti-rollback unverified first record cannot be removed",
+    );
+  }
+  fs.unlinkSync(recordPath);
+  if (process.platform !== "win32") {
+    fsyncDirectory(path.dirname(recordPath));
+  }
+}
+
 function appendRecordAtPath(recordPath, record, parentDevice) {
   let descriptor = null;
+  let recordOpened = false;
+  let createsRecord = false;
+  let requiresDirectoryPublication = false;
+  let initialSize = 0;
+  let opened = null;
   try {
     let flags = fs.constants.O_WRONLY | fs.constants.O_APPEND;
-    const createsRecord = !fs.existsSync(recordPath);
+    createsRecord = !fs.existsSync(recordPath);
     if (createsRecord) {
       flags |= fs.constants.O_CREAT | fs.constants.O_EXCL;
     }
@@ -640,7 +820,18 @@ function appendRecordAtPath(recordPath, record, parentDevice) {
       flags |= fs.constants.O_NOFOLLOW;
     }
     descriptor = fs.openSync(recordPath, flags, 0o600);
-    const opened = fs.fstatSync(descriptor, { bigint: true });
+    recordOpened = true;
+    runFaultHook("afterRecordOpen", { recordPath, record, createsRecord });
+    opened = fs.fstatSync(descriptor, { bigint: true });
+    if (!opened.isFile()) {
+      throw new Error("session anti-rollback append target is not a file");
+    }
+    initialSize = Number(opened.size);
+    // A previous process can die immediately after O_CREAT|O_EXCL and leave a
+    // visible zero-byte entry before its parent-directory fsync. Treat that
+    // exact crash residue like a first publication: the retry must flush the
+    // directory entry after it writes and fsyncs revision 1.
+    requiresDirectoryPublication = createsRecord || opened.size === 0n;
     const payload = Buffer.from(`${JSON.stringify(record)}\n`, "utf8");
     let offset = 0;
     while (offset < payload.length) {
@@ -657,6 +848,11 @@ function appendRecordAtPath(recordPath, record, parentDevice) {
       }
       offset += written;
     }
+    runFaultHook("beforeRecordFsync", {
+      recordPath,
+      record,
+      createsRecord,
+    });
     fs.fsyncSync(descriptor);
     const published = fs.lstatSync(recordPath, { bigint: true });
     const identityMatches =
@@ -667,14 +863,64 @@ function appendRecordAtPath(recordPath, record, parentDevice) {
     if (published.isSymbolicLink() || !published.isFile() || !identityMatches) {
       throw new Error("session anti-rollback record identity changed");
     }
-    if (createsRecord && process.platform !== "win32") {
+    if (requiresDirectoryPublication && process.platform !== "win32") {
       const directoryDescriptor = fs.openSync(path.dirname(recordPath), "r");
       try {
+        runFaultHook("beforeRecordDirectoryFsync", {
+          recordPath,
+          record,
+          createsRecord,
+          recoveredEmptyRecord: !createsRecord,
+        });
         fs.fsyncSync(directoryDescriptor);
       } finally {
         fs.closeSync(directoryDescriptor);
       }
     }
+  } catch (cause) {
+    // A completed JSON line is immediately readable even when its fsync (or a
+    // first-record directory fsync) reports failure. Best-effort rollback to
+    // the pre-append byte boundary prevents that unacknowledged record from
+    // becoming the next readback authority in the still-running process. If
+    // this was the first record, remove the empty entry and durably publish
+    // that removal on POSIX so a retry recreates and flushes the entry again.
+    try {
+      if (descriptor !== null) {
+        fs.closeSync(descriptor);
+        descriptor = null;
+      }
+      if (opened !== null) {
+        rollbackRecordAppend({
+          recordPath,
+          opened,
+          initialSize,
+          createsRecord,
+          parentDevice,
+        });
+      } else if (recordOpened && createsRecord) {
+        rollbackEmptyCreatedRecord(recordPath);
+      }
+      if (cause && typeof cause === "object") {
+        cause.commitState = "not-committed";
+        cause.rollbackState = "restored";
+        cause.persistenceTarget = recordPath;
+      }
+    } catch (rollbackCause) {
+      if (cause && typeof cause === "object") {
+        cause.rollbackCause = rollbackCause;
+        cause.commitState = "unknown";
+        cause.rollbackState = "failed";
+        cause.persistenceTarget = recordPath;
+      }
+    }
+    if (cause && typeof cause === "object" && !cause.commitState) {
+      // open/fstat failures happen before any payload write. A successfully
+      // opened first entry is removed above before reporting this state.
+      cause.commitState = "not-committed";
+      cause.rollbackState = "not-required";
+      cause.persistenceTarget = recordPath;
+    }
+    throw cause;
   } finally {
     if (descriptor !== null) fs.closeSync(descriptor);
   }
@@ -708,7 +954,18 @@ export function publishSessionAntiRollbackAnchor(
           current.headHash === candidate.headHash &&
           current.eventCount === candidate.eventCount &&
           current.deletedAtMs === candidate.deletedAtMs;
-        if (unchanged) return current;
+        // Revision 1 is the only record that can carry an unsettled first
+        // directory entry. Settle it before either acknowledging an exact
+        // replay or advancing directly to a proven successor.
+        if (current?.revision === "1") {
+          settleExistingRecord(location, current);
+        }
+        if (unchanged) {
+          if (current.revision !== "1") {
+            settleExistingRecord(location, current);
+          }
+          return current;
+        }
         if (current === null) ensureNamespaceEntry(location);
         const core = recordCore(
           location,

package/src/lib/shell-approval.js

@@ -32,6 +32,129 @@ import {
   resolveInstallPolicy,
 } from "./install-command-policy.js";
 
+const SHELL_EXECUTION_DESCRIPTOR_VERSION =
+  "chainlesschain.shell-execution-descriptor/v1";
+
+function deepFreezeData(value, seen = new WeakSet()) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value))
+    return value;
+  if (seen.has(value)) return value;
+  seen.add(value);
+  for (const child of Object.values(value)) deepFreezeData(child, seen);
+  return Object.freeze(value);
+}
+
+function cloneData(value, label) {
+  try {
+    return structuredClone(value);
+  } catch (cause) {
+    throw new Error(`${label} must be structured-cloneable`, { cause });
+  }
+}
+
+/** Capture only the declared run_shell data contract and freeze it. */
+export function snapshotShellExecutionArgs(args = {}, fallbackCommand = null) {
+  const source = args && typeof args === "object" ? args : {};
+  const snapshot = {
+    command:
+      source.command !== undefined
+        ? cloneData(source.command, "command")
+        : cloneData(fallbackCommand ?? null, "command"),
+  };
+  for (const key of ["cwd", "shell", "run_in_background", "timeout"]) {
+    if (source[key] !== undefined) snapshot[key] = cloneData(source[key], key);
+  }
+  return deepFreezeData(snapshot);
+}
+
+/**
+ * Build the bounded, secret-free data tuple shown to ApprovalGate and later
+ * consumed at dispatch. Runtime objects/callbacks never enter this descriptor.
+ */
+export function createShellExecutionDescriptor({
+  args,
+  workspace = null,
+  shellInvocation = null,
+  pluginInvocation = null,
+  pluginSandboxPolicy = null,
+  pluginSandboxExecutionContract = null,
+  sandbox = null,
+  environmentRef = null,
+} = {}) {
+  const shellArgs = snapshotShellExecutionArgs(args);
+  const descriptor = {
+    ...shellArgs,
+    execution: {
+      version: SHELL_EXECUTION_DESCRIPTOR_VERSION,
+      mode: shellArgs.run_in_background === true ? "background" : "foreground",
+      workspace: workspace || null,
+      shell: shellInvocation
+        ? {
+            kind: shellInvocation.kind || null,
+            useDefaultShell: shellInvocation.useDefaultShell === true,
+            file: shellInvocation.file || null,
+            argv: Array.isArray(shellInvocation.argv)
+              ? [...shellInvocation.argv]
+              : [],
+          }
+        : null,
+      plugin: pluginInvocation
+        ? {
+            command: pluginInvocation.command || null,
+            id: pluginInvocation.pluginId || null,
+            version: pluginInvocation.pluginVersion || null,
+            source: pluginInvocation.pluginSource || null,
+            bin: pluginInvocation.binName || null,
+            path: pluginInvocation.binPath || null,
+            runtime: pluginInvocation.runtime || null,
+            argv: Array.isArray(pluginInvocation.args)
+              ? [...pluginInvocation.args]
+              : [],
+            executableSha256:
+              pluginInvocation.executableIdentity?.sha256 || null,
+            sandboxPolicy: pluginSandboxPolicy
+              ? cloneData(pluginSandboxPolicy, "pluginSandboxPolicy")
+              : null,
+            sandboxExecution: pluginSandboxExecutionContract
+              ? {
+                  version:
+                    pluginSandboxExecutionContract.contractVersion || null,
+                  kind: pluginSandboxExecutionContract.kind || null,
+                  pluginRoot: pluginSandboxExecutionContract.pluginRoot || null,
+                  workingDirectory:
+                    pluginSandboxExecutionContract.workingDirectory || null,
+                  runtimePath:
+                    pluginSandboxExecutionContract.runtimePath || null,
+                  entrySha256:
+                    pluginSandboxExecutionContract.entryIdentity?.sha256 ||
+                    null,
+                  runtimeSha256:
+                    pluginSandboxExecutionContract.runtimeIdentity?.sha256 ||
+                    null,
+                }
+              : null,
+          }
+        : null,
+      sandbox: sandbox ? cloneData(sandbox, "sandbox") : null,
+      environment: environmentRef
+        ? cloneData(environmentRef, "environmentRef")
+        : null,
+    },
+  };
+  return deepFreezeData(descriptor);
+}
+
+export function shellApprovalAction(riskLevel) {
+  return riskLevel ? `${riskLevel}-risk` : null;
+}
+
+export function commitShellApprovalSideEffects(result) {
+  const audit = result?.installAudit || null;
+  if (!audit) return false;
+  recordInstallCommandAudit(audit.entry, audit.options || {});
+  return true;
+}
+
 export const SHELL_TO_RISK = {
   allow: RISK.LOW,
   warn: RISK.MEDIUM,
@@ -41,10 +164,16 @@ export const SHELL_TO_RISK = {
 
 export async function evaluateShellCommandWithApproval({
   command,
+  args = null,
   sessionId = null,
   approvalGate = null,
   shellPolicyOptions = {},
   installPolicy = null,
+  workspace = null,
+  targetEnv = null,
+  policyEnv = process.env,
+  policyVersion = null,
+  deferSideEffects = false,
 } = {}) {
   const shellPolicy = sharedShellPolicy.evaluateShellCommandPolicy(
     command,
@@ -62,8 +191,9 @@ export async function evaluateShellCommandWithApproval({
   // CC_INSTALL_RISK_FLOOR) so the real run_shell path picks it up with no extra
   // wiring. Both unset → disabled → the block below is skipped, byte-unchanged.
   const effectiveInstallPolicy =
-    installPolicy || resolveInstallPolicy({ env: process.env });
+    installPolicy || resolveInstallPolicy({ env: policyEnv });
   let install = null;
+  let installAudit = null;
   if (effectiveInstallPolicy && effectiveInstallPolicy.enabled) {
     const cls = classifyCodeAcquisition(command);
     if (cls.flagged) {
@@ -72,8 +202,8 @@ export async function evaluateShellCommandWithApproval({
         riskLevel = applyRiskFloor(riskLevel, effectiveInstallPolicy.riskFloor);
       }
       if (effectiveInstallPolicy.audit) {
-        recordInstallCommandAudit(
-          {
+        installAudit = {
+          entry: {
             command,
             shellDecision: shellPolicy.decision,
             riskLevel,
@@ -82,8 +212,12 @@ export async function evaluateShellCommandWithApproval({
             global: hasGlobalInstall(cls),
             sessionId,
           },
-          effectiveInstallPolicy.auditOpts || {},
-        );
+          options: effectiveInstallPolicy.auditOpts || {},
+        };
+        if (!deferSideEffects) {
+          recordInstallCommandAudit(installAudit.entry, installAudit.options);
+          installAudit = null;
+        }
       }
     }
   }
@@ -100,6 +234,7 @@ export async function evaluateShellCommandWithApproval({
       riskLevel,
       policy: null,
       install,
+      installAudit,
     };
   }
 
@@ -114,14 +249,29 @@ export async function evaluateShellCommandWithApproval({
       riskLevel,
       policy: null,
       install,
+      installAudit,
     };
   }
 
+  const operationArgs = args
+    ? Object.isFrozen(args)
+      ? args
+      : deepFreezeData(cloneData(args, "run_shell approval args"))
+    : snapshotShellExecutionArgs({ command });
+  const effectivePolicyVersion =
+    typeof policyVersion === "string" && policyVersion
+      ? policyVersion
+      : `shell-policy:${shellPolicy.decision}:${shellPolicy.ruleId || "none"}`;
+  const action = shellApprovalAction(riskLevel);
   const gateResult = await approvalGate.decide({
     sessionId,
     riskLevel,
     tool: "run_shell",
-    args: { command },
+    args: operationArgs,
+    cwd: workspace,
+    targetEnv,
+    policyVersion: effectivePolicyVersion,
+    action,
   });
 
   return {
@@ -133,6 +283,19 @@ export async function evaluateShellCommandWithApproval({
     riskLevel,
     policy: gateResult.policy,
     install,
+    installAudit,
+    authorization: gateResult.authorization || null,
+    authorizationContext: gateResult.authorization
+      ? {
+          tool: "run_shell",
+          action,
+          args: operationArgs,
+          workspace,
+          session: sessionId,
+          targetEnv,
+          policyVersion: effectivePolicyVersion,
+        }
+      : null,
     // Explainability passthrough (autoMode.decisions wrapper attaches these):
     // which gate rule fired and why — surfaced in the permission chain.
     gateReason: gateResult.reason ?? null,

package/src/lib/sub-agent-context.js

@@ -323,6 +323,7 @@ export class SubAgentContext {
     // parent's policy, Plan lock, workspace sandbox, or unattended boundary.
     this._parentAuthority = Object.freeze({
       permissionRules: options.permissionRules || null,
+      permissionRulesProvider: options.permissionRulesProvider || null,
       hostManagedToolPolicy: options.hostManagedToolPolicy || null,
       planManager: options.planManager || null,
       sandbox: options.sandbox || null,
@@ -618,6 +619,9 @@ export class SubAgentContext {
     if (authority.permissionRules) {
       options.permissionRules = authority.permissionRules;
     }
+    if (authority.permissionRulesProvider) {
+      options.permissionRulesProvider = authority.permissionRulesProvider;
+    }
     if (authority.hostManagedToolPolicy) {
       options.hostManagedToolPolicy = authority.hostManagedToolPolicy;
     }