@deftai/directive-core 0.79.3 → 0.80.0

package/dist/pr-watch/watch.js

@@ -1,5 +1,5 @@
 import { defaultRunGh } from "../pr-merge-readiness/gh.js";
-import { DEFAULT_MAX_WAIT_MINUTES, DEFAULT_POLL_SECONDS, DEFAULT_STALL_THRESHOLD, EXIT_CLEAN, EXIT_NEW_P0_P1, EXIT_TERMINAL_ERROR, VERDICT_CLEAN, VERDICT_CONFIG, VERDICT_ERRORED, VERDICT_NEW_P0_P1, VERDICT_PENDING, VERDICT_STALL, VERDICT_TIMEOUT, } from "./constants.js";
+import { DEFAULT_CI_BLOCKED_THRESHOLD, DEFAULT_MAX_WAIT_MINUTES, DEFAULT_POLL_SECONDS, DEFAULT_STALL_THRESHOLD, EXIT_CLEAN, EXIT_NEW_P0_P1, EXIT_TERMINAL_ERROR, VERDICT_CI_BLOCKED, VERDICT_CLEAN, VERDICT_CONFIG, VERDICT_ERRORED, VERDICT_NEW_P0_P1, VERDICT_PENDING, VERDICT_RUNNER_CAPACITY_STALL, VERDICT_STALL, VERDICT_TIMEOUT, } from "./constants.js";
 import { probeOnce } from "./probe.js";
 const systemMonotonicClock = {
     now() {
@@ -52,6 +52,7 @@ export function watch(prNumber, repo, options = {}) {
     const startedAt = clockFn.now();
     let lastProbe = null;
     let stallStreak = 0;
+    let ciBlockedStreak = 0;
     const build = (verdict, exitCode, probe, poll) => ({
         verdict,
         exitCode,
@@ -79,6 +80,25 @@ export function watch(prNumber, repo, options = {}) {
         if (probe.errored) {
             return build(VERDICT_ERRORED, EXIT_TERMINAL_ERROR, probe, poll);
         }
+        // #2672: capacity stall is distinct from ordinary not_ready_yet — surface
+        // immediately (exit 2) so agents wait for auto-failover instead of --skip-ci.
+        if (probe.ciReadyState === "runner_capacity_stall") {
+            return build(VERDICT_RUNNER_CAPACITY_STALL, EXIT_TERMINAL_ERROR, probe, poll);
+        }
+        // #2688: Greptile side satisfied on HEAD but CI red — fail loud toward a
+        // fix loop instead of burning max-wait-minutes on idle Greptile polls.
+        if (probe.cleanGateHoldout === "ci_failures") {
+            ciBlockedStreak += 1;
+        }
+        else {
+            ciBlockedStreak = 0;
+        }
+        if (oneShot && probe.cleanGateHoldout === "ci_failures") {
+            return build(VERDICT_CI_BLOCKED, EXIT_TERMINAL_ERROR, probe, poll);
+        }
+        if (!oneShot && ciBlockedStreak >= DEFAULT_CI_BLOCKED_THRESHOLD) {
+            return build(VERDICT_CI_BLOCKED, EXIT_TERMINAL_ERROR, probe, poll);
+        }
         // Stall = a review IS present but stuck on a non-HEAD commit; surface it
         // rather than burning the whole cap waiting for a re-review that isn't coming.
         if (probe.found && !probe.shaMatch) {
@@ -112,6 +132,9 @@ export function watch(prNumber, repo, options = {}) {
         hasBlocking: false,
         errored: false,
         ciFailures: 0,
+        ciFailedChecks: [],
+        ciReadyState: null,
+        ciCapacityStalledChecks: [],
         terminalCheckRun: false,
         isClean: false,
         cleanGateHoldout: null,

package/dist/scope/main.js

@@ -1,5 +1,6 @@
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { maybeRunStalenessTickler } from "../staleness-tickler/run.js";
 import { reconcileUmbrellas, renderUmbrellasReport } from "../vbrief-reconcile/umbrellas.js";
 import { canonicalLogPath, readAll } from "./audit-log.js";
 import { TRANSITIONS } from "./constants.js";
@@ -110,6 +111,17 @@ export function lifecycleMain(argv) {
             catch {
                 /* best-effort drift warning + reconcile; lifecycle success remains authoritative */
             }
+            try {
+                const rootForTickler = resolveProjectRoot(projectRoot) ??
+                    dirname(dirname(dirname(completedPathForScopeMove(filePath))));
+                const tickler = maybeRunStalenessTickler(rootForTickler);
+                for (const line of tickler.lines) {
+                    process.stdout.write(`${line}\n`);
+                }
+            }
+            catch {
+                /* best-effort staleness tickler; lifecycle success remains authoritative */
+            }
         }
         return 0;
     }

package/dist/scope/undo.js

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { basename, join, relative, resolve } from "node:path";
+import { assertWriteTargetSafe, ProjectionContainmentError } from "../fs/projection-containment.js";
 import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { append, canonicalLogPath, newDecisionId, readAll } from "./audit-log.js";
 import { REVERSIBLE_ACTIONS, TERMINAL_ACTIONS } from "./constants.js";
@@ -157,7 +158,7 @@ function inversePlan(entry, logEntries) {
     }
     return null;
 }
-function moveAndFlip(srcFile, destFolder, newStatus, timestamp) {
+function moveAndFlip(srcFile, destFolder, newStatus, timestamp, projectRoot) {
     if (!existsSync(srcFile)) {
         return [false, `File not found: ${srcFile}`, null];
     }
@@ -172,6 +173,15 @@ function moveAndFlip(srcFile, destFolder, newStatus, timestamp) {
     if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
         return [false, `Missing or invalid 'plan' object in ${srcFile}`, null];
     }
+    try {
+        assertWriteTargetSafe(projectRoot, srcFile);
+    }
+    catch (err) {
+        if (err instanceof ProjectionContainmentError) {
+            return [false, err.message, null];
+        }
+        throw err;
+    }
     const planObj = plan;
     planObj.status = newStatus;
     planObj.updated = timestamp;
@@ -262,7 +272,7 @@ export function undoOne(entry, projectRoot, options = {}) {
         });
         return { ok: true, message: msg, auditEntry: preview };
     }
-    const [ok, fsMsg, destPath] = moveAndFlip(srcPath, destFolderPath, plan.newStatus, timestamp);
+    const [ok, fsMsg, destPath] = moveAndFlip(srcPath, destFolderPath, plan.newStatus, timestamp, projectRoot);
     if (!ok || destPath === null) {
         return { ok: false, message: fsMsg, auditEntry: null };
     }

package/dist/session/release-availability.d.ts

@@ -0,0 +1,21 @@
+export interface ReleaseAvailabilityProbeOptions {
+    readonly now?: Date;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly readText?: (path: string) => string | null;
+    readonly isFile?: (path: string) => boolean;
+    readonly runNpmView?: () => {
+        ok: boolean;
+        version: string;
+    };
+    readonly readState?: (path: string) => string | null;
+    readonly writeState?: (path: string, content: string) => void;
+}
+export interface ReleaseAvailabilityProbeResult {
+    readonly lines: readonly string[];
+}
+/**
+ * Probe the public npm registry separately from doctor. Doctor stays offline
+ * by default (#2182); mutable session start may emit this bounded advisory.
+ */
+export declare function probeSessionReleaseAvailability(projectRoot: string, options?: ReleaseAvailabilityProbeOptions): ReleaseAvailabilityProbeResult;
+//# sourceMappingURL=release-availability.d.ts.map

package/dist/session/release-availability.js

@@ -0,0 +1,109 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { locateManifest, parseInstallManifest } from "../doctor/manifest.js";
+import { runningInsideDeftRepo } from "../doctor/paths.js";
+import { evaluateReleaseAvailability } from "../doctor/release-availability.js";
+const THROTTLE_MS = 24 * 60 * 60 * 1000;
+const PUBLIC_NPM_REGISTRY = "https://registry.npmjs.org/";
+const STATE_RELATIVE_PATH = join("xbrief", ".triage-cache", "release-availability-state.json");
+function defaultReadText(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function defaultNpmView() {
+    const result = spawnSync("npm", [
+        "view",
+        "@deftai/directive",
+        "version",
+        `--registry=${PUBLIC_NPM_REGISTRY}`,
+        "--ignore-scripts",
+    ], {
+        encoding: "utf8",
+        timeout: 5_000,
+    });
+    const version = (result.stdout ?? "").trim().split(/\r?\n/)[0]?.trim() ?? "";
+    return { ok: result.status === 0 && version.length > 0, version };
+}
+function parseState(text) {
+    if (text === null)
+        return {};
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed !== null && typeof parsed === "object") {
+            return parsed;
+        }
+    }
+    catch {
+        // A stale advisory state is never allowed to block session start.
+    }
+    return {};
+}
+function isThrottled(state, latestVersion, now) {
+    if (state.latestVersion !== latestVersion || !state.notifiedAt)
+        return false;
+    const notifiedAt = Date.parse(state.notifiedAt);
+    return Number.isFinite(notifiedAt) && now.getTime() - notifiedAt < THROTTLE_MS;
+}
+function defaultWriteState(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, content, "utf8");
+    renameSync(temporary, path);
+}
+/**
+ * Probe the public npm registry separately from doctor. Doctor stays offline
+ * by default (#2182); mutable session start may emit this bounded advisory.
+ */
+export function probeSessionReleaseAvailability(projectRoot, options = {}) {
+    const env = options.env ?? process.env;
+    if (env.DEFT_NO_NETWORK === "1") {
+        return { lines: ["[deft release] skipped (DEFT_NO_NETWORK=1)."] };
+    }
+    if (runningInsideDeftRepo(projectRoot)) {
+        return { lines: [] };
+    }
+    const readText = options.readText ?? defaultReadText;
+    const isFile = options.isFile ?? existsSync;
+    const manifestPath = locateManifest(projectRoot, null, isFile);
+    const manifestText = manifestPath ? readText(manifestPath) : null;
+    if (manifestText === null)
+        return { lines: [] };
+    const manifest = parseInstallManifest(manifestText);
+    const installed = (manifest.tag ?? manifest.ref ?? "").trim();
+    if (evaluateReleaseAvailability(installed, null).status === "not-applicable") {
+        return { lines: [] };
+    }
+    const lines = [
+        `[deft release] Checking ${PUBLIC_NPM_REGISTRY} for a newer published Directive release.`,
+    ];
+    let npmResult;
+    try {
+        npmResult = (options.runNpmView ?? defaultNpmView)();
+    }
+    catch {
+        npmResult = { ok: false, version: "" };
+    }
+    const availability = evaluateReleaseAvailability(installed, npmResult.ok ? npmResult.version : null);
+    if (availability.status !== "available")
+        return { lines };
+    const statePath = join(projectRoot, STATE_RELATIVE_PATH);
+    const state = parseState((options.readState ?? defaultReadText)(statePath));
+    const now = options.now ?? new Date();
+    if (isThrottled(state, availability.latestVersion, now))
+        return { lines: [] };
+    const message = `[deft release] Newer Directive release available: v${availability.latestVersion} ` +
+        `(installed v${availability.installedVersion}). Run \`npm i -g @deftai/directive@latest\`.`;
+    try {
+        (options.writeState ?? defaultWriteState)(statePath, `${JSON.stringify({ latestVersion: availability.latestVersion, notifiedAt: now.toISOString() }, null, 2)}\n`);
+    }
+    catch {
+        // The advisory remains useful if its best-effort throttle state cannot persist.
+    }
+    return { lines: [...lines, message] };
+}
+//# sourceMappingURL=release-availability.js.map

package/dist/session/ritual-sentinel.d.ts

@@ -43,6 +43,20 @@ export declare function newRitualStatePayload(input: {
 }): Record<string, unknown>;
 export declare function readRitualState(projectRoot: string): [RitualState | null, string | null];
 export declare function writeRitualState(projectRoot: string, payload: Record<string, unknown>): string;
+/** Instant guaranteed to fail `evaluateLoadedState` age checks on any policy horizon. */
+export declare const RITUAL_STALE_EPOCH: Date;
+export interface MarkRitualStaleAfterCompactResult {
+    readonly changed: boolean;
+    readonly statePath: string;
+    readonly message: string;
+}
+/**
+ * Invalidate an existing mutation ritual after host context compaction/resume (#2113).
+ * Reuses ritual-state age semantics — no parallel policy stack.
+ */
+export declare function markRitualStaleAfterCompact(projectRoot: string, input?: {
+    now?: Date;
+}): MarkRitualStaleAfterCompactResult;
 export declare function recordRitualStep(projectRoot: string, input: {
     tier: "quick" | "gated";
     stepName: string;

package/dist/session/ritual-sentinel.js

@@ -184,6 +184,34 @@ export function writeRitualState(projectRoot, payload) {
     atomicWriteJson(stateFile, payload, ".ritual-state.");
     return stateFile;
 }
+/** Instant guaranteed to fail `evaluateLoadedState` age checks on any policy horizon. */
+export const RITUAL_STALE_EPOCH = new Date("1970-01-01T00:00:00Z");
+/**
+ * Invalidate an existing mutation ritual after host context compaction/resume (#2113).
+ * Reuses ritual-state age semantics — no parallel policy stack.
+ */
+export function markRitualStaleAfterCompact(projectRoot, input = {}) {
+    const now = input.now ?? new Date();
+    const statePath = ritualStatePath(projectRoot);
+    const [state, err] = readRitualState(projectRoot);
+    if (state === null) {
+        return {
+            changed: false,
+            statePath,
+            message: err ?? "no ritual state to invalidate after compaction",
+        };
+    }
+    const payload = { ...state.raw };
+    payload.started_at = timestampIso(RITUAL_STALE_EPOCH);
+    payload.compact_resume_at = timestampIso(now);
+    writeRitualState(projectRoot, payload);
+    return {
+        changed: true,
+        statePath,
+        message: "Marked session ritual stale after context compaction; run session:start and " +
+            "verify:session-ritual -- --tier=gated before direct writes.",
+    };
+}
 export function recordRitualStep(projectRoot, input) {
     const [state, err] = readRitualState(projectRoot);
     if (state === null) {

package/dist/session/session-start.d.ts

@@ -1,6 +1,7 @@
 import { type EnvironmentContext } from "../platform/shell-context.js";
 import { type ResolveUserMdResult } from "../user-config/resolve-user-md.js";
 import type { GitRunner } from "./git.js";
+import { type ReleaseAvailabilityProbeOptions } from "./release-availability.js";
 import { ritualStatePath } from "./ritual-sentinel.js";
 export declare const SESSION_POSTURES: readonly ["read-only", "mutation"];
 export type SessionPosture = (typeof SESSION_POSTURES)[number];
@@ -42,6 +43,15 @@ export interface SessionStartOptions {
     };
     readonly resolveUserMd?: (projectRoot: string) => ResolveUserMdResult;
     readonly probeEnvironment?: () => EnvironmentContext;
+    readonly probeReleaseAvailability?: (projectRoot: string, options: ReleaseAvailabilityProbeOptions) => {
+        lines: readonly string[];
+    };
+    readonly runStalenessTickler?: (projectRoot: string, options: {
+        now?: Date;
+    }) => {
+        lines: readonly string[];
+        prompted: boolean;
+    };
 }
 export declare function parseDeferrals(rawValues: readonly string[]): {
     deferrals: Record<string, string>;

package/dist/session/session-start.js

@@ -5,11 +5,13 @@ import { MIGRATE_COMPLETION_NUDGE, shouldEmitMigrateNudge } from "../init-deposi
 import { detectEnvironmentContext, environmentContextToDict, formatEnvironmentContext, } from "../platform/shell-context.js";
 import { disclosureLine } from "../policy/disclosure.js";
 import { resolvePolicy } from "../policy/resolve.js";
+import { maybeRunStalenessTickler } from "../staleness-tickler/run.js";
 import { runDefaultMode } from "../triage/welcome/default-mode.js";
 import { resolveUserMdPath } from "../user-config/resolve-user-md.js";
 import { emitSessionValueReadback } from "../value/readback.js";
 import { verifyRequiredTools } from "../verify-env/verify-tools.js";
 import { defaultGitRunner, gitHead, worktreePath } from "./git.js";
+import { probeSessionReleaseAvailability, } from "./release-availability.js";
 import { newRitualStatePayload, ritualStatePath, ritualStep, writeRitualState, } from "./ritual-sentinel.js";
 export const SESSION_POSTURES = ["read-only", "mutation"];
 export const READ_ONLY_POSTURE = "read-only";
@@ -341,6 +343,22 @@ export function runSessionStart(projectRoot, options = {}) {
             lines.push(message);
         }
     }
+    try {
+        const releaseAvailability = (options.probeReleaseAvailability ?? probeSessionReleaseAvailability)(projectRoot, { now: instant });
+        lines.push(...releaseAvailability.lines);
+    }
+    catch {
+        // Release availability is a best-effort operator advisory, never a session blocker.
+    }
+    try {
+        const tickler = (options.runStalenessTickler ?? maybeRunStalenessTickler)(projectRoot, {
+            now: instant,
+        });
+        lines.push(...tickler.lines);
+    }
+    catch {
+        // Staleness tickler is best-effort and must never block session start.
+    }
     if (!runningInsideDeftRepo(projectRoot) && shouldEmitMigrateNudge(projectRoot)) {
         lines.push(MIGRATE_COMPLETION_NUDGE);
     }

package/dist/staleness-tickler/escalation.d.ts

@@ -0,0 +1,14 @@
+import type { DriftInputs, DriftScoreResult, StalenessTicklerPolicy, StalenessTicklerState, StalenessTicklerTier, XbriefSchemaDistance } from "./types.js";
+/** Compute a weighted drift score from independent axes (#2489). */
+export declare function scoreDrift(inputs: DriftInputs, policy: StalenessTicklerPolicy): number;
+/** Map drift inputs to an escalation tier using typed thresholds. */
+export declare function resolveTier(inputs: DriftInputs, policy: StalenessTicklerPolicy): StalenessTicklerTier;
+/** Hold the last known tier when detection is unverified (#2489 monotonicity). */
+export declare function holdTierOnUnverified(computedTier: StalenessTicklerTier, computedScore: number, state: StalenessTicklerState, directiveUnverified: boolean): DriftScoreResult;
+/** Snooze window widens with deferrals up to `maxWidenMultiplier`. */
+export declare function snoozeWindowMs(tier: StalenessTicklerTier, deferralCount: number, policy: StalenessTicklerPolicy): number;
+export declare function isSnoozeActive(state: StalenessTicklerState, now: Date): boolean;
+/** Assert tier re-prompts at idle even when a plain snooze would still be active. */
+export declare function shouldPromptDespiteSnooze(tier: StalenessTicklerTier, state: StalenessTicklerState): boolean;
+export declare function mergeHeldXbriefDistance(current: XbriefSchemaDistance, held: XbriefSchemaDistance | undefined): XbriefSchemaDistance;
+//# sourceMappingURL=escalation.d.ts.map

package/dist/staleness-tickler/escalation.js

@@ -0,0 +1,106 @@
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+/** Compute a weighted drift score from independent axes (#2489). */
+export function scoreDrift(inputs, policy) {
+    const { weights } = policy;
+    let score = 0;
+    if (inputs.directive.stale) {
+        if (inputs.directive.majorBehind) {
+            score += weights.directiveMajor;
+        }
+        score += inputs.directive.minorDistance * weights.directiveMinor;
+        score += inputs.directive.patchDistance * weights.directivePatch;
+    }
+    if (inputs.xbrief.stale) {
+        if (inputs.xbrief.distance === "behind-major") {
+            score += weights.schemaMajor;
+        }
+        else if (inputs.xbrief.distance === "behind-minor") {
+            score += weights.schemaMinor;
+        }
+    }
+    score += (inputs.ageMs / MS_PER_DAY) * weights.agePerDay;
+    score += inputs.deferralCount * weights.deferral;
+    return score;
+}
+function baseTierFromInputs(inputs, policy) {
+    const { tiers } = policy;
+    if (inputs.directive.majorBehind ||
+        inputs.xbrief.distance === "behind-major" ||
+        inputs.ageMs >= tiers.strongAgeMs) {
+        return "strong";
+    }
+    if (inputs.directive.minorDistance >= tiers.noticeMinorThreshold ||
+        inputs.xbrief.distance === "behind-minor") {
+        return "notice";
+    }
+    return "quiet";
+}
+/** Map drift inputs to an escalation tier using typed thresholds. */
+export function resolveTier(inputs, policy) {
+    const base = baseTierFromInputs(inputs, policy);
+    if (base === "strong" && inputs.deferralCount >= policy.tiers.assertDeferralCap) {
+        return "assert";
+    }
+    return base;
+}
+/** Hold the last known tier when detection is unverified (#2489 monotonicity). */
+export function holdTierOnUnverified(computedTier, computedScore, state, directiveUnverified) {
+    if (!directiveUnverified || state.lastTier === undefined) {
+        return { score: computedScore, tier: computedTier };
+    }
+    const heldTier = state.lastTier;
+    const heldScore = state.lastScore ?? computedScore;
+    const tierRank = (tier) => tier === "quiet" ? 0 : tier === "notice" ? 1 : tier === "strong" ? 2 : 3;
+    if (tierRank(heldTier) > tierRank(computedTier)) {
+        return { score: heldScore, tier: heldTier };
+    }
+    return { score: computedScore, tier: computedTier };
+}
+function baseSnoozeMs(tier, policy) {
+    switch (tier) {
+        case "quiet":
+            return policy.snooze.quietMs;
+        case "notice":
+            return policy.snooze.noticeMs;
+        case "strong":
+            return policy.snooze.strongMs;
+        case "assert":
+            return policy.snooze.strongMs;
+        default:
+            return policy.snooze.noticeMs;
+    }
+}
+/** Snooze window widens with deferrals up to `maxWidenMultiplier`. */
+export function snoozeWindowMs(tier, deferralCount, policy) {
+    const base = baseSnoozeMs(tier, policy);
+    const multiplier = Math.min(1 + deferralCount, Math.max(1, policy.snooze.maxWidenMultiplier));
+    if (tier === "assert") {
+        return Math.min(base, policy.snooze.strongMs);
+    }
+    return Math.round(base * multiplier);
+}
+export function isSnoozeActive(state, now) {
+    if (!state.snoozedUntil) {
+        return false;
+    }
+    const until = Date.parse(state.snoozedUntil);
+    return Number.isFinite(until) && now.getTime() < until;
+}
+/** Assert tier re-prompts at idle even when a plain snooze would still be active. */
+export function shouldPromptDespiteSnooze(tier, state) {
+    if (tier !== "assert") {
+        return false;
+    }
+    if (state.remindAfterNextRelease) {
+        return false;
+    }
+    return true;
+}
+export function mergeHeldXbriefDistance(current, held) {
+    if (held === undefined) {
+        return current;
+    }
+    const rank = (distance) => distance === "current" ? 0 : distance === "behind-minor" ? 1 : 2;
+    return rank(held) > rank(current) ? held : current;
+}
+//# sourceMappingURL=escalation.js.map

package/dist/staleness-tickler/idle.d.ts

@@ -0,0 +1,18 @@
+import type { StalenessTicklerPolicy } from "./types.js";
+export interface IdleGateOptions {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly readPorcelain?: (projectRoot: string) => string | null;
+    readonly countInFlight?: (projectRoot: string) => number;
+    readonly insideDeftRepo?: (projectRoot: string) => boolean;
+}
+export interface IdleGateResult {
+    readonly ok: boolean;
+    readonly reason?: string;
+}
+/** True when every #2488 idle gate passes for an interactive tickler prompt. */
+export declare function isSafeIdlePoint(projectRoot: string, policy: StalenessTicklerPolicy, options?: IdleGateOptions): IdleGateResult;
+/** Skip the tickler entirely in CI/headless ritual-skip contexts. */
+export declare function shouldSkipTicklerEntirely(env?: NodeJS.ProcessEnv): boolean;
+/** Whether stdin/stdout are TTYs suitable for a blocking consent prompt. */
+export declare function isInteractiveSession(env?: NodeJS.ProcessEnv, isTty?: () => boolean): boolean;
+//# sourceMappingURL=idle.d.ts.map

package/dist/staleness-tickler/idle.js

@@ -0,0 +1,47 @@
+import { runningInsideDeftRepo } from "../doctor/paths.js";
+import { gitPorcelain } from "../story-ready/git.js";
+import { countFilesystemInFlight } from "../triage/summary/index.js";
+function ritualSkipActive(env) {
+    return env.DEFT_SESSION_RITUAL_SKIP === "1";
+}
+/** True when every #2488 idle gate passes for an interactive tickler prompt. */
+export function isSafeIdlePoint(projectRoot, policy, options = {}) {
+    const env = options.env ?? process.env;
+    if (ritualSkipActive(env)) {
+        return { ok: false, reason: "DEFT_SESSION_RITUAL_SKIP=1" };
+    }
+    if (!policy.enabled || policy.optOut) {
+        return { ok: false, reason: "policy-disabled" };
+    }
+    const insideDeft = options.insideDeftRepo ?? ((root) => runningInsideDeftRepo(root));
+    if (insideDeft(projectRoot)) {
+        return { ok: false, reason: "framework-repo" };
+    }
+    const porcelain = (options.readPorcelain ?? gitPorcelain)(projectRoot);
+    if (porcelain === null) {
+        return { ok: false, reason: "git-undeterminable" };
+    }
+    if (porcelain.trim().length > 0) {
+        return { ok: false, reason: "dirty-tree" };
+    }
+    const inFlight = (options.countInFlight ?? countFilesystemInFlight)(projectRoot);
+    if (inFlight > 0) {
+        return { ok: false, reason: "story-in-flight" };
+    }
+    return { ok: true };
+}
+/** Skip the tickler entirely in CI/headless ritual-skip contexts. */
+export function shouldSkipTicklerEntirely(env = process.env) {
+    return ritualSkipActive(env);
+}
+/** Whether stdin/stdout are TTYs suitable for a blocking consent prompt. */
+export function isInteractiveSession(env = process.env, isTty = () => process.stdin.isTTY === true && process.stdout.isTTY === true) {
+    if (env.DEFT_SESSION_RITUAL_SKIP === "1") {
+        return false;
+    }
+    if (env.CI === "true" || env.CI === "1") {
+        return false;
+    }
+    return isTty();
+}
+//# sourceMappingURL=idle.js.map

package/dist/staleness-tickler/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./escalation.js";
+export * from "./idle.js";
+export * from "./probe-directive.js";
+export * from "./probe-xbrief.js";
+export { DIRECTIVE_UPGRADE_COMMAND, maybeRunStalenessTickler, probeStalenessDimensions, XBRIEF_MIGRATE_COMMAND, } from "./run.js";
+export * from "./state.js";
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/staleness-tickler/index.js

@@ -0,0 +1,8 @@
+export * from "./escalation.js";
+export * from "./idle.js";
+export * from "./probe-directive.js";
+export * from "./probe-xbrief.js";
+export { DIRECTIVE_UPGRADE_COMMAND, maybeRunStalenessTickler, probeStalenessDimensions, XBRIEF_MIGRATE_COMMAND, } from "./run.js";
+export * from "./state.js";
+export * from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/staleness-tickler/probe-directive.d.ts

@@ -0,0 +1,32 @@
+import { type ReleaseAvailabilityResult } from "../doctor/release-availability.js";
+import type { ParsedSemverCore } from "./types.js";
+export interface ProbeDirectiveOptions {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly readText?: (path: string) => string | null;
+    readonly isFile?: (path: string) => boolean;
+    readonly runNpmView?: () => {
+        ok: boolean;
+        version: string;
+    };
+}
+/** Parse `X.Y.Z` or `vX.Y.Z` core semver (ignores pre-release suffix). */
+export declare function parseSemverCore(version: string): ParsedSemverCore | null;
+export declare function computeDirectiveDistance(installedVersion: string, latestVersion: string): {
+    majorBehind: boolean;
+    minorDistance: number;
+    patchDistance: number;
+};
+export interface ProbeDirectiveResult {
+    readonly availability: ReleaseAvailabilityResult;
+    readonly majorBehind: boolean;
+    readonly minorDistance: number;
+    readonly patchDistance: number;
+    readonly stale: boolean;
+    readonly registryDisclosure: string;
+}
+/**
+ * Probe Directive payload staleness via the public npm registry (#1692 substrate).
+ * Skips network when `DEFT_NO_NETWORK=1`.
+ */
+export declare function probeDirectiveStaleness(projectRoot: string, options?: ProbeDirectiveOptions): ProbeDirectiveResult | null;
+//# sourceMappingURL=probe-directive.d.ts.map