@tea-agent/loop-agent 0.16.26 → 0.17.1

package/dist/task/contract/validate-draft.js

@@ -0,0 +1,106 @@
+import path from "node:path";
+import { safeParseTaskContractDraft } from "./schema.js";
+import { getTaskContractPaths } from "./paths.js";
+import { readSourceManifest } from "../source-references.js";
+function isPathOutsideRepoHint(p) {
+    if (path.isAbsolute(p))
+        return true;
+    if (p.includes("\0"))
+        return true;
+    const normalized = p.replace(/\\/g, "/");
+    if (normalized.startsWith("../") || normalized.includes("/../"))
+        return true;
+    return false;
+}
+export async function validateTaskContractDraft(input) {
+    const errors = [];
+    const warnings = [];
+    const parsed = safeParseTaskContractDraft(input.draft);
+    if (!parsed.success) {
+        for (const issue of parsed.error.issues) {
+            errors.push({
+                code: issue.message.includes("schemaVersion") ||
+                    issue.path[0] === "schemaVersion"
+                    ? "UNSUPPORTED_SCHEMA_VERSION"
+                    : "INVALID_INPUT",
+                path: issue.path.join("."),
+                message: issue.message,
+            });
+        }
+        return {
+            taskId: input.taskId,
+            valid: false,
+            errors,
+            warnings,
+        };
+    }
+    const draft = parsed.data;
+    if (draft.taskId !== input.taskId) {
+        errors.push({
+            code: "INVALID_INPUT",
+            path: "taskId",
+            message: `draft.taskId (${draft.taskId}) does not match task (${input.taskId})`,
+        });
+    }
+    for (const p of draft.constraints.allowedPaths) {
+        if (isPathOutsideRepoHint(p) && !p.includes("*")) {
+            // globs may be relative; absolute is out of repo
+            if (path.isAbsolute(p)) {
+                errors.push({
+                    code: "PATH_OUTSIDE_REPO",
+                    path: "constraints.allowedPaths",
+                    message: `absolute path not allowed: ${p}`,
+                });
+            }
+        }
+    }
+    for (const p of draft.constraints.forbiddenPaths) {
+        if (path.isAbsolute(p)) {
+            errors.push({
+                code: "PATH_OUTSIDE_REPO",
+                path: "constraints.forbiddenPaths",
+                message: `absolute path not allowed: ${p}`,
+            });
+        }
+    }
+    if (draft.references && draft.references.length > 0) {
+        const paths = getTaskContractPaths(input.repoRoot, input.taskId);
+        const manifest = await readSourceManifest(paths.sourceDir);
+        if (!manifest) {
+            warnings.push({
+                code: "MISSING_SOURCE_MANIFEST",
+                message: "draft references present but source-manifest.json is missing; import-prd first for immutable evidence",
+            });
+        }
+        else {
+            for (const ref of draft.references) {
+                const normalized = ref.ref.replace(/\\/g, "/");
+                const hit = manifest.documents.some((doc) => {
+                    const mat = doc.materializedPath.replace(/\\/g, "/");
+                    return (mat === normalized ||
+                        `source/${mat}` === normalized ||
+                        normalized.endsWith(mat));
+                });
+                if (!hit) {
+                    warnings.push({
+                        code: "REFERENCE_NOT_IN_MANIFEST",
+                        message: `reference not found in source-manifest: ${ref.ref}`,
+                    });
+                }
+            }
+        }
+    }
+    if (draft.sourceResolutions &&
+        draft.sourceResolutions.some((r) => r.decidedBy !== "human")) {
+        warnings.push({
+            code: "NON_HUMAN_SOURCE_RESOLUTION",
+            message: "one or more sourceResolutions are not decidedBy=human; blocking conflicts require human resolution before apply",
+        });
+    }
+    return {
+        taskId: input.taskId,
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}

package/dist/task/index.js

@@ -7,3 +7,6 @@ export * from "./subagent-guidance.js";
 export * from "./runtime.js";
 export * from "./config.js";
 export * from "./worktree.js";
+export * as taskContract from "./contract/index.js";
+export * as taskOperator from "./operator/index.js";
+export * from "./contract/index.js";

package/dist/task/operator/capabilities.js

@@ -0,0 +1,6 @@
+/**
+ * Compatibility re-export — canonical capabilities document lives in
+ * src/shared/operator (includes Console negotiation `dag` block).
+ * No independent projection / dual implementation.
+ */
+export { buildOperatorCapabilitiesDocument, } from "../../shared/operator/capabilities.js";

package/dist/task/operator/envelope.js

@@ -0,0 +1,2 @@
+/** Compatibility re-export — canonical envelope lives in src/shared/operator. */
+export { buildOperatorResult, operatorSucceeded, operatorFailed, writeOperatorJson, processExitCodeForOutcome, } from "../../shared/operator/envelope.js";

package/dist/task/operator/index.js

@@ -0,0 +1,5 @@
+/** Compatibility barrel — re-exports src/shared/operator for task-adjacent imports. */
+export * from "./types.js";
+export * from "./envelope.js";
+export * from "./registry.js";
+export * from "./capabilities.js";

package/dist/task/operator/registry.js

@@ -0,0 +1,2 @@
+/** Compatibility re-export — canonical registry lives in src/shared/operator. */
+export { OPERATOR_OUTCOMES_V1, OPERATOR_ERROR_CODES_V1, OPERATOR_ERROR_CODE_SET, isOperatorErrorCode, } from "../../shared/operator/registry.js";

package/dist/task/operator/types.js

@@ -0,0 +1 @@
+export {};

package/dist/task/runtime.js

@@ -64,6 +64,10 @@ export function getTaskPaths(repoRoot, taskId) {
         logsDir: path.join(taskDir, 'logs'),
         sourceDir: path.join(taskDir, 'source'),
         statePath: path.join(taskDir, '.workflow_state.json'),
+        /** Managed TaskContractRefV1 metadata (Phase 0.5). */
+        contractPath: path.join(taskDir, 'contract.json'),
+        /** Journaled contract transactions directory. */
+        transactionsDir: path.join(taskDir, '.transactions'),
     };
 }
 export async function createTask(repoRoot, taskId, title) {
@@ -180,7 +184,7 @@ export function parseTaskConfigForRuntime(rawConfig) {
     const parsed = taskConfigSchema.parse(rawConfig);
     if (typeof rawConfig === 'object' &&
         rawConfig !== null &&
-        !Object.prototype.hasOwnProperty.call(rawConfig, 'maxFixLoops')) {
+        !Object.hasOwn(rawConfig, 'maxFixLoops')) {
         return {
             ...parsed,
             maxFixLoops: deriveMaxFixLoops(parsed.complexity),

package/dist/task/source-references.js

@@ -174,6 +174,13 @@ export async function importPrdDocument(input) {
             referenceDocs,
         });
     }
+    // Managed contracts must bump revision after import-prd mutates manifest/task config.
+    // Lazy import avoids circular init with contract/observe.
+    const { refreshManagedContractAfterImport } = await import("./contract/import-revision.js");
+    await refreshManagedContractAfterImport({
+        repoRoot: input.repoRoot,
+        taskId: input.taskId,
+    });
     return {
         taskId: input.taskId,
         sourcePath: sourcePathForRecord,

package/dist/worker/cli.js

@@ -14,10 +14,10 @@ import { createCompositeProgressReporter } from "./observability/progress-compos
 import { createRoutedWorkerEventStore } from "./observability/event-store.js";
 import { buildGlobalSnapshot } from "./observability/read-model.js";
 import { createObserveServer } from "./observe/server.js";
-import { diagnoseTaskPoolStates, formatDoctorHuman, loadOperatorMapping } from "./pool/doctor.js";
+import { diagnoseTaskPoolStates, formatDoctorHuman, loadOperatorMapping, } from "./pool/doctor.js";
 import { migrateTaskPoolStates } from "./pool/migrate-state.js";
-import { markTaskPoolFailed, reconcileTaskPoolAbandon } from "./pool/reconcile.js";
-import { getTaskPoolRoot, prepareTaskPoolRetry, readFeatureTaskPoolStates } from "./pool/run-store.js";
+import { markTaskPoolFailed, reconcileTaskPoolAbandon, } from "./pool/reconcile.js";
+import { getTaskPoolRoot, prepareTaskPoolRetry, readFeatureTaskPoolStates, } from "./pool/run-store.js";
 import { TaskPoolStateError } from "./pool/types.js";
 import { taskSpecSchema } from "./task-spec/schema.js";
 import { validateTaskSpec } from "./task-spec/validate.js";
@@ -29,7 +29,7 @@ import { renderFeatureRun, runFeature } from "./feature/run.js";
 import { draftFollowUpDecision } from "./follow-up/factory.js";
 import { approveFollowUp } from "./follow-up/approve.js";
 import { prepareFeatureDelivery } from "./delivery/package.js";
-import { previewFeatureCloseout, renderCloseoutPreview } from "./closeout/preview.js";
+import { previewFeatureCloseout, renderCloseoutPreview, } from "./closeout/preview.js";
 import { applyFeatureCloseout } from "./closeout/apply.js";
 import { projectMonthlyMetrics } from "./metrics/projector.js";
 import { runFeatureFinalVerification } from "./delivery/final-verification.js";
@@ -43,11 +43,24 @@ export function buildAgentWorkerProgram() {
         .showHelpAfterError()
         .showSuggestionAfterError();
     const task = program.command("task").description("TaskSpec utilities");
-    const batch = program.command("batch").description("Task Pool batch utilities");
-    const report = program.command("report").description("Task Pool reporting utilities");
-    const observe = program.command("observe").description("Observe UI server and snapshot utilities");
-    const feature = program.command("feature").description("Feature-level review and delivery workflow");
-    const pool = program.command("pool").description("Task Pool state doctor and migration utilities");
+    const batch = program
+        .command("batch")
+        .description("Task Pool batch utilities");
+    const report = program
+        .command("report")
+        .description("Task Pool reporting utilities");
+    const observe = program
+        .command("observe")
+        .description("Observe UI server and snapshot utilities");
+    const consoleCmd = program
+        .command("console")
+        .description("Loop Operator Console (local)");
+    const feature = program
+        .command("feature")
+        .description("Feature-level review and delivery workflow");
+    const pool = program
+        .command("pool")
+        .description("Task Pool state doctor and migration utilities");
     pool
         .command("mark-failed")
         .requiredOption("--repo <repo-root>", "Target repo root")
@@ -81,7 +94,9 @@ export function buildAgentWorkerProgram() {
         const repoRoot = path.resolve(options.repo);
         const mapping = await loadOperatorMapping(options.mapping);
         const report = await diagnoseTaskPoolStates(repoRoot, { mapping });
-        process.stdout.write(options.json ? `${JSON.stringify(report, null, 2)}\n` : formatDoctorHuman(report));
+        process.stdout.write(options.json
+            ? `${JSON.stringify(report, null, 2)}\n`
+            : formatDoctorHuman(report));
     });
     pool
         .command("migrate-state")
@@ -108,7 +123,9 @@ export function buildAgentWorkerProgram() {
         }
         catch (error) {
             const detail = error instanceof Error ? error.message : String(error);
-            const code = error instanceof TaskPoolStateError ? error.code : "task-pool-migrate-failed";
+            const code = error instanceof TaskPoolStateError
+                ? error.code
+                : "task-pool-migrate-failed";
             if (options.json) {
                 process.stdout.write(`${JSON.stringify({
                     schemaVersion: 1,
@@ -155,7 +172,9 @@ export function buildAgentWorkerProgram() {
             featureDir: path.resolve(options.featureDir),
             repoRoot: path.resolve(options.repo),
         });
-        process.stdout.write(options.json ? `${JSON.stringify(result, null, 2)}\n` : renderFeatureReview(result));
+        process.stdout.write(options.json
+            ? `${JSON.stringify(result, null, 2)}\n`
+            : renderFeatureReview(result));
     });
     feature
         .command("run")
@@ -197,7 +216,9 @@ export function buildAgentWorkerProgram() {
             });
         }
         catch {
-            progress = createProgressReporter({ quiet: options.quiet ?? options.dryRun ?? false });
+            progress = createProgressReporter({
+                quiet: options.quiet ?? options.dryRun ?? false,
+            });
         }
         const result = await runFeature({
             featureDir: path.resolve(options.featureDir),
@@ -207,7 +228,9 @@ export function buildAgentWorkerProgram() {
             limit: Number.parseInt(options.limit, 10),
             batchRunId,
             runCheckRepo: options.checkRepo ?? false,
-            ...(options.checkRepoCommand ? { checkRepoCommand: options.checkRepoCommand } : {}),
+            ...(options.checkRepoCommand
+                ? { checkRepoCommand: options.checkRepoCommand }
+                : {}),
             progress,
             ...(options.piModel ? { piModel: options.piModel } : {}),
             gitMode: options.gitMode === "checkpoint" ? "checkpoint" : "none",
@@ -215,7 +238,9 @@ export function buildAgentWorkerProgram() {
             controllerIdentity: client.getIdentity(),
             controllerExpectation: expectedIdentity,
         });
-        process.stdout.write(options.json ? `${JSON.stringify(result, null, 2)}\n` : renderFeatureRun(result));
+        process.stdout.write(options.json
+            ? `${JSON.stringify(result, null, 2)}\n`
+            : renderFeatureRun(result));
         if (result.status === "failed" || result.status === "needs-action")
             process.exitCode = 1;
     });
@@ -231,12 +256,28 @@ export function buildAgentWorkerProgram() {
         .option("--expected-controller-fingerprint <value>", "Exact expected controller fingerprint sha256:<hex> (fail before writes if mismatched)")
         .description("Run an independent HEAD-bound final QA verification and project Delivery evidence")
         .action(async (options) => {
-        if (options.evidenceMode !== "auto" && options.evidenceMode !== "qa-execute" && options.evidenceMode !== "typed")
+        if (options.evidenceMode !== "auto" &&
+            options.evidenceMode !== "qa-execute" &&
+            options.evidenceMode !== "typed")
             throw new Error("feature verify-final --evidence-mode must be auto, qa-execute, or typed");
         const repoRoot = path.resolve(options.repo);
-        const client = new LoopAgentClient({ loopAgentBin: options.loopAgentBin, artifactRoot: path.join(getTaskPoolRoot(repoRoot), "artifacts", `final-verification-${Date.now()}`), resolveIdentity: true });
-        const result = await runFeatureFinalVerification({ featureDir: path.resolve(options.featureDir), repoRoot, taskId: options.taskId, client, controllerIdentity: client.getIdentity(), controllerExpectation: buildIdentityExpectation(options), evidenceMode: options.evidenceMode });
-        process.stdout.write(options.json ? `${JSON.stringify(result, null, 2)}\n` : `Feature: ${result.featureId}\nFinal verification: ${result.workerRunId}\nEvidence mode: ${result.evidenceMode ?? "qa-execute"}\nQA evidence: ${result.qaEvidencePath}\nFinal evidence: ${result.finalVerificationPath}${result.bundleEvidencePath ? `\nVerification bundle: ${result.bundleEvidencePath}` : ""}\n`);
+        const client = new LoopAgentClient({
+            loopAgentBin: options.loopAgentBin,
+            artifactRoot: path.join(getTaskPoolRoot(repoRoot), "artifacts", `final-verification-${Date.now()}`),
+            resolveIdentity: true,
+        });
+        const result = await runFeatureFinalVerification({
+            featureDir: path.resolve(options.featureDir),
+            repoRoot,
+            taskId: options.taskId,
+            client,
+            controllerIdentity: client.getIdentity(),
+            controllerExpectation: buildIdentityExpectation(options),
+            evidenceMode: options.evidenceMode,
+        });
+        process.stdout.write(options.json
+            ? `${JSON.stringify(result, null, 2)}\n`
+            : `Feature: ${result.featureId}\nFinal verification: ${result.workerRunId}\nEvidence mode: ${result.evidenceMode ?? "qa-execute"}\nQA evidence: ${result.qaEvidencePath}\nFinal evidence: ${result.finalVerificationPath}${result.bundleEvidencePath ? `\nVerification bundle: ${result.bundleEvidencePath}` : ""}\n`);
     });
     feature
         .command("delivery")
@@ -250,11 +291,16 @@ export function buildAgentWorkerProgram() {
         .description("Validate checkpointed Feature evidence and prepare a local Delivery Package")
         .action(async (options) => {
         const result = await prepareFeatureDelivery({
-            featureDir: path.resolve(options.featureDir), repoRoot: path.resolve(options.repo),
-            qaEvidencePath: options.qaEvidence, finalVerificationPath: options.finalVerification,
-            ...(options.waivers ? { waiverPath: options.waivers } : {}), dryRun: options.dryRun ?? false,
+            featureDir: path.resolve(options.featureDir),
+            repoRoot: path.resolve(options.repo),
+            qaEvidencePath: options.qaEvidence,
+            finalVerificationPath: options.finalVerification,
+            ...(options.waivers ? { waiverPath: options.waivers } : {}),
+            dryRun: options.dryRun ?? false,
         });
-        process.stdout.write(options.json ? `${JSON.stringify(result, null, 2)}\n` : `Feature: ${result.featureId}\nDelivery: ${result.status}\nArtifacts: ${Object.values(result.artifacts).join(", ")}\nBlockers: ${result.blockers.join("; ") || "none"}\n`);
+        process.stdout.write(options.json
+            ? `${JSON.stringify(result, null, 2)}\n`
+            : `Feature: ${result.featureId}\nDelivery: ${result.status}\nArtifacts: ${Object.values(result.artifacts).join(", ")}\nBlockers: ${result.blockers.join("; ") || "none"}\n`);
         if (result.status === "blocked")
             process.exitCode = 1;
     });
@@ -268,12 +314,21 @@ export function buildAgentWorkerProgram() {
         .description("Preview Feature Closeout gates without modifying the Feature Packet")
         .action(async (options) => {
         if (options.apply) {
-            const result = await applyFeatureCloseout({ featureDir: path.resolve(options.featureDir), repoRoot: path.resolve(options.repo), owner: options.owner ?? "" });
+            const result = await applyFeatureCloseout({
+                featureDir: path.resolve(options.featureDir),
+                repoRoot: path.resolve(options.repo),
+                owner: options.owner ?? "",
+            });
             process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
             return;
         }
-        const result = await previewFeatureCloseout({ featureDir: path.resolve(options.featureDir), repoRoot: path.resolve(options.repo) });
-        process.stdout.write(options.json ? `${JSON.stringify(result, null, 2)}\n` : renderCloseoutPreview(result));
+        const result = await previewFeatureCloseout({
+            featureDir: path.resolve(options.featureDir),
+            repoRoot: path.resolve(options.repo),
+        });
+        process.stdout.write(options.json
+            ? `${JSON.stringify(result, null, 2)}\n`
+            : renderCloseoutPreview(result));
         if (result.status === "blocked")
             process.exitCode = 1;
     });
@@ -482,7 +537,9 @@ export function buildAgentWorkerProgram() {
         const result = await runReadyTasks({
             repoRoot,
             featureDir: path.resolve(options.featureDir),
-            ...(options.limit ? { limit: Number.parseInt(options.limit, 10) } : {}),
+            ...(options.limit
+                ? { limit: Number.parseInt(options.limit, 10) }
+                : {}),
             batchRunId,
             client,
             runCheckRepo: options.checkRepo ?? false,
@@ -527,9 +584,62 @@ export function buildAgentWorkerProgram() {
         .option("--json", "Emit JSON (default)")
         .description("Print GlobalSnapshot JSON to stdout")
         .action(async (options) => {
-        const snapshot = await buildGlobalSnapshot({ repoRoot: path.resolve(options.repo) });
+        const snapshot = await buildGlobalSnapshot({
+            repoRoot: path.resolve(options.repo),
+        });
         process.stdout.write(`${JSON.stringify(snapshot)}\n`);
     });
+    consoleCmd
+        .command("serve")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--port <port>", "HTTP port", "8790")
+        .option("--host <host>", "Bind host (default 127.0.0.1; non-loopback is rejected)", "127.0.0.1")
+        .option("--app-data <path>", "Override Console application-data root (Draft/Operation/confirmation)")
+        .description("Start Loop Operator Console HTTP server (static SPA + Operator API)")
+        .action(async (options) => {
+        const { createConsoleServer } = await import("./console/server.js");
+        const { isLoopbackHost } = await import("./console/loopback.js");
+        if (!isLoopbackHost(options.host)) {
+            process.stderr.write(`console serve: non-loopback host "${options.host}" is not allowed (fail closed)\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const repoRoot = path.resolve(options.repo);
+        const server = await createConsoleServer({
+            repoRoot,
+            host: options.host,
+            port: Number.parseInt(options.port, 10),
+            appDataRoot: options.appData
+                ? path.resolve(options.appData)
+                : undefined,
+        });
+        process.stdout.write(`${server.url}\n`);
+        await new Promise((resolve) => {
+            const shutdown = () => resolve();
+            process.once("SIGINT", shutdown);
+            process.once("SIGTERM", shutdown);
+        });
+        await server.close();
+    });
+    consoleCmd
+        .command("doctor")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--json", "Emit JSON report on stdout")
+        .option("--observe-url <url>", "Optional Observe base URL to probe (non-blocking)", "http://127.0.0.1:8787")
+        .description("Report sibling loop-agent identity, repo preflight, and optional Observe health")
+        .action(async (options) => {
+        const { formatConsoleDoctorHuman, runConsoleDoctor } = await import("./console/doctor.js");
+        const report = await runConsoleDoctor({
+            repoRoot: path.resolve(options.repo),
+            observeBaseUrl: options.observeUrl,
+        });
+        if (options.json) {
+            process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        }
+        else {
+            process.stdout.write(formatConsoleDoctorHuman(report));
+        }
+    });
     report
         .command("morning")
         .requiredOption("--repo <repo-root>", "Target repo root")
@@ -554,13 +664,19 @@ export function buildAgentWorkerProgram() {
         .option("--json", "Emit the metrics JSON on stdout")
         .description("Project monthly Feature delivery metrics to JSON and Markdown")
         .action(async (options) => {
-        const result = await projectMonthlyMetrics({ repoRoot: path.resolve(options.repo), month: options.month });
-        process.stdout.write(options.json ? `${JSON.stringify(result.metrics, null, 2)}\n` : `${JSON.stringify({ ok: true, jsonPath: result.jsonPath, markdownPath: result.markdownPath }, null, 2)}\n`);
+        const result = await projectMonthlyMetrics({
+            repoRoot: path.resolve(options.repo),
+            month: options.month,
+        });
+        process.stdout.write(options.json
+            ? `${JSON.stringify(result.metrics, null, 2)}\n`
+            : `${JSON.stringify({ ok: true, jsonPath: result.jsonPath, markdownPath: result.markdownPath }, null, 2)}\n`);
     });
     return program;
 }
 export function buildIdentityExpectation(options) {
-    if (options.expectedControllerVersion || options.expectedControllerFingerprint) {
+    if (options.expectedControllerVersion ||
+        options.expectedControllerFingerprint) {
         const expectation = {};
         if (options.expectedControllerVersion)
             expectation.expectedVersion = options.expectedControllerVersion;
@@ -599,7 +715,9 @@ function handleFollowUpCliError(error, json, action) {
         status: "failed",
         action,
         error: { code, message: detail },
-        nextAction: action === "draft-followup" ? "Inspect the failed Worker run and failure category." : "Regenerate and review the Follow-up draft before approving.",
+        nextAction: action === "draft-followup"
+            ? "Inspect the failed Worker run and failure category."
+            : "Regenerate and review the Follow-up draft before approving.",
     }, null, 2)}\n`);
     process.exitCode = 1;
 }

package/dist/worker/console/app-data.js

@@ -0,0 +1,185 @@
+import { createHash, randomBytes } from "node:crypto";
+import { chmodSync, existsSync, lstatSync, mkdirSync, renameSync, writeFileSync, } from "node:fs";
+import { readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { repoFingerprintV1 } from "./repo-fingerprint.js";
+const APP_DATA_PRODUCT = "loop-console";
+export const MAX_STAGED_BYTES = 10 * 1024 * 1024;
+/**
+ * Resolve OS application-data root for Console (overrideable for tests).
+ * Never under a target repo `.harness` tree.
+ */
+export function defaultConsoleAppDataRoot(env = process.env) {
+    if (env.LOOP_CONSOLE_APP_DATA && env.LOOP_CONSOLE_APP_DATA.trim()) {
+        return path.resolve(env.LOOP_CONSOLE_APP_DATA.trim());
+    }
+    if (process.platform === "win32") {
+        const base = env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
+        return path.join(base, APP_DATA_PRODUCT);
+    }
+    if (process.platform === "darwin") {
+        return path.join(os.homedir(), "Library", "Application Support", APP_DATA_PRODUCT);
+    }
+    const xdg = env.XDG_DATA_HOME || path.join(os.homedir(), ".local", "share");
+    return path.join(xdg, APP_DATA_PRODUCT);
+}
+export function openConsoleAppData(options) {
+    const fingerprint = repoFingerprintV1(options.repoRoot);
+    const root = path.resolve(options.appDataRoot ?? defaultConsoleAppDataRoot());
+    const repoNamespace = path.join(root, "repos", fingerprint);
+    assertNotUnderRepoHarness(options.repoRoot, repoNamespace);
+    const paths = {
+        root,
+        repoRoot: path.resolve(options.repoRoot),
+        fingerprint,
+        drafts: path.join(repoNamespace, "drafts"),
+        operations: path.join(repoNamespace, "operations"),
+        confirmations: path.join(repoNamespace, "confirmations"),
+        staged: path.join(repoNamespace, "staged"),
+        assessments: path.join(repoNamespace, "assessments"),
+        interviews: path.join(repoNamespace, "interviews"),
+    };
+    for (const dir of [
+        paths.drafts,
+        paths.operations,
+        paths.confirmations,
+        paths.staged,
+        paths.assessments,
+        paths.interviews,
+    ]) {
+        ensureSecureDir(dir);
+    }
+    return paths;
+}
+function assertNotUnderRepoHarness(repoRoot, candidate) {
+    const repo = path.resolve(repoRoot);
+    const harness = path.join(repo, ".harness");
+    const resolvedCandidate = path.resolve(candidate);
+    const harnessPrefix = harness.endsWith(path.sep)
+        ? harness
+        : harness + path.sep;
+    if (resolvedCandidate === harness ||
+        resolvedCandidate.startsWith(harnessPrefix) ||
+        resolvedCandidate.startsWith(path.join(repo, ".harness"))) {
+        throw new Error(`console app-data must not live under repo .harness: ${resolvedCandidate}`);
+    }
+}
+export function ensureSecureDir(dir) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    try {
+        chmodSync(dir, 0o700);
+    }
+    catch {
+        // Windows may ignore mode; best-effort.
+    }
+}
+export function assertSafeAppDataPath(baseDir, candidate) {
+    const resolvedBase = path.resolve(baseDir);
+    const resolved = path.resolve(candidate);
+    const prefix = resolvedBase.endsWith(path.sep)
+        ? resolvedBase
+        : resolvedBase + path.sep;
+    if (resolved !== resolvedBase && !resolved.startsWith(prefix)) {
+        throw new Error(`path escapes app-data namespace: ${candidate}`);
+    }
+    if (existsSync(resolved)) {
+        const st = lstatSync(resolved);
+        if (st.isSymbolicLink()) {
+            throw new Error(`symlink rejected in app-data: ${candidate}`);
+        }
+        if (st.nlink > 1 && st.isFile()) {
+            throw new Error(`hardlink rejected in app-data: ${candidate}`);
+        }
+    }
+    return resolved;
+}
+export async function writeSecureJson(filePath, value) {
+    const dir = path.dirname(filePath);
+    ensureSecureDir(dir);
+    const resolved = assertSafeAppDataPath(dir, filePath);
+    const tmp = `${resolved}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    const body = `${JSON.stringify(value, null, 2)}\n`;
+    await writeFile(tmp, body, { encoding: "utf8", mode: 0o600 });
+    try {
+        chmodSync(tmp, 0o600);
+    }
+    catch {
+        // best-effort
+    }
+    await rename(tmp, resolved);
+    try {
+        chmodSync(resolved, 0o600);
+    }
+    catch {
+        // best-effort
+    }
+}
+export async function readJsonIfExists(filePath) {
+    if (!existsSync(filePath))
+        return undefined;
+    const st = lstatSync(filePath);
+    if (st.isSymbolicLink() || !st.isFile()) {
+        throw new Error(`refusing to read non-regular file: ${filePath}`);
+    }
+    const raw = await readFile(filePath, "utf8");
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`invalid JSON in app-data file ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function listJsonFiles(dir) {
+    if (!existsSync(dir))
+        return [];
+    const names = await readdir(dir);
+    return names
+        .filter((n) => n.endsWith(".json") && !n.endsWith(".tmp"))
+        .map((n) => path.join(dir, n));
+}
+export function sha256Utf8(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+export function sha256Json(value) {
+    return sha256Utf8(JSON.stringify(value));
+}
+/**
+ * Stage UTF-8 text under app-data staged/ with random name (≤10MiB).
+ * Returns absolute path; rejects path traversal / symlink semantics.
+ */
+export async function stageUtf8Text(appData, text, options) {
+    const bytes = Buffer.byteLength(text, "utf8");
+    if (bytes > MAX_STAGED_BYTES) {
+        throw new Error(`staged input exceeds ${MAX_STAGED_BYTES} bytes (got ${bytes})`);
+    }
+    const ext = options?.extension ?? ".txt";
+    const name = `${randomBytes(16).toString("hex")}${ext.startsWith(".") ? ext : `.${ext}`}`;
+    const target = assertSafeAppDataPath(appData.staged, path.join(appData.staged, name));
+    ensureSecureDir(appData.staged);
+    await writeFile(target, text, { encoding: "utf8", mode: 0o600 });
+    try {
+        chmodSync(target, 0o600);
+    }
+    catch {
+        // best-effort
+    }
+    return { path: target, sha256: sha256Utf8(text), bytes };
+}
+export async function removeStaged(filePath) {
+    if (!existsSync(filePath))
+        return;
+    await rm(filePath, { force: true });
+}
+/** Synchronous helpers used by boot-time path checks. */
+export function writeSecureJsonSync(filePath, value) {
+    const dir = path.dirname(filePath);
+    ensureSecureDir(dir);
+    const resolved = assertSafeAppDataPath(dir, filePath);
+    const tmp = `${resolved}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    renameSync(tmp, resolved);
+}