@deftai/directive-core 0.88.0 → 0.90.0

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

@@ -0,0 +1,67 @@
+/**
+ * session:ready — one-shot mutation recovery (#2993).
+ *
+ * Composes existing APIs (does not reimplement session:start or gated verify):
+ *   1. Fast path when inspectSessionRitual(gated) is already green
+ *   2. session:start when quick-tier state is missing/stale
+ *   3. verifySessionRitual(--tier=gated) for doctor + cache_fresh
+ *   4. cache fetch-all recovery when cache_fresh is the remaining blocker
+ *   5. re-verify gated
+ *
+ * Exit 0 means a subsequent inspect/verify gated would pass (or the single
+ * remaining hard blocker is printed once).
+ */
+import type { GitRunner } from "./git.js";
+import { type SessionStartOptions, type SessionStartResult } from "./session-start.js";
+import { type InspectSessionRitualOptions, type RitualRunner, type VerifyResult, type VerifySessionRitualOptions } from "./verify-session-ritual.js";
+export declare const SESSION_READY_FAST_PATH = "fast";
+export declare const SESSION_READY_RECOVERED = "recovered";
+export declare const SESSION_READY_VERIFIED = "verified";
+export declare const SESSION_READY_FAILED = "failed";
+export type SessionReadyPath = typeof SESSION_READY_FAST_PATH | typeof SESSION_READY_RECOVERED | typeof SESSION_READY_VERIFIED | typeof SESSION_READY_FAILED;
+export interface SessionReadyResult {
+    readonly code: number;
+    readonly message: string;
+    readonly path: SessionReadyPath;
+    readonly lines: readonly string[];
+    /** Steps actually executed (for tests / --json). */
+    readonly steps: readonly string[];
+    readonly duration_ms: number;
+}
+export type CacheFetchAllSeam = (options: {
+    source: string;
+    repo: string;
+    force?: boolean;
+    cacheRoot?: string;
+}) => unknown;
+export interface SessionReadyOptions {
+    readonly now?: Date;
+    readonly runGit?: GitRunner;
+    readonly runner?: RitualRunner;
+    readonly env?: NodeJS.ProcessEnv;
+    /** When set, overrides DEFT_TRIAGE_REPO / git remote inference for cache recovery. */
+    readonly repo?: string | null;
+    readonly sessionStartOptions?: Omit<SessionStartOptions, "now" | "runGit" | "env">;
+    readonly inspectRitual?: (projectRoot: string, options: InspectSessionRitualOptions) => VerifyResult;
+    readonly verifyRitual?: (projectRoot: string, options: VerifySessionRitualOptions) => VerifyResult;
+    readonly runStart?: (projectRoot: string, options: SessionStartOptions) => SessionStartResult;
+    readonly fetchAll?: CacheFetchAllSeam;
+    readonly inferRepo?: (projectRoot: string) => string | null;
+    /** Skip cache recovery even when cache_fresh failed (tests). */
+    readonly skipCacheRecovery?: boolean;
+}
+/** True when a gated verify failure is attributable to the cache_fresh step. */
+export declare function isCacheFreshFailure(message: string): boolean;
+/**
+ * True readiness for PreToolUse: exit 0 without DEFT_SESSION_RITUAL_SKIP bypass.
+ * Bypassed code 0 does not make inspectSessionRitual green (#2993 Greptile P1).
+ */
+export declare function isGatedVerifyActuallyReady(result: VerifyResult): boolean;
+/** Infer OWNER/NAME from DEFT_TRIAGE_REPO or git remote origin. */
+export declare function inferSessionReadyRepo(projectRoot: string, env?: NodeJS.ProcessEnv): string | null;
+/**
+ * One-shot recovery: leave the worktree PreToolUse-gated-inspect green, or
+ * print the single remaining blocker.
+ */
+export declare function runSessionReady(projectRoot: string, options?: SessionReadyOptions): SessionReadyResult;
+//# sourceMappingURL=session-ready.d.ts.map

package/dist/session/session-ready.js

@@ -0,0 +1,264 @@
+/**
+ * session:ready — one-shot mutation recovery (#2993).
+ *
+ * Composes existing APIs (does not reimplement session:start or gated verify):
+ *   1. Fast path when inspectSessionRitual(gated) is already green
+ *   2. session:start when quick-tier state is missing/stale
+ *   3. verifySessionRitual(--tier=gated) for doctor + cache_fresh
+ *   4. cache fetch-all recovery when cache_fresh is the remaining blocker
+ *   5. re-verify gated
+ *
+ * Exit 0 means a subsequent inspect/verify gated would pass (or the single
+ * remaining hard blocker is printed once).
+ */
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { cacheFetchAll } from "../cache/fetch.js";
+import { formatFrameworkCommand } from "../render/framework-commands.js";
+import { runSessionStart, } from "./session-start.js";
+import { inspectSessionRitual, verifySessionRitual, } from "./verify-session-ritual.js";
+export const SESSION_READY_FAST_PATH = "fast";
+export const SESSION_READY_RECOVERED = "recovered";
+export const SESSION_READY_VERIFIED = "verified";
+export const SESSION_READY_FAILED = "failed";
+function elapsedMs(started) {
+    return Math.max(0, Math.round(performance.now() - started));
+}
+/** True when a gated verify failure is attributable to the cache_fresh step. */
+export function isCacheFreshFailure(message) {
+    return /cache_fresh|cache-fresh|cache fetch-all|cache-fresh:|stale-by-drift|stale age/i.test(message);
+}
+/**
+ * True readiness for PreToolUse: exit 0 without DEFT_SESSION_RITUAL_SKIP bypass.
+ * Bypassed code 0 does not make inspectSessionRitual green (#2993 Greptile P1).
+ */
+export function isGatedVerifyActuallyReady(result) {
+    return result.code === 0 && !result.bypassed;
+}
+function bypassedReadyFailure(result) {
+    const detail = result.message.trim().length > 0
+        ? result.message
+        : "session ritual verification was bypassed (DEFT_SESSION_RITUAL_SKIP)";
+    return (`${detail}\n` +
+        `  session:ready refuses bypassed verification (would not pass PreToolUse inspect). ` +
+        `Unset DEFT_SESSION_RITUAL_SKIP and re-run \`${readyCommand()}\`.`);
+}
+function normaliseRepoUrl(url) {
+    if (!url)
+        return null;
+    const cleaned = url
+        .trim()
+        .replace(/\/$/, "")
+        .replace(/\.git$/, "");
+    const match = cleaned.match(/^(?:(?:https?|ssh|git):\/\/)?(?:[^/@]+@)?github\.com[:/]+([^/]+)\/([^/]+)/i);
+    if (!match)
+        return null;
+    const owner = match[1];
+    const repo = match[2];
+    if (owner && repo)
+        return `${owner}/${repo}`;
+    return null;
+}
+/** Infer OWNER/NAME from DEFT_TRIAGE_REPO or git remote origin. */
+export function inferSessionReadyRepo(projectRoot, env = process.env) {
+    const fromEnv = (env.DEFT_TRIAGE_REPO ?? "").trim();
+    if (fromEnv.length > 0 && fromEnv.includes("/"))
+        return fromEnv;
+    try {
+        const stdout = execFileSync("git", ["remote", "get-url", "origin"], {
+            cwd: projectRoot,
+            encoding: "utf8",
+            timeout: 10000,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        return normaliseRepoUrl(stdout.trim());
+    }
+    catch {
+        return null;
+    }
+}
+function readyCommand() {
+    return formatFrameworkCommand(["session:ready"]);
+}
+/**
+ * One-shot recovery: leave the worktree PreToolUse-gated-inspect green, or
+ * print the single remaining blocker.
+ */
+export function runSessionReady(projectRoot, options = {}) {
+    const started = performance.now();
+    const now = options.now ?? new Date();
+    const env = options.env ?? process.env;
+    const lines = [];
+    const steps = [];
+    const inspect = options.inspectRitual ?? ((root, opts) => inspectSessionRitual(root, opts));
+    const verify = options.verifyRitual ?? ((root, opts) => verifySessionRitual(root, opts));
+    const start = options.runStart ?? ((root, opts) => runSessionStart(root, opts));
+    const fetchAll = options.fetchAll ?? cacheFetchAll;
+    const inferRepo = options.inferRepo ?? ((root) => inferSessionReadyRepo(root, env));
+    // --- Fast path: already green for PreToolUse gated inspect ---
+    const gatedInspect = inspect(projectRoot, {
+        tier: "gated",
+        posture: "mutation",
+        now,
+        runGit: options.runGit,
+    });
+    if (gatedInspect.code === 0) {
+        const message = "OK session ready (gated ritual already fresh).";
+        lines.push(message);
+        return {
+            code: 0,
+            message,
+            path: SESSION_READY_FAST_PATH,
+            lines,
+            steps,
+            duration_ms: elapsedMs(started),
+        };
+    }
+    // --- Ensure quick-tier ritual state when missing / stale / drifted ---
+    const quickInspect = inspect(projectRoot, {
+        tier: "quick",
+        posture: "mutation",
+        now,
+        runGit: options.runGit,
+    });
+    if (quickInspect.code !== 0) {
+        steps.push("session:start");
+        const startResult = start(projectRoot, {
+            ...options.sessionStartOptions,
+            now,
+            runGit: options.runGit,
+            env,
+            writeHistory: options.sessionStartOptions?.writeHistory ?? false,
+        });
+        for (const line of startResult.lines) {
+            lines.push(line);
+        }
+        if (startResult.code !== 0) {
+            const message = startResult.lines.join("\n").trim() ||
+                `session:start failed (exit ${startResult.code}). Recovery: run \`${readyCommand()}\` again after fixing the blocker.`;
+            lines.push(message);
+            return {
+                code: startResult.code === 0 ? 1 : startResult.code,
+                message,
+                path: SESSION_READY_FAILED,
+                lines,
+                steps,
+                duration_ms: elapsedMs(started),
+            };
+        }
+    }
+    // --- Gated verify (lazy doctor + cache_fresh) ---
+    steps.push("verify:session-ritual:gated");
+    const verifyOpts = {
+        tier: "gated",
+        posture: "mutation",
+        now,
+        runGit: options.runGit,
+        runner: options.runner,
+    };
+    let verifyResult = verify(projectRoot, verifyOpts);
+    if (isGatedVerifyActuallyReady(verifyResult)) {
+        const message = "OK session ready (gated ritual verified).";
+        lines.push(message);
+        return {
+            code: 0,
+            message,
+            path: SESSION_READY_VERIFIED,
+            lines,
+            steps,
+            duration_ms: elapsedMs(started),
+        };
+    }
+    if (verifyResult.code === 0 && verifyResult.bypassed) {
+        const message = bypassedReadyFailure(verifyResult);
+        lines.push(message);
+        return {
+            code: 1,
+            message,
+            path: SESSION_READY_FAILED,
+            lines,
+            steps,
+            duration_ms: elapsedMs(started),
+        };
+    }
+    // --- Cache recovery when cache_fresh is the remaining blocker ---
+    if (!options.skipCacheRecovery && isCacheFreshFailure(verifyResult.message)) {
+        const repo = options.repo !== undefined ? options.repo : inferRepo(projectRoot);
+        if (repo === null || repo.length === 0) {
+            const message = `${verifyResult.message}\n` +
+                `  Recovery: set DEFT_TRIAGE_REPO=OWNER/NAME or run \`deft cache fetch-all --source github-issue --repo OWNER/NAME --force\`, then \`${readyCommand()}\`.`;
+            lines.push(message);
+            return {
+                code: 1,
+                message,
+                path: SESSION_READY_FAILED,
+                lines,
+                steps,
+                duration_ms: elapsedMs(started),
+            };
+        }
+        steps.push("cache:fetch-all");
+        try {
+            fetchAll({
+                source: "github-issue",
+                repo,
+                force: true,
+                cacheRoot: join(projectRoot, ".deft-cache"),
+            });
+            lines.push(`[session:ready] cache fetch-all completed for ${repo} (--force).`);
+        }
+        catch (cause) {
+            const detail = cause instanceof Error ? cause.message : String(cause);
+            const message = `session:ready cache recovery failed: ${detail}\n` +
+                `  Recovery: run \`deft cache fetch-all --source github-issue --repo ${repo} --force\`, then \`${readyCommand()}\`.`;
+            lines.push(message);
+            return {
+                code: 1,
+                message,
+                path: SESSION_READY_FAILED,
+                lines,
+                steps,
+                duration_ms: elapsedMs(started),
+            };
+        }
+        steps.push("verify:session-ritual:gated:retry");
+        verifyResult = verify(projectRoot, verifyOpts);
+        if (isGatedVerifyActuallyReady(verifyResult)) {
+            const message = "OK session ready (recovered via cache refresh).";
+            lines.push(message);
+            return {
+                code: 0,
+                message,
+                path: SESSION_READY_RECOVERED,
+                lines,
+                steps,
+                duration_ms: elapsedMs(started),
+            };
+        }
+        if (verifyResult.code === 0 && verifyResult.bypassed) {
+            const message = bypassedReadyFailure(verifyResult);
+            lines.push(message);
+            return {
+                code: 1,
+                message,
+                path: SESSION_READY_FAILED,
+                lines,
+                steps,
+                duration_ms: elapsedMs(started),
+            };
+        }
+    }
+    // --- Hard failure: surface the single remaining blocker ---
+    const message = `${verifyResult.message}\n` +
+        `  Remaining blocker after session:ready. Fix the step above, then re-run \`${readyCommand()}\`.`;
+    lines.push(message);
+    return {
+        code: verifyResult.code === 0 ? 1 : verifyResult.code,
+        message,
+        path: SESSION_READY_FAILED,
+        lines,
+        steps,
+        duration_ms: elapsedMs(started),
+    };
+}
+//# sourceMappingURL=session-ready.js.map

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

@@ -2,15 +2,33 @@ 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";
+import { type RitualState, ritualStatePath } from "./ritual-sentinel.js";
 export declare const SESSION_POSTURES: readonly ["read-only", "mutation"];
 export type SessionPosture = (typeof SESSION_POSTURES)[number];
 export declare const READ_ONLY_POSTURE: SessionPosture;
 export declare const MUTATION_POSTURE: SessionPosture;
 export declare const READ_ONLY_ALIGNMENT_MESSAGE = "Deft Directive active -- AGENTS.md loaded.";
 export declare const READ_ONLY_RESULT_MESSAGE = "read-only session posture (alignment only; no ritual-state write)";
+/** Cold (full) vs re-arm (clock/HEAD refresh) ceremony tiers (#2992). */
+export declare const SESSION_CEREMONY_TIERS: readonly ["cold", "rearm"];
+export type SessionCeremonyTier = (typeof SESSION_CEREMONY_TIERS)[number];
+export declare const COLD_CEREMONY_TIER: SessionCeremonyTier;
+export declare const REARM_CEREMONY_TIER: SessionCeremonyTier;
 export declare const QUICK_STEPS: readonly ["alignment", "branch_policy", "triage_welcome"];
 export declare const GATED_STEPS: readonly ["doctor", "cache_fresh"];
+/** Env opt-in for optional session:start network (release probe + triage cache hydrate) (#2991). */
+export declare const ENV_SESSION_START_NETWORK = "DEFT_SESSION_START_NETWORK";
+/** Human-readable skip notice when optional network is off the hot path (#2991). */
+export declare const OPTIONAL_NETWORK_SKIPPED_MESSAGE: string;
+/** Re-arm skips fat cold-path work when prior ritual is still structurally valid (#2992). */
+export declare const REARM_SKIPPED_FAT_PATH_MESSAGE: string;
+/** When --rearm is requested but state requires a full cold ceremony (#2992). */
+export declare const REARM_INELIGIBLE_PREFIX = "session re-arm refused \u2014 full cold session:start required:";
+export interface SessionStartStepTiming {
+    readonly name: string;
+    readonly duration_ms: number;
+    readonly skipped?: boolean;
+}
 export interface DefaultBranchSync {
     readonly branch: string | null;
     readonly upstream: string | null;
@@ -26,6 +44,12 @@ export interface SessionStartResult {
 export interface SessionStartOptions {
     /** #2176: read-only records alignment only; mutation runs the full quick tier. */
     readonly posture?: SessionPosture;
+    /**
+     * #2992: `rearm` refreshes ritual clock/HEAD/worktree without fat cold path
+     * (no verify:tools, triage welcome, release probe, tickler). Default `cold`.
+     * CLI: `--rearm` or `--tier=rearm`.
+     */
+    readonly ceremonyTier?: SessionCeremonyTier;
     readonly deferrals?: Readonly<Record<string, string>>;
     readonly now?: Date;
     readonly writeHistory?: boolean;
@@ -52,7 +76,38 @@ export interface SessionStartOptions {
         lines: readonly string[];
         prompted: boolean;
     };
+    /**
+     * #2991: when true, run optional network (npm release probe + triage cache
+     * empty-hydrate / self-heal) before ritual-state write. Default false so the
+     * mutation hot path does not block on GitHub/npm. CLI: `--with-network`;
+     * env: `DEFT_SESSION_START_NETWORK=1`.
+     * Ignored on re-arm tier (always skips optional network).
+     */
+    readonly allowOptionalNetwork?: boolean;
+    /** Process env for network opt-in resolution (tests inject). */
+    readonly env?: NodeJS.ProcessEnv;
 }
+/** Format preferred `session:start` recovery command for cold vs re-arm (#2992). */
+export declare function formatSessionStartRecoveryCommand(tier?: SessionCeremonyTier): string;
+export type RearmEligibility = {
+    eligible: true;
+    state: RitualState;
+    currentHead: string;
+    currentWorktree: string;
+} | {
+    eligible: false;
+    reason: string;
+};
+/**
+ * Whether a prior ritual can be re-armed without a full cold ceremony (#2992).
+ * Requires valid state, same worktree, continuous (or identical) HEAD, and
+ * previously-passing quick steps.
+ */
+export declare function assessRearmEligibility(projectRoot: string, options?: {
+    runGit?: GitRunner;
+}): RearmEligibility;
+/** Resolve whether optional session:start network work is enabled (#2991). */
+export declare function resolveSessionStartOptionalNetwork(options?: Pick<SessionStartOptions, "allowOptionalNetwork" | "env">): boolean;
 export declare function parseDeferrals(rawValues: readonly string[]): {
     deferrals: Record<string, string>;
     errors: string[];