@tea-agent/loop-agent 0.44.0-next.13 → 0.44.0-next.14

package/dist/commands/operator-guide.js

@@ -0,0 +1,99 @@
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { checkInitUpdate } from "./init.js";
+import { loadNormalizedProjectConfig } from "../governance/project-config.js";
+import { CONTROLLER_RESOURCE_IDS, createControllerContextProvider, } from "../governance/resource-catalog.js";
+import { LOOP_AGENT_PACKAGE_NAME, readPackageVersion } from "../shared/package-metadata.js";
+async function exists(file) {
+    try {
+        await access(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function buildOperatorGuideDocument(repoRootInput) {
+    const repoRoot = path.resolve(repoRootInput);
+    const provider = await createControllerContextProvider();
+    const packageRoot = path.dirname(provider.list().length > 0
+        ? (await provider.readText(CONTROLLER_RESOURCE_IDS.loopAgentBridgeSkill)).absolutePath
+        : repoRoot);
+    const version = readPackageVersion(path.resolve(packageRoot, "..", "..", "..")) ?? "unknown";
+    let reproducibility = "unavailable";
+    try {
+        reproducibility = (await loadNormalizedProjectConfig(repoRoot)).verification.reproducibility;
+    }
+    catch {
+        // An uninitialized or malformed project is classified below by init assessment.
+    }
+    let status = "uninitialized";
+    let bridge = "missing";
+    let next = {
+        command: "loop-agent init --repo-root .",
+        reason: "initialize the minimal project surface",
+    };
+    if (await exists(path.join(repoRoot, "harness.json"))) {
+        const report = await checkInitUpdate({ repoRoot });
+        const bridgeDecision = report.humanDecisions.find((item) => item.reason.includes("bridge-path-conflict"));
+        bridge = bridgeDecision
+            ? "conflict"
+            : await exists(path.join(repoRoot, ".agents", "skills", "loop-agent", "SKILL.md"))
+                ? "ready"
+                : "missing";
+        if (report.humanDecisions.length > 0 || report.modelMergeTasks.length > 0) {
+            status = "blocked";
+            next = {
+                command: "loop-agent init upgrade --repo-root . --json",
+                reason: "complete the bounded migration decisions before starting new work",
+            };
+        }
+        else if (report.deterministicActions.length > 0) {
+            status = "needs-update";
+            next = {
+                command: "loop-agent init update --repo-root . --apply-safe --json",
+                reason: "apply the deterministic minimal-surface update",
+            };
+        }
+        else {
+            status = "ready";
+            next = {
+                command: "loop-agent task advance <task-id> --profile auto --json",
+                reason: "prepare or continue a governed task",
+            };
+        }
+    }
+    return {
+        schemaVersion: 1,
+        kind: "loop-agent-operator-guide",
+        controller: {
+            packageName: LOOP_AGENT_PACKAGE_NAME,
+            version,
+            resourceCatalogSha256: provider.identity.catalogDigest,
+        },
+        project: { repoRoot, status, configReproducibility: reproducibility, bridge },
+        dag: {
+            entry: "loop-agent task advance",
+            longRunningOwner: "console-operation-required",
+            builtinSkillSource: "builtin",
+        },
+        next,
+    };
+}
+export function renderOperatorGuideMarkdown(document) {
+    return [
+        "# loop-agent operator guide",
+        "",
+        `- Controller: \`${document.controller.packageName}@${document.controller.version}\``,
+        `- Project: \`${document.project.status}\``,
+        `- Bridge: \`${document.project.bridge}\``,
+        `- Verification: \`${document.project.configReproducibility}\``,
+        "",
+        "## Next",
+        "",
+        `\`${document.next.command}\``,
+        "",
+        document.next.reason,
+        "",
+    ].join("\n");
+}

package/dist/commands/operator.js

@@ -1,4 +1,5 @@
 import { buildOperatorCapabilitiesDocument, operatorFailed, operatorSucceeded, processExitCodeForOutcome, writeOperatorJson, } from "../shared/operator/index.js";
+import { buildOperatorGuideDocument, renderOperatorGuideMarkdown, } from "./operator-guide.js";
 export function parseOperatorArgs(args) {
     const options = {};
     const positional = [];
@@ -7,19 +8,31 @@ export function parseOperatorArgs(args) {
             options.json = true;
             continue;
         }
+        if (token === "--markdown") {
+            options.markdown = true;
+            continue;
+        }
         if (token.startsWith("-")) {
-            throw new Error(`unknown flag ${token}\nusage: operator capabilities --json`);
+            throw new Error(`unknown flag ${token}\nusage: operator <capabilities|guide> [--json|--markdown]`);
         }
         positional.push(token);
     }
     const subcommand = positional[0];
     if (!subcommand) {
-        throw new Error("usage: operator <capabilities> --json");
+        throw new Error("usage: operator <capabilities|guide> [--json|--markdown]");
     }
     return { subcommand, options };
 }
-export async function runOperator(_repoRoot, args) {
+export async function runOperator(repoRoot, args) {
     const { subcommand, options } = parseOperatorArgs(args);
+    if (subcommand === "guide") {
+        const guide = await buildOperatorGuideDocument(repoRoot);
+        if (options.markdown)
+            console.log(renderOperatorGuideMarkdown(guide));
+        else
+            emit(operatorSucceeded("operator guide", guide), true);
+        return;
+    }
     if (subcommand !== "capabilities") {
         const result = operatorFailed({
             command: "operator",

package/dist/executors/pi-sdk-executor.js

@@ -8,7 +8,7 @@ import { computeExtensionToolAllowlistExtras } from "./pi-extension-resolver.js"
 import { BoundedTextPreview, classifyPiFailure, createPiJsonlStreamCollector, DEFAULT_ABORT_GRACE_MS, DEFAULT_STALL_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, extractPiEventStopReason, extractAssistantTextFromPiJson, } from "./pi-executor.js";
 import { serializeSessionEvent } from "./pi-event-serializer.js";
 import { PI_RECOMMENDED_COMPACTION, PI_RECOMMENDED_RETRY, } from "../shared/pi-retry-settings.js";
-import { createCompactionController, createContextPressureExtension, createSiftBridgeState, inMemoryCompactionSettings, isDagSiftEnabled, parseCompactionPolicy, parseSiftBridgeConfig, SIFT_RETRIEVE_TOOL_NAME, } from "../shared/pi-context-pressure/index.js";
+import { createCompactionController, createContextPressureExtension, createSiftBridgeState, inMemoryCompactionSettings, isDagSiftEnabled, parseCompactionPolicy, parsePiToolResultPruneConfig, parseSiftBridgeConfig, SIFT_RETRIEVE_TOOL_NAME, } from "../shared/pi-context-pressure/index.js";
 import { DAG_TELEMETRY_SESSION_ID_ENV, injectWizardLocalTelemetryHeaders, isTelemetrySessionId, } from "../shared/wizard-local-telemetry.js";
 /** Maximum number of same-session continuations after provider output truncation. */
 export const PI_SDK_OUTPUT_LIMIT_CONTINUE_MAX = 3;
@@ -292,6 +292,7 @@ async function createSdkSession(sdk, input, shared) {
     // Prefer SettingsManager.inMemory so harness runs do not depend on ~/.pi or
     // project .pi/settings.json being present/trusted.
     const policy = parseCompactionPolicy();
+    const pruneSettings = parsePiToolResultPruneConfig();
     const compaction = {
         ...PI_RECOMMENDED_COMPACTION,
         ...inMemoryCompactionSettings(policy),
@@ -321,6 +322,7 @@ async function createSdkSession(sdk, input, shared) {
         policy,
         controller,
         sift,
+        ...(pruneSettings.enabled && policy.mode !== "off" ? { prune: pruneSettings.config } : {}),
     });
     const telemetryExtension = createDagWizardLocalTelemetryHeadersExtension(input.telemetrySessionId);
     const extensionFactories = [pressureExtension, telemetryExtension].filter((extension) => Boolean(extension));

package/dist/governance/harness.js

@@ -1,9 +1,4 @@
-import { readFile } from 'node:fs/promises';
-import path from 'node:path';
-import { harnessManifestSchema } from '../shared/types.js';
+import { loadNormalizedProjectConfig } from './project-config.js';
 export async function loadHarnessManifest(repoRoot) {
-    const manifestPath = path.join(repoRoot, 'harness.json');
-    const raw = await readFile(manifestPath, 'utf-8');
-    const parsed = JSON.parse(raw);
-    return harnessManifestSchema.parse(parsed);
+    return (await loadNormalizedProjectConfig(repoRoot)).manifest;
 }

package/dist/governance/manifest-types.js

@@ -209,14 +209,18 @@ export const nightSchedulerPolicySchema = z.object({
 export const workerPolicySchema = z.object({
     nightScheduler: nightSchedulerPolicySchema.optional().default({}),
 });
-export const CURSOR_HARNESS_EXECUTOR_REMOVED_ERROR = "harness executors.cursor is no longer supported; remove it and use executors.pi only (Cursor is available only via cursor-prompt sidecar)";
-export const harnessManifestSchema = z
+export const verificationCommandsSchema = z
     .object({
+    quick: z.array(z.string().trim().min(1)).optional().default([]),
+    standard: z.array(z.string().trim().min(1)).optional().default([]),
+    full: z.array(z.string().trim().min(1)).optional().default([]),
+})
+    .strict();
+export const CURSOR_HARNESS_EXECUTOR_REMOVED_ERROR = "harness executors.cursor is no longer supported; remove it and use executors.pi only (Cursor is available only via cursor-prompt sidecar)";
+const harnessManifestCommonShape = {
     $schema: z.string().optional(),
-    version: z.number(),
     project: z.string(),
     adapter: z.string().optional(),
-    governanceRoot: z.string(),
     features: z
         .object({
         goals: z.boolean().optional().default(true),
@@ -225,9 +229,7 @@ export const harnessManifestSchema = z
         .default({
         goals: true,
     }),
-    entrypoints: z.record(z.string(), z.string().nullable()),
-    artifacts: z.record(z.string(), z.string().nullable()),
-    scripts: z.record(z.string(), z.string().nullable()),
+    verification: verificationCommandsSchema.optional().default({}),
     workflowPolicy: workflowPolicySchema,
     /** Optional; absent means Night Scheduler uses package defaults when enabled by callers. */
     workerPolicy: workerPolicySchema.optional(),
@@ -237,8 +239,25 @@ export const harnessManifestSchema = z
         .strict()
         .optional()
         .default({}),
-})
-    .strict()
+};
+const harnessManifestV1Schema = z.object({
+    ...harnessManifestCommonShape,
+    version: z.literal(1),
+    governanceRoot: z.string(),
+    entrypoints: z.record(z.string(), z.string().nullable()),
+    artifacts: z.record(z.string(), z.string().nullable()),
+    scripts: z.record(z.string(), z.string().nullable()),
+}).strict();
+const harnessManifestV2Schema = z.object({
+    ...harnessManifestCommonShape,
+    version: z.literal(2),
+    governanceRoot: z.string().optional().default("docs"),
+    entrypoints: z.record(z.string(), z.string().nullable()).optional().default({}),
+    artifacts: z.record(z.string(), z.string().nullable()).optional().default({}),
+    scripts: z.record(z.string(), z.string().nullable()).optional().default({}),
+}).strict();
+export const harnessManifestSchema = z
+    .discriminatedUnion("version", [harnessManifestV1Schema, harnessManifestV2Schema])
     .superRefine((manifest, ctx) => {
     // Preserve the empty read-only compatibility projection for callers that
     // inspect parsed manifests, while rejecting this field in JSON input.

package/dist/governance/project-capability-scanner.js

@@ -0,0 +1,263 @@
+import { createHash } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { lstat, open, readdir, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+export const PROJECT_CAPABILITY_SCANNER_VERSION = 1;
+const MAX_INPUT_BYTES = 1024 * 1024;
+const RISKY_COMMAND_RE = /(?:^|[^A-Za-z0-9])(deploy|publish|release|upload|push|destroy|apply|login|logout)(?:$|[^A-Za-z0-9])/i;
+const SHELL_COMPOSITION_RE = /(?:&&|\|\||[|;<>`]|\$\(|\r|\n)/;
+const SAFE_NODE_SCRIPT_RE = /^(?:(?:npx|pnpm exec|yarn exec)\s+)?(?:tsc|eslint|biome|prettier|vitest|jest|mocha|ava|vite|next|node --test)(?:\s|$)/i;
+export function classifyVerificationCommand(command) {
+    const normalized = command.trim();
+    if (!normalized || RISKY_COMMAND_RE.test(normalized) || SHELL_COMPOSITION_RE.test(normalized))
+        return "unsafe";
+    return "safe";
+}
+function isContained(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+async function readSafeInput(repoRoot, relativePath) {
+    const file = path.resolve(repoRoot, ...relativePath.split("/"));
+    if (!isContained(path.resolve(repoRoot), file))
+        return null;
+    try {
+        const [rootReal, fileReal, linkInfo] = await Promise.all([realpath(repoRoot), realpath(file), lstat(file)]);
+        if (!isContained(rootReal, fileReal) || !linkInfo.isFile() || linkInfo.isSymbolicLink() || linkInfo.nlink !== 1)
+            return null;
+        if (linkInfo.size > MAX_INPUT_BYTES)
+            return null;
+        const noFollow = "O_NOFOLLOW" in fsConstants ? fsConstants.O_NOFOLLOW : 0;
+        const handle = await open(file, fsConstants.O_RDONLY | noFollow);
+        let before;
+        let after;
+        let bytes;
+        try {
+            before = await handle.stat();
+            if (!before.isFile() || before.nlink !== 1 || before.size > MAX_INPUT_BYTES)
+                return null;
+            bytes = await handle.readFile();
+            after = await handle.stat();
+        }
+        finally {
+            await handle.close();
+        }
+        const [pathAfter, fileRealAfter] = await Promise.all([stat(file), realpath(file)]);
+        if (!isContained(rootReal, fileRealAfter))
+            return null;
+        if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs)
+            return null;
+        if (after.dev !== pathAfter.dev || after.ino !== pathAfter.ino || after.size !== pathAfter.size)
+            return null;
+        return {
+            path: relativePath,
+            bytes: bytes.byteLength,
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+            content: bytes.toString("utf8"),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function isSafeNodeScript(name, scripts, visiting = new Set()) {
+    if (visiting.has(name))
+        return false;
+    const body = scripts[name];
+    if (typeof body !== "string" || classifyVerificationCommand(body) !== "safe")
+        return false;
+    if (SAFE_NODE_SCRIPT_RE.test(body.trim()))
+        return true;
+    const delegated = /^(?:npm|pnpm|yarn)\s+(?:run\s+)?([A-Za-z0-9:_-]+)$/.exec(body.trim());
+    if (!delegated)
+        return false;
+    visiting.add(name);
+    const safe = isSafeNodeScript(delegated[1], scripts, visiting);
+    visiting.delete(name);
+    return safe;
+}
+function parseJson(input) {
+    if (!input)
+        return null;
+    try {
+        const parsed = JSON.parse(input.content);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function nodePackageManager(pkg, evidence) {
+    if (typeof pkg.packageManager === "string") {
+        if (pkg.packageManager.startsWith("pnpm@"))
+            return "pnpm";
+        if (pkg.packageManager.startsWith("yarn@"))
+            return "yarn";
+    }
+    if (evidence.has("pnpm-lock.yaml"))
+        return "pnpm";
+    if (evidence.has("yarn.lock"))
+        return "yarn";
+    return "npm";
+}
+function nodeCommand(pm, script) {
+    if (script === "test")
+        return `${pm} test`;
+    return pm === "npm" ? `npm run ${script}` : `${pm} run ${script}`;
+}
+function workspacePatterns(pkg) {
+    const raw = Array.isArray(pkg.workspaces)
+        ? pkg.workspaces
+        : pkg.workspaces && typeof pkg.workspaces === "object" && Array.isArray(pkg.workspaces.packages)
+            ? pkg.workspaces.packages
+            : [];
+    return raw.filter((item) => typeof item === "string" && item.endsWith("/*") && !item.includes(".."));
+}
+async function discoverWorkspaceCandidates(repoRoot, patterns) {
+    const candidates = [];
+    for (const pattern of patterns) {
+        const parent = pattern.slice(0, -2).replaceAll("\\", "/");
+        const parentPath = path.resolve(repoRoot, ...parent.split("/"));
+        if (!isContained(path.resolve(repoRoot), parentPath))
+            continue;
+        let names;
+        try {
+            names = (await readdir(parentPath, { withFileTypes: true }))
+                .filter((entry) => entry.isDirectory() && !entry.isSymbolicLink())
+                .map((entry) => entry.name)
+                .sort();
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            const relative = `${parent}/${name}`;
+            if (await readSafeInput(repoRoot, `${relative}/package.json`))
+                candidates.push(relative);
+        }
+    }
+    return [...new Set(candidates)].sort();
+}
+async function rootDotnetFiles(repoRoot) {
+    try {
+        return (await readdir(repoRoot, { withFileTypes: true }))
+            .filter((entry) => entry.isFile() && (/\.sln$/i.test(entry.name) || /\.csproj$/i.test(entry.name)))
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+export class ProjectCapabilityScanner {
+    async scan(repoRoot, options = {}) {
+        const root = path.resolve(repoRoot);
+        const evidence = new Map();
+        const add = async (relative) => {
+            if (evidence.has(relative))
+                return evidence.get(relative);
+            const value = await readSafeInput(root, relative);
+            if (value)
+                evidence.set(relative, value);
+            return value;
+        };
+        for (const name of [
+            "README.md", "package.json", "package-lock.json", "pnpm-lock.yaml", "yarn.lock",
+            "pyproject.toml", "go.mod", "Cargo.toml", "pom.xml", "build.gradle", "build.gradle.kts",
+            "gradlew", "gradlew.bat", "Makefile",
+        ])
+            await add(name);
+        for (const name of await rootDotnetFiles(root))
+            await add(name);
+        const rootPkg = parseJson(evidence.get("package.json") ?? null);
+        const workspaceCandidates = rootPkg ? await discoverWorkspaceCandidates(root, workspacePatterns(rootPkg)) : [];
+        const requestedWorkspace = options.workspaceRoot?.replaceAll("\\", "/").replace(/^\.\//, "") ?? null;
+        const explicitRoot = requestedWorkspace === ".";
+        let selectedWorkspace = explicitRoot ? null : requestedWorkspace;
+        if (selectedWorkspace && !workspaceCandidates.includes(selectedWorkspace)) {
+            throw new Error(`workspaceRoot is not a discovered workspace: ${selectedWorkspace}`);
+        }
+        if (!explicitRoot && !selectedWorkspace && workspaceCandidates.length === 1)
+            selectedWorkspace = workspaceCandidates[0];
+        const ambiguousWorkspace = !explicitRoot && !selectedWorkspace && workspaceCandidates.length > 1;
+        if (selectedWorkspace)
+            await add(`${selectedWorkspace}/package.json`);
+        const commands = [];
+        const ecosystems = new Set();
+        const push = (ecosystem, id, command, evidencePaths, cwd = ".") => {
+            if (classifyVerificationCommand(command) !== "safe")
+                return;
+            ecosystems.add(ecosystem);
+            commands.push({ id, command, cwd, scope: cwd === "." ? ["**"] : [`${cwd}/**`], evidence: evidencePaths, confidence: "high", source: "scanner" });
+        };
+        const nodeManifestPath = selectedWorkspace ? `${selectedWorkspace}/package.json` : "package.json";
+        const nodePkg = parseJson(evidence.get(nodeManifestPath) ?? null);
+        if (nodePkg) {
+            ecosystems.add("node");
+            if (!ambiguousWorkspace) {
+                const pm = nodePackageManager(rootPkg ?? nodePkg, evidence);
+                for (const script of ["typecheck", "lint", "test", "build"]) {
+                    const body = nodePkg.scripts?.[script];
+                    if (typeof body !== "string" || !isSafeNodeScript(script, nodePkg.scripts ?? {}))
+                        continue;
+                    push("node", `node:${script}`, nodeCommand(pm, script), [nodeManifestPath], selectedWorkspace ?? ".");
+                }
+            }
+        }
+        if (evidence.has("pyproject.toml")) {
+            ecosystems.add("python");
+            if (/\[tool\.pytest\.ini_options\]/.test(evidence.get("pyproject.toml").content))
+                push("python", "python:test", "python -m pytest", ["pyproject.toml"]);
+        }
+        if (evidence.has("go.mod")) {
+            ecosystems.add("go");
+            push("go", "go:test", "go test ./...", ["go.mod"]);
+        }
+        if (evidence.has("Cargo.toml")) {
+            ecosystems.add("rust");
+            push("rust", "rust:test", "cargo test", ["Cargo.toml"]);
+        }
+        if (evidence.has("pom.xml")) {
+            ecosystems.add("maven");
+            push("maven", "maven:test", "mvn test", ["pom.xml"]);
+        }
+        const gradle = evidence.has("build.gradle.kts") ? "build.gradle.kts" : evidence.has("build.gradle") ? "build.gradle" : null;
+        if (gradle) {
+            ecosystems.add("gradle");
+            push("gradle", "gradle:test", process.platform === "win32" && evidence.has("gradlew.bat") ? "gradlew.bat test" : evidence.has("gradlew") ? "./gradlew test" : "gradle test", [gradle]);
+        }
+        if (evidence.has("Makefile")) {
+            ecosystems.add("make");
+            if (/^test\s*:/m.test(evidence.get("Makefile").content))
+                push("make", "make:test", "make test", ["Makefile"]);
+        }
+        const dotnet = [...evidence.keys()].filter((name) => /\.(?:sln|csproj)$/i.test(name));
+        if (dotnet.length > 0)
+            ecosystems.add("dotnet");
+        if (dotnet.length === 1)
+            push("dotnet", "dotnet:test", `dotnet test ${dotnet[0]}`, [dotnet[0]]);
+        const evidenceList = [...evidence.values()]
+            .map(({ content: _content, ...item }) => item)
+            .sort((a, b) => a.path.localeCompare(b.path));
+        const fingerprintHash = createHash("sha256");
+        fingerprintHash.update(`project-capability-scanner-v${PROJECT_CAPABILITY_SCANNER_VERSION}\n`);
+        for (const item of evidenceList)
+            fingerprintHash.update(`${item.path}\0${item.sha256}\n`);
+        fingerprintHash.update(`workspace\0${explicitRoot ? "." : selectedWorkspace ?? ""}\n`);
+        const status = ambiguousWorkspace ? "ambiguous" : commands.length > 0 ? "ready" : "unavailable";
+        return {
+            schemaVersion: 1,
+            scannerVersion: 1,
+            repoRoot: root,
+            workspace: { selected: explicitRoot ? "." : selectedWorkspace, candidates: workspaceCandidates },
+            ecosystems: [...ecosystems].sort(),
+            evidence: evidenceList,
+            fingerprint: fingerprintHash.digest("hex"),
+            verification: {
+                status,
+                commands: ambiguousWorkspace ? [] : commands,
+                requiredInput: ambiguousWorkspace ? ["workspaceRoot"] : commands.length === 0 ? ["verification"] : [],
+            },
+        };
+    }
+}

package/dist/governance/project-config.js

@@ -0,0 +1,96 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { harnessManifestSchema, verificationCommandsSchema, workflowPolicySchema, workerPolicySchema, worktreeManifestConfigSchema, } from "./manifest-types.js";
+function isSafeProjectPath(value) {
+    if (!value || path.isAbsolute(value))
+        return false;
+    return !value.replaceAll("\\", "/").split("/").some((part) => part === "" || part === "." || part === "..");
+}
+const nullablePathMapSchema = z.record(z.string(), z.string().refine(isSafeProjectPath, "path must be a safe project-relative path").nullable());
+/** Shared, credential-free overrides that are safe to commit with the project. */
+export const projectConfigSchema = z
+    .object({
+    $schema: z.string().optional(),
+    version: z.literal(1),
+    verification: verificationCommandsSchema.optional(),
+    entrypoints: nullablePathMapSchema.optional(),
+    artifacts: nullablePathMapSchema.optional(),
+    workflowPolicy: workflowPolicySchema.optional(),
+    workerPolicy: workerPolicySchema.optional(),
+    worktree: worktreeManifestConfigSchema.optional(),
+})
+    .strict();
+const EMPTY_VERIFICATION = { quick: [], standard: [], full: [] };
+function appendUnique(left, right) {
+    return [...new Set([...left, ...right])];
+}
+function mergeVerification(tracked, local) {
+    const shared = tracked ?? EMPTY_VERIFICATION;
+    const machine = local ?? EMPTY_VERIFICATION;
+    const sources = [];
+    if ([...shared.quick, ...shared.standard, ...shared.full].length > 0)
+        sources.push("tracked");
+    if ([...machine.quick, ...machine.standard, ...machine.full].length > 0)
+        sources.push("local");
+    return {
+        quick: appendUnique(shared.quick, machine.quick),
+        standard: appendUnique(shared.standard, machine.standard),
+        full: appendUnique(shared.full, machine.full),
+        reproducibility: sources.includes("local") ? "local-only" : sources.includes("tracked") ? "tracked" : "inferred",
+        sources,
+    };
+}
+async function readOptionalJson(file) {
+    try {
+        return JSON.parse(await readFile(file, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * Load package defaults, tracked project policy, then machine-local runtime
+ * settings. Local verification is additive by construction: it cannot remove
+ * or replace a command committed in project.json.
+ */
+export async function loadNormalizedProjectConfig(repoRoot) {
+    const localPath = path.join(repoRoot, "harness.json");
+    const trackedPath = path.join(repoRoot, ".loop-agent", "project.json");
+    const [localRaw, trackedRaw] = await Promise.all([
+        readOptionalJson(localPath),
+        readOptionalJson(trackedPath),
+    ]);
+    if (localRaw === undefined)
+        throw Object.assign(new Error("harness.json not found"), { code: "HARNESS_NOT_FOUND" });
+    const local = harnessManifestSchema.parse(localRaw);
+    const tracked = trackedRaw === undefined ? undefined : projectConfigSchema.parse(trackedRaw);
+    const verification = mergeVerification(tracked?.verification, local.verification);
+    const localInput = localRaw;
+    const localFields = { ...local };
+    delete localFields.modelProfiles;
+    const manifest = harnessManifestSchema.parse({
+        ...localFields,
+        entrypoints: { ...(tracked?.entrypoints ?? {}), ...(local.entrypoints ?? {}) },
+        artifacts: { ...(tracked?.artifacts ?? {}), ...(local.artifacts ?? {}) },
+        workflowPolicy: Object.hasOwn(localInput, "workflowPolicy") ? local.workflowPolicy : tracked?.workflowPolicy ?? local.workflowPolicy,
+        workerPolicy: Object.hasOwn(localInput, "workerPolicy") ? local.workerPolicy : tracked?.workerPolicy ?? local.workerPolicy,
+        worktree: Object.hasOwn(localInput, "worktree") ? local.worktree : tracked?.worktree ?? local.worktree,
+        verification: {
+            quick: verification.quick,
+            standard: verification.standard,
+            full: verification.full,
+        },
+    });
+    return {
+        schemaVersion: 1,
+        manifest,
+        verification,
+        sources: {
+            tracked: tracked ? ".loop-agent/project.json" : null,
+            local: "harness.json",
+        },
+    };
+}