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

package/dist/commands/dag-context.js

@@ -0,0 +1,184 @@
+import { randomBytes } from "node:crypto";
+import { link, lstat, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { buildContextBundle } from "../workflows/dag/context-transfer/context-bundle.js";
+import { effectiveNodeContextV1Schema } from "../shared/context-transfer.js";
+import { locateDagRun } from "../workflows/dag/lifecycle.js";
+function parseContextArgs(args) {
+    const action = args[0];
+    if (action !== "show" && action !== "export") {
+        throw new Error("usage: dag context <show|export> --run-id <id> --node-id <id> --attempt <n> [--json]");
+    }
+    let runId = "";
+    let nodeId = "";
+    let attempt = 0;
+    let json = false;
+    let target = "generic";
+    let profile = "redacted";
+    let output;
+    let acknowledgeSensitiveData = false;
+    for (let index = 1; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--run-id")
+            runId = args[++index] ?? "";
+        else if (arg.startsWith("--run-id="))
+            runId = arg.slice(9);
+        else if (arg === "--node-id")
+            nodeId = args[++index] ?? "";
+        else if (arg.startsWith("--node-id="))
+            nodeId = arg.slice(10);
+        else if (arg === "--attempt")
+            attempt = Number(args[++index]);
+        else if (arg.startsWith("--attempt="))
+            attempt = Number(arg.slice(10));
+        else if (arg === "--target")
+            target = (args[++index] ?? "");
+        else if (arg.startsWith("--target="))
+            target = arg.slice(9);
+        else if (arg === "--redaction")
+            profile = (args[++index] ?? "");
+        else if (arg.startsWith("--redaction="))
+            profile = arg.slice(12);
+        else if (arg === "--output")
+            output = args[++index];
+        else if (arg.startsWith("--output="))
+            output = arg.slice(9);
+        else if (arg === "--acknowledge-sensitive-data")
+            acknowledgeSensitiveData = true;
+        else if (arg === "--json")
+            json = true;
+        else
+            throw new Error(`unknown dag context flag: ${arg}`);
+    }
+    if (!runId || !nodeId || !Number.isSafeInteger(attempt) || attempt < 1) {
+        throw new Error("dag context requires --run-id, --node-id, and positive --attempt");
+    }
+    if (!["generic", "pi-session", "pi-handoff", "readable"].includes(target)) {
+        throw new Error(`unsupported context target: ${target}`);
+    }
+    if (profile !== "redacted" && profile !== "raw") {
+        throw new Error(`unsupported redaction profile: ${profile}`);
+    }
+    if (action === "export" && !output) {
+        throw new Error("dag context export requires --output <path>");
+    }
+    if (action === "export" && profile === "raw" && !acknowledgeSensitiveData) {
+        throw new Error("raw context export requires --acknowledge-sensitive-data");
+    }
+    return {
+        action,
+        runId,
+        nodeId,
+        attempt,
+        json,
+        target,
+        profile,
+        ...(output ? { output } : {}),
+        acknowledgeSensitiveData,
+    };
+}
+function receiptPath(runDir, nodeId, attempt) {
+    return path.join(runDir, nodeId, "context-receipts", `attempt-${attempt}.json`);
+}
+function outputLabel(repoRoot, outputPath) {
+    const relative = path
+        .relative(repoRoot, outputPath)
+        .split(path.sep)
+        .join("/");
+    return relative && !relative.startsWith("../") && relative !== ".."
+        ? relative
+        : path.basename(outputPath);
+}
+export async function runDagContextCore(repoRoot, args) {
+    const input = parseContextArgs(args);
+    const located = await locateDagRun(repoRoot, input.runId);
+    if (!located)
+        throw new Error(`dag run not found: ${input.runId}`);
+    if (input.action === "show") {
+        let receipt;
+        try {
+            receipt = effectiveNodeContextV1Schema.parse(JSON.parse(await readFile(receiptPath(located.runDir, input.nodeId, input.attempt), "utf8")));
+        }
+        catch {
+            throw new Error("CONTEXT_RECEIPT_MISSING");
+        }
+        return {
+            schemaVersion: 1,
+            runId: input.runId,
+            nodeId: input.nodeId,
+            attempt: input.attempt,
+            capturedAt: receipt.identity.capturedAt,
+            contextDigest: receipt.contextDigest,
+            componentCount: receipt.orderedComponents.length,
+            truncationCount: receipt.promptAssembly.truncations.length,
+            runtime: {
+                executor: receipt.runtime.executor,
+                model: receipt.runtime.resolvedModel ?? receipt.runtime.modelHint ?? null,
+                skills: receipt.runtime.skills,
+                extensions: receipt.runtime.extensions,
+                tools: receipt.runtime.activeTools,
+            },
+        };
+    }
+    const outputPath = path.resolve(repoRoot, input.output);
+    const parent = path.dirname(outputPath);
+    const parentStat = await lstat(parent).catch(() => undefined);
+    if (parentStat?.isSymbolicLink())
+        throw new Error("unsafe output parent symlink");
+    const existing = await lstat(outputPath).catch(() => undefined);
+    if (existing)
+        throw new Error("context export output already exists");
+    const bundle = await buildContextBundle({
+        runDir: located.runDir,
+        runId: input.runId,
+        nodeId: input.nodeId,
+        attempt: input.attempt,
+        profile: input.profile,
+        target: input.target,
+        ...(input.profile === "raw" && input.acknowledgeSensitiveData
+            ? {
+                rawAcknowledgement: {
+                    requestId: `cli-${bundleRequestIdentity(input)}`,
+                    acknowledgedAt: new Date().toISOString(),
+                },
+            }
+            : {}),
+    });
+    const temporaryPath = `${outputPath}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    try {
+        await writeFile(temporaryPath, bundle.zipBytes, { flag: "wx", mode: 0o600 });
+        await link(temporaryPath, outputPath);
+        await rm(temporaryPath, { force: true });
+    }
+    catch (error) {
+        await rm(temporaryPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+    return {
+        schemaVersion: 1,
+        bundleId: bundle.manifest.bundleId,
+        bundleSha256: bundle.manifest.bundleSha256,
+        profile: bundle.manifest.profile,
+        target: bundle.manifest.target,
+        bytes: bundle.zipBytes.byteLength,
+        output: outputLabel(repoRoot, outputPath),
+    };
+}
+export async function runDagContext(repoRoot, args) {
+    const input = parseContextArgs(args);
+    const result = await runDagContextCore(repoRoot, args);
+    if (input.action === "show") {
+        const summary = result;
+        process.stdout.write(input.json
+            ? `${JSON.stringify(result, null, 2)}\n`
+            : `Context ${summary.runId}/${summary.nodeId} attempt ${summary.attempt}\nDigest: ${summary.contextDigest}\nComponents: ${summary.componentCount}\n`);
+        return;
+    }
+    const exported = result;
+    process.stdout.write(input.json
+        ? `${JSON.stringify(result, null, 2)}\n`
+        : `Exported ${exported.bundleId} to ${exported.output} (${exported.bytes} bytes)\n`);
+}
+function bundleRequestIdentity(input) {
+    return `${input.runId}-${input.nodeId}-${input.attempt}`.replace(/[^a-zA-Z0-9._-]/g, "-");
+}

package/dist/commands/dag-follow-up.js

@@ -0,0 +1,138 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { FRONTEND_REVIEW_FINDINGS_PRD_REL, readFrontendReviewFindingsPrd, } from "../workflows/dag/frontend-review-findings.js";
+import { locateDagRun } from "../workflows/dag/lifecycle.js";
+import { createTask, getTaskPaths } from "../task/runtime.js";
+import { importPrdDocument } from "../task/source-references.js";
+function parseFlagValue(rawArgs, flag) {
+    const index = rawArgs.indexOf(flag);
+    if (index < 0 || index + 1 >= rawArgs.length)
+        return undefined;
+    return rawArgs[index + 1];
+}
+export function parseDagFollowUpArgs(rawArgs) {
+    const positional = rawArgs.filter((arg) => !arg.startsWith("-"));
+    const parentRunId = positional[0];
+    if (!parentRunId) {
+        throw new Error("usage: dag follow-up <parent-run-id> [--task-id <id>] [--execute] [--profile <profile>]");
+    }
+    return {
+        parentRunId,
+        taskId: parseFlagValue(rawArgs, "--task-id"),
+        execute: rawArgs.includes("--execute"),
+        profile: parseFlagValue(rawArgs, "--profile"),
+    };
+}
+export function deriveFollowUpTaskId(parentRunId) {
+    // Deterministic, valid task id derived from the parent run id.
+    return `${parentRunId}-followup`;
+}
+/** CLI entry: parse raw args and run the follow-up flow. */
+export async function runDagFollowUp(repoRoot, rawArgs) {
+    const parsed = parseDagFollowUpArgs(rawArgs);
+    const result = await runDagFollowUpInternal(repoRoot, parsed.parentRunId, {
+        taskId: parsed.taskId,
+        execute: parsed.execute,
+        profile: parsed.profile,
+    });
+    console.log(JSON.stringify(result, null, 2));
+    if (!result.ok) {
+        process.exitCode = result.mode === "blocked" ? 2 : 1;
+    }
+}
+export async function runDagFollowUpInternal(repoRoot, parentRunId, options = {}) {
+    const located = await locateDagRun(repoRoot, parentRunId);
+    if (!located) {
+        return {
+            ok: false,
+            mode: "invalid",
+            reason: `dag run not found: ${parentRunId}`,
+        };
+    }
+    const prd = await readFrontendReviewFindingsPrd(located.runDir);
+    if (!prd) {
+        return {
+            ok: false,
+            mode: "invalid",
+            reason: `no frontend review findings PRD found in run ${parentRunId} (${FRONTEND_REVIEW_FINDINGS_PRD_REL}); the review must have committed request_review_changes`,
+        };
+    }
+    const taskId = options.taskId ?? deriveFollowUpTaskId(parentRunId);
+    try {
+        await createTask(repoRoot, taskId, `修复 review 发现（parent ${parentRunId}）`);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            mode: "blocked",
+            reason: `failed to create task ${taskId}: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    // Materialize the PRD draft into the task's source directory so the task
+    // lifecycle can import it as its requirement.
+    const prdMaterialized = path.join(getTaskPaths(repoRoot, taskId).sourceDir, "review-findings-prd.md");
+    try {
+        await mkdir(path.dirname(prdMaterialized), { recursive: true });
+        await importPrdDocument({
+            repoRoot,
+            taskId,
+            filePath: path.join(located.runDir, FRONTEND_REVIEW_FINDINGS_PRD_REL),
+            name: "review-findings-prd",
+        });
+    }
+    catch (error) {
+        return {
+            ok: false,
+            mode: "blocked",
+            reason: `failed to import PRD into task ${taskId}: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (!options.execute) {
+        return {
+            ok: true,
+            mode: "created",
+            taskId,
+            prdPath: prdMaterialized,
+            next: {
+                kind: "advance",
+                command: `loop-agent task advance ${taskId} --task-kind frontend-implementation --json`,
+            },
+        };
+    }
+    // Execute: advance through the frontend DAG.
+    const { advanceTaskLifecycle } = await import("../application/task-lifecycle/advance.js");
+    const profile = options.profile === "auto" ||
+        options.profile === "minimal" ||
+        options.profile === "standard" ||
+        options.profile === "reviewed" ||
+        options.profile === "supervised"
+        ? options.profile
+        : undefined;
+    const result = await advanceTaskLifecycle({
+        repoRoot,
+        taskId,
+        taskKind: "frontend-implementation",
+        taskKindExplicit: true,
+        ...(profile ? { profile, profileExplicit: true } : {}),
+        observer: undefined,
+    });
+    const ok = result.lifecycleState === "run-succeeded" ||
+        result.lifecycleState === "awaiting-write-set-approval";
+    return {
+        ok,
+        mode: ok ? "created" : "blocked",
+        taskId,
+        prdPath: prdMaterialized,
+        reason: ok
+            ? undefined
+            : `advance lifecycleState: ${result.lifecycleState}${result.blockers.length > 0
+                ? `; blockers: ${result.blockers.map((b) => b.code).join(", ")}`
+                : ""}`,
+        next: ok
+            ? undefined
+            : {
+                kind: "advance",
+                command: `loop-agent task advance ${taskId} --task-kind frontend-implementation --json`,
+            },
+    };
+}

package/dist/commands/dag-rerun-task.js

@@ -11,6 +11,8 @@ export async function runDagRerunTask(repoRoot, rawArgs) {
         profileExplicit: parsed.profileExplicit,
         taskIdOverride: parsed.taskIdOverride,
         execute: parsed.execute,
+        frontendRecovery: parsed.frontendRecovery,
+        recoveryOperationId: parsed.recoveryOperationId,
     });
     console.log(JSON.stringify(result, null, 2));
     if (!result.ok) {

package/dist/commands/dag-rerun.js

@@ -1,6 +1,13 @@
+import { randomBytes } from "node:crypto";
 import { readFile } from "node:fs/promises";
+import { executeArtifactRevisionContinuation, planArtifactRevisionContinuation, } from "../workflows/dag/context-transfer/operator-actions.js";
 import { isDagRerunPromptOverrideEnabled } from "../shared/dag-prompt-override.js";
-import { executeDagRerun, planDagRerun, } from "../workflows/dag/rerun-run.js";
+import { workerContinuationAuthorityV1Schema, } from "../shared/context-transfer.js";
+import { openConsoleAppData } from "../infrastructure/console/app-data.js";
+import { buildArtifactOverrideSet, consumeArtifactRevision, readArtifactRevision, readArtifactRevisionCandidate, acquireArtifactRevisionLease, releaseArtifactRevisionLease, EXECUTE_REVISION_LEASE_TTL_MS, } from "../infrastructure/console/artifact-revision-store.js";
+import { buildArtifactBindingGraph } from "../workflows/dag/artifact-bindings.js";
+import { locateDagRun, readDagRunSpec } from "../workflows/dag/lifecycle.js";
+import { executeDagRerun, planDagRerun, readOperatorRequestReplay, } from "../workflows/dag/rerun-run.js";
 export function parseDagRerunArgs(args) {
     if (args.length === 0) {
         throw new Error("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]");
@@ -111,6 +118,10 @@ async function loadPromptOverrides(specs, mode) {
     return overrides;
 }
 export async function runDagRerun(repoRoot, rawArgs) {
+    if (rawArgs.some((arg) => arg === "--artifact-revision" || arg.startsWith("--artifact-revision="))) {
+        await runArtifactRevisionRerun(repoRoot, rawArgs);
+        return;
+    }
     const parsed = parseDagRerunArgs(rawArgs);
     let promptOverrides;
     const hasOverrides = parsed.promptOverrideSpecs.length > 0 ||
@@ -163,3 +174,197 @@ export async function runDagRerun(repoRoot, rawArgs) {
         }
     }
 }
+function readFlag(args, name) {
+    const exact = args.indexOf(name);
+    if (exact >= 0)
+        return args[exact + 1];
+    const prefix = `${name}=`;
+    return args.find((arg) => arg.startsWith(prefix))?.slice(prefix.length);
+}
+function parseWorkerContinuationAuthority(raw) {
+    if (raw === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("dag rerun --worker-continuation must be valid JSON");
+    }
+    const result = workerContinuationAuthorityV1Schema.safeParse(parsed);
+    if (!result.success) {
+        throw new Error(`dag rerun --worker-continuation is invalid: ${result.error.issues[0]?.message ?? "schema mismatch"}`);
+    }
+    return result.data;
+}
+function executeLeaseHolder(requestId) {
+    // The request id identifies the idempotency envelope, not a live process.
+    // A unique invocation holder prevents two concurrent direct CLI invocations
+    // with the same request id from treating each other as a lease renewal.
+    return `cli-execute:${requestId}:${randomBytes(12).toString("hex")}`;
+}
+/**
+ * Hold the staging lease across candidate read + continuation execution so a
+ * concurrent discard/second execute fails with LEASE_HELD and a crashed
+ * process leaves a stale, TTL-takeover-able lease instead of silent races.
+ * The acquire/renew here also refreshes the sliding window before the long
+ * child run starts.
+ */
+async function withExecuteRevisionLease(appData, requestId, revisionId, operation) {
+    const holder = executeLeaseHolder(requestId);
+    await acquireArtifactRevisionLease({
+        appData,
+        revisionId,
+        holder,
+        ttlMs: EXECUTE_REVISION_LEASE_TTL_MS,
+    });
+    try {
+        return await operation(holder);
+    }
+    finally {
+        await releaseArtifactRevisionLease({
+            appData,
+            revisionId,
+            holder,
+        }).catch(() => { });
+    }
+}
+export async function runArtifactRevisionRerunCore(repoRoot, rawArgs, cliOptions) {
+    const allowed = new Set([
+        "--run-id",
+        "--artifact-revision",
+        "--plan-hash",
+        "--request-id",
+        "--reason",
+        "--worker-continuation",
+    ]);
+    for (let index = 0; index < rawArgs.length; index += 1) {
+        const arg = rawArgs[index];
+        if (arg === "--plan" || arg === "--json")
+            continue;
+        const name = arg.split("=", 1)[0];
+        if (!allowed.has(name))
+            throw new Error(`unknown artifact revision rerun flag: ${arg}`);
+        if (!arg.includes("="))
+            index += 1;
+    }
+    const parentRunId = readFlag(rawArgs, "--run-id")?.trim();
+    const revisionId = readFlag(rawArgs, "--artifact-revision")?.trim();
+    const planOnly = rawArgs.includes("--plan");
+    if (!parentRunId || !revisionId) {
+        throw new Error("dag rerun artifact revision requires --run-id and --artifact-revision");
+    }
+    const appData = openConsoleAppData({
+        repoRoot,
+        ...(cliOptions?.appDataRoot ? { appDataRoot: cliOptions.appDataRoot } : {}),
+    });
+    const planHash = readFlag(rawArgs, "--plan-hash")?.trim();
+    const requestId = readFlag(rawArgs, "--request-id")?.trim();
+    const reason = readFlag(rawArgs, "--reason")?.trim();
+    const workerContinuation = parseWorkerContinuationAuthority(readFlag(rawArgs, "--worker-continuation"));
+    if (!planOnly && (!planHash || !requestId || !reason)) {
+        throw new Error("dag rerun artifact revision execute requires --plan-hash, --request-id, and --reason");
+    }
+    if (!planOnly) {
+        // Replay-first (B4): a prior execute may have consumed the revision and
+        // the staging record may already have been reconciled away. The persisted
+        // operator request is the authoritative idempotent result and must be
+        // honored before any dependency on the revision metadata. A replay that
+        // does not match the requested parent/planHash is a reuse conflict, not a
+        // valid idempotent answer (SF2).
+        const replay = await readOperatorRequestReplay(repoRoot, requestId, {
+            parentRunId,
+            planHash,
+        });
+        if (replay) {
+            return {
+                payload: replay,
+                exitCode: replay.ok
+                    ? 0
+                    : replay.errorCode === "RERUN_PLAN_DRIFT"
+                        ? 3
+                        : replay.errorCode === "INELIGIBLE"
+                            ? 2
+                            : 1,
+            };
+        }
+    }
+    const revision = await readArtifactRevision(appData, revisionId);
+    if (!revision || revision.parent.runId !== parentRunId) {
+        throw new Error("ARTIFACT_REVISION_EXPIRED");
+    }
+    const located = await locateDagRun(repoRoot, parentRunId);
+    if (!located)
+        throw new Error(`dag run not found: ${parentRunId}`);
+    const declaration = buildArtifactBindingGraph(await readDagRunSpec(located.runDir)).artifacts.find((item) => item.producerNodeId === revision.parent.nodeId &&
+        item.path === revision.parent.artifactPath);
+    if (!declaration)
+        throw new Error("ARTIFACT_BINDING_UNAVAILABLE");
+    const artifactOverrides = buildArtifactOverrideSet(revision);
+    if (planOnly) {
+        if (planHash || requestId || reason) {
+            throw new Error("dag rerun --plan cannot be combined with execute flags");
+        }
+        const plan = await planArtifactRevisionContinuation({
+            cwd: repoRoot,
+            parentRunId,
+            artifactId: declaration.artifactId,
+            artifactOverrides,
+            stagingRevisionSha256: revision.candidate.sha256,
+            ...(workerContinuation
+                ? { workerContinuationAuthority: workerContinuation }
+                : {}),
+        });
+        return { payload: { ok: plan.eligible, plan }, exitCode: plan.eligible ? 0 : 2 };
+    }
+    if (revision.state === "consumed") {
+        // Replay was not found above, so this is a crashed consume without a
+        // persisted result — refuse rather than re-execute a consumed revision.
+        throw new Error("ARTIFACT_REVISION_EXPIRED: revision already consumed and no operator replay exists for this request");
+    }
+    const result = await withExecuteRevisionLease(appData, requestId, revision.revisionId, async (leaseHolder) => {
+        const candidateBytes = await readArtifactRevisionCandidate({ appData, revision });
+        return executeArtifactRevisionContinuation({
+            cwd: repoRoot,
+            parentRunId,
+            artifactId: declaration.artifactId,
+            artifactOverrides,
+            stagingRevisionSha256: revision.candidate.sha256,
+            candidateBytes,
+            planHash: planHash,
+            requestId: requestId,
+            reason: reason,
+            ...(workerContinuation
+                ? { workerContinuationAuthority: workerContinuation }
+                : {}),
+            consumeRevision: async ({ revisionId: consumedId, expectedSha256 }) => {
+                await consumeArtifactRevision({
+                    appData,
+                    revisionId: consumedId,
+                    expectedSha256,
+                    holder: leaseHolder,
+                });
+            },
+        });
+    });
+    return {
+        payload: result,
+        exitCode: result.ok
+            ? 0
+            : result.errorCode === "RERUN_PLAN_DRIFT"
+                ? 3
+                : result.errorCode === "INELIGIBLE"
+                    ? 2
+                    : 1,
+    };
+}
+async function runArtifactRevisionRerun(repoRoot, rawArgs) {
+    const { payload, exitCode } = await runArtifactRevisionRerunCore(repoRoot, rawArgs);
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    if (exitCode !== 0) {
+        const failure = payload;
+        const message = failure.message ?? failure.errorCode ?? `artifact rerun failed with exit ${exitCode}`;
+        process.stderr.write(`${message}\n`);
+        process.exitCode = exitCode;
+    }
+}

package/dist/commands/init.js

@@ -14,6 +14,19 @@ const GITIGNORE_BLOCK_START = "# LOOP_AGENT_INIT_START";
 const GITIGNORE_BLOCK_END = "# LOOP_AGENT_INIT_END";
 const INIT_SURFACE_STATE_PATH = ".harness/init-surface.json";
 const DEFAULT_GOVERNANCE_ROOT = "ai_workspace/loop-agent";
+function buildSpecRegistry() {
+    return `${JSON.stringify({
+        version: 1,
+        roots: [],
+        discovery: {
+            enabled: true,
+            maxDepth: 3,
+            maxFiles: 100,
+            maxBytes: 1048576,
+            timeoutMs: 2000,
+        },
+    }, null, 2)}\n`;
+}
 const CORE_DOC_FILES = [
     { source: "README.md", target: "README.md" },
     {
@@ -610,7 +623,7 @@ if (
   (assessment.status === "passed" && assessment.currentExitCode !== 0) ||
   (assessment.status === "baseline-debt" && assessment.currentExitCode === 0)
 ) fail();
-if (!assessment.baselineRef || assessment.baselineRef.nodeId !== "frontend-lint-baseline-shell") fail();
+if (!assessment.baselineRef || assessment.baselineRef.nodeId !== "frontend-writer-admission-shell") fail();
 const baselineRaw = readContained(assessment.baselineRef.path);
 if (sha256(baselineRaw) !== assessment.baselineRef.sha256) fail();
 let baseline;
@@ -1312,6 +1325,9 @@ async function buildDesiredSurfaceContent(input) {
             }), null, 2)}\n`,
         };
     }
+    if (manifestPath === "docs/spec-registry.json") {
+        return { content: buildSpecRegistry() };
+    }
     if (manifestPath === OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH) {
         return { content: buildOpenCodeTransientRetryPluginSource() };
     }
@@ -1709,6 +1725,8 @@ async function listRelativeFiles(rootPath) {
 async function expectedLegacyInitFileSha(input) {
     if (input.legacyPath.startsWith("docs/")) {
         const doc = input.legacyPath.slice("docs/".length);
+        if (doc === "spec-registry.json")
+            return sha256Text(buildSpecRegistry());
         const generated = buildGeneratedCoreDoc({
             doc,
             projectName: input.projectName,
@@ -2707,6 +2725,14 @@ export async function initializeLoopAgentProject(options) {
         targetRelativePath: path.join(governanceRoot, "templates"),
         written,
     });
+    await writeTextIfMissing({
+        repoRoot,
+        relativePath: path.join(governanceRoot, "spec-registry.json"),
+        content: buildSpecRegistry(),
+        merge,
+        written,
+        skipped,
+    });
     if (profile === "full") {
         // Project repo-local skills live only under `.agents/skills/`.
         // The package still ships `skills/` as the built-in fallback source.

package/dist/commands/task-advance.js

@@ -377,6 +377,25 @@ export async function runTaskAdvance(repoRoot, args) {
                 intervalMs: options.progressIntervalMs,
             });
         }
+        // Idempotent client-recovery surface install before any DAG run: the Pi
+        // context-overflow extension / OpenCode plugins / project .pi settings
+        // are normally installed by `loop-agent init`, but an upgraded or
+        // non-init-created project may lack them. Installing here (missing-only)
+        // ensures the overflow compact+retry recovery path is always present,
+        // independent of how the project was created. Best-effort: a failure to
+        // install never blocks the run.
+        if (options.approveGate && !options.dryRun) {
+            try {
+                const { runClientRecovery } = await import("./client-recovery.js");
+                // mode "project" installs only project-owned surfaces
+                // (.pi/extensions + .opencode/plugins + .pi/settings.json),
+                // never the user home; installs are missing-only.
+                await runClientRecovery({ repoRoot, mode: "project" });
+            }
+            catch {
+                // best-effort; do not fail the run over a recovery-surface install
+            }
+        }
         const result = await advanceTaskLifecycle(toUseCaseInput(repoRoot, taskId, options, progress?.observer));
         const outcome = mapOutcome(result);
         const gateStop = result.lifecycleState === "awaiting-write-set-approval" &&