@tea-agent/loop-agent 0.41.1 → 0.42.0-next.10

package/dist/infrastructure/console/dir-lock.js

@@ -0,0 +1,132 @@
+import { randomBytes } from "node:crypto";
+import { lstat, mkdir, readFile, rename, rm, utimes, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { ensureSecureDir } from "./app-data.js";
+const OWNER_FILE = "owner";
+const DEFAULT_STALE_MS = 30_000;
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function freshToken() {
+    return randomBytes(16).toString("hex");
+}
+function ownerPath(lockDir) {
+    return path.join(lockDir, OWNER_FILE);
+}
+/**
+ * A lock's freshness is the owner-file heartbeat, not the containing
+ * directory mtime. Creating or editing a file does not refresh the directory
+ * mtime, so using the latter could make a healthy long-running lock appear
+ * stale and permit a second holder into its critical section.
+ */
+async function lockTimestamp(lockDir) {
+    const ownerStat = await lstat(ownerPath(lockDir)).catch(() => undefined);
+    if (ownerStat?.isFile())
+        return ownerStat.mtimeMs;
+    return (await lstat(lockDir).catch(() => undefined))?.mtimeMs;
+}
+export async function isDirLockStale(lockDir, staleMs, nowMs = Date.now()) {
+    const timestamp = await lockTimestamp(lockDir);
+    return timestamp === undefined || nowMs - timestamp > staleMs;
+}
+async function refreshDirLock(lockDir, token) {
+    const owner = await readFile(ownerPath(lockDir), "utf-8").catch(() => undefined);
+    if (owner !== token)
+        return;
+    const now = new Date();
+    await utimes(ownerPath(lockDir), now, now).catch(() => { });
+}
+/**
+ * Cross-process exclusive directory lock (mkdir-based). Ownership is
+ * token-guarded: each holder writes a unique owner file inside the lock
+ * directory and only ever removes a lock whose owner token matches its own.
+ *
+ * Release protocol (B2): verify owner AND freshness BEFORE touching the lock
+ * path. Takeover only ever targets a stale lock, so a holder that releases a
+ * lock it still owns (fresh) cannot have been taken over between the verify
+ * and the rename — it moves its own lock, never a successor's. A stale lock is
+ * deliberately left alone (a takeover may be in flight); only the post-rename
+ * tombstone check restores a lock moved by an unexpected race, never deletes a
+ * successor's live lock.
+ */
+export async function acquireDirLock(lockDir, options) {
+    const token = options?.token ?? freshToken();
+    const staleMs = options?.staleMs ?? DEFAULT_STALE_MS;
+    ensureSecureDir(path.dirname(lockDir));
+    for (;;) {
+        try {
+            await mkdir(lockDir);
+        }
+        catch (error) {
+            const code = error?.code;
+            if (code !== "EEXIST")
+                throw error;
+            const stat = await lstat(lockDir).catch(() => undefined);
+            if (stat?.isDirectory() && await isDirLockStale(lockDir, staleMs)) {
+                const tombstone = `${lockDir}.${freshToken()}.tomb`;
+                try {
+                    await rename(lockDir, tombstone);
+                    await rm(tombstone, { recursive: true, force: true });
+                }
+                catch {
+                    // another process won the takeover; retry the loop
+                }
+                continue;
+            }
+            await delay(20);
+            continue;
+        }
+        try {
+            await writeFile(ownerPath(lockDir), token, {
+                flag: "wx",
+                mode: 0o600,
+            });
+        }
+        catch {
+            await rm(lockDir, { recursive: true, force: true });
+            continue;
+        }
+        break;
+    }
+    const heartbeat = setInterval(() => { void refreshDirLock(lockDir, token); }, Math.max(10, Math.floor(staleMs / 3)));
+    heartbeat.unref();
+    let released = false;
+    const release = async () => {
+        if (released)
+            return;
+        released = true;
+        clearInterval(heartbeat);
+        // Verify the lock is still ours AND fresh before renaming it away. If the
+        // owner no longer matches, a successor holds the lock — never touch it.
+        const stat = await lstat(lockDir).catch(() => undefined);
+        if (!stat?.isDirectory())
+            return;
+        if (await isDirLockStale(lockDir, staleMs)) {
+            // Our lock went stale: a takeover may be in flight or imminent. Leave
+            // it alone — removing it now could delete a successor's live lock.
+            return;
+        }
+        const owner = await readFile(ownerPath(lockDir), "utf-8").catch(() => undefined);
+        if (owner !== token)
+            return;
+        const tombstone = `${lockDir}.${token}.release`;
+        try {
+            await rename(lockDir, tombstone);
+        }
+        catch {
+            // lock path already gone (a takeover removed it); nothing of ours.
+            return;
+        }
+        const movedOwner = await readFile(path.join(tombstone, OWNER_FILE), "utf-8").catch(() => undefined);
+        if (movedOwner !== token) {
+            // Raced with a takeover in the microsecond window between the fresh
+            // verify and the rename: restore the moved lock if the path is still
+            // free; otherwise leave the tombstone for reconcile — never delete a
+            // successor's live lock.
+            await rename(tombstone, lockDir).catch(() => { });
+            return;
+        }
+        await rm(tombstone, { recursive: true, force: true }).catch(() => { });
+    };
+    return { token, release };
+}

package/dist/infrastructure/console/operation-store.js

@@ -0,0 +1,417 @@
+import { randomBytes } from "node:crypto";
+import path from "node:path";
+import { assertFrontendSplitProjectionSuccessor, frontendSplitProjectionSchema, } from "../../workflows/dag/frontend-split-application-service.js";
+import { buildFrontendHumanDecisionProjection, consumeFrontendHumanDecision, materializeFrontendHumanDecision, parseFrontendHumanDecisionProjection, parseFrontendHumanDecisionReceipt, } from "../../workflows/dag/frontend-human-decision.js";
+import { buildFrontendSplitAggregateCloseout, computeFrontendSplitDigest, finalizeFrontendSplitAggregate, frontendCommittedFactRefSchema, frontendSplitChildCloseoutFactsSchema, initializeFrontendSplitParent, } from "../../workflows/dag/frontend-split-orchestrator.js";
+import { frontendCloseoutFactsSchema, frontendTestHandoffSchema, } from "../../workflows/dag/frontend-closeout.js";
+import { listJsonFiles, readJsonIfExists, sha256Json, writeSecureJson, } from "./app-data.js";
+export const TERMINAL_OPERATION_STATES = new Set(["succeeded", "failed", "timed-out", "restarting"]);
+function operationFile(appData, operationId) {
+    return path.join(appData.operations, `${operationId}.json`);
+}
+function requestIndexFile(appData, clientRequestId) {
+    const safe = clientRequestId.replace(/[^a-zA-Z0-9._-]+/g, "_").slice(0, 180);
+    return path.join(appData.operations, `req-${safe}.json`);
+}
+export function computeActionPayloadHash(action, actionParams) {
+    return sha256Json({ action, actionParams });
+}
+export function newOperationId() {
+    return `op_${randomBytes(12).toString("hex")}`;
+}
+const sharedWriteChains = new Map();
+export class OperationStore {
+    appData;
+    /** Shared per-store-root, per-key write lock. Multiple OperationStore instances
+     * in one worker process must observe the same CAS critical section. */
+    writeChains;
+    constructor(appData) {
+        this.appData = appData;
+        const root = path.resolve(appData.operations);
+        let chains = sharedWriteChains.get(root);
+        if (!chains) {
+            chains = new Map();
+            sharedWriteChains.set(root, chains);
+        }
+        this.writeChains = chains;
+    }
+    serialize(key, op) {
+        const prev = this.writeChains.get(key) ?? Promise.resolve();
+        const next = prev.then(op, op);
+        this.writeChains.set(key, next.then(() => undefined, () => undefined));
+        return next;
+    }
+    async create(input) {
+        const clientRequestId = input.clientRequestId.trim();
+        if (!clientRequestId) {
+            throw new Error("clientRequestId is required for mutation operations");
+        }
+        const payloadHash = computeActionPayloadHash(input.action, input.actionParams);
+        return this.serialize(`req:${clientRequestId}`, async () => {
+            const indexPath = requestIndexFile(this.appData, clientRequestId);
+            const existingIndex = await readJsonIfExists(indexPath);
+            if (existingIndex) {
+                const existing = await this.get(existingIndex.operationId);
+                if (existing) {
+                    if (existing.payloadHash === payloadHash) {
+                        return { kind: "idempotent", operation: existing };
+                    }
+                    return {
+                        kind: "conflict",
+                        code: "REQUEST_ID_REUSE_CONFLICT",
+                        message: `clientRequestId ${clientRequestId} was reused with a different payload`,
+                        existing,
+                    };
+                }
+            }
+            const operationId = newOperationId();
+            const now = new Date().toISOString();
+            const operation = {
+                schemaVersion: 1,
+                operationId,
+                clientRequestId,
+                action: input.action,
+                actionParams: input.actionParams,
+                payloadHash,
+                state: "queued",
+                createdAt: now,
+                revision: 1,
+                taskId: input.taskId,
+                cliArgs: input.cliArgs,
+                ...(input.externalCommand
+                    ? { externalCommand: input.externalCommand }
+                    : {}),
+            };
+            await writeSecureJson(operationFile(this.appData, operationId), operation);
+            await writeSecureJson(indexPath, { operationId, payloadHash });
+            return { kind: "created", operation };
+        });
+    }
+    /**
+     * Idempotently materialize a split child/integration operation with a
+     * caller-specified deterministic operationId (from the split manifest).
+     * Unlike create() (random op_<hex> id) and save/update (no create), this is
+     * the durable cross-restart idempotency boundary for the production
+     * FrontendSplitTaskMaterializer backend: an existing operation file with the
+     * same taskId + payloadHash is returned as {created:false}; any drift fails
+     * closed instead of overwriting or silently diverging.
+     */
+    async ensureSplitMaterializedOperation(input) {
+        return this.serialize(input.operationId, async () => {
+            const existing = await this.get(input.operationId);
+            if (existing) {
+                if (existing.taskId !== input.taskId ||
+                    existing.payloadHash !== input.payloadHash) {
+                    throw new Error("frontend split operation materialization payload drift");
+                }
+                return { operation: existing, created: false };
+            }
+            const now = new Date().toISOString();
+            const operation = {
+                schemaVersion: 1,
+                operationId: input.operationId,
+                clientRequestId: `split:${input.operationId}`,
+                action: input.action,
+                actionParams: input.actionParams,
+                payloadHash: input.payloadHash,
+                state: "queued",
+                createdAt: now,
+                revision: 1,
+                taskId: input.taskId,
+                ...(input.cliArgs ? { cliArgs: input.cliArgs } : {}),
+            };
+            await writeSecureJson(operationFile(this.appData, input.operationId), operation);
+            return { operation, created: true };
+        });
+    }
+    async get(operationId) {
+        return readJsonIfExists(operationFile(this.appData, operationId));
+    }
+    async save(operation) {
+        return this.serialize(operation.operationId, async () => {
+            const current = await this.get(operation.operationId);
+            if (current?.revision !== undefined && operation.revision !== current.revision)
+                throw new Error("operation revision may not be changed by save");
+            if (operation.frontendHumanDecision !== undefined || current?.frontendHumanDecision !== undefined) {
+                if (!current || JSON.stringify(operation) !== JSON.stringify(current))
+                    throw new Error("human-decision projection may only be mutated by canonical CAS");
+                return current;
+            }
+            if (operation.frontendSplit !== undefined || current?.frontendSplit !== undefined) {
+                if (!current || JSON.stringify(operation) !== JSON.stringify(current))
+                    throw new Error("split projection may only be mutated by compareAndSwapFrontendSplit");
+                return current;
+            }
+            await writeSecureJson(operationFile(this.appData, operation.operationId), operation);
+            return operation;
+        });
+    }
+    async update(operationId, patch) {
+        return this.serialize(operationId, async () => {
+            const current = await this.get(operationId);
+            if (!current) {
+                throw new Error(`operation not found: ${operationId}`);
+            }
+            if ("frontendHumanDecision" in patch || (current.frontendHumanDecision !== undefined && ("state" in patch || "frontendExecution" in patch)))
+                throw new Error("human-decision projection may only be mutated by canonical CAS");
+            if ("frontendSplit" in patch || "revision" in patch || (current.frontendSplit !== undefined && ("state" in patch || "frontendExecution" in patch)))
+                throw new Error("split projection may only be mutated by compareAndSwapFrontendSplit");
+            const next = {
+                ...current,
+                ...patch,
+                operationId: current.operationId,
+                schemaVersion: 1,
+                clientRequestId: current.clientRequestId,
+                payloadHash: current.payloadHash,
+                action: current.action,
+                createdAt: current.createdAt,
+            };
+            await writeSecureJson(operationFile(this.appData, operationId), next);
+            return next;
+        });
+    }
+    async materializeFrontendHumanDecision(input) {
+        return this.serialize(input.operationId, async () => {
+            const current = await this.get(input.operationId);
+            if (!current || current.revision === undefined || current.revision !== input.expectedRecordRevision) {
+                const fallback = current?.frontendHumanDecision ?? buildFrontendHumanDecisionProjection({ status: "active", operationId: input.operationId, runId: input.envelope.runId, revision: Math.max(1, input.expectedRecordRevision) });
+                return { outcome: "rejected", reason: "record revision conflict or legacy record", projection: fallback };
+            }
+            const projection = current.frontendHumanDecision ?? buildFrontendHumanDecisionProjection({ status: "active", operationId: current.operationId, runId: input.envelope.runId, revision: current.revision });
+            const result = materializeFrontendHumanDecision({ projection, envelope: input.envelope, expectedRecordRevision: input.expectedRecordRevision, expectedProjectionDigest: input.expectedProjectionDigest });
+            if (result.outcome !== "applied")
+                return result;
+            const record = { ...current, revision: result.projection.revision, frontendHumanDecision: result.projection, state: "running" };
+            await writeSecureJson(operationFile(this.appData, current.operationId), record);
+            return result;
+        });
+    }
+    async consumeFrontendHumanDecision(input) {
+        return this.serialize(input.operationId, async () => {
+            const current = await this.get(input.operationId);
+            if (!current || current.revision === undefined || !current.frontendHumanDecision) {
+                const fallback = buildFrontendHumanDecisionProjection({ status: "active", operationId: input.operationId, runId: input.receipt.runId, revision: Math.max(1, input.expectedRecordRevision) });
+                return { outcome: "rejected", reason: "record has no mutable human-decision projection", projection: fallback };
+            }
+            const projection = parseFrontendHumanDecisionProjection(current.frontendHumanDecision);
+            if (current.revision !== input.expectedRecordRevision)
+                return { outcome: "rejected", reason: "record revision conflict", projection };
+            const result = consumeFrontendHumanDecision({ projection, receipt: input.receipt, expectedRecordRevision: input.expectedRecordRevision, expectedProjectionDigest: input.expectedProjectionDigest, currentTargetDigest: input.currentTargetDigest, now: input.now });
+            if (result.outcome !== "applied")
+                return result;
+            const record = { ...current, revision: result.projection.revision, frontendHumanDecision: result.projection };
+            await writeSecureJson(operationFile(this.appData, current.operationId), record);
+            return result;
+        });
+    }
+    async initializeFrontendHumanApprovedSplit(input) {
+        return this.serialize(input.operationId, async () => {
+            const current = await this.get(input.operationId);
+            const fallback = current?.frontendHumanDecision ?? buildFrontendHumanDecisionProjection({ status: "active", operationId: input.operationId, runId: input.receipt.runId, revision: Math.max(1, input.expectedRecordRevision) });
+            if (!current || current.revision === undefined || current.revision !== input.expectedRecordRevision || !current.frontendHumanDecision || !current.frontendExecution || current.frontendSplit)
+                return { outcome: "rejected", reason: "record is not an authoritative pending single-task split", projection: fallback };
+            const humanProjection = parseFrontendHumanDecisionProjection(current.frontendHumanDecision);
+            if (humanProjection.status !== "blocked-human" || humanProjection.envelope.kind !== "split-materialization-approval" || humanProjection.digest !== input.expectedProjectionDigest)
+                return { outcome: "rejected", reason: "pending split envelope conflict", projection: humanProjection };
+            const receipt = parseFrontendHumanDecisionReceipt(input.receipt);
+            if (receipt.kind !== "split-materialization-approval")
+                return { outcome: "rejected", reason: "receipt is not a split approval", projection: humanProjection };
+            if (JSON.stringify(current.frontendExecution) !== JSON.stringify(input.execution) || input.execution.kind !== "single-task")
+                return { outcome: "rejected", reason: "single-task execution conflict", projection: humanProjection };
+            const consumed = consumeFrontendHumanDecision({ projection: humanProjection, receipt, expectedRecordRevision: input.expectedRecordRevision, expectedProjectionDigest: input.expectedProjectionDigest, currentTargetDigest: input.currentTargetDigest, now: input.now });
+            if (consumed.outcome !== "applied")
+                return consumed;
+            const initialized = initializeFrontendSplitParent({
+                execution: input.execution,
+                manifest: input.manifest,
+                expectedOperationRevision: input.execution.operationRevision,
+                successorOperationRevision: consumed.projection.revision,
+                envelopeTargetDigest: humanProjection.envelope.targetDigest,
+                activeWriterOperationId: input.activeWriterOperationId,
+                activeProviderOperationId: input.activeProviderOperationId,
+                authorization: { mode: "human", envelope: humanProjection.envelope, receipt },
+            });
+            if (initialized.outcome !== "applied")
+                return { outcome: "rejected", reason: initialized.reason, projection: humanProjection };
+            const splitProjection = frontendSplitProjectionSchema.parse({ revision: consumed.projection.revision, execution: initialized.execution, manifest: input.manifest, parent: initialized.parent });
+            const { frontendExecution: _singleTask, ...withoutSingleTask } = current;
+            const record = { ...withoutSingleTask, revision: consumed.projection.revision, frontendHumanDecision: consumed.projection, frontendSplit: splitProjection, state: "running" };
+            await writeSecureJson(operationFile(this.appData, current.operationId), record);
+            return { outcome: "applied", projection: splitProjection, humanDecision: consumed.projection };
+        });
+    }
+    async compareAndSwapFrontendSplit(input) {
+        return this.serialize(input.operationId, async () => {
+            const current = await this.get(input.operationId);
+            if (!current || current.revision === undefined || current.revision !== input.expectedRevision)
+                return { outcome: "conflict" };
+            const currentProjection = current.frontendSplit;
+            if (currentProjection) {
+                if (currentProjection.execution.digest !== input.expectedExecutionDigest || currentProjection.parent.digest !== input.expectedParentDigest)
+                    return { outcome: "conflict" };
+            }
+            else if (input.expectedExecutionDigest || input.expectedParentDigest)
+                return { outcome: "conflict" };
+            const next = currentProjection
+                ? assertFrontendSplitProjectionSuccessor(currentProjection, input.next)
+                : frontendSplitProjectionSchema.parse(input.next);
+            if (next.revision !== current.revision + 1 || next.parent.operationId !== input.operationId)
+                throw new Error("split CAS next revision or operation binding mismatch");
+            const state = next.parent.operationState === "success" ? "succeeded" : next.parent.operationTerminal !== undefined ? "failed" : current.state;
+            const record = { ...current, revision: next.revision, frontendSplit: next, state };
+            await writeSecureJson(operationFile(this.appData, input.operationId), record);
+            return { outcome: "applied", projection: next };
+        });
+    }
+    async loadChildCloseoutFacts(input) {
+        const factsDir = input.closeoutRef.ref;
+        const facts = await readJsonIfExists(path.join(factsDir, "frontend-closeout-facts.json"));
+        if (facts === undefined)
+            return frontendSplitChildCloseoutFactsSchema.parse({ childId: input.childId, residualRisks: [], frontendTestHandoffRef: undefined });
+        const parsedFacts = frontendCloseoutFactsSchema.parse(facts);
+        if (computeFrontendSplitDigest(parsedFacts) !== input.closeoutRef.digest)
+            throw new Error(`child closeout facts digest mismatch: ${input.childId}`);
+        const handoff = await readJsonIfExists(path.join(factsDir, "frontend-test-handoff.json"));
+        const frontendTestHandoffRef = handoff === undefined ? undefined : computeFrontendSplitDigest(frontendTestHandoffSchema.parse(handoff));
+        return frontendSplitChildCloseoutFactsSchema.parse({ childId: input.childId, residualRisks: parsedFacts.residualRisks ?? [], frontendTestHandoffRef });
+    }
+    async settleFrontendSplitAggregate(input) {
+        return this.serialize(input.operationId, async () => {
+            const record = await this.get(input.operationId);
+            if (!record || record.revision === undefined || record.revision !== input.expectedRevision || !record.frontendSplit)
+                return { outcome: "conflict" };
+            const authoritative = frontendSplitProjectionSchema.parse(record.frontendSplit);
+            if (authoritative.parent.operationId !== input.operationId
+                || authoritative.revision !== input.expectedRevision
+                || authoritative.execution.digest !== input.expectedExecutionDigest
+                || authoritative.parent.digest !== input.expectedParentDigest
+                || authoritative.manifest.digest !== input.expectedManifestDigest
+                || authoritative.candidateBinding?.digest !== input.expectedCandidateBindingDigest
+                || authoritative.integrationBinding?.digest !== input.expectedIntegrationBindingDigest)
+                return { outcome: "conflict" };
+            if (!authoritative.candidateBinding)
+                return { outcome: "conflict" };
+            const expectedAggregate = buildFrontendSplitAggregateCloseout(authoritative.parent, authoritative.manifest, authoritative.candidateBinding, authoritative.integrationBinding, input.childCloseoutFacts);
+            if (JSON.stringify(expectedAggregate) !== JSON.stringify(input.aggregate))
+                return { outcome: "conflict" };
+            const transaction = await input.prepareAggregate({
+                operationId: authoritative.parent.operationId,
+                aggregate: expectedAggregate,
+            });
+            try {
+                const committedRef = frontendCommittedFactRefSchema.parse(transaction.committedRef);
+                const finalized = finalizeFrontendSplitAggregate(authoritative.parent, expectedAggregate, committedRef);
+                const next = assertFrontendSplitProjectionSuccessor(authoritative, { ...authoritative, revision: authoritative.revision + 1, parent: finalized.parent, execution: finalized.execution, aggregateCloseout: { value: expectedAggregate, committedRef } });
+                const nextRecord = { ...record, revision: next.revision, frontendSplit: next, state: "succeeded" };
+                await transaction.commit({
+                    parentRecordPath: operationFile(this.appData, record.operationId),
+                    parentRecord: nextRecord,
+                });
+                return { outcome: "applied", projection: next };
+            }
+            catch (error) {
+                await transaction.rollback();
+                throw error;
+            }
+        });
+    }
+    async initializeFrontendSplit(expectedRevision, projectionValue) {
+        const projection = frontendSplitProjectionSchema.parse(projectionValue);
+        return this.serialize(projection.parent.operationId, async () => {
+            const current = await this.get(projection.parent.operationId);
+            if (!current || current.revision === undefined || current.revision !== expectedRevision || current.frontendSplit !== undefined || projection.revision !== expectedRevision + 1)
+                return { outcome: "conflict" };
+            const record = { ...current, revision: projection.revision, frontendSplit: projection };
+            await writeSecureJson(operationFile(this.appData, current.operationId), record);
+            return { outcome: "applied", projection };
+        });
+    }
+    async list() {
+        const files = await listJsonFiles(this.appData.operations);
+        const ops = [];
+        for (const file of files) {
+            const base = path.basename(file);
+            if (base.startsWith("req-"))
+                continue;
+            const rec = await readJsonIfExists(file);
+            if (rec?.operationId)
+                ops.push(rec);
+        }
+        ops.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+        return ops;
+    }
+    /**
+     * On Console boot: any non-terminal operation that cannot be proven still
+     * running becomes needs-reconcile (never invent succeeded/failed).
+     */
+    async reconcileOnBoot(options) {
+        const isAlive = options?.isProcessAlive ??
+            ((pid) => {
+                try {
+                    process.kill(pid, 0);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            });
+        const changed = [];
+        for (const op of await this.list()) {
+            if (TERMINAL_OPERATION_STATES.has(op.state))
+                continue;
+            // A consoleUpdateAndInit whose record already proves a requested
+            // handoff died before writing its terminal state: the update and
+            // restart themselves succeeded — the booting process IS the
+            // handoff target. Mark it succeeded instead of surfacing the
+            // generic needs-reconcile failure copy to the operator.
+            if (op.action === "consoleUpdateAndInit" &&
+                op.state === "needs-reconcile" &&
+                isProvenConsoleUpdateHandoff(op.result)) {
+                changed.push(await this.update(op.operationId, {
+                    state: "succeeded",
+                    errorCode: undefined,
+                    errorMessage: undefined,
+                }));
+                continue;
+            }
+            if (op.state === "needs-reconcile")
+                continue;
+            let next;
+            if (op.state === "running" &&
+                typeof op.pid === "number" &&
+                isAlive(op.pid, op.processStartIdentity)) {
+                // still running — leave as-is
+                continue;
+            }
+            // queued/starting/running without proven process → needs-reconcile
+            next = await this.update(op.operationId, {
+                state: "needs-reconcile",
+                errorCode: "OPERATION_NEEDS_RECONCILE",
+                errorMessage: "Console restart or lost process evidence; operation needs reconcile (not cancelled)",
+            });
+            changed.push(next);
+        }
+        return changed;
+    }
+}
+export function isTerminalOperationState(state) {
+    return TERMINAL_OPERATION_STATES.has(state);
+}
+/**
+ * True when a consoleUpdateAndInit result proves the handoff was requested
+ * (install verified + init clean + new Console spawned). Used by boot
+ * reconcile to close the record as succeeded even though the old process
+ * died before writing its terminal state.
+ */
+function isProvenConsoleUpdateHandoff(result) {
+    if (!result || typeof result !== "object")
+        return false;
+    const shape = result;
+    return (shape.state === "restarting" &&
+        shape.maintenance?.handoff?.status === "requested");
+}
+export function clipPreview(text, max = 4096) {
+    if (text.length <= max)
+        return text;
+    return `${text.slice(0, max)}\n…[truncated ${text.length - max} chars]`;
+}

package/dist/infrastructure/harness/artifact-store.js

@@ -1,6 +1,6 @@
 import { mkdir } from "node:fs/promises";
 import path from "node:path";
-import { writeJsonAtomic, writeTextAtomic, } from "./atomic-write.js";
+import { writeJsonAtomic, writeBufferAtomic, writeTextAtomic, } from "./atomic-write.js";
 function resolveRepoRootFromDagRunDir(runDir) {
     const normalized = path.resolve(runDir);
     const lifecycleDir = path.dirname(normalized);
@@ -26,12 +26,16 @@ function dagWriteOptions(runDir, options) {
     return {
         repoRoot: options?.repoRoot ?? resolveRepoRootFromDagRunDir(runDir),
         allowCompletedFactsWrite: options?.allowCompletedFactsWrite,
+        mode: options?.mode,
+        directoryMode: options?.directoryMode,
     };
 }
 function pathWriteOptions(targetPath, options) {
     return {
         repoRoot: options?.repoRoot ?? resolveRepoRootFromHarnessPath(targetPath),
         allowCompletedFactsWrite: options?.allowCompletedFactsWrite,
+        mode: options?.mode,
+        directoryMode: options?.directoryMode,
     };
 }
 function completedRelocationWriteOptions(runDir) {
@@ -48,6 +52,11 @@ export async function writeDagNodeTextArtifact(runDir, nodeId, fileName, content
     await writeTextAtomic(targetPath, content, dagWriteOptions(runDir, options));
     return targetPath;
 }
+export async function writeDagNodeBufferArtifact(runDir, nodeId, fileName, bytes, options) {
+    const targetPath = path.join(runDir, nodeId, fileName);
+    await writeBufferAtomic(targetPath, bytes, dagWriteOptions(runDir, options));
+    return targetPath;
+}
 export async function writeDagNodeJsonArtifact(runDir, nodeId, fileName, value, options) {
     const targetPath = path.join(runDir, nodeId, fileName);
     await writeJsonAtomic(targetPath, value, dagWriteOptions(runDir, options));

package/dist/infrastructure/harness/atomic-write.js

@@ -30,10 +30,17 @@ async function writeAtomic(targetPath, content, options) {
     const resolved = options?.repoRoot && !path.isAbsolute(targetPath)
         ? path.resolve(options.repoRoot, targetPath)
         : path.resolve(targetPath);
-    await mkdir(path.dirname(resolved), { recursive: true });
+    await mkdir(path.dirname(resolved), {
+        recursive: true,
+        ...(options?.directoryMode !== undefined
+            ? { mode: options.directoryMode }
+            : {}),
+    });
     const tempPath = `${resolved}.${process.pid}.${(atomicWriteSequence += 1)}.tmp`;
     try {
-        await writeFile(tempPath, content, "utf-8");
+        await writeFile(tempPath, content, {
+            ...(options?.mode !== undefined ? { mode: options.mode } : {}),
+        });
         try {
             await rename(tempPath, resolved);
         }
@@ -54,6 +61,9 @@ export async function writeJsonAtomic(targetPath, value, options) {
 export async function writeTextAtomic(targetPath, text, options) {
     await writeAtomic(targetPath, text, options);
 }
+export async function writeBufferAtomic(targetPath, bytes, options) {
+    await writeAtomic(targetPath, bytes, options);
+}
 export function serializeJsonl(entries) {
     if (entries.length === 0)
         return "";