@deftai/directive-core 0.106.0 → 0.108.0

package/dist/preflight/evaluate.js

@@ -11,6 +11,26 @@ export const ACTIVE_FOLDER = "active";
 export const ELIGIBLE_STATUS = "running";
 /** Actionable redirect appended to every reject path (#810 / #2449). */
 export const ACTIVATE_HINT = "Run `task scope:activate -- {path}` (or legacy `task vbrief:activate -- {path}`) before spawning an implementation agent.";
+/**
+ * Recovery for the origin-freshness reject (#3828).
+ *
+ * Freshness is only reached after the active/ + running checks pass, so
+ * `ACTIVATE_HINT` names a transition that cannot apply here: `activate` accepts
+ * `pending/` alone and fails with `Invalid transition: 'activate' requires file
+ * in pending/`. `block` -> `unblock` is in place (`targetFolder: null`), requires
+ * and restores `running`, and stamps `plan.updated` plus `xBRIEFInfo.updated`,
+ * the field this reject compares. It is interim: the pair also records a
+ * `blocked` -> `running` transition for a brief that was never blocked, a
+ * tradeoff accepted knowingly. #3857 owns the dedicated acknowledge verb.
+ */
+export const ORIGIN_FRESHNESS_HINT = "Recovery: this xBRIEF is already in active/ at status running. " +
+    "Once you have re-read the origin delta, stamp xBRIEFInfo.updated in place with " +
+    "`task scope:block -- {path}` then `task scope:unblock -- {path}`. " +
+    "That pair is interim: it records a blocked -> running transition for a brief " +
+    "that was never blocked, and #3857 owns the verb that records the " +
+    "acknowledgement honestly. If the origin could not be fetched or compared, " +
+    "restore `gh` REST access to the origin repository first -- a stamp does not " +
+    "clear that.";
 /** Lifecycle folder names eligible for implementation (#810). */
 export const ELIGIBLE_LIFECYCLE_DIRS = ["xbrief/active", "vbrief/active"];
 export const PREFLIGHT_USAGE_HINT = "Expected: `task xbrief:preflight -- xbrief/active/<story>.xbrief.json` (legacy: `task vbrief:preflight -- <path>`).";
@@ -18,8 +38,12 @@ export const PREFLIGHT_USAGE_HINT = "Expected: `task xbrief:preflight -- xbrief/
 export function formatActivateHint(path) {
     return ACTIVATE_HINT.replace("{path}", () => path);
 }
-function buildReject(path, reason) {
-    return `${reason}\n  ${PREFLIGHT_USAGE_HINT}\n  ${formatActivateHint(path)}`;
+/** Substitute every `{path}` without `$`-pattern expansion in user paths (#1721). */
+export function formatOriginFreshnessHint(path) {
+    return ORIGIN_FRESHNESS_HINT.split("{path}").join(path);
+}
+function buildReject(path, reason, hint) {
+    return `${reason}\n  ${PREFLIGHT_USAGE_HINT}\n  ${hint ?? formatActivateHint(path)}`;
 }
 /** Map Node `JSON.parse` errors to CPython `json.JSONDecodeError.msg` for parity (#1721). */
 function nodeJsonErrorToPythonMsg(nodeMessage) {
@@ -167,7 +191,9 @@ export function evaluate(vbriefPath, options = {}) {
         return {
             exitCode: 1,
             parentLineage: lineage,
-            message: buildReject(path, originFreshness.message),
+            // #3828: the brief is active + running by this point, so the activate
+            // hint would name a transition that hard-errors from the printed state.
+            message: buildReject(path, originFreshness.message, formatOriginFreshnessHint(path)),
         };
     }
     // #3425: fail closed when an applicable project invariant has no disposition.

package/dist/preflight-cache/evaluate.js

@@ -300,13 +300,19 @@ function formatDriftFailure(repo, drift) {
     };
 }
 function runDriftProbe(resolvedRepo, cacheRoot, source, options) {
-    if (options.probeDriftFn) {
-        return options.probeDriftFn(resolvedRepo, cacheRoot, source);
-    }
     try {
+        if (options.probeDriftFn) {
+            return options.probeDriftFn(resolvedRepo, cacheRoot, source);
+        }
         return probeCacheDrift({ repo: resolvedRepo, source, cacheRoot });
     }
     catch {
+        // Deliberate fail-open (#3738 / #3422): a thrown probe (429 after retry,
+        // 502/503, DNS, auth) returns null; evaluate treats null as pass.
+        // Work-selection / session:start still inherit this. The write path no
+        // longer executes cache_fresh, so this is not a write-authorization bypass.
+        // Do not silently convert to fail-closed without revisiting #3422 (local
+        // work MAY continue when it does not need the forge).
         return null;
     }
 }

package/dist/product-first-done-gate/acceptance-resolver.d.ts

@@ -93,18 +93,30 @@ export declare function resolveAcceptanceVerdict(reading: AcceptanceReading): Ac
 /** One line naming the predicate and the value it read (#3497). */
 export declare function formatAcceptanceVerdict(verdictResult: AcceptanceVerdict): string;
 /**
- * Clause-walk composition (#3323 / #3497).
+ * Clause-walk composition (#3323 / #3497 / #3826).
  *
  * A clause the shipped artifact contradicts (`failed`) always blocks. A clause the
  * static walk cannot decide (`unverifiable`) is evidence of nothing — it blocks only
  * when nothing else verified the product. A green executable acceptance run IS that
  * something: the product-first oracle already ran. Before #3497 an all-unverifiable
  * clause set refused an artifact whose stated command had just exited 0.
+ *
+ * #3826 excused a set the walk has no oracle for at all: a clause with no bound
+ * artifact path can only ever come back `unverifiable`, so demanding a positive
+ * `verified` from a set of them cannot be satisfied by doing the work correctly.
+ * Where the walk has no oracle, `failed === 0` is the strongest verdict available
+ * and `evaluateAcceptanceEvidenceGate` adjudicates those criteria at `scope:complete`.
+ *
+ * #3835 makes that excusal per clause. As a *set* predicate, `verified > 0` was
+ * re-armed for every clause by any single bound one, so one verified binding
+ * covered siblings that had their own oracle and did not meet it.
+ * `adjudicableUnverified` counts exactly those siblings.
  */
 export declare function clauseWalkBlocks(input: {
     readonly failed: number;
-    readonly verified: number;
     readonly walked: number;
+    /** Clauses the walk had an oracle for and that did not come back `verified`. */
+    readonly adjudicableUnverified: number;
     readonly hasGreenExecutableRun: boolean;
 }): boolean;
 /** Which consumer is reading acceptance. Selects one shared option profile (#3497). */

package/dist/product-first-done-gate/acceptance-resolver.js

@@ -106,19 +106,30 @@ export function formatAcceptanceVerdict(verdictResult) {
     return `${lead}\n  remedy: ${verdictResult.remedy}`;
 }
 /**
- * Clause-walk composition (#3323 / #3497).
+ * Clause-walk composition (#3323 / #3497 / #3826).
  *
  * A clause the shipped artifact contradicts (`failed`) always blocks. A clause the
  * static walk cannot decide (`unverifiable`) is evidence of nothing — it blocks only
  * when nothing else verified the product. A green executable acceptance run IS that
  * something: the product-first oracle already ran. Before #3497 an all-unverifiable
  * clause set refused an artifact whose stated command had just exited 0.
+ *
+ * #3826 excused a set the walk has no oracle for at all: a clause with no bound
+ * artifact path can only ever come back `unverifiable`, so demanding a positive
+ * `verified` from a set of them cannot be satisfied by doing the work correctly.
+ * Where the walk has no oracle, `failed === 0` is the strongest verdict available
+ * and `evaluateAcceptanceEvidenceGate` adjudicates those criteria at `scope:complete`.
+ *
+ * #3835 makes that excusal per clause. As a *set* predicate, `verified > 0` was
+ * re-armed for every clause by any single bound one, so one verified binding
+ * covered siblings that had their own oracle and did not meet it.
+ * `adjudicableUnverified` counts exactly those siblings.
  */
 export function clauseWalkBlocks(input) {
     if (input.failed > 0) {
         return true;
     }
-    if (input.walked === 0 || input.verified > 0) {
+    if (input.walked === 0 || input.adjudicableUnverified === 0) {
         return false;
     }
     return !input.hasGreenExecutableRun;

package/dist/product-first-done-gate/evaluate.js

@@ -10,14 +10,14 @@
 import { existsSync, readFileSync } from "node:fs";
 import { basename, isAbsolute, relative, resolve } from "node:path";
 import { emitAcceptanceStampFromPlan, MISSING_AMBIGUITY_ATTESTATION_CAUSE, stampedAmbiguityAttestationError, } from "../intake/clause-derivation.js";
-import { appendLiteralAcceptanceAdvisory, evaluateLiteralAcceptanceFromPlan, isNoopRefusalReason, runLiteralAcceptanceCommands, stripLiteralAcceptanceAdvisory, } from "../literal-acceptance/index.js";
+import { appendLiteralAcceptanceAdvisory, evaluateLiteralAcceptanceFromPlan, isExecutableLiteralSource, isInlineProseMention, isNoopRefusalReason, readNotAcceptanceCommands, readStoredLiteralAcceptanceCommands, runLiteralAcceptanceCommands, stripLiteralAcceptanceAdvisory, } from "../literal-acceptance/index.js";
 import { ENV_RUN_SUMMARY_PATH, RunSummaryEmitter, } from "../run-summary/index.js";
 import { maybeBankOnAcPass } from "../session/ac-pass-banking.js";
 import { resolveAcReuse, resolveScopeIdForAcReuse, snapshotFromReuseFields, } from "../session/ac-pass-reuse.js";
 import { gitHead } from "../session/git.js";
 import { hashProductState } from "../session/product-state-hash.js";
 import { resolveVerifyAcSessionId, writeVerifyAcSessionCache, } from "../session/verify-ac-session-cache.js";
-import { formatClauseWalkMessage, walkAcceptanceClauses, } from "../verify-ac/clauses.js";
+import { countUnverifiedAdjudicableClauses, formatClauseWalkMessage, readDeclaredArtifactScope, walkAcceptanceClauses, } from "../verify-ac/clauses.js";
 import { emitVerifyAcAttempts, evaluateProductOracleIntegrity, mergeOracleVerdict, } from "../verify-ac/evaluate.js";
 import { readPlanAcceptance, validatePlanAcceptance } from "./acceptance.js";
 import { clauseWalkBlocks, formatAcceptanceVerdict, resolveAcceptanceVerdict, } from "./acceptance-resolver.js";
@@ -205,9 +205,10 @@ export function evaluateVerifyAcFromPlan(plan, options = {}) {
     // the #3267 ledger is a parallel store and can be empty while stated commands exist.
     // Stated was previously excluded, so rung=stated + empty ledger printed "nothing to run".
     // Do not override a blocking rejected ledger or a config error.
-    if (shouldRunPlanAcceptanceDirectly(base, acceptance)) {
+    if (shouldRunPlanAcceptanceDirectly(base, acceptance, plan)) {
         const runner = optionsWithScope.runner;
-        const direct = runLiteralAcceptanceCommands(acceptance.commands.map((c) => ({
+        const directCommands = statedAcceptanceCommands(acceptance, plan);
+        const direct = runLiteralAcceptanceCommands(directCommands.map((c) => ({
             command: c.command,
             cwd: c.cwd ?? null,
             expectedStdout: c.expectedStdout ?? null,
@@ -271,8 +272,38 @@ export function evaluateVerifyAcFromPlan(plan, options = {}) {
     }
     return applyOracle(annotate(base, acceptance, optionsWithScope.quiet), optionsWithScope, plan);
 }
-function shouldRunPlanAcceptanceDirectly(base, acceptance) {
-    if (acceptance.commands.length === 0)
+function hasNonDefaultAcceptanceContext(command) {
+    const cwd = command.cwd !== undefined && command.cwd !== null && String(command.cwd).trim();
+    const stdout = command.expectedStdout !== undefined &&
+        command.expectedStdout !== null &&
+        String(command.expectedStdout).length > 0;
+    const exit = typeof command.expectedExitCode === "number" && command.expectedExitCode !== 0;
+    return Boolean(cwd) || stdout || exit;
+}
+function hasStructuredAcceptancePeer(plan, command) {
+    return readStoredLiteralAcceptanceCommands(plan).some((c) => c.command === command && isExecutableLiteralSource(c.source));
+}
+/**
+ * True when a plan.acceptance.commands row is only an ingest copy of an inline
+ * prose mention (or an operator not-command disposition) and has no structured
+ * peer. Independently authored rows — promoted verify_commands, or a command
+ * with its own cwd/expectedStdout/exit — still run (#3721 Greptile).
+ */
+function isInlineScrapedAcceptanceCommand(plan, command) {
+    if (hasNonDefaultAcceptanceContext(command))
+        return false;
+    if (hasStructuredAcceptancePeer(plan, command.command))
+        return false;
+    if (readNotAcceptanceCommands(plan).has(command.command))
+        return true;
+    return readStoredLiteralAcceptanceCommands(plan).some((c) => c.command === command.command && isInlineProseMention(c));
+}
+/** plan.acceptance.commands minus ingest-copied inline mentions (#3721). */
+function statedAcceptanceCommands(acceptance, plan) {
+    return acceptance.commands.filter((c) => !isInlineScrapedAcceptanceCommand(plan, c));
+}
+function shouldRunPlanAcceptanceDirectly(base, acceptance, plan) {
+    if (statedAcceptanceCommands(acceptance, plan).length === 0)
         return false;
     if (base.runs.length > 0)
         return false;
@@ -444,21 +475,24 @@ export function emitVerifyAcTerminalOutcome(input) {
         resolvedCommandCount: 0,
     }, { projectRoot: input.projectRoot, env: input.env }, resolve(input.projectRoot));
 }
-function applyClauseWalk(result, options) {
+function applyClauseWalk(result, options, plan) {
     const clauses = result.acceptance.clauses ?? [];
     if (clauses.length === 0 || result.resolution === "config" || result.resolution === "skipped") {
         return result;
     }
     const projectRoot = resolve(options.projectRoot ?? process.cwd());
-    const report = walkAcceptanceClauses(clauses, projectRoot);
+    // #3835: the walk reads files, so it reads only what this brief declared.
+    const report = walkAcceptanceClauses(clauses, projectRoot, {
+        declaredScope: readDeclaredArtifactScope(plan),
+    });
     const message = options.quiet ? result.message : formatClauseWalkMessage(report, result.message);
     // #3497: a clause the static walk cannot decide is evidence of nothing. It blocks
     // only when nothing else verified the product; a green executable acceptance run
     // already is the product-first oracle. Failed clauses still block unconditionally.
     const blocked = clauseWalkBlocks({
         failed: report.failed.length,
-        verified: report.verified.length,
         walked: report.clauses.length,
+        adjudicableUnverified: countUnverifiedAdjudicableClauses(report.clauses),
         hasGreenExecutableRun: result.ok && result.runs.length > 0 && result.runs.every((run) => run.ok),
     });
     const ok = result.ok && !blocked;
@@ -467,8 +501,10 @@ function applyClauseWalk(result, options) {
         ok,
         code: ok ? result.code : result.code === 2 ? 2 : 1,
         message,
+        // #3835: only a clause that actually verified may relabel an empty pass as
+        // verified. A walk that verified nothing has not verified anything.
         resolution: ok
-            ? result.resolution === "empty-pass"
+            ? result.resolution === "empty-pass" && report.verified.length > 0
                 ? "verified-pass"
                 : result.resolution
             : "fail",
@@ -518,8 +554,13 @@ function labelVerdict(result) {
 }
 function applyOracle(result, options, plan = {}) {
     const projectRoot = resolve(options.projectRoot ?? process.cwd());
-    const walked = applyClauseWalk(applyRejectedNoop(result), options);
-    const gated = walked.clauseWalked === true ? walked : applyEmptyFloorPolicy(walked, options);
+    const walked = applyClauseWalk(applyRejectedNoop(result), options, plan);
+    // #3835: the clause walk may stand in for the empty floor only when it actually
+    // verified something. A walk that verified nothing is not positive evidence, so
+    // an otherwise-empty acceptance still answers to the project floor rather than
+    // passing on the strength of a clause set nothing adjudicated.
+    const walkVerified = (walked.clauseOutcomes ?? []).some((row) => row.outcome === "verified");
+    const gated = walked.clauseWalked === true && walkVerified ? walked : applyEmptyFloorPolicy(walked, options);
     // Emit/read disk only when the caller supplied env (CLI passes process.env).
     // Tests stay isolated unless they opt in with env or runSummaryText.
     if (options.env !== undefined) {

package/dist/release/cli-drift-report.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Local-vs-released CLI drift report after a cut (#3753).
+ *
+ * Report-only: never runs `npm i -g`. Never fails the release. Polls all four
+ * workspace packages with `--prefer-online` so a lag-poisoned npm cache cannot
+ * masquerade as a missing publish.
+ */
+import { type ActiveCliCheckResult } from "../session/active-cli.js";
+import type { ReleaseConfig } from "./types.js";
+/** Workspace packages published by npm-publish.yml (sibling propagate is not atomic). */
+export declare const WORKSPACE_PACKAGES: readonly ["@deftai/directive-types", "@deftai/directive-core", "@deftai/directive-content", "@deftai/directive"];
+export type WorkspacePackageName = (typeof WORKSPACE_PACKAGES)[number];
+/** Observed sibling lag was ~7 minutes; Phase 7 wait sits under this ceiling. */
+export declare const CLI_DRIFT_POLL_TIMEOUT_MS: number;
+export declare const CLI_DRIFT_POLL_INTERVAL_MS = 30000;
+/** Pipeline completion is a single probe — Step 13 returns before npm-publish.yml is green. */
+export declare const CLI_DRIFT_PIPELINE_POLL_TIMEOUT_MS = 0;
+export type RegistryVisibility = "all-visible" | "still-propagating" | "publish-incomplete" | "skipped";
+export interface WorkspacePackageProbe {
+    readonly name: WorkspacePackageName;
+    readonly visible: boolean;
+    readonly version: string | null;
+}
+export interface CliDriftReport {
+    readonly releasedVersion: string;
+    readonly localVersion: string | null;
+    readonly localPath: string | null;
+    readonly match: boolean;
+    readonly shadowed: boolean;
+    readonly registry: RegistryVisibility;
+    readonly packages: readonly WorkspacePackageProbe[];
+    readonly remediation: string;
+    readonly lines: readonly string[];
+}
+export interface CliDriftReportSeams {
+    readonly checkActiveCli?: (targetVersion: string) => ActiveCliCheckResult;
+    readonly viewPackage?: (name: WorkspacePackageName, version: string) => WorkspacePackageProbe;
+    readonly nowMs?: () => number;
+    readonly sleepMs?: (ms: number) => void;
+}
+export declare function remediationCommand(version: string): string;
+export declare function npmViewArgs(name: WorkspacePackageName, version: string): string[];
+export declare function defaultViewWorkspacePackage(name: WorkspacePackageName, version: string): WorkspacePackageProbe;
+export declare function classifyRegistryVisibility(opts: {
+    readonly probes: readonly WorkspacePackageProbe[];
+    readonly waitExhausted: boolean;
+    readonly skipped: boolean;
+}): RegistryVisibility;
+export declare function pollWorkspacePackages(version: string, opts: {
+    readonly timeoutMs: number;
+    readonly intervalMs?: number;
+    readonly viewPackage: (name: WorkspacePackageName, version: string) => WorkspacePackageProbe;
+    readonly nowMs?: () => number;
+    readonly sleepMs?: (ms: number) => void;
+}): {
+    readonly probes: readonly WorkspacePackageProbe[];
+    readonly waitExhausted: boolean;
+};
+export declare function shouldSkipRegistryPoll(config: Pick<ReleaseConfig, "dryRun" | "skipTag" | "version">, env?: NodeJS.ProcessEnv): boolean;
+export declare function buildCliDriftReport(releasedVersion: string, opts?: {
+    readonly skipRegistryPoll: boolean;
+    readonly pollTimeoutMs?: number;
+    readonly pollIntervalMs?: number;
+} & CliDriftReportSeams): CliDriftReport;
+export declare function formatCliDriftReport(report: CliDriftReport): string;
+/** Best-effort wrapper — a report failure must never fail the cut. */
+export declare function emitCliDriftReportBestEffort(releasedVersion: string, opts: Parameters<typeof buildCliDriftReport>[1], write?: (text: string) => void): void;
+//# sourceMappingURL=cli-drift-report.d.ts.map

package/dist/release/cli-drift-report.js

@@ -0,0 +1,189 @@
+/**
+ * Local-vs-released CLI drift report after a cut (#3753).
+ *
+ * Report-only: never runs `npm i -g`. Never fails the release. Polls all four
+ * workspace packages with `--prefer-online` so a lag-poisoned npm cache cannot
+ * masquerade as a missing publish.
+ */
+import { spawnSync } from "node:child_process";
+import { PUBLIC_NPM_REGISTRY } from "../doctor/constants.js";
+import { checkActiveCliAgainstTarget } from "../session/active-cli.js";
+import { RELEASE_E2E_ENV } from "./skip-ci-incident.js";
+/** Same sentinel as release-e2e `REHEARSAL_VERSION` — do not poll npm for 0.0.1. */
+const REHEARSAL_VERSION = "0.0.1";
+/** Workspace packages published by npm-publish.yml (sibling propagate is not atomic). */
+export const WORKSPACE_PACKAGES = [
+    "@deftai/directive-types",
+    "@deftai/directive-core",
+    "@deftai/directive-content",
+    "@deftai/directive",
+];
+/** Observed sibling lag was ~7 minutes; Phase 7 wait sits under this ceiling. */
+export const CLI_DRIFT_POLL_TIMEOUT_MS = 10 * 60 * 1000;
+export const CLI_DRIFT_POLL_INTERVAL_MS = 30_000;
+/** Pipeline completion is a single probe — Step 13 returns before npm-publish.yml is green. */
+export const CLI_DRIFT_PIPELINE_POLL_TIMEOUT_MS = 0;
+export function remediationCommand(version) {
+    return `npm i -g @deftai/directive@${version} --prefer-online`;
+}
+export function npmViewArgs(name, version) {
+    return [
+        "view",
+        `${name}@${version}`,
+        "version",
+        "--prefer-online",
+        "--ignore-scripts",
+        `--registry=${PUBLIC_NPM_REGISTRY}`,
+    ];
+}
+export function defaultViewWorkspacePackage(name, version) {
+    try {
+        const result = spawnSync("npm", npmViewArgs(name, version), {
+            encoding: "utf8",
+            timeout: 15_000,
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+        });
+        const raw = typeof result.stdout === "string" ? result.stdout : "";
+        const seen = raw.trim().split(/\r?\n/)[0]?.trim() ?? "";
+        const visible = result.status === 0 && seen === version;
+        return { name, visible, version: seen.length > 0 ? seen : null };
+    }
+    catch {
+        return { name, visible: false, version: null };
+    }
+}
+export function classifyRegistryVisibility(opts) {
+    if (opts.skipped)
+        return "skipped";
+    const visibleCount = opts.probes.filter((p) => p.visible).length;
+    if (opts.probes.length > 0 && visibleCount === opts.probes.length)
+        return "all-visible";
+    if (visibleCount === 0 && opts.waitExhausted)
+        return "publish-incomplete";
+    return "still-propagating";
+}
+export function pollWorkspacePackages(version, opts) {
+    const now = opts.nowMs ?? Date.now;
+    const sleep = opts.sleepMs ?? (() => undefined);
+    const interval = opts.intervalMs ?? CLI_DRIFT_POLL_INTERVAL_MS;
+    const start = now();
+    let probes = WORKSPACE_PACKAGES.map((name) => opts.viewPackage(name, version));
+    if (probes.every((p) => p.visible)) {
+        return { probes, waitExhausted: false };
+    }
+    if (opts.timeoutMs <= 0) {
+        return { probes, waitExhausted: false };
+    }
+    while (now() - start < opts.timeoutMs) {
+        const remaining = opts.timeoutMs - (now() - start);
+        if (remaining <= 0)
+            break;
+        sleep(Math.min(interval, remaining));
+        probes = WORKSPACE_PACKAGES.map((name) => opts.viewPackage(name, version));
+        if (probes.every((p) => p.visible)) {
+            return { probes, waitExhausted: false };
+        }
+    }
+    return { probes, waitExhausted: true };
+}
+export function shouldSkipRegistryPoll(config, env = process.env) {
+    if (config.dryRun || config.skipTag)
+        return true;
+    if (config.version === REHEARSAL_VERSION)
+        return true;
+    if (env[RELEASE_E2E_ENV])
+        return true;
+    if (env.CI === "true" || env.GITHUB_ACTIONS === "true")
+        return true;
+    // Unit tests never probe the live registry; production `task release` does not set VITEST.
+    if (env.VITEST)
+        return true;
+    return false;
+}
+function formatRegistryLine(registry, packages) {
+    if (registry === "skipped") {
+        return "  registry: skipped (dry-run / skip-tag / rehearsal / CI — no publish to poll)";
+    }
+    const visible = packages.filter((p) => p.visible).map((p) => p.name);
+    const missing = packages.filter((p) => !p.visible).map((p) => p.name);
+    const counts = `visible ${visible.length}/${packages.length}`;
+    if (registry === "all-visible") {
+        return `  registry: all-visible (${counts})`;
+    }
+    if (registry === "publish-incomplete") {
+        return `  registry: publish-incomplete (${counts}; none of the four packages resolved after the wait)`;
+    }
+    const missingText = missing.length > 0 ? `; missing: ${missing.join(", ")}` : "";
+    return `  registry: still-propagating (${counts}${missingText})`;
+}
+export function buildCliDriftReport(releasedVersion, opts = { skipRegistryPoll: false }) {
+    const check = opts.checkActiveCli ?? ((target) => checkActiveCliAgainstTarget(target));
+    const cli = check(releasedVersion);
+    const localVersion = cli.active?.version ?? null;
+    const localPath = cli.active?.path ?? null;
+    const match = localVersion !== null && localVersion === releasedVersion && cli.ok;
+    const shadowed = !cli.ok && cli.candidates.length > 0;
+    let packages = [];
+    let waitExhausted = false;
+    if (!opts.skipRegistryPoll) {
+        const view = opts.viewPackage ?? defaultViewWorkspacePackage;
+        const polled = pollWorkspacePackages(releasedVersion, {
+            timeoutMs: opts.pollTimeoutMs ?? CLI_DRIFT_PIPELINE_POLL_TIMEOUT_MS,
+            intervalMs: opts.pollIntervalMs,
+            viewPackage: view,
+            nowMs: opts.nowMs,
+            sleepMs: opts.sleepMs,
+        });
+        packages = polled.probes;
+        waitExhausted = polled.waitExhausted;
+    }
+    const registry = classifyRegistryVisibility({
+        probes: packages,
+        waitExhausted,
+        skipped: opts.skipRegistryPoll,
+    });
+    const remediation = remediationCommand(releasedVersion);
+    const localLabel = localVersion === null
+        ? "none on PATH"
+        : `${localVersion}${localPath !== null ? ` (${localPath})` : ""}`;
+    const lines = [
+        "CLI drift report (#3753):",
+        `  released: ${releasedVersion}`,
+        `  local global CLI: ${localLabel}`,
+        `  match: ${match ? "yes" : "no"}`,
+        ...(shadowed
+            ? ["  note: PATH-shadowed install — bare deft --version is not sufficient (#3233)"]
+            : []),
+        formatRegistryLine(registry, packages),
+        `  remediation: ${remediation}`,
+        "  note: report-only — this pipeline does not run npm i -g",
+    ];
+    return {
+        releasedVersion,
+        localVersion,
+        localPath,
+        match,
+        shadowed,
+        registry,
+        packages,
+        remediation,
+        lines,
+    };
+}
+export function formatCliDriftReport(report) {
+    return `${report.lines.join("\n")}\n`;
+}
+/** Best-effort wrapper — a report failure must never fail the cut. */
+export function emitCliDriftReportBestEffort(releasedVersion, opts, write = (text) => {
+    process.stderr.write(text);
+}) {
+    try {
+        write(formatCliDriftReport(buildCliDriftReport(releasedVersion, opts)));
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        write(`CLI drift report (#3753): skipped (${reason.replace(/\r?\n/g, " ")})\n`);
+    }
+}
+//# sourceMappingURL=cli-drift-report.js.map

package/dist/release/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./auto-hatch.js";
 export * from "./build-dist.js";
+export * from "./cli-drift-report.js";
 export * from "./closed-verb-gate.js";
 export * from "./constants.js";
 export * from "./coverage-debt-ledger.js";

package/dist/release/index.js

@@ -1,6 +1,7 @@
 /* v8 ignore file -- re-export barrel; covered via main.ts */
 export * from "./auto-hatch.js";
 export * from "./build-dist.js";
+export * from "./cli-drift-report.js";
 export * from "./closed-verb-gate.js";
 export * from "./constants.js";
 export * from "./coverage-debt-ledger.js";

package/dist/release/issue-state-fetch.d.ts

@@ -1,4 +1,4 @@
-import { type FetchIssueStatesOptions } from "../intake/reconcile-issues.js";
+import { IssueState } from "../intake/reconcile-issues.js";
 import { type CallOptions, type CompletedProcess } from "../scm/call.js";
 export type ScmCallFn = (source: string, verb: string, args: readonly string[] | null, options?: CallOptions) => CompletedProcess;
 /** Max seconds to sleep before the single rate-limit retry (operator-locked cap). */
@@ -9,13 +9,15 @@ export interface RateLimitProbe {
     readonly coreResetUnix: number | null;
     readonly graphqlRemaining: number | null;
 }
-export interface FetchIssueStatesForReleaseOptions extends FetchIssueStatesOptions {
+export interface FetchIssueStatesForReleaseOptions {
+    readonly cwd?: string;
+    readonly scmCall?: ScmCallFn;
     readonly sleep?: SleepFn;
     readonly now?: () => number;
 }
 export type FetchIssueStatesForReleaseResult = {
     readonly ok: true;
-    readonly states: Map<number, import("../intake/reconcile-issues.js").IssueState>;
+    readonly states: Map<number, IssueState>;
 } | {
     readonly ok: false;
     readonly reason: string;