@tea-agent/loop-agent 0.39.0-beta.7 → 0.39.0-beta.9

package/dist/task/source-prepare/source-fidelity-pi.js

@@ -0,0 +1,384 @@
+/**
+ * 生产 Source Fidelity Pi 适配器（AC-PROD-001..006 / AC-001..006）
+ *
+ * 为真实 `task advance` 的 prepare-contract 路径提供两个独立的 Pi 调用面：
+ * - reconcile：仅叙述性/歧义 ledger fragment 的顺序 reconciliation executor
+ *   （结构化片段由 ledger-reconciliation.ts 的 isStructuredMappableFragment
+ *   走代码映射，零 Pi 调用）；
+ * - review：context-only / duplicate / conflict 的独立 reviewer（与 reconciler
+ *   是不同调用阶段，最多一次有界修订，LEDGER_REVIEW_MAX_REVISIONS=1）。
+ *
+ * 模型队列镜像 semantic-intake.ts（MED→HIGH→LOW harness 档位 + Pi SDK 目录），
+ * 单次尝试沿用有界超时（SOURCE_FIDELITY_ATTEMPT_TIMEOUT_MS），工具面仅只读
+ * read/grep/find/ls（无写工具）。所有模型输出经 validateOutput + zod 严格校验：
+ * 无效 JSON/schema、越界 canonical ID、排除类 disposition 缺理由一律抛
+ * LedgerReconciliationError / LedgerReviewError，由 prepare.ts 既有 catch 转为
+ * 稳定 SOURCE_FIDELITY_* 阻断码，绝不回退确定性 heuristics。队列空 / 执行失败 /
+ * 超时同样 fail closed。
+ */
+import { z } from "zod";
+import { executePiStep } from "../../executors/pi-executor.js";
+import { resolveDagPiModelConfig } from "../../executors/dag-pi-executor.js";
+import { resolveExecutorModelMatrices } from "../../executors/model-routing.js";
+import { listPiSdkAvailableModels } from "../../executors/pi-sdk-executor.js";
+import { loadHarnessManifest } from "../../governance/harness.js";
+import { loadTaskConfig } from "../runtime.js";
+import { buildSemanticIntakeModelQueue, extractJsonObject, } from "./semantic-intake.js";
+import { LEDGER_RECONCILIATION_DEFAULT_BUDGET_CHARS, LedgerReconciliationError, } from "./ledger-reconciliation.js";
+import { LedgerReviewError, } from "./ledger-review.js";
+/** 只读工具面（AC-003）：source fidelity Pi 调用无任何写工具。 */
+export const SOURCE_FIDELITY_PI_TOOL_NAMES = [
+    "read",
+    "grep",
+    "find",
+    "ls",
+];
+/** 单次 reconciliation/review Pi 尝试的墙钟上限（镜像 SEMANTIC_INTAKE_ATTEMPT_TIMEOUT_MS）。 */
+export const SOURCE_FIDELITY_ATTEMPT_TIMEOUT_MS = 300_000;
+/** 接线侧门 taskKind（AC-PROD-005）。 */
+export const SOURCE_FIDELITY_TASK_KIND = "frontend-implementation";
+const FRAGMENT_DISPOSITIONS = [
+    "requirement",
+    "acceptance",
+    "constraint",
+    "non-goal",
+    "duplicate",
+    "context-only",
+    "unresolved",
+];
+const EXCLUSION_DISPOSITIONS = new Set([
+    "context-only",
+    "duplicate",
+    "unresolved",
+]);
+const reconciliationResultSchema = z.object({
+    fragmentId: z.string().min(1),
+    mappedIds: z.array(z.string().min(1)).default([]),
+    disposition: z.enum(FRAGMENT_DISPOSITIONS),
+    reason: z.string().min(1).optional(),
+});
+const reviewResponseSchema = z.object({
+    fragmentId: z.string().min(1),
+    approved: z.boolean(),
+    reason: z.string().min(1).optional(),
+    revision: z
+        .object({
+        disposition: z.enum(FRAGMENT_DISPOSITIONS).optional(),
+        reason: z.string().min(1).optional(),
+    })
+        .optional(),
+});
+/**
+ * 模型队列构建镜像 semantic-intake.ts：MED→HIGH→LOW（harness executors.pi）+
+ * Pi SDK 目录（已认证优先、非 chat 模型过滤、额外模型上限沿用
+ * SEMANTIC_INTAKE_MAX_EXTRA_MODELS）。队列空即 fail closed。
+ */
+export function buildSourceFidelityModelQueue(input) {
+    return buildSemanticIntakeModelQueue(input);
+}
+async function buildProductionModelQueue(repoRoot, listAvailableModels) {
+    const manifest = await loadHarnessManifest(repoRoot);
+    const models = resolveExecutorModelMatrices(manifest);
+    let available = [];
+    try {
+        available = listAvailableModels
+            ? await listAvailableModels()
+            : await listPiSdkAvailableModels();
+    }
+    catch {
+        available = [];
+    }
+    return buildSourceFidelityModelQueue({ harness: models.pi, available });
+}
+function buildReconciliationPrompt(request) {
+    return [
+        "You are a read-only source-fidelity-reconcile agent for loop-agent task intake.",
+        "Map the source fragment to EXISTING canonical requirement ids only.",
+        "Return exactly one JSON object (optional json fence); no prose outside it.",
+        "Rules:",
+        "- mappedIds: canonical requirement ids from the provided list that this fragment directly supports; empty array when none.",
+        "- fragmentId: MUST equal the requested fragment id exactly (echo the `fragment id:` line verbatim); identity mismatch is rejected.",
+        "- disposition: exactly one of requirement|acceptance|constraint|non-goal|duplicate|context-only|unresolved.",
+        "- reason: REQUIRED (non-empty) when disposition is context-only, duplicate or unresolved; optional otherwise.",
+        "- Never invent canonical ids; only use ids present in the provided canonical requirements.",
+        "- Never invent requirements or human resolutions.",
+        JSON.stringify({
+            fragmentId: "REQ-SRC-AB12CD34EF56",
+            mappedIds: ["AC-001"],
+            disposition: "requirement",
+            reason: "optional; required for exclusion dispositions",
+        }, null, 2),
+        `fragment id: ${request.fragment.id}`,
+        `fragment path: ${request.fragment.path}`,
+        `fragment headingPath: ${request.fragment.headingPath}`,
+        `fragment lineRange: ${JSON.stringify(request.fragment.lineRange)}`,
+        `budgetChars: ${request.budgetChars}`,
+        "fragment text:",
+        "```markdown",
+        request.fragment.text,
+        "```",
+        "canonical requirements:",
+        JSON.stringify(request.canonicalRequirements, null, 2),
+    ].join("\n\n");
+}
+function buildReviewPrompt(request) {
+    return [
+        "You are an independent read-only source-fidelity-review agent for loop-agent task intake.",
+        "Review whether the given fragment's context-only / duplicate / conflict disposition is justified.",
+        "You are a separate stage from reconciliation: do not re-map fragments; only approve, reject, or propose at most one bounded revision.",
+        "Return exactly one JSON object (optional json fence); no prose outside it.",
+        "Rules:",
+        "- approved: true only when the exclusion/conflict handling is justified.",
+        "- fragmentId: MUST equal the requested fragment id exactly (echo the `fragment id:` line verbatim); identity mismatch is rejected.",
+        "- reason: recommended; explain the verdict.",
+        "- revision: optional single bounded revision {disposition, reason}; never invent requirements or human resolutions.",
+        JSON.stringify({
+            fragmentId: "REQ-SRC-AB12CD34EF56",
+            approved: true,
+            reason: "verdict rationale",
+            revision: {
+                disposition: "duplicate",
+                reason: "optional bounded revision",
+            },
+        }, null, 2),
+        `review kind: ${request.kind}`,
+        `fragment id: ${request.fragment.id}`,
+        `fragment disposition: ${request.fragment.disposition}`,
+        ...(request.fragment.reason
+            ? [`fragment reason: ${request.fragment.reason}`]
+            : []),
+        `fragment risk: ${request.fragment.risk}`,
+        `fragment canonicalRequirementIds: ${JSON.stringify(request.fragment.canonicalRequirementIds)}`,
+        ...(request.fragment.text.trim()
+            ? [
+                "fragment text:",
+                "```markdown",
+                request.fragment.text,
+                "```",
+            ]
+            : [
+                "fragment text: (bounded original text unavailable for this record)",
+                `fragment id: ${request.fragment.id}`,
+            ]),
+        "canonical requirements:",
+        JSON.stringify(request.canonicalRequirements, null, 2),
+        ...(request.resolutionAvailable
+            ? ["resolutionAvailable: true (conflict has a valid human resolution)"]
+            : []),
+    ].join("\n\n");
+}
+function validateReconciliationOutput(text, request) {
+    let raw;
+    try {
+        raw = extractJsonObject(text);
+    }
+    catch (error) {
+        throw new LedgerReconciliationError(`reconciliation output is not a JSON object: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let parsed;
+    try {
+        parsed = reconciliationResultSchema.parse(raw);
+    }
+    catch (error) {
+        throw new LedgerReconciliationError(`reconciliation output failed schema validation: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // 生产 fragmentId 绑定（AC-005 / AC-HARD-005）：缺失/错配即 fail closed，
+    // 保证 reviewer/reconciler 决策绑定到实际请求的 source fragment。
+    if (parsed.fragmentId !== request.fragmentId) {
+        throw new LedgerReconciliationError(`reconciliation output fragmentId ${parsed.fragmentId} does not match requested fragment ${request.fragmentId}`);
+    }
+    const outOfBounds = parsed.mappedIds.filter((id) => !request.canonicalIds.has(id));
+    if (outOfBounds.length > 0) {
+        throw new LedgerReconciliationError(`reconciliation output contains out-of-bounds canonical ids: ${outOfBounds.join(", ")}`);
+    }
+    if (EXCLUSION_DISPOSITIONS.has(parsed.disposition) && !parsed.reason?.trim()) {
+        throw new LedgerReconciliationError(`reconciliation output omitted the required exclusion reason for disposition ${parsed.disposition}`);
+    }
+    return {
+        mappedIds: parsed.mappedIds,
+        disposition: parsed.disposition,
+        ...(parsed.reason ? { reason: parsed.reason } : {}),
+    };
+}
+function validateReviewOutput(text, request) {
+    let raw;
+    try {
+        raw = extractJsonObject(text);
+    }
+    catch (error) {
+        throw new LedgerReviewError(`review output is not a JSON object: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let parsed;
+    try {
+        parsed = reviewResponseSchema.parse(raw);
+    }
+    catch (error) {
+        throw new LedgerReviewError(`review output failed schema validation: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // 生产 fragmentId 绑定（AC-005 / AC-HARD-005）：缺失/错配即 fail closed。
+    if (parsed.fragmentId !== request.fragmentId) {
+        throw new LedgerReviewError(`review output fragmentId ${parsed.fragmentId} does not match requested fragment ${request.fragmentId}`);
+    }
+    return {
+        approved: parsed.approved,
+        ...(parsed.reason ? { reason: parsed.reason } : {}),
+        ...(parsed.revision ? { revision: parsed.revision } : {}),
+    };
+}
+/**
+ * 执行一次生产 reconciliation：模型队列串行尝试（默认真实 executePiStep），
+ * 每个成功输出都经 validateOutput + zod 严格校验，全部失败抛
+ * LedgerReconciliationError（稳定 SOURCE_FIDELITY_RECONCILIATION_FAILED）。
+ */
+export async function runProductionLedgerReconciliation(request, options) {
+    const canonicalIds = new Set(request.canonicalRequirements.map((requirement) => requirement.id));
+    const parseAndValidate = (text) => validateReconciliationOutput(text, {
+        fragmentId: request.fragment.id,
+        canonicalIds,
+    });
+    const queue = options.modelQueue ??
+        (await buildProductionModelQueue(options.repoRoot, options.listAvailableModels));
+    if (queue.length === 0) {
+        throw new LedgerReconciliationError("source fidelity reconciliation has no MED/HIGH/LOW or Pi-supported models to try (fail closed)");
+    }
+    const prompt = buildReconciliationPrompt(request);
+    const execute = options.executePi ?? executePiStep;
+    const timeoutMs = options.timeoutMs ?? SOURCE_FIDELITY_ATTEMPT_TIMEOUT_MS;
+    let lastFailure = "";
+    for (const modelRef of queue) {
+        try {
+            const result = await execute({
+                attachedFiles: [],
+                modelConfig: resolveDagPiModelConfig(modelRef),
+                prompt,
+                repoRoot: options.repoRoot,
+                step: "analyze",
+                toolNames: [...SOURCE_FIDELITY_PI_TOOL_NAMES],
+                timeoutMs,
+                stallTimeoutMs: timeoutMs,
+                userMessage: "Reconcile the source fragment into the required JSON only.",
+                validateOutput: (text) => {
+                    try {
+                        parseAndValidate(text);
+                        return [];
+                    }
+                    catch (error) {
+                        return [error instanceof Error ? error.message : String(error)];
+                    }
+                },
+            });
+            if (!result.ok) {
+                lastFailure =
+                    `${result.failureCategory}: ${(result.stderr || result.assistantText).slice(0, 2000)}`;
+                continue;
+            }
+            try {
+                return parseAndValidate(result.assistantText);
+            }
+            catch (error) {
+                // 模型返回成功但输出未通过严格校验：视为 invalid-output，尝试下一模型。
+                lastFailure =
+                    `invalid-output: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        }
+        catch (error) {
+            lastFailure =
+                `unknown: ${error instanceof Error ? error.message : String(error)}`.slice(0, 2000);
+        }
+    }
+    throw new LedgerReconciliationError(`source fidelity reconciliation pi failed after ${queue.length} model(s): ${lastFailure || "no attempt produced valid output"}`);
+}
+/**
+ * 执行一次生产独立 review：模型队列串行尝试（默认真实 executePiStep），
+ * 输出经 validateOutput + zod 严格校验，全部失败抛 LedgerReviewError
+ * （稳定 SOURCE_FIDELITY_RECONCILIATION_FAILED，绝不回退默认 reviewer）。
+ */
+export async function runProductionLedgerReview(request, options) {
+    const parseAndValidate = (text) => validateReviewOutput(text, { fragmentId: request.fragment.id });
+    const queue = options.modelQueue ??
+        (await buildProductionModelQueue(options.repoRoot, options.listAvailableModels));
+    if (queue.length === 0) {
+        throw new LedgerReviewError("source fidelity review has no MED/HIGH/LOW or Pi-supported models to try (fail closed)");
+    }
+    const prompt = buildReviewPrompt(request);
+    const execute = options.executePi ?? executePiStep;
+    const timeoutMs = options.timeoutMs ?? SOURCE_FIDELITY_ATTEMPT_TIMEOUT_MS;
+    let lastFailure = "";
+    for (const modelRef of queue) {
+        try {
+            const result = await execute({
+                attachedFiles: [],
+                modelConfig: resolveDagPiModelConfig(modelRef),
+                prompt,
+                repoRoot: options.repoRoot,
+                step: "analyze",
+                toolNames: [...SOURCE_FIDELITY_PI_TOOL_NAMES],
+                timeoutMs,
+                stallTimeoutMs: timeoutMs,
+                userMessage: "Review the fragment disposition into the required JSON only.",
+                validateOutput: (text) => {
+                    try {
+                        parseAndValidate(text);
+                        return [];
+                    }
+                    catch (error) {
+                        return [error instanceof Error ? error.message : String(error)];
+                    }
+                },
+            });
+            if (!result.ok) {
+                lastFailure =
+                    `${result.failureCategory}: ${(result.stderr || result.assistantText).slice(0, 2000)}`;
+                continue;
+            }
+            try {
+                return parseAndValidate(result.assistantText);
+            }
+            catch (error) {
+                lastFailure =
+                    `invalid-output: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        }
+        catch (error) {
+            lastFailure =
+                `unknown: ${error instanceof Error ? error.message : String(error)}`.slice(0, 2000);
+        }
+    }
+    throw new LedgerReviewError(`source fidelity review pi failed after ${queue.length} model(s): ${lastFailure || "no attempt produced valid output"}`);
+}
+/**
+ * 生产适配器工厂：返回 prepare 可注入的 reconcile executor（budgetChars=4000）
+ * 与独立 reviewer 两个不同 Pi 调用面。
+ */
+export function createProductionSourceFidelityPi(options) {
+    const reconcileExecutor = (request) => runProductionLedgerReconciliation(request, options);
+    const reviewer = (request) => runProductionLedgerReview(request, options);
+    return {
+        reconcile: {
+            executor: reconcileExecutor,
+            budgetChars: LEDGER_RECONCILIATION_DEFAULT_BUDGET_CHARS,
+        },
+        reviewer,
+    };
+}
+/**
+ * 接线侧门（AC-PROD-005）：taskKind === 'frontend-implementation'（input.taskKind
+ * 优先，缺省回退 loadTaskConfig(repoRoot, taskId).taskKind）。ineligible 返回
+ * undefined 不接线；配合 prepare.ts 的 parseable requirement/acceptance 前置
+ * 双重保证非 eligible 路径零 source-fidelity Pi 调用。
+ */
+export async function resolveProductionSourceFidelityPi(input) {
+    let effectiveTaskKind = input.taskKind?.trim();
+    if (!effectiveTaskKind) {
+        try {
+            const config = await loadTaskConfig(input.repoRoot, input.taskId);
+            effectiveTaskKind = config.taskKind?.trim();
+        }
+        catch {
+            effectiveTaskKind = undefined;
+        }
+    }
+    if (effectiveTaskKind !== SOURCE_FIDELITY_TASK_KIND)
+        return undefined;
+    return createProductionSourceFidelityPi({ repoRoot: input.repoRoot });
+}

package/dist/task/source-prepare/types.js

@@ -5,3 +5,25 @@ export const PREPARE_DEFAULT_FORBIDDEN_PATHS = [
     ".harness/**",
     "node_modules/**",
 ];
+// ---------------------------------------------------------------------------
+// Source Fidelity Ledger (20260824-frontend-source-fidelity-ledger-v1)
+// ---------------------------------------------------------------------------
+// 原始 requirement/acceptance 文档保持语义权威；派生 source/需求.md 仅作导航视图。
+// ledger 是二者之间确定性、可审计的映射账本：完整性由可审计账本、来源绑定和
+// writer 前确定性门禁证明，摘要遗漏不再静默通过。
+/** 稳定机器可判读错误码（SOURCE_FIDELITY_* 类目），writer 前门禁/修复路由消费。 */
+export const SOURCE_FIDELITY_ERROR_CODES = [
+    "SOURCE_FIDELITY_LEDGER_MISSING",
+    "SOURCE_FIDELITY_LEDGER_STALE",
+    "SOURCE_FIDELITY_UNRESOLVED",
+    "SOURCE_FIDELITY_CONFLICT",
+    "SOURCE_FIDELITY_HIGH_RISK_UNCOVERED",
+    "SOURCE_FIDELITY_CONTEXT_ONLY_UNREVIEWED",
+    "SOURCE_FIDELITY_REQUIREMENT_NOT_COVERED",
+    "SOURCE_FIDELITY_SOURCE_REF_INVALID",
+    "SOURCE_FIDELITY_FRAGMENT_INVALID",
+    "SOURCE_FIDELITY_RECONCILIATION_FAILED",
+];
+export const LEDGER_SCHEMA_VERSION = 1;
+export const LEDGER_SCHEMA_RECONCILER_VERSION = "ledger-reconciler-v1";
+export const REQUIREMENT_LEDGER_FILE_NAME = "requirement-ledger.json";

package/dist/worker/cli.js

@@ -1,11 +1,8 @@
 #!/usr/bin/env node
 import { readFile } from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
-import { createNpmUpdateClient } from "../shared/update/npm-client.js";
-import { runConsoleDailyUpdateCheck } from "../shared/update/console-notifier.js";
 import { readPackageVersion } from "../shared/package-metadata.js";
 import YAML from "yaml";
 import { LoopAgentClient } from "./loop-agent/loop-agent-client.js";
@@ -844,37 +841,26 @@ function parseOptionalTimeoutMs(raw) {
 export async function runConsoleServe(options) {
     const { createConsoleServer } = await import("./console/server.js");
     const { maybeOpenConsoleBrowser } = await import("./console/open-browser.js");
+    const { readConsoleHandoff, waitForOldConsoleExit } = await import("./console/console-handoff.js");
     try {
-        try {
-            const packageRoot = path.dirname(path.dirname(path.dirname(fileURLToPath(import.meta.url))));
-            const currentVersion = readPackageVersion(packageRoot) ?? "0.0.0";
-            await runConsoleDailyUpdateCheck({
-                currentVersion,
-                packageRoot,
-                homeDir: os.homedir(),
-                cwd: options.repoRoot,
-                env: process.env,
-                stdinIsTTY: process.stdin.isTTY === true,
-                stderrIsTTY: process.stderr.isTTY === true,
-                client: createNpmUpdateClient({
-                    currentVersion,
-                    packageRoot,
-                    cwd: options.repoRoot,
-                    env: process.env,
-                }),
-            });
-        }
-        catch (error) {
-            const detail = error instanceof Error ? error.message : String(error);
-            process.stderr.write(`loop-agent 更新检查已跳过：${detail}\n`);
+        const handoff = readConsoleHandoff(process.env);
+        const appDataRoot = options.appDataRoot ?? handoff?.appDataRoot;
+        if (handoff) {
+            if (path.resolve(handoff.repoRoot) !== path.resolve(options.repoRoot) ||
+                handoff.host !== options.host ||
+                handoff.port !== options.port) {
+                throw new Error("console handoff does not match requested repo/host/port");
+            }
+            await waitForOldConsoleExit(handoff.oldPid);
         }
         const server = await createConsoleServer({
             repoRoot: options.repoRoot,
             host: options.host,
             port: options.port,
             debug: options.debug === true,
-            appDataRoot: options.appDataRoot,
+            appDataRoot,
             defaultTimeoutMs: parseOptionalTimeoutMs(options.defaultTimeoutMsRaw),
+            ...(handoff ? { consoleInstanceId: handoff.consoleInstanceId } : {}),
         });
         // Keep stdout bind URL contract (may include 0.0.0.0 / ::); browser URL is normalized separately.
         process.stdout.write(`${server.url}

package/dist/worker/console/console-handoff.js

@@ -0,0 +1,82 @@
+import { createHash, randomBytes } from "node:crypto";
+const HANDOFF_ENV = "LOOP_CONSOLE_HANDOFF_V1";
+const HANDOFF_HASH_ENV = "LOOP_CONSOLE_HANDOFF_SHA256";
+function canonicalJson(value) {
+    return JSON.stringify(value);
+}
+function digest(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}
+export function createConsoleHandoff(input) {
+    const handoff = {
+        schemaVersion: 1,
+        consoleInstanceId: `console_${randomBytes(16).toString("hex")}`,
+        ...input,
+    };
+    const encoded = canonicalJson(handoff);
+    return {
+        handoff,
+        env: {
+            [HANDOFF_ENV]: Buffer.from(encoded, "utf8").toString("base64url"),
+            [HANDOFF_HASH_ENV]: digest(encoded),
+        },
+    };
+}
+/** Parse an exact, hash-bound handoff contract inherited by the replacement process. */
+export function readConsoleHandoff(env) {
+    const encoded = env[HANDOFF_ENV];
+    const expectedDigest = env[HANDOFF_HASH_ENV];
+    if (!encoded && !expectedDigest)
+        return undefined;
+    if (!encoded || !expectedDigest)
+        throw new Error("console handoff contract is incomplete");
+    let raw;
+    try {
+        raw = Buffer.from(encoded, "base64url").toString("utf8");
+    }
+    catch {
+        throw new Error("console handoff payload is invalid");
+    }
+    if (digest(raw) !== expectedDigest)
+        throw new Error("console handoff hash mismatch");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("console handoff payload is not JSON");
+    }
+    const value = parsed;
+    if (value.schemaVersion !== 1 ||
+        !Number.isInteger(value.oldPid) ||
+        value.oldPid <= 0 ||
+        typeof value.repoRoot !== "string" ||
+        typeof value.host !== "string" ||
+        !Number.isInteger(value.port) ||
+        value.port < 0 ||
+        typeof value.targetVersion !== "string" ||
+        typeof value.consoleInstanceId !== "string") {
+        throw new Error("console handoff payload has invalid fields");
+    }
+    return value;
+}
+export async function waitForOldConsoleExit(oldPid, options = {}) {
+    const isAlive = options.isAlive ?? ((pid) => {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const timeoutMs = options.timeoutMs ?? 15_000;
+    const started = Date.now();
+    while (isAlive(oldPid)) {
+        if (Date.now() - started >= timeoutMs) {
+            throw new Error(`old Console PID ${oldPid} did not exit before handoff timeout`);
+        }
+        await sleep(50);
+    }
+}

package/dist/worker/console/console-update-and-init.js

@@ -0,0 +1,115 @@
+import semver from "semver";
+function notRunMaintenance(channel) {
+    return {
+        package: { status: "failed", channel },
+        initialization: { status: "not-run", pendingPaths: [] },
+        handoff: { status: "not-needed" },
+    };
+}
+function failed(code, message, maintenance = notRunMaintenance("latest")) {
+    return {
+        state: "failed",
+        maintenance,
+        errorCode: code,
+        errorMessage: message,
+    };
+}
+/**
+ * Deterministic core for the Console-only maintenance operation. It contains
+ * no HTTP, model, or process-global calls, which makes the safety ordering
+ * independently testable and keeps the caller responsible for privileged
+ * handoff mechanics.
+ */
+export async function performConsoleUpdateAndInit(deps, channel = "latest") {
+    const preflight = await deps.preflight();
+    if (!preflight.ok) {
+        return failed(preflight.code, preflight.message, notRunMaintenance(channel));
+    }
+    const target = await deps.resolveVersion(channel);
+    if (!target.ok) {
+        return failed("REGISTRY_UNAVAILABLE", `could not verify npm ${channel} (${target.reason})`, notRunMaintenance(channel));
+    }
+    if (!semver.valid(deps.currentVersion) || !semver.valid(target.version)) {
+        return failed("INVALID_VERSION", "installed or selected channel version is invalid", notRunMaintenance(channel));
+    }
+    if (channel === "latest" && semver.lt(target.version, deps.currentVersion)) {
+        return failed("REGISTRY_VERSION_REGRESSION", `npm latest ${target.version} is older than installed ${deps.currentVersion}`, notRunMaintenance(channel));
+    }
+    const release = await deps.acquireLock();
+    if (!release) {
+        return failed("UPDATE_LOCKED", "another loop-agent update is already in progress for this user", notRunMaintenance(channel));
+    }
+    try {
+        const packageChanged = target.version !== deps.currentVersion;
+        const maintenance = {
+            package: {
+                status: packageChanged ? "updated" : "current",
+                channel,
+                targetVersion: target.version,
+            },
+            initialization: { status: "not-run", pendingPaths: [] },
+            handoff: { status: "not-needed" },
+        };
+        if (packageChanged) {
+            const proof = await deps.canAutoInstall();
+            if (!proof.ok) {
+                maintenance.package = { status: "failed", channel, reason: proof.reason };
+                return failed("GLOBAL_INSTALL_UNPROVEN", proof.reason, maintenance);
+            }
+            const installed = await deps.installExact(target.version, channel);
+            if (!installed.ok) {
+                maintenance.package = { status: "failed", channel, reason: installed.reason };
+                return failed("INSTALL_FAILED", installed.reason, maintenance);
+            }
+            const verified = await deps.verifyInstalled(target.version);
+            if (!verified.ok) {
+                maintenance.package = { status: "failed", channel, reason: verified.reason };
+                return failed("INSTALL_VERIFICATION_FAILED", verified.reason, maintenance);
+            }
+        }
+        const initResult = await deps.applySafeInit();
+        maintenance.initialization = initResult.ok
+            ? { status: "clean", pendingPaths: initResult.pendingPaths }
+            : {
+                status: "needs-reconcile",
+                pendingPaths: initResult.pendingPaths,
+                message: initResult.message,
+            };
+        if (!packageChanged) {
+            return {
+                state: initResult.ok ? "succeeded" : "needs-reconcile",
+                maintenance,
+                ...(initResult.ok
+                    ? {}
+                    : {
+                        errorCode: "INIT_NEEDS_RECONCILE",
+                        errorMessage: initResult.message,
+                    }),
+            };
+        }
+        const handoff = await deps.requestHandoff({
+            targetVersion: target.version,
+            initResult,
+        });
+        if (!handoff.ok) {
+            maintenance.handoff = {
+                status: "needs-reconcile",
+                message: handoff.message,
+            };
+            return {
+                state: "needs-reconcile",
+                maintenance,
+                errorCode: "HANDOFF_FAILED",
+                errorMessage: handoff.message,
+            };
+        }
+        maintenance.handoff = {
+            status: "requested",
+            consoleInstanceId: handoff.consoleInstanceId,
+        };
+        return { state: "restarting", maintenance };
+    }
+    finally {
+        await release().catch(() => undefined);
+    }
+}