@deftai/directive-core 0.78.0 → 0.79.0

package/dist/release-e2e/types.d.ts

@@ -3,7 +3,8 @@ export interface E2EConfig {
     owner: string;
     projectRoot: string;
     dryRun: boolean;
-    keepRepo: boolean;
+    /** When true, attempt gh repo delete after rehearsal (#2572 opt-in privileged mode). */
+    destroyRepo: boolean;
     /** When true, skip the npm publish dry-run rehearsal step (#1910). */
     skipNpm: boolean;
     /**
@@ -20,7 +21,8 @@ export interface ParsedE2EFlags {
     help: boolean;
     owner: string;
     dryRun: boolean;
-    keepRepo: boolean;
+    /** When true, attempt gh repo delete after rehearsal (#2572 opt-in privileged mode). */
+    destroyRepo: boolean;
     projectRoot: string | null;
     skipNpm: boolean;
     /** Opt-in: run the pinned legacy->bridge->npm-hybrid migration leg (#1912). */

package/dist/resolution/classify.d.ts

@@ -30,7 +30,7 @@ export interface ClassifySeams {
     /** Pre-cutover probe; defaults to the shared `detectPreCutover` detector. */
     readonly preCutoverProbe?: (cwd: string) => boolean;
 }
-/** Default engine probe: try `directive --version`, then `deft --version`. */
+/** Default engine probe: in-process identity, then `directive` / `deft` on PATH. */
 export declare function defaultEngineProbe(): EngineProbeResult;
 /**
  * Classify a project directory into the orthogonal resolution fact-set. All I/O

package/dist/resolution/classify.js

@@ -11,13 +11,16 @@
  *  - deposited payload version-> `../doctor/manifest.ts` + `../init-deposit/constants.ts`
  *  - committed pin            -> `./pin.ts`
  */
-import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { locateManifest, manifestTagToVersion, parseInstallManifest } from "../doctor/manifest.js";
+import { readCorePackageVersion } from "../engine-version.js";
 import { CANONICAL_INSTALL_ROOT } from "../init-deposit/constants.js";
 import { extractManagedSection, parseManagedSectionAttrs } from "../platform/agents-md.js";
+import { ENV_VAR } from "../platform/constants.js";
 import { detectPreCutover } from "../vbrief-validate/precutover.js";
+import { resolveCommandOnPath, spawnCommandText } from "../verify-env/command-spawn.js";
 import { readPin } from "./pin.js";
 /** App-source markers used for the `hasAppCode` heuristic. */
 const APP_CODE_MARKERS = [
@@ -57,22 +60,44 @@ function defaultReadText(p) {
         return null;
     }
 }
-function probeEngineVersion(binary) {
+function parseVersionFromOutput(out) {
+    const match = SEMVER_IN_TEXT_RE.exec(out);
+    return match?.[1] ?? null;
+}
+/**
+ * Prefer the engine version from the already-loaded core package when doctor /
+ * update are executing inside `@deftai/directive` (#2606).
+ */
+function readInProcessEngineVersion() {
+    const envVersion = process.env[ENV_VAR]?.trim();
+    if (envVersion) {
+        return parseVersionFromOutput(envVersion) ?? envVersion;
+    }
     try {
-        const out = execFileSync(binary, ["--version"], {
-            encoding: "utf8",
-            timeout: 5000,
-            stdio: ["ignore", "pipe", "ignore"],
-        });
-        const match = SEMVER_IN_TEXT_RE.exec(out);
-        return match?.[1] ?? null;
+        const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
+        if (!existsSync(pkgPath)) {
+            return null;
+        }
+        return readCorePackageVersion();
     }
     catch {
         return null;
     }
 }
-/** Default engine probe: try `directive --version`, then `deft --version`. */
+function probeEngineVersion(binary) {
+    const resolved = resolveCommandOnPath(binary);
+    const result = spawnCommandText(resolved ?? binary, ["--version"], { timeoutMs: 5000 });
+    if (result.status !== 0) {
+        return null;
+    }
+    return parseVersionFromOutput(result.stdout);
+}
+/** Default engine probe: in-process identity, then `directive` / `deft` on PATH. */
 export function defaultEngineProbe() {
+    const inProcess = readInProcessEngineVersion();
+    if (inProcess !== null) {
+        return { reachable: true, version: inProcess };
+    }
     for (const binary of ["directive", "deft"]) {
         const version = probeEngineVersion(binary);
         if (version !== null) {

package/dist/scope/project-definition-sync.js

@@ -1,158 +1,10 @@
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
-import { referenceTypeMatches } from "@deftai/directive-types";
 import { resolveProjectDefinitionPath } from "../layout/resolve.js";
-import { formatVbriefJson } from "./vbrief-json.js";
-import { relativeToVbrief, resolveVbriefRef, scopeIdsForFilename } from "./vbrief-ref.js";
-function rewriteProjectDefinitionPlanReference(ref, oldResolved, newRel, vbriefRoot) {
-    if (typeof ref !== "object" || ref === null || Array.isArray(ref)) {
-        return false;
-    }
-    const r = ref;
-    if (!referenceTypeMatches(String(r.type ?? ""), "plan")) {
-        return false;
-    }
-    const resolved = resolveVbriefRef(r.uri, vbriefRoot);
-    if (resolved === null || resolve(resolved) !== resolve(oldResolved)) {
-        return false;
-    }
-    const uri = r.uri;
-    const newUri = typeof uri === "string" && uri.startsWith("file://") ? `file://${newRel}` : newRel;
-    if (newUri === uri) {
-        return false;
-    }
-    r.uri = newUri;
-    return true;
-}
-function projectItemReferencesScope(item, oldResolved, newResolved, vbriefRoot) {
-    const metadata = item.metadata;
-    if (typeof metadata === "object" && metadata !== null && !Array.isArray(metadata)) {
-        const meta = metadata;
-        const sourcePath = meta.source_path;
-        if (typeof sourcePath === "string") {
-            const resolved = resolveVbriefRef(sourcePath, vbriefRoot);
-            if (resolved !== null && [oldResolved, newResolved].includes(resolve(resolved))) {
-                return true;
-            }
-        }
-        const metadataRefs = meta.references;
-        if (Array.isArray(metadataRefs)) {
-            for (const ref of metadataRefs) {
-                if (typeof ref !== "object" || ref === null || Array.isArray(ref)) {
-                    continue;
-                }
-                const r = ref;
-                if (!referenceTypeMatches(String(r.type ?? ""), "plan")) {
-                    continue;
-                }
-                const resolved = resolveVbriefRef(r.uri, vbriefRoot);
-                if (resolved !== null && [oldResolved, newResolved].includes(resolve(resolved))) {
-                    return true;
-                }
-            }
-        }
-    }
-    const refs = item.references;
-    if (Array.isArray(refs)) {
-        for (const ref of refs) {
-            if (typeof ref !== "object" || ref === null || Array.isArray(ref)) {
-                continue;
-            }
-            const r = ref;
-            if (!referenceTypeMatches(String(r.type ?? ""), "plan")) {
-                continue;
-            }
-            const resolved = resolveVbriefRef(r.uri, vbriefRoot);
-            if (resolved !== null && [oldResolved, newResolved].includes(resolve(resolved))) {
-                return true;
-            }
-        }
-    }
-    return false;
-}
-function projectItemMatchesScope(item, scopeData, oldPath, newPath, vbriefRoot) {
-    const oldResolved = resolve(oldPath);
-    const newResolved = resolve(newPath);
-    if (projectItemReferencesScope(item, oldResolved, newResolved, vbriefRoot)) {
-        return true;
-    }
-    const itemId = item.id;
-    if (typeof itemId === "string" &&
-        scopeIdsForFilename(resolve(newPath).split(/[/\\]/).pop() ?? "").has(itemId)) {
-        return true;
-    }
-    const scopePlan = scopeData.plan;
-    const scopeTitle = typeof scopePlan === "object" && scopePlan !== null && !Array.isArray(scopePlan)
-        ? scopePlan.title
-        : undefined;
-    const itemTitle = item.title;
-    return (typeof scopeTitle === "string" && typeof itemTitle === "string" && itemTitle === scopeTitle);
-}
+import { syncRegistryArtifactAfterScopeMove } from "./registry-artifact-sync.js";
 /** Best-effort sync of PROJECT-DEFINITION after a lifecycle move (#1527). */
 export function syncProjectDefinitionAfterScopeMove(scopeData, oldPath, newPath, vbriefRoot, targetStatus) {
-    const newRel = relativeToVbrief(newPath, vbriefRoot);
-    if (newRel === null) {
-        return;
-    }
     const projectRoot = dirname(resolve(vbriefRoot));
     const projectDefPath = resolveProjectDefinitionPath(projectRoot);
-    if (!existsSync(projectDefPath)) {
-        return;
-    }
-    try {
-        const projectDef = JSON.parse(readFileSync(projectDefPath, "utf8"));
-        const plan = projectDef.plan;
-        if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
-            return;
-        }
-        const p = plan;
-        let changed = false;
-        const oldResolved = resolve(oldPath);
-        const refs = p.references;
-        if (Array.isArray(refs)) {
-            for (const ref of refs) {
-                if (rewriteProjectDefinitionPlanReference(ref, oldResolved, newRel, vbriefRoot)) {
-                    changed = true;
-                }
-            }
-        }
-        const items = p.items;
-        if (Array.isArray(items)) {
-            for (const item of items) {
-                if (typeof item !== "object" || item === null || Array.isArray(item)) {
-                    continue;
-                }
-                const i = item;
-                if (!projectItemMatchesScope(i, scopeData, oldPath, newPath, vbriefRoot)) {
-                    continue;
-                }
-                if (i.status !== targetStatus) {
-                    i.status = targetStatus;
-                    changed = true;
-                }
-                let metadata = i.metadata;
-                if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata)) {
-                    metadata = {};
-                    i.metadata = metadata;
-                }
-                const meta = metadata;
-                const targetFolder = dirname(resolve(newPath)).split(/[/\\]/).pop() ?? "";
-                if (meta.source_path !== newRel) {
-                    meta.source_path = newRel;
-                    changed = true;
-                }
-                if (meta.lifecycle_folder !== targetFolder) {
-                    meta.lifecycle_folder = targetFolder;
-                    changed = true;
-                }
-            }
-        }
-        if (changed) {
-            writeFileSync(projectDefPath, formatVbriefJson(projectDef), "utf8");
-        }
-    }
-    catch {
-        /* best-effort */
-    }
+    syncRegistryArtifactAfterScopeMove(projectDefPath, scopeData, oldPath, newPath, vbriefRoot, targetStatus);
 }
 //# sourceMappingURL=project-definition-sync.js.map

package/dist/scope/registry-artifact-sync.d.ts

@@ -0,0 +1,3 @@
+/** Best-effort sync of a registry artifact (PROJECT-DEFINITION, specification, etc.) after a lifecycle move. */
+export declare function syncRegistryArtifactAfterScopeMove(registryPath: string, scopeData: Record<string, unknown>, oldPath: string, newPath: string, vbriefRoot: string, targetStatus: string): void;
+//# sourceMappingURL=registry-artifact-sync.d.ts.map

package/dist/scope/registry-artifact-sync.js

@@ -0,0 +1,159 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { referenceTypeMatches } from "@deftai/directive-types";
+import { formatVbriefJson } from "./vbrief-json.js";
+import { relativeToVbrief, resolveVbriefRef, scopeIdsForFilename } from "./vbrief-ref.js";
+function rewriteRegistryPlanReference(ref, oldResolved, newRel, vbriefRoot) {
+    if (typeof ref !== "object" || ref === null || Array.isArray(ref)) {
+        return false;
+    }
+    const r = ref;
+    if (!referenceTypeMatches(String(r.type ?? ""), "plan")) {
+        return false;
+    }
+    const resolved = resolveVbriefRef(r.uri, vbriefRoot);
+    if (resolved === null || resolve(resolved) !== resolve(oldResolved)) {
+        return false;
+    }
+    const uri = r.uri;
+    const newUri = typeof uri === "string" && uri.startsWith("file://") ? `file://${newRel}` : newRel;
+    if (newUri === uri) {
+        return false;
+    }
+    r.uri = newUri;
+    return true;
+}
+function registryItemReferencesScope(item, oldResolved, newResolved, vbriefRoot) {
+    const metadata = item.metadata;
+    if (typeof metadata === "object" && metadata !== null && !Array.isArray(metadata)) {
+        const meta = metadata;
+        const sourcePath = meta.source_path;
+        if (typeof sourcePath === "string") {
+            const resolved = resolveVbriefRef(sourcePath, vbriefRoot);
+            if (resolved !== null && [oldResolved, newResolved].includes(resolve(resolved))) {
+                return true;
+            }
+        }
+        const metadataRefs = meta.references;
+        if (Array.isArray(metadataRefs)) {
+            for (const ref of metadataRefs) {
+                if (typeof ref !== "object" || ref === null || Array.isArray(ref)) {
+                    continue;
+                }
+                const r = ref;
+                if (!referenceTypeMatches(String(r.type ?? ""), "plan")) {
+                    continue;
+                }
+                const resolved = resolveVbriefRef(r.uri, vbriefRoot);
+                if (resolved !== null && [oldResolved, newResolved].includes(resolve(resolved))) {
+                    return true;
+                }
+            }
+        }
+    }
+    const refs = item.references;
+    if (Array.isArray(refs)) {
+        for (const ref of refs) {
+            if (typeof ref !== "object" || ref === null || Array.isArray(ref)) {
+                continue;
+            }
+            const r = ref;
+            if (!referenceTypeMatches(String(r.type ?? ""), "plan")) {
+                continue;
+            }
+            const resolved = resolveVbriefRef(r.uri, vbriefRoot);
+            if (resolved !== null && [oldResolved, newResolved].includes(resolve(resolved))) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function registryItemMatchesScope(item, scopeData, oldPath, newPath, vbriefRoot) {
+    const oldResolved = resolve(oldPath);
+    const newResolved = resolve(newPath);
+    if (registryItemReferencesScope(item, oldResolved, newResolved, vbriefRoot)) {
+        return true;
+    }
+    const itemId = item.id;
+    if (typeof itemId === "string" &&
+        scopeIdsForFilename(resolve(newPath).split(/[/\\]/).pop() ?? "").has(itemId)) {
+        return true;
+    }
+    const scopePlan = scopeData.plan;
+    const scopeTitle = typeof scopePlan === "object" && scopePlan !== null && !Array.isArray(scopePlan)
+        ? scopePlan.title
+        : undefined;
+    const itemTitle = item.title;
+    return (typeof scopeTitle === "string" && typeof itemTitle === "string" && itemTitle === scopeTitle);
+}
+/** Best-effort sync of a registry artifact (PROJECT-DEFINITION, specification, etc.) after a lifecycle move. */
+export function syncRegistryArtifactAfterScopeMove(registryPath, scopeData, oldPath, newPath, vbriefRoot, targetStatus) {
+    const newRel = relativeToVbrief(newPath, vbriefRoot);
+    if (newRel === null) {
+        return;
+    }
+    if (!existsSync(registryPath)) {
+        return;
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(registryPath, "utf8"));
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return;
+        }
+        const registry = parsed;
+        const plan = registry.plan;
+        if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+            return;
+        }
+        const p = plan;
+        let changed = false;
+        const oldResolved = resolve(oldPath);
+        const refs = p.references;
+        if (Array.isArray(refs)) {
+            for (const ref of refs) {
+                if (rewriteRegistryPlanReference(ref, oldResolved, newRel, vbriefRoot)) {
+                    changed = true;
+                }
+            }
+        }
+        const items = p.items;
+        if (Array.isArray(items)) {
+            for (const item of items) {
+                if (typeof item !== "object" || item === null || Array.isArray(item)) {
+                    continue;
+                }
+                const i = item;
+                if (!registryItemMatchesScope(i, scopeData, oldPath, newPath, vbriefRoot)) {
+                    continue;
+                }
+                if (i.status !== targetStatus) {
+                    i.status = targetStatus;
+                    changed = true;
+                }
+                let metadata = i.metadata;
+                if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata)) {
+                    metadata = {};
+                    i.metadata = metadata;
+                }
+                const meta = metadata;
+                const targetFolder = dirname(resolve(newPath)).split(/[/\\]/).pop() ?? "";
+                if (meta.source_path !== newRel) {
+                    meta.source_path = newRel;
+                    changed = true;
+                }
+                if (meta.lifecycle_folder !== targetFolder) {
+                    meta.lifecycle_folder = targetFolder;
+                    changed = true;
+                }
+            }
+        }
+        if (changed) {
+            writeFileSync(registryPath, formatVbriefJson(registry), "utf8");
+        }
+    }
+    catch {
+        /* best-effort */
+    }
+}
+//# sourceMappingURL=registry-artifact-sync.js.map

package/dist/scope/specification-sync.d.ts

@@ -0,0 +1,3 @@
+/** Best-effort sync of specification.xbrief.json after a lifecycle move (#2566). */
+export declare function syncSpecificationAfterScopeMove(scopeData: Record<string, unknown>, oldPath: string, newPath: string, vbriefRoot: string, targetStatus: string): void;
+//# sourceMappingURL=specification-sync.d.ts.map

package/dist/scope/specification-sync.js

@@ -0,0 +1,16 @@
+import { dirname, resolve } from "node:path";
+import { resolveSpecArtifactPath } from "../layout/resolve.js";
+import { syncRegistryArtifactAfterScopeMove } from "./registry-artifact-sync.js";
+/** Best-effort sync of specification.xbrief.json after a lifecycle move (#2566). */
+export function syncSpecificationAfterScopeMove(scopeData, oldPath, newPath, vbriefRoot, targetStatus) {
+    const projectRoot = dirname(resolve(vbriefRoot));
+    let specPath;
+    try {
+        specPath = resolveSpecArtifactPath(projectRoot);
+    }
+    catch {
+        return;
+    }
+    syncRegistryArtifactAfterScopeMove(specPath, scopeData, oldPath, newPath, vbriefRoot, targetStatus);
+}
+//# sourceMappingURL=specification-sync.js.map

package/dist/scope/transition.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, renameSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { InstrumentedVbriefCrud, persistCrudMetrics } from "../eval/crud-telemetry.js";
 import { assertProjectionContained, ProjectionContainmentError, } from "../fs/projection-containment.js";
@@ -8,6 +8,7 @@ import { stampCompletionMetadata } from "./capacity-stamp.js";
 import { LIFECYCLE_FOLDERS, MOVE_LABELS, STATUS_PRECONDITIONS, STAY_LABELS, TRANSITIONS, } from "./constants.js";
 import { detectLifecycleFolder, updateDecomposedChildBackReferences, updateDecomposedParentBackReferences, } from "./decomposed-refs.js";
 import { syncProjectDefinitionAfterScopeMove } from "./project-definition-sync.js";
+import { syncSpecificationAfterScopeMove } from "./specification-sync.js";
 import { formatVbriefJson, utcNowIso } from "./vbrief-json.js";
 export function runTransition(action, filePath, now = new Date()) {
     if (!(action in TRANSITIONS)) {
@@ -101,30 +102,57 @@ export function runTransition(action, filePath, now = new Date()) {
     }
     const formatted = formatVbriefJson(data);
     const crud = new InstrumentedVbriefCrud({ now: () => now });
-    const writeResult = crud.update(resolvedPath, formatted, { trustedWrite: true });
-    if (!writeResult.ok) {
-        return { ok: false, message: writeResult.error ?? `CRUD update failed for ${resolvedPath}` };
-    }
-    try {
-        persistCrudMetrics(projectRoot, crud.getMetrics());
-    }
-    catch {
-        /* best-effort telemetry persistence */
-    }
     if (targetFolder !== null) {
         const destDir = join(vbriefRoot, targetFolder);
         mkdirSync(destDir, { recursive: true });
         const destPath = join(destDir, basename);
-        renameSync(resolvedPath, destPath);
+        if (existsSync(destPath)) {
+            return { ok: false, message: `Target already exists: ${destPath}` };
+        }
+        // #2578: stamp terminal status at the destination path in the same write as
+        // folder placement — never leave a non-terminal status under completed/.
+        const writeResult = crud.update(destPath, formatted, { trustedWrite: true });
+        if (!writeResult.ok) {
+            return { ok: false, message: writeResult.error ?? `CRUD update failed for ${destPath}` };
+        }
+        try {
+            unlinkSync(resolvedPath);
+        }
+        catch (err) {
+            try {
+                unlinkSync(destPath);
+            }
+            catch {
+                /* best-effort rollback */
+            }
+            return { ok: false, message: `Failed to remove source after move: ${String(err)}` };
+        }
+        try {
+            persistCrudMetrics(projectRoot, crud.getMetrics());
+        }
+        catch {
+            /* best-effort telemetry persistence */
+        }
         updateDecomposedParentBackReferences(data, resolvedPath, destPath, vbriefRoot);
         updateDecomposedChildBackReferences(data, resolvedPath, destPath, vbriefRoot);
         syncProjectDefinitionAfterScopeMove(data, resolvedPath, destPath, vbriefRoot, targetStatus);
+        syncSpecificationAfterScopeMove(data, resolvedPath, destPath, vbriefRoot, targetStatus);
         const actionLabel = MOVE_LABELS[act] ?? act.charAt(0).toUpperCase() + act.slice(1);
         return {
             ok: true,
             message: `${actionLabel} ${basename}: ${currentFolder}/ -> ${targetFolder}/ (status: ${targetStatus})`,
         };
     }
+    const writeResult = crud.update(resolvedPath, formatted, { trustedWrite: true });
+    if (!writeResult.ok) {
+        return { ok: false, message: writeResult.error ?? `CRUD update failed for ${resolvedPath}` };
+    }
+    try {
+        persistCrudMetrics(projectRoot, crud.getMetrics());
+    }
+    catch {
+        /* best-effort telemetry persistence */
+    }
     const actionLabel = STAY_LABELS[act] ?? act.charAt(0).toUpperCase() + act.slice(1);
     return {
         ok: true,

package/dist/session/cache-recovery.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Format a consumer-runnable `deft cache fetch-all` recovery command (#2574).
+ *
+ * Uses the space-separated CLI surface (not the colon task alias) and always
+ * includes required `--source` / `--repo` flags so following the hint literally
+ * reaches the handler instead of `unknown verb 'cache:fetch-all'`.
+ */
+export declare function formatCacheFetchAllRecoveryCommand(repo: string | null, options?: {
+    force?: boolean;
+}): string;
+/**
+ * Branch-aware recovery hint (#1953 Option 3, #2574 argv fix).
+ * Age-stale (or age+drift mixed) → --force bypasses TTL; drift-only → plain refetch.
+ */
+export declare function recoveryHintForStaleFailure(causes: Readonly<{
+    ageStale: boolean;
+    driftDetected: boolean;
+}>, repo?: string | null): string;
+//# sourceMappingURL=cache-recovery.d.ts.map

package/dist/session/cache-recovery.js

@@ -0,0 +1,26 @@
+import { formatFrameworkCommand } from "../render/framework-commands.js";
+const CACHE_FETCH_SOURCE = "github-issue";
+/**
+ * Format a consumer-runnable `deft cache fetch-all` recovery command (#2574).
+ *
+ * Uses the space-separated CLI surface (not the colon task alias) and always
+ * includes required `--source` / `--repo` flags so following the hint literally
+ * reaches the handler instead of `unknown verb 'cache:fetch-all'`.
+ */
+export function formatCacheFetchAllRecoveryCommand(repo, options = {}) {
+    const repoSlug = repo ?? "OWNER/NAME";
+    const args = ["cache", "fetch-all", "--source", CACHE_FETCH_SOURCE, "--repo", repoSlug];
+    if (options.force) {
+        args.push("--force");
+    }
+    return formatFrameworkCommand(args);
+}
+/**
+ * Branch-aware recovery hint (#1953 Option 3, #2574 argv fix).
+ * Age-stale (or age+drift mixed) → --force bypasses TTL; drift-only → plain refetch.
+ */
+export function recoveryHintForStaleFailure(causes, repo = null) {
+    const command = formatCacheFetchAllRecoveryCommand(repo, { force: causes.ageStale });
+    return `  Recovery: run \`${command}\` to refresh and reconcile upstream state.`;
+}
+//# sourceMappingURL=cache-recovery.js.map

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

@@ -1,3 +1,4 @@
+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 { ritualStatePath } from "./ritual-sentinel.js";
@@ -40,6 +41,7 @@ export interface SessionStartOptions {
         exitCode: number;
     };
     readonly resolveUserMd?: (projectRoot: string) => ResolveUserMdResult;
+    readonly probeEnvironment?: () => EnvironmentContext;
 }
 export declare function parseDeferrals(rawValues: readonly string[]): {
     deferrals: Record<string, string>;

package/dist/session/session-start.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { runningInsideDeftRepo } from "../doctor/paths.js";
 import { emitSessionEvalReadback } from "../eval/readback.js";
 import { MIGRATE_COMPLETION_NUDGE, shouldEmitMigrateNudge } from "../init-deposit/migrate.js";
+import { detectEnvironmentContext, environmentContextToDict, formatEnvironmentContext, } from "../platform/shell-context.js";
 import { disclosureLine } from "../policy/disclosure.js";
 import { resolvePolicy } from "../policy/resolve.js";
 import { runDefaultMode } from "../triage/welcome/default-mode.js";
@@ -187,7 +188,7 @@ export function defaultBranchSync(projectRoot, runGit = defaultGitRunner) {
     }
     return { branch, upstream, ahead, behind, warning };
 }
-function runReadOnlySessionStart(projectRoot, options, instant) {
+function runReadOnlySessionStart(projectRoot, options, instant, environment) {
     const lines = [];
     const resolveUserMd = options.resolveUserMd ?? ((root) => resolveUserMdPath({ projectRoot: root }));
     const userMd = resolveUserMd(projectRoot);
@@ -198,6 +199,7 @@ function runReadOnlySessionStart(projectRoot, options, instant) {
         : safeDiagnostic;
     lines.push(READ_ONLY_ALIGNMENT_MESSAGE);
     lines.push(userMdLine);
+    lines.push(formatEnvironmentContext(environment));
     const resultPayload = {
         ready: true,
         exit_code: 0,
@@ -217,6 +219,7 @@ function runReadOnlySessionStart(projectRoot, options, instant) {
             found: userMd.found,
             diagnostic: userMd.diagnostic,
         },
+        environment: environmentContextToDict(environment),
         message: READ_ONLY_RESULT_MESSAGE,
     };
     return { code: 0, payload: resultPayload, lines };
@@ -226,16 +229,22 @@ export function runSessionStart(projectRoot, options = {}) {
     const instant = options.now ?? new Date();
     const deferrals = options.deferrals ?? {};
     const runGit = options.runGit ?? defaultGitRunner;
+    const environment = (options.probeEnvironment ?? detectEnvironmentContext)();
     if (posture === READ_ONLY_POSTURE) {
-        return runReadOnlySessionStart(projectRoot, options, instant);
+        return runReadOnlySessionStart(projectRoot, options, instant, environment);
     }
     const { head: gitHeadValue, error: gitError } = gitHead(projectRoot, runGit);
     if (gitHeadValue === null) {
         const payload = {
             ready: false,
+            environment: environmentContextToDict(environment),
             message: gitError ?? "could not resolve git HEAD",
         };
-        return { code: 2, payload, lines: [payload.message] };
+        return {
+            code: 2,
+            payload,
+            lines: [formatEnvironmentContext(environment), payload.message],
+        };
     }
     const quickSteps = recordDeferredSteps(QUICK_STEPS, deferrals, instant);
     const gatedSteps = recordDeferredSteps(GATED_STEPS, deferrals, instant);
@@ -265,6 +274,7 @@ export function runSessionStart(projectRoot, options = {}) {
         lines.push(message);
         lines.push(userMdLine);
     }
+    lines.push(formatEnvironmentContext(environment));
     if (!quickSteps.branch_policy) {
         const result = resolvePolicy(projectRoot);
         const message = disclosureLine(result);
@@ -377,6 +387,7 @@ export function runSessionStart(projectRoot, options = {}) {
             found: userMd.found,
             diagnostic: userMd.diagnostic,
         },
+        environment: environmentContextToDict(environment),
         message: code === 0 ? "session ritual recorded" : "session ritual failed",
     };
     return { code, payload: resultPayload, lines };