chainlesschain 0.165.3 → 0.165.4

package/src/lib/artifact-store.js

@@ -24,6 +24,7 @@ import fs from "fs";
 import os from "os";
 import path from "path";
 import crypto from "crypto";
+import { withFileLock } from "./with-file-lock.js";
 
 export const ARTIFACT_KINDS = Object.freeze([
   "report",
@@ -62,6 +63,7 @@ export function publicArtifactMetadata(entry) {
     expiresAt,
     immutable,
     recordDigest,
+    lineage,
   } = entry;
   return {
     id,
@@ -76,6 +78,7 @@ export function publicArtifactMetadata(entry) {
     expiresAt,
     immutable: immutable === true,
     recordDigest: recordDigest || null,
+    ...(lineage ? { lineage } : {}),
   };
 }
 
@@ -120,10 +123,36 @@ function normalizeKind(kind) {
   return ARTIFACT_KINDS.includes(k) ? k : "other";
 }
 
+function normalizeLineage(lineage) {
+  if (lineage == null) return null;
+  if (typeof lineage !== "object" || Array.isArray(lineage)) {
+    throw new Error("artifact lineage must be an object");
+  }
+  let normalized;
+  try {
+    normalized = JSON.parse(JSON.stringify(lineage));
+  } catch {
+    throw new Error("artifact lineage must be JSON serializable");
+  }
+  if (
+    !normalized ||
+    typeof normalized !== "object" ||
+    Array.isArray(normalized)
+  ) {
+    throw new Error("artifact lineage must be a JSON object");
+  }
+  return normalized;
+}
+
 export class ArtifactStore {
-  constructor({ dir = null, now = () => Date.now() } = {}) {
+  constructor({
+    dir = null,
+    now = () => Date.now(),
+    indexLock = withFileLock,
+  } = {}) {
     this.dir = dir || artifactsDir();
     this._now = typeof now === "function" ? now : () => now;
+    this._indexLock = indexLock;
   }
 
   _indexFile() {
@@ -138,6 +167,31 @@ export class ArtifactStore {
     fs.mkdirSync(this._filesDir(), { recursive: true });
   }
 
+  _withIndexLock(callback) {
+    this._ensureDirs();
+    return this._indexLock(this._indexFile(), callback, {
+      failIfUnavailable: true,
+      timeoutMs: 30_000,
+      retryMs: 1,
+      maxRetryMs: 8,
+      retryJitterMs: 4,
+    });
+  }
+
+  /**
+   * Run a read-only callback against one locked index generation. The callback
+   * may inspect stored bytes before it returns; all ArtifactStore mutations use
+   * this same lock and therefore cannot replace that generation mid-read.
+   */
+  withIndexSnapshot(callback) {
+    if (typeof callback !== "function") {
+      throw new TypeError("artifact index snapshot requires a callback");
+    }
+    return this._withIndexLock(() =>
+      callback(Object.freeze(this._readEntries())),
+    );
+  }
+
   /**
    * Publish a file as an artifact (copy + metadata row).
    * @param {{ filePath: string, title?: string, kind?: string,
@@ -162,14 +216,16 @@ export class ArtifactStore {
       );
     }
     const body = fs.readFileSync(abs);
-    return this._publishData(body, {
-      fileName: path.basename(abs),
-      title,
-      kind,
-      sessionId,
-      ttlDays,
-      sourcePath: abs,
-    });
+    return this._withIndexLock(() =>
+      this._publishDataUnlocked(body, {
+        fileName: path.basename(abs),
+        title,
+        kind,
+        sessionId,
+        ttlDays,
+        sourcePath: abs,
+      }),
+    );
   }
 
   /**
@@ -191,20 +247,78 @@ export class ArtifactStore {
     if (typeof data !== "string" && !Buffer.isBuffer(data)) {
       throw new Error("publishData requires string or Buffer data");
     }
-    return this._publishData(Buffer.from(data), {
-      fileName,
-      title,
-      kind,
-      mime,
-      sessionId,
-      ttlDays,
-      immutable,
-      recordDigest,
-      sourcePath: null,
+    return this._withIndexLock(() =>
+      this._publishDataUnlocked(Buffer.from(data), {
+        fileName,
+        title,
+        kind,
+        mime,
+        sessionId,
+        ttlDays,
+        immutable,
+        recordDigest,
+        sourcePath: null,
+      }),
+    );
+  }
+
+  /**
+   * Publish generated bytes once for a stable authority digest.
+   *
+   * The strict cross-process index lock makes response-loss retries return the
+   * same metadata row instead of creating duplicate managed artifacts. The
+   * caller still owns the semantic validation of the persisted lineage and
+   * must verifyIntegrity() before treating the returned entry as readable.
+   */
+  publishDataOnce({
+    data,
+    fileName = "artifact.bin",
+    title,
+    kind,
+    mime,
+    sessionId = null,
+    ttlDays,
+    immutable = false,
+    recordDigest,
+    lineage,
+  } = {}) {
+    if (typeof data !== "string" && !Buffer.isBuffer(data)) {
+      throw new Error("publishDataOnce requires string or Buffer data");
+    }
+    const stableDigest = String(recordDigest || "");
+    if (!/^sha256:[a-f0-9]{64}$/u.test(stableDigest)) {
+      throw new Error("publishDataOnce requires a canonical recordDigest");
+    }
+    const normalizedLineage = normalizeLineage(lineage);
+    return this._withIndexLock(() => {
+      const matches = this._readEntries().filter(
+        (entry) => entry.recordDigest === stableDigest,
+      );
+      if (matches.length > 1) {
+        throw new Error(
+          `artifact authority ${stableDigest} has duplicate index rows`,
+        );
+      }
+      if (matches.length === 1) {
+        return Object.freeze({ entry: matches[0], published: false });
+      }
+      const entry = this._publishDataUnlocked(Buffer.from(data), {
+        fileName,
+        title,
+        kind,
+        mime,
+        sessionId,
+        ttlDays,
+        immutable,
+        recordDigest: stableDigest,
+        lineage: normalizedLineage,
+        sourcePath: null,
+      });
+      return Object.freeze({ entry, published: true });
     });
   }
 
-  _publishData(
+  _publishDataUnlocked(
     body,
     {
       fileName,
@@ -215,6 +329,7 @@ export class ArtifactStore {
       ttlDays,
       immutable = false,
       recordDigest = null,
+      lineage = null,
       sourcePath = null,
     },
   ) {
@@ -247,10 +362,15 @@ export class ArtifactStore {
       expiresAt: new Date(createdAt + days * 24 * 60 * 60 * 1000).toISOString(),
       immutable: immutable === true,
       recordDigest: recordDigest ? String(recordDigest) : null,
+      ...(lineage ? { lineage: normalizeLineage(lineage) } : {}),
     };
     this._ensureDirs();
     const storedPath = path.join(this._filesDir(), entry.file);
-    fs.writeFileSync(storedPath, body, { flag: "wx" });
+    fs.writeFileSync(storedPath, body, {
+      flag: "wx",
+      mode: 0o600,
+      flush: true,
+    });
     if (entry.immutable) {
       try {
         fs.chmodSync(storedPath, 0o444);
@@ -259,12 +379,37 @@ export class ArtifactStore {
         // support; immutable here means append-only/no update API, not WORM.
       }
     }
-    fs.appendFileSync(this._indexFile(), JSON.stringify(entry) + "\n", "utf-8");
+    let descriptor = null;
+    try {
+      descriptor = fs.openSync(
+        this._indexFile(),
+        fs.constants.O_WRONLY |
+          fs.constants.O_APPEND |
+          fs.constants.O_CREAT |
+          Number(fs.constants.O_NOFOLLOW || 0),
+        0o600,
+      );
+      const indexStat = fs.fstatSync(descriptor);
+      if (!indexStat.isFile() || Number(indexStat.nlink) !== 1) {
+        throw new Error("artifact index identity is invalid");
+      }
+      fs.writeFileSync(descriptor, `${JSON.stringify(entry)}\n`, "utf-8");
+      fs.fsyncSync(descriptor);
+    } catch (error) {
+      try {
+        this._deleteStoredFile(entry);
+      } catch {
+        /* best-effort rollback of an unpublished stored copy */
+      }
+      throw error;
+    } finally {
+      if (descriptor !== null) fs.closeSync(descriptor);
+    }
     return entry;
   }
 
   /** All (non-corrupt) metadata rows, oldest first. */
-  list({ sessionId } = {}) {
+  _readEntries({ sessionId } = {}) {
     let raw;
     try {
       raw = fs.readFileSync(this._indexFile(), "utf-8");
@@ -285,6 +430,10 @@ export class ArtifactStore {
     return sessionId ? out.filter((e) => e.sessionId === sessionId) : out;
   }
 
+  list(options = {}) {
+    return this._withIndexLock(() => this._readEntries(options));
+  }
+
   /** One entry by id (or null). */
   get(id) {
     return this.list().find((e) => e.id === id) || null;
@@ -348,47 +497,103 @@ export class ArtifactStore {
 
   /** Remove one artifact (file + index row). @returns {boolean} found */
   remove(id) {
-    const entries = this.list();
-    const target = entries.find((e) => e.id === id);
-    if (!target) return false;
-    try {
-      this._deleteStoredFile(target);
-    } catch {
-      /* best-effort — the index row is the source of truth */
-    }
-    this._rewrite(entries.filter((e) => e.id !== id));
-    return true;
+    return this._withIndexLock(() => {
+      const entries = this._readEntries();
+      const matches = entries.filter((entry) => entry.id === id);
+      if (matches.length === 0) return false;
+      if (matches.length > 1) {
+        throw new Error(`artifact id ${id} has duplicate index rows`);
+      }
+      const target = matches[0];
+      this._rewriteUnlocked(entries.filter((entry) => entry.id !== id));
+      try {
+        this._deleteStoredFile(target);
+      } catch {
+        /* best-effort — the locked index generation is the source of truth */
+      }
+      return true;
+    });
   }
 
   /**
-   * Remove expired artifacts (expiresAt in the past).
+   * Low-level legacy primitive for removing expired artifacts.
+   * Official CLI and WebSocket callers must use artifact cleanup settlement so
+   * retries preserve a frozen scope and leave content-free audit evidence.
    * @returns {{ removed: number }}
    */
   cleanupExpired() {
-    const entries = this.list();
-    const now = this._now();
-    const keep = [];
-    let removed = 0;
-    for (const e of entries) {
-      const exp = Date.parse(e.expiresAt || "");
-      if (Number.isFinite(exp) && exp <= now) {
+    return this._withIndexLock(() => {
+      const entries = this._readEntries();
+      const now = this._now();
+      const keep = [];
+      const expired = [];
+      for (const entry of entries) {
+        const exp = Date.parse(entry.expiresAt || "");
+        if (Number.isFinite(exp) && exp <= now) {
+          expired.push(entry);
+        } else {
+          keep.push(entry);
+        }
+      }
+      if (expired.length > 0) this._rewriteUnlocked(keep);
+      for (const entry of expired) {
         try {
-          this._deleteStoredFile(e);
+          this._deleteStoredFile(entry);
         } catch {
-          /* best-effort */
+          /* best-effort — the locked index generation is the source of truth */
         }
-        removed += 1;
-      } else {
-        keep.push(e);
       }
-    }
-    if (removed > 0) this._rewrite(keep);
-    return { removed };
+      return { removed: expired.length };
+    });
   }
 
-  _rewrite(entries) {
+  _rewriteUnlocked(entries) {
     this._ensureDirs();
     const text = entries.map((e) => JSON.stringify(e)).join("\n");
-    fs.writeFileSync(this._indexFile(), text ? text + "\n" : "", "utf-8");
+    const indexFile = this._indexFile();
+    const temporary = `${indexFile}.${process.pid}.${crypto
+      .randomBytes(8)
+      .toString("hex")}.tmp`;
+    let descriptor = null;
+    try {
+      descriptor = fs.openSync(
+        temporary,
+        fs.constants.O_WRONLY |
+          fs.constants.O_CREAT |
+          fs.constants.O_EXCL |
+          Number(fs.constants.O_NOFOLLOW || 0),
+        0o600,
+      );
+      fs.writeFileSync(descriptor, text ? `${text}\n` : "", "utf-8");
+      fs.fsyncSync(descriptor);
+      fs.closeSync(descriptor);
+      descriptor = null;
+      fs.renameSync(temporary, indexFile);
+      this._syncIndexDirectory();
+    } finally {
+      if (descriptor !== null) fs.closeSync(descriptor);
+      try {
+        fs.rmSync(temporary, { force: true });
+      } catch {
+        /* best-effort cleanup of an unpublished index generation */
+      }
+    }
+  }
+
+  _syncIndexDirectory() {
+    let descriptor = null;
+    try {
+      descriptor = fs.openSync(this.dir, "r");
+      fs.fsyncSync(descriptor);
+    } catch (error) {
+      if (
+        process.platform !== "win32" ||
+        !["EACCES", "EINVAL", "ENOTSUP", "EPERM"].includes(error?.code)
+      ) {
+        throw error;
+      }
+    } finally {
+      if (descriptor !== null) fs.closeSync(descriptor);
+    }
   }
 }

package/src/lib/command-lifecycle-report.js

@@ -38,12 +38,16 @@ export const COMMAND_ALIAS_DECISION_POLICY = Object.freeze({
   requiredPlatforms: Object.freeze(["linux", "macos", "windows"]),
 });
 
-// This repository-owned anchor intentionally remains unconfigured until the
-// first public release containing the DELTA lifecycle exporter is published.
-// Updating it requires a reviewed code change with all three exact values.
+// Repository-owned anchor for the first public release containing the complete
+// DELTA lifecycle exporter and repository-probe hardening. Coverage must begin
+// at this exact npm publication boundary; report input cannot override it.
 export const COMMAND_LIFECYCLE_DELTA_RELEASE_POLICY = Object.freeze({
   schema: "chainlesschain.command-lifecycle-delta-release-policy.v1",
-  firstPublicRelease: null,
+  firstPublicRelease: Object.freeze({
+    version: "0.163.4",
+    commitSha: "27ed0ac2005e16ce5ddff53990e85b1d13ea0b1d",
+    npmPublishedAt: "2026-08-10T19:42:11.053Z",
+  }),
   incompatibleReleases: Object.freeze(["0.162.198", "0.163.3"]),
 });
 

package/src/lib/cowork-adapter.js

@@ -108,8 +108,9 @@ async function invokeChatCall(callWrapper, provider, model, call) {
  * @param {string} [options.apiKey] - API key override
  * @param {(request: {call: function, provider: string, model: string}) => Promise<object>} [options.callWrapper]
  *        Optional host boundary around each real provider call. The callback
- *        resolves to a private `{content, usage?}` envelope; callers still
- *        receive only the response string.
+ *        may invoke `call({ signal })` to bind cancellation and resolves to a
+ *        private `{content, usage?}` envelope; callers still receive only the
+ *        response string.
  * @returns {(messages: object[], opts?: object) => Promise<string>}
  */
 export function createChatFn(options = {}) {
@@ -145,9 +146,10 @@ export function createChatFn(options = {}) {
         callWrapper,
         provider,
         currentModel,
-        async () => {
+        async ({ signal = opts.signal || resolved.signal } = {}) => {
           const res = await fetch(`${baseUrl}/api/chat`, {
             method: "POST",
+            signal,
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({
               model: currentModel,
@@ -185,9 +187,10 @@ export function createChatFn(options = {}) {
         callWrapper,
         provider,
         currentModel,
-        async () => {
+        async ({ signal = opts.signal || resolved.signal } = {}) => {
           const res = await fetch(`${baseUrl}/messages`, {
             method: "POST",
+            signal,
             headers: {
               "Content-Type": "application/json",
               "x-api-key": key,
@@ -214,9 +217,10 @@ export function createChatFn(options = {}) {
       callWrapper,
       provider,
       currentModel,
-      async () => {
+      async ({ signal = opts.signal || resolved.signal } = {}) => {
         const res = await fetch(`${baseUrl}/chat/completions`, {
           method: "POST",
+          signal,
           headers: {
             "Content-Type": "application/json",
             Authorization: `Bearer ${key}`,

package/src/lib/cowork-task-runner.js

@@ -518,8 +518,12 @@ export function prepareCoworkMcpRuntime(mcp, options = {}) {
  * @param {string} [options.mcpSessionId] - Stable MCP ledger session for resume
  * @param {string} [options.workflowEffectId] - Canonical durable workflow effect
  * @param {boolean} [options.strictUsageTelemetry] - Require synchronous durable call observers
+ * @param {boolean} [options.managedCheckpoint] - Wrap mutating child tools in workspace transactions
+ * @param {string|null} [options.managedCheckpointStateDir] - Optional transaction state root
+ * @param {string[]} [options.managedCheckpointExclusions] - Explicit uncovered workspace paths
  * @param {function} [options.onUsageBoundary] - Provider-call durable start observer
  * @param {function} [options.onUsageSettlement] - Provider-call durable settlement observer
+ * @param {function} [options.onProviderReceipt] - Provider receipt durable prewrite observer
  * @param {function} [options.onToolCallBoundary] - Tool-call durable start observer
  * @param {function} [options.onToolCallSettlement] - Tool-call durable settlement observer
  * @param {(request: object) => boolean|Promise<boolean>} [options.approveMcpLocalCodeExecution]
@@ -540,8 +544,12 @@ export async function runCoworkTask(options = {}) {
     mcpSessionId = null,
     workflowEffectId = null,
     strictUsageTelemetry = false,
+    managedCheckpoint = false,
+    managedCheckpointStateDir = null,
+    managedCheckpointExclusions = [],
     onUsageBoundary = null,
     onUsageSettlement = null,
+    onProviderReceipt = null,
     onToolCallBoundary = null,
     onToolCallSettlement = null,
     approveMcpLocalCodeExecution = null,
@@ -640,6 +648,7 @@ export async function runCoworkTask(options = {}) {
             strictUsageTelemetry: true,
             onUsageBoundary,
             onUsageSettlement,
+            onProviderReceipt,
             onToolCallBoundary,
             onToolCallSettlement,
           }
@@ -678,6 +687,17 @@ export async function runCoworkTask(options = {}) {
       mcpRuntime.sessionId && mcpRuntime.bindingAllowed
         ? { sessionId: mcpRuntime.sessionId }
         : {};
+    if (managedCheckpoint === true) {
+      loopOptions.managedCheckpoint = true;
+      if (managedCheckpointStateDir) {
+        loopOptions.managedCheckpointStateDir = managedCheckpointStateDir;
+      }
+      if (Array.isArray(managedCheckpointExclusions)) {
+        loopOptions.managedCheckpointExclusions = [
+          ...managedCheckpointExclusions,
+        ];
+      }
+    }
     if (
       Array.isArray(template.shellPolicyOverrides) &&
       template.shellPolicyOverrides.length