@cassiomc1/forgeloop 1.2.3 → 1.3.0

package/src/core/artifacts.js

@@ -5,6 +5,7 @@ import { assertSecretFree } from "./receipt.js";
 import { assertJsonBytes, assertJsonLimits } from "./json-safety.js";
 import { assertSchema, readSchema } from "./schema-validation.js";
 import { getPackageRoot } from "./templates.js";
+import { getActiveTaskTransaction, withTaskTransaction } from "./transaction.js";
 
 export const ARTIFACT_PATHS = Object.freeze({
   contract: ".forgeloop/current-contract.json",
@@ -75,7 +76,9 @@ export async function readJsonArtifact(
   }
 
   const artifactPath = ensureWithin(target, relativePath);
-  if (!(await fileExists(artifactPath))) {
+  const transaction = getActiveTaskTransaction();
+  const stagedText = transaction ? await transaction.readText(relativePath) : null;
+  if (stagedText === null && !(await fileExists(artifactPath))) {
     throw new ArtifactError(
       "ARTIFACT_MISSING",
       `Artifact is missing: ${relativePath}`,
@@ -85,7 +88,7 @@ export async function readJsonArtifact(
 
   let value;
   try {
-    const bytes = await readBytes(artifactPath);
+    const bytes = stagedText === null ? await readBytes(artifactPath) : Buffer.from(stagedText, "utf8");
     assertJsonBytes(bytes, relativePath);
     value = JSON.parse(bytes.toString("utf8"));
     assertJsonLimits(value, relativePath);
@@ -114,13 +117,19 @@ export async function writeJsonArtifact(
   value,
   schemaName,
   packageRoot = getPackageRoot(),
-  { dryRun = false } = {},
+  { dryRun = false, taskId = null, operation = "write-artifact" } = {},
 ) {
   try {
     await assertSafePath(target, relativePath);
   } catch (error) {
     throw artifactError("ARTIFACT_PATH_INVALID", relativePath, error);
   }
+  const activeTransaction = getActiveTaskTransaction();
+  if (!activeTransaction && taskId && !dryRun) {
+    return withTaskTransaction({ target, taskId, operation, packageRoot }, async () => (
+      writeJsonArtifact(target, relativePath, value, schemaName, packageRoot, { dryRun, taskId, operation })
+    ));
+  }
   try {
     const artifactPath = ensureWithin(target, relativePath);
     assertSecretFree(value);
@@ -129,7 +138,11 @@ export async function writeJsonArtifact(
     assertJsonLimits(value, relativePath);
     const serialized = `${JSON.stringify(value, null, 2)}\n`;
     assertJsonBytes(serialized, relativePath);
-    await writeFileAtomic(artifactPath, serialized, { dryRun });
+    if (activeTransaction && !dryRun) {
+      await activeTransaction.stageText(relativePath, serialized);
+    } else {
+      await writeFileAtomic(artifactPath, serialized, { dryRun });
+    }
     return { path: relativePath, fingerprint: canonicalFingerprint(value), value };
   } catch (error) {
     throw artifactError(

package/src/core/cli-command-definitions.js

@@ -58,6 +58,19 @@ export const CLI_TASK_OPTION = Object.freeze({
 export const CLI_BOOTSTRAP_OPTIONS = CLI_COMMON_OPTIONS;
 
 export const CLI_COMMAND_DEFINITIONS = Object.freeze({
+  "protocol-info": Object.freeze({
+    name: "protocol-info",
+    category: "diagnostics",
+    mutation: "READ_ONLY",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit complete machine-readable protocol metadata" }),
+    }),
+    writes: [],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Reports versioning, lifecycle, command, guide, and public error compatibility metadata for external harnesses.",
+  }),
   init: Object.freeze({
     name: "init",
     category: "project-maintenance",
@@ -264,6 +277,7 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
       "--id": Object.freeze({ targetKey: "checkId", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--id requires a check ID", description: "stable check identifier" }),
       "--requirement": Object.freeze({ targetKey: "checkRequirement", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--requirement requires an evidence target", description: "completion requirement covered by the check" }),
       "--details": Object.freeze({ targetKey: "checkDetails", parseType: "json-object", takesValue: true, valueName: "json", missingValueMessage: "--details requires a JSON object", description: "additional structured check details" }),
+      "--timeout-ms": Object.freeze({ targetKey: "timeoutMs", parseType: "non-negative-integer", takesValue: true, valueName: "number", missingValueMessage: "--timeout-ms requires a non-negative integer", description: "maximum command duration before termination" }),
       "--": Object.freeze({ targetKey: "commandArgv", parseType: "argv", takesValue: true, valueName: "argv...", description: "exact command argv to classify, execute, and attest" }),
       "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
     }),
@@ -683,6 +697,20 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     mayExecuteExternalProcess: false,
     description: "Shows details of a specific task descriptor and its scoped artifacts.",
   }),
+  "task-lock-status": Object.freeze({
+    name: "task-lock-status",
+    category: "lifecycle",
+    mutation: "READ_ONLY",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Reports a task lock record and its lease-based stale-lock classification.",
+  }),
   "task-scope": Object.freeze({
     name: "task-scope",
     category: "lifecycle",
@@ -712,6 +740,21 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     mayExecuteExternalProcess: false,
     description: "Migrates a legacy 1.0 singleton task state layout into a task-namespaced layout.",
   }),
+  "migrate-protocol": Object.freeze({
+    name: "migrate-protocol",
+    category: "project-maintenance",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      "--to": Object.freeze({ targetKey: "to", parseType: "string", takesValue: true, valueName: "protocolVersion", missingValueMessage: "--to requires a protocol version", description: "target supported protocol version" }),
+      "--dry-run": Object.freeze({ targetKey: "dryRun", parseType: "boolean", takesValue: false, description: "show migration actions without writing or deleting artifacts" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured migration result as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/*"],
+    removes: [".forgeloop/current-contract.json", ".forgeloop/routing-result.json", ".forgeloop/work-state.json", ".forgeloop/preflight.json", ".forgeloop/execution-receipt.json", ".forgeloop/events.ndjson", ".forgeloop/continuity.json", ".forgeloop/gates", ".forgeloop/executions"],
+    mayExecuteExternalProcess: false,
+    description: "Safely migrates explicitly supported protocol state; unknown target versions fail without rewriting artifacts.",
+  }),
   "task-unlock": Object.freeze({
     name: "task-unlock",
     category: "project-maintenance",
@@ -720,6 +763,7 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
       ...CLI_COMMON_OPTIONS,
       ...CLI_TASK_OPTION,
       "--force": Object.freeze({ targetKey: "force", parseType: "boolean", takesValue: false, description: "force release of an orphaned task lock" }),
+      "--stale-only": Object.freeze({ targetKey: "staleOnly", parseType: "boolean", takesValue: false, description: "release only a lock whose lease is expired" }),
       "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
     }),
     writes: [],

package/src/core/completion-artifacts.js

@@ -16,7 +16,7 @@ import { evaluatePreflight } from "./preflight.js";
 import { currentChangedPaths } from "./repository.js";
 import { readPersistedRoute } from "./route-artifact.js";
 import { createReceipt, validateReceipt } from "./receipt.js";
-import { readWorkState, writeWorkState } from "./work-state.js";
+import { readWorkState, mutateWorkState } from "./work-state.js";
 import { assertExecutionPrerequisites, hasExecutionStarted } from "./execution-prerequisites.js";
 import { normalizeRequirements } from "./evidence-readiness.js";
 import { classifyCommandResolution, validateVerificationAuthority } from "./verification-capability.js";
@@ -650,6 +650,7 @@ export async function recordCheck({
   });
   const nextState = {
     ...state,
+    revision: (state.revision ?? 0) + 1,
     checks,
     verificationEvidence: appendUniqueEvidence(state.verificationEvidence ?? [], evidence),
     evidenceCoverage: coverage,
@@ -682,7 +683,12 @@ export async function recordCheck({
     runtimeContext,
   });
 
-  await writeWorkState(target, nextState, { packageRoot, taskId, statePath });
+  await mutateWorkState(target, {
+    expectedRevision: state.revision ?? 0,
+    packageRoot,
+    taskId,
+    statePath,
+  }, () => nextState);
   const written = await writeJsonArtifact(
     target,
     receiptRel,
@@ -900,6 +906,7 @@ export async function recordTerminalResult({
   const evidenceList = appendUniqueEvidence(existingReceipt.value.evidence ?? [], terminalEvidence);
   const nextState = {
     ...state,
+    revision: (state.revision ?? 0) + 1,
     verificationEvidence: evidenceList,
     lastUpdated: new Date().toISOString(),
   };
@@ -932,7 +939,12 @@ export async function recordTerminalResult({
     runtimeContext,
   });
 
-  await writeWorkState(target, nextState, { packageRoot, taskId, statePath });
+  await mutateWorkState(target, {
+    expectedRevision: state.revision ?? 0,
+    packageRoot,
+    taskId,
+    statePath,
+  }, () => nextState);
   await writeJsonArtifact(
     target,
     receiptRel,

package/src/core/completion.js

@@ -4,7 +4,7 @@ import { appendProtocolEvent, LIFECYCLE_MILESTONES, validateEventLedger, validat
 import { evaluatePreflight } from "./preflight.js";
 import { readContract } from "./contract.js";
 import { readPersistedRoute } from "./route-artifact.js";
-import { readWorkState, writeWorkState, classifyLoadedWorkState } from "./work-state.js";
+import { readWorkState, mutateWorkState, classifyLoadedWorkState } from "./work-state.js";
 import { createReceipt, validateReceipt } from "./receipt.js";
 import { completionRelationshipErrors } from "./completion-relationships.js";
 import { assertSafePath, ensureWithin, fileExists } from "./filesystem.js";
@@ -517,7 +517,13 @@ export async function runComplete({
       } catch {
         // The evaluator already reports a missing or invalid receipt; evidence-only rejection can persist without one.
       }
-      await writeWorkState(target, next, { packageRoot, taskId, statePath });
+      next.revision = (state.revision ?? 0) + 1;
+      await mutateWorkState(target, {
+        expectedRevision: state.revision ?? 0,
+        packageRoot,
+        taskId,
+        statePath,
+      }, () => next);
       let nextReceipt = null;
       if (receipt) {
         nextReceipt = await createReceipt({
@@ -565,12 +571,18 @@ export async function runComplete({
         publicationStatus: result.publicationStatus,
         lastUpdated: new Date().toISOString(),
       };
+      next.revision = (state.revision ?? 0) + 1;
       const nextReceipt = await createReceipt({
         ...receipt.value,
         stateFingerprint: canonicalFingerprint(next),
         verificationCycle: next.verificationCycle ?? receipt.value.verificationCycle ?? 1,
       }, packageRoot, { target, taskId: state.taskId, authorityContext, runtimeContext });
-      await writeWorkState(target, next, { packageRoot, taskId, statePath });
+      await mutateWorkState(target, {
+        expectedRevision: state.revision ?? 0,
+        packageRoot,
+        taskId,
+        statePath,
+      }, () => next);
       await writeJsonArtifact(target, receiptRel, nextReceipt, "execution-receipt", packageRoot);
     }
     const contract = await readContract(target, packageRoot, { taskId, contractPath });

package/src/core/diagnosis.js

@@ -1,5 +1,5 @@
 import { appendProtocolEvent, validateEventLedger } from "./events.js";
-import { readWorkState, writeWorkState } from "./work-state.js";
+import { readWorkState, mutateWorkState } from "./work-state.js";
 import {
   DIAGNOSIS_INFORMATION_GAIN,
   assertDiagnosisDetails,
@@ -110,16 +110,16 @@ export async function recordDiagnosis({
   });
 
   if (existingEvent?.details?.diagnosisFingerprint === requestedFingerprint) {
-    const updatedState = {
-      ...state,
-      diagnosedHypothesis: existingEvent.details.hypothesis,
-      lastUpdated: new Date().toISOString(),
-    };
-    await writeWorkState(target, updatedState, {
+    const updatedState = await mutateWorkState(target, {
+      expectedRevision: state.revision ?? 0,
       packageRoot,
       taskId: taskId ?? null,
       statePath,
-    });
+    }, () => ({
+      ...state,
+      diagnosedHypothesis: existingEvent.details.hypothesis,
+      lastUpdated: new Date().toISOString(),
+    }));
     return {
       event: existingEvent,
       state: updatedState,
@@ -155,12 +155,16 @@ export async function recordDiagnosis({
     { taskId: taskId ?? null, eventsPath },
   );
 
-  const updatedState = {
+  const updatedState = await mutateWorkState(target, {
+    expectedRevision: state.revision ?? 0,
+    packageRoot,
+    taskId: taskId ?? null,
+    statePath,
+  }, () => ({
     ...state,
     diagnosedHypothesis: hypothesis.trim(),
     lastUpdated: new Date().toISOString(),
-  };
-  await writeWorkState(target, updatedState, { packageRoot, taskId: taskId ?? null, statePath });
+  }));
 
   return {
     event,

package/src/core/error-codes.js

@@ -29,6 +29,7 @@ export const E_TASK_CHANGE_ATTRIBUTION_UNAVAILABLE = "E_TASK_CHANGE_ATTRIBUTION_
 export const E_TASK_LAYOUT_LEGACY = "E_TASK_LAYOUT_LEGACY";
 export const E_TASK_MIGRATION_INVALID = "E_TASK_MIGRATION_INVALID";
 export const E_TASK_MIGRATION_IDENTITY_MISMATCH = "E_TASK_MIGRATION_IDENTITY_MISMATCH";
+export const E_PROTOCOL_MIGRATION_TARGET_UNSUPPORTED = "E_PROTOCOL_MIGRATION_TARGET_UNSUPPORTED";
 
 export const E_DIAGNOSIS_REQUIRED = "E_DIAGNOSIS_REQUIRED";
 export const E_DIAGNOSIS_INVALID = "E_DIAGNOSIS_INVALID";
@@ -469,6 +470,7 @@ export const ALL_KNOWN_ERROR_CODES = Object.freeze(new Set([
   E_TASK_LAYOUT_LEGACY,
   E_TASK_MIGRATION_INVALID,
   E_TASK_MIGRATION_IDENTITY_MISMATCH,
+  E_PROTOCOL_MIGRATION_TARGET_UNSUPPORTED,
   E_CHECK_INERT,
   E_CHECK_MUTATION_NOT_DETECTED,
   E_POLICY_DRIFT,
@@ -487,3 +489,19 @@ export const ALL_KNOWN_ERROR_CODES = Object.freeze(new Set([
   E_POLICY_INITIALIZATION_FAILED,
   E_INIT_KIT_CONFLICT,
 ]));
+
+/**
+ * Complete public registry.  Older callers can retain PUBLIC_ERROR_CODES while
+ * documentation and compatibility handshakes enumerate every stable code.
+ */
+export const PUBLIC_ERROR_REGISTRY = Object.freeze(
+  Object.fromEntries([...ALL_KNOWN_ERROR_CODES].sort().map((code) => [code, Object.freeze(
+    PUBLIC_ERROR_CODES[code] ?? {
+      code,
+      category: "protocol",
+      classification: "PUBLIC_STABLE",
+      meaning: "A ForgeLoop protocol validation or lifecycle condition was not satisfied.",
+      safeResolution: "Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json.",
+    },
+  )])),
+);

package/src/core/events.js

@@ -1,5 +1,5 @@
 
-import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { appendFile, mkdir, open, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 
 import { assertSafePath, ensureWithin, fileExists } from "./filesystem.js";
@@ -11,6 +11,7 @@ import { PROTOCOL_VERSION } from "./protocol.js";
 import { isRecoverableCompletionEvidenceCode } from "./completion-recovery.js";
 
 import { taskArtifactPath } from "./task-paths.js";
+import { getActiveTaskTransaction, withTaskTransaction } from "./transaction.js";
 
 import { assertDiagnosisDetails } from "./diagnosis-model.js";
 import { assertDecisionCriterionDetails } from "./settlement-model.js";
@@ -40,6 +41,50 @@ const REPEATABLE_MILESTONES = new Set([
   "TERMINAL_RESULT_RECORDED",
 ]);
 
+function eventIndexPath(eventsPath) {
+  return `${eventsPath}.index.json`;
+}
+
+function parseEventIndex(text, relativePath) {
+  if (typeof text !== "string") return null;
+  try {
+    const value = JSON.parse(text);
+    if (!value || value.schemaVersion !== 1 || !Number.isInteger(value.seq) || value.seq < 0
+      || (value.lastHash !== null && !/^[a-f0-9]{64}$/.test(value.lastHash))) return null;
+    return value;
+  } catch {
+    return null;
+  }
+}
+
+function checkpointFromEvents(events) {
+  const last = events.at(-1) ?? null;
+  return {
+    schemaVersion: 1,
+    seq: last?.seq ?? 0,
+    lastHash: last?.hash ?? null,
+  };
+}
+
+async function readEventCheckpoint(target, packageRoot, relPath, options, transaction) {
+  if (!transaction.eventCheckpoints) transaction.eventCheckpoints = new Map();
+  const cached = transaction.eventCheckpoints.get(relPath);
+  if (cached) return cached;
+
+  const indexPath = eventIndexPath(relPath);
+  const indexed = parseEventIndex(await transaction.readText(indexPath), indexPath);
+  const tail = await readEventTail(target, packageRoot, { ...options, eventsPath: relPath, limit: 1 });
+  const last = tail.at(-1) ?? null;
+  let checkpoint;
+  if (indexed && indexed.seq === (last?.seq ?? 0) && indexed.lastHash === (last?.hash ?? null)) {
+    checkpoint = indexed;
+  } else {
+    checkpoint = checkpointFromEvents(await readEvents(target, packageRoot, { ...options, eventsPath: relPath }));
+  }
+  transaction.eventCheckpoints.set(relPath, checkpoint);
+  return checkpoint;
+}
+
 export function validateKnownEventDetails(event) {
   if (!event || typeof event !== "object") return;
   switch (event.event) {
@@ -94,6 +139,47 @@ export async function readEvents(target, packageRoot, options = {}) {
   const eventsPath = ensureWithin(target, relPath);
   if (!(await fileExists(eventsPath))) return [];
   const text = await readFile(eventsPath, "utf8");
+  return parseEventsText(text, relPath, packageRoot);
+}
+
+export async function readEventTail(target, packageRoot, options = {}) {
+  const limit = options.limit ?? 50;
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw protocolError("E_EVENT_INVALID", "ledger tail limit must be a positive integer");
+  }
+  const relPath = options?.eventsPath ?? options?.relativePath ?? (options?.taskId ? taskArtifactPath(options.taskId, "events") : ARTIFACT_PATHS.events);
+  await assertSafePath(target, relPath);
+  const eventsPath = ensureWithin(target, relPath);
+  if (!(await fileExists(eventsPath))) return [];
+  const size = (await stat(eventsPath)).size;
+  let window = Math.min(size, 64 * 1024);
+  while (true) {
+    const position = size - window;
+    const handle = await open(eventsPath, "r");
+    const bytes = Buffer.alloc(window);
+    try {
+      await handle.read(bytes, 0, window, position);
+    } finally {
+      await handle.close();
+    }
+    let text = bytes.toString("utf8");
+    if (position > 0) {
+      const firstLineEnd = text.indexOf("\n");
+      if (firstLineEnd < 0) {
+        window = Math.min(size, window * 2);
+        continue;
+      }
+      text = text.slice(firstLineEnd + 1);
+    }
+    const lines = text.split(/\r?\n/).filter((line) => line.trim() !== "");
+    if (lines.length >= limit || position === 0) {
+      return parseEventsText(lines.slice(-limit).join("\n"), relPath, packageRoot);
+    }
+    window = Math.min(size, window * 2);
+  }
+}
+
+async function parseEventsText(text, relPath, packageRoot) {
   assertJsonBytes(text, relPath);
   const schema = await readSchema("event", packageRoot);
   const lines = text.split(/\r?\n/).filter((line) => line.trim() !== "");
@@ -112,20 +198,28 @@ export async function readEvents(target, packageRoot, options = {}) {
 }
 
 export async function appendProtocolEvent(target, input, packageRoot, options = {}) {
+  const activeTransaction = getActiveTaskTransaction();
   if (typeof input?.taskId !== "string" || !input.taskId) throw protocolError("E_EVENT_INVALID", "event taskId is required");
   if (typeof input?.event !== "string" || !input.event) throw protocolError("E_EVENT_INVALID", "event type is required");
   const relPath = options?.eventsPath ?? options?.relativePath ?? (options?.taskId ? taskArtifactPath(options.taskId, "events") : ARTIFACT_PATHS.events);
-  const events = await readEvents(target, packageRoot, { ...options, eventsPath: relPath });
-  const previous = events.at(-1) ?? null;
+  if (!activeTransaction) {
+    return withTaskTransaction({
+      target,
+      taskId: options.taskId ?? input.taskId,
+      lockTaskId: relPath === ARTIFACT_PATHS.events ? "__legacy-events__" : (options.taskId ?? input.taskId),
+      operation: "append-event",
+    }, async () => appendProtocolEvent(target, input, packageRoot, options));
+  }
+  const checkpoint = await readEventCheckpoint(target, packageRoot, relPath, options, activeTransaction);
   const event = {
-    seq: events.length + 1,
+    seq: checkpoint.seq + 1,
     schemaVersion: EVENT_SCHEMA_VERSION,
     protocolVersion: PROTOCOL_VERSION,
     taskId: input.taskId,
     event: input.event,
     at: input.at ?? new Date().toISOString(),
     ...(input.fingerprint ? { fingerprint: input.fingerprint } : {}),
-    previousHash: previous?.hash ?? null,
+    previousHash: checkpoint.lastHash,
     ...(input.details ? { details: structuredClone(input.details) } : {}),
   };
   validateKnownEventDetails(event);
@@ -133,10 +227,17 @@ export async function appendProtocolEvent(target, input, packageRoot, options =
   const schema = await readSchema("event", packageRoot);
   assertSchema(event, schema, relPath);
   event.hash = eventHash(event);
-  const eventsPath = ensureWithin(target, relPath);
   if (!options.dryRun) {
-    await mkdir(path.dirname(eventsPath), { recursive: true });
-    await appendFile(eventsPath, `${JSON.stringify(event)}\n`, { encoding: "utf8" });
+    if (activeTransaction) {
+      await activeTransaction.appendText(relPath, `${JSON.stringify(event)}\n`);
+      const nextCheckpoint = { schemaVersion: 1, seq: event.seq, lastHash: event.hash };
+      await activeTransaction.stageText(eventIndexPath(relPath), `${JSON.stringify(nextCheckpoint)}\n`);
+      activeTransaction.eventCheckpoints.set(relPath, nextCheckpoint);
+    } else {
+      const eventsPath = ensureWithin(target, relPath);
+      await mkdir(path.dirname(eventsPath), { recursive: true });
+      await appendFile(eventsPath, `${JSON.stringify(event)}\n`, { encoding: "utf8" });
+    }
   }
   return event;
 }

package/src/core/execution.js

@@ -1,4 +1,4 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
 import { readdir } from "node:fs/promises";
 import path from "node:path";
@@ -54,25 +54,79 @@ function validateAuthorityBeforeLaunch({ target, taskId, argv, resolution, detai
   }
 }
 
-function executeProcess(argv, cwd) {
+const MAX_CAPTURED_OUTPUT_BYTES = 64 * 1024;
+export const TERMINATION_GRACE_MS = 1_000;
+
+function digest(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+function executeProcess(argv, cwd, { timeoutMs = null } = {}) {
   return new Promise((resolve) => {
     let spawnError = null;
+    let timedOut = false;
+    let settled = false;
+    let timeout = null;
+    let forceTermination = null;
+    const stdout = [];
+    const stderr = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let outputTruncated = false;
+    const capture = (chunks, chunk, total) => {
+      const available = MAX_CAPTURED_OUTPUT_BYTES - total;
+      if (available <= 0) {
+        outputTruncated = true;
+        return total;
+      }
+      if (chunk.length > available) {
+        chunks.push(chunk.subarray(0, available));
+        outputTruncated = true;
+        return total + available;
+      }
+      chunks.push(chunk);
+      return total + chunk.length;
+    };
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      if (timeout) clearTimeout(timeout);
+      if (forceTermination) clearTimeout(forceTermination);
+      resolve({
+        ...result,
+        timedOut,
+        stdout: Buffer.concat(stdout),
+        stderr: Buffer.concat(stderr),
+        stdoutBytes,
+        stderrBytes,
+        outputTruncated,
+      });
+    };
     try {
       const child = spawn(argv[0], argv.slice(1), {
         cwd,
         shell: false,
         stdio: ["ignore", "pipe", "pipe"],
       });
-      child.stdout?.resume();
-      child.stderr?.resume();
+      child.stdout?.on("data", (chunk) => { stdoutBytes = capture(stdout, chunk, stdoutBytes); });
+      child.stderr?.on("data", (chunk) => { stderrBytes = capture(stderr, chunk, stderrBytes); });
       child.once("error", (error) => {
         spawnError = error;
       });
-      child.once("close", (exitCode) => {
-        resolve({ exitCode, spawnError });
+      child.once("close", (exitCode, signal) => {
+        finish({ exitCode, signal, spawnError });
       });
+      if (Number.isInteger(timeoutMs) && timeoutMs > 0) {
+        timeout = setTimeout(() => {
+          timedOut = true;
+          child.kill("SIGTERM");
+          forceTermination = setTimeout(() => {
+            child.kill("SIGKILL");
+          }, TERMINATION_GRACE_MS);
+        }, timeoutMs);
+      }
     } catch (error) {
-      resolve({ exitCode: null, spawnError: error });
+      finish({ exitCode: null, signal: null, spawnError: error });
     }
   });
 }
@@ -106,6 +160,7 @@ export async function runCommandExecution({
   authorityContext,
   runtimeContext,
   executionPath,
+  timeoutMs = null,
 } = {}) {
   const commandArgv = normalizeArgv(argv);
   const resolution = await resolveExecutionResolution({
@@ -145,7 +200,7 @@ export async function runCommandExecution({
 
   const executionId = `exec-${randomUUID()}`;
   const startedAt = new Date().toISOString();
-  const processResult = await executeProcess(commandArgv, target);
+  const processResult = await executeProcess(commandArgv, target, { timeoutMs });
   const finishedAt = new Date().toISOString();
   const execution = {
     schemaVersion: 1,
@@ -167,8 +222,17 @@ export async function runCommandExecution({
     ...(resolution.dispatch ? { dispatch: resolution.dispatch } : {}),
     startedAt,
     finishedAt,
-    status: processResult.exitCode === 0 && !processResult.spawnError ? "passed" : "failed",
+    status: processResult.exitCode === 0 && !processResult.spawnError && !processResult.timedOut ? "passed" : "failed",
     exitCode: processResult.exitCode,
+    durationMs: Math.max(0, Date.parse(finishedAt) - Date.parse(startedAt)),
+    termination: processResult.spawnError ? "spawn-error" : processResult.timedOut ? "timeout" : processResult.signal ? "signal" : "exit",
+    signal: processResult.signal ?? null,
+    stdoutSha256: digest(processResult.stdout),
+    stderrSha256: digest(processResult.stderr),
+    stdoutBytes: processResult.stdoutBytes,
+    stderrBytes: processResult.stderrBytes,
+    outputTruncated: processResult.outputTruncated,
+    ...(Number.isInteger(timeoutMs) && timeoutMs > 0 ? { timeoutMs, terminationGraceMs: TERMINATION_GRACE_MS } : {}),
   };
   const execPath = executionPath ?? await resolveExecutionArtifactPath(target, taskId, executionId);
   const written = await writeJsonArtifact(target, execPath, execution, "execution", packageRoot);

package/src/core/filesystem.js

@@ -3,11 +3,11 @@ import {
   access,
   lstat,
   mkdir,
+  open,
   readFile,
   realpath,
   rename,
   unlink,
-  writeFile,
 } from "node:fs/promises";
 import path from "node:path";
 
@@ -108,10 +108,28 @@ export async function writeFileAtomic(filePath, bytes, { dryRun = false } = {})
 
   await mkdir(path.dirname(filePath), { recursive: true });
   const temporaryPath = `${filePath}.${randomUUID()}.tmp`;
+  let temporaryHandle;
   try {
-    await writeFile(temporaryPath, bytes, { mode: 0o644 });
+    // A rename alone is atomic but does not guarantee that staged bytes have
+    // reached stable storage. Sync the temporary file before publishing it;
+    // directory sync is best-effort because Windows and some filesystems do
+    // not permit opening a directory for fsync.
+    temporaryHandle = await open(temporaryPath, "w", 0o644);
+    await temporaryHandle.writeFile(bytes);
+    await temporaryHandle.sync();
+    await temporaryHandle.close();
+    temporaryHandle = null;
     await rename(temporaryPath, filePath);
+    try {
+      const directoryHandle = await open(path.dirname(filePath), "r");
+      try { await directoryHandle.sync(); } finally { await directoryHandle.close(); }
+    } catch (error) {
+      if (!["EINVAL", "EPERM", "EISDIR", "ENOTSUP", "UNKNOWN"].includes(error.code)) throw error;
+    }
   } catch (error) {
+    if (temporaryHandle) {
+      try { await temporaryHandle.close(); } catch { /* preserve original error */ }
+    }
     try {
       await unlink(temporaryPath);
     } catch {