@deftai/directive-core 0.100.0 → 0.101.0

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

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/index.d.ts

@@ -48,12 +48,14 @@ export * as prMonitor from "./pr-monitor/index.js";
 export * as prProtectedIssues from "./pr-protected-issues/index.js";
 export * as prWaitMergeable from "./pr-wait-mergeable/index.js";
 export * as preflight from "./preflight/index.js";
+export * as productFirstDoneGate from "./product-first-done-gate/index.js";
 export * as release from "./release/index.js";
 export * as releaseE2e from "./release-e2e/index.js";
 export * as releasePublish from "./release-publish/index.js";
 export * as releaseRollback from "./release-rollback/index.js";
 export * as render from "./render/index.js";
 export * as resolution from "./resolution/index.js";
+export * as runSummary from "./run-summary/index.js";
 export * as scm from "./scm/index.js";
 export * as scope from "./scope/index.js";
 export * as scopeProvenance from "./scope-provenance/index.js";

package/dist/index.js

@@ -49,12 +49,14 @@ export * as prMonitor from "./pr-monitor/index.js";
 export * as prProtectedIssues from "./pr-protected-issues/index.js";
 export * as prWaitMergeable from "./pr-wait-mergeable/index.js";
 export * as preflight from "./preflight/index.js";
+export * as productFirstDoneGate from "./product-first-done-gate/index.js";
 export * as release from "./release/index.js";
 export * as releaseE2e from "./release-e2e/index.js";
 export * as releasePublish from "./release-publish/index.js";
 export * as releaseRollback from "./release-rollback/index.js";
 export * as render from "./render/index.js";
 export * as resolution from "./resolution/index.js";
+export * as runSummary from "./run-summary/index.js";
 export * as scm from "./scm/index.js";
 export * as scope from "./scope/index.js";
 export * as scopeProvenance from "./scope-provenance/index.js";

package/dist/init-deposit/gitignore.js

@@ -30,6 +30,8 @@ export const CANONICAL_GITIGNORE_BASELINE = [
     ".deft/ritual-state.json",
     ".deft/last-session.json",
     ".deft/routing.local.json",
+    // #3282: opt-in default run-summary JSONL at repo root (collectible; must not dirty trees).
+    ".deft-run-summary.json",
     // Temporary test/local kill-switch — must stay untracked (#3039).
     DEFT_DIRECTIVE_DISABLE_GITIGNORE_LINE,
     "vbrief/.triage-cache/candidates.jsonl",

package/dist/intake/issue-ingest.js

@@ -5,6 +5,7 @@ import { scan } from "../cache/scanner.js";
 import { assertWriteTargetSafe, ProjectionContainmentError } from "../fs/projection-containment.js";
 import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
 import { captureAndAttachLiteralAcceptance } from "../literal-acceptance/index.js";
+import { stampAcceptanceFromLiteralCapture } from "../product-first-done-gate/index.js";
 import { call } from "../scm/call.js";
 import { resolveProjectRoot } from "../scope/project-context.js";
 import { resolveProjectRepo } from "../slice/project-context.js";
@@ -472,6 +473,12 @@ export function buildIssueVbrief(issue, status, repoUrl, options = {}) {
             }
         }
         Object.assign(plan, attached.plan);
+        // #3284: stamp plan.acceptance from captured literals (stated or none_stated floor).
+        Object.assign(plan, stampAcceptanceFromLiteralCapture(plan));
+    }
+    else {
+        // No body: still record none_stated acceptance so absence is a decision.
+        Object.assign(plan, stampAcceptanceFromLiteralCapture(plan));
     }
     const infoRootKey = options.infoRootKey ?? LEGACY_INFO_ROOT_KEY;
     const infoVersion = options.infoVersion ?? EMITTED_VBRIEF_VERSION;

package/dist/policy/ac-pass-banking.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Typed plan.policy.acPassBanking (#3285).
+ *
+ * Surplus-threshold policy for post-AC-pass deepening: after the first
+ * stated-AC bank, agents may deepen only when remaining budget is at least
+ * this fraction of the hard max (default 0.2 = 20%).
+ *
+ * Composes #3266 bank-the-pass and product-first done-gate (#3284).
+ */
+/** Canonical dotted path for policy:show / PROJECT-DEFINITION. */
+export declare const FIELD_AC_PASS_BANKING = "plan.policy.acPassBanking";
+/** CLI alias for `task policy:show --field=acPassBanking`. */
+export declare const FIELD_AC_PASS_BANKING_CLI_ALIAS = "acPassBanking";
+/**
+ * Default surplus fraction of max turns/cost that must remain after bank
+ * before self-imposed deepening is allowed (#3285).
+ */
+export declare const DEFAULT_SURPLUS_THRESHOLD = 0.2;
+/** Floor / ceiling for surplusThreshold (inclusive). */
+export declare const SURPLUS_THRESHOLD_MIN = 0;
+export declare const SURPLUS_THRESHOLD_MAX = 1;
+/** Optional env override (fraction 0–1 or percent 0–100). */
+export declare const ENV_SURPLUS_THRESHOLD = "DEFT_AC_PASS_SURPLUS_THRESHOLD";
+export interface AcPassBankingConfig {
+    /**
+     * When false, surplus gate is inactive (unbounded / optional discipline only).
+     * Default true — the gate still only binds under a hard effort budget.
+     */
+    readonly enabled: boolean;
+    /**
+     * Minimum remaining fraction of max turns/cost required to deepen after bank.
+     * Default {@link DEFAULT_SURPLUS_THRESHOLD} (0.2).
+     */
+    readonly surplusThreshold: number;
+}
+export type AcPassBankingSource = "typed" | "env" | "default" | "default-on-error";
+export interface AcPassBankingResolved extends AcPassBankingConfig {
+    readonly source: AcPassBankingSource;
+    readonly error: string | null;
+}
+/** Parse a 0–1 fraction or a 0–100 percent string/number into a fraction. */
+export declare function parseSurplusThreshold(raw: unknown): number | null;
+/** Validate a `plan.policy.acPassBanking` payload. */
+export declare function validateAcPassBanking(value: unknown): string[];
+/**
+ * Resolve surplus policy from typed plan.policy.acPassBanking, then env,
+ * then defaults (#3285).
+ */
+export declare function resolveAcPassBanking(projectRoot?: string | null, environ?: Readonly<Record<string, string | undefined>>): AcPassBankingResolved;
+export interface AcPassBankingPolicyField {
+    readonly name: typeof FIELD_AC_PASS_BANKING;
+    readonly current: AcPassBankingConfig;
+    readonly default: AcPassBankingConfig;
+    readonly source: string;
+}
+/** Inspector row for `task policy:show --field=acPassBanking` (#3285). */
+export declare function inspectAcPassBanking(_data: Record<string, unknown> | null, projectRoot?: string): AcPassBankingPolicyField;
+//# sourceMappingURL=ac-pass-banking.d.ts.map

package/dist/policy/ac-pass-banking.js

@@ -0,0 +1,150 @@
+/**
+ * Typed plan.policy.acPassBanking (#3285).
+ *
+ * Surplus-threshold policy for post-AC-pass deepening: after the first
+ * stated-AC bank, agents may deepen only when remaining budget is at least
+ * this fraction of the hard max (default 0.2 = 20%).
+ *
+ * Composes #3266 bank-the-pass and product-first done-gate (#3284).
+ */
+import { readPlanPolicy } from "./plan-extensions.js";
+import { loadProjectDefinition } from "./resolve.js";
+/** Canonical dotted path for policy:show / PROJECT-DEFINITION. */
+export const FIELD_AC_PASS_BANKING = "plan.policy.acPassBanking";
+/** CLI alias for `task policy:show --field=acPassBanking`. */
+export const FIELD_AC_PASS_BANKING_CLI_ALIAS = "acPassBanking";
+/**
+ * Default surplus fraction of max turns/cost that must remain after bank
+ * before self-imposed deepening is allowed (#3285).
+ */
+export const DEFAULT_SURPLUS_THRESHOLD = 0.2;
+/** Floor / ceiling for surplusThreshold (inclusive). */
+export const SURPLUS_THRESHOLD_MIN = 0;
+export const SURPLUS_THRESHOLD_MAX = 1;
+/** Optional env override (fraction 0–1 or percent 0–100). */
+export const ENV_SURPLUS_THRESHOLD = "DEFT_AC_PASS_SURPLUS_THRESHOLD";
+function defaultResolved(source, error = null, override) {
+    return {
+        enabled: override?.enabled ?? true,
+        surplusThreshold: override?.surplusThreshold ?? DEFAULT_SURPLUS_THRESHOLD,
+        source,
+        error,
+    };
+}
+/** Parse a 0–1 fraction or a 0–100 percent string/number into a fraction. */
+export function parseSurplusThreshold(raw) {
+    if (typeof raw === "number" && Number.isFinite(raw)) {
+        if (raw >= 0 && raw <= 1)
+            return raw;
+        // Allow 20 meaning 20% when clearly a percent.
+        if (raw > 1 && raw <= 100)
+            return raw / 100;
+        return null;
+    }
+    if (typeof raw === "string") {
+        const text = raw.trim();
+        if (!text)
+            return null;
+        const percent = text.endsWith("%");
+        const n = Number(percent ? text.slice(0, -1).trim() : text);
+        if (!Number.isFinite(n))
+            return null;
+        if (percent) {
+            if (n < 0 || n > 100)
+                return null;
+            return n / 100;
+        }
+        if (n >= 0 && n <= 1)
+            return n;
+        if (n > 1 && n <= 100)
+            return n / 100;
+        return null;
+    }
+    return null;
+}
+/** Validate a `plan.policy.acPassBanking` payload. */
+export function validateAcPassBanking(value) {
+    if (value === null || value === undefined) {
+        return [];
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        return [`${FIELD_AC_PASS_BANKING} must be an object; got ${typeof value}`];
+    }
+    const rec = value;
+    const errors = [];
+    if ("enabled" in rec && typeof rec.enabled !== "boolean") {
+        errors.push(`${FIELD_AC_PASS_BANKING}.enabled must be a boolean`);
+    }
+    if ("surplusThreshold" in rec) {
+        const parsed = parseSurplusThreshold(rec.surplusThreshold);
+        if (parsed === null) {
+            errors.push(`${FIELD_AC_PASS_BANKING}.surplusThreshold must be a fraction 0–1 ` +
+                `(or percent 0–100); got ${JSON.stringify(rec.surplusThreshold)}`);
+        }
+    }
+    return errors;
+}
+/**
+ * Resolve surplus policy from typed plan.policy.acPassBanking, then env,
+ * then defaults (#3285).
+ */
+export function resolveAcPassBanking(projectRoot, environ = process.env) {
+    if (projectRoot !== undefined && projectRoot !== null && projectRoot.length > 0) {
+        const [data, err] = loadProjectDefinition(projectRoot);
+        if (data !== null) {
+            const policyBlock = readPlanPolicy(data.plan);
+            if (typeof policyBlock === "object" &&
+                policyBlock !== null &&
+                !Array.isArray(policyBlock) &&
+                "acPassBanking" in policyBlock) {
+                const raw = policyBlock.acPassBanking;
+                const errors = validateAcPassBanking(raw);
+                if (errors.length > 0) {
+                    return defaultResolved("default-on-error", errors[0] ?? "invalid acPassBanking");
+                }
+                if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
+                    const rec = raw;
+                    const enabled = typeof rec.enabled === "boolean" ? rec.enabled : true;
+                    const threshold = "surplusThreshold" in rec
+                        ? (parseSurplusThreshold(rec.surplusThreshold) ?? DEFAULT_SURPLUS_THRESHOLD)
+                        : DEFAULT_SURPLUS_THRESHOLD;
+                    return {
+                        enabled,
+                        surplusThreshold: threshold,
+                        source: "typed",
+                        error: null,
+                    };
+                }
+            }
+        }
+        else if (err !== null && err.length > 0) {
+            // Fall through to env/default; record nothing as fatal.
+        }
+    }
+    const envRaw = environ[ENV_SURPLUS_THRESHOLD];
+    if (envRaw !== undefined && envRaw.trim() !== "") {
+        const parsed = parseSurplusThreshold(envRaw);
+        if (parsed !== null) {
+            return defaultResolved("env", null, { surplusThreshold: parsed });
+        }
+        return defaultResolved("default-on-error", `${ENV_SURPLUS_THRESHOLD} is not a valid fraction/percent: ${envRaw}`);
+    }
+    return defaultResolved("default");
+}
+/** Inspector row for `task policy:show --field=acPassBanking` (#3285). */
+export function inspectAcPassBanking(_data, projectRoot) {
+    const resolved = resolveAcPassBanking(projectRoot);
+    return {
+        name: FIELD_AC_PASS_BANKING,
+        current: {
+            enabled: resolved.enabled,
+            surplusThreshold: resolved.surplusThreshold,
+        },
+        default: {
+            enabled: true,
+            surplusThreshold: DEFAULT_SURPLUS_THRESHOLD,
+        },
+        source: resolved.source,
+    };
+}
+//# sourceMappingURL=ac-pass-banking.js.map

package/dist/policy/ceremony-dial.d.ts

@@ -286,4 +286,33 @@ export interface CeremonyDialAuditSnapshot {
 export declare function readCeremonyDialAudit(projectRoot: string): CeremonyDialAuditSnapshot;
 /** One-line operator summary for audit tooling / failed-task forensics (#3263). */
 export declare function formatCeremonyDialAuditLine(audit: CeremonyDialAuditSnapshot): string;
+/**
+ * Reified dial transition for run-summary telemetry (#3282).
+ *
+ * IMPLEMENTATION PREREQUISITE from the issue: dial transitions must be
+ * engine-managed events, not prose-only policy. This function is the CLI-facing
+ * transition hook (`policy:set-ceremony-dial` / dial escalate): it persists the
+ * override (when confirm) and always emits a `dial_transition` run-summary line
+ * when a depth change is applied.
+ */
+export interface EscalateCeremonyDialOptions {
+    readonly to: CeremonyDepth;
+    readonly reason: string;
+    readonly evidence?: string;
+    readonly sessionId?: string;
+    readonly confirm?: boolean;
+    readonly actor?: string;
+    readonly note?: string;
+    /** When false, skip run-summary emission (tests). Default true. */
+    readonly emitRunSummary?: boolean;
+    readonly env?: NodeJS.ProcessEnv;
+}
+export interface EscalateCeremonyDialResult {
+    readonly exitCode: number;
+    readonly from: CeremonyDepth | null;
+    readonly to: CeremonyDepth;
+    readonly changed: boolean;
+    readonly lines: readonly string[];
+}
+export declare function escalateCeremonyDial(projectRoot: string, options: EscalateCeremonyDialOptions): EscalateCeremonyDialResult;
 //# sourceMappingURL=ceremony-dial.d.ts.map