@kontourai/flow-agents 3.3.0 → 3.4.1

package/build/src/cli/skill-drift-check.js

@@ -0,0 +1,165 @@
+import { createRequire } from "node:module";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs, flagBool, flagString } from "../lib/args.js";
+import { skillsManifestPath } from "../lib/local-artifact-root.js";
+import { root } from "../tools/common.js";
+import { globalDest, ensureBundle } from "./init.js";
+const REFRESH_COMMAND_LINE = "Run `flow-agents init --runtime claude-code --global` to refresh drifted or missing skill copies " +
+    "(user-modified files are reported here, not overwritten — review them before refreshing).";
+function usage() {
+    console.log(`usage: flow-agents skill-drift-check [options]
+
+Read-only comparison of installed Claude Code skill files against the current
+kit/bundle source and the last-recorded install manifest. Never writes under
+the installed skills directory or the kit source directory.
+
+Options:
+  --dest PATH             Installed Claude Code global destination (contains
+                           skills/ and .flow-agents/skills-manifest.json).
+                           Defaults to the global claude-code destination
+                           (honors FLOW_AGENTS_USER_CLAUDE_SETTINGS).
+  --kit-source-dir PATH   Kit/bundle skills source directory to compare
+                           against. Defaults to the current built bundle's
+                           .claude/skills directory.
+  --json                  Emit the machine-readable drift report as JSON.
+  --help, -h              Show this help.
+
+Exit codes:
+  0   Clean — every checked file is in_sync, no unbaselined/missing entries.
+  1   Drift found — at least one file is not in_sync (kit_updated,
+      user_modified, unbaselined, missing_install, or kit_removed).
+  2   Cannot fully check — no manifest exists yet, or <dest>/skills is
+      missing. Reported with guidance, not a stack trace.
+`);
+}
+function loadSkillDriftLib() {
+    const skillDriftLibPath = path.join(root, "scripts", "hooks", "lib", "skill-drift.js");
+    const _require = createRequire(import.meta.url);
+    return _require(skillDriftLibPath);
+}
+function printStatePaths(report, state, label) {
+    const paths = report.files.filter((entry) => entry.state === state).map((entry) => entry.path);
+    if (!paths.length)
+        return;
+    console.log(`  ${label}:`);
+    for (const p of paths)
+        console.log(`    - ${p}`);
+}
+function printReport(report) {
+    const s = report.summary;
+    console.log(`Skill drift check: ${report.installedDir}`);
+    console.log(`  kit source: ${report.kitSourceDir}`);
+    console.log(`  manifest found: ${report.manifestFound ? "yes" : "no"}`);
+    console.log(`  total ${s.total} — in_sync ${s.inSync}, kit_updated ${s.kitUpdated}, user_modified ${s.userModified}, ` +
+        `unbaselined ${s.unbaselined}, missing_install ${s.missingInstall}, kit_removed ${s.kitRemoved}`);
+    printStatePaths(report, "kit_updated", "kit_updated (installed matches last recorded baseline; kit source has changed)");
+    printStatePaths(report, "user_modified", "user_modified (installed bytes changed locally since last recorded install)");
+    printStatePaths(report, "unbaselined", "unbaselined (no recorded baseline for this file yet)");
+    printStatePaths(report, "missing_install", "missing_install (present in kit source, not installed yet)");
+    printStatePaths(report, "kit_removed", "kit_removed (installed file no longer present in current kit source)");
+    if (report.hasDrift) {
+        console.log("");
+        console.log(REFRESH_COMMAND_LINE);
+    }
+    else {
+        console.log("");
+        console.log("All installed skill files are in sync with the current kit source.");
+    }
+    if (s.kitRemoved > 0) {
+        console.log("");
+        console.log("kit_removed files were removed from the current kit source; refresh will NOT delete them " +
+            "— review and remove them manually if appropriate.");
+    }
+}
+export async function main(argv = process.argv.slice(2)) {
+    // Whole-body error containment (#439 review fix): any unexpected error (a bug in this CLI, a
+    // filesystem error not already handled below, etc.) must never surface as a raw stack trace to
+    // the user — print one stderr line and exit 2 ("cannot fully check"), same exit code already
+    // used for the other known cannot-check conditions below.
+    try {
+        const args = parseArgs(argv);
+        if (flagBool(args.flags, "help") || flagBool(args.flags, "h")) {
+            usage();
+            return 0;
+        }
+        const dest = path.resolve(flagString(args.flags, "dest") ?? globalDest("claude-code"));
+        const installedDir = path.join(dest, "skills");
+        let kitSourceDir;
+        const kitSourceOverride = flagString(args.flags, "kit-source-dir");
+        if (kitSourceOverride) {
+            kitSourceDir = path.resolve(kitSourceOverride);
+        }
+        else {
+            try {
+                kitSourceDir = path.join(ensureBundle("claude-code"), ".claude", "skills");
+            }
+            catch (error) {
+                console.error(`flow-agents skill-drift-check: could not resolve current kit source: ${error.message}`);
+                console.error("Pass --kit-source-dir explicitly, or build the bundle first.");
+                return 2;
+            }
+        }
+        const { loadManifest, compareSkillDrift } = loadSkillDriftLib();
+        const manifestPath = skillsManifestPath(dest);
+        const manifest = loadManifest(manifestPath);
+        const installedDirExists = fs.existsSync(installedDir);
+        // Cannot fully check when there is no recorded baseline manifest at all yet, OR the installed
+        // skills directory itself does not exist — reported explicitly with guidance, never silently
+        // mis-reported as in_sync and never a stack trace (plan's exit-code-2 contract; see also the
+        // "drifted-but-never-manifested install" stop-short risk).
+        if (!manifest || !installedDirExists) {
+            const reasons = [];
+            if (!manifest)
+                reasons.push(`no manifest found at ${manifestPath}`);
+            if (!installedDirExists)
+                reasons.push(`installed skills directory does not exist at ${installedDir}`);
+            if (flagBool(args.flags, "json")) {
+                console.log(JSON.stringify({ ok: false, reason: reasons.join("; "), manifestFound: Boolean(manifest), installedDirExists, manifestPath, installedDir, kitSourceDir }, null, 2));
+            }
+            else {
+                console.error(`flow-agents skill-drift-check: cannot fully check — ${reasons.join("; ")}.`);
+                console.error("Run this once to establish or refresh a baseline, then re-run skill-drift-check:");
+                console.error(REFRESH_COMMAND_LINE);
+            }
+            return 2;
+        }
+        const report = compareSkillDrift({ installedDir, kitSourceDir, manifest });
+        if (flagBool(args.flags, "json")) {
+            console.log(JSON.stringify(report, null, 2));
+        }
+        else {
+            printReport(report);
+        }
+        // Exit 1 iff any file is not in_sync — kit_updated, user_modified, unbaselined,
+        // missing_install, and kit_removed are ALL drift (plan's five/six-state exit-code contract;
+        // previously only kit_updated/user_modified tripped this, silently exiting 0 for
+        // unbaselined/missing_install/kit_removed despite printing drift guidance).
+        if (report.hasDrift)
+            return 1;
+        return 0;
+    }
+    catch (error) {
+        console.error(`flow-agents skill-drift-check: unexpected error: ${error.message}`);
+        return 2;
+    }
+}
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try {
+    return fs.realpathSync(fileURLToPath(import.meta.url));
+}
+catch {
+    return fileURLToPath(import.meta.url);
+} })();
+const _argv1RealPath = (() => { try {
+    return fs.realpathSync(process.argv[1]);
+}
+catch {
+    return process.argv[1];
+} })();
+if (_selfRealPath === _argv1RealPath) {
+    main().then((code) => { process.exitCode = code; }).catch((err) => { console.error(err); process.exitCode = 1; });
+}

package/build/src/cli/telemetry-doctor.d.ts

@@ -1 +1,38 @@
+type Reachability = {
+    checked: boolean;
+    ok: boolean | null;
+    statusCode?: number;
+    error?: string;
+};
+export type DoctorReport = {
+    ok: boolean;
+    destination: string;
+    telemetry: {
+        configFile: string;
+        configExists: boolean;
+        enabled: boolean;
+        dataDir: string;
+        sessionDir: string;
+        channels: Array<{
+            name: string;
+            logFile?: string;
+            endpointUrl?: string;
+            active: boolean;
+        }>;
+        activeSinks: string[];
+    };
+    console: {
+        sink: "local-only" | "console";
+        url?: string;
+        endpointUrl?: string;
+        endpointAllowed: boolean;
+        tokenConfigured: boolean;
+        tenantConfigured: boolean;
+        reachability: Reachability;
+    };
+    warnings: string[];
+};
+export declare function endpointAllowed(endpointUrl: string, allowNetwork?: boolean): boolean;
+export declare function buildReport(argv: string[]): Promise<DoctorReport>;
 export declare function main(argv?: string[]): Promise<number>;
+export {};

package/build/src/cli/telemetry-doctor.js

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as http from "node:http";
 import * as https from "node:https";
+import * as os from "node:os";
 import * as path from "node:path";
 import { parseArgs, flagBool, flagString } from "../lib/args.js";
 import { telemetryDataDir as defaultTelemetryDataDir } from "../lib/local-artifact-root.js";
@@ -61,7 +62,18 @@ function deriveConsoleEndpoint(consoleUrl, explicitEndpoint) {
         return `${base}/records`;
     return `${base}/api/telemetry/records`;
 }
-function endpointAllowed(endpointUrl, allowNetwork = false) {
+// The one known hosted Kontour Console host is reachability-checkable by
+// default (no --allow-network): reuses the exact override knob
+// scripts/telemetry/console-presets.sh already defines
+// (FLOW_AGENTS_KONTOUR_CLOUD_CONSOLE_URL / https://console.kontourai.io), so
+// it self-corrects if that default ever changes rather than drifting via a
+// second hardcoded literal. Scoped to this one hostname only -- a generic
+// non-local HTTPS endpoint still requires --allow-network exactly as today.
+function isKnownHostedConsoleHostname(hostname) {
+    const hostedUrl = parseUrl(process.env["FLOW_AGENTS_KONTOUR_CLOUD_CONSOLE_URL"] ?? "https://console.kontourai.io");
+    return hostedUrl !== null && hostname === hostedUrl.hostname;
+}
+export function endpointAllowed(endpointUrl, allowNetwork = false) {
     if (!endpointUrl || endpointUrl.includes("\n") || endpointUrl.includes("\r") || endpointUrl.includes('"'))
         return false;
     const url = parseUrl(endpointUrl);
@@ -70,7 +82,7 @@ function endpointAllowed(endpointUrl, allowNetwork = false) {
     if (url.username || url.password)
         return false;
     if (url.protocol === "https:")
-        return allowNetwork || isLocalHostname(url.hostname);
+        return allowNetwork || isLocalHostname(url.hostname) || isKnownHostedConsoleHostname(url.hostname);
     return url.protocol === "http:" && isLocalHostname(url.hostname);
 }
 function activeSinks(enabled, channels, consoleEndpoint, allowed) {
@@ -126,6 +138,31 @@ function parseUrl(value) {
 function isLocalHostname(hostname) {
     return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1" || hostname.endsWith(".localhost");
 }
+// TS mirror of scripts/telemetry/lib/config.sh's telemetry_conf_trusted
+// (mode-600 + owner-uid + no-symlink gate). Used only to WARN that a
+// candidate telemetry-console.conf exists but would be silently ignored by
+// the real bash runtime pipeline -- this doctor still reads the shipped
+// scripts/telemetry/telemetry.conf default for its own report (accepted,
+// explicitly out-of-scope gap; see install-flow-foundations plan Thread C).
+// Symlink-then-existence guard order mirrors console-learning-projection.ts
+// and workflow-sidecar.ts's existing lstatSync-before-statSync precedent.
+function isConfTrusted(file) {
+    try {
+        if (fs.lstatSync(file).isSymbolicLink())
+            return false;
+        const stat = fs.statSync(file);
+        if (!stat.isFile())
+            return false;
+        if ((stat.mode & 0o777) !== 0o600)
+            return false;
+        if (typeof process.getuid === "function" && stat.uid !== process.getuid())
+            return false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function safeReportUrl(value) {
     if (!value)
         return undefined;
@@ -140,7 +177,7 @@ function safeReportUrl(value) {
     }
     return parsed.toString();
 }
-async function buildReport(argv) {
+export async function buildReport(argv) {
     const args = parseArgs(argv);
     const allowNetwork = flagBool(args.flags, "allow-network");
     const dest = path.resolve(flagString(args.flags, "dest", process.cwd()) ?? process.cwd());
@@ -163,7 +200,7 @@ async function buildReport(argv) {
     const allowed = endpointAllowed(endpointUrl, allowNetwork);
     const timeoutMs = Number.parseInt(flagString(args.flags, "timeout-ms", "2000") ?? "2000", 10);
     const reachability = await checkConsoleReachability(endpointUrl, Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 2000, allowNetwork);
-    const warnings = reportWarnings(configFile, endpointUrl, allowed, allowNetwork);
+    const warnings = reportWarnings(configFile, endpointUrl, allowed, allowNetwork, dest);
     return {
         ok: enabled && (!endpointUrl || (allowed && reachability.ok !== false)),
         destination: dest,
@@ -188,12 +225,22 @@ async function buildReport(argv) {
         warnings,
     };
 }
-function reportWarnings(configFile, endpointUrl, allowed, allowNetwork) {
+function reportWarnings(configFile, endpointUrl, allowed, allowNetwork, dest) {
     const warnings = [];
     if (!fs.existsSync(configFile))
         warnings.push("telemetry.conf was not found under destination scripts/telemetry");
     if (endpointUrl && !allowed)
-        warnings.push(allowNetwork ? "Console endpoint is malformed or contains credentials" : "Console endpoint is not allowed without --allow-network; local http(s) endpoints are allowed by default");
+        warnings.push(allowNetwork ? "Console endpoint is malformed or contains credentials" : "Console endpoint is not allowed without --allow-network; local http(s) endpoints and the known hosted Console host are allowed by default");
+    // Mirrors config.sh's local-before-global precedence for the warning only
+    // (see isConfTrusted's doc comment for the accepted config-resolution-parity gap).
+    const localConf = path.join(dest, ".kontourai", "telemetry-console.conf");
+    const globalConf = path.join(os.homedir(), ".flow-agents", "telemetry-console.conf");
+    if (fs.existsSync(localConf) && !isConfTrusted(localConf)) {
+        warnings.push(`Untrusted telemetry console conf at ${localConf} (must be mode 600, owned by the current user, and not a symlink); it is being ignored and telemetry stays fail-open`);
+    }
+    else if (fs.existsSync(globalConf) && !isConfTrusted(globalConf)) {
+        warnings.push(`Untrusted telemetry console conf at ${globalConf} (must be mode 600, owned by the current user, and not a symlink); it is being ignored and telemetry stays fail-open`);
+    }
     return warnings;
 }
 function printText(report) {

package/build/src/cli/validate-hook-influence.js

@@ -1,18 +1,47 @@
 import * as fs from "node:fs";
 import { fileURLToPath } from "node:url";
+import { readKitInventory } from "../runtime-adapters.js";
+import { root } from "../tools/common.js";
 const validTiers = new Set(["adapter", "design-target", "installed-command", "live-acceptance", "documented-runtime-gap"]);
 const validRuntimes = new Set(["codex", "claude-code", "kiro-cli"]);
 const validHooks = new Set(["workflow-steering", "stop-goal-fit"]);
 const validEvents = new Set(["UserPromptSubmit", "PostToolUse", "Stop"]);
-const requiredCases = {
-    "dev-builder-build-requires-pickup-probe-before-plan": { description: "missing pickup Probe before plan", tier: "design-target", must_include: ["design-probe", "accepted gaps", "provider_state", "conflict_risks"], agent_must_do: ["route decision_gap back to design-probe/pickup Probe"] },
-    "dev-builder-review-before-verify-after-execute": { description: "review-before-verify after execute", tier: "adapter", event: "PostToolUse", must_include: ["Next: review", "then verify", "report only"], agent_must_do: ["review-work for report-only critique before verify-work", "not count critique.json as verification evidence"] },
-    "dev-builder-route-fresh-coding-prompt": { description: "fresh coding prompt routes into Builder workflow", tier: "adapter", event: "UserPromptSubmit", must_include: ["BUILDER WORKFLOW ROUTE", "activate `deliver`", "--flow-id builder.build", "plan-work -> execute-plan -> review-work -> verify-work", "publish/release-readiness and learning-review"], agent_must_do: ["activate Builder Kit delivery workflow before source edits", "use deliver by default for coding/build work", "do not bypass plan-work -> execute-plan -> review-work -> verify-work", "publish, release readiness, and learning feedback"] },
+const engineRequiredCases = {
     "dev-verify-fail-preserves-trace-before-rework": { description: "verify failure route-back with preserved FAIL evidence", tier: "design-target", must_include: ["If verdict=FAIL: record the FAIL artifact"], agent_must_do: ["write the FAIL artifact before routing back", "route to plan"] },
     "codex-claude-strict-stop-adapter-contract": { description: "Goal Fit stop adapter behavior", tier: "adapter", hook: "stop-goal-fit", event: "Stop", must_include: ["Goal Fit warning"], agent_must_do: ["treat strict Stop guidance as a blocker"] },
     "codex-live-context-gap": { description: "Codex documented runtime gap", tier: "documented-runtime-gap", must_include: ["STATE:", "not_verified"], agent_must_do: ["record NOT_VERIFIED for live influence"] },
     "installed-command-protocol-guidance": { description: "installed-command evidence lane", tier: "installed-command", must_include: ["STATE:", "CRITIQUE:", "CONTEXT MAP:"], agent_must_do: ["treat hook guidance as additional context"] },
 };
+function requiredCases() {
+    const dest = process.env.FLOW_AGENTS_HOOK_INFLUENCE_DEST ?? root;
+    const sourceRoot = process.env.FLOW_AGENTS_HOOK_INFLUENCE_SOURCE_ROOT ?? root;
+    const inventory = readKitInventory(sourceRoot, dest);
+    if (inventory.errors.length) {
+        fail(`kit hook influence metadata is invalid:\n${inventory.errors.join("\n")}`);
+    }
+    const kitCases = {};
+    for (const expectation of inventory.hook_influence_expectations) {
+        const namespacedId = `kit:${expectation.kit_id}:${expectation.id}`;
+        if (engineRequiredCases[expectation.id]) {
+            fail(`${expectation.kit_id}: hook influence expectation id collides with engine-required case id: ${expectation.id}`);
+        }
+        if (engineRequiredCases[namespacedId]) {
+            fail(`${expectation.kit_id}: namespaced hook influence expectation id collides with engine-required case id: ${namespacedId}`);
+        }
+        if (kitCases[namespacedId]) {
+            fail(`${expectation.kit_id}: duplicate namespaced hook influence expectation id: ${namespacedId}`);
+        }
+        kitCases[namespacedId] = {
+            description: expectation.description,
+            tier: expectation.tier,
+            ...(expectation.hook ? { hook: expectation.hook } : {}),
+            ...(expectation.event ? { event: expectation.event } : {}),
+            must_include: expectation.must_include_guidance,
+            agent_must_do: expectation.must_include_actions,
+        };
+    }
+    return { ...engineRequiredCases, ...kitCases };
+}
 function fail(message) {
     throw new Error(message);
 }
@@ -65,6 +94,7 @@ function validateEvidenceCommand(caseId, runtimes, evidence) {
 export function main(argv = process.argv.slice(2)) {
     try {
         const file = argv[0] ?? "evals/fixtures/hook-influence/cases.json";
+        const required = requiredCases();
         const data = JSON.parse(fs.readFileSync(file, "utf8"));
         if (data.schema_version !== "1.0")
             fail("schema_version must be 1.0");
@@ -108,7 +138,7 @@ export function main(argv = process.argv.slice(2)) {
             ["command", "status"].forEach((key) => { if (typeof evidence[key] !== "string" || !String(evidence[key]).trim())
                 fail(`${caseId}: evidence.${key} must be a non-empty string`); });
             validateEvidenceCommand(caseId, runtimes, evidence);
-            const req = requiredCases[caseId];
+            const req = required[caseId];
             if (req) {
                 if (tier !== req.tier)
                     fail(`${caseId}: ${req.description} must use ${req.tier} evidence tier`);
@@ -132,9 +162,9 @@ export function main(argv = process.argv.slice(2)) {
         for (const tier of ["adapter", "installed-command", "live-acceptance", "documented-runtime-gap"])
             if (!byTier.has(tier))
                 fail(`missing required #62 evidence tier(s): ${tier}`);
-        for (const id of Object.keys(requiredCases))
+        for (const id of Object.keys(required))
             if (!casesById.has(id))
-                fail(`missing required #62 case for ${requiredCases[id].description}: ${id}`);
+                fail(`missing required #62 case for ${required[id].description}: ${id}`);
         const codexGap = casesById.get("codex-live-context-gap");
         const codexRuntimes = codexGap.runtime_scope;
         const codexEvidence = codexGap.evidence;

package/build/src/cli/workflow-sidecar.d.ts

@@ -133,6 +133,36 @@ type SurfaceModule = {
         assuranceLevel: "signed";
     } | null>;
 };
+/**
+ * Fold a raw command-log (command-log.jsonl entries) into a per-command classification,
+ * keyed by normalized command text (whitespace-collapsed, trimmed). Pure and side-effect-free
+ * so it is directly unit-testable (#470 iteration 2, finding #2 — HIGH: the prior inline reducer
+ * collapsed every non-"fail" `observedResult` — including "ambiguous" — to "pass", feeding a
+ * verified event + `passing:true` and reintroducing the #470 false-pass through the trust-bundle
+ * reconciliation path).
+ *
+ * Three-way classification, keyed on `observedResult` (never re-derived from `exitCode` alone,
+ * which would miscoerce the #362 grep/diff absence carve-out `ambiguous,exitCode:1` entry to
+ * `fail`):
+ *   - "fail"      when `observedResult==="fail"`, or (legacy, no observedResult) a nonzero
+ *                 integer `exitCode`.
+ *   - "ambiguous" when `observedResult==="ambiguous"`, or (legacy) `exitCode` is `null` with no
+ *                 fail signal.
+ *   - "pass"      when `observedResult==="pass"`, or (legacy) `exitCode===0`.
+ *
+ * Precedence across repeated entries for the same command: fail > pass > ambiguous. A genuine
+ * exit-0 pass is positive evidence and confirms; ambiguous holds only when there is neither a
+ * fail nor a positive pass, since a "pass" always requires positive evidence.
+ *
+ * The caller (buildTrustBundle) maps "ambiguous" onto the existing canonical non-confirming
+ * status `not_verified` — consume-never-fork, mirroring record-check's identical mapping — so
+ * `checkStatusToEventStatus("not_verified")` returns null (no verification event emitted) and the
+ * evidence item is stamped `passing:false`. See Decision/finding #2 in the iteration-2 plan.
+ */
+export declare function reduceCaptureLogByCommand(commandLog: AnyObj[] | undefined): Map<string, {
+    observedResult: "pass" | "fail" | "ambiguous";
+    exitCode: number | null;
+}>;
 /**
  * Build a Hachure trust.bundle from raw check/criterion/critique inputs.
  * trust.bundle is the PRIMARY artifact (ADR 0010 Phase 4a producer inversion).
@@ -167,7 +197,7 @@ export declare function writeTrustBundle(dir: string, slug: string, timestamp: s
 export declare function sidecarBase(slug: string): AnyObj;
 export declare function validateEvidenceRef(ref: AnyObj, label: string): AnyObj;
 export declare function normalizeEvidenceRefs(raw: unknown, label: string): AnyObj[];
-export declare function normalizeCheck(raw: AnyObj): AnyObj;
+export declare function normalizeCheck(raw: AnyObj, allowGateClaimPrefix?: boolean, existingCheckStampById?: ReadonlyMap<string, boolean>): AnyObj;
 /**
  * Derive kit identity from a parsed trust.bundle by structurally reading the
  * DECLARED primary claim (kit-typed) rather than hardcoding "builder".
@@ -252,6 +282,34 @@ export declare class NotFreshHolderError extends Error {
         guidance: string[];
     });
 }
+/**
+ * Distinct, identifiable error for a publish attempt whose resolved `repoRoot` does not
+ * positively confirm the session's sealed `trust.checkpoint.json` `commit_sha` — a FOURTH,
+ * distinct fail-closed tier (#413 Facet A), never conflated with `InvalidBundleShapeError`
+ * (bundle shape) or `NotFreshHolderError` (actor hold). This is the "refuse loudly when the cwd
+ * repo does not match the sealed checkpoint commit_sha" fallback the issue itself proposed:
+ * `publishDelivery`'s `repoRoot` is resolved by walking up from the ARTIFACT directory
+ * (findRepoRootFromDirStrict), which always physically lives under the primary checkout even
+ * when invoked from an unrelated worktree/repo — so a positively-confirmed mismatch here is the
+ * signal that this resolved repoRoot is NOT the repo the sealed checkpoint was produced against,
+ * and publishing into it would silently write to the wrong tree.
+ *
+ * #413 iteration-2 Fix 4: thrown for the ONE positively-determinable `mismatchKind` (see
+ * checkpointHeadAncestry's doc comment) — `"positive"` (repoRoot's HEAD is confirmed NOT an
+ * ancestor-or-equal of commit_sha; `headSha` is a real sha). It is intentionally NEVER thrown for
+ * `"undeterminable-shallow"` (e.g. a shallow clone missing the commit object) — that case only
+ * warns and allows the publish (see publishDelivery's own gate). A non-git `repoRoot` classifies
+ * as `mismatchKind === "none"` (no opinion — allow; see checkpointHeadAncestry's doc comment for
+ * why the iteration-2 Fix 5 refusal here was reverted in iteration-3) and never throws this error
+ * either.
+ */
+export declare class RepoHeadMismatchError extends Error {
+    readonly code: "PUBLISH_DELIVERY_REPO_HEAD_MISMATCH";
+    readonly repoRoot: string;
+    readonly commitSha: string;
+    readonly headSha: string;
+    constructor(repoRoot: string, commitSha: string, headSha: string);
+}
 export declare function runReconcilePreflight(dir: string, repoRoot: string, manifestOverride?: string | null): {
     ok: boolean;
     issues: string[];
@@ -439,17 +497,44 @@ export declare function runTakeoverPreflight(dir: string, opts?: {
  * which stay exactly as before (see each publishDelivery call site's catch handler for how
  * the distinction is preserved end-to-end).
  *
- * #293 (SECOND, DISTINCT fail-closed gate): immediately after the shape check above and BEFORE
+ * #293 (THIRD, DISTINCT fail-closed gate): immediately after the shape check above and BEFORE
  * writing anything into delivery/, runs `runVerifyHold()` — the assignment ⋈ liveness join
  * asking "is the calling actor the fresh, non-superseded holder of this subject (or is it
  * free/self-held)?" A not-fresh-holder result throws `NotFreshHolderError` (distinct from
  * `InvalidBundleShapeError` — a different `code`, a different failure mode: actor hold vs
- * bundle shape). There are now THREE tiers here, and they must never be conflated in prose or
- * in a call site's catch handler: (1) fail-SOFT bundle absence / repo-root resolution (silent
- * no-op / visible warning, unchanged from before #356), (2) fail-CLOSED bundle shape (#356,
- * `InvalidBundleShapeError`), (3) fail-CLOSED verify-hold (#293, `NotFreshHolderError`). The
- * shape check runs first (per the plan's ordering) — a bundle that is BOTH shape-invalid and
- * not-held throws `InvalidBundleShapeError` specifically, never `NotFreshHolderError`.
+ * bundle shape).
+ *
+ * #413 Facet A (FOURTH, DISTINCT fail-closed gate): immediately after the verify-hold gate and
+ * BEFORE writing anything into delivery/, compares the resolved `repoRoot`'s `git rev-parse
+ * HEAD` against the session's sealed `trust.checkpoint.json` `commit_sha` (via the shared
+ * checkpointHeadAncestry() helper — the SAME ancestor-check checkpointStalenessWarning already
+ * used as a non-blocking warning). Throws `RepoHeadMismatchError` (distinct from both other
+ * error tiers) instead of silently publishing into what is very likely the WRONG repo (e.g.
+ * `repoRoot` resolved to the primary checkout via findRepoRootFromDirStrict's artifact-dir
+ * walk, even though this session's checkpoint was sealed against a DIFFERENT worktree's HEAD).
+ * A session with no checkpoint yet, or a checkpoint with no commit_sha, has nothing to compare
+ * against and is unaffected (scoped strictly to the mismatch case, never a spurious refusal).
+ *
+ * #413 iteration-2 Fix 4 (see checkpointHeadAncestry's own doc comment for the full
+ * `mismatchKind` classification this gate reads): only `mismatchKind === "positive"` (a
+ * POSITIVELY-DETERMINABLE ancestry mismatch — the real wrong-tree harm case) hard refuses here.
+ * `"undeterminable-shallow"` (e.g. a local shallow clone missing the commit_sha object) must
+ * NEVER hard-refuse a legitimate publish — this branch only WARNS loudly and lets the shape +
+ * verify-hold gates above continue to stand guard. A non-git `repoRoot` classifies as
+ * `mismatchKind === "none"` (allow) — iteration-2's Fix 5 hard-refused this case too, but that
+ * regressed the SUPPORTED non-git-repoRoot scratch/checkpoint-signing flow (see
+ * evals/integration/test_checkpoint_signing.sh TEST 2) and was reverted in iteration-3. Wrong-tree
+ * protection for that case relies on the shape-check and verify-hold gates above, which correctly
+ * no-op (allow) when there is no git repo to inspect, same as this gate.
+ *
+ * There are now FOUR fail-closed/fail-soft TIERS in this function, and they must never be
+ * conflated in prose or in a call site's catch handler: (1) fail-SOFT bundle absence /
+ * repo-root resolution (silent no-op / visible warning, unchanged from before #356), (2)
+ * fail-CLOSED bundle shape (#356, `InvalidBundleShapeError`), (3) fail-CLOSED verify-hold (#293,
+ * `NotFreshHolderError`), (4) fail-CLOSED repo-HEAD-vs-checkpoint mismatch (#413 Facet A,
+ * `RepoHeadMismatchError`) — see this tier's own gate below for the undeterminable-shallow
+ * carve-out. Tiers run in this fixed order (shape, then verify-hold, then HEAD-mismatch); a
+ * bundle that fails an earlier tier throws that tier's error specifically, never a later one's.
  */
 export declare function publishDelivery(dir: string, repoRoot: string | null): Promise<void>;
 export declare function validateLearningCorrection(record: AnyObj): void;