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

package/dist/application/task-lifecycle/plan-transitions.js

@@ -46,6 +46,37 @@ export function planTransitions(input) {
         actions.push({ type: "recover-contract" });
         expectedTransitions.push("contract-recovered");
     }
+    const startupStatus = snapshot.source?.sourceFidelityStartup?.status;
+    const startupRepairDetected = startupStatus === "missing" ||
+        startupStatus === "invalid" ||
+        startupStatus === "coverage-incomplete";
+    if (startupRepairDetected && input.startupRepairAttempted) {
+        actions.push({ type: "stop", reason: "blocker" });
+        return {
+            actions,
+            gate: null,
+            blockers,
+            next: {
+                kind: "advance",
+                command: `loop-agent task advance ${snapshot.taskId} --json`,
+            },
+            expectedTransitions,
+        };
+    }
+    const startupRepairRequired = startupRepairDetected;
+    if (startupStatus === "human-decision-blocked") {
+        actions.push({ type: "stop", reason: "blocker" });
+        return {
+            actions,
+            gate: null,
+            blockers,
+            next: {
+                kind: "external-action",
+                description: "Requirement ledger requires an existing human source decision; preserve sourceResolutions, resolve the blocker, then advance again.",
+            },
+            expectedTransitions,
+        };
+    }
     const sourceReady = snapshot.source?.requirementReady === true;
     const contractManaged = snapshot.contract?.effectiveStatus === "managed" ||
         Boolean(snapshot.contract?.revision && snapshot.contract.revision > 0);
@@ -53,7 +84,9 @@ export function planTransitions(input) {
     // Prefer prepare once PRDs are on disk; re-import only when caller still
     // signals hasPrdInput (advance.ts latches this after one import per call).
     const shouldImportPrd = input.hasPrdInput;
-    if (input.forcePrepareContract || input.refreshManagedContract) {
+    if (input.forcePrepareContract ||
+        input.refreshManagedContract ||
+        startupRepairRequired) {
         if (shouldImportPrd) {
             actions.push({ type: "import-prd" });
             expectedTransitions.push("prd-imported");
@@ -124,7 +157,8 @@ export function planTransitions(input) {
     const strictValidated = snapshot.dagDraft?.strictValidated === true;
     const dagRefreshRequired = Boolean(input.forceDagRefresh ||
         input.refreshManagedContract ||
-        input.forcePrepareContract);
+        input.forcePrepareContract ||
+        startupRepairRequired);
     if (!dagExists || dagRefreshRequired) {
         actions.push({ type: "generate-dag" });
         expectedTransitions.push("dag-generated");
@@ -145,10 +179,11 @@ export function planTransitions(input) {
         snapshot.lifecycleState === "evidence-closed" ||
         snapshot.lifecycleState === "needs-attention" ||
         snapshot.lifecycleState === "awaiting-decision";
-    const approvedForCurrent = postRunState || (input.approveGate && gate !== null);
+    const approveCurrentGate = input.approveGate && !dagRefreshRequired;
+    const approvedForCurrent = postRunState || (approveCurrentGate && gate !== null);
     if (!approvedForCurrent && (strictValidated || !dagExists || dagRefreshRequired)) {
         // Gate opens after generate+validate in the advance loop; plan includes open.
-        if (!input.approveGate) {
+        if (!approveCurrentGate) {
             actions.push({ type: "open-write-set-gate" });
             expectedTransitions.push("write-set-gate-opened");
             if (input.dryRun) {
@@ -177,14 +212,14 @@ export function planTransitions(input) {
         (snapshot.lifecycleState === "run-failed" && !failedRecoverable) ||
         snapshot.lifecycleState === "evidence-closed";
     if (!alreadyTerminalRun) {
-        if (input.approveGate && !postRunState) {
+        if (approveCurrentGate && !postRunState) {
             expectedTransitions.push("write-set-approved");
             actions.push({ type: "start-or-monitor-run" });
             expectedTransitions.push("dag-run-started", "dag-run-monitored");
         }
         else if (snapshot.lifecycleState === "running" ||
             snapshot.activeRun ||
-            (input.approveGate && Boolean(snapshot.activeRun))) {
+            (approveCurrentGate && Boolean(snapshot.activeRun))) {
             actions.push({ type: "start-or-monitor-run" });
             expectedTransitions.push("dag-run-monitored");
         }
@@ -218,7 +253,7 @@ export function planTransitions(input) {
         actions,
         gate,
         blockers,
-        next: deriveNext(snapshot, gate, input.approveGate),
+        next: deriveNext(snapshot, gate, approveCurrentGate),
         expectedTransitions,
     };
 }

package/dist/application/task-lifecycle/recommendations.js

@@ -42,6 +42,7 @@ export async function buildTaskLifecycleRecommendations(input) {
     const allowedPaths = [];
     const verifyCommands = [];
     // 1) managed task config
+    let hasDeclaredManagedVerify = false;
     try {
         const config = await loadTaskConfig(input.repoRoot, input.taskId);
         for (const glob of config.allowedPaths ?? []) {
@@ -53,7 +54,9 @@ export async function buildTaskLifecycleRecommendations(input) {
                 source: "managed-task-config",
             });
         }
-        for (const cmd of config.verifyCommands ?? []) {
+        const managedVerify = (config.verifyCommands ?? []).filter((cmd) => Boolean(cmd.command?.trim()));
+        hasDeclaredManagedVerify = managedVerify.length > 0;
+        for (const cmd of managedVerify) {
             const label = cmd.label?.trim() || "verify";
             const command = cmd.command?.trim();
             if (!command)
@@ -70,14 +73,22 @@ export async function buildTaskLifecycleRecommendations(input) {
         // task may not exist yet
     }
     // 2) package.json scripts (only if not already covered by managed config)
+    // The full-suite `test` script is recommended only when the task declares
+    // NO managed verifyCommands at all. Once a task configures a targeted
+    // verify set (e.g. per-change typecheck + a scoped vitest run), the full
+    // `npm run test` must never be auto-added: it validates the whole repo,
+    // costs far more than the change under review, and can fail on unrelated
+    // pre-existing breakage, turning a targeted verify green into a hard fail.
     const scripts = await readPackageScripts(input.repoRoot);
     const hasVerifyLabel = (label) => verifyCommands.some((entry) => entry.label === label);
     const scriptCandidates = [
         { label: "typecheck", script: "typecheck" },
-        { label: "test", script: "test" },
         { label: "check-repo", script: "check:repo" },
         { label: "check-repo", script: "check-repo" },
     ];
+    if (!hasDeclaredManagedVerify) {
+        scriptCandidates.push({ label: "test", script: "test" });
+    }
     for (const candidate of scriptCandidates) {
         const scriptBody = scripts[candidate.script];
         if (!scriptBody)

package/dist/build-stamp.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "version": "0.41.1",
-  "gitSha": "d5dec271d8ae9c579c423d9ea7b98fb0270baa5a",
-  "builtAt": "2026-09-02T04:40:44.741Z"
+  "version": "0.42.0-next.10",
+  "gitSha": "610477f8b0bb4b8e4972bb540abdf5ad438c236a",
+  "builtAt": "2026-09-03T14:48:16.726Z"
 }

package/dist/cli/command-definitions.js

@@ -31,17 +31,20 @@ import { runDagWorkflowValidate } from "../commands/dag-workflow-validate.js";
 import { runDagWorkflowCompile } from "../commands/dag-workflow-compile.js";
 import { runDagWorkflowPlan } from "../commands/dag-workflow-plan.js";
 import { runDagApprove } from "../commands/dag-approve.js";
+import { runDagArtifact } from "../commands/dag-artifact.js";
 import { runDagReject } from "../commands/dag-reject.js";
 import { runDagReconcileTasks } from "../commands/dag-reconcile-tasks.js";
 import { runDagReconcileRun } from "../commands/dag-reconcile-run.js";
 import { runDagRequestInterrupt } from "../commands/dag-request-interrupt.js";
 import { runDagRerunTask } from "../commands/dag-rerun-task.js";
+import { runDagFollowUp } from "../commands/dag-follow-up.js";
 import { runDagRerun } from "../commands/dag-rerun.js";
 import { runDagResume } from "../commands/dag-resume.js";
 import { runDagDecisionInspect, runDagDecisionValidate, } from "../workflows/dag/decision-envelope.js";
 import { runDagDoctor, runDagStatus } from "../workflows/dag/lifecycle.js";
 import { runDagCloseoutDraft, runDagReport } from "../commands/dag-report.js";
 import { runDagFinalVerification } from "../commands/dag-final-verification.js";
+import { runDagContext } from "../commands/dag-context.js";
 import { runKnowledge } from "../commands/knowledge.js";
 import { runLoopBenchmark } from "../commands/loop-benchmark.js";
 import { runPiReuseBenchmark } from "../commands/pi-reuse-benchmark.js";
@@ -135,8 +138,11 @@ const DAG_SUBCOMMANDS = [
     "request-interrupt",
     "rerun",
     "rerun-task",
+    "follow-up",
     "reconcile-tasks",
     "final-verification",
+    "context",
+    "artifact",
     "decision",
 ];
 const TASK_SUBCOMMANDS = ["advance", "status", "source"];
@@ -581,6 +587,11 @@ export const COMMAND_DEFINITIONS = [
                 await runDagRerunTask(repoRoot, rerunTaskArgs);
                 return;
             }
+            if (subcommand === "follow-up") {
+                const followUpArgs = rest.filter((arg) => Boolean(arg));
+                await runDagFollowUp(repoRoot, followUpArgs);
+                return;
+            }
             if (subcommand === "reconcile-tasks") {
                 const reconcileArgs = rest.filter((arg) => Boolean(arg));
                 await runDagReconcileTasks(repoRoot, reconcileArgs);
@@ -591,6 +602,14 @@ export const COMMAND_DEFINITIONS = [
                 await runDagFinalVerification(repoRoot, finalVerificationArgs);
                 return;
             }
+            if (subcommand === "context") {
+                await runDagContext(repoRoot, rest.filter((arg) => Boolean(arg)));
+                return;
+            }
+            if (subcommand === "artifact") {
+                await runDagArtifact(repoRoot, rest.filter((arg) => Boolean(arg)));
+                return;
+            }
             if (subcommand === "decision") {
                 const decisionSubcommand = rest[0];
                 const decisionArgs = rest

package/dist/cli/program.js

@@ -7,12 +7,15 @@ import { runCoverageAudit } from "../commands/coverage-audit.js";
 import { runCoverageReport } from "../commands/coverage-report.js";
 import { parseCursorPromptArgs, printCursorPromptUsage, runCursorPrompt, } from "../commands/cursor-prompt.js";
 import { runDagApprove } from "../commands/dag-approve.js";
+import { runDagArtifact } from "../commands/dag-artifact.js";
 import { runDagFinalVerification } from "../commands/dag-final-verification.js";
+import { runDagContext } from "../commands/dag-context.js";
 import { runDagInitHybrid } from "../commands/dag-init-hybrid.js";
 import { runDagReconcileTasks } from "../commands/dag-reconcile-tasks.js";
 import { runDagReconcileRun } from "../commands/dag-reconcile-run.js";
 import { runDagRequestInterrupt } from "../commands/dag-request-interrupt.js";
 import { runDagRerunTask } from "../commands/dag-rerun-task.js";
+import { runDagFollowUp } from "../commands/dag-follow-up.js";
 import { runDagRerun } from "../commands/dag-rerun.js";
 import { runDagReject } from "../commands/dag-reject.js";
 import { runDagCloseoutDraft, runDagReport } from "../commands/dag-report.js";
@@ -357,12 +360,21 @@ async function runDagAction(repoRoot, subcommand, rest) {
         case "rerun-task":
             await runDagRerunTask(repoRoot, args);
             return;
+        case "follow-up":
+            await runDagFollowUp(repoRoot, args);
+            return;
         case "reconcile-tasks":
             await runDagReconcileTasks(repoRoot, args);
             return;
         case "final-verification":
             await runDagFinalVerification(repoRoot, args);
             return;
+        case "context":
+            await runDagContext(repoRoot, args);
+            return;
+        case "artifact":
+            await runDagArtifact(repoRoot, args);
+            return;
         case "decision": {
             const [decisionSubcommand, ...decisionArgs] = args;
             if (decisionSubcommand === "inspect") {
@@ -376,7 +388,7 @@ async function runDagAction(repoRoot, subcommand, rest) {
             throw new Error("usage: dag decision <inspect|validate> --run-id <id> [--node-id <node-id>]");
         }
         default:
-            throw new Error("usage: dag <init-hybrid|execute|validate|workflow-plan|workflow-validate|workflow-compile|approve|reject|resume|status|doctor|report|closeout-draft|reconcile-run|request-interrupt|rerun|rerun-task|reconcile-tasks|final-verification|decision> ...");
+            throw new Error("usage: dag <init-hybrid|execute|validate|workflow-plan|workflow-validate|workflow-compile|approve|reject|resume|status|doctor|report|closeout-draft|reconcile-run|request-interrupt|rerun|rerun-task|reconcile-tasks|final-verification|context|artifact|decision> ...");
     }
 }
 function compactArgs(args) {
@@ -428,7 +440,7 @@ const RAW_SUBCOMMAND_USAGE = {
     "dag approve": 'usage: dag approve --run-id <id> --option <A|B|...> [--notes "..."]',
     "dag reject": 'usage: dag reject --run-id <id> --reason "..."',
     "dag rerun": "usage: dag rerun --run-id <id> --from-node <node-id> --plan [--json] | dag rerun --run-id <id> --from-node <node-id> --plan-hash <hash> --request-id <key> --reason <text> [--json]",
-    "dag rerun-task": "usage: dag rerun-task --run-id <id> --reason <text> --request-id <key> [--profile auto|minimal|standard|reviewed|supervised] [--task-id <id>] [--json]",
+    "dag rerun-task": "usage: dag rerun-task --run-id <id> --reason <text> --request-id <key> [--profile auto|minimal|standard|reviewed|supervised] [--task-id <id>] [--frontend-recovery --recovery-operation-id <id>] [--json]",
     "dag reconcile-run": "usage: dag reconcile-run --run-id <id> [--action supersede|abandon] [--reason <text>]",
     "dag doctor": "usage: dag doctor [--run-id <id>]\nInspect health issues before approve/reject/resume; no --json (output is already structured JSON).",
     "dag report": "usage: dag report [--run-id <id>] [--lifecycle active|paused|completed|all] [--json|--markdown] [--failed-only] [--latest] [--paused-latest]\nRead-only run report; --json gives structured facts (canonical: `dag report --run-id <id> --lifecycle completed --json`).",
@@ -545,9 +557,24 @@ function addDagCommand(program, defaultRepoRoot) {
         "request-interrupt",
         "rerun",
         "rerun-task",
+        "follow-up",
         "reconcile-tasks",
         "final-verification",
+        "context",
+        "artifact",
     ], defaultRepoRoot);
+    const context = dag.commands.find((command) => command.name() === "context");
+    if (!context)
+        throw new Error("dag context command registration failed");
+    context
+        .description("Inspect or export a captured effective node context")
+        .addHelpText("after", "\nActions:\n  show --run-id <id> --node-id <id> --attempt <n> [--json]\n  export --run-id <id> --node-id <id> --attempt <n> --output <zip> [--target <generic|pi-session|pi-handoff|readable>] [--redaction <redacted|raw>] [--acknowledge-sensitive-data] [--json]");
+    const artifact = dag.commands.find((command) => command.name() === "artifact");
+    if (!artifact)
+        throw new Error("dag artifact command registration failed");
+    artifact
+        .description("Inspect artifact consumers or manage staged artifact revisions")
+        .addHelpText("after", "\nActions:\n  consumers --run-id <id> --node-id <producer> --artifact <path> [--json]\n  revision stage --run-id <id> --node-id <producer> --artifact <path> --file <replacement> --request-id <id> [--json]\n  revision discard --revision-id <id> --request-id <id> [--json]");
     const validate = createRawArgsCommand("validate", "Validate an Agent DAG spec", defaultRepoRoot);
     configureDagValidate(validate);
     replaceActionWithOptionAwareDispatch(validate, defaultRepoRoot);

package/dist/commands/client-recovery.js

@@ -1328,12 +1328,15 @@ export async function runClientRecovery(input) {
     }
     const plugin = await installProjectOpenCodePlugin({
         repoRoot: input.repoRoot,
+        onlyIfMissing: true,
     });
     const overflowPlugin = await installProjectOpenCodeOverflowCompactPlugin({
         repoRoot: input.repoRoot,
+        onlyIfMissing: true,
     });
     const piExtension = await installProjectPiContextOverflowExtension({
         repoRoot: input.repoRoot,
+        onlyIfMissing: true,
     });
     const pi = await applyProjectPiSettingsMerge({ repoRoot: input.repoRoot });
     if (mode !== "user") {

package/dist/commands/dag-artifact.js

@@ -0,0 +1,284 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile } from "node:fs/promises";
+import path from "node:path";
+import { readRevisionParentArtifact } from "../workflows/dag/context-transfer/operator-actions.js";
+import { readFileBoundarySafe } from "../shared/path-safety.js";
+import { openConsoleAppData } from "../infrastructure/console/app-data.js";
+import { artifactRevisionUploadPath, createArtifactRevision, discardArtifactRevision, acquireArtifactRevisionLease, releaseArtifactRevisionLease, } from "../infrastructure/console/artifact-revision-store.js";
+import { OperationStore } from "../infrastructure/console/operation-store.js";
+import { buildArtifactBindingGraph } from "../workflows/dag/artifact-bindings.js";
+import { resolveArtifactRevisionSchema } from "../workflows/dag/artifact-revision-schema-registry.js";
+import { locateDagRun, readDagRunSpec } from "../workflows/dag/lifecycle.js";
+function parseArtifactArgs(args) {
+    const [first, second] = args;
+    const action = first === "consumers"
+        ? "consumers"
+        : first === "revision" && second === "stage"
+            ? "stage"
+            : first === "revision" && second === "discard"
+                ? "discard"
+                : undefined;
+    if (!action) {
+        throw new Error("usage: dag artifact consumers --run-id <run> --node-id <producer> --artifact <path> [--json] | dag artifact revision <stage|discard> ...");
+    }
+    let runId;
+    let nodeId;
+    let artifactPath;
+    let artifactId;
+    let file;
+    let candidateUpload;
+    let revisionId;
+    let requestId;
+    let json = false;
+    for (let index = action === "consumers" ? 1 : 2; index < args.length; index += 1) {
+        const arg = args[index];
+        const next = () => args[++index];
+        if (arg === "--run-id")
+            runId = next();
+        else if (arg.startsWith("--run-id="))
+            runId = arg.slice(9);
+        else if (arg === "--node-id")
+            nodeId = next();
+        else if (arg.startsWith("--node-id="))
+            nodeId = arg.slice(10);
+        else if (arg === "--artifact")
+            artifactPath = next();
+        else if (arg.startsWith("--artifact="))
+            artifactPath = arg.slice(11);
+        else if (arg === "--artifact-id")
+            artifactId = next();
+        else if (arg.startsWith("--artifact-id="))
+            artifactId = arg.slice(14);
+        else if (arg === "--file")
+            file = next();
+        else if (arg.startsWith("--file="))
+            file = arg.slice(7);
+        else if (arg === "--candidate-upload")
+            candidateUpload = next();
+        else if (arg.startsWith("--candidate-upload="))
+            candidateUpload = arg.slice(19);
+        else if (arg === "--revision-id")
+            revisionId = next();
+        else if (arg.startsWith("--revision-id="))
+            revisionId = arg.slice(14);
+        else if (arg === "--request-id")
+            requestId = next();
+        else if (arg.startsWith("--request-id="))
+            requestId = arg.slice(13);
+        else if (arg === "--json")
+            json = true;
+        else
+            throw new Error(`unknown dag artifact flag: ${arg}`);
+    }
+    return { action, runId, nodeId, artifactPath, artifactId, file, candidateUpload, revisionId, requestId, json };
+}
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function print(value, json, fallback) {
+    process.stdout.write(json ? `${JSON.stringify(value, null, 2)}\n` : `${fallback}\n`);
+}
+export async function runDagArtifactCore(repoRoot, args, cliOptions) {
+    const input = parseArtifactArgs(args);
+    if (input.action === "discard") {
+        if (!input.revisionId || !input.requestId) {
+            throw new Error("dag artifact revision discard requires --revision-id and --request-id");
+        }
+        const appData = openConsoleAppData({ repoRoot, ...(cliOptions?.appDataRoot ? { appDataRoot: cliOptions.appDataRoot } : {}) });
+        const operations = new OperationStore(appData);
+        const created = await operations.create({
+            clientRequestId: input.requestId,
+            action: "cliArtifactRevisionDiscard",
+            actionParams: { revisionId: input.revisionId },
+        });
+        if (created.kind === "conflict")
+            throw new Error(created.code);
+        if (created.kind === "idempotent" && created.operation.state === "succeeded") {
+            return asRecord(created.operation.result);
+        }
+        const leaseHolder = `cli-discard:${input.requestId}`;
+        const revision = await acquireArtifactRevisionLease({
+            appData,
+            revisionId: input.revisionId,
+            holder: leaseHolder,
+        })
+            .then(() => discardArtifactRevision({
+            appData,
+            revisionId: input.revisionId,
+            holder: leaseHolder,
+        }))
+            .finally(() => releaseArtifactRevisionLease({
+            appData,
+            revisionId: input.revisionId,
+            holder: leaseHolder,
+        }).catch(() => { }));
+        const result = { ok: true, revisionId: revision.revisionId, state: revision.state };
+        await operations.update(created.operation.operationId, {
+            state: "succeeded",
+            startedAt: created.operation.createdAt,
+            finishedAt: new Date().toISOString(),
+            result,
+        });
+        return result;
+    }
+    if (!input.runId || !input.nodeId || (!input.artifactPath && !input.artifactId)) {
+        throw new Error("dag artifact requires --run-id, --node-id, and --artifact <relative-path> or --artifact-id <id>");
+    }
+    const located = await locateDagRun(repoRoot, input.runId);
+    if (!located)
+        throw new Error(`dag run not found: ${input.runId}`);
+    const graph = buildArtifactBindingGraph(await readDagRunSpec(located.runDir));
+    const declaration = graph.artifacts.find((item) => item.producerNodeId === input.nodeId &&
+        (input.artifactId
+            ? item.artifactId === input.artifactId
+            : item.path === input.artifactPath));
+    if (!declaration)
+        throw new Error("ARTIFACT_BINDING_UNAVAILABLE");
+    if (input.action === "consumers") {
+        return {
+            schemaVersion: 1,
+            runId: input.runId,
+            nodeId: input.nodeId,
+            artifactId: declaration.artifactId,
+            artifactPath: declaration.path,
+            directConsumerNodeIds: declaration.directConsumerNodeIds,
+            graphSha256: graph.artifactGraphSha256,
+        };
+    }
+    if (!input.requestId || (!input.file && !input.candidateUpload)) {
+        throw new Error("dag artifact revision stage requires --file or --candidate-upload, and --request-id");
+    }
+    const appData = openConsoleAppData({
+        repoRoot,
+        ...(cliOptions?.appDataRoot ? { appDataRoot: cliOptions.appDataRoot } : {}),
+    });
+    // The candidate upload lives in app-data and is cross-process mutable;
+    // resolve + read it TOCTOU-safe (O_NOFOLLOW fd read) instead of
+    // lstat-then-readFile, so a swapped symlink can never feed an unintended
+    // file into the stage. Both the path resolution (assertSafeAppDataPath
+    // rejects symlinks/hardlinks) and the fd read map to the stable
+    // ARTIFACT_REVISION_PATH_INVALID code.
+    let candidateBytes;
+    if (input.candidateUpload) {
+        try {
+            if (!/^[a-f0-9]{64}$/.test(input.candidateUpload)) {
+                throw new Error("invalid --candidate-upload hash");
+            }
+            const candidatePath = artifactRevisionUploadPath(appData, input.candidateUpload);
+            candidateBytes = await readFileBoundarySafe({
+                boundaryRoot: path.dirname(candidatePath),
+                targetPath: candidatePath,
+                label: "candidate upload",
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (/symlink|hardlink|single-link|regular|boundary|escap|app-data/i.test(message)) {
+                throw new Error("ARTIFACT_REVISION_PATH_INVALID");
+            }
+            throw error;
+        }
+    }
+    else {
+        const candidatePath = path.resolve(repoRoot, input.file);
+        const stat = await lstat(candidatePath);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) {
+            throw new Error("candidate must be an owned regular file");
+        }
+        candidateBytes = await readFile(candidatePath);
+    }
+    if (candidateBytes.byteLength > 10 * 1024 * 1024)
+        throw new Error("candidate exceeds 10 MiB");
+    const operations = new OperationStore(appData);
+    const actionParams = {
+        runId: input.runId,
+        nodeId: input.nodeId,
+        artifactPath: declaration.path,
+        candidateSha256: sha256(candidateBytes),
+        candidateBytes: candidateBytes.byteLength,
+    };
+    const created = await operations.create({
+        clientRequestId: input.requestId,
+        action: "cliArtifactRevisionStage",
+        actionParams,
+    });
+    if (created.kind === "conflict")
+        throw new Error(created.code);
+    if (created.kind === "idempotent" && created.operation.state === "succeeded") {
+        return asRecord(created.operation.result);
+    }
+    const parent = await readRevisionParentArtifact({
+        cwd: repoRoot,
+        runId: input.runId,
+        producerNodeId: input.nodeId,
+        artifactId: declaration.artifactId,
+    });
+    const revision = await createArtifactRevision({
+        appData,
+        parentRunId: input.runId,
+        producerNodeId: input.nodeId,
+        declaration: parent.declaration,
+        parentSha256: parent.parentSha256,
+        parentBytes: parent.parentBytes,
+        candidateBytes,
+        mediaType: declaration.mediaType,
+        artifactSchemaResolver: resolveArtifactRevisionSchema,
+    });
+    const projected = {
+        revisionId: revision.revisionId,
+        state: revision.state,
+        parent: revision.parent,
+        candidate: {
+            sha256: revision.candidate.sha256,
+            bytes: revision.candidate.bytes,
+            mediaType: revision.candidate.mediaType,
+            uploadedAt: revision.candidate.uploadedAt,
+        },
+        validation: revision.validation,
+        diff: {
+            kind: revision.diff.kind,
+            summary: revision.diff.summary,
+            truncated: revision.diff.truncated,
+        },
+        expiresAt: revision.expiresAt,
+    };
+    const result = { ok: true, revision: projected };
+    await operations.update(created.operation.operationId, {
+        state: "succeeded",
+        startedAt: created.operation.createdAt,
+        finishedAt: new Date().toISOString(),
+        result,
+    });
+    return result;
+}
+function asRecord(value) {
+    return value && typeof value === "object" ? value : { ok: true };
+}
+export async function runDagArtifact(repoRoot, args) {
+    const input = parseArtifactArgs(args);
+    try {
+        const result = await runDagArtifactCore(repoRoot, args);
+        if (input.action === "discard") {
+            print(result, input.json, `Discarded ${String(result.revisionId ?? "")}`);
+        }
+        else if (input.action === "consumers") {
+            const consumers = result;
+            print(result, input.json, `${consumers.artifactPath}: ${(consumers.directConsumerNodeIds ?? []).join(", ") || "no consumers"}`);
+        }
+        else {
+            print(result, input.json, `Staged revision ${String(result.revisionId ?? "")}`);
+        }
+    }
+    catch (error) {
+        if (!input.json)
+            throw error;
+        const message = error instanceof Error ? error.message : String(error);
+        const candidateCode = message.split(":", 1)[0]?.trim() ?? "";
+        const code = /^[A-Z][A-Z0-9_]+$/.test(candidateCode)
+            ? candidateCode
+            : "INTERNAL_ERROR";
+        process.stdout.write(`${JSON.stringify({ schemaVersion: 1, ok: false, error: { code, message } }, null, 2)}\n`);
+        process.stderr.write(`${message}\n`);
+        process.exitCode = 1;
+    }
+}