@deftai/directive-core 0.93.0 → 0.95.0

package/dist/vbrief-reconcile/umbrellas.js

@@ -1,15 +1,18 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { referenceTypeMatches } from "@deftai/directive-types";
-import { createIssueComment, editIssueCommentBody, GitHubBodyError, } from "../intake/github-body.js";
+import { createIssueComment, editIssueBody, editIssueCommentBody, fetchIssueBody, GitHubBodyError, } from "../intake/github-body.js";
+import { fetchIssueStates, IssueState } from "../intake/reconcile-issues.js";
 import { hasArtifactSuffix, resolveLifecycleRoot, stripArtifactSuffix } from "../layout/resolve.js";
 import { call } from "../scm/call.js";
-import { extractIssueRef } from "../triage/reconcile/parse-uri.js";
+import { extractIssueRef, parseGithubIssueUri } from "../triage/reconcile/parse-uri.js";
 import { isRepoMutationAllowed } from "./repo-guard.js";
 export const OPEN_FOLDERS = ["proposed", "pending", "active"];
 export const CLOSED_FOLDERS = ["completed", "cancelled"];
 export const LIFECYCLE_FOLDERS = [...OPEN_FOLDERS, ...CLOSED_FOLDERS];
 export const CHILD_REF_TYPE = "x-xbrief/plan";
+/** Synthetic lifecycle folder for issue-only children with no local xBRIEF (#1649). */
+export const UNKNOWN_FOLDER = "unknown";
 const SCM_SOURCE = "github-issue";
 const HEADER_RE = /^## Current shape \(as of pass-(\d+)\)/m;
 // ReDoS-hardened (#1782 s4 / CodeQL js/polynomial-redos): the original
@@ -23,6 +26,12 @@ const HISTORY_RE = /^Child-count history:\s*(\S.*|)$/m;
 const LAST_UPDATED_RE = /^Last updated:\s*(\S.*|)$/m;
 const LAST_PASS_TYPE_RE = /^Last pass type:\s*(\S.*|)$/m;
 const HISTORY_TOKEN_RE = /^\s*pass-(\d+):\s*(\d+)\s*$/;
+/**
+ * Issue-body checklist line with a `#N` child ref (#1649).
+ * Captures leading marker, checkbox state, and the remainder after `]`.
+ * Linear-time: no nested quantifiers on overlapping classes.
+ */
+const CHECKLIST_ISSUE_LINE_RE = /^([ \t]*[-*+][ \t]+)\[([ xX])\]([ \t]*#[0-9]+\b.*)$/;
 const READING_ORDER = "1. Read the umbrella issue body.\n" +
     "2. Read this current-shape comment.\n" +
     "3. Read the amendment comments in chronological order for the full audit trail.";
@@ -52,12 +61,14 @@ export function childFromData(data, folder, fallbackId) {
         : {};
     const rawDeps = swarm.depends_on;
     const dependsOn = Array.isArray(rawDeps) ? rawDeps.map((d) => String(d)) : [];
+    const [, issueNumber] = extractIssueRef(data);
     return {
         story_id: String(plan.id ?? fallbackId),
         title: String(plan.title ?? plan.id ?? fallbackId),
         kind: String(metadata.kind ?? "story"),
         folder,
         depends_on: dependsOn,
+        issue_number: issueNumber,
     };
 }
 export function buildChildIndex(vbriefDir) {
@@ -80,7 +91,22 @@ export function buildChildIndex(vbriefDir) {
     }
     return index;
 }
-export function computeChildren(epicData, index) {
+/** Index children by forge issue number for github-issue ref resolution (#1649). */
+export function indexChildrenByIssueNumber(index) {
+    const byIssue = new Map();
+    for (const child of Object.values(index)) {
+        if (typeof child.issue_number === "number" && !byIssue.has(child.issue_number)) {
+            byIssue.set(child.issue_number, child);
+        }
+    }
+    return byIssue;
+}
+/**
+ * Resolve epic children from plan refs AND github-issue refs (#1649 defect 2).
+ * The epic's own github-issue ref is skipped when `epicIssueNumber` is provided.
+ * Issue-only children (no local xBRIEF) are synthesized with folder `unknown`.
+ */
+export function computeChildren(epicData, index, options = {}) {
     const plan = typeof epicData.plan === "object" && epicData.plan !== null && !Array.isArray(epicData.plan)
         ? epicData.plan
         : {};
@@ -89,21 +115,102 @@ export function computeChildren(epicData, index) {
     const seen = new Set();
     if (!Array.isArray(refs))
         return children;
+    const byIssue = indexChildrenByIssueNumber(index);
+    const epicIssue = options.epicIssueNumber ?? null;
     for (const ref of refs) {
         if (typeof ref !== "object" || ref === null || Array.isArray(ref))
             continue;
         const rec = ref;
-        if (!referenceTypeMatches(String(rec.type ?? ""), "plan"))
-            continue;
-        const name = basename(String(rec.uri ?? ""));
-        const child = index[name];
-        if (!child || seen.has(child.story_id))
+        const refType = String(rec.type ?? "");
+        if (referenceTypeMatches(refType, "plan")) {
+            const name = basename(String(rec.uri ?? ""));
+            const child = index[name];
+            if (!child || seen.has(child.story_id))
+                continue;
+            seen.add(child.story_id);
+            children.push(child);
             continue;
-        seen.add(child.story_id);
-        children.push(child);
+        }
+        if (referenceTypeMatches(refType, "github-issue")) {
+            const [, number] = parseGithubIssueUri(rec.uri);
+            if (number === null)
+                continue;
+            if (epicIssue !== null && number === epicIssue)
+                continue;
+            const fromIndex = byIssue.get(number);
+            if (fromIndex) {
+                if (seen.has(fromIndex.story_id))
+                    continue;
+                seen.add(fromIndex.story_id);
+                children.push(fromIndex);
+                continue;
+            }
+            // Synthetic child: hand-filed / issue:emit epic with issue-only child links.
+            const syntheticId = `#${number}`;
+            if (seen.has(syntheticId))
+                continue;
+            seen.add(syntheticId);
+            const title = typeof rec.title === "string" && rec.title.trim().length > 0
+                ? rec.title.trim()
+                : syntheticId;
+            children.push({
+                story_id: syntheticId,
+                title,
+                kind: "story",
+                folder: UNKNOWN_FOLDER,
+                depends_on: [],
+                issue_number: number,
+            });
+        }
     }
     return children;
 }
+/**
+ * Whether a child counts as open for current-shape + checklist (#1649 defect 3).
+ * Prefer forge issue state when present; fall back to lifecycle folder.
+ * `unknown` (issue-only, no local xBRIEF) counts open without forge confirmation.
+ */
+export function isChildOpen(child, forgeStates) {
+    if (typeof child.issue_number === "number" &&
+        forgeStates != null &&
+        forgeStates.has(child.issue_number)) {
+        return forgeStates.get(child.issue_number) === "open";
+    }
+    if (CLOSED_FOLDERS.includes(child.folder))
+        return false;
+    // proposed/pending/active/unknown (and any unexpected folder) → open
+    return true;
+}
+/**
+ * Reconcile umbrella issue-body checkboxes `- [ ] #N` / `- [x] #N` to child state (#1649).
+ * Only lines that mention a known child issue number are rewritten; other checkboxes untouched.
+ * Idempotent: returns `changed: false` when already correct.
+ */
+export function reconcileBodyChecklist(body, closedIssueNumbers, knownIssueNumbers) {
+    if (knownIssueNumbers.size === 0)
+        return { body, changed: false };
+    const lines = body.split("\n");
+    let changed = false;
+    const out = lines.map((line) => {
+        const match = CHECKLIST_ISSUE_LINE_RE.exec(line);
+        if (!match)
+            return line;
+        const issueMatch = /#(\d+)\b/.exec(match[3] ?? "");
+        if (!issueMatch?.[1])
+            return line;
+        const issueNum = Number(issueMatch[1]);
+        if (!knownIssueNumbers.has(issueNum))
+            return line;
+        const wantChecked = closedIssueNumbers.has(issueNum);
+        const isChecked = (match[2] ?? " ").toLowerCase() === "x";
+        if (isChecked === wantChecked)
+            return line;
+        changed = true;
+        const marker = wantChecked ? "x" : " ";
+        return `${match[1]}[${marker}]${match[3]}`;
+    });
+    return { body: out.join("\n"), changed };
+}
 export function computeWaves(children) {
     const ids = new Set(children.map((c) => c.story_id));
     const deps = {};
@@ -249,18 +356,92 @@ export class ScmUmbrellaClient {
             throw new UmbrellaScmError(`create comment #${issueNumber} (${repo}) failed: ${message}`);
         }
     }
+    fetchIssueStates(repo, issueNumbers) {
+        const result = new Map();
+        if (issueNumbers.length === 0)
+            return result;
+        const states = fetchIssueStates(repo, new Set(issueNumbers));
+        if (states === null) {
+            throw new UmbrellaScmError(`fetch issue states (${repo}) failed`);
+        }
+        for (const [num, state] of states) {
+            if (!(state instanceof IssueState))
+                continue;
+            const value = state.value.toUpperCase();
+            if (value === "OPEN")
+                result.set(num, "open");
+            else if (value === "CLOSED")
+                result.set(num, "closed");
+            // NOT_FOUND / other → omit so folder fallback applies
+        }
+        return result;
+    }
+    fetchIssueBody(repo, issueNumber) {
+        try {
+            return fetchIssueBody(repo, issueNumber);
+        }
+        catch (exc) {
+            const message = exc instanceof GitHubBodyError ? exc.message : String(exc);
+            throw new UmbrellaScmError(`fetch issue body #${issueNumber} (${repo}) failed: ${message}`);
+        }
+    }
+    editIssueBody(repo, issueNumber, body) {
+        try {
+            editIssueBody(repo, issueNumber, { body });
+        }
+        catch (exc) {
+            const message = exc instanceof GitHubBodyError ? exc.message : String(exc);
+            throw new UmbrellaScmError(`edit issue body #${issueNumber} (${repo}) failed: ${message}`);
+        }
+    }
 }
-function planShape(epicData, index) {
-    const children = computeChildren(epicData, index);
+function planShape(epicData, index, options = {}) {
+    const children = computeChildren(epicData, index, {
+        epicIssueNumber: options.epicIssueNumber,
+    });
     const openChildren = children
-        .filter((c) => OPEN_FOLDERS.includes(c.folder))
+        .filter((c) => isChildOpen(c, options.forgeStates))
         .sort((a, b) => a.story_id.localeCompare(b.story_id));
     const closedChildren = children
-        .filter((c) => !OPEN_FOLDERS.includes(c.folder))
+        .filter((c) => !isChildOpen(c, options.forgeStates))
         .sort((a, b) => a.story_id.localeCompare(b.story_id));
     const waves = computeWaves(children);
     return [openChildren, closedChildren, waves];
 }
+function resolveForgeStates(client, repo, children) {
+    if (typeof client.fetchIssueStates !== "function")
+        return null;
+    const numbers = children
+        .map((c) => c.issue_number)
+        .filter((n) => typeof n === "number");
+    if (numbers.length === 0)
+        return null;
+    return client.fetchIssueStates(repo, numbers);
+}
+function reconcileChecklistForEpic(client, repo, issueNumber, closedChildren, allChildren, dryRun) {
+    if (typeof client.fetchIssueBody !== "function" || typeof client.editIssueBody !== "function") {
+        return "skipped";
+    }
+    const known = new Set();
+    for (const c of allChildren) {
+        if (typeof c.issue_number === "number")
+            known.add(c.issue_number);
+    }
+    if (known.size === 0)
+        return "skipped";
+    const closed = new Set();
+    for (const c of closedChildren) {
+        if (typeof c.issue_number === "number")
+            closed.add(c.issue_number);
+    }
+    const currentBody = client.fetchIssueBody(repo, issueNumber);
+    const { body: nextBody, changed } = reconcileBodyChecklist(currentBody, closed, known);
+    if (!changed)
+        return "unchanged";
+    if (!dryRun)
+        client.editIssueBody(repo, issueNumber, nextBody);
+    return "edited";
+}
 function reconcileOneEpic(epicData, index, options) {
     const mutateGate = isRepoMutationAllowed(options.repo, options.projectRoot, {
         allowCrossRepo: options.allowCrossRepo,
@@ -270,10 +451,28 @@ function reconcileOneEpic(epicData, index, options) {
     if (!mutateGate.allowed) {
         throw new Error(mutateGate.reason ?? `refusing cross-repo mutation on ${options.repo}`);
     }
-    const [openChildren, closedChildren, waves] = planShape(epicData, index);
-    const total = openChildren.length + closedChildren.length;
+    // Resolve children once without forge state to know which issue numbers to fetch.
+    const childrenProbe = computeChildren(epicData, index, {
+        epicIssueNumber: options.number,
+    });
+    const forgeStates = resolveForgeStates(options.client, options.repo, childrenProbe);
+    const [openChildren, closedChildren, waves] = planShape(epicData, index, {
+        epicIssueNumber: options.number,
+        forgeStates,
+    });
+    const allChildren = [...openChildren, ...closedChildren];
+    const total = allChildren.length;
     const comments = options.client.fetchComments(options.repo, options.number);
     const existing = comments.find((c) => hasCurrentShape(c.body));
+    let checklistAction = "skipped";
+    try {
+        checklistAction = reconcileChecklistForEpic(options.client, options.repo, options.number, closedChildren, allChildren, options.dryRun);
+    }
+    catch (exc) {
+        // Checklist is best-effort relative to comment path: surface as throw so
+        // callers see the failure (body drift is the #1649 user-visible bug).
+        throw new UmbrellaScmError(exc instanceof Error ? exc.message : `checklist reconcile failed: ${String(exc)}`);
+    }
     if (!existing) {
         const body = renderBody({
             passN: 1,
@@ -293,6 +492,7 @@ function reconcileOneEpic(epicData, index, options) {
             action: "created",
             pass_n: 1,
             body,
+            checklist_action: checklistAction,
         };
     }
     const parsed = parseCurrentShape(existing.body);
@@ -308,13 +508,16 @@ function reconcileOneEpic(epicData, index, options) {
         history: parsed.history.length > 0 ? parsed.history : [[prevPass, total]],
     });
     if (candidate === existing.body) {
+        // Comment unchanged; still report edited when checklist flipped (#1649).
+        const action = checklistAction === "edited" ? "edited" : "unchanged";
         return {
             story_id: options.storyId,
             repo: options.repo,
             issue_number: options.number,
-            action: "unchanged",
+            action,
             pass_n: prevPass,
             body: candidate,
+            checklist_action: checklistAction,
         };
     }
     const passN = prevPass + 1;
@@ -336,6 +539,7 @@ function reconcileOneEpic(epicData, index, options) {
         action: "edited",
         pass_n: passN,
         body,
+        checklist_action: checklistAction,
     };
 }
 export function nowIso(date = new Date()) {
@@ -441,13 +645,19 @@ export function reconcileUmbrellas(projectRoot, options = {}) {
     }
     return [outcome.errors.length > 0 ? 1 : 0, outcome];
 }
+function formatChecklistSuffix(action) {
+    if (action === undefined || action === "skipped")
+        return "";
+    return `; checklist=${action}`;
+}
 export function renderUmbrellasReport(outcome) {
     const lines = ["vBRIEF reconcile umbrellas", ""];
     const suffix = outcome.dry_run ? " (dry-run)" : "";
     lines.push(`Changed${suffix}:`);
     if (outcome.changed.length > 0) {
         for (const c of outcome.changed) {
-            lines.push(`- #${c.issue_number} (${c.repo}) [${c.story_id}]: ${c.action} -> pass-${c.pass_n}`);
+            lines.push(`- #${c.issue_number} (${c.repo}) [${c.story_id}]: ${c.action} -> pass-${c.pass_n}` +
+                formatChecklistSuffix(c.checklist_action));
         }
     }
     else {
@@ -457,7 +667,8 @@ export function renderUmbrellasReport(outcome) {
     lines.push("Unchanged:");
     if (outcome.unchanged.length > 0) {
         for (const c of outcome.unchanged) {
-            lines.push(`- #${c.issue_number} (${c.repo}) [${c.story_id}]: pass-${c.pass_n}`);
+            lines.push(`- #${c.issue_number} (${c.repo}) [${c.story_id}]: pass-${c.pass_n}` +
+                formatChecklistSuffix(c.checklist_action));
         }
     }
     else {
@@ -484,6 +695,7 @@ export function umbrellasOutcomeToJson(outcome) {
         issue_number: c.issue_number,
         action: c.action,
         pass_n: c.pass_n,
+        checklist_action: c.checklist_action ?? "skipped",
     });
     return {
         changed: outcome.changed.map(toChange),

package/dist/vbrief-validate/project-definition.js

@@ -78,7 +78,7 @@ export function validateProjectDefinition(filepath, data, vbriefDir) {
                 }
                 const uriRaw = ref.uri;
                 const uri = typeof uriRaw === "string" ? uriRaw : "";
-                if (uri && uri.startsWith("file://")) {
+                if (uri.startsWith("file://")) {
                     const refPath = uri.replace("file://", "");
                     const fullPath = resolve(vbriefDir, refPath);
                     if (!isRelativeTo(fullPath, resolvedRoot)) {

package/dist/verify-env/agent-hook-readiness.d.ts

@@ -0,0 +1,42 @@
+import type { HookHost } from "../hooks/dispatcher.js";
+import type { AgentHookInspection } from "../init-deposit/agent-hooks.js";
+import type { HostHooksPolicy } from "../policy/host-hooks.js";
+import { type AgentHookHealthResult } from "./agent-hooks.js";
+import { type AgentHookLiveProbeResult, type AgentHookLiveProbeSeams } from "./agent-hooks-live-probe.js";
+import type { OutputStream } from "./verify-hooks-installed.js";
+export type AgentHookReadinessRegistration = "registered" | "disabled" | "missing" | "drifted" | "not-applicable";
+export type AgentHookReadinessFunctionality = "functional" | "non-functional" | "unavailable" | "not-run" | "disabled" | "not-applicable";
+export type AgentHookReadinessTrust = "manual-review-required" | "not-applicable" | "disabled";
+export type AgentHookReadinessInterception = "not-directly-verified" | "not-applicable" | "disabled";
+export type AgentHookReadinessLiveStatus = "functional" | "non-functional" | "unavailable" | "not-run" | "disabled" | "skipped";
+export interface AgentHookReadinessHostResult {
+    readonly host: HookHost;
+    readonly registration: AgentHookReadinessRegistration;
+    readonly functionality: AgentHookReadinessFunctionality;
+    readonly trust: AgentHookReadinessTrust;
+    readonly interception: AgentHookReadinessInterception;
+}
+export interface AgentHookReadinessResult {
+    readonly code: 0 | 1 | 2;
+    readonly message: string;
+    readonly stream: OutputStream;
+    readonly skipped: boolean;
+    readonly liveStatus: AgentHookReadinessLiveStatus;
+    readonly hosts: readonly AgentHookReadinessHostResult[];
+    readonly registrations: readonly AgentHookInspection[];
+    readonly liveProbe: AgentHookLiveProbeResult | null;
+}
+export interface AgentHookReadinessOptions {
+    readonly hostHooksPolicy?: HostHooksPolicy;
+    readonly consumerContext?: (projectRoot: string) => boolean;
+    readonly evaluateStructural?: (projectRoot: string, policy: HostHooksPolicy) => AgentHookHealthResult;
+    readonly probeLive?: (projectRoot: string, seams?: AgentHookLiveProbeSeams) => AgentHookLiveProbeResult;
+    readonly liveProbeSeams?: Omit<AgentHookLiveProbeSeams, "hosts">;
+}
+/** Stable CLI JSON projection; keep the four readiness dimensions orthogonal. */
+export declare function agentHookReadinessJson(result: AgentHookReadinessResult): Record<string, unknown>;
+/** Preserve fail-closed readiness semantics when an unexpected evaluator dependency throws. */
+export declare function evaluateAgentHookReadinessSafely(projectRoot: string, evaluate?: (projectRoot: string) => AgentHookReadinessResult): AgentHookReadinessResult;
+/** Fail-closed consumer readiness: structural registration first, installed-shim live probe second. */
+export declare function evaluateAgentHookReadiness(projectRoot: string, options?: AgentHookReadinessOptions): AgentHookReadinessResult;
+//# sourceMappingURL=agent-hook-readiness.d.ts.map

package/dist/verify-env/agent-hook-readiness.js

@@ -0,0 +1,150 @@
+import { resolve } from "node:path";
+import { resolveFrameworkRootForProject } from "../doctor/paths.js";
+import { loadHostHooksPolicyFromProject } from "../policy/host-hooks.js";
+import { evaluateAgentHooks } from "./agent-hooks.js";
+import { probeAgentHooksLive, } from "./agent-hooks-live-probe.js";
+/** Stable CLI JSON projection; keep the four readiness dimensions orthogonal. */
+export function agentHookReadinessJson(result) {
+    return {
+        ready: result.code === 0,
+        exit_code: result.code,
+        skipped: result.skipped,
+        live_status: result.liveStatus,
+        hosts: result.hosts.map((entry) => ({ ...entry })),
+        message: result.message,
+    };
+}
+/** Preserve fail-closed readiness semantics when an unexpected evaluator dependency throws. */
+export function evaluateAgentHookReadinessSafely(projectRoot, evaluate = evaluateAgentHookReadiness) {
+    try {
+        return evaluate(projectRoot);
+    }
+    catch (cause) {
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        return {
+            code: 2,
+            message: `❌ deft agent hook readiness unavailable: ${detail}`,
+            stream: "stderr",
+            skipped: false,
+            liveStatus: "unavailable",
+            hosts: [],
+            registrations: [],
+            liveProbe: null,
+        };
+    }
+}
+function isConsumerContext(projectRoot) {
+    return resolve(projectRoot) !== resolve(resolveFrameworkRootForProject(projectRoot));
+}
+function registrationState(entry) {
+    if (entry.status === "healthy")
+        return "registered";
+    return entry.status;
+}
+function renderHosts(hosts) {
+    return hosts
+        .map((entry) => `  - ${entry.host}: registration=${entry.registration}; functionality=${entry.functionality}; ` +
+        `trust=${entry.trust}; interception=${entry.interception}`)
+        .join("\n");
+}
+function baseHostResult(entry, policy) {
+    if (!policy[entry.host]) {
+        return {
+            host: entry.host,
+            registration: "disabled",
+            functionality: "disabled",
+            trust: "disabled",
+            interception: "disabled",
+        };
+    }
+    return {
+        host: entry.host,
+        registration: registrationState(entry),
+        functionality: "not-run",
+        trust: entry.host === "codex" ? "manual-review-required" : "not-applicable",
+        interception: "not-directly-verified",
+    };
+}
+/** Fail-closed consumer readiness: structural registration first, installed-shim live probe second. */
+export function evaluateAgentHookReadiness(projectRoot, options = {}) {
+    const root = resolve(projectRoot);
+    const consumerContext = options.consumerContext ?? isConsumerContext;
+    if (!consumerContext(root)) {
+        return {
+            code: 0,
+            message: "✓ deft agent hook readiness skipped: maintainer source checkout; consumer hook deposit is not applicable.",
+            stream: "stdout",
+            skipped: true,
+            liveStatus: "skipped",
+            hosts: [],
+            registrations: [],
+            liveProbe: null,
+        };
+    }
+    const policy = options.hostHooksPolicy ?? loadHostHooksPolicyFromProject(root);
+    const structural = (options.evaluateStructural ?? evaluateAgentHooks)(root, policy);
+    const hosts = structural.registrations.map((entry) => baseHostResult(entry, policy));
+    if (structural.code !== 0) {
+        return {
+            code: structural.code,
+            message: `${structural.message}\n${renderHosts(hosts)}`,
+            stream: "stderr",
+            skipped: false,
+            liveStatus: "not-run",
+            hosts,
+            registrations: structural.registrations,
+            liveProbe: null,
+        };
+    }
+    const enabledHosts = structural.registrations
+        .filter((entry) => policy[entry.host])
+        .map((entry) => entry.host);
+    const liveProbe = (options.probeLive ?? probeAgentHooksLive)(root, {
+        ...options.liveProbeSeams,
+        hosts: enabledHosts,
+    });
+    const liveByHost = new Map(liveProbe.hosts.map((entry) => [entry.host, entry.status]));
+    const evaluatedHosts = hosts.map((entry) => {
+        if (entry.functionality === "disabled")
+            return entry;
+        const liveStatus = liveByHost.get(entry.host);
+        return {
+            ...entry,
+            functionality: liveStatus === "functional"
+                ? "functional"
+                : liveStatus === "unavailable"
+                    ? "unavailable"
+                    : liveStatus === "non-functional"
+                        ? "non-functional"
+                        : "not-run",
+        };
+    });
+    const allDisabled = enabledHosts.length === 0;
+    const liveStatus = allDisabled
+        ? "disabled"
+        : liveProbe.code === 0
+            ? "functional"
+            : liveProbe.code === 2
+                ? "unavailable"
+                : "non-functional";
+    const trustReview = policy.codex
+        ? "\n  Codex trust: manual-review-required. Open `/hooks` and approve the exact project hook commands. " +
+            "The live probe validates the shim and codec, not host interception."
+        : "";
+    return {
+        code: liveProbe.code,
+        message: `${liveProbe.code === 0 ? "✓" : "❌"} deft agent hook readiness: ${liveProbe.message}\n` +
+            renderHosts(evaluatedHosts) +
+            trustReview +
+            (liveProbe.code === 0
+                ? ""
+                : "\n  If an affected host is unused, inspect `deft policy:show --field=hostHooks`, set `plan.policy.hostHooks.<host> = false`, and run `deft update`."),
+        stream: liveProbe.code === 0 ? "stdout" : "stderr",
+        skipped: false,
+        liveStatus,
+        hosts: evaluatedHosts,
+        registrations: structural.registrations,
+        liveProbe,
+    };
+}
+//# sourceMappingURL=agent-hook-readiness.js.map

package/dist/verify-env/agent-hooks-live-probe.d.ts

@@ -1,5 +1,6 @@
-import type { HookEvent, HookHost } from "../hooks/dispatcher.js";
-export type AgentHookLiveProbeIssue = "hook-command-missing" | "spawn-failed" | "empty-stdout" | "unparseable-json" | "missing-allow" | "missing-deny";
+import { type HookEvent, type HookHost } from "../hooks/dispatcher.js";
+export declare const LIVE_PROBE_CASE_TIMEOUT_MS = 1500;
+export type AgentHookLiveProbeIssue = "hook-command-missing" | "spawn-failed" | "timed-out" | "empty-stdout" | "unparseable-json" | "missing-allow" | "missing-deny";
 export interface AgentHookLiveProbeCase {
     readonly host: HookHost;
     readonly event: HookEvent;
@@ -7,26 +8,37 @@ export interface AgentHookLiveProbeCase {
     readonly issue: AgentHookLiveProbeIssue;
     readonly detail: string;
 }
+export type AgentHookLiveProbeHostStatus = "functional" | "non-functional" | "unavailable";
+export interface AgentHookLiveProbeHostResult {
+    readonly host: HookHost;
+    readonly status: AgentHookLiveProbeHostStatus;
+}
 export interface AgentHookLiveProbeResult {
     readonly code: 0 | 1 | 2;
     readonly message: string;
     readonly cases: readonly AgentHookLiveProbeCase[];
+    readonly hosts: readonly AgentHookLiveProbeHostResult[];
+    readonly durationMs: number;
 }
 export interface AgentHookLiveProbeSeams {
+    /** Enabled hosts to probe. Defaults to every deposited host. */
+    readonly hosts?: readonly HookHost[];
     readonly resolveCommand?: (name: string) => string | null;
     readonly spawnHook?: (input: {
         readonly command: string;
         readonly args: readonly string[];
         readonly stdin: string;
         readonly cwd: string;
-        readonly env?: NodeJS.ProcessEnv;
+        readonly env: NodeJS.ProcessEnv;
     }) => {
         readonly status: number;
         readonly stdout: string;
         readonly stderr: string;
+        readonly timedOut?: boolean;
     };
 }
+/** Quote one Windows cmd.exe argument used by the installed hook shim. */
 export declare function quoteWindowsCmdArg(value: string): string;
-/** Spawn the configured hook command and assert Cursor tool.before allow/deny behavior. */
+/** Invoke the installed deft-hook shim and validate enabled host allow/deny codecs. */
 export declare function probeAgentHooksLive(projectRoot: string, seams?: AgentHookLiveProbeSeams): AgentHookLiveProbeResult;
 //# sourceMappingURL=agent-hooks-live-probe.d.ts.map