chainlesschain 0.165.2 → 0.165.4

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

@@ -23,6 +23,12 @@ import {
 import { isGitRepo } from "./git-integration.js";
 import { markRuntimeLedgerPersistenceError } from "./runtime-usage-ledger.js";
 import { IterationBudget } from "./iteration-budget.js";
+import {
+  beginSessionBudgetUsage,
+  markSessionBudgetUsageUnknown,
+  recordSessionBudgetUsage,
+  rejectSessionBudgetUsageUnknown,
+} from "./session-budget-usage.js";
 
 // ─── Constants ──────────────────────────────────────────────────────────────
 
@@ -162,6 +168,8 @@ export class SubAgentContext {
    *   work cannot begin without a durable parent boundary.
    * @param {function} [options.onUsageSettlement] - Synchronous observer for
    *   real child token-usage/model-usage-unknown settlements.
+   * @param {function} [options.onProviderReceipt] - Synchronous observer for
+   *   a provider-returned receipt before the matching usage settlement.
    * @param {function} [options.onToolCallBoundary] - Synchronous observer for
    *   real child tool-executing boundaries.
    * @param {function} [options.onToolCallSettlement] - Synchronous observer for
@@ -284,6 +292,10 @@ export class SubAgentContext {
       typeof options.onUsageSettlement === "function"
         ? options.onUsageSettlement
         : null;
+    this._onProviderReceipt =
+      typeof options.onProviderReceipt === "function"
+        ? options.onProviderReceipt
+        : null;
     this._onToolCallBoundary =
       typeof options.onToolCallBoundary === "function"
         ? options.onToolCallBoundary
@@ -690,6 +702,7 @@ export class SubAgentContext {
     const pendingToolCalls = new Map();
     let observeUsageBoundary = null;
     let observeUsageSettlement = null;
+    let observeProviderReceipt = null;
     let observeToolBoundary = null;
     let observeToolSettlement = null;
     const providerReceiptForSettlement = (event) => {
@@ -739,6 +752,17 @@ export class SubAgentContext {
         requireSyncUsageObserver(this._onUsageSettlement, event, "settlement");
         pendingUsageCalls.delete(callId);
       };
+      observeProviderReceipt = (event) => {
+        const callId = requireUsageCallId(event, "receipt");
+        if (!pendingUsageCalls.has(callId)) {
+          throw runtimeUsageObserverFailure(
+            null,
+            "CC_USAGE_RECEIPT_BOUNDARY_MISSING",
+            `Child provider receipt has no matching boundary: ${callId}`,
+          );
+        }
+        requireSyncUsageObserver(this._onProviderReceipt, event, "receipt");
+      };
 
       // agentLoop yields model-usage-started before provider work. Its consumer
       // runs synchronously before requesting the next event, so a durable host
@@ -747,6 +771,9 @@ export class SubAgentContext {
       // directly, before its provider query, rather than yielding a start event.
       options.onUsageBoundary = observeUsageBoundary;
       options.onUsageSettlement = observeUsageSettlement;
+      if (this._onProviderReceipt) {
+        options.onProviderReceipt = observeProviderReceipt;
+      }
       options.strictUsageTelemetry = true;
 
       observeToolBoundary = (event) => {
@@ -869,21 +896,28 @@ export class SubAgentContext {
           }
         }
         if (event.type === "provider-request-receipt") {
-          this._providerRequestReceipts.push(
-            Object.freeze({
-              protocol: event.protocol,
-              provider: event.provider,
-              workflowEffectId: event.workflowEffectId,
-              callId: event.callId,
-              callSequence: event.callSequence,
-              source: event.source,
-              clientRequestId: event.clientRequestId,
-              requestId: event.requestId || null,
-              responseId: event.responseId || null,
-              requestIdentitySemantics: event.requestIdentitySemantics,
-              independentlyReadable: event.independentlyReadable,
-            }),
-          );
+          const receipt = Object.freeze({
+            protocol: event.protocol,
+            provider: event.provider,
+            workflowEffectId: event.workflowEffectId,
+            callId: event.callId,
+            callSequence: event.callSequence,
+            source: event.source,
+            clientRequestId: event.clientRequestId,
+            requestId: event.requestId || null,
+            responseId: event.responseId || null,
+            requestIdentitySemantics: event.requestIdentitySemantics,
+            independentlyReadable: event.independentlyReadable,
+          });
+          this._providerRequestReceipts.push(receipt);
+          if (strictUsageTelemetry && this._onProviderReceipt) {
+            observeProviderReceipt({
+              type: "provider-request-receipt",
+              ...receipt,
+              workflowRequestSource: receipt.source,
+              providerReceipt: { ...receipt },
+            });
+          }
         }
 
         if (event.type === "token-usage") {
@@ -914,13 +948,11 @@ export class SubAgentContext {
           // call into a permanently open `started` row.
           // Attributed usage was already charged by the nested child sharing
           // this same authority, so only direct usage is folded here.
-          if (!event.attribution && this.sessionBudget?.recordUsage) {
-            this.sessionBudget.recordUsage({
-              provider: event.provider || null,
-              model: event.model || null,
-              usage: event.usage || null,
-            });
-          }
+          recordSessionBudgetUsage(
+            this.sessionBudget,
+            event,
+            "sub-agent usage settlement",
+          );
           if (this._onUsage) {
             // Forward real usage to the spawner. A nested child's event already
             // carries its own attribution frame — preserve it (deepest wins).
@@ -954,6 +986,11 @@ export class SubAgentContext {
               observeUsageBoundary(event);
             }
           }
+          beginSessionBudgetUsage(
+            this.sessionBudget,
+            event,
+            "sub-agent provider call",
+          );
         }
 
         if (event.type === "tool-executing" && strictUsageTelemetry) {
@@ -990,6 +1027,10 @@ export class SubAgentContext {
             observeUsageSettlement(forwardedUnknown);
             forwardedUnknown.ledgerPersisted = true;
           }
+          const budgetUsageUnknown = markSessionBudgetUsageUnknown(
+            this.sessionBudget,
+            event,
+          );
           if (this._onUsage) {
             if (strictUsageTelemetry) {
               requireSyncUsageObserver(
@@ -1005,6 +1046,12 @@ export class SubAgentContext {
               }
             }
           }
+          if (budgetUsageUnknown) {
+            rejectSessionBudgetUsageUnknown(
+              event,
+              "sub-agent provider call",
+            );
+          }
         }
 
         if (event.type === "tool-executing") {

package/src/lib/web-ui-server.js

@@ -23,6 +23,7 @@ import crypto from "crypto";
 import { fileURLToPath } from "url";
 import { getInlineSource as getEnvelopeInlineSource } from "./web-ui-envelope.js";
 import { CLISkillLoader } from "./skill-loader.js";
+import { authorizeArtifactContentAccess } from "./artifact-access-ledger.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -1333,6 +1334,15 @@ export function handleApiRequest(req, res, ctx = {}) {
           res.end(JSON.stringify({ error: "Stored copy missing" }));
           return;
         }
+        const accessIdHeader = req.headers["x-chainlesschain-access-id"];
+        const authorization = authorizeArtifactContentAccess(store, {
+          artifactId: entry.id,
+          client: "web",
+          action: "download",
+          ...(typeof accessIdHeader === "string"
+            ? { accessId: accessIdHeader }
+            : {}),
+        });
         const downloadName =
           entry.title && path.extname(entry.title)
             ? entry.title
@@ -1343,8 +1353,9 @@ export function handleApiRequest(req, res, ctx = {}) {
           "Content-Disposition": encodeDispositionFilename(downloadName),
           "Cache-Control": "no-store",
           "X-Content-Type-Options": "nosniff",
+          "X-ChainlessChain-Access-Digest": authorization.access.eventDigest,
         });
-        const stream = fs.createReadStream(storedPath);
+        const stream = fs.createReadStream(authorization.storedPath);
         stream.on("error", () => res.destroy());
         stream.pipe(res);
       } catch (err) {

package/src/lib/with-file-lock.js

@@ -14,14 +14,18 @@
  * reclaimed merely because the directory is old, and corrupt ownership fails
  * closed. The default filesystem publishes a fully populated, uniquely staged
  * directory in one rename so a process killed during acquisition cannot expose
- * an ownerless lock. Confirmed-dead owners are reclaimed with an exact-token
- * marker inside the lock directory so a delayed contender cannot delete a
- * replacement lock. Strict callers may use bounded jittered retries and an
+ * an ownerless lock. Confirmed-dead owners are reclaimed with an exact-token,
+ * process-owned claim inside the lock directory so a delayed contender cannot
+ * delete a replacement lock and another contender can take over if the first
+ * reclaimer is killed. Strict callers may use bounded jittered retries and an
  * after-release yield to avoid Windows sharing transients and fixed-interval
  * lock convoys.
  *
  * @param {string} targetPath  the file being guarded (lock is `${targetPath}.lock`)
- * @param {(ctx:{locked:boolean})=>T} fn  critical section; receives whether the lock was held
+ * @param {(ctx:{locked:boolean,publishReleaseAfterPathRemoved:(pendingPath:string)=>boolean})=>T} fn
+ *   critical section; `publishReleaseAfterPathRemoved` lets a transaction
+ *   publish an exact, contender-completable handoff before its final atomic
+ *   rename removes a uniquely named staging path
  * @returns {T} whatever `fn` returns
  */
 export function withFileLock(targetPath, fn, opts = {}) {
@@ -54,7 +58,9 @@ export function withFileLock(targetPath, fn, opts = {}) {
   };
   let held = false;
   let acquisitionError = null;
+  let lastOwnerObservation = null;
   let retryAttempt = 0;
+  let releasePublished = false;
   const deadline = _now() + timeoutMs;
 
   for (;;) {
@@ -88,6 +94,17 @@ export function withFileLock(targetPath, fn, opts = {}) {
       const incumbent = ownerRead.owner;
       acquisitionError = ownerRead.error;
       if (incumbent) {
+        let incumbentAlive = true;
+        try {
+          incumbentAlive = isOwnerAlive(incumbent);
+        } catch {
+          // An unavailable identity probe must retain the lock.
+        }
+        lastOwnerObservation = {
+          pid: incumbent.pid,
+          startedAt: incumbent.startedAt,
+          alive: incumbentAlive,
+        };
         // The owner writes this exact-token marker only after its critical
         // section has finished. A Windows sharing violation can then prevent
         // the final recursive removal while the owner process remains alive,
@@ -102,11 +119,19 @@ export function withFileLock(targetPath, fn, opts = {}) {
           owner,
           isOwnerAlive,
         );
+        lastOwnerObservation.releasePublished = publishedRelease.published;
         if (publishedRelease.completed) continue;
-        if (!publishedRelease.published && !isOwnerAlive(incumbent)) {
-          if (reclaimOwnedDirectory(_fs, lockDir, incumbent, isOwnerAlive)) {
+        if (!incumbentAlive) {
+          // A published handoff can still retain its unique staging path when
+          // the owner is killed between marker publication and the atomic
+          // replacement. No process can commit that staging file after the
+          // exact owner is proven dead, so the lock directory is reclaimable
+          // whether the transaction committed or not. Leave the private
+          // staging file untouched; it cannot affect the guarded target.
+          if (
+            reclaimOwnedDirectory(_fs, lockDir, incumbent, owner, isOwnerAlive)
+          )
             continue;
-          }
         }
       } else if (!failIfUnavailable) {
         // Compatibility for legacy best-effort locks that predate owner.json.
@@ -139,12 +164,21 @@ export function withFileLock(targetPath, fn, opts = {}) {
   }
 
   if (!held && failIfUnavailable) {
+    const ownerDetails = lastOwnerObservation
+      ? `; owner pid=${lastOwnerObservation.pid}, ageMs=${Math.max(
+          0,
+          _now() - lastOwnerObservation.startedAt,
+        )}, alive=${lastOwnerObservation.alive}, releasePublished=${Boolean(lastOwnerObservation.releasePublished)}`
+      : "";
     const error = new Error(
-      `Could not acquire state lock: ${targetPath}`,
+      `Could not acquire state lock: ${targetPath}${ownerDetails}`,
       acquisitionError ? { cause: acquisitionError } : undefined,
     );
     error.code = "STATE_LOCK_UNAVAILABLE";
     error.attempts = retryAttempt + 1;
+    error.lockOwner = lastOwnerObservation
+      ? Object.freeze({ ...lastOwnerObservation })
+      : null;
     throw error;
   }
 
@@ -152,7 +186,32 @@ export function withFileLock(targetPath, fn, opts = {}) {
   let bodyThrew = false;
   let result;
   try {
-    result = fn({ locked: held });
+    result = fn({
+      locked: held,
+      publishReleaseAfterPathRemoved(pendingPath) {
+        if (!held || typeof pendingPath !== "string" || !pendingPath) {
+          return false;
+        }
+        const current = readOwner(_fs, ownerPath);
+        if (!sameOwner(current, owner)) return false;
+        const markerPath = path.join(lockDir, `.release-${owner.token}`);
+        const marker = { ...owner, releaseAfterPathRemoved: pendingPath };
+        try {
+          writeOwnerMarker(_fs, markerPath, marker);
+        } catch (error) {
+          if (error?.code !== "EEXIST") throw error;
+          const existing = readOwner(_fs, markerPath);
+          if (
+            !sameOwner(existing, owner) ||
+            existing?.releaseAfterPathRemoved !== pendingPath
+          ) {
+            return false;
+          }
+        }
+        releasePublished = true;
+        return true;
+      },
+    });
   } catch (error) {
     bodyThrew = true;
     bodyError = error;
@@ -161,7 +220,13 @@ export function withFileLock(targetPath, fn, opts = {}) {
   let releaseError = null;
   if (held) {
     try {
-      released = releaseOwnedDirectory(_fs, lockDir, owner, isOwnerAlive);
+      released = releaseOwnedDirectory(
+        _fs,
+        lockDir,
+        owner,
+        isOwnerAlive,
+        releasePublished,
+      );
     } catch (error) {
       releaseError = error;
     }
@@ -251,6 +316,15 @@ function directoryExists(_fs, target) {
   }
 }
 
+function pathStatus(_fs, target) {
+  try {
+    _fs.statSync(target);
+    return "present";
+  } catch (error) {
+    return error?.code === "ENOENT" ? "absent" : "unknown";
+  }
+}
+
 function isProcessAlive(pid) {
   try {
     process.kill(pid, 0);
@@ -361,21 +435,65 @@ function writeOwnerMarker(_fs, markerPath, owner) {
   });
 }
 
-function reclaimOwnedDirectory(_fs, lockDir, owner, ownerAlive) {
-  const markerPath = path.join(lockDir, `.reclaim-${owner.token}`);
-  try {
-    writeOwnerMarker(_fs, markerPath, owner);
-  } catch (error) {
-    if (error?.code === "ENOENT" || error?.code === "EEXIST") return false;
-    throw error;
+function reclaimOwnedDirectory(_fs, lockDir, incumbent, claimant, ownerAlive) {
+  const claimPath = path.join(lockDir, `.reclaim-${incumbent.token}`);
+  for (;;) {
+    const existingClaim = readOwner(_fs, claimPath);
+    if (existingClaim) {
+      if (sameOwner(existingClaim, claimant)) break;
+      if (!ownerAlive(existingClaim)) {
+        if (removeOwnMarker(_fs, claimPath, existingClaim)) continue;
+      }
+      return false;
+    }
+    try {
+      // The claim belongs to the contender, not the dead incumbent. If this
+      // contender is killed before detaching the directory, another process
+      // can prove that exact claimant dead and safely take over.
+      writeOwnerMarker(_fs, claimPath, claimant);
+      break;
+    } catch (error) {
+      if (error?.code === "ENOENT") {
+        return !directoryExists(_fs, lockDir);
+      }
+      if (error?.code === "EEXIST" || isTransientLockError(error)) {
+        return false;
+      }
+      throw error;
+    }
   }
+
   const current = readOwner(_fs, path.join(lockDir, "owner.json"));
-  if (!sameOwner(current, owner) || ownerAlive(owner)) {
-    removeOwnMarker(_fs, markerPath, owner);
+  if (!sameOwner(current, incumbent) || ownerAlive(incumbent)) {
+    removeOwnMarker(_fs, claimPath, claimant);
     return false;
   }
-  _fs.rmSync(lockDir, { recursive: true, force: true });
-  return true;
+
+  if (typeof _fs.renameSync !== "function") {
+    _fs.rmSync(lockDir, { recursive: true, force: true });
+    return true;
+  }
+
+  const cleanupDir = `${lockDir}.reclaimed-${incumbent.token}-${claimant.token}`;
+  try {
+    // Free the acquisition path atomically before recursive cleanup. A killed
+    // reclaimer can therefore leave only uniquely named debris, never a
+    // claimant marker that permanently fences the shared lock path.
+    _fs.renameSync(lockDir, cleanupDir);
+    try {
+      _fs.rmSync(cleanupDir, { recursive: true, force: true });
+    } catch {
+      /* private reclaim debris is harmless after the lock path is detached */
+    }
+    return true;
+  } catch (error) {
+    removeOwnMarker(_fs, claimPath, claimant);
+    if (error?.code === "ENOENT") {
+      return !directoryExists(_fs, lockDir);
+    }
+    if (isTransientLockError(error)) return false;
+    throw error;
+  }
 }
 
 function reclaimLegacyDirectory(_fs, lockDir, stat) {
@@ -401,9 +519,23 @@ function reclaimLegacyDirectory(_fs, lockDir, stat) {
 
 function completePublishedRelease(_fs, lockDir, owner, claimant, ownerAlive) {
   const markerPath = path.join(lockDir, `.release-${owner.token}`);
-  if (!sameOwner(readOwner(_fs, markerPath), owner)) {
+  const marker = readOwner(_fs, markerPath);
+  if (!sameOwner(marker, owner)) {
     return { published: false, completed: false };
   }
+  // A state transaction can stage its exact replacement, publish this marker,
+  // and only then atomically rename the staging file over the guarded target.
+  // Contenders may complete the release only after that unique staging path is
+  // gone. This closes the otherwise unbounded scheduler-preemption window
+  // between a committed rename and the owner's first release syscall without
+  // ever exposing an in-progress write to a competing critical section.
+  if (
+    typeof marker.releaseAfterPathRemoved === "string" &&
+    marker.releaseAfterPathRemoved &&
+    pathStatus(_fs, marker.releaseAfterPathRemoved) !== "absent"
+  ) {
+    return { published: true, completed: false };
+  }
   const claimPath = path.join(lockDir, `.release-claim-${owner.token}`);
   for (;;) {
     const existingClaim = readOwner(_fs, claimPath);
@@ -461,9 +593,20 @@ function completePublishedRelease(_fs, lockDir, owner, claimant, ownerAlive) {
   }
 }
 
-function releaseOwnedDirectory(_fs, lockDir, owner, ownerAlive) {
+function releaseOwnedDirectory(
+  _fs,
+  lockDir,
+  owner,
+  ownerAlive,
+  releaseWasPublished = false,
+) {
   if (!sameOwner(readOwner(_fs, path.join(lockDir, "owner.json")), owner)) {
-    return false;
+    // Once this exact owner published a guarded handoff, a contender is allowed
+    // to detach the old directory as soon as the final staging path disappears.
+    // A missing or replacement lock therefore proves successful release, not
+    // ownership loss. Without that publication the strict legacy verdict stays
+    // fail-closed.
+    return releaseWasPublished;
   }
   // Atomically move the exact owned directory out of the acquisition path,
   // then remove that uniquely-tokened directory. A replacement owner may
@@ -482,7 +625,7 @@ function releaseOwnedDirectory(_fs, lockDir, owner, ownerAlive) {
       }
       return true;
     } catch (error) {
-      if (error?.code === "ENOENT") return false;
+      if (error?.code === "ENOENT") return releaseWasPublished;
       // Windows sharing transients fall back to the marker-based release.
     }
   }
@@ -490,7 +633,13 @@ function releaseOwnedDirectory(_fs, lockDir, owner, ownerAlive) {
   try {
     writeOwnerMarker(_fs, markerPath, owner);
   } catch (error) {
-    if (error?.code === "ENOENT" || error?.code === "EEXIST") return false;
+    if (error?.code === "ENOENT") return releaseWasPublished;
+    if (error?.code === "EEXIST") {
+      const existing = readOwner(_fs, markerPath);
+      if (!sameOwner(existing, owner)) return false;
+      return completePublishedRelease(_fs, lockDir, owner, owner, ownerAlive)
+        .published;
+    }
     throw error;
   }
   if (!sameOwner(readOwner(_fs, path.join(lockDir, "owner.json")), owner)) {