@deftai/directive-core 0.83.0 → 0.84.0

package/dist/check/context.js

@@ -0,0 +1,28 @@
+import { existsSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+/** True when `path` is the directive framework source checkout root. */
+export function isFrameworkRepoRoot(path) {
+    const root = resolve(path);
+    return (existsSync(join(root, "packages", "cli", "package.json")) &&
+        existsSync(join(root, "biome.json")) &&
+        existsSync(join(root, "Taskfile.yml")));
+}
+/** Return true when running in the framework's own source checkout (#1519). */
+export function isFrameworkSourceContext(frameworkRoot, projectRoot) {
+    const fw = resolve(frameworkRoot);
+    const pr = resolve(projectRoot);
+    if (fw === pr) {
+        return true;
+    }
+    if (!isFrameworkRepoRoot(fw)) {
+        return false;
+    }
+    return pr.startsWith(`${fw}${sep}`);
+}
+/** Select the Taskfile target for the given context. */
+export function resolveCheckTarget(frameworkRoot, projectRoot) {
+    return isFrameworkSourceContext(frameworkRoot, projectRoot)
+        ? "check:framework-source"
+        : "check:consumer";
+}
+//# sourceMappingURL=context.js.map

package/dist/check/gate-lists.d.ts

@@ -0,0 +1,18 @@
+/** Gate execution order mirrors Taskfile.yml check targets (#1713 dogfood). */
+/**
+ * A check gate is either a bare Taskfile task name, or a public task plus CLI
+ * args (after `--`). Framework-only shims that are `internal: true` in
+ * Taskfile.yml cannot be shelled by name under go-task 3.50 (#2791) — use the
+ * public surface with the shim's flags instead.
+ */
+export type CheckGateSpec = string | {
+    readonly task: string;
+    readonly args?: readonly string[];
+};
+export declare function checkGateId(spec: CheckGateSpec): string;
+/** Args for `task … --taskfile <path>` (optional `--` + public CLI flags). */
+export declare function checkGateSpawnArgs(spec: CheckGateSpec, taskfilePath: string): string[];
+export declare const FRAMEWORK_CHECK_GATES: readonly CheckGateSpec[];
+export declare const CONSUMER_CHECK_GATES: readonly CheckGateSpec[];
+export declare function gatesForCheckTarget(target: string): readonly CheckGateSpec[];
+//# sourceMappingURL=gate-lists.d.ts.map

package/dist/check/gate-lists.js

@@ -0,0 +1,68 @@
+/** Gate execution order mirrors Taskfile.yml check targets (#1713 dogfood). */
+export function checkGateId(spec) {
+    return typeof spec === "string" ? spec : spec.task;
+}
+/** Args for `task … --taskfile <path>` (optional `--` + public CLI flags). */
+export function checkGateSpawnArgs(spec, taskfilePath) {
+    const task = checkGateId(spec);
+    const extra = typeof spec === "string" ? undefined : spec.args;
+    if (extra !== undefined && extra.length > 0) {
+        return [task, "--taskfile", taskfilePath, "--", ...extra];
+    }
+    return [task, "--taskfile", taskfilePath];
+}
+export const FRAMEWORK_CHECK_GATES = [
+    "ts:check-lane",
+    "toolchain:check",
+    "verify:stubs",
+    "verify:links",
+    "verify:rule-ownership",
+    "verify:biome-config",
+    "verify:content-manifest",
+    "verify:skill-external-fetch-gate",
+    "verify:contract-drift",
+    "verify:cursor-tier1",
+    "verify:go-freeze",
+    "verify:bridge-drift",
+    "verify:branch",
+    "verify:encoding",
+    "verify:forward-coverage",
+    "verify:vbrief-conformance",
+    "verify:destructive-gh-verbs",
+    "verify:scm-boundary",
+    "verify:xbrief-drift",
+    "verify:no-task-runtime",
+    "verify:cache-fresh",
+    "verify:pack-drift",
+    // Public surface for Taskfile verify-wip-cap-framework-self-check (#1124 / #2791)
+    { task: "verify:wip-cap", args: ["--allow-over-cap"] },
+    "verify:orphan-active",
+    "verify:agents-md-budget",
+    // Public surfaces for internal eval-relocation framework shims (#2791)
+    { task: "verify:eval-health-relocation", args: ["--base-ref", "origin/master"] },
+    { task: "verify:eval-triggers-relocation", args: ["--base-ref", "origin/master"] },
+    "vbrief:validate",
+    "codebase:validate-structure",
+    "verify:codebase-map-fresh",
+    "verify-strategy-output",
+];
+export const CONSUMER_CHECK_GATES = [
+    "doctor",
+    "toolchain:check-consumer",
+    "verify:branch",
+    "verify:cache-fresh",
+    "verify:wip-cap",
+    "verify:orphan-active",
+    "vbrief:validate",
+    "verify-strategy-output",
+];
+export function gatesForCheckTarget(target) {
+    if (target === "check:framework-source") {
+        return FRAMEWORK_CHECK_GATES;
+    }
+    if (target === "check:consumer") {
+        return CONSUMER_CHECK_GATES;
+    }
+    return [];
+}
+//# sourceMappingURL=gate-lists.js.map

package/dist/check/index.d.ts

@@ -1,3 +1,6 @@
-export type { CheckOrchestratorSeams } from "./orchestrator.js";
+export { dispatchCachedTaskCheck } from "./cached-orchestrator.js";
+export { type CheckGateSpec, CONSUMER_CHECK_GATES, checkGateId, checkGateSpawnArgs, FRAMEWORK_CHECK_GATES, gatesForCheckTarget, } from "./gate-lists.js";
+export type { CheckOrchestratorOptions, CheckOrchestratorSeams } from "./orchestrator.js";
 export { dispatchTaskCheck, isFrameworkRepoRoot, isFrameworkSourceContext, resolveCheckTarget, } from "./orchestrator.js";
+export { detectTestRunner, type RunnerDetectResult, runnerDetectionTable, type TestRunnerKind, } from "./runner-detect.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/check/index.js

@@ -1,2 +1,5 @@
+export { dispatchCachedTaskCheck } from "./cached-orchestrator.js";
+export { CONSUMER_CHECK_GATES, checkGateId, checkGateSpawnArgs, FRAMEWORK_CHECK_GATES, gatesForCheckTarget, } from "./gate-lists.js";
 export { dispatchTaskCheck, isFrameworkRepoRoot, isFrameworkSourceContext, resolveCheckTarget, } from "./orchestrator.js";
+export { detectTestRunner, runnerDetectionTable, } from "./runner-detect.js";
 //# sourceMappingURL=index.js.map

package/dist/check/orchestrator.d.ts

@@ -11,51 +11,9 @@
  *   1 -- one or more gates failed
  *   2 -- config error (missing args, task spawn error, etc.)
  */
-/** Seams for test isolation (allow injecting a custom task runner). */
-export interface CheckOrchestratorSeams {
-    /** Override the `task` binary path (default: "task"). */
-    readonly taskBin?: string;
-    /** Override the spawnSync implementation for unit testing. */
-    readonly spawnFn?: (cmd: string, args: string[], opts: {
-        cwd: string;
-        stdio: string;
-        env?: NodeJS.ProcessEnv;
-        timeoutMs?: number;
-    }) => {
-        status: number | null;
-        signal?: NodeJS.Signals | null;
-        error?: Error;
-    };
-    /** Child-process environment (default: process.env). */
-    readonly env?: NodeJS.ProcessEnv;
-    /** Wall-clock spawn timeout in milliseconds (default: none). */
-    readonly timeoutMs?: number;
-}
-/**
- * True when `path` is the directive framework source checkout root (not a
- * vendored `.deft/core` content deposit). Used to distinguish a maintainer
- * running `task check` from a subdirectory (#2220) from a consumer install.
- */
-export declare function isFrameworkRepoRoot(path: string): boolean;
-/**
- * Return true when running in the framework's own source checkout (#1519).
- *
- * Mirrors `is_framework_source_context` from _project_context.py with one
- * extension (#2220): when the Taskfile lives at the framework repo root,
- * `task check` may be invoked from a subdirectory (`USER_WORKING_DIR` !=
- * `TASKFILE_DIR`). Those invocations must still route to
- * `check:framework-source` so the biome lane runs. We do NOT resolve
- * symlinks on the framework root -- a consumer project may symlink
- * `.deft/core` to a local framework checkout and should still run the
- * consumer-safe gate (the deposit path lacks `packages/cli`).
- */
-export declare function isFrameworkSourceContext(frameworkRoot: string, projectRoot: string): boolean;
-/**
- * Select the Taskfile target for the given context.
- *
- * Mirrors _project_context.py::dispatch_task_check target selection.
- */
-export declare function resolveCheckTarget(frameworkRoot: string, projectRoot: string): string;
+import { type CheckOrchestratorSeams } from "./context.js";
+export type { CheckOrchestratorOptions, CheckOrchestratorSeams } from "./context.js";
+export { isFrameworkRepoRoot, isFrameworkSourceContext, resolveCheckTarget } from "./context.js";
 /**
  * Dispatch to the context-appropriate `task check` aggregate target.
  *

package/dist/check/orchestrator.js

@@ -12,52 +12,10 @@
  *   2 -- config error (missing args, task spawn error, etc.)
  */
 import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { join, resolve, sep } from "node:path";
-/**
- * True when `path` is the directive framework source checkout root (not a
- * vendored `.deft/core` content deposit). Used to distinguish a maintainer
- * running `task check` from a subdirectory (#2220) from a consumer install.
- */
-export function isFrameworkRepoRoot(path) {
-    const root = resolve(path);
-    return (existsSync(join(root, "packages", "cli", "package.json")) &&
-        existsSync(join(root, "biome.json")) &&
-        existsSync(join(root, "Taskfile.yml")));
-}
-/**
- * Return true when running in the framework's own source checkout (#1519).
- *
- * Mirrors `is_framework_source_context` from _project_context.py with one
- * extension (#2220): when the Taskfile lives at the framework repo root,
- * `task check` may be invoked from a subdirectory (`USER_WORKING_DIR` !=
- * `TASKFILE_DIR`). Those invocations must still route to
- * `check:framework-source` so the biome lane runs. We do NOT resolve
- * symlinks on the framework root -- a consumer project may symlink
- * `.deft/core` to a local framework checkout and should still run the
- * consumer-safe gate (the deposit path lacks `packages/cli`).
- */
-export function isFrameworkSourceContext(frameworkRoot, projectRoot) {
-    const fw = resolve(frameworkRoot);
-    const pr = resolve(projectRoot);
-    if (fw === pr) {
-        return true;
-    }
-    if (!isFrameworkRepoRoot(fw)) {
-        return false;
-    }
-    return pr.startsWith(`${fw}${sep}`);
-}
-/**
- * Select the Taskfile target for the given context.
- *
- * Mirrors _project_context.py::dispatch_task_check target selection.
- */
-export function resolveCheckTarget(frameworkRoot, projectRoot) {
-    return isFrameworkSourceContext(frameworkRoot, projectRoot)
-        ? "check:framework-source"
-        : "check:consumer";
-}
+import { join, resolve } from "node:path";
+import { dispatchCachedTaskCheck } from "./cached-orchestrator.js";
+import { resolveCheckTarget } from "./context.js";
+export { isFrameworkRepoRoot, isFrameworkSourceContext, resolveCheckTarget } from "./context.js";
 /**
  * Dispatch to the context-appropriate `task check` aggregate target.
  *
@@ -69,6 +27,10 @@ export function resolveCheckTarget(frameworkRoot, projectRoot) {
 export function dispatchTaskCheck(frameworkRoot, projectRoot, seams = {}) {
     const resolvedFramework = resolve(frameworkRoot);
     const resolvedProject = resolve(projectRoot);
+    const useTaskCache = seams.useTaskCache !== false && !seams.noCache;
+    if (useTaskCache) {
+        return dispatchCachedTaskCheck(resolvedFramework, resolvedProject, seams);
+    }
     const taskfilePath = join(resolvedFramework, "Taskfile.yml");
     const taskBin = seams.taskBin ?? "task";
     const target = resolveCheckTarget(resolvedFramework, resolvedProject);

package/dist/check/runner-detect.d.ts

@@ -0,0 +1,20 @@
+export type TestRunnerKind = "vitest" | "jest" | "go" | "pytest" | "none";
+export interface RunnerDetectResult {
+    readonly kind: TestRunnerKind;
+    readonly affectedArgs: readonly string[];
+    readonly source: "config" | "heuristic" | "fallback";
+    readonly message?: string;
+}
+export interface RunnerDetectOptions {
+    readonly projectRoot: string;
+    readonly override?: TestRunnerKind;
+}
+/** Auto-detect consumer test runner with explicit override (#1713). */
+export declare function detectTestRunner(options: RunnerDetectOptions): RunnerDetectResult;
+/** Human-readable detection table rows for docs. */
+export declare function runnerDetectionTable(): ReadonlyArray<{
+    runner: TestRunnerKind;
+    detection: string;
+    affectedConvention: string;
+}>;
+//# sourceMappingURL=runner-detect.d.ts.map

package/dist/check/runner-detect.js

@@ -0,0 +1,131 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { projectDefinitionPath } from "../policy/index.js";
+const RUNNER_AFFECTED = {
+    vitest: ["--changed"],
+    jest: ["--onlyChanged"],
+    go: [],
+    pytest: ["--testmon"],
+};
+function affectedArgsFor(kind) {
+    if (kind === "none") {
+        return [];
+    }
+    return RUNNER_AFFECTED[kind];
+}
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function detectFromPolicy(projectRoot) {
+    try {
+        const planPath = projectDefinitionPath(projectRoot);
+        const plan = readJson(planPath);
+        const raw = plan?.plan?.policy?.testRunner;
+        if (raw === "vitest" || raw === "jest" || raw === "go" || raw === "pytest" || raw === "none") {
+            return raw;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+function detectFromHeuristics(projectRoot) {
+    const root = resolve(projectRoot);
+    if (existsSync(join(root, "go.mod"))) {
+        return "go";
+    }
+    const pkgPath = join(root, "package.json");
+    if (existsSync(pkgPath)) {
+        const pkg = readJson(pkgPath);
+        const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
+        if ("vitest" in deps) {
+            return "vitest";
+        }
+        if ("jest" in deps || "@jest/core" in deps) {
+            return "jest";
+        }
+    }
+    if (existsSync(join(root, "pytest.ini")) ||
+        existsSync(join(root, "pyproject.toml")) ||
+        existsSync(join(root, "requirements.txt"))) {
+        return "pytest";
+    }
+    return null;
+}
+/** Auto-detect consumer test runner with explicit override (#1713). */
+export function detectTestRunner(options) {
+    if (options.override !== undefined) {
+        if (options.override === "none") {
+            return {
+                kind: "none",
+                affectedArgs: [],
+                source: "config",
+                message: "Runner override set to full-suite-only.",
+            };
+        }
+        return {
+            kind: options.override,
+            affectedArgs: affectedArgsFor(options.override),
+            source: "config",
+        };
+    }
+    const fromPolicy = detectFromPolicy(options.projectRoot);
+    if (fromPolicy !== null) {
+        return {
+            kind: fromPolicy,
+            affectedArgs: affectedArgsFor(fromPolicy),
+            source: "config",
+        };
+    }
+    const fromHeuristics = detectFromHeuristics(options.projectRoot);
+    if (fromHeuristics !== null) {
+        return {
+            kind: fromHeuristics,
+            affectedArgs: affectedArgsFor(fromHeuristics),
+            source: "heuristic",
+        };
+    }
+    return {
+        kind: "none",
+        affectedArgs: [],
+        source: "fallback",
+        message: "No supported test runner detected — merge gate uses the full suite.",
+    };
+}
+/** Human-readable detection table rows for docs. */
+export function runnerDetectionTable() {
+    return [
+        {
+            runner: "vitest",
+            detection: "package.json lists vitest, or plan.policy.testRunner = vitest",
+            affectedConvention: "vitest --changed",
+        },
+        {
+            runner: "jest",
+            detection: "package.json lists jest / @jest/core, or plan.policy.testRunner = jest",
+            affectedConvention: "jest --onlyChanged",
+        },
+        {
+            runner: "go",
+            detection: "go.mod present, or plan.policy.testRunner = go",
+            affectedConvention: "go test (native package cache)",
+        },
+        {
+            runner: "pytest",
+            detection: "pytest.ini / pyproject.toml / requirements.txt, or plan.policy.testRunner = pytest",
+            affectedConvention: "pytest --testmon",
+        },
+        {
+            runner: "none",
+            detection: "No match after config + heuristics",
+            affectedConvention: "Full suite at merge gate",
+        },
+    ];
+}
+//# sourceMappingURL=runner-detect.js.map

package/dist/eval/readback.js

@@ -1,5 +1,6 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { assertWriteTargetSafe, ProjectionContainmentError } from "../fs/projection-containment.js";
 import { MAX_LINE_CHARS } from "../triage/welcome/constants.js";
 import { evaluateHealth, healthHistoryPath } from "./health.js";
 /** Repeat-suppression window for the budgeted eval session nudge (#1703 / #1279 parity). */
@@ -124,10 +125,14 @@ function appendEvalReadbackHistory(projectRoot, nudgeKey, line, options = {}) {
         line,
     };
     try {
+        assertWriteTargetSafe(projectRoot, path);
         mkdirSync(join(path, ".."), { recursive: true });
         appendFileSync(path, `${JSON.stringify(record)}\n`, "utf8");
     }
-    catch {
+    catch (err) {
+        if (err instanceof ProjectionContainmentError) {
+            throw err;
+        }
         // observability only
     }
 }

package/dist/hooks/dispatcher.d.ts

@@ -67,6 +67,8 @@ export declare function toProjectRelativePosix(projectRoot: string, targetPath:
  * planning, not implementation dispatch — exempt from the active-scope gate (#2625).
  */
 export declare function isProposedLifecycleWrite(projectRoot: string, targetPath: string | null): boolean;
+/** Normalize hook project-root resolution on Windows (doubled drive + MSYS `/c/...`). */
+export declare function normalizeHookProjectRoot(path: string): string;
 export declare function projectRootFromHookPayload(payload: unknown, fallback: string): string;
 export declare function isHookHost(value: string): value is HookHost;
 export declare function isHookEvent(value: string): value is HookEvent;

package/dist/hooks/dispatcher.js

@@ -164,17 +164,59 @@ export function isProposedLifecycleWrite(projectRoot, targetPath) {
 function isWindowsDriveOnlyRoot(value) {
     return /^[A-Za-z]:[/\\]?$/.test(value.trim());
 }
+function hookPayloadRootCandidates(input) {
+    const candidates = [];
+    const push = (value) => {
+        if (typeof value === "string" && value.trim().length > 0) {
+            candidates.push(value.trim());
+        }
+    };
+    push(input.workspaceRoot);
+    push(input.workspace_root);
+    const workspaceRoots = input.workspace_roots;
+    if (Array.isArray(workspaceRoots)) {
+        for (const entry of workspaceRoots)
+            push(entry);
+    }
+    push(input.cwd);
+    return candidates;
+}
+/** Collapse join('C:', 'c:\\...') doubled drive prefix on Windows (#2787). */
+function collapseDoubledWindowsDrivePrefix(path) {
+    return path.replace(/^([A-Za-z]:\\)(?=[A-Za-z]:\\)/i, "");
+}
+function msysPathToWin32(path) {
+    const match = /^\/([a-zA-Z])\/(.*)$/.exec(path.trim());
+    if (match === null || match[1] === undefined || match[2] === undefined)
+        return null;
+    return `${match[1].toUpperCase()}:\\${match[2].replace(/\//g, "\\")}`;
+}
+/** Normalize hook project-root resolution on Windows (doubled drive + MSYS `/c/...`). */
+export function normalizeHookProjectRoot(path) {
+    if (process.platform !== "win32")
+        return resolve(path);
+    const trimmed = path.trim();
+    const msys = msysPathToWin32(trimmed);
+    let resolved = resolve(msys ?? trimmed);
+    const collapsed = collapseDoubledWindowsDrivePrefix(resolved);
+    if (collapsed !== resolved) {
+        resolved = resolve(collapsed);
+    }
+    if (/^[a-z]:\\/.test(resolved)) {
+        resolved = `${resolved.charAt(0).toUpperCase()}${resolved.slice(1)}`;
+    }
+    return resolved;
+}
 export function projectRootFromHookPayload(payload, fallback) {
+    const fallbackResolved = normalizeHookProjectRoot(fallback);
     const input = record(payload);
-    const fallbackResolved = resolve(fallback);
     if (input === null)
         return fallbackResolved;
-    const workspaceRoots = input.workspace_roots;
-    const candidate = firstString(input.workspaceRoot, input.workspace_root, Array.isArray(workspaceRoots) ? workspaceRoots[0] : null, input.cwd);
-    if (candidate === null || isWindowsDriveOnlyRoot(candidate)) {
-        return fallbackResolved;
+    const usable = hookPayloadRootCandidates(input).find((candidate) => !isWindowsDriveOnlyRoot(candidate));
+    if (usable !== undefined) {
+        return normalizeHookProjectRoot(usable);
     }
-    return resolve(candidate);
+    return fallbackResolved;
 }
 export function isHookHost(value) {
     return HOOK_HOSTS.includes(value);

package/dist/init-deposit/gitignore.js

@@ -22,6 +22,7 @@ const DEFT_CORE_COVERING_LINES = new Set([".deft/core/", ".deft/core"]);
  */
 export const CANONICAL_GITIGNORE_BASELINE = [
     ".deft-cache/",
+    ".deft/cache/",
     ".deft/.cli/",
     ".deft/ritual-state.json",
     ".deft/last-session.json",

package/dist/scope/decompose.js

@@ -9,6 +9,7 @@
 import { accessSync, constants, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { referenceTypeMatches } from "@deftai/directive-types";
+import { assertWriteTargetSafe, ProjectionContainmentError } from "../fs/projection-containment.js";
 import { hasArtifactSuffix, LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, resolveLifecycleRoot, } from "../layout/resolve.js";
 import { referenceWithDefaultTrust, slugify } from "../vbrief-build/build.js";
 import { EMITTED_VBRIEF_VERSION } from "../vbrief-build/constants.js";
@@ -52,7 +53,8 @@ function loadJson(path) {
     }
     return data;
 }
-function writeJson(path, data) {
+function writeJson(projectRoot, path, data) {
+    assertWriteTargetSafe(projectRoot, path);
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, formatBriefJson(data), "utf8");
 }
@@ -871,7 +873,7 @@ export function applyDecomposition(opts) {
     }
     for (let i = 0; i < childPaths.length; i += 1) {
         // biome-ignore lint/style/noNonNullAssertion: loop bound ensures these exist
-        writeJson(childPaths[i].target, childDocs[i]);
+        writeJson(projectRoot, childPaths[i].target, childDocs[i]);
     }
     let parentPlan = parent.plan;
     if (parentPlan === null || parentPlan === undefined) {
@@ -911,7 +913,7 @@ export function applyDecomposition(opts) {
     planObj.references = dedupeReferences(references
         .filter((r) => typeof r === "object" && r !== null && !Array.isArray(r))
         .map((r) => r));
-    writeJson(parentPath, parent);
+    writeJson(projectRoot, parentPath, parent);
     actions.push(`UPDATE ${parentRel} references`);
     return actions;
 }
@@ -1022,6 +1024,10 @@ export function decomposeMain(argv) {
             process.stderr.write(`ERROR: ${err.message}\n`);
             return 1;
         }
+        if (err instanceof ProjectionContainmentError) {
+            process.stderr.write(`ERROR: ${err.message}\n`);
+            return 2;
+        }
         process.stderr.write(`ERROR: ${String(err)}\n`);
         return 1;
     }

package/dist/session/git.d.ts

@@ -10,5 +10,7 @@ export declare function gitHead(projectRoot: string, runGit?: GitRunner): {
     error: string | null;
 };
 export declare function worktreePath(projectRoot: string, runGit?: GitRunner): string;
+/** True when `ancestor` is reachable from `descendant` (same commit counts). */
+export declare function gitIsAncestor(projectRoot: string, ancestor: string, descendant: string, runGit?: GitRunner): boolean | null;
 export declare function detectBranch(projectRoot: string, runGit?: GitRunner): string | null;
 //# sourceMappingURL=git.d.ts.map

package/dist/session/git.js

@@ -35,6 +35,20 @@ export function worktreePath(projectRoot, runGit = defaultGitRunner) {
     }
     return resolve(projectRoot);
 }
+/** True when `ancestor` is reachable from `descendant` (same commit counts). */
+export function gitIsAncestor(projectRoot, ancestor, descendant, runGit = defaultGitRunner) {
+    if (ancestor === descendant) {
+        return true;
+    }
+    const { code } = runGit(projectRoot, ["merge-base", "--is-ancestor", ancestor, descendant]);
+    if (code === 0) {
+        return true;
+    }
+    if (code === 1) {
+        return false;
+    }
+    return null;
+}
 export function detectBranch(projectRoot, runGit = defaultGitRunner) {
     const sym = runGit(projectRoot, ["symbolic-ref", "--short", "HEAD"]);
     if (sym.code === 0 && sym.stdout.trim()) {