@pome-sh/cli 0.8.0 → 0.10.0

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
   "package": "pome-sh",
-  "version": "0.8.0",
-  "git_sha": "a0a02905d653d8527558dd2bd64ad5eaded24d07",
-  "build_time": "2026-07-24T22:05:00.539Z"
+  "version": "0.10.0",
+  "git_sha": "14613c1a69d37441adc719248f0a506d7db76da9",
+  "build_time": "2026-07-28T23:09:18.070Z"
 }

package/dist/src/cli/agent-identity.js

@@ -13,7 +13,7 @@ import { dirname } from "node:path";
 import { postAgentResolver, resolveSeams, } from "./agent-resolver.js";
 import { resolveCredentials } from "./credentials.js";
 import { ensurePomeGitignored, readLinkCache, resolveCachedAgentId, writeLinkCache, } from "./link-cache.js";
-import { readManifest } from "./project-config.js";
+import { normalizeManifestTwins, readManifest } from "./project-config.js";
 export async function resolveRunAgentIdentity(input) {
     const manifestRead = await readManifest(input.startDir);
     if (!manifestRead) {
@@ -38,13 +38,18 @@ export async function resolveRunAgentIdentity(input) {
         if (cachedId) {
             return { ...base, agentId: cachedId };
         }
-        // Silent re-resolution — a run never prompts for a near-miss.
+        // Silent re-resolution — a run never prompts for a near-miss. Send the
+        // manifest's twins so a fork / first `pome run` that auto-creates the agent
+        // enables the declared services instead of the server's `github` default
+        // (F-926); the server merges additively, so this is safe when the agent
+        // already exists.
         const resolved = await postAgentResolver(creds, {
             name: agent.name ?? agent.slug,
             slug: agent.slug,
             description: agent.description,
             version: agent.version,
             framework: agent.framework,
+            twins: normalizeManifestTwins(manifestRead.manifest.twins),
         }, resolveSeams({ stdinIsTTY: false }));
         if (creds.teamId) {
             await writeLinkCache(projectDir, { agent_id: resolved.id, team_id: creds.teamId });

package/dist/src/cli/agent-resolver.d.ts

@@ -4,6 +4,9 @@ import type { ResolvedCredentials } from "./credentials.js";
 export interface InteractiveSeams {
     stdinIsTTY?: boolean;
     confirm?: (question: string) => Promise<boolean>;
+    /** Free-text prompt. Added by F-1074: picking a check from a numbered list and
+     *  filling its typed parameters needs an answer, not a yes/no. */
+    ask?: (question: string) => Promise<string>;
 }
 /** The manifest identity fields POSTed to the resolver. */
 export interface AgentPostBody {

package/dist/src/cli/agent-resolver.js

@@ -11,6 +11,7 @@ export function resolveSeams(opts) {
     return {
         stdinIsTTY: opts.stdinIsTTY ?? Boolean(process.stdin.isTTY),
         confirm: opts.confirm ?? promptYesNo,
+        ask: opts.ask ?? promptLine,
     };
 }
 async function requestAgent(creds, body) {
@@ -119,3 +120,12 @@ async function promptYesNo(question) {
         rl.close();
     }
 }
+async function promptLine(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return (await new Promise((resolve) => rl.question(question, resolve))).trim();
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/src/cli/checks-add.d.ts

@@ -0,0 +1,32 @@
+import { type InteractiveSeams } from "./agent-resolver.js";
+export interface RemoteChecks {
+    twin: string;
+    digest: string;
+    checks: Array<{
+        id: string;
+        template: string;
+        substrate: string;
+    }>;
+}
+export type HandshakeResult = {
+    kind: "match";
+} | {
+    kind: "skew";
+    message: string;
+} | {
+    kind: "unverified";
+    note: string;
+};
+export declare function parseArgFlags(pairs: string[]): Record<string, string> | {
+    error: string;
+};
+export declare function handshake(twin: string, fetchRemote: (twin: string) => Promise<RemoteChecks>): Promise<HandshakeResult>;
+export interface ChecksAddOptions extends InteractiveSeams {
+    check?: string;
+    arg: string[];
+    apiBaseUrl?: string;
+    /** Test seam — defaults to the live GET /v1/checks handshake. */
+    fetchRemote?: (twin: string) => Promise<RemoteChecks>;
+    credentialsPath?: string;
+}
+export declare function runChecksAddCommand(file: string, opts: ChecksAddOptions): Promise<void>;

package/dist/src/cli/checks-add.js

@@ -0,0 +1,236 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * `pome checks add <file>` — pick a declared check, fill its typed parameters,
+ * and let pome write the English into the task file. The author never types the
+ * sentence, so it cannot fail to bind.
+ *
+ * The digest handshake: this CLI resolves declarations from its own npm pin and
+ * the cloud resolves them from a different one. Before writing, ask the cloud
+ * for the vocabulary it GRADES against and compare digests.
+ *   equal        → write, silently
+ *   different    → REFUSE, and name which check moved
+ *   unreachable  → write from the local pin with a named note on stderr
+ * Offline authoring is real, and the degraded path's worst case is bounded: a
+ * stale sentence that keeps a template's literal segments fails at finalize as
+ * `corrupted_check_instance:<id>` — named, not a silent unmatched.
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import { renderCheck, templateSlots } from "@pome-sh/sdk/checks";
+import { DuplicateCriterionError, MissingCriteriaSectionError, insertCriterion, } from "../task/insertCriterion.js";
+import { readConfigTwins } from "../task/parseTask.js";
+import { resolveSeams } from "./agent-resolver.js";
+import { SUBSTRATE_HELP, checksFor, displaySentence, findCheck, localDigest, pinnedVersion, twinOf, } from "./checks.js";
+import { resolveCredentials } from "./credentials.js";
+export function parseArgFlags(pairs) {
+    const args = {};
+    for (const pair of pairs) {
+        const eq = pair.indexOf("=");
+        if (eq <= 0)
+            return { error: `--arg must be key=value, got ${JSON.stringify(pair)}` };
+        args[pair.slice(0, eq)] = pair.slice(eq + 1);
+    }
+    return args;
+}
+export async function handshake(twin, fetchRemote) {
+    const pin = pinnedVersion(`@pome-sh/twin-${twin}`);
+    let remote;
+    try {
+        remote = await fetchRemote(twin);
+    }
+    catch (err) {
+        return {
+            kind: "unverified",
+            note: `Not verified against the cloud (${err instanceof Error ? err.message : "unreachable"}). ` +
+                `Writing from the local pin: @pome-sh/twin-${twin} ${pin}.`,
+        };
+    }
+    if (localDigest(twin) === remote.digest)
+        return { kind: "match" };
+    const here = new Map(checksFor(twin).map((check) => [check.id, check.template]));
+    const there = new Map(remote.checks.map((check) => [check.id, check.template]));
+    const moved = [];
+    for (const [id, template] of here) {
+        if (!there.has(id))
+            moved.push(`${id} — this CLI has it, the cloud does not`);
+        else if (there.get(id) !== template) {
+            moved.push(`${id} — the sentence differs\n        here:  ${template}\n        cloud: ${there.get(id)}`);
+        }
+    }
+    for (const id of there.keys()) {
+        if (!here.has(id))
+            moved.push(`${id} — the cloud has it, this CLI does not`);
+    }
+    return {
+        kind: "skew",
+        message: `Refusing to write: this CLI and the cloud disagree about ${twin}'s vocabulary, so a ` +
+            `sentence written here might not be graded there.\n` +
+            moved.map((line) => `      - ${line}`).join("\n") +
+            `\n\n  local @pome-sh/twin-${twin} ${pin}` +
+            `\n  Update with \`npm i -g @pome-sh/cli@latest\`. If this CLI is already current, the ` +
+            `cloud is behind — that is a deploy, not something you can fix here.`,
+    };
+}
+async function liveFetch(creds, twin) {
+    const res = await fetch(`${creds.apiBaseUrl}/v1/checks?twin=${encodeURIComponent(twin)}`, {
+        headers: { "x-api-key": creds.apiKey },
+    });
+    if (!res.ok)
+        throw new Error(`GET /v1/checks returned ${res.status}`);
+    return (await res.json());
+}
+async function pickInteractively(source, seams) {
+    // CI is not interactive even when stdin happens to be a TTY — the same guard
+    // as agent-resolver's, so a pipeline gets a named refusal, never a hang.
+    if (!seams.stdinIsTTY || process.env.CI) {
+        console.error("Not an interactive terminal. Pass `--check <id> --arg key=value` " +
+            "(run `pome checks <twin>` to see both).");
+        process.exitCode = 2;
+        return undefined;
+    }
+    const twins = readConfigTwins(source);
+    const available = twins.flatMap((twin) => [...checksFor(twin)]);
+    if (available.length === 0) {
+        console.error(`No declared checks for this task's twins (${twins.join(", ")}). ` +
+            `Use a [model] criterion, or run \`pome checks\` to see which twins declare one.`);
+        process.exitCode = 2;
+        return undefined;
+    }
+    console.log("Which check?");
+    available.forEach((def, i) => {
+        console.log(`  ${i + 1}) ${displaySentence(def)}`);
+        console.log(`     ${def.description}`);
+        console.log(`     needs: ${SUBSTRATE_HELP[def.substrate] ?? def.substrate}`);
+        console.log("");
+    });
+    const answer = await seams.ask("> ");
+    const index = Number.parseInt(answer, 10);
+    const picked = Number.isInteger(index) ? available[index - 1] : undefined;
+    if (!picked) {
+        console.error(`"${answer}" is not one of 1-${available.length}.`);
+        process.exitCode = 2;
+        return undefined;
+    }
+    return picked;
+}
+async function promptArgs(def, seams) {
+    const args = {};
+    for (const name of templateSlots(def.template).params) {
+        const type = def.params[name];
+        // The example, never the pattern. A regex source is not a prompt.
+        const valid = new RegExp(`^${type.pattern}$`);
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            const value = await seams.ask(`${name}  (e.g. ${type.example})\n> `);
+            if (valid.test(value)) {
+                args[name] = value;
+                break;
+            }
+            console.error(`  not a valid ${name} — it should look like ${type.example}`);
+        }
+        if (args[name] === undefined)
+            return { error: `Gave up on \`${name}\` after three tries.` };
+    }
+    return args;
+}
+export async function runChecksAddCommand(file, opts) {
+    let source;
+    try {
+        source = await readFile(file, "utf8");
+    }
+    catch {
+        console.error(`Could not read ${file}.`);
+        process.exitCode = 2;
+        return;
+    }
+    const seams = resolveSeams(opts);
+    let picked;
+    if (opts.check) {
+        picked = findCheck(opts.check);
+        if (!picked) {
+            console.error(`Unknown check "${opts.check}". Run \`pome checks <twin>\` to see the declared set; ` +
+                `github declares: ${checksFor("github")
+                    .map((c) => c.id)
+                    .join(", ")}.`);
+            process.exitCode = 2;
+            return;
+        }
+    }
+    else {
+        picked = await pickInteractively(source, seams);
+        if (!picked)
+            return; // already reported why
+    }
+    const parsed = opts.check ? parseArgFlags(opts.arg) : await promptArgs(picked, seams);
+    if ("error" in parsed) {
+        console.error(parsed.error);
+        process.exitCode = 2;
+        return;
+    }
+    const args = parsed;
+    const slots = templateSlots(picked.template).params;
+    for (const name of slots) {
+        const type = picked.params[name];
+        const value = args[name];
+        if (value === undefined) {
+            console.error(`${picked.id} needs a \`${name}\` — add \`--arg ${name}=${type.example}\`.`);
+            process.exitCode = 2;
+            return;
+        }
+        if (!new RegExp(`^${type.pattern}$`).test(value)) {
+            console.error(`\`${name}\` = ${JSON.stringify(value)} is not valid for ${picked.id}. ` +
+                `Example: ${type.example}`);
+            process.exitCode = 2;
+            return;
+        }
+    }
+    const extra = Object.keys(args).filter((key) => !slots.includes(key));
+    if (extra.length > 0) {
+        console.error(`${picked.id} does not declare: ${extra.join(", ")}. It takes: ${slots.join(", ")}.`);
+        process.exitCode = 2;
+        return;
+    }
+    const twin = twinOf(picked.id);
+    const fetchRemote = opts.fetchRemote ??
+        (async (t) => liveFetch(await resolveCredentials({
+            apiBaseUrl: opts.apiBaseUrl,
+            credentialsPath: opts.credentialsPath,
+        }), t));
+    const gate = await handshake(twin, fetchRemote);
+    if (gate.kind === "skew") {
+        console.error(gate.message);
+        process.exitCode = 2;
+        return;
+    }
+    if (gate.kind === "unverified")
+        console.error(gate.note);
+    const tagged = readConfigTwins(source).length > 1;
+    const line = `- [code${tagged ? `:${twin}` : ""}] ${renderCheck(picked, args)}`;
+    if (!opts.check) {
+        console.log("");
+        console.log("Appending to ## Success Criteria:");
+        console.log("");
+        console.log(`  ${line}`);
+        console.log("");
+        if (!(await seams.confirm(`Write it? ${line} [Y/n] `))) {
+            console.log("Nothing written.");
+            return;
+        }
+    }
+    let next;
+    try {
+        next = insertCriterion(source, line, file);
+    }
+    catch (err) {
+        if (err instanceof MissingCriteriaSectionError || err instanceof DuplicateCriterionError) {
+            console.error(err.message);
+            process.exitCode = 2;
+            return;
+        }
+        throw err;
+    }
+    await writeFile(file, next, "utf8");
+    console.log(`Wrote ${file}:`);
+    console.log(`  ${line}`);
+    console.log(picked.polarity(args) === "negative"
+        ? "  negative — this should PASS on an untouched seed; only the examinee can break it."
+        : "  positive — this should FAIL on an untouched seed; the examinee has to make it true.");
+}

package/dist/src/cli/checks.d.ts

@@ -0,0 +1,21 @@
+import { type CheckDefinition } from "@pome-sh/sdk/checks";
+export type DeclaredCheck = CheckDefinition<unknown, Record<string, string>>;
+export declare function twinsWithChecks(): string[];
+export declare function checksFor(twin: string): readonly DeclaredCheck[];
+export declare function findCheck(id: string): DeclaredCheck | undefined;
+export declare function twinOf(id: string): string | undefined;
+export declare function isKnownTwin(twin: string): boolean;
+/** `` No new labels were created in `<repo>` `` — every slot shown as its own
+ *  name. Derived from the template, so no `title` field has to exist. */
+export declare function displaySentence(def: DeclaredCheck): string;
+export declare function localDigest(twin: string): string;
+/** Read the pin from OUR OWN manifest. The twin's exports map sends
+ *  `./package.json` through its `"./*"` wildcard and fails to resolve — and the
+ *  pin we control is the one that matters anyway. */
+export declare function pinnedVersion(pkg: string): string;
+export declare const SUBSTRATE_HELP: Record<string, string>;
+export declare function argFlagsFor(def: DeclaredCheck): string;
+export interface ChecksCommandOptions {
+    json?: boolean;
+}
+export declare function runChecksCommand(twinArg: string | undefined, opts: ChecksCommandOptions): Promise<void>;

package/dist/src/cli/checks.js

@@ -0,0 +1,150 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * `pome checks` — the assertable vocabulary a twin declares.
+ *
+ * Discovery is offline, like `pome tasks`: the declaration comes from the twin
+ * package this CLI is pinned to. That is a SECOND resolution point (pome-cloud's
+ * `resolveDeclaredChecks` is the first), accepted so authoring works without a
+ * network, and gated by the digest handshake in `checks-add.ts` — which refuses
+ * to write a sentence when the two pins disagree.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { checksDigest, templateSlots } from "@pome-sh/sdk/checks";
+import { GITHUB_CHECKS } from "@pome-sh/twin-github/checks";
+import { resolvePackageRoot } from "./resolve-package-root.js";
+const REGISTRIES = {
+    github: GITHUB_CHECKS,
+};
+// Twins that EXIST but declare nothing yet. Listed separately so `pome checks
+// slack` answers "not migrated yet" instead of "no such twin" — a typo and an
+// empty vocabulary are different facts.
+const TWINS_WITHOUT_CHECKS = ["slack", "stripe", "gmail", "linear"];
+export function twinsWithChecks() {
+    return Object.keys(REGISTRIES).sort();
+}
+export function checksFor(twin) {
+    return REGISTRIES[twin] ?? [];
+}
+export function findCheck(id) {
+    for (const checks of Object.values(REGISTRIES)) {
+        const hit = checks.find((check) => check.id === id);
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
+export function twinOf(id) {
+    for (const [twin, checks] of Object.entries(REGISTRIES)) {
+        if (checks.some((check) => check.id === id))
+            return twin;
+    }
+    return undefined;
+}
+export function isKnownTwin(twin) {
+    return twinsWithChecks().includes(twin) || TWINS_WITHOUT_CHECKS.includes(twin);
+}
+/** `` No new labels were created in `<repo>` `` — every slot shown as its own
+ *  name. Derived from the template, so no `title` field has to exist. */
+export function displaySentence(def) {
+    const { literals, params } = templateSlots(def.template);
+    return params.reduce((out, param, i) => `${out}<${param}>${literals[i + 1]}`, literals[0]);
+}
+export function localDigest(twin) {
+    return checksDigest(checksFor(twin));
+}
+/** Read the pin from OUR OWN manifest. The twin's exports map sends
+ *  `./package.json` through its `"./*"` wildcard and fails to resolve — and the
+ *  pin we control is the one that matters anyway. */
+export function pinnedVersion(pkg) {
+    const root = resolvePackageRoot(import.meta.url);
+    if (!root)
+        return "unknown";
+    try {
+        const manifest = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+        return manifest.dependencies?.[pkg] ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+export const SUBSTRATE_HELP = {
+    final: "the final state",
+    "seed+final": "the seed and the final state",
+    tape: "the recorded call tape",
+};
+function useColor() {
+    return Boolean(process.stdout.isTTY && !process.env.NO_COLOR);
+}
+function dim(s) {
+    return useColor() ? `\x1b[2m${s}\x1b[0m` : s;
+}
+function bold(s) {
+    return useColor() ? `\x1b[1m${s}\x1b[0m` : s;
+}
+export function argFlagsFor(def) {
+    return templateSlots(def.template)
+        .params.map((name) => `--arg ${name}=${def.params[name].example}`)
+        .join(" ");
+}
+function jsonView(twin) {
+    return {
+        twin,
+        digest: localDigest(twin),
+        checks: checksFor(twin).map((def) => ({
+            id: def.id,
+            template: def.template,
+            description: def.description,
+            substrate: def.substrate,
+            params: templateSlots(def.template).params.map((name) => ({
+                name,
+                pattern: def.params[name].pattern,
+                example: def.params[name].example,
+            })),
+        })),
+    };
+}
+export async function runChecksCommand(twinArg, opts) {
+    if (!twinArg) {
+        if (opts.json) {
+            console.log(JSON.stringify({ twins: twinsWithChecks() }, null, 2));
+            return;
+        }
+        console.log(bold("Pome checks"));
+        console.log(dim("Twins that declare an assertable vocabulary."));
+        console.log("");
+        for (const twin of twinsWithChecks()) {
+            console.log(`  ${bold(twin)} ${dim(`(${checksFor(twin).length} checks)`)}`);
+        }
+        console.log("");
+        console.log(dim("Run `pome checks <twin>` to list them."));
+        return;
+    }
+    const twin = twinArg.trim();
+    if (!isKnownTwin(twin)) {
+        console.error(`Unknown twin "${twin}". Twins that declare checks: ${twinsWithChecks().join(", ")}.`);
+        process.exitCode = 2;
+        return;
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(jsonView(twin), null, 2));
+        return;
+    }
+    const checks = checksFor(twin);
+    if (checks.length === 0) {
+        console.log(bold(`${twin} — no declared checks yet`));
+        console.log(dim(`Its vocabulary has not been migrated. Use [model] criteria for ${twin} for now.`));
+        return;
+    }
+    console.log(`${bold(`${twin} — ${checks.length} declared check${checks.length === 1 ? "" : "s"}`)} ` +
+        dim(`(@pome-sh/twin-${twin} ${pinnedVersion(`@pome-sh/twin-${twin}`)})`));
+    console.log("");
+    for (const def of checks) {
+        console.log(`  ${bold(def.id)}`);
+        console.log(`    ${displaySentence(def)}`);
+        console.log(`    ${dim(def.description)}`);
+        console.log(`    ${dim(`needs: ${SUBSTRATE_HELP[def.substrate] ?? def.substrate}`)}`);
+        console.log(`    ${dim(`pome checks add <file> --check ${def.id} ${argFlagsFor(def)}`)}`);
+        console.log("");
+    }
+}

package/dist/src/cli/compile-seeds.js

@@ -18,6 +18,17 @@ import { compileSeedHosted } from "../task/seed-compiler-hosted.js";
 import { verifySeedWithTwin } from "../task/seed-verifier.js";
 import { exitCodeFor } from "../hosted/errors.js";
 const SIDECAR_META_VERSION = 1;
+/**
+ * Sidecars written by hand rather than by the compiler mark themselves with
+ * this sentinel. It is a statement of provenance, not a cache state: the seeds
+ * that carry it encode adversarial setups (a backdoored PR, a fabricated green
+ * CI status, an exfiltration lure) that a recompile would quietly rewrite,
+ * changing what the task tests while the run still reports normally. So it
+ * outranks even `--force`; to recompile one, delete the sidecar or drop its
+ * `_meta` first.
+ */
+const HAND_AUTHORED_MARKER = "hand-authored";
+const HAND_AUTHORED_SOURCE_HASH = `sha256:${HAND_AUTHORED_MARKER}`;
 export async function runCompileSeeds(target, opts) {
     const files = await resolveTaskFiles(target ?? "tasks");
     if (files.length === 0) {
@@ -56,15 +67,20 @@ async function compileOne(taskPath, opts) {
     if (seedText.length === 0) {
         return { path: taskPath, status: "skipped-no-seed", message: "no ## Seed State section" };
     }
-    // Stripe scenarios use a different schema; v1 only supports github. Check
-    // twin first so Stripe scenarios are silently skipped without surfacing
-    // misleading "still on inline JSON" warnings.
+    // Other twins use a different schema; v1 only emits a flat github seed. Check
+    // twin first so those tasks are silently skipped without surfacing misleading
+    // "still on inline JSON" warnings.
+    //
+    // A task naming github *alongside* another twin is seeded from a per-twin
+    // envelope (`{ github: {...}, linear: {...} }`), so compiling it would replace
+    // the envelope with a github-only seed and drop the other twin's half.
     const twins = readTwinsFromConfig(markdown);
-    if (twins.length > 0 && !twins.includes("github")) {
+    const githubOnly = twins.length === 1 && twins[0] === "github";
+    if (twins.length > 0 && !githubOnly) {
         return {
             path: taskPath,
             status: "skipped-unsupported-twin",
-            message: `twins=${twins.join(",")} not supported yet`
+            message: `twins=${twins.join(",")} — only single-twin github tasks are supported yet`
         };
     }
     // Heuristic: if the section is a fenced JSON block, this scenario is still
@@ -79,6 +95,16 @@ async function compileOne(taskPath, opts) {
     }
     const sidecarPath = sidecarPathFor(taskPath);
     const proseHash = hashProse(seedText);
+    // Checked ahead of `--force` and ahead of the cache: this is authorship, not
+    // staleness. The sentinel can never equal a real sha256, so without this the
+    // cache always misses and the hand-authored seed is silently overwritten.
+    if (existsSync(sidecarPath) && (await isHandAuthored(sidecarPath))) {
+        return {
+            path: taskPath,
+            status: "skipped-hand-authored",
+            message: `hand-authored seed left untouched (${sidecarPath}) — delete it or drop its _meta to recompile`
+        };
+    }
     // Cache check only applies to local compile — hosted callers may have
     // different model versions than the locally-pinned COMPILER_MODEL, and the
     // cloud has its own edge cache to avoid duplicate work anyway.
@@ -186,6 +212,24 @@ async function readSidecarMeta(path) {
         return null;
     }
 }
+/**
+ * Deliberately more lenient than `sidecarMetaSchema`: a hand-edited sidecar may
+ * carry only the sentinel and omit `version`/`compiled_at`. Failing that parse
+ * would fall through to a recompile — the exact overwrite this guards against —
+ * so any `_meta` bearing either sentinel field counts.
+ */
+async function isHandAuthored(path) {
+    try {
+        const raw = await readFile(path, "utf8");
+        const meta = JSON.parse(raw)._meta;
+        if (!meta)
+            return false;
+        return meta.model === HAND_AUTHORED_MARKER || meta.source_hash === HAND_AUTHORED_SOURCE_HASH;
+    }
+    catch {
+        return false;
+    }
+}
 async function resolveTaskFiles(target) {
     const abs = resolve(target);
     if (!existsSync(abs))
@@ -202,6 +246,8 @@ function statusStamp(status) {
             return "OK  ";
         case "skipped-cached":
             return "skip";
+        case "skipped-hand-authored":
+            return "keep";
         case "skipped-no-seed":
             return "skip";
         case "skipped-unsupported-twin":