@deftai/directive-core 0.100.0 → 0.102.0

package/dist/check/named-cause.js

@@ -0,0 +1,131 @@
+/**
+ * Named-cause + remedy formatting for check gate failures (#3282).
+ *
+ * Gate failures must never be bare exit 1: report gate name, cause, and remedy
+ * without embedding env values.
+ */
+/** Per-gate remedy hints (static; no env interpolation). */
+const GATE_REMEDIES = {
+    "verify:branch": "Create a feature branch (`git switch -c feat/<name>`) or set plan.policy.allowDirectCommitsToMaster with confirmation",
+    "verify:encoding": "Fix non-ASCII / encoding issues flagged by the gate; re-run task verify:encoding",
+    "verify:cache-fresh": "Run task cache:fetch-all or task triage:bootstrap to refresh the cache",
+    "verify:orphan-active": "Complete or cancel active xBRIEFs whose issues are closed / PRs merged (task scope:complete / scope:cancel)",
+    "verify:wip-cap": "Demote stale pending scopes (task scope:demote) or raise plan.policy.wipCap deliberately",
+    doctor: "Run task doctor and follow the named recovery steps",
+    "toolchain:check": "Install missing maintainer tools reported by the gate (go, uv, git, gh, node, pnpm)",
+    "toolchain:check-consumer": "Install missing consumer tools: go-task, git, gh, node, pnpm (corepack enable && corepack prepare pnpm@latest --activate)",
+    "ts:check-lane": "Fix lint/type/test failures; re-run task ts:check-lane",
+    "vbrief:validate": "Fix xBRIEF/vBRIEF schema errors reported by the gate",
+    "verify-strategy-output": "Re-run strategy output or fix non-conformant scope filenames / PROJECT-DEFINITION",
+    "verify:test-boundary": "Move tests to the allowed placement or update plan.policy test-boundary allowlist",
+    "verify:scope-provenance": "Record approved scope provenance for the failing paths",
+    "verify:consumer-check-contract": "Align consumer Taskfile includes with the required gate graph",
+    "verify:forward-coverage": "Add tests covering new source files (task verify:forward-coverage)",
+    "verify:scm-boundary": "Move SCM mutations off GraphQL-heavy paths or wait for rate-limit reset",
+    "verify:license-sync": "Sync LICENSE / package license fields",
+    "verify:agents-md-budget": "Trim AGENTS.md managed section or raise plan.policy.agentsMdBudget deliberately",
+};
+const SPAWN_ERROR_REMEDY = "Install go-task (https://taskfile.dev/installation/) and ensure `task` is on PATH; then re-run task check";
+const CLI_SPAWN_ERROR_REMEDY = "Install: npm i -g @deftai/directive@latest";
+/**
+ * Extract a short cause from gate stdout/stderr without leaking env values.
+ * Strips lines that look like KEY=value assignments.
+ */
+export function extractGateCause(stdout, stderr, exitCode, spawnError) {
+    if (spawnError !== undefined && spawnError.length > 0) {
+        // Normalize common missing-binary messages without path dumps.
+        if (/ENOENT|not found|not recognized/i.test(spawnError)) {
+            if (/\b(deft|directive)(\.cmd)?\b/i.test(spawnError)) {
+                return "global deft/directive CLI not found on PATH";
+            }
+            return "task binary not found on PATH (cannot spawn go-task)";
+        }
+        return sanitizeCauseLine(spawnError);
+    }
+    const combined = `${stderr}\n${stdout}`
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+    for (const line of combined) {
+        if (looksLikeEnvLeak(line))
+            continue;
+        if (line.startsWith("check:"))
+            continue;
+        return sanitizeCauseLine(line);
+    }
+    return `gate exited ${exitCode} without a diagnostic message`;
+}
+function looksLikeEnvLeak(line) {
+    // Avoid echoing DEFT_*= or generic env dumps.
+    if (/^[A-Z][A-Z0-9_]*=/.test(line))
+        return true;
+    if (/\bDEFT_[A-Z0-9_]+\b/.test(line) && line.includes("="))
+        return true;
+    return false;
+}
+function sanitizeCauseLine(line) {
+    // Cap length; collapse absolute home paths lightly.
+    let out = line.replace(/\r/g, "").trim();
+    if (out.length > 240) {
+        out = `${out.slice(0, 237)}...`;
+    }
+    return out;
+}
+export function remedyForGate(gateId, cause) {
+    if (/global deft\/directive CLI not found/i.test(cause)) {
+        return CLI_SPAWN_ERROR_REMEDY;
+    }
+    if (/task binary not found|cannot spawn go-task/i.test(cause)) {
+        if (gateId.startsWith("verify:") || gateId.startsWith("verify-") || gateId === "doctor") {
+            return CLI_SPAWN_ERROR_REMEDY;
+        }
+        return SPAWN_ERROR_REMEDY;
+    }
+    if (/pnpm binary not found|pnpm: NOT FOUND/i.test(cause)) {
+        return "Enable pnpm: corepack enable && corepack prepare pnpm@latest --activate";
+    }
+    return (GATE_REMEDIES[gateId] ??
+        `Re-run the gate for details: task ${gateId}  (or task check); fix the reported product/process defect`);
+}
+/**
+ * Format named-cause failure lines for a single gate.
+ */
+export function formatNamedCauseFailure(input) {
+    const cause = extractGateCause(input.stdout ?? "", input.stderr ?? "", input.exitCode, input.spawnError);
+    const remedy = remedyForGate(input.gateId, cause);
+    const lines = [
+        `check: gate ${input.gateId} failed (exit ${input.exitCode})`,
+        `  cause: ${cause}`,
+        `  remedy: ${remedy}`,
+    ];
+    return {
+        gateId: input.gateId,
+        exitCode: input.exitCode,
+        cause,
+        remedy,
+        lines,
+    };
+}
+/**
+ * Format degraded-mode skip report (which gates skipped and why).
+ */
+export function formatDegradedSkipReport(input) {
+    const exitCode = input.exitCode ?? 2;
+    const lines = [
+        `check: degraded mode — ${input.reason}`,
+        `check: skipped ${input.skipped.length} gate(s) due to missing framework toolchain (#3282):`,
+    ];
+    for (const gate of input.skipped) {
+        lines.push(`  - ${gate.id}: cause: ${gate.cause}; remedy: ${gate.remedy}`);
+    }
+    if (input.ran !== undefined && input.ran.length > 0) {
+        lines.push(`check: ran: ${input.ran.join(", ")}`);
+    }
+    if (input.failed !== undefined && input.failed.length > 0) {
+        lines.push(`check: failed: ${input.failed.join(", ")}`);
+    }
+    lines.push(`check: exit ${exitCode} (degraded/config) — skipped required gates are not a green pass; ` +
+        "install missing tooling (see remedies above) and re-run task check");
+    return lines;
+}
+//# sourceMappingURL=named-cause.js.map

package/dist/check/orchestrator.js

@@ -57,7 +57,12 @@ export function dispatchTaskCheck(frameworkRoot, projectRoot, seams = {}) {
         timeoutMs: seams.timeoutMs,
     });
     if (result.error !== undefined) {
-        process.stderr.write(`check: failed to invoke task: ${result.error.message}\n`);
+        // #3282: named cause + remedy instead of bare spawn failure.
+        const detail = result.error.message;
+        const missingTask = /ENOENT|not found|not recognized/i.test(detail);
+        process.stderr.write(`check: gate ${target} failed (exit 2)\n` +
+            `  cause: ${missingTask ? "task binary not found on PATH (cannot spawn go-task)" : detail}\n` +
+            "  remedy: Install go-task (https://taskfile.dev/installation/) and ensure `task` is on PATH; then re-run task check\n");
         return 2;
     }
     if (result.signal === "SIGTERM" && result.status === null && seams.timeoutMs !== undefined) {

package/dist/doctor/checks.d.ts

@@ -87,12 +87,6 @@ export declare function checkTypescript7SideBySide(projectRoot: string, seams?:
  * `directive init` or `directive update`).
  */
 export declare function checkGitignoreCoverage(projectRoot: string, seams?: CheckSeams): CheckResult;
-/**
- * Surface undecided / invalid coverageDebt + checkResume policy (#3189).
- * Advisory skip when undecided; never hard-fails doctor / check:consumer.
- * Decided-off is quiet; dismiss-with-reason is pass with reason in detail.
- * Invalid typed blocks resolve fail-closed and surface via source=default-on-error.
- */
 /**
  * Fail closed when completed/ plan.status disagrees with the folder (#3242 AC1 / epic #3237 Q4).
  * Open plan.items under completed/ are reported by `checkCompletedOpenItems` (exit-exempt
@@ -104,6 +98,11 @@ export declare function checkCompletedLifecycleConsistency(projectRoot: string):
  * historical pre-#2862 corpora do not red-light doctor; scope:complete fails closed.
  */
 export declare function checkCompletedOpenItems(projectRoot: string): CheckResult;
+/**
+ * Surface invalid coverageDebt + checkResume typed blocks (#3314).
+ * Absent / default / valid typed values pass. Invalid blocks skip (advisory,
+ * fail-closed resolution). Doctor no longer reports "undecided".
+ */
 export declare function checkCoverageCheckResumePolicy(projectRoot: string): CheckResult;
 export declare function deriveExitCode(checks: readonly CheckResult[], errors: readonly string[]): number;
 export declare function runChecksImpl(projectRoot: string, seams?: CheckSeams & {

package/dist/doctor/checks.js

@@ -8,7 +8,6 @@ import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { scanCompletedLifecycleConsistency } from "../lifecycle/completed-consistency.js";
 import { resolveCheckResume } from "../policy/check-resume.js";
 import { resolveCoverageDebt } from "../policy/coverage-debt.js";
-import { policyColonInvocation } from "../policy/policy-invocation.js";
 import { classifyXbriefSchemaDistance } from "../staleness-tickler/probe-xbrief.js";
 import { findSkillPathsInText } from "../text/redos-safe.js";
 import { stripGitignoreInlineComment } from "../triage/bootstrap/gitignore.js";
@@ -1070,12 +1069,6 @@ export function checkGitignoreCoverage(projectRoot, seams = {}) {
         },
     };
 }
-/**
- * Surface undecided / invalid coverageDebt + checkResume policy (#3189).
- * Advisory skip when undecided; never hard-fails doctor / check:consumer.
- * Decided-off is quiet; dismiss-with-reason is pass with reason in detail.
- * Invalid typed blocks resolve fail-closed and surface via source=default-on-error.
- */
 /**
  * Fail closed when completed/ plan.status disagrees with the folder (#3242 AC1 / epic #3237 Q4).
  * Open plan.items under completed/ are reported by `checkCompletedOpenItems` (exit-exempt
@@ -1152,6 +1145,11 @@ export function checkCompletedOpenItems(projectRoot) {
         },
     };
 }
+/**
+ * Surface invalid coverageDebt + checkResume typed blocks (#3314).
+ * Absent / default / valid typed values pass. Invalid blocks skip (advisory,
+ * fail-closed resolution). Doctor no longer reports "undecided".
+ */
 export function checkCoverageCheckResumePolicy(projectRoot) {
     const debt = resolveCoverageDebt(projectRoot);
     const resume = resolveCheckResume(projectRoot);
@@ -1160,66 +1158,25 @@ export function checkCoverageCheckResumePolicy(projectRoot) {
             name: "coverage-check-resume-policy",
             status: "skip",
             detail: "advisory: coverageDebt and/or checkResume block is invalid; " +
-                "resolution is fail-closed (mode off, localStamp off, CI never trusts stamps). " +
+                "resolution is fail-closed (mode off, localStamp off). " +
                 `coverageDebt.error=${JSON.stringify(debt.error)}; ` +
                 `checkResume.error=${JSON.stringify(resume.error)}. ` +
-                "Fix the typed block or re-apply Strict / Hatch-aware / dismiss-with-reason.",
+                "Fix the typed block in PROJECT-DEFINITION.",
             data: {
-                coverageDebt: { status: debt.status, source: debt.source, error: debt.error },
-                checkResume: { status: resume.status, source: resume.source, error: resume.error },
+                coverageDebt: { mode: debt.mode, source: debt.source, error: debt.error },
+                checkResume: { localStamp: resume.localStamp, source: resume.source, error: resume.error },
                 advisory: true,
                 invalid: true,
             },
         };
     }
-    const undecided = debt.status === "unset" || resume.status === "unset";
-    if (!undecided) {
-        const dismissParts = [];
-        if (debt.dismissReason) {
-            dismissParts.push(`coverageDebt.dismissReason=${JSON.stringify(debt.dismissReason)}`);
-        }
-        if (resume.dismissReason) {
-            dismissParts.push(`checkResume.dismissReason=${JSON.stringify(resume.dismissReason)}`);
-        }
-        const dismissNote = dismissParts.length > 0 ? ` Dismissed: ${dismissParts.join("; ")}.` : "";
-        return {
-            name: "coverage-check-resume-policy",
-            status: "pass",
-            detail: `coverageDebt status=${debt.status} mode=${debt.mode}; ` +
-                `checkResume status=${resume.status} localStamp=${resume.localStamp}; ` +
-                `ciTrustsLocalStamp=false (fixed v1).${dismissNote}`,
-            data: {
-                coverageDebt: {
-                    status: debt.status,
-                    mode: debt.mode,
-                    autoFile: debt.autoFile,
-                    dismissReason: debt.dismissReason,
-                },
-                checkResume: {
-                    status: resume.status,
-                    localStamp: resume.localStamp,
-                    ciTrustsLocalStamp: false,
-                    dismissReason: resume.dismissReason,
-                },
-            },
-        };
-    }
-    // Advisory only (status=skip): never hard-fails doctor / check:consumer (#3189).
-    // Behavior remains fail-closed while unset; session-start nudge carries the ask.
     return {
         name: "coverage-check-resume-policy",
-        status: "skip",
-        detail: "advisory: coverageDebt and/or checkResume policy is undecided (status=unset). " +
-            "Behavior stays fail-closed (no hatch soft-pass, no local suite stamp, CI never trusts stamps). " +
-            "Choose Strict / Hatch-aware on the next interactive session-start nudge, or record " +
-            "dismiss-with-reason. Inspect: " +
-            `\`${policyColonInvocation("show", " --field=coverageDebt")}\` / ` +
-            `\`${policyColonInvocation("show", " --field=checkResume")}\`.`,
+        status: "pass",
+        detail: `coverageDebt.mode=${debt.mode}; checkResume.localStamp=${resume.localStamp}.`,
         data: {
-            coverageDebt: { status: debt.status, mode: debt.mode },
-            checkResume: { status: resume.status, localStamp: resume.localStamp },
-            suggested_fix: policyColonInvocation("show", " --field=coverageDebt"),
-            advisory: true,
+            coverageDebt: { mode: debt.mode, autoFile: debt.autoFile, source: debt.source },
+            checkResume: { localStamp: resume.localStamp, source: resume.source },
         },
     };
 }

package/dist/doctor/help.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Doctor --help / -h text (#2712 session coda env docs + flag surface).
+ */
+export declare function formatDoctorHelp(): string;
+//# sourceMappingURL=help.d.ts.map

package/dist/doctor/help.js

@@ -0,0 +1,31 @@
+/**
+ * Doctor --help / -h text (#2712 session coda env docs + flag surface).
+ */
+import { DOCTOR_ALLOWED_FLAGS } from "./constants.js";
+import { sessionCodaHelpText } from "./session-coda.js";
+export function formatDoctorHelp() {
+    const flags = DOCTOR_ALLOWED_FLAGS.join(", ");
+    return [
+        "Usage: deft doctor [options]",
+        "",
+        "Diagnose the Directive install and print the one next step.",
+        "",
+        "Options:",
+        "  --session              Session-oriented probe",
+        "  --fix, --repair       Attempt safe repairs (Taskfile / OpenClaw pins)",
+        "  --json                 Machine-readable JSON (no human footer / no coda)",
+        "  --quiet                Suppress mid-run chatter; final summary still prints",
+        "  --full                 Bypass throttle; re-probe fully",
+        "  --network              Allow offline-tier network checks (payload staleness)",
+        "  --project-root <path>  Project root (default: cwd)",
+        "  --force                Replace divergent OpenClaw pins during --fix",
+        "  --openclaw-all-agents  Wire always-pins into every OpenClaw workspace seat",
+        "  -h, --help             Show this help",
+        "",
+        `Allowed flags: ${flags}`,
+        "",
+        sessionCodaHelpText(),
+        "",
+    ].join("\n");
+}
+//# sourceMappingURL=help.js.map

package/dist/doctor/index.d.ts

@@ -3,6 +3,7 @@ export * from "./checks.js";
 export * from "./constants.js";
 export * from "./doctor-state.js";
 export * from "./flags.js";
+export * from "./help.js";
 export * from "./json.js";
 export * from "./main.js";
 export * from "./manifest.js";
@@ -13,6 +14,7 @@ export * from "./openclaw-soft-rebind.js";
 export * from "./paths.js";
 export * from "./payload-staleness.js";
 export * from "./release-availability.js";
+export * from "./session-coda.js";
 export * from "./taskfile.js";
 export * from "./types.js";
 export * from "./which.js";

package/dist/doctor/index.js

@@ -3,6 +3,7 @@ export * from "./checks.js";
 export * from "./constants.js";
 export * from "./doctor-state.js";
 export * from "./flags.js";
+export * from "./help.js";
 export * from "./json.js";
 export * from "./main.js";
 export * from "./manifest.js";
@@ -13,6 +14,7 @@ export * from "./openclaw-soft-rebind.js";
 export * from "./paths.js";
 export * from "./payload-staleness.js";
 export * from "./release-availability.js";
+export * from "./session-coda.js";
 export * from "./taskfile.js";
 export * from "./types.js";
 export * from "./which.js";

package/dist/doctor/main.js

@@ -16,6 +16,7 @@ import { checkXbriefEnvelopeMajorVersion, runChecks, XBRIEF_ENVELOPE_MAJOR_CHECK
 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";
@@ -25,6 +26,7 @@ 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";
@@ -58,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;
@@ -489,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) {
@@ -498,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) {

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