@deftai/directive-core 0.93.0 → 0.95.0

package/dist/check/consumer-gate-integrity.js

@@ -0,0 +1,265 @@
+/**
+ * Consumer check-graph integrity (#3070).
+ *
+ * CONSUMER_CHECK_GATES lists Taskfile tasks that must resolve in a vendored
+ * deposit. When optional Taskfile includes silently omit `tasks/verify.yml`
+ * (etc.), go-task fails with opaque exit 200/201 ("Task does not exist").
+ *
+ * This module:
+ *  1. Maps each gate to its include namespace / root Taskfile surface
+ *  2. Proves shipped files define those tasks (static + runtime)
+ *  3. Emits a deposit-repair recovery message instead of opaque go-task errors
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { CONSUMER_CHECK_GATES, checkGateId } from "./gate-lists.js";
+/** Include namespaces required by the consumer check graph (Taskfile includes). */
+export const CHECK_GRAPH_REQUIRED_NAMESPACES = ["verify", "toolchain", "vbrief"];
+export const CONSUMER_GATE_INTEGRITY_RECOVERY = "Incomplete Deft deposit: check-graph Taskfile include(s) missing or incomplete. " +
+    "Run `deft update` (or `npm i -g @deftai/directive@latest` then `deft update`) " +
+    "to restore `.deft/core/tasks/` (including `tasks/verify.yml` for `verify:orphan-active`). " +
+    "See UPGRADING.md.";
+/** Namespace for a namespaced task (`verify:orphan-active` → `verify`); null for root tasks. */
+export function gateNamespace(gateId) {
+    const colon = gateId.indexOf(":");
+    if (colon <= 0) {
+        return null;
+    }
+    return gateId.slice(0, colon);
+}
+/** Local task name inside an include (`verify:orphan-active` → `orphan-active`). */
+export function gateLocalName(gateId) {
+    const colon = gateId.indexOf(":");
+    if (colon <= 0) {
+        return gateId;
+    }
+    return gateId.slice(colon + 1);
+}
+/** Relative path of the include Taskfile for a namespace. */
+export function includeTaskfileRel(namespace) {
+    return `tasks/${namespace}.yml`;
+}
+/**
+ * Namespaces that CONSUMER_CHECK_GATES require via `ns:task` form.
+ * Root-only gates (doctor, verify-strategy-output) do not add a namespace.
+ */
+export function requiredNamespacesForGates(gates = CONSUMER_CHECK_GATES) {
+    const seen = new Set();
+    for (const spec of gates) {
+        const ns = gateNamespace(checkGateId(spec));
+        if (ns !== null) {
+            seen.add(ns);
+        }
+    }
+    return [...seen].sort();
+}
+/** True when `localName` is a top-level task key under a Taskfile `tasks:` section. */
+export function taskDefinedInTaskfileYaml(text, localName) {
+    // go-task task keys are indented two spaces under `tasks:`.
+    // Match `  orphan-active:` / `  check-consumer:` etc., not nested keys.
+    const escaped = localName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const re = new RegExp(`^ {2}${escaped}\\s*:`, "m");
+    return re.test(text.replace(/\r\n/g, "\n").replace(/\r/g, "\n"));
+}
+/**
+ * Parse root Taskfile `includes:` entries: map namespace → { taskfile, optional }.
+ * Minimal line parser (avoids a YAML dependency); sufficient for go-task include shape.
+ */
+export function parseTaskfileIncludes(text) {
+    const lines = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+    const result = new Map();
+    let inIncludes = false;
+    let includesIndent = 0;
+    let currentNs = null;
+    let currentTaskfile = null;
+    let currentOptional = true; // go-task default when omitted is false, but our deposit historically used true
+    const flush = () => {
+        if (currentNs !== null && currentTaskfile !== null) {
+            result.set(currentNs, { taskfile: currentTaskfile, optional: currentOptional });
+        }
+        currentNs = null;
+        currentTaskfile = null;
+        currentOptional = false;
+    };
+    for (const raw of lines) {
+        const stripped = raw.trim();
+        if (!stripped || stripped.startsWith("#")) {
+            continue;
+        }
+        const indent = raw.length - raw.trimStart().length;
+        if (!inIncludes) {
+            if (/^includes\s*:/.test(stripped) && indent === 0) {
+                inIncludes = true;
+                includesIndent = indent;
+            }
+            continue;
+        }
+        if (indent <= includesIndent && !stripped.startsWith("#")) {
+            flush();
+            inIncludes = false;
+            // fall through if a new top-level key; re-check next iteration naturally
+            if (/^includes\s*:/.test(stripped)) {
+                inIncludes = true;
+                includesIndent = indent;
+            }
+            continue;
+        }
+        // Namespace key at includes+2 (typically 2 spaces): `  verify:`
+        if (indent === includesIndent + 2 && /^[A-Za-z_][\w-]*\s*:/.test(stripped)) {
+            flush();
+            currentNs = stripped.replace(/:\s*(?:#.*)?$/, "").trim();
+            currentTaskfile = null;
+            currentOptional = false;
+            continue;
+        }
+        if (currentNs === null) {
+            continue;
+        }
+        // Properties at includes+4: taskfile / optional
+        if (indent >= includesIndent + 4) {
+            const taskfileMatch = stripped.match(/^taskfile\s*:\s*["']?([^"'#]+?)["']?\s*(?:#.*)?$/i);
+            if (taskfileMatch?.[1]) {
+                currentTaskfile = taskfileMatch[1].trim();
+                continue;
+            }
+            const optionalMatch = stripped.match(/^optional\s*:\s*(true|false)\s*(?:#.*)?$/i);
+            if (optionalMatch?.[1]) {
+                currentOptional = optionalMatch[1].toLowerCase() === "true";
+            }
+        }
+    }
+    flush();
+    return result;
+}
+/**
+ * Assert every consumer check gate resolves against `frameworkRoot` Taskfile + includes.
+ * When the root Taskfile is absent, returns ok with no findings (caller/spawn handles that).
+ */
+export function evaluateConsumerGateIntegrity(frameworkRoot, seams = {}) {
+    const root = resolve(frameworkRoot);
+    const exists = seams.exists ?? ((p) => existsSync(p));
+    const readText = seams.readText ??
+        ((p) => {
+            try {
+                if (!existsSync(p)) {
+                    return null;
+                }
+                return readFileSync(p, "utf8");
+            }
+            catch {
+                return null;
+            }
+        });
+    const gates = seams.gates ?? CONSUMER_CHECK_GATES;
+    const findings = [];
+    const rootTaskfile = join(root, "Taskfile.yml");
+    if (!exists(rootTaskfile)) {
+        // Incomplete / non-deposit path: do not invent a Taskfile; let spawn fail as before.
+        return { ok: true, findings: [], recovery: CONSUMER_GATE_INTEGRITY_RECOVERY };
+    }
+    const rootText = readText(rootTaskfile);
+    if (rootText === null) {
+        findings.push({
+            gateId: "*",
+            kind: "missing-root-taskfile",
+            detail: `Taskfile.yml unreadable at ${rootTaskfile}`,
+            expectedPath: rootTaskfile,
+        });
+        return { ok: false, findings, recovery: CONSUMER_GATE_INTEGRITY_RECOVERY };
+    }
+    const includes = parseTaskfileIncludes(rootText);
+    const yamlCache = new Map();
+    const readCached = (abs) => {
+        if (yamlCache.has(abs)) {
+            return yamlCache.get(abs) ?? null;
+        }
+        const t = readText(abs);
+        yamlCache.set(abs, t);
+        return t;
+    };
+    yamlCache.set(rootTaskfile, rootText);
+    for (const spec of gates) {
+        const gateId = checkGateId(spec);
+        const ns = gateNamespace(gateId);
+        const local = gateLocalName(gateId);
+        if (ns === null) {
+            // Root Taskfile task (doctor, verify-strategy-output, …)
+            if (!taskDefinedInTaskfileYaml(rootText, local)) {
+                findings.push({
+                    gateId,
+                    kind: "missing-task-definition",
+                    detail: `Root task "${local}" not defined in Taskfile.yml (required by consumer check gate "${gateId}")`,
+                    expectedPath: rootTaskfile,
+                });
+            }
+            continue;
+        }
+        const rel = includeTaskfileRel(ns);
+        const includeMeta = includes.get(ns);
+        const relFromInclude = includeMeta?.taskfile ? includeMeta.taskfile.replace(/^\.\//, "") : rel;
+        const includeAbs = join(root, relFromInclude);
+        if (!exists(includeAbs)) {
+            findings.push({
+                gateId,
+                kind: "missing-include-file",
+                detail: `Missing Taskfile include file for namespace "${ns}" (gate "${gateId}"): ` +
+                    `${relFromInclude}. Optional silent omit of this include causes go-task ` +
+                    `"Task \\"${gateId}\\" does not exist" (exit 200/201).`,
+                expectedPath: includeAbs,
+            });
+            continue;
+        }
+        const includeText = readCached(includeAbs);
+        if (includeText === null) {
+            findings.push({
+                gateId,
+                kind: "missing-include-file",
+                detail: `Unreadable Taskfile include for namespace "${ns}": ${relFromInclude}`,
+                expectedPath: includeAbs,
+            });
+            continue;
+        }
+        if (!taskDefinedInTaskfileYaml(includeText, local)) {
+            findings.push({
+                gateId,
+                kind: "missing-task-definition",
+                detail: `Task "${local}" not defined in ${relFromInclude} (required by consumer check gate "${gateId}")`,
+                expectedPath: includeAbs,
+            });
+        }
+    }
+    return {
+        ok: findings.length === 0,
+        findings,
+        recovery: CONSUMER_GATE_INTEGRITY_RECOVERY,
+    };
+}
+/** Format integrity failure for stderr (check orchestrator / doctor). */
+export function formatConsumerGateIntegrityFailure(result) {
+    const lines = [
+        "check: consumer gate integrity failed (#3070)",
+        ...result.findings.map((f) => `  - ${f.gateId}: ${f.detail}`),
+        `  recovery: ${result.recovery}`,
+    ];
+    return `${lines.join("\n")}\n`;
+}
+/**
+ * Namespaces that must not be `optional: true` on the root Taskfile when the
+ * check graph depends on them — silent omit is the #3070 failure mode.
+ */
+export function checkGraphOptionalIncludeViolations(rootTaskfileText, namespaces = requiredNamespacesForGates()) {
+    const includes = parseTaskfileIncludes(rootTaskfileText);
+    const bad = [];
+    for (const ns of namespaces) {
+        const meta = includes.get(ns);
+        if (meta === undefined) {
+            bad.push(`${ns} (include entry missing)`);
+            continue;
+        }
+        if (meta.optional) {
+            bad.push(`${ns} (optional: true — check-graph includes must fail loud when file is missing)`);
+        }
+    }
+    return bad;
+}
+//# sourceMappingURL=consumer-gate-integrity.js.map

package/dist/check/index.d.ts

@@ -1,4 +1,5 @@
 export { dispatchCachedTaskCheck } from "./cached-orchestrator.js";
+export { CHECK_GRAPH_REQUIRED_NAMESPACES, CONSUMER_GATE_INTEGRITY_RECOVERY, type ConsumerGateIntegrityFinding, type ConsumerGateIntegrityResult, type ConsumerGateIntegritySeams, checkGraphOptionalIncludeViolations, evaluateConsumerGateIntegrity, formatConsumerGateIntegrityFailure, gateLocalName, gateNamespace, includeTaskfileRel, parseTaskfileIncludes, requiredNamespacesForGates, taskDefinedInTaskfileYaml, } from "./consumer-gate-integrity.js";
 export { type CheckGateSpec, CONSUMER_CHECK_GATES, checkGateId, checkGateSpawnArgs, FRAMEWORK_CHECK_GATES, gatesForCheckTarget, } from "./gate-lists.js";
 export type { CheckOrchestratorOptions, CheckOrchestratorSeams } from "./orchestrator.js";
 export { dispatchTaskCheck, isFrameworkRepoRoot, isFrameworkSourceContext, resolveCheckTarget, } from "./orchestrator.js";

package/dist/check/index.js

@@ -1,4 +1,5 @@
 export { dispatchCachedTaskCheck } from "./cached-orchestrator.js";
+export { CHECK_GRAPH_REQUIRED_NAMESPACES, CONSUMER_GATE_INTEGRITY_RECOVERY, checkGraphOptionalIncludeViolations, evaluateConsumerGateIntegrity, formatConsumerGateIntegrityFailure, gateLocalName, gateNamespace, includeTaskfileRel, parseTaskfileIncludes, requiredNamespacesForGates, taskDefinedInTaskfileYaml, } from "./consumer-gate-integrity.js";
 export { CONSUMER_CHECK_GATES, checkGateId, checkGateSpawnArgs, FRAMEWORK_CHECK_GATES, gatesForCheckTarget, } from "./gate-lists.js";
 export { dispatchTaskCheck, isFrameworkRepoRoot, isFrameworkSourceContext, resolveCheckTarget, } from "./orchestrator.js";
 export { detectTestRunner, runnerDetectionTable, } from "./runner-detect.js";

package/dist/check/orchestrator.js

@@ -14,6 +14,7 @@
 import { spawnSync } from "node:child_process";
 import { join, resolve } from "node:path";
 import { dispatchCachedTaskCheck } from "./cached-orchestrator.js";
+import { evaluateConsumerGateIntegrity, formatConsumerGateIntegrityFailure, } from "./consumer-gate-integrity.js";
 import { resolveCheckTarget } from "./context.js";
 export { isFrameworkRepoRoot, isFrameworkSourceContext, resolveCheckTarget } from "./context.js";
 /**
@@ -35,6 +36,15 @@ export function dispatchTaskCheck(frameworkRoot, projectRoot, seams = {}) {
     const taskBin = seams.taskBin ?? "task";
     const target = resolveCheckTarget(resolvedFramework, resolvedProject);
     const cwd = target === "check:framework-source" ? resolvedFramework : resolvedProject;
+    // #3070: pre-flight consumer check-graph integrity (same path as cached
+    // orchestrator) so uncached aggregate shelling also fails with recovery text.
+    if (target === "check:consumer") {
+        const integrity = evaluateConsumerGateIntegrity(resolvedFramework);
+        if (!integrity.ok) {
+            process.stderr.write(formatConsumerGateIntegrityFailure(integrity));
+            return 2;
+        }
+    }
     const spawn = seams.spawnFn ?? defaultSpawn;
     const result = spawn(taskBin, [target, "--taskfile", taskfilePath], {
         cwd,

package/dist/content-contracts/skills/greptile-detector.d.ts

@@ -34,6 +34,13 @@ export declare const BODY_AC4_INLINE_SHA_CLEAN: string;
 export declare const BODY_AC4_THIRD_CONFIDENCE_FORM: string;
 export declare const BODY_AC4_EMPTY = "";
 export declare const BODY_AC4_TRUNCATED: string;
+/**
+ * Fail-closed CLEAN gate shared by pr:watch, swarm poller, and content-contracts.
+ *
+ * `minConfidence` defaults to the consumer bar (4 == legacy confidence > 3).
+ * Directive dogfood and project policy resolve a higher floor via
+ * `resolveMinGreptileConfidence` (#3095).
+ */
 export declare function evaluateCleanGate(params: {
     lastReviewedSha: string | null;
     headSha: string;
@@ -42,6 +49,8 @@ export declare function evaluateCleanGate(params: {
     ciFailures: number;
     errored: boolean;
     terminalCheckRun?: boolean;
+    /** Minimum confidence score (1–5) that CLEANs; score must be >= min. Default 4. */
+    minConfidence?: number;
 }): [boolean, string | null];
 type PollExitClass = "CLEAN" | "NEW_P0P1" | "ERRORED" | "STALL" | "RUNNING";
 export declare function simulatePollLoop(params: {

package/dist/content-contracts/skills/greptile-detector.js

@@ -277,15 +277,22 @@ export const BODY_AC4_THIRD_CONFIDENCE_FORM = "Greptile review of head 1234567\n
     `Last reviewed commit: [fix: foo](https://github.com/deftai/directive/commit/${HEAD_SHA})\n`;
 export const BODY_AC4_EMPTY = "";
 export const BODY_AC4_TRUNCATED = "Greptile review of head 1234567\n" + "\n" + "## Confidence Score:";
+/**
+ * Fail-closed CLEAN gate shared by pr:watch, swarm poller, and content-contracts.
+ *
+ * `minConfidence` defaults to the consumer bar (4 == legacy confidence > 3).
+ * Directive dogfood and project policy resolve a higher floor via
+ * `resolveMinGreptileConfidence` (#3095).
+ */
 export function evaluateCleanGate(params) {
-    const { lastReviewedSha, headSha, hasBlocking, confidence, ciFailures, errored, terminalCheckRun = true, } = params;
+    const { lastReviewedSha, headSha, hasBlocking, confidence, ciFailures, errored, terminalCheckRun = true, minConfidence = 4, } = params;
     if (lastReviewedSha === null || lastReviewedSha !== headSha) {
         return [false, "sha_match"];
     }
     if (hasBlocking) {
         return [false, "has_blocking"];
     }
-    if (confidence === null || confidence <= 3) {
+    if (confidence === null || confidence < minConfidence) {
         return [false, "confidence"];
     }
     if (ciFailures > 0) {

package/dist/doctor/main.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { VBRIEF_VERSION } from "@deftai/directive-types";
 import { evaluate as evaluateAgentsMdAdvisory } from "../agents-md-advisory/evaluate.js";
+import { evaluateConsumerGateIntegrity, formatConsumerGateIntegrityFailure, } from "../check/consumer-gate-integrity.js";
 import { contentRoot } from "../content-root.js";
 import { resolveProjectDefinitionPath } from "../layout/resolve.js";
 import { DEFT_DIRECTIVE_DISABLE_FLAG_NAME, DEFT_DIRECTIVE_DISABLE_STATUS, DEFT_DIRECTIVE_DISABLE_TRACKED_WARNING, detectDeftDirectiveDisable, formatDeftDirectiveDisableMessage, isDeftDirectiveDisableActive, } from "../policy/deft-directive-disable.js";
@@ -389,6 +390,11 @@ export function cmdDoctor(args, seams = {}) {
     if (!jsonMode) {
         sink.blank();
     }
+    sink.info("Checking consumer check-graph integrity (verify:orphan-active and peers)...");
+    runConsumerCheckGraphIntegrity(projectRoot, frameworkRoot, sink, addFinding, seams);
+    if (!jsonMode) {
+        sink.blank();
+    }
     sink.info("Checking OpenClaw always-pin skills...");
     runOpenClawSkillPinsCheck(sink, addFinding, {
         frameworkRoot,
@@ -511,8 +517,11 @@ export function runAgentHooksHealthCheck(projectRoot, consumerContext, sink, add
             });
             return false;
         }
-        const message = `${checkName}: registered and structurally valid; ` +
-            "Codex runtime trust is user-controlled and must be reviewed with `/hooks`";
+        const codexEnabled = result.registrations.some((entry) => entry.host === "codex" && entry.status !== "disabled");
+        const message = `${checkName}: registered and structurally valid` +
+            (codexEnabled
+                ? "; Codex trust is manual-review-required — open `/hooks` to review the project commands"
+                : "");
         sink.success(message);
         addFinding({
             severity: "skip",
@@ -520,8 +529,11 @@ export function runAgentHooksHealthCheck(projectRoot, consumerContext, sink, add
             check: checkName,
             status: "registered",
             registrations: result.registrations,
-            trust_status: "not-verifiable",
-            trust_review: "Open `/hooks` in Codex and review the project hook commands.",
+            trust_status: codexEnabled ? "manual-review-required" : "not-applicable",
+            trust_review: codexEnabled
+                ? "Open `/hooks` in Codex and review the exact project hook commands."
+                : null,
+            interception_status: "not-directly-verified",
         });
         return true;
     }
@@ -537,7 +549,25 @@ export function runAgentHooksLiveProbeCheck(projectRoot, sink, addFinding, seams
     const liveCheckName = "agent-hooks-live-probe";
     try {
         const result = (seams.evaluateAgentHooks ?? evaluateAgentHooks)(projectRoot);
-        const liveResult = (seams.probeAgentHooksLive ?? probeAgentHooksLive)(projectRoot);
+        if (result.code !== 0) {
+            const message = `${checkName}: ${result.message.replace(/\s+/g, " ").trim()}`;
+            sink.warn(message);
+            addFinding({
+                severity: "warning",
+                message,
+                check: checkName,
+                status: result.code === 2 ? "unavailable" : "incomplete",
+                registrations: result.registrations,
+                suggestion: "deft update",
+            });
+            return;
+        }
+        const enabledHosts = result.registrations
+            .filter((entry) => entry.status !== "disabled")
+            .map((entry) => entry.host);
+        const liveResult = (seams.probeAgentHooksLive ?? probeAgentHooksLive)(projectRoot, {
+            hosts: enabledHosts,
+        });
         if (liveResult.code !== 0) {
             const message = `${liveCheckName}: ${liveResult.message.replace(/\s+/g, " ").trim()}`;
             sink.warn(message);
@@ -551,8 +581,12 @@ export function runAgentHooksLiveProbeCheck(projectRoot, sink, addFinding, seams
             });
             return;
         }
-        const message = `${checkName}: registered, structurally valid, and live probe passed; ` +
-            "Codex runtime trust is user-controlled and must be reviewed with `/hooks`";
+        const codexEnabled = result.registrations.some((entry) => entry.host === "codex" && entry.status !== "disabled");
+        const message = `${checkName}: registered, structurally valid, and live probe passed` +
+            (codexEnabled
+                ? "; Codex trust is manual-review-required — open `/hooks` to review the project commands"
+                : "") +
+            "; direct shim invocation does not verify host interception";
         sink.success(message);
         addFinding({
             severity: "skip",
@@ -560,9 +594,13 @@ export function runAgentHooksLiveProbeCheck(projectRoot, sink, addFinding, seams
             check: liveCheckName,
             status: "registered-and-functional",
             registrations: result.registrations,
-            trust_status: "not-verifiable",
-            trust_review: "Open `/hooks` in Codex and review the project hook commands.",
+            trust_status: codexEnabled ? "manual-review-required" : "not-applicable",
+            trust_review: codexEnabled
+                ? "Open `/hooks` in Codex and review the exact project hook commands."
+                : null,
+            interception_status: "not-directly-verified",
             live_probe: "passed",
+            live_probe_duration_ms: liveResult.durationMs,
         });
     }
     catch (cause) {
@@ -763,6 +801,57 @@ function runAgentsMdAdvisoryCheck(projectRoot, sink, addFinding, seams) {
         addFinding({ severity: "warning", message, check: checkName });
     }
 }
+/**
+ * Consumer check-graph integrity (#3070): every CONSUMER_CHECK_GATES entry
+ * (including `verify:orphan-active`) must resolve against the deposited
+ * Taskfile includes. Missing `tasks/verify.yml` previously failed only at
+ * go-task shell time with opaque exit 200/201.
+ */
+function runConsumerCheckGraphIntegrity(projectRoot, frameworkRoot, sink, addFinding, seams) {
+    const checkName = "consumer-check-graph-integrity";
+    if (runningInsideDeftRepo(projectRoot, seams)) {
+        // Still prove the source checkout ships a resolvable consumer gate set.
+        const integrity = evaluateConsumerGateIntegrity(frameworkRoot);
+        if (integrity.ok) {
+            sink.success(`${checkName}: source checkout resolves CONSUMER_CHECK_GATES (incl. verify:orphan-active)`);
+            return;
+        }
+        const message = formatConsumerGateIntegrityFailure(integrity).trim();
+        sink.error(message);
+        addFinding({
+            severity: "error",
+            message,
+            check: checkName,
+            suggestion: "deft update",
+            status: "fail",
+        });
+        return;
+    }
+    try {
+        const depositRoot = frameworkRoot;
+        const integrity = evaluateConsumerGateIntegrity(depositRoot);
+        if (integrity.ok) {
+            sink.success(`${checkName}: deposit resolves CONSUMER_CHECK_GATES (incl. verify:orphan-active)`);
+            return;
+        }
+        // Incomplete deposit is an error for consumers — check:consumer would hard-fail.
+        const message = formatConsumerGateIntegrityFailure(integrity).trim();
+        sink.error(message);
+        addFinding({
+            severity: "error",
+            message,
+            check: checkName,
+            suggestion: integrity.recovery,
+            status: "fail",
+            findings: integrity.findings,
+        });
+    }
+    catch (exc) {
+        const message = `${checkName}: probe failed -- ${exc instanceof Error ? exc.name : "Error"}: ${exc}`;
+        sink.warn(message);
+        addFinding({ severity: "warning", message, check: checkName });
+    }
+}
 function runTaskfileIncludeCheck(projectRoot, fixMode, jsonMode, sink, addFinding, seams) {
     if (runningInsideDeftRepo(projectRoot, seams)) {
         sink.info("Skipping Taskfile include check -- running inside the deft framework repo (the repo's own Taskfile.yml is the surface).");

package/dist/doctor/types.d.ts

@@ -4,7 +4,7 @@ import type { EngineProbeResult } from "../resolution/classify.js";
 import type { ResolutionMode } from "../resolution/index.js";
 import type { ResolveUserMdResult } from "../user-config/resolve-user-md.js";
 import type { AgentHookHealthResult } from "../verify-env/agent-hooks.js";
-import type { AgentHookLiveProbeResult } from "../verify-env/agent-hooks-live-probe.js";
+import type { AgentHookLiveProbeResult, AgentHookLiveProbeSeams } from "../verify-env/agent-hooks-live-probe.js";
 export declare const EXIT_CLEAN = 0;
 export declare const EXIT_DRIFT = 1;
 export declare const EXIT_CONFIG_ERROR = 2;
@@ -153,7 +153,7 @@ export interface DoctorSeams {
     /** Read-only agent-host hook registration probe (#2438). */
     readonly evaluateAgentHooks?: (projectRoot: string) => AgentHookHealthResult;
     /** Live hook spawn probe for doctor --full (#2852). */
-    readonly probeAgentHooksLive?: (projectRoot: string) => AgentHookLiveProbeResult;
+    readonly probeAgentHooksLive?: (projectRoot: string, seams?: AgentHookLiveProbeSeams) => AgentHookLiveProbeResult;
     /**
      * xBRIEF project-envelope staleness probe (#2971). Injected so doctor can
      * fail closed on 0.6 project JSON under an xbrief/ layout without re-deriving

package/dist/finish-loop/pr-finish-loop.js

@@ -77,6 +77,7 @@ export function runPrFinishLoop(options) {
             maxWaitMinutes: options.maxWaitMinutes,
             pollSeconds: options.pollSeconds,
             oneShot: options.oneShot === true,
+            projectRoot,
         });
     }
     catch (err) {

package/dist/freshness/bind.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Session bind of live deposit generation (#3117).
+ *
+ * Host-agnostic storage:
+ * - Default (no sessionId): `.deft/session-bind.json` — single-operator convenience.
+ * - With sessionId: `.deft/session-binds/<safeId>.json` — isolated multi-session binds.
+ *
+ * Multi-agent hosts MUST pass a stable host session identity when binding and
+ * reporting so one session cannot certify another as current.
+ */
+import { type BoundGeneration, type LiveGeneration } from "./types.js";
+/** Relative path for the default (no-sessionId) bind record. */
+export declare const SESSION_BIND_REL: string;
+/** Directory for per-session bind records. */
+export declare const SESSION_BINDS_DIR_REL: string;
+export declare function sessionBindPath(projectRoot: string, sessionId?: string | null): string;
+/**
+ * Stable filesystem-safe file name for a host session id.
+ * Keeps a short prefix for debug, hashes the rest to avoid path injection.
+ * Character filter is O(n) (no regex) — CodeQL poly-redos on uncontrolled ids.
+ */
+export declare function safeSessionFileName(sessionId: string): string;
+export interface BindSessionOptions {
+    readonly sessionId?: string | null;
+    readonly nowIso?: string;
+    /**
+     * When live generation is missing (legacy deposit), stamp generation 1 from
+     * contentVersion before binding. Default true.
+     */
+    readonly ensureLive?: boolean;
+    /** Used only when ensuring a missing live token. */
+    readonly contentVersion?: string;
+    readonly stampedBy?: string;
+    /**
+     * When binding with a sessionId, also write the default bind path.
+     * Default **false** — multi-agent isolation requires hosts to report with
+     * `--session-id`. Enabling this reopens cross-session false-current (Greptile).
+     */
+    readonly alsoWriteDefault?: boolean;
+    /**
+     * Host attests that payload surfaces for the live generation were reloaded
+     * into the session. Required for trusted readiness. Default false.
+     */
+    readonly payloadLoaded?: boolean;
+}
+export interface ReadBoundOptions {
+    /** When set, read only that session's bind (never the default). */
+    readonly sessionId?: string | null;
+}
+/** Parse a bound generation record (null if invalid). */
+export declare function parseBoundGeneration(raw: unknown): BoundGeneration | null;
+/** Read the session bind record (null when absent/unreadable). */
+export declare function readBoundGeneration(projectRoot: string, options?: ReadBoundOptions): BoundGeneration | null;
+/**
+ * Bind the current live generation into session context.
+ *
+ * Does not require restarting a shared host runtime — callers re-load payload
+ * surfaces into the session and call this (or `freshness:bind`) to rebind.
+ *
+ * Multi-agent hosts MUST supply `sessionId` so binds do not overwrite each other.
+ */
+export declare function bindSessionGeneration(projectRoot: string, options?: BindSessionOptions): {
+    bound: BoundGeneration;
+    live: LiveGeneration;
+    path: string;
+};
+//# sourceMappingURL=bind.d.ts.map