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

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",
+        },
+    };
+}

package/dist/governance/resource-catalog.js

@@ -0,0 +1,151 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { findPackageRoot } from "../shared/package-metadata.js";
+const SHA256_RE = /^[a-f0-9]{64}$/;
+function isSafePackagePath(value) {
+    if (!value || path.isAbsolute(value) || value.includes("\\"))
+        return false;
+    const parts = value.split("/");
+    return parts.every((part) => part !== "" && part !== "." && part !== "..");
+}
+export const resourceCatalogEntrySchema = z
+    .object({
+    id: z.string().trim().min(1).regex(/^[A-Za-z0-9][A-Za-z0-9:._/-]*$/),
+    path: z.string().refine(isSafePackagePath, "path must stay within the package root"),
+    kind: z.enum(["document", "skill", "template", "schema", "prompt", "script", "other"]),
+    bytes: z.number().int().nonnegative(),
+    sha256: z.string().regex(SHA256_RE),
+    schemaVersion: z.number().int().positive(),
+})
+    .strict();
+export const resourceCatalogSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    entries: z.array(resourceCatalogEntrySchema),
+})
+    .strict()
+    .superRefine((catalog, ctx) => {
+    const ids = new Set();
+    const paths = new Set();
+    for (const [index, entry] of catalog.entries.entries()) {
+        if (ids.has(entry.id))
+            ctx.addIssue({ code: "custom", path: ["entries", index, "id"], message: "duplicate resource id" });
+        if (paths.has(entry.path))
+            ctx.addIssue({ code: "custom", path: ["entries", index, "path"], message: "duplicate resource path" });
+        ids.add(entry.id);
+        paths.add(entry.path);
+    }
+});
+export const CONTROLLER_RESOURCE_IDS = {
+    loopAgentBridgeSkill: "agent-bridge:loop-agent",
+};
+export function builtinSkillResourceId(name) {
+    return `builtin-skill:${name}`;
+}
+export function builtinSkillReferenceResourceId(name, relativePath) {
+    return `builtin-skill-resource:${name}/${relativePath}`;
+}
+export class ResourceCatalogError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ResourceCatalogError";
+    }
+}
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+async function assertContainedRegularFile(root, candidate) {
+    const [rootReal, candidateReal, linkInfo] = await Promise.all([
+        realpath(root),
+        realpath(candidate),
+        lstat(candidate),
+    ]);
+    const relative = path.relative(rootReal, candidateReal);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new ResourceCatalogError("RESOURCE_PATH_ESCAPE", `resource resolves outside package root: ${candidate}`);
+    }
+    if (!linkInfo.isFile() || linkInfo.isSymbolicLink() || linkInfo.nlink !== 1) {
+        throw new ResourceCatalogError("RESOURCE_NOT_REGULAR", `resource is not a regular file: ${candidate}`);
+    }
+}
+/** Lazy package resource provider: load the small catalog once, hash bytes only when used. */
+export class ControllerContextProvider {
+    packageRoot;
+    identity;
+    entries;
+    constructor(packageRoot, catalog, catalogBytes) {
+        this.packageRoot = packageRoot;
+        this.entries = new Map(catalog.entries.map((entry) => [entry.id, entry]));
+        this.identity = { schemaVersion: 1, catalogDigest: sha256(catalogBytes) };
+    }
+    static async load(packageRoot, catalogName = "resource-catalog.v1.json") {
+        const catalogPath = path.join(packageRoot, catalogName);
+        await assertContainedRegularFile(packageRoot, catalogPath);
+        const bytes = await readFile(catalogPath);
+        let parsed;
+        try {
+            parsed = JSON.parse(bytes.toString("utf8"));
+        }
+        catch (error) {
+            throw new ResourceCatalogError("RESOURCE_CATALOG_INVALID", `invalid resource catalog JSON: ${String(error)}`);
+        }
+        const catalog = resourceCatalogSchema.safeParse(parsed);
+        if (!catalog.success) {
+            throw new ResourceCatalogError("RESOURCE_CATALOG_INVALID", `invalid resource catalog: ${catalog.error.message}`);
+        }
+        return new ControllerContextProvider(packageRoot, catalog.data, bytes);
+    }
+    list() {
+        return [...this.entries.values()].map((entry) => ({ ...entry }));
+    }
+    entry(id) {
+        const entry = this.entries.get(id);
+        return entry ? { ...entry } : undefined;
+    }
+    async read(id) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            throw new ResourceCatalogError("RESOURCE_NOT_FOUND", `resource not found: ${id}`);
+        const file = path.join(this.packageRoot, ...entry.path.split("/"));
+        await assertContainedRegularFile(this.packageRoot, file);
+        const before = await stat(file);
+        const bytes = await readFile(file);
+        const after = await stat(file);
+        if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs) {
+            throw new ResourceCatalogError("RESOURCE_CHANGED_DURING_READ", `resource changed while reading: ${id}`);
+        }
+        if (bytes.byteLength !== entry.bytes || sha256(bytes) !== entry.sha256) {
+            throw new ResourceCatalogError("RESOURCE_HASH_MISMATCH", `resource does not match catalog: ${id}`);
+        }
+        return bytes;
+    }
+    async readText(id) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            throw new ResourceCatalogError("RESOURCE_NOT_FOUND", `resource not found: ${id}`);
+        const bytes = await this.read(id);
+        return {
+            id,
+            relativePath: entry.path,
+            absolutePath: path.join(this.packageRoot, ...entry.path.split("/")),
+            kind: entry.kind,
+            schemaVersion: entry.schemaVersion,
+            bytes: entry.bytes,
+            sha256: entry.sha256,
+            text: bytes.toString("utf8"),
+        };
+    }
+}
+export async function createControllerContextProvider(options = {}) {
+    const packageRoot = options.packageRoot
+        ?? findPackageRoot(path.dirname(fileURLToPath(import.meta.url)));
+    if (!packageRoot) {
+        throw new ResourceCatalogError("PACKAGE_ROOT_NOT_FOUND", "cannot locate the loop-agent package root for controller resources");
+    }
+    return ControllerContextProvider.load(packageRoot, options.catalogName ?? "resource-catalog.v1.json");
+}

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

@@ -290,13 +290,17 @@ export async function removeStaged(filePath) {
     await rm(filePath, { force: true });
 }
 /** Synchronous helpers used by boot-time path checks. */
-export function writeSecureJsonSync(filePath, value) {
+export function writeSecureJsonSync(filePath, value, options) {
     const dir = path.dirname(filePath);
     ensureSecureDir(dir);
     const resolved = assertSafeAppDataPath(dir, filePath);
     const tmp = `${resolved}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    const pretty = options?.pretty !== false;
+    const body = pretty
+        ? `${JSON.stringify(value, null, 2)}\n`
+        : `${JSON.stringify(value)}\n`;
     try {
-        writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, {
+        writeFileSync(tmp, body, {
             encoding: "utf8",
             mode: 0o600,
         });

package/dist/shared/operator/capabilities.js

@@ -395,7 +395,7 @@ export function buildOperatorCapabilitiesDocument() {
         {
             action: "prepareScheduledTask", cli: "console scheduled task preparation", kind: "mutation",
             inputSchemaVersion: 1, resultSchemaVersion: 1, envelopeSchemaVersion: 1, requiredErrorCodes: ["INVALID_INPUT"],
-            description: "Preferred entry for natural-language one-time scheduled tasks, including read-only inspection reports. Call this directly after understanding the goal, output scope, executable acceptance and time; the server uses the CURRENT project directory and creates the immutable PRD, managed Task and strict writeSet gate, binds THIS Chat automatically and returns a REAL planned goal/confirmation card. No pre-existing task, worktree or session ID is needed: never ask the user for these internal fields and do not manually create/edit them with bash/write/newTask/importPrd. Keep preparation concise: preserve the user goal without inventing extra requirements. Omit budget for ordinary tasks. Use minimal independent acceptance commands (AC-1, AC-2), preferably existing test/build scripts or test -s scheduled-report.md for a report; no compound shell/pipelines/substitution, language-specific grep checks or redundant scope assertions (the host enforces scope). Infer routine defaults and verification commands from the repository; ask only about genuinely ambiguous goal/scope/time. For read-only requests allow just an ordinary report file in the current project directory, e.g. scheduled-report.md, not .harness/. Use schedule.delayMinutes for relative time (counted after preparation finishes), or localAt + IANA timezone for an exact date/time. The current workspace must match committed HEAD; never auto-commit/stash/reset existing changes. The card exposes the exact time, bounded defaults and committed base before one human confirmation. Same request in this Chat is idempotent. Only a returned goalId with state=planned is a prepared reservation; textual drafts, Tasks or failed operations are NOT bookings. Never replace a requested schedule with immediate execution or sleep, never call runDag or self-confirm. On failure explain the returned stage, correct business inputs and retry this tool; do not mutate imported PRD/runtime artifacts. For a new distinct appointment, make its goal/time distinct.",
+            description: "Preferred entry for natural-language one-time scheduled tasks, including read-only inspection reports. Call this directly after understanding the goal, output scope, executable acceptance and time; the server uses the CURRENT project directory and creates the immutable PRD, managed Task and strict writeSet gate, binds THIS Chat automatically and returns a REAL planned goal/confirmation card. No pre-existing task, worktree or session ID is needed: never ask the user for these internal fields and do not manually create/edit them with bash/write/newTask/importPrd. Keep preparation concise: preserve the user goal without inventing extra requirements. Omit budget for ordinary tasks: the host freezes 5 goal attempts, 5 DAG runs and 4 supervisor calls, with a 15-minute latest-start grace and a 240-minute execution window, all shown before confirmation. maxTurns counts goal attempts, not model tool calls. Explicit budget or maxDurationMinutes is never raised. Use minimal independent acceptance commands (AC-1, AC-2), preferably existing test/build scripts or test -s scheduled-report.md for a report; no compound shell/pipelines/substitution, language-specific grep checks or redundant scope assertions (the host enforces scope). Infer routine defaults and verification commands from the repository; ask only about genuinely ambiguous goal/scope/time. For read-only requests allow just an ordinary report file in the current project directory, e.g. scheduled-report.md, not .harness/. Use schedule.delayMinutes for relative time (counted after preparation finishes), or localAt + IANA timezone for an exact date/time. The current workspace must match committed HEAD; never auto-commit/stash/reset existing changes. The card exposes the exact time, bounded defaults and committed base before one human confirmation. Same request in this Chat is idempotent. Only a returned goalId with state=planned is a prepared reservation; textual drafts, Tasks or failed operations are NOT bookings. Never replace a requested schedule with immediate execution or sleep, never call runDag or self-confirm. On failure explain the returned stage, correct business inputs and retry this tool; do not mutate imported PRD/runtime artifacts. For a new distinct appointment, make its goal/time distinct.",
             inputParams: [{ name: "request", type: "object", required: true, description: "Business goal, workflow, allowedPaths, acceptance and schedule; optional forbiddenPaths/budget. Runtime identity is server-owned." }],
             modelCallable: "always", humanConfirmation: "none",
         },
@@ -409,7 +409,7 @@ export function buildOperatorCapabilitiesDocument() {
             "requiredErrorCodes": [
                 "INVALID_INPUT"
             ],
-            "description": "Advanced entry ONLY for an already prepared Task. For a new natural-language reservation use prepareScheduledTask instead. Requires the current repository or its linked worktree at frozenBase and a managed Task already strict-prepared at its writeSet gate. booking must include managedTaskId, originalGoal, chatSessionRef, workflow, worktreeRef, frozenBase, allowedPaths, forbiddenPaths, acceptance {policy, criteria [{acId,description,command}]}, budget {maxTurns,maxDagRuns,maxSupervisorCalls}, time {executeAtUtc,latestStartUtc,stopAtUtc,expiresAt,timezone,allowedHours,misfirePolicy}. Resolve natural-language dates with the user timezone; ask about ambiguous time/AC/scope. No execution or authorization occurs. Show the complete scope/time/budget for one browser confirmation. Never call runDag for this reservation.",
+            "description": "Advanced entry ONLY for an already prepared Task. For a new natural-language reservation use prepareScheduledTask instead. Requires the current repository or its linked worktree at frozenBase and a managed Task already strict-prepared at its writeSet gate. booking must include managedTaskId, originalGoal, chatSessionRef, workflow, worktreeRef, frozenBase, allowedPaths, forbiddenPaths, acceptance {policy, criteria [{acId,description,command}]}, budget {maxTurns,maxDagRuns,maxSupervisorCalls}, time {executeAtUtc,latestStartUtc,stopAtUtc,expiresAt,timezone,allowedHours,misfirePolicy}. This entry never fills omitted budget; for implementation work supply at least maxTurns=5, maxDagRuns=5, maxSupervisorCalls=4. Resolve natural-language dates with the user timezone; ask about ambiguous time/AC/scope. No execution or authorization occurs. Show the complete scope/time/budget for one browser confirmation. Never call runDag for this reservation.",
             "inputParams": [
                 {
                     "name": "booking",

package/dist/shared/package-metadata.js

@@ -106,8 +106,9 @@ export function computeBinarySha256(filePath) {
  * Compute a portable, deterministic content fingerprint for the installed
  * package rooted at `packageRoot`.
  *
- * The fingerprint covers four scopes (package.json, bin/**, dist/**,
- * skills/**) and is independent of the absolute installation path.
+ * The fingerprint covers executable code plus package-owned Skills, templates,
+ * bridge resources, and their generated catalog. It is independent of the
+ * absolute installation path.
  *
  * Sorting uses code-point order (UTF-8 byte comparison), NOT localeCompare,
  * to ensure deterministic behaviour across locales.
@@ -118,17 +119,23 @@ export function computePackageFingerprint(packageRoot) {
         "bin/**",
         "dist/**",
         "skills/**",
+        "docs/templates/**",
+        "resources/**",
+        "resource-catalog.v1.json",
     ];
     // Collecting entries ---------------------------------------------------
     const entries = [];
     // 1) package.json (required single file)
     addRequiredFile(entries, path.join(packageRoot, "package.json"), "");
-    // 2) bin/**, dist/**, skills/** via recursive walk
-    for (const dir of ["bin", "dist", "skills"]) {
+    // 2) Package-owned executable and controller-resource trees.
+    for (const dir of ["bin", "dist", "skills", "docs/templates", "resources"]) {
         const absoluteDir = path.join(packageRoot, dir);
         collectTree(entries, absoluteDir, dir);
     }
-    // 3) Deterministic sort by relative path (code-point / byte order)
+    // 3) The generated catalog binds logical resource ids to those bytes. It is
+    // optional only for source/test fixtures; published packages always ship it.
+    addOptionalFile(entries, path.join(packageRoot, "resource-catalog.v1.json"), "");
+    // 4) Deterministic sort by relative path (code-point / byte order)
     entries.sort((a, b) => {
         const aBuf = Buffer.from(a.relativePath, "utf-8");
         const bBuf = Buffer.from(b.relativePath, "utf-8");
@@ -141,14 +148,14 @@ export function computePackageFingerprint(packageRoot) {
         }
         return aBuf.length - bBuf.length;
     });
-    // 4) Cumulative hash: hash of (<relativePath> + "\t" + <contentHash>) lines
+    // 5) Cumulative hash: hash of (<relativePath> + "\t" + <contentHash>) lines
     const cumulative = createHash("sha256");
     for (const entry of entries) {
         cumulative.update(`${entry.relativePath}\t${entry.contentHash}\n`);
     }
     return {
         algorithm: "sha256",
-        scopeVersion: 1,
+        scopeVersion: 2,
         scope,
         value: `sha256:${cumulative.digest("hex")}`,
         fileCount: entries.length,
@@ -316,6 +323,15 @@ function addRequiredFile(entries, absolutePath, relativeDir) {
         : path.basename(absolutePath);
     entries.push({ relativePath, contentHash });
 }
+function addOptionalFile(entries, absolutePath, relativeDir) {
+    try {
+        addRequiredFile(entries, absolutePath, relativeDir);
+    }
+    catch (error) {
+        if (!isNotFound(error))
+            throw error;
+    }
+}
 function collectTree(entries, absoluteDir, relativeDir) {
     let stats;
     try {