@deftai/directive-core 0.105.0 → 0.107.0

package/dist/value/feedback-file.js

@@ -7,6 +7,21 @@ import { GhRestError, restCreateIssue, restIssueListPaginated, } from "../scm/gh
 import { resolveProjectRoot } from "../scope/project-context.js";
 export const DEFAULT_UPSTREAM_REPO = "deftai/directive";
 export const FRAMEWORK_GAP_TITLE_PREFIX = "[framework-gap]";
+/** Sole sanctioned title classification (#3713). Does not write `adoption-blocker`. */
+export const ADOPTION_BLOCKER_TITLE_TOKEN = "BLOCKER";
+const FRAMEWORK_GAP_PREFIX_RE = /^\[framework-gap\]\s*/i;
+const BLOCKER_TITLE_TOKEN_RE = /^BLOCKER\b[:\s-]*/i;
+/** Strip source prefix and the optional BLOCKER token so marked/unmarked titles dedup. */
+export function stripTitleClassificationTokens(title) {
+    let rest = title.trim();
+    let previous = "";
+    while (rest !== previous) {
+        previous = rest;
+        rest = rest.replace(FRAMEWORK_GAP_PREFIX_RE, "").trim();
+        rest = rest.replace(BLOCKER_TITLE_TOKEN_RE, "").trim();
+    }
+    return rest;
+}
 function sanitizeOneLine(value) {
     return value.replace(/\r?\n/g, " ").trim();
 }
@@ -18,23 +33,54 @@ function sectionOrPlaceholder(value, placeholder) {
 export function isMaintainerFrameworkRepo(projectRoot) {
     return isFrameworkRepoRoot(resolve(projectRoot));
 }
-/** Normalize a title for duplicate comparison (#1709). */
+/** Normalize a title for duplicate comparison (#1709 / #3713). */
 export function normalizeForDedup(title) {
-    return title
-        .trim()
-        .replace(/^\[framework-gap\]\s*/i, "")
+    return stripTitleClassificationTokens(title)
         .toLowerCase()
         .replace(/[^\p{L}\p{N}]+/gu, " ")
         .trim();
 }
 /** Build the upstream issue title for a framework-gap report. */
-export function buildFrameworkGapTitle(summary) {
+export function buildFrameworkGapTitle(summary, options) {
     const clean = sanitizeOneLine(summary);
+    if (options?.adoptionBlocker) {
+        const rest = stripTitleClassificationTokens(clean);
+        return `${FRAMEWORK_GAP_TITLE_PREFIX} ${ADOPTION_BLOCKER_TITLE_TOKEN} ${rest}`;
+    }
     if (clean.toLowerCase().startsWith(FRAMEWORK_GAP_TITLE_PREFIX.toLowerCase())) {
         return clean;
     }
     return `${FRAMEWORK_GAP_TITLE_PREFIX} ${clean}`;
 }
+function buildAdoptionImpactSection(input) {
+    if (!input.adoptionBlocker) {
+        return [];
+    }
+    return [
+        "## Adoption impact",
+        "",
+        "This report is a consumer hard-stop: the consumer cannot complete an intended Directive flow and has no reasonable workaround.",
+        "",
+        `Title token: \`${ADOPTION_BLOCKER_TITLE_TOKEN}\`. This token does not apply the \`adoption-blocker\` ranking label. A privileged actor applies that label after the body-evidence test.`,
+        "",
+        "### Affected consumer flow and version",
+        "",
+        sectionOrPlaceholder(input.flowAndVersion, "_(not provided)_"),
+        "",
+        "### Documented alternatives attempted",
+        "",
+        sectionOrPlaceholder(input.alternatives, "_(not provided — why documented alternatives are not a reasonable workaround)_"),
+        "",
+        "### Observed recovery cost",
+        "",
+        sectionOrPlaceholder(input.recoveryCost, "_(not provided)_"),
+        "",
+        "### Triage owner and date",
+        "",
+        "_(to be filled by a privileged actor when applying `adoption-blocker`)_",
+        "",
+    ];
+}
 /** Build the structured framework-gap issue body. */
 export function buildFrameworkGapBody(input) {
     const summary = sanitizeOneLine(input.summary);
@@ -59,6 +105,7 @@ export function buildFrameworkGapBody(input) {
         "",
         sectionOrPlaceholder(input.sessionNotes, "_(not provided)_"),
         "",
+        ...buildAdoptionImpactSection(input),
         "---",
         "_Filed via `task feedback:file` from a directive consumer project (Refs #1709 value-feedback gap escalation)._",
         "",
@@ -126,7 +173,7 @@ export function runFeedbackFile(options) {
     }
     const projectRoot = resolve(projectRootRaw);
     const repo = resolveRepo(options);
-    const title = buildFrameworkGapTitle(summary);
+    const title = buildFrameworkGapTitle(summary, { adoptionBlocker: options.adoptionBlocker });
     const body = buildFrameworkGapBody(options);
     if (isMaintainerFrameworkRepo(projectRoot)) {
         return {
@@ -254,6 +301,8 @@ export function parseFeedbackFileArgs(argv) {
             out.dryRun = true;
         else if (arg === "--json")
             out.json = true;
+        else if (arg === "--blocker")
+            out.adoptionBlocker = true;
         else if (arg === "--summary") {
             out.summary = argv[++i];
         }
@@ -287,6 +336,27 @@ export function parseFeedbackFileArgs(argv) {
         else if (arg?.startsWith("--session-notes=")) {
             out.sessionNotes = arg.slice("--session-notes=".length);
         }
+        else if (arg === "--flow" || arg === "--flow-and-version") {
+            out.flowAndVersion = argv[++i];
+        }
+        else if (arg?.startsWith("--flow=")) {
+            out.flowAndVersion = arg.slice("--flow=".length);
+        }
+        else if (arg?.startsWith("--flow-and-version=")) {
+            out.flowAndVersion = arg.slice("--flow-and-version=".length);
+        }
+        else if (arg === "--alternatives") {
+            out.alternatives = argv[++i];
+        }
+        else if (arg?.startsWith("--alternatives=")) {
+            out.alternatives = arg.slice("--alternatives=".length);
+        }
+        else if (arg === "--recovery-cost") {
+            out.recoveryCost = argv[++i];
+        }
+        else if (arg?.startsWith("--recovery-cost=")) {
+            out.recoveryCost = arg.slice("--recovery-cost=".length);
+        }
         else if (arg === "--repo") {
             out.repo = argv[++i];
         }
@@ -327,6 +397,10 @@ export function feedbackFileMain(argv) {
         expected: args.expected,
         actual: args.actual,
         sessionNotes: args.sessionNotes,
+        adoptionBlocker: args.adoptionBlocker,
+        flowAndVersion: args.flowAndVersion,
+        alternatives: args.alternatives,
+        recoveryCost: args.recoveryCost,
         confirm: args.confirm,
         dryRun: args.dryRun,
         json: args.json,

package/dist/value/readback.d.ts

@@ -1,5 +1,6 @@
 import { type BehavioralEventRecord } from "../lifecycle/events.js";
 import { type ValueFeedbackResolved } from "../policy/value-feedback.js";
+import { type CeremonyCostRollup } from "../session/process-cost.js";
 /** Repeat-suppression window for the budgeted session readback (#1709 / #1279 parity). */
 export declare const VALUE_READBACK_SUPPRESSION_HOURS = 4;
 export declare const VALUE_READBACK_HISTORY_REL: string;
@@ -24,6 +25,8 @@ export interface ValueShowResult {
     readonly empty: boolean;
     readonly text: string;
     readonly trend: ValueShowTrend | null;
+    /** Composed #3508 ceremony-cost rollup (CLI process time, not turn clock). */
+    readonly ceremonyCost: CeremonyCostRollup | null;
 }
 export interface SessionReadbackResult {
     readonly line: string | null;
@@ -64,7 +67,7 @@ export declare function computeValueShowTrend(projectRoot: string, options?: {
     now?: Date;
 }): ValueShowTrend;
 export declare function formatValueShowReport(trend: ValueShowTrend): string;
-/** Pull-based value:show CLI core (#1709). */
+/** Pull-based value:show CLI core (#1709) with composed ceremony-cost reader (#3508). */
 export declare function runValueShow(options: {
     projectRoot?: string | null;
     window?: string;

package/dist/value/readback.js

@@ -8,6 +8,7 @@ import { DEFAULT_EVENT_LOG, readEvents } from "../lifecycle/events.js";
 import { policyColonInvocation } from "../policy/policy-invocation.js";
 import { isValueFeedbackPathAllowed, resolveValueFeedback, } from "../policy/value-feedback.js";
 import { resolveProjectRoot } from "../scope/project-context.js";
+import { computeCeremonyCostRollup, formatCeremonyCostReport, PROCESS_COST_EVENT_NAMES, } from "../session/process-cost.js";
 import { MAX_LINE_CHARS } from "../triage/welcome/constants.js";
 import { probeAdoptionAtWorkBoundary } from "./adoption-emit.js";
 import { probeFrictionAtWorkBoundary } from "./friction-emit.js";
@@ -391,7 +392,36 @@ export function formatValueShowReport(trend) {
     ];
     return `${lines.join("\n")}\n`;
 }
-/** Pull-based value:show CLI core (#1709). */
+function attachCeremonyCost(result, ceremonyCost, format) {
+    if (format === "json") {
+        const payload = result.trend !== null
+            ? {
+                ...result.trend,
+                ceremonyCost,
+                process_cost_events: PROCESS_COST_EVENT_NAMES,
+                gated: result.gated,
+                attribution_gated: result.gated,
+            }
+            : {
+                ceremonyCost,
+                process_cost_events: PROCESS_COST_EVENT_NAMES,
+                gated: result.gated,
+                attribution_gated: result.gated,
+                empty: result.empty,
+            };
+        return {
+            ...result,
+            ceremonyCost,
+            text: `${JSON.stringify(payload, null, 2)}\n`,
+        };
+    }
+    return {
+        ...result,
+        ceremonyCost,
+        text: `${result.text}${formatCeremonyCostReport(ceremonyCost)}`,
+    };
+}
+/** Pull-based value:show CLI core (#1709) with composed ceremony-cost reader (#3508). */
 export function runValueShow(options) {
     const rootRaw = resolveProjectRoot(options.projectRoot ?? undefined);
     if (rootRaw === null) {
@@ -401,30 +431,39 @@ export function runValueShow(options) {
             empty: true,
             text: "Error: could not resolve project root.\n",
             trend: null,
+            ceremonyCost: null,
         };
     }
     const root = resolve(rootRaw);
+    const windowMs = parseWindowMs(options.window);
+    const ceremonyCost = computeCeremonyCostRollup({
+        projectRoot: root,
+        logPath: options.logPath,
+        windowMs,
+        now: options.now,
+        windowLabel: formatWindowLabel(windowMs),
+    });
     if (maintainerReadbackDisabled(root)) {
-        return {
+        return attachCeremonyCost({
             exitCode: 0,
-            gated: true,
+            gated: false,
             empty: true,
-            text: "[value] Skipped: maintainer framework repo (set DEFT_VALUE_SELF_DOGFOOD=1 to dogfood).\n",
+            text: "[value] Attribution skipped: maintainer framework repo " +
+                "(set DEFT_VALUE_SELF_DOGFOOD=1 to dogfood).\n",
             trend: null,
-        };
+        }, ceremonyCost, options.format);
     }
     const policy = options.policyOverride ?? resolveValueFeedback(root);
     if (!policy.enabled) {
-        return {
+        return attachCeremonyCost({
             exitCode: 1,
             gated: true,
             empty: true,
             text: "[value] Blocked: plan.policy.valueFeedback is OFF. " +
                 `Enable with \`${policyColonInvocation("enable-value-feedback", " -- --confirm")}\`.\n`,
             trend: null,
-        };
+        }, ceremonyCost, options.format);
     }
-    const windowMs = parseWindowMs(options.window);
     const trend = computeValueShowTrend(root, {
         windowMs,
         logPath: options.logPath,
@@ -432,21 +471,21 @@ export function runValueShow(options) {
     });
     const empty = trend.total === 0;
     if (options.format === "json") {
-        return {
+        return attachCeremonyCost({
             exitCode: 0,
             gated: false,
             empty,
             text: `${JSON.stringify(trend, null, 2)}\n`,
             trend,
-        };
+        }, ceremonyCost, "json");
     }
-    return {
+    return attachCeremonyCost({
         exitCode: 0,
         gated: false,
         empty,
         text: formatValueShowReport(trend),
         trend,
-    };
+    }, ceremonyCost, "text");
 }
 export function parseValueShowArgs(argv) {
     const out = {};

package/dist/vbrief-reconcile/labels.d.ts

@@ -9,6 +9,7 @@ export declare function computeDesiredLabels(plan: Record<string, unknown>, unre
 export declare class ScmLabelClient implements LabelClient {
     fetchLabels(repo: string, issueNumber: number): string[];
     apply(repo: string, issueNumber: number, add: readonly string[], remove: readonly string[]): void;
+    private applyMut;
 }
 export interface ReconcileLabelsOptions {
     readonly repo?: string | null;

package/dist/vbrief-reconcile/labels.js

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { applyDesignCritiqueCatalogChip, isDesignCritiqueCatalogChip, } from "../design-critique/exclusive-chip.js";
 import { hasArtifactSuffix, resolveLifecycleRoot, stripArtifactSuffix } from "../layout/resolve.js";
 import { call } from "../scm/call.js";
 import { extractIssueRef } from "../triage/reconcile/parse-uri.js";
@@ -69,6 +70,35 @@ export class ScmLabelClient {
         return names;
     }
     apply(repo, issueNumber, add, remove) {
+        const catalogAdds = add.filter(isDesignCritiqueCatalogChip);
+        if (catalogAdds.length > 0) {
+            const nextChip = catalogAdds[catalogAdds.length - 1];
+            const restAdd = add.filter((name) => !isDesignCritiqueCatalogChip(name));
+            const restRemove = remove.filter((name) => !isDesignCritiqueCatalogChip(name));
+            let applied = false;
+            const inner = {
+                fetchLabels: (r, n) => this.fetchLabels(r, n),
+                apply: (r, n, a, rem) => {
+                    applied = true;
+                    const addSet = new Set([...a, ...restAdd]);
+                    const removeSet = new Set([...rem, ...restRemove]);
+                    for (const name of addSet)
+                        removeSet.delete(name);
+                    this.applyMut(r, n, [...addSet], [...removeSet]);
+                },
+            };
+            applyDesignCritiqueCatalogChip(inner, repo, issueNumber, nextChip);
+            if (!applied && (restAdd.length > 0 || restRemove.length > 0)) {
+                this.applyMut(repo, issueNumber, restAdd, restRemove);
+            }
+            return;
+        }
+        this.applyMut(repo, issueNumber, add, remove);
+    }
+    applyMut(repo, issueNumber, add, remove) {
+        if (add.length === 0 && remove.length === 0) {
+            return;
+        }
         const args = ["edit", String(issueNumber), "--repo", repo];
         for (const name of add)
             args.push("--add-label", name);

package/dist/vbrief-validate/schema.d.ts

@@ -1,4 +1,8 @@
 export type JsonObject = Record<string, unknown>;
+export declare function resolveInfoBlock(data: JsonObject): {
+    key: "vBRIEFInfo" | "xBRIEFInfo";
+    info: JsonObject;
+} | null;
 /** Validate vBRIEF/xBRIEF structural requirements (v0.6 + v0.8 additive). */
 export declare function validateVbriefSchema(data: JsonObject, filepath: string): string[];
 /** Normalize a narrative key for D3 comparison. */

package/dist/vbrief-validate/schema.js

@@ -22,7 +22,7 @@ function validatePlanRefs(planRefs, path, errors) {
         }
     }
 }
-function resolveInfoBlock(data) {
+export function resolveInfoBlock(data) {
     for (const key of VALID_INFO_ROOT_KEYS) {
         if (!(key in data)) {
             continue;

package/dist/vbrief-validation/story-quality.d.ts

@@ -25,5 +25,12 @@ export interface StoryQualityParams {
     readonly swarm: JsonObject;
     readonly concurrentReady?: boolean;
 }
+/**
+ * Shared Gate A text for `readiness=ready` + `parallel_safe: false` (#3666 / #3252).
+ * Authoring (`scope:decompose`) and launch (`swarm:readiness` / `swarm:launch`)
+ * both emit this string. It must not recommend `readiness=sequential` as a
+ * launch remediation — Gate B rejects that value on the same call.
+ */
+export declare const READY_REQUIRES_PARALLEL_SAFE = "readiness=ready requires parallel_safe=true. This story is not eligible for concurrent swarm:launch; dispatch non-concurrent work via the interactive swarm-skill solo-worker path (that path is not gated by swarm:readiness exiting 0; exit 0 gates concurrent workers only; see #3669)";
 export declare function storyQualityIssues(params: StoryQualityParams): string[];
 //# sourceMappingURL=story-quality.d.ts.map

package/dist/vbrief-validation/story-quality.js

@@ -266,6 +266,13 @@ export function deprecatedSubitemsIssues(items, prefix = "plan.items") {
     visit(items, prefix);
     return issues;
 }
+/**
+ * Shared Gate A text for `readiness=ready` + `parallel_safe: false` (#3666 / #3252).
+ * Authoring (`scope:decompose`) and launch (`swarm:readiness` / `swarm:launch`)
+ * both emit this string. It must not recommend `readiness=sequential` as a
+ * launch remediation — Gate B rejects that value on the same call.
+ */
+export const READY_REQUIRES_PARALLEL_SAFE = "readiness=ready requires parallel_safe=true. This story is not eligible for concurrent swarm:launch; dispatch non-concurrent work via the interactive swarm-skill solo-worker path (that path is not gated by swarm:readiness exiting 0; exit 0 gates concurrent workers only; see #3669)";
 export function storyQualityIssues(params) {
     const issues = [];
     const concurrentReady = params.concurrentReady ?? true;
@@ -304,7 +311,7 @@ export function storyQualityIssues(params) {
         issues.push(...fileScopeIssues(params.swarm));
         issues.push(...verifyCommandIssues(params.swarm));
         if (params.swarm.parallel_safe === false) {
-            issues.push("readiness=ready requires parallel_safe=true; use readiness=sequential or needs_refinement for non-concurrent work");
+            issues.push(READY_REQUIRES_PARALLEL_SAFE);
         }
         if (params.swarm.file_scope_confidence === "low") {
             issues.push("readiness=ready requires file_scope_confidence above low");

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

@@ -5,10 +5,10 @@ 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 AgentHookReadinessFunctionality = "functional" | "non-functional" | "unavailable" | "timed-out" | "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 type AgentHookReadinessLiveStatus = "functional" | "non-functional" | "unavailable" | "timed-out" | "not-run" | "disabled" | "skipped";
 export interface AgentHookReadinessHostResult {
     readonly host: HookHost;
     readonly registration: AgentHookReadinessRegistration;

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

@@ -1,6 +1,6 @@
 import { resolve } from "node:path";
 import { resolveFrameworkRootForProject } from "../doctor/paths.js";
-import { loadHostHooksPolicyFromProject } from "../policy/host-hooks.js";
+import { loadHostHooksPolicyFromProject, UNUSED_HOST_HOOKS_RECOVERY, } 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. */
@@ -114,31 +114,35 @@ export function evaluateAgentHookReadiness(projectRoot, options = {}) {
                 ? "functional"
                 : liveStatus === "unavailable"
                     ? "unavailable"
-                    : liveStatus === "non-functional"
-                        ? "non-functional"
-                        : "not-run",
+                    : liveStatus === "timed-out"
+                        ? "timed-out"
+                        : liveStatus === "non-functional"
+                            ? "non-functional"
+                            : "not-run",
         };
     });
     const allDisabled = enabledHosts.length === 0;
+    const timeoutOnly = liveProbe.cases.length > 0 && liveProbe.cases.every((entry) => entry.issue === "timed-out");
     const liveStatus = allDisabled
         ? "disabled"
         : liveProbe.code === 0
             ? "functional"
             : liveProbe.code === 2
                 ? "unavailable"
-                : "non-functional";
+                : timeoutOnly
+                    ? "timed-out"
+                    : "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."
         : "";
+    const unusedHostRecovery = liveProbe.code === 0 || timeoutOnly ? "" : `\n  ${UNUSED_HOST_HOOKS_RECOVERY}`;
     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`."),
+            unusedHostRecovery,
         stream: liveProbe.code === 0 ? "stdout" : "stderr",
         skipped: false,
         liveStatus,

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

@@ -1,5 +1,9 @@
 import { type HookEvent, type HookHost } from "../hooks/dispatcher.js";
 export declare const LIVE_PROBE_CASE_TIMEOUT_MS = 1500;
+/** Extra attempts after a timeout. One retry keeps 4×2×1.5s×2 = 24s under Cursor 30s (#3570). */
+export declare const LIVE_PROBE_CASE_RETRY_COUNT = 1;
+export declare const LIVE_PROBE_TIMEOUT_RECOVERY = "Recovery: retry the gated ritual when load is lower. Do not reinstall @deftai/directive or disable hostHooks for a timeout.";
+export declare const LIVE_PROBE_BROKEN_RECOVERY = "Recovery: reinstall @deftai/directive and run `deft update`.";
 export type AgentHookLiveProbeIssue = "hook-command-missing" | "spawn-failed" | "timed-out" | "empty-stdout" | "unparseable-json" | "missing-allow" | "missing-deny";
 export interface AgentHookLiveProbeCase {
     readonly host: HookHost;
@@ -8,7 +12,7 @@ export interface AgentHookLiveProbeCase {
     readonly issue: AgentHookLiveProbeIssue;
     readonly detail: string;
 }
-export type AgentHookLiveProbeHostStatus = "functional" | "non-functional" | "unavailable";
+export type AgentHookLiveProbeHostStatus = "functional" | "non-functional" | "unavailable" | "timed-out";
 export interface AgentHookLiveProbeHostResult {
     readonly host: HookHost;
     readonly status: AgentHookLiveProbeHostStatus;

package/dist/verify-env/agent-hooks-live-probe.js

@@ -6,6 +6,10 @@ import { DEFT_HOOK_COMMAND_MARKER } from "../init-deposit/agent-hooks.js";
 import { SUBPROCESS_MAX_BUFFER } from "../subprocess/max-buffer.js";
 import { quoteWin32CommandForShell, resolveCommandOnPath, shouldUseShellForCommand, } from "./command-spawn.js";
 export const LIVE_PROBE_CASE_TIMEOUT_MS = 1_500;
+/** Extra attempts after a timeout. One retry keeps 4×2×1.5s×2 = 24s under Cursor 30s (#3570). */
+export const LIVE_PROBE_CASE_RETRY_COUNT = 1;
+export const LIVE_PROBE_TIMEOUT_RECOVERY = "Recovery: retry the gated ritual when load is lower. Do not reinstall @deftai/directive or disable hostHooks for a timeout.";
+export const LIVE_PROBE_BROKEN_RECOVERY = "Recovery: reinstall @deftai/directive and run `deft update`.";
 const LIVE_PROBE_EVENT = "tool.before";
 function elapsedMs(started) {
     return Math.max(0, Math.round(performance.now() - started));
@@ -122,21 +126,38 @@ function validateFixtureOutput(host, fixture, stdout) {
         ? { ok: true }
         : { ok: false, issue: "missing-deny", detail: `expected ${host} deny envelope` };
 }
+function liveProbeRecovery(cases) {
+    if (cases.length > 0 && cases.every((entry) => entry.issue === "timed-out")) {
+        return LIVE_PROBE_TIMEOUT_RECOVERY;
+    }
+    return LIVE_PROBE_BROKEN_RECOVERY;
+}
+function hostStatusFromFailure(hostFailure) {
+    if (hostFailure === null)
+        return "functional";
+    if (hostFailure.issue === "timed-out")
+        return "timed-out";
+    return "non-functional";
+}
 function runFixtureProbe(command, host, projectRoot, fixture, spawnHook) {
-    const spawned = spawnHook({
+    const input = {
         command,
         args: ["--host", host, "--event", LIVE_PROBE_EVENT, "--project-root", projectRoot],
         stdin: fixture === "allow" ? allowFixture(projectRoot) : denyFixture(projectRoot),
         cwd: projectRoot,
         env: fixture === "allow" ? process.env : denyProbeEnv(),
-    });
+    };
+    let spawned = spawnHook(input);
+    for (let retry = 0; retry < LIVE_PROBE_CASE_RETRY_COUNT && spawned.timedOut === true; retry += 1) {
+        spawned = spawnHook(input);
+    }
     if (spawned.timedOut === true) {
         return {
             host,
             event: LIVE_PROBE_EVENT,
             fixture,
             issue: "timed-out",
-            detail: `hook command exceeded ${LIVE_PROBE_CASE_TIMEOUT_MS}ms`,
+            detail: `hook command exceeded ${LIVE_PROBE_CASE_TIMEOUT_MS}ms after ${LIVE_PROBE_CASE_RETRY_COUNT + 1} attempts`,
         };
     }
     if (spawned.status !== 0) {
@@ -204,7 +225,7 @@ export function probeAgentHooksLive(projectRoot, seams = {}) {
                 break;
             }
         }
-        hostResults.push({ host, status: hostFailure === null ? "functional" : "non-functional" });
+        hostResults.push({ host, status: hostStatusFromFailure(hostFailure) });
     }
     if (failures.length === 0) {
         return {
@@ -220,7 +241,7 @@ export function probeAgentHooksLive(projectRoot, seams = {}) {
         .join("; ");
     return {
         code: 1,
-        message: `deft agent hooks live probe FAILED: ${summary}. Recovery: reinstall @deftai/directive and run \`deft update\`.`,
+        message: `deft agent hooks live probe FAILED: ${summary}. ${liveProbeRecovery(failures)}`,
         cases: failures,
         hosts: hostResults,
         durationMs: elapsedMs(started),

package/dist/verify-env/agent-hooks.js

@@ -1,7 +1,7 @@
 import { statSync } from "node:fs";
 import { resolve } from "node:path";
 import { inspectAgentHookDeposit } from "../init-deposit/agent-hooks.js";
-import { loadHostHooksPolicyFromProject } from "../policy/host-hooks.js";
+import { loadHostHooksPolicyFromProject, UNUSED_HOST_HOOKS_RECOVERY, } from "../policy/host-hooks.js";
 function isDirectory(path) {
     try {
         return statSync(path).isDirectory();
@@ -30,9 +30,8 @@ export function evaluateAgentHooks(projectRoot, hostHooksPolicy = loadHostHooksP
                 unhealthy
                     .map((entry) => `  - ${entry.host}: ${entry.status} at ${entry.path} — ${entry.detail}`)
                     .join("\n") +
-                "\n  Recovery: run `deft update` (or `directive init`) to refresh project hooks." +
-                " If a failed host is intentionally unused, inspect `deft policy:show --field=hostHooks`, " +
-                "set `plan.policy.hostHooks.<host> = false`, and run `deft update` again.",
+                "\n  Recovery: run `deft update` (or `directive init`) to refresh project hooks. " +
+                UNUSED_HOST_HOOKS_RECOVERY,
             stream: "stderr",
             registrations,
         };