chainlesschain 0.165.3 → 0.165.5

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/artifact-workbench-projection.js

@@ -0,0 +1,171 @@
+import { publicArtifactMetadata } from "./artifact-store.js";
+import { readArtifactAccessLedger } from "./artifact-access-ledger.js";
+import { readArtifactCleanupLedger } from "./artifact-cleanup-ledger.js";
+import { readArtifactDeletionLedger } from "./artifact-deletion-ledger.js";
+import {
+  buildArtifactRecoveryPlan,
+  readArtifactOrphanGcLedger,
+} from "./artifact-recovery.js";
+
+export const ARTIFACT_WORKBENCH_PROJECTION_SCHEMA = "cc-artifact-workbench/v1";
+export const MAX_ARTIFACT_WORKBENCH_ACTIVITY = 200;
+
+function returnedResultLineage(lineage) {
+  if (lineage?.schema !== "cc-execution-location-result-artifact-lineage/v1") {
+    return null;
+  }
+  const fields = [
+    "sessionId",
+    "requestId",
+    "reviewDigest",
+    "item",
+    "kind",
+    "mediaType",
+    "byteLength",
+    "sourceDigest",
+  ];
+  if (fields.some((field) => lineage[field] == null)) return null;
+  return Object.freeze(
+    Object.fromEntries(fields.map((field) => [field, lineage[field]])),
+  );
+}
+
+function accessActivity(event) {
+  return Object.freeze({
+    type: "access",
+    occurredAt: event.authorizedAt,
+    artifactId: event.artifactId,
+    artifactSessionId: event.artifactSessionId,
+    recordDigest: event.recordDigest,
+    action: event.action,
+    client: event.client,
+    settlementId: event.accessId,
+    eventDigest: event.eventDigest,
+  });
+}
+
+function deletionActivity(event) {
+  return Object.freeze({
+    type: "deletion",
+    phase: event.phase,
+    occurredAt: event.occurredAt,
+    artifactId: event.artifactId,
+    artifactSessionId: event.artifactSessionId,
+    recordDigest: event.recordDigest,
+    action: event.reason,
+    client: event.client,
+    settlementId: event.deletionId,
+    eventDigest: event.eventDigest,
+  });
+}
+
+function cleanupActivity(event) {
+  return Object.freeze({
+    type: "cleanup",
+    phase: event.phase,
+    occurredAt: event.occurredAt,
+    artifactId: null,
+    artifactSessionId: null,
+    recordDigest: null,
+    action: "expired",
+    client: event.client,
+    settlementId: event.cleanupId,
+    itemCount: event.itemCount,
+    eventDigest: event.eventDigest,
+  });
+}
+
+function orphanGcActivity(event) {
+  return Object.freeze({
+    type: "orphan-gc",
+    phase: event.phase,
+    occurredAt: event.occurredAt,
+    artifactId: null,
+    artifactSessionId: null,
+    recordDigest: null,
+    action: event.decision,
+    client: "administrator",
+    settlementId: event.adjudicationId,
+    outcome: event.outcome,
+    eventDigest: event.eventDigest,
+  });
+}
+
+function occurredAtMs(event) {
+  const parsed = Date.parse(event.occurredAt || "");
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+export function buildArtifactWorkbenchProjection(store, options = {}) {
+  if (!store?.dir) {
+    throw new TypeError("artifact workbench requires an ArtifactStore");
+  }
+  const recovery = (
+    options.buildArtifactRecoveryPlan || buildArtifactRecoveryPlan
+  )(store, options.recoveryOptions || {});
+  const access = (options.readArtifactAccessLedger || readArtifactAccessLedger)(
+    store,
+    options.accessOptions || {},
+  );
+  const deletion = (
+    options.readArtifactDeletionLedger || readArtifactDeletionLedger
+  )(store, options.deletionOptions || {});
+  const cleanup = (
+    options.readArtifactCleanupLedger || readArtifactCleanupLedger
+  )(store, options.cleanupOptions || {});
+  const orphanGc = (
+    options.readArtifactOrphanGcLedger || readArtifactOrphanGcLedger
+  )(store, options.orphanGcOptions || {});
+  const accessByArtifact = new Map();
+  for (const event of access.events) {
+    const events = accessByArtifact.get(event.artifactId) || [];
+    events.push(event);
+    accessByArtifact.set(event.artifactId, events);
+  }
+  const artifacts = store.list().map((entry) => {
+    const metadata = publicArtifactMetadata(entry);
+    const accesses = accessByArtifact.get(entry.id) || [];
+    const latestAccess = accesses.at(-1) || null;
+    return Object.freeze({
+      ...metadata,
+      returnedResult: returnedResultLineage(metadata.lineage),
+      history: Object.freeze({
+        accessCount: accesses.length,
+        latestAccess: latestAccess
+          ? Object.freeze({
+              action: latestAccess.action,
+              client: latestAccess.client,
+              authorizedAt: latestAccess.authorizedAt,
+              eventDigest: latestAccess.eventDigest,
+            })
+          : null,
+      }),
+    });
+  });
+  const allActivity = [
+    ...access.events.map(accessActivity),
+    ...deletion.events.map(deletionActivity),
+    ...cleanup.events.map(cleanupActivity),
+    ...orphanGc.events.map(orphanGcActivity),
+  ].sort((left, right) => {
+    const time = occurredAtMs(right) - occurredAtMs(left);
+    return time || right.eventDigest.localeCompare(left.eventDigest);
+  });
+  const activity = allActivity.slice(0, MAX_ARTIFACT_WORKBENCH_ACTIVITY);
+  return Object.freeze({
+    schema: ARTIFACT_WORKBENCH_PROJECTION_SCHEMA,
+    observedAt: recovery.observedAt,
+    artifacts: Object.freeze(artifacts),
+    recovery,
+    history: Object.freeze({
+      accessHeadDigest: access.headDigest,
+      deletionHeadDigest: deletion.headDigest,
+      cleanupHeadDigest: cleanup.headDigest,
+      orphanGcHeadDigest: orphanGc.headDigest,
+      totalEventCount: allActivity.length,
+      returnedEventCount: activity.length,
+      truncated: allActivity.length > activity.length,
+      activity: Object.freeze(activity),
+    }),
+  });
+}

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}`,