@deftai/directive-core 0.99.0 → 0.101.0

package/dist/doctor/main.js

@@ -1,25 +1,22 @@
 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";
 import { detectNoDeftDirective, NO_DEFT_DIRECTIVE_DISABLED_MESSAGE, NO_DEFT_DIRECTIVE_FLAG_NAME, NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE, NO_DEFT_DIRECTIVE_INCONSISTENT_POLICY, } from "../policy/no-deft-directive.js";
 import { describeShadowedPlanExtension, detectShadowedPlanExtensions, } from "../policy/plan-extensions.js";
 import { loadProjectDefinition } from "../policy/resolve.js";
 import { checkLocalEngineIntegrity, classify, detectPackageManager, evaluateSkew, reconcileVersions, plan as resolvePlan, } from "../resolution/index.js";
-import { classifyXbriefSchemaDistance } from "../staleness-tickler/probe-xbrief.js";
 import { resolveUserMdPath } from "../user-config/resolve-user-md.js";
 import { evaluateAgentHooks } from "../verify-env/agent-hooks.js";
 import { probeAgentHooksLive } from "../verify-env/agent-hooks-live-probe.js";
-import { readDeclaredArtifactVersion } from "../xbrief-migrate/transforms.js";
 import { agentsRefreshPlan, hasV3ManagedMarker } from "./agents-md.js";
-import { runChecks } from "./checks.js";
+import { checkXbriefEnvelopeMajorVersion, runChecks, XBRIEF_ENVELOPE_MAJOR_CHECK, XBRIEF_ENVELOPE_MIGRATE_COMMAND, } from "./checks.js";
 import { CONSUMER_FRAMEWORK_DIRS, EXPECTED_CONTENT_DIRS, EXPECTED_FRAMEWORK_DIRS, NETWORK_DISCLOSURE_LINE, PAYLOAD_STALENESS_OFFLINE_SKIP_MESSAGE, TASKFILE_INCLUDE_SNIPPET, UV_INSTALL_URL, } from "./constants.js";
 import { decideThrottle, formatIsoZ, readState, renderDoctorStatusLine, writeState, } from "./doctor-state.js";
 import { formatAllowedFlagsHint, formatUnknownFlagsError, parseDoctorFlags } from "./flags.js";
+import { formatDoctorHelp } from "./help.js";
 import { pythonJsonDump } from "./json.js";
 import { parseInstallRootFromAgentsMd } from "./manifest.js";
 import { runNpmRegistryMirrorCheck } from "./npm-registry.js";
@@ -29,12 +26,11 @@ import { runOpenClawSoftRebindCheck } from "./openclaw-soft-rebind.js";
 import { createPlainSink } from "./output.js";
 import { readTextSafe, resolveFrameworkRootForProject, resolvePath, resolveVersion, runningInsideDeftRepo, } from "./paths.js";
 import { runPayloadStalenessCheck } from "./payload-staleness.js";
+import { loadSessionCodas, projectRootRealpath, resolveSessionCodaLine, SESSION_CODA_ENV, sessionCodaMode, shouldEmitSessionCodaLine, utcDateYmd, } from "./session-coda.js";
 import { runLocalSignpostChecks } from "./signpost-checks.js";
 import { classifyTaskfileInclude, formatGatesSurfaceDualRemediation, formatMissingIncludeSnippet, GATES_SURFACE_DEFT_REMEDIATION, includesBlockHasDeftTaskfile, resolveConsumerTaskfile, } from "./taskfile.js";
 import { defaultWhich } from "./which.js";
 const DEFAULT_RESOLUTION_PLATFORMS = ["linux", "darwin", "win32"];
-/** Next-action command for project-envelope behind-major (#2971). */
-const XBRIEF_ENVELOPE_MIGRATE_COMMAND = "deft migrate:xbrief";
 /**
  * Read the `packageManager` field (Corepack) from a project package.json, or
  * null when absent/unreadable. Lets the doctor detect a pnpm project that has
@@ -64,6 +60,10 @@ export function cmdDoctor(args, seams = {}) {
         sink.info(formatAllowedFlagsHint());
         return 2;
     }
+    if (flags.help) {
+        process.stdout.write(formatDoctorHelp());
+        return 0;
+    }
     const sessionMode = flags.session;
     const fixMode = flags.fix && !sessionMode;
     const jsonMode = flags.json;
@@ -495,6 +495,15 @@ export function cmdDoctor(args, seams = {}) {
     sink.blank();
     if (errorCount === 0 && warningCount === 0) {
         sink.finalSuccess("System check passed!");
+        emitSessionCodaAfterFinalSuccess({
+            projectRoot,
+            frameworkRoot,
+            jsonMode,
+            exitOk: true,
+            now: nowFn(),
+            seams,
+            sink,
+        });
         return 0;
     }
     if (errorCount) {
@@ -504,8 +513,51 @@ export function cmdDoctor(args, seams = {}) {
         return 1;
     }
     sink.finalWarn(`System check completed with ${warningCount} warning(s).`);
+    emitSessionCodaAfterFinalSuccess({
+        projectRoot,
+        frameworkRoot,
+        jsonMode,
+        exitOk: true,
+        now: nowFn(),
+        seams,
+        sink,
+    });
     return 0;
 }
+/**
+ * After the final human success footer only (D2): optional off-hint or ✦ coda.
+ * Never mid-run Next command: block; never JSON; never hard-fail path (D1).
+ */
+function emitSessionCodaAfterFinalSuccess(input) {
+    const stdoutIsTty = input.seams.stdoutIsTty ?? (() => process.stdout.isTTY === true);
+    // `in` so tests can force unset via `{ sessionCodaEnv: undefined }` without
+    // leaking the host process env.
+    const envRaw = "sessionCodaEnv" in input.seams ? input.seams.sessionCodaEnv : process.env[SESSION_CODA_ENV];
+    const ciRaw = "ciEnv" in input.seams ? input.seams.ciEnv : process.env.CI;
+    const ci = Boolean(ciRaw && ciRaw !== "0" && String(ciRaw).toLowerCase() !== "false");
+    const shouldEmit = shouldEmitSessionCodaLine({
+        tty: stdoutIsTty(),
+        ci,
+        json: input.jsonMode,
+        exitOk: input.exitOk,
+    });
+    const mode = sessionCodaMode(envRaw);
+    const codas = mode === "on"
+        ? (input.seams.loadSessionCodas?.(input.frameworkRoot) ??
+            loadSessionCodas(input.frameworkRoot, input.seams.readText))
+        : [];
+    const line = resolveSessionCodaLine({
+        mode,
+        shouldEmit,
+        date: utcDateYmd(input.now),
+        projectRoot: projectRootRealpath(input.projectRoot),
+        codas,
+    });
+    if (line === null)
+        return;
+    input.sink.blank();
+    input.sink.raw(line);
+}
 export function runAgentHooksHealthCheck(projectRoot, consumerContext, sink, addFinding, seams) {
     const checkName = "agent-hooks-registration";
     if (!consumerContext) {
@@ -653,6 +705,11 @@ function runInstallIntegrityChecks(projectRoot, sink, addFinding, seams) {
             const name = String(entry.name ?? "install-integrity");
             const status = String(entry.status ?? "");
             const detail = String(entry.detail ?? "");
+            // Authoritative envelope-major emission is runXbriefEnvelopeVersionCheck
+            // (runs for framework repo + consumers). Skip install-integrity duplicate.
+            if (name === XBRIEF_ENVELOPE_MAJOR_CHECK) {
+                continue;
+            }
             if (status === "pass") {
                 sink.success(`${name}: pass`);
                 continue;
@@ -954,105 +1011,99 @@ function runTaskfileIncludeCheck(projectRoot, fixMode, jsonMode, sink, addFindin
     });
 }
 /**
- * Fail closed when PROJECT-DEFINITION under an xbrief/ layout still declares
- * envelope 0.6 while the framework schema is 0.8 (#2971). Greenfield (no
- * project definition yet) and current 0.8 envelopes pass. Unreadable paths
- * (test seams / permission) skip rather than false-positive fail. Behind-major
- * records `deft migrate:xbrief` as the next action — layout rename alone is not
- * enough. Distinct from deposited-schema (`stale-xbrief-schema-deposit`) which
- * must NOT route to migrate:xbrief when only framework schema files are stale.
+ * Fail closed when any scanned project xbrief lifecycle `*.xbrief.json` envelope
+ * declares a schema major behind the framework target (#2971 / #3243). Greenfield
+ * (no envelopes) skips. Behind-major records `deft migrate:xbrief` as the next
+ * action (hybrid in-place rewrite on already-xbrief trees — #3236). Distinct from
+ * deposited-schema (`stale-xbrief-schema-deposit`) which must NOT route to
+ * migrate:xbrief when only framework schema files are stale.
  */
 export function runXbriefEnvelopeVersionCheck(projectRoot, sink, addFinding, seams) {
-    const checkName = "xbrief-envelope-version";
-    const isFile = seams.isFile ?? ((p) => existsSync(p));
-    const readText = seams.readText ?? readTextSafe;
-    const targetVersion = VBRIEF_VERSION;
+    const checkName = XBRIEF_ENVELOPE_MAJOR_CHECK;
     if (seams.probeXbriefEnvelope) {
         const probe = seams.probeXbriefEnvelope(projectRoot);
         emitXbriefEnvelopeFinding(checkName, probe, sink, addFinding);
         return;
     }
-    let definitionPath;
-    try {
-        definitionPath = resolveProjectDefinitionPath(projectRoot);
-    }
-    catch {
-        // Pure vbrief/-only trees are already covered by layout migrate signposts.
-        const skipMessage = `${checkName}: skip -- legacy-only layout (use layout migrate first)`;
-        sink.info(skipMessage);
-        addFinding({
-            severity: "skip",
-            message: skipMessage,
-            check: checkName,
-            status: "skip",
-            reason: "legacy-only-layout",
-        });
-        return;
-    }
-    if (!isFile(definitionPath)) {
-        const skipMessage = `${checkName}: skip -- no PROJECT-DEFINITION yet (greenfield)`;
-        sink.info(skipMessage);
-        addFinding({
-            severity: "skip",
-            message: skipMessage,
-            check: checkName,
-            status: "skip",
-            reason: "no-project-definition",
-        });
-        return;
-    }
-    const text = readText(definitionPath);
-    if (text === null) {
-        // Unreadable path (permissions or injectable seams) is not proof of 0.6.
-        const skipMessage = `${checkName}: skip -- PROJECT-DEFINITION unreadable`;
+    const result = checkXbriefEnvelopeMajorVersion(projectRoot, {
+        ...(seams.readText ? { readText: seams.readText } : {}),
+        ...(seams.isFile ? { isFile: seams.isFile } : {}),
+        ...(seams.isDir ? { isDir: seams.isDir } : {}),
+    });
+    const data = (result.data ?? {});
+    const targetVersion = typeof data.target_version === "string"
+        ? data.target_version
+        : String(data.target_version ?? "");
+    const declaredFromData = data.declared_versions;
+    const declaredVersion = Array.isArray(declaredFromData)
+        ? (declaredFromData.find((v) => typeof v === "string") ?? null)
+        : null;
+    if (result.status === "skip") {
+        const skipMessage = `${checkName}: skip -- ${result.detail}`;
         sink.info(skipMessage);
         addFinding({
             severity: "skip",
             message: skipMessage,
             check: checkName,
             status: "skip",
-            reason: "unreadable",
+            reason: typeof data.reason === "string" ? data.reason : "skip",
+            target_version: targetVersion || undefined,
         });
         return;
     }
-    let declaredVersion = null;
-    try {
-        const parsed = JSON.parse(text);
-        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
-            declaredVersion = readDeclaredArtifactVersion(parsed);
-        }
-        else {
-            const skipMessage = `${checkName}: skip -- PROJECT-DEFINITION is not a JSON object`;
-            sink.info(skipMessage);
+    if (result.status === "pass") {
+        const status = typeof data.status === "string" ? data.status : "current";
+        if (status === "behind-minor") {
+            // Major-only check (#3243) does not fail closed, but surface an advisory
+            // when the shared scan observed behind-minor distance.
+            const warnMessage = `${checkName}: behind-minor -- ${result.detail}. Prefer \`${XBRIEF_ENVELOPE_MIGRATE_COMMAND}\` when convenient.`;
+            sink.warn(warnMessage);
             addFinding({
-                severity: "skip",
-                message: skipMessage,
+                severity: "warning",
+                message: warnMessage,
                 check: checkName,
-                status: "skip",
-                reason: "invalid-json-shape",
+                status: "behind-minor",
+                suggestion: XBRIEF_ENVELOPE_MIGRATE_COMMAND,
+                target_version: targetVersion || undefined,
+                next_command: XBRIEF_ENVELOPE_MIGRATE_COMMAND,
             });
             return;
         }
-    }
-    catch {
-        const skipMessage = `${checkName}: skip -- PROJECT-DEFINITION JSON parse failed`;
-        sink.info(skipMessage);
+        const okMessage = `${checkName}: ${result.detail}`;
+        sink.success(okMessage);
         addFinding({
             severity: "skip",
-            message: skipMessage,
+            message: okMessage,
             check: checkName,
-            status: "skip",
-            reason: "parse-error",
+            status: "current",
+            target_version: targetVersion || undefined,
         });
         return;
     }
-    const distance = classifyXbriefSchemaDistance(declaredVersion, targetVersion);
-    emitXbriefEnvelopeFinding(checkName, {
-        declaredVersion,
-        targetVersion,
-        distance,
-        stale: distance !== "current",
-    }, sink, addFinding);
+    // fail / error → behind-major fail closed (migratable 0.6 or non-migratable)
+    const status = typeof data.status === "string" ? data.status : "behind-major";
+    const nextCommand = typeof data.next_command === "string"
+        ? data.next_command
+        : data.next_command === null
+            ? null
+            : XBRIEF_ENVELOPE_MIGRATE_COMMAND;
+    const suggestion = typeof data.suggestion === "string"
+        ? data.suggestion
+        : (nextCommand ?? `set xBRIEFInfo.version to framework target`);
+    const message = `${checkName}: ${result.detail}`;
+    sink.error(message);
+    addFinding({
+        severity: "error",
+        message,
+        check: checkName,
+        status,
+        suggestion,
+        declared_version: declaredVersion,
+        target_version: targetVersion || undefined,
+        next_command: nextCommand,
+        sample_paths: data.sample_paths,
+        behind_major_count: data.behind_major_count,
+    });
 }
 function emitXbriefEnvelopeFinding(checkName, probe, sink, addFinding) {
     if (probe.distance === "current") {

package/dist/doctor/session-coda.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Optional deterministic session coda for interactive doctor success (#2712).
+ *
+ * Human TTY affordance only: never JSON, never AGENTS/skills, never exit-code
+ * changes. Env three-state DEFT_SESSION_CODA (unset / 1 / 0). Copy lives in
+ * content/doctor/session-coda.json — not embedded as an engine literal.
+ */
+/** Env var name (env-only v1; no USER.md key). */
+export declare const SESSION_CODA_ENV = "DEFT_SESSION_CODA";
+/**
+ * Fixed discoverability line when env is unset and gates pass (D3).
+ * Snapshot-stable; not selected from the pack; no ✦ prefix.
+ */
+export declare const SESSION_CODA_OFF_HINT = "Session coda: off (set DEFT_SESSION_CODA=1 to enable)";
+/** U+2726 FOUR RAYED STAR + space — stable; do not localize. */
+export declare const SESSION_CODA_STAR_PREFIX = "\u2726 ";
+/** Max body length; longer pack entries are skipped (fail-open). */
+export declare const SESSION_CODA_MAX_CHARS = 100;
+/** Relative path under contentRoot (source: content/doctor/…; deposit: doctor/…). */
+export declare const SESSION_CODA_REL_PATH: string;
+export type SessionCodaMode = "unset" | "on" | "off";
+/**
+ * Map DEFT_SESSION_CODA to the three-state mode (D3).
+ * - undefined / "" → unset (discoverability off-hint)
+ * - "1" → on (✦ coda)
+ * - "0" → off (silent)
+ * - any other non-empty value → unset (show correct enable form)
+ */
+export declare function sessionCodaMode(envValue: string | undefined): SessionCodaMode;
+/**
+ * Whether any extra line (off-hint or coda) is allowed (D1 + surface gates).
+ * TTY = stdout.isTTY; CI truthy blocks; json blocks; exitOk = errorCount === 0.
+ */
+export declare function shouldEmitSessionCodaLine(input: {
+    readonly tty: boolean;
+    readonly ci: boolean;
+    readonly json: boolean;
+    readonly exitOk: boolean;
+}): boolean;
+/**
+ * FNV-1a 32-bit (#2712). Documented choice for hash_u32(date + "\\0" + root).
+ * No Math.random; same inputs ⇒ same u32 on every platform.
+ */
+export declare function hashU32(input: string): number;
+/** UTC calendar date yyyy-mm-dd from a Date (stable for 24h across a team day). */
+export declare function utcDateYmd(date: Date): string;
+/** Best-effort realpath; falls back to the given path when realpath fails. */
+export declare function projectRootRealpath(projectRoot: string): string;
+/**
+ * Select one coda body from the pack (enabled path only).
+ * index = hash_u32(utc_date + "\\0" + project_root_realpath) % len(codas)
+ * Empty list → null (omit ✦; doctor still 0).
+ */
+export declare function selectSessionCoda(input: {
+    readonly date: string;
+    readonly projectRoot: string;
+    readonly codas: readonly string[];
+}): string | null;
+/** Skip non-strings and bodies over SESSION_CODA_MAX_CHARS. */
+export declare function filterCodaEntries(raw: unknown): string[];
+/**
+ * Load + filter coda lines from content. Fail-open: missing/unreadable/invalid
+ * / empty after filter → [] (omit ✦; no error noise).
+ */
+export declare function loadSessionCodas(frameworkRoot: string, readText?: (path: string) => string | null): string[];
+/** Format enabled coda line: ✦ + space + body. */
+export declare function formatSessionCodaEnabledLine(body: string): string;
+export interface ResolveSessionCodaLineInput {
+    readonly mode: SessionCodaMode;
+    readonly shouldEmit: boolean;
+    readonly date: string;
+    readonly projectRoot: string;
+    readonly codas: readonly string[];
+}
+/**
+ * Resolve the single extra line (or null) after final success footer.
+ * Does not print; caller places after blank line post footer (D2).
+ */
+export declare function resolveSessionCodaLine(input: ResolveSessionCodaLineInput): string | null;
+/** Help / env-docs fragment for DEFT_SESSION_CODA three-state (#2712). */
+export declare function sessionCodaHelpText(): string;
+//# sourceMappingURL=session-coda.d.ts.map

package/dist/doctor/session-coda.js

@@ -0,0 +1,151 @@
+/**
+ * Optional deterministic session coda for interactive doctor success (#2712).
+ *
+ * Human TTY affordance only: never JSON, never AGENTS/skills, never exit-code
+ * changes. Env three-state DEFT_SESSION_CODA (unset / 1 / 0). Copy lives in
+ * content/doctor/session-coda.json — not embedded as an engine literal.
+ */
+import { readFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { contentRoot } from "../content-root.js";
+/** Env var name (env-only v1; no USER.md key). */
+export const SESSION_CODA_ENV = "DEFT_SESSION_CODA";
+/**
+ * Fixed discoverability line when env is unset and gates pass (D3).
+ * Snapshot-stable; not selected from the pack; no ✦ prefix.
+ */
+export const SESSION_CODA_OFF_HINT = "Session coda: off (set DEFT_SESSION_CODA=1 to enable)";
+/** U+2726 FOUR RAYED STAR + space — stable; do not localize. */
+export const SESSION_CODA_STAR_PREFIX = "\u2726 ";
+/** Max body length; longer pack entries are skipped (fail-open). */
+export const SESSION_CODA_MAX_CHARS = 100;
+/** Relative path under contentRoot (source: content/doctor/…; deposit: doctor/…). */
+export const SESSION_CODA_REL_PATH = join("doctor", "session-coda.json");
+/**
+ * Map DEFT_SESSION_CODA to the three-state mode (D3).
+ * - undefined / "" → unset (discoverability off-hint)
+ * - "1" → on (✦ coda)
+ * - "0" → off (silent)
+ * - any other non-empty value → unset (show correct enable form)
+ */
+export function sessionCodaMode(envValue) {
+    if (envValue === undefined || envValue === "")
+        return "unset";
+    if (envValue === "1")
+        return "on";
+    if (envValue === "0")
+        return "off";
+    return "unset";
+}
+/**
+ * Whether any extra line (off-hint or coda) is allowed (D1 + surface gates).
+ * TTY = stdout.isTTY; CI truthy blocks; json blocks; exitOk = errorCount === 0.
+ */
+export function shouldEmitSessionCodaLine(input) {
+    return input.exitOk === true && input.tty === true && input.ci !== true && input.json !== true;
+}
+/**
+ * FNV-1a 32-bit (#2712). Documented choice for hash_u32(date + "\\0" + root).
+ * No Math.random; same inputs ⇒ same u32 on every platform.
+ */
+export function hashU32(input) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < input.length; i += 1) {
+        hash ^= input.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 0;
+}
+/** UTC calendar date yyyy-mm-dd from a Date (stable for 24h across a team day). */
+export function utcDateYmd(date) {
+    return date.toISOString().slice(0, 10);
+}
+/** Best-effort realpath; falls back to the given path when realpath fails. */
+export function projectRootRealpath(projectRoot) {
+    try {
+        return realpathSync(projectRoot);
+    }
+    catch {
+        return projectRoot;
+    }
+}
+/**
+ * Select one coda body from the pack (enabled path only).
+ * index = hash_u32(utc_date + "\\0" + project_root_realpath) % len(codas)
+ * Empty list → null (omit ✦; doctor still 0).
+ */
+export function selectSessionCoda(input) {
+    const { date, projectRoot, codas } = input;
+    if (codas.length === 0)
+        return null;
+    const key = `${date}\0${projectRoot}`;
+    const index = hashU32(key) % codas.length;
+    return codas[index] ?? null;
+}
+/** Skip non-strings and bodies over SESSION_CODA_MAX_CHARS. */
+export function filterCodaEntries(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const entry of raw) {
+        if (typeof entry !== "string")
+            continue;
+        if (entry.length === 0 || entry.length > SESSION_CODA_MAX_CHARS)
+            continue;
+        out.push(entry);
+    }
+    return out;
+}
+/**
+ * Load + filter coda lines from content. Fail-open: missing/unreadable/invalid
+ * / empty after filter → [] (omit ✦; no error noise).
+ */
+export function loadSessionCodas(frameworkRoot, readText) {
+    const packPath = join(contentRoot(frameworkRoot), SESSION_CODA_REL_PATH);
+    try {
+        const text = readText !== undefined ? readText(packPath) : readFileSync(packPath, { encoding: "utf8" });
+        if (text === null || text === "")
+            return [];
+        return filterCodaEntries(JSON.parse(text));
+    }
+    catch {
+        return [];
+    }
+}
+/** Format enabled coda line: ✦ + space + body. */
+export function formatSessionCodaEnabledLine(body) {
+    return `${SESSION_CODA_STAR_PREFIX}${body}`;
+}
+/**
+ * Resolve the single extra line (or null) after final success footer.
+ * Does not print; caller places after blank line post footer (D2).
+ */
+export function resolveSessionCodaLine(input) {
+    if (!input.shouldEmit)
+        return null;
+    if (input.mode === "off")
+        return null;
+    if (input.mode === "unset")
+        return SESSION_CODA_OFF_HINT;
+    const body = selectSessionCoda({
+        date: input.date,
+        projectRoot: input.projectRoot,
+        codas: input.codas,
+    });
+    if (body === null)
+        return null;
+    return formatSessionCodaEnabledLine(body);
+}
+/** Help / env-docs fragment for DEFT_SESSION_CODA three-state (#2712). */
+export function sessionCodaHelpText() {
+    return [
+        "Environment:",
+        `  ${SESSION_CODA_ENV}  Session coda after interactive success (exit 0, TTY, not CI, not --json):`,
+        "    unset  Print discoverability line:",
+        `           ${SESSION_CODA_OFF_HINT}`,
+        "    =1     Print one curated line, e.g.:",
+        `           ${formatSessionCodaEnabledLine("Doctor first. Then continue.")}`,
+        "    =0     Silent (no hint, no coda)",
+    ].join("\n");
+}
+//# sourceMappingURL=session-coda.js.map

package/dist/doctor/types.d.ts

@@ -123,6 +123,22 @@ export interface DoctorSeams {
         now?: Date;
     }) => string | null;
     readonly isTty?: () => boolean;
+    /**
+     * stdout TTY probe for session coda (#2712). Defaults to
+     * `process.stdout.isTTY === true` (not stdin). Separate from `isTty` (stdin
+     * used by --fix prompts).
+     */
+    readonly stdoutIsTty?: () => boolean;
+    /**
+     * Override DEFT_SESSION_CODA for tests (#2712). `undefined` means read
+     * process.env; pass `""` or omit via explicit nullish env simulation with
+     * `undefined` from a seam that returns undefined.
+     */
+    readonly sessionCodaEnv?: string | undefined;
+    /** Override CI env string for session coda gates (#2712). */
+    readonly ciEnv?: string | undefined;
+    /** Override session-coda pack loader for fail-open tests (#2712). */
+    readonly loadSessionCodas?: (frameworkRoot: string) => string[];
     readonly readYn?: (prompt: string, defaultYes: boolean) => boolean;
     readonly writeText?: (path: string, content: string) => void;
     readonly now?: () => Date;

package/dist/doctor/which.d.ts

@@ -1,3 +1,22 @@
-/** Default PATH lookup mirroring Python `shutil.which`. */
+export interface WhichAllOptions {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly platform?: NodeJS.Platform;
+    readonly exists?: (path: string) => boolean;
+    /** Optional executable predicate (defaults to file + X_OK on posix). */
+    readonly isExecutable?: (path: string) => boolean;
+}
+/**
+ * Enumerate every PATH match for `name` (PATH order, first = highest precedence).
+ * Pure PATH scan — no shell locator — so tests and win32/posix stay hermetic and
+ * gated ritual never executes a PATH-substituted `which`/`where` (#3233).
+ * Only files (posix: executable bit) are accepted — not bare directories.
+ */
+export declare function whichAllFromPath(name: string, options?: WhichAllOptions): string[];
+/**
+ * All PATH matches for `name` without shelling out (#3233 security).
+ * Alias of {@link whichAllFromPath} — never runs bare `which` / `where`.
+ */
+export declare function defaultWhichAll(name: string, options?: WhichAllOptions): string[];
+/** Default PATH lookup mirroring Python `shutil.which` (first match only). */
 export declare function defaultWhich(name: string): string | null;
 //# sourceMappingURL=which.d.ts.map

package/dist/doctor/which.js

@@ -1,5 +1,71 @@
 import { execFileSync } from "node:child_process";
-/** Default PATH lookup mirroring Python `shutil.which`. */
+import { accessSync, constants, existsSync, statSync } from "node:fs";
+import { posix, win32 } from "node:path";
+function defaultIsExecutable(path, platform) {
+    try {
+        const st = statSync(path);
+        // Directories named `deft` must not shadow later executables (#3233 Greptile).
+        if (st.isDirectory())
+            return false;
+        if (!st.isFile() && !st.isSymbolicLink())
+            return false;
+        if (platform === "win32") {
+            return true;
+        }
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Enumerate every PATH match for `name` (PATH order, first = highest precedence).
+ * Pure PATH scan — no shell locator — so tests and win32/posix stay hermetic and
+ * gated ritual never executes a PATH-substituted `which`/`where` (#3233).
+ * Only files (posix: executable bit) are accepted — not bare directories.
+ */
+export function whichAllFromPath(name, options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const exists = options.exists ?? existsSync;
+    const isExecutable = options.isExecutable ?? ((p) => defaultIsExecutable(p, platform));
+    const pathValue = env.PATH ?? env.Path ?? "";
+    if (pathValue === "") {
+        return [];
+    }
+    const isWindows = platform === "win32";
+    const exts = isWindows ? (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";") : [""];
+    const sep = isWindows ? ";" : ":";
+    const joinPath = isWindows ? win32.join : posix.join;
+    const seen = new Set();
+    const out = [];
+    for (const dir of pathValue.split(sep)) {
+        if (dir === "")
+            continue;
+        for (const ext of exts) {
+            const candidate = joinPath(dir, `${name}${ext}`);
+            const key = isWindows ? candidate.toLowerCase() : candidate;
+            if (seen.has(key))
+                continue;
+            if (exists(candidate) && isExecutable(candidate)) {
+                seen.add(key);
+                out.push(candidate);
+                // One match per PATH directory (first PATHEXT hit wins on win32).
+                break;
+            }
+        }
+    }
+    return out;
+}
+/**
+ * All PATH matches for `name` without shelling out (#3233 security).
+ * Alias of {@link whichAllFromPath} — never runs bare `which` / `where`.
+ */
+export function defaultWhichAll(name, options = {}) {
+    return whichAllFromPath(name, options);
+}
+/** Default PATH lookup mirroring Python `shutil.which` (first match only). */
 export function defaultWhich(name) {
     const locator = process.platform === "win32" ? "where" : "which";
     try {