@kynetic-ai/spec 0.10.0 → 0.12.0

package/dist/parser/shadow.js

@@ -10,6 +10,7 @@
  */
 import { execFile, spawn, spawnSync } from "node:child_process";
 import * as fs from "node:fs/promises";
+import { tmpdir } from "node:os";
 import * as path from "node:path";
 import { promisify } from "node:util";
 import { fileURLToPath } from "node:url";
@@ -38,6 +39,28 @@ async function runGitAsync(cwd, args, env) {
     });
     return { stdout: stdout.toString(), stderr: stderr.toString() };
 }
+async function stashBrokenWorktreeDir(worktreeDir) {
+    const stat = await fs.stat(worktreeDir).catch(() => null);
+    if (!stat) {
+        return null;
+    }
+    const backupDir = `${worktreeDir}.repair-backup-${Date.now()}`;
+    await fs.rename(worktreeDir, backupDir);
+    return backupDir;
+}
+async function restoreStashedWorktreeDir(backupDir, worktreeDir) {
+    if (!backupDir) {
+        return;
+    }
+    await fs.rm(worktreeDir, { recursive: true, force: true });
+    await fs.rename(backupDir, worktreeDir);
+}
+async function discardStashedWorktreeDir(backupDir) {
+    if (!backupDir) {
+        return;
+    }
+    await fs.rm(backupDir, { recursive: true, force: true });
+}
 function runGitSync(cwd, args) {
     const result = spawnSync("git", args, {
         cwd,
@@ -49,6 +72,129 @@ function runGitSync(cwd, args) {
         stdout: (result.stdout || "").toString(),
     };
 }
+/**
+ * Parse git version from `git --version` output.
+ * Returns [major, minor, patch] or null if unparseable.
+ */
+export function getGitVersion(cwd) {
+    const result = spawnSync("git", ["--version"], {
+        cwd,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+    });
+    if (result.error || result.status !== 0)
+        return null;
+    const match = (result.stdout || "").match(/(\d+)\.(\d+)\.(\d+)/);
+    if (!match)
+        return null;
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+/**
+ * Check if the installed git supports `git worktree add --orphan` (requires >= 2.42.0).
+ */
+export function gitSupportsOrphanWorktree(cwd) {
+    const version = getGitVersion(cwd);
+    if (!version)
+        return false;
+    const [major, minor] = version;
+    return major > 2 || (major === 2 && minor >= 42);
+}
+/**
+ * Fallback for creating an orphan branch when git < 2.42.
+ *
+ * Strategy:
+ * 1. Create a temp bare repo in the OS temp directory
+ * 2. Create an orphan branch with an empty commit there
+ * 3. Push that branch to the project repo (via file:// protocol)
+ * 4. Clean up the temp repo
+ * 5. Attach using standard `git worktree add <dir> <branch>`
+ *
+ * This approach NEVER modifies the project's working tree.
+ *
+ * AC: @config-shadow ac-10
+ */
+export async function createOrphanBranchFallback(projectRoot, branchName, directoryName) {
+    const tmpDir = await fs.mkdtemp(path.join(tmpdir(), "kspec-orphan-"));
+    try {
+        // 1. Init a bare repo in the temp dir
+        await runGitAsync(tmpDir, ["init", "--bare"]);
+        // 2. Create the orphan branch using a temporary non-bare clone.
+        //    We need a working tree to make a commit, so clone the bare repo.
+        const workDir = await fs.mkdtemp(path.join(tmpdir(), "kspec-orphan-work-"));
+        try {
+            await runGitAsync(workDir, ["clone", tmpDir, "."]);
+            await runGitAsync(workDir, [
+                "config",
+                "user.email",
+                "kspec@localhost",
+            ]);
+            await runGitAsync(workDir, [
+                "config",
+                "user.name",
+                "kspec",
+            ]);
+            // Create an orphan branch (checkout --orphan works on all git versions)
+            await runGitAsync(workDir, [
+                "checkout",
+                "--orphan",
+                branchName,
+            ]);
+            // Remove any files that might have been staged
+            try {
+                await runGitAsync(workDir, ["rm", "-rf", "."]);
+            }
+            catch {
+                // May fail if nothing to remove (empty repo) - that's fine
+            }
+            // Create an empty initial commit
+            await runGitAsync(workDir, [
+                "commit",
+                "--allow-empty",
+                "-m",
+                `Initialize ${branchName}`,
+            ]);
+            // Push the orphan branch back to the bare repo
+            await runGitAsync(workDir, [
+                "push",
+                "origin",
+                branchName,
+            ]);
+        }
+        finally {
+            await fs.rm(workDir, { recursive: true, force: true });
+        }
+        // 3. Push from the temp bare repo to the project repo
+        //    Use file:// protocol to ensure git treats it as a proper remote
+        await runGitAsync(tmpDir, [
+            "push",
+            `file://${path.resolve(projectRoot)}`,
+            branchName,
+        ]);
+    }
+    finally {
+        // 4. Clean up the temp bare repo
+        await fs.rm(tmpDir, { recursive: true, force: true });
+    }
+    // 5. Attach worktree using standard git worktree add (no --orphan flag)
+    await runGitAsync(projectRoot, [
+        "worktree",
+        "add",
+        directoryName,
+        branchName,
+    ]);
+    // 6. Remove all tracked files from the worktree since the fallback
+    //    created an empty commit but `git worktree add` may still populate
+    //    the index from the branch. Clear anything that appeared.
+    try {
+        const { stdout } = await runGitAsync(path.join(projectRoot, directoryName), ["ls-files"]);
+        if (stdout.trim()) {
+            await runGitAsync(path.join(projectRoot, directoryName), ["rm", "-rf", "."]);
+        }
+    }
+    catch {
+        // Nothing to remove — expected for an empty commit
+    }
+}
 // Import getVerboseMode for checking CLI --debug-shadow flag
 // We use a getter function to avoid issues with circular dependencies
 let getVerboseModeFunc = null;
@@ -76,6 +222,11 @@ export const SHADOW_BRANCH_NAME = "kspec-meta";
  * Default shadow worktree directory
  */
 export const SHADOW_WORKTREE_DIR = ".kspec";
+/**
+ * Sessions storage directory name (at project root, separate from shadow worktree).
+ * AC: @session-storage-modes ac-sessions-dir
+ */
+export const SESSIONS_WORKTREE_DIR = ".kspec-sessions";
 /**
  * Get effective branch name from options or default.
  * AC: @config-shadow ac-7 — backward compat when called without config
@@ -90,6 +241,54 @@ function getBranchName(options) {
 function getDirectoryName(options) {
     return options?.directory ?? SHADOW_WORKTREE_DIR;
 }
+/**
+ * Get effective remote name from options or default.
+ * AC: @config-shadow ac-3 ac-7 — resolves configured remote for fetch/push/pull.
+ * Named remotes use the name directly; path/URL remotes use the auto-created "kspec-specs".
+ */
+export function getRemoteName(options) {
+    if (!options?.remote)
+        return "origin";
+    const remoteType = options.remoteType ?? "named";
+    if (remoteType === "path" || remoteType === "url")
+        return "kspec-specs";
+    return options.remote;
+}
+/**
+ * Resolve the remote target used for direct ls-remote/fetch queries.
+ * Named remotes use the configured name, while path remotes expand "~".
+ */
+function getRemoteQueryTarget(options) {
+    if (!options?.remote)
+        return "origin";
+    const remoteType = options.remoteType ?? "named";
+    if (remoteType !== "path") {
+        return options.remote;
+    }
+    if (options.remote.startsWith("~")) {
+        return options.remote.replace(/^~/, process.env.HOME || process.env.USERPROFILE || "~");
+    }
+    return options.remote;
+}
+/**
+ * Check whether the shadow branch exists on the configured/default remote.
+ */
+export async function remoteShadowBranchExists(projectRoot, options) {
+    const branchName = getBranchName(options);
+    const remoteType = options?.remoteType ?? "named";
+    const remoteName = getRemoteName(options);
+    const remoteQueryTarget = getRemoteQueryTarget(options);
+    if (options?.remote) {
+        if (remoteType === "named" && !(await hasRemote(projectRoot, remoteName))) {
+            return false;
+        }
+        return remoteBranchExists(projectRoot, branchName, remoteQueryTarget);
+    }
+    if (!(await hasRemote(projectRoot, remoteName))) {
+        return false;
+    }
+    return remoteBranchExists(projectRoot, branchName, remoteQueryTarget);
+}
 /**
  * Check if debug mode is enabled.
  * Debug mode can be enabled via:
@@ -127,6 +326,45 @@ export function getGitRoot(dir) {
     }
     return result.stdout.trim();
 }
+function isSubmoduleCommonDir(commonDir) {
+    const segments = path.normalize(commonDir).split(path.sep).filter(Boolean);
+    const gitIndex = segments.lastIndexOf(".git");
+    return gitIndex >= 0 && segments[gitIndex + 1] === "modules";
+}
+export function resolveProjectRoots(dir) {
+    const result = runGitSync(dir, [
+        "rev-parse",
+        "--show-toplevel",
+        "--git-common-dir",
+    ]);
+    if (!result.ok) {
+        return null;
+    }
+    const [rawTopLevel, rawCommonDir] = result.stdout
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    if (!rawTopLevel || !rawCommonDir) {
+        return null;
+    }
+    const worktreeRoot = path.resolve(rawTopLevel);
+    const commonDir = path.isAbsolute(rawCommonDir)
+        ? path.resolve(rawCommonDir)
+        : path.resolve(worktreeRoot, rawCommonDir);
+    if (isSubmoduleCommonDir(commonDir) ||
+        commonDir === path.join(worktreeRoot, ".git")) {
+        return {
+            mainRoot: worktreeRoot,
+            worktreeRoot,
+            isWorktree: false,
+        };
+    }
+    return {
+        mainRoot: path.dirname(commonDir),
+        worktreeRoot,
+        isWorktree: true,
+    };
+}
 /**
  * Check if a branch exists
  */
@@ -188,20 +426,18 @@ export async function detectRunningFromShadowWorktree(cwd, configuredDirectory)
         if (!match) {
             return null;
         }
-        const gitdir = match[1];
+        const gitdir = path.resolve(cwd, match[1]);
         // Check if this is a worktree (pattern: <project>/.git/worktrees/<name>)
         if (gitdir.includes(".git/worktrees/")) {
-            const worktreesMatch = gitdir.match(/^(.+)\/\.git\/worktrees\//);
+            const worktreesMatch = gitdir.match(/^(.*?)[/\\]\.git[/\\]worktrees[/\\]/);
             if (worktreesMatch) {
                 const mainProjectRoot = worktreesMatch[1];
                 const cwdBase = path.basename(cwd);
-                const worktreeName = path.basename(gitdir);
                 // AC: ac-8 — check multiple patterns for shadow worktree detection
                 const directoryToCheck = configuredDirectory || SHADOW_WORKTREE_DIR;
-                // Check if directory name matches default, configured, or worktree contains "kspec"
+                // Exact shadow directory names are always considered shadow worktrees.
                 if (cwdBase === SHADOW_WORKTREE_DIR ||
-                    cwdBase === directoryToCheck ||
-                    worktreeName.includes("kspec")) {
+                    cwdBase === directoryToCheck) {
                     return mainProjectRoot;
                 }
                 // Additional check: see if this directory has a kspec manifest
@@ -239,8 +475,8 @@ export async function detectRunningFromShadowWorktree(cwd, configuredDirectory)
  * @param startDir Directory to start detection from
  * @param options Optional shadow configuration (branch name, directory)
  */
-export async function detectShadow(startDir, options) {
-    const gitRoot = getGitRoot(startDir);
+export async function detectShadow(startDir, options, mainRoot) {
+    const gitRoot = mainRoot ?? getGitRoot(startDir);
     if (!gitRoot) {
         return null;
     }
@@ -493,7 +729,12 @@ export function generateCommitMessage(operation, ref, detail) {
             parts.push(`Note on @${ref}`);
             break;
         case "task-add":
-            parts.push(`Add task: ${detail || ref}`);
+            if (ref && detail) {
+                parts.push(`Add task @${ref}: ${detail}`);
+            }
+            else {
+                parts.push(`Add task: ${detail || ref}`);
+            }
             break;
         case "inbox-add":
             parts.push(`Inbox: ${detail?.slice(0, 50)}${(detail?.length || 0) > 50 ? "..." : ""}`);
@@ -573,6 +814,7 @@ export async function commitIfShadow(shadowConfig, operation, ref, detail, verbo
     const message = generateCommitMessage(operation, ref, detail);
     const committed = await shadowAutoCommit(shadowConfig.worktreeDir, message, verbose);
     // AC: @shadow-sync ac-1 - Fire-and-forget push after each commit
+    // AC: @shadow-write-sync ac-write-always-syncs — writes always sync via push path
     if (committed) {
         shadowPushAsync(shadowConfig.worktreeDir, verbose);
     }
@@ -650,6 +892,30 @@ export async function fetchRemote(projectRoot, remoteName = "origin") {
         return false;
     }
 }
+/**
+ * Check if the local shadow branch has unpushed commits ahead of upstream.
+ * Returns true if local is ahead, false otherwise (including when upstream
+ * ref doesn't exist or an error occurs).
+ *
+ * @param worktreeDir Path to shadow worktree
+ */
+export async function isAheadOfUpstream(worktreeDir) {
+    try {
+        const { stdout } = await runGitAsync(worktreeDir, [
+            "rev-list",
+            "--left-right",
+            "--count",
+            "HEAD...@{u}",
+        ]);
+        const [aheadStr] = stdout.trim().split("\t");
+        const ahead = parseInt(aheadStr, 10);
+        return ahead > 0;
+    }
+    catch {
+        // No upstream ref or other error — not ahead
+        return false;
+    }
+}
 /**
  * Push shadow branch to remote with tracking.
  * Returns true if push succeeded, false otherwise.
@@ -817,9 +1083,117 @@ function noteShadowPushSuccess(worktreeDir) {
     shadowPushFailureCounts.delete(worktreeDir);
 }
 /**
- * Fire-and-forget push to remote.
+ * Pull-rebase from remote before pushing, using the kspec merge driver for
+ * YAML conflict resolution.
+ *
+ * AC: @config-shadow ac-11 — pull-rebase before push prevents divergence
+ *
+ * @returns true if pull succeeded (or was unnecessary), false on conflict
+ */
+async function pullRebaseBeforePush(worktreeDir, branchName, debug, options) {
+    try {
+        // Fetch latest remote state for the shadow branch specifically.
+        // Using the worktree dir for fetch ensures we use the branch's tracking config.
+        try {
+            await runGitAsync(worktreeDir, ["fetch"]);
+        }
+        catch {
+            if (debug) {
+                console.error("[DEBUG] Shadow pull-rebase: fetch failed, skipping pull");
+            }
+            // Fetch failure is non-fatal — push may still succeed if already up to date
+            return true;
+        }
+        // AC: @config-shadow ac-3 — resolve the configured remote name from git config
+        // instead of hardcoding "origin", so custom shadow.remote setups work correctly
+        const projectRoot = path.dirname(worktreeDir);
+        let remoteName = "origin";
+        try {
+            const { stdout } = await runGitAsync(worktreeDir, [
+                "config",
+                `branch.${branchName}.remote`,
+            ]);
+            const configured = stdout.trim();
+            if (configured) {
+                remoteName = configured;
+            }
+        }
+        catch {
+            // Fall back to origin if config lookup fails
+        }
+        const remoteHasBranch = await remoteBranchExists(projectRoot, branchName, remoteName);
+        if (!remoteHasBranch) {
+            if (debug) {
+                console.error("[DEBUG] Shadow pull-rebase: no remote branch yet, skipping pull");
+            }
+            return true;
+        }
+        // Check if there are any upstream changes to integrate.
+        // If local is already at or ahead of remote, skip the pull.
+        try {
+            const { stdout } = await runGitAsync(worktreeDir, [
+                "rev-list",
+                "--count",
+                `${branchName}..@{upstream}`,
+            ]);
+            const behindCount = parseInt(stdout.trim(), 10);
+            if (behindCount === 0) {
+                if (debug) {
+                    console.error("[DEBUG] Shadow pull-rebase: already up to date with remote");
+                }
+                return true;
+            }
+        }
+        catch {
+            // rev-list may fail if upstream isn't set — proceed with pull attempt
+        }
+        // Try fast-forward first (cleanest, no rebase needed)
+        try {
+            await runGitAsync(worktreeDir, ["pull", "--ff-only"]);
+            if (debug) {
+                console.error("[DEBUG] Shadow pull-rebase: fast-forward succeeded");
+            }
+            return true;
+        }
+        catch {
+            // FF failed, need rebase
+        }
+        // Fall back to rebase — the kspec merge driver handles YAML conflicts
+        try {
+            await runGitAsync(worktreeDir, ["pull", "--rebase"]);
+            if (debug) {
+                console.error("[DEBUG] Shadow pull-rebase: rebase succeeded");
+            }
+            return true;
+        }
+        catch {
+            // Rebase failed — abort and report
+        }
+        // Abort the failed rebase so local state is clean
+        try {
+            await runGitAsync(worktreeDir, ["rebase", "--abort"]);
+        }
+        catch {
+            // May not be in rebase state
+        }
+        if (debug) {
+            console.error("[DEBUG] Shadow pull-rebase: conflict detected, push skipped");
+        }
+        return false;
+    }
+    catch (err) {
+        if (debug) {
+            console.error("[DEBUG] Shadow pull-rebase error:", err);
+        }
+        // Pull failure is non-fatal — still attempt push
+        return true;
+    }
+}
+/**
+ * Fire-and-forget push to remote with pull-rebase-before-push.
  * AC-1: Called after each auto-commit when tracking is configured.
  * AC-8: Automatically sets up tracking if main branch has remote.
+ * AC: @config-shadow ac-11 — pull-rebase before push for bidirectional sync.
  * Push failures are surfaced as warnings, but local commits still succeed.
  *
  * AC: @config-shadow ac-7 — backward compat when called without config
@@ -847,6 +1221,14 @@ export async function shadowPushAsync(worktreeDir, verbose, options) {
         }
         return; // AC: @shadow-sync ac-4 - silently skip if no tracking
     }
+    // AC: @config-shadow ac-11 — pull-rebase before pushing to integrate remote changes
+    // AC: @shadow-write-sync ac-write-always-syncs — writes always perform full sync
+    const branchName = getBranchName(options);
+    const pullOk = await pullRebaseBeforePush(worktreeDir, branchName, debug, options);
+    if (!pullOk) {
+        noteShadowPushFailure(worktreeDir, "Pull-rebase failed due to conflicts. Run `kspec shadow resolve` to fix.");
+        return;
+    }
     try {
         if (debug) {
             console.error(`[DEBUG] Shadow push: git push (cwd: ${worktreeDir})`);
@@ -915,7 +1297,22 @@ export async function shadowPushAsync(worktreeDir, verbose, options) {
  * @param worktreeDir Path to shadow worktree
  * @param options Optional shadow configuration
  */
-export async function shadowPull(worktreeDir, options) {
+// In-flight dedup: if a pull is already running for this worktree, piggyback
+// on its result instead of starting a concurrent stash/pull/pop sequence.
+const pullInflight = new Map();
+export function shadowPull(worktreeDir, options) {
+    const key = path.resolve(worktreeDir);
+    const existing = pullInflight.get(key);
+    if (existing) {
+        return existing;
+    }
+    const promise = shadowPullImpl(worktreeDir, options).finally(() => {
+        pullInflight.delete(key);
+    });
+    pullInflight.set(key, promise);
+    return promise;
+}
+async function shadowPullImpl(worktreeDir, options) {
     const branchName = getBranchName(options);
     const result = {
         success: false,
@@ -937,17 +1334,41 @@ export async function shadowPull(worktreeDir, options) {
         return result;
     }
     // Check if remote branch exists before attempting pull
+    // AC: @config-shadow ac-3 — use configured remote instead of hardcoded origin
+    const remoteName = getRemoteName(options);
     // Fetch first to ensure refs are up to date
-    await fetchRemote(projectRoot);
-    const remoteHasBranch = await remoteBranchExists(projectRoot, branchName);
+    await fetchRemote(projectRoot, remoteName);
+    const remoteHasBranch = await remoteBranchExists(projectRoot, branchName, remoteName);
     if (!remoteHasBranch) {
         // Remote branch doesn't exist yet - nothing to pull, but success
         result.success = true;
         return result;
     }
+    // Stash uncommitted changes before pulling to avoid false conflict reports
+    let stashed = false;
+    try {
+        const { stdout } = await runGitAsync(worktreeDir, ["stash", "push", "-m", "shadow-sync-auto"]);
+        stashed = !stdout.includes("No local changes");
+    }
+    catch {
+        // If stash fails, skip the pull entirely — don't risk reporting a false conflict
+        result.success = true;
+        return result;
+    }
+    const unstash = async () => {
+        if (stashed) {
+            try {
+                await runGitAsync(worktreeDir, ["stash", "pop"]);
+            }
+            catch {
+                // Stash pop conflict is unlikely but leave stash intact if it happens
+            }
+        }
+    };
     try {
         // Try fast-forward only first (cleanest)
         await runGitAsync(worktreeDir, ["pull", "--ff-only"]);
+        await unstash();
         result.success = true;
         result.pulled = true;
         return result;
@@ -958,6 +1379,7 @@ export async function shadowPull(worktreeDir, options) {
     try {
         // AC: @shadow-sync ac-6 - Fall back to rebase
         await runGitAsync(worktreeDir, ["pull", "--rebase"]);
+        await unstash();
         result.success = true;
         result.pulled = true;
         return result;
@@ -972,6 +1394,7 @@ export async function shadowPull(worktreeDir, options) {
     catch {
         // May not be in rebase state, ignore
     }
+    await unstash();
     result.hadConflict = true;
     result.error = "Sync conflict detected. Run `kspec shadow resolve` to fix.";
     return result;
@@ -1004,6 +1427,135 @@ export async function shadowSync(worktreeDir, options) {
     }
     return pullResult;
 }
+// ─── Lazy Drift Check ────────────────────────────────────────────────────────
+const FETCH_TIMEOUT_MS = 5000;
+/**
+ * Spawn a git command with a hard timeout. Returns stdout/stderr on success,
+ * throws on non-zero exit or timeout. On timeout, sends SIGTERM then SIGKILL.
+ *
+ * Used for drift check fetch only — other git ops continue using runGitAsync.
+ *
+ * AC: @shadow-lazy-read-sync ac-fetch-timeout
+ */
+export function spawnGitWithTimeout(cwd, args, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("git", args, {
+            cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (d) => {
+            stdout += d;
+        });
+        child.stderr.on("data", (d) => {
+            stderr += d;
+        });
+        let promiseSettled = false;
+        let processExited = false;
+        const timer = setTimeout(() => {
+            child.kill("SIGTERM");
+            setTimeout(() => {
+                if (!processExited)
+                    child.kill("SIGKILL");
+            }, 1000);
+            promiseSettled = true;
+            reject(new Error(`git ${args[0]} timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        child.on("close", (code) => {
+            processExited = true;
+            clearTimeout(timer);
+            if (promiseSettled)
+                return;
+            promiseSettled = true;
+            if (code === 0)
+                resolve({ stdout, stderr });
+            else
+                reject(new Error(`git ${args[0]} exited ${code}: ${stderr}`));
+        });
+    });
+}
+/**
+ * Lightweight drift check: determine whether local shadow branch needs
+ * to pull from remote. Uses FETCH_HEAD mtime to avoid redundant fetches,
+ * and ahead/behind counts to decide if a pull is needed.
+ *
+ * AC: @shadow-lazy-read-sync ac-drift-check
+ * AC: @shadow-lazy-read-sync ac-fetch-head-location
+ * AC: @shadow-lazy-read-sync ac-fetch-head-freshness
+ * AC: @shadow-lazy-read-sync ac-fetch-when-stale
+ * AC: @shadow-lazy-read-sync ac-fetch-timeout-no-error
+ * AC: @shadow-lazy-read-sync ac-fetch-timeout-debug-log
+ * AC: @shadow-lazy-read-sync ac-pull-when-behind
+ * AC: @shadow-lazy-read-sync ac-no-pull-when-ahead
+ * AC: @shadow-lazy-read-sync ac-pull-when-diverged
+ * AC: @shadow-lazy-read-sync ac-upstream-ref-missing
+ * AC: @shadow-lazy-read-sync ac-no-drift-fast-path
+ * AC: @shadow-lazy-read-sync ac-threshold-from-config
+ *
+ * @returns true if shadowPull() should be called, false if local state is current
+ */
+export async function shadowNeedsSync(worktreeDir, remoteName, thresholdMs) {
+    // 1. Resolve FETCH_HEAD path for this worktree
+    // AC: ac-fetch-head-location — use rev-parse --git-path from worktree dir
+    const { stdout: fetchHeadRaw } = await runGitAsync(worktreeDir, [
+        "rev-parse",
+        "--git-path",
+        "FETCH_HEAD",
+    ]);
+    const fetchHeadPath = path.resolve(worktreeDir, fetchHeadRaw.trim());
+    // 2. Check freshness — if stale or missing, fetch with timeout
+    // AC: ac-fetch-head-freshness, ac-fetch-when-stale
+    let fetchNeeded = true;
+    try {
+        const stat = await fs.stat(fetchHeadPath);
+        fetchNeeded = Date.now() - stat.mtimeMs > thresholdMs;
+    }
+    catch {
+        // No FETCH_HEAD — need to fetch
+    }
+    if (fetchNeeded) {
+        try {
+            // AC: ac-fetch-timeout — kill if exceeds FETCH_TIMEOUT_MS
+            await spawnGitWithTimeout(worktreeDir, ["fetch", remoteName], FETCH_TIMEOUT_MS);
+        }
+        catch (err) {
+            // AC: ac-fetch-timeout-no-error — no error surfaced to user
+            // AC: ac-fetch-timeout-debug-log — debug log if enabled
+            if (isDebugEnabled()) {
+                console.error(`[DEBUG] shadow drift-check: fetch failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            return false;
+        }
+    }
+    // 3. Check ahead/behind — only sync when behind or diverged
+    // AC: ac-pull-when-behind, ac-no-pull-when-ahead, ac-pull-when-diverged
+    try {
+        const { stdout } = await runGitAsync(worktreeDir, [
+            "rev-list",
+            "--left-right",
+            "--count",
+            "HEAD...@{u}",
+        ]);
+        const [, behind] = stdout.trim().split("\t").map(Number);
+        // AC: ac-no-drift-fast-path — behind === 0 means no pull needed
+        return behind > 0;
+    }
+    catch {
+        // AC: ac-upstream-ref-missing — force sync as safer default
+        return true;
+    }
+}
+/**
+ * Check if debug logging is enabled (KSPEC_DEBUG=1 or --debug-shadow).
+ */
+function isDebugEnabled() {
+    if (process.env.KSPEC_DEBUG === "1")
+        return true;
+    if (getVerboseModeFunc?.())
+        return true;
+    return false;
+}
 /**
  * Check if .gitignore has uncommitted changes
  */
@@ -1092,6 +1644,123 @@ async function ensureGitignore(projectRoot, options) {
         throw new ShadowError(`Failed to update .gitignore: ${error}`, "GIT_ERROR", "Check file permissions for .gitignore");
     }
 }
+/**
+ * Add .kspec-sessions/ to root .gitignore if not already present.
+ * Does NOT commit — caller is responsible for committing if needed.
+ *
+ * AC: @session-storage-modes ac-gitignore
+ *
+ * @param projectRoot Git repository root
+ * @returns true if entry was added, false if already present
+ */
+export async function needsSessionsGitignore(projectRoot) {
+    const gitignorePath = path.join(projectRoot, ".gitignore");
+    let content = "";
+    try {
+        content = await fs.readFile(gitignorePath, "utf-8");
+    }
+    catch {
+        // File doesn't exist — entry is needed
+        return true;
+    }
+    const lines = content.split("\n");
+    const patterns = [
+        SESSIONS_WORKTREE_DIR,
+        `${SESSIONS_WORKTREE_DIR}/`,
+        `/${SESSIONS_WORKTREE_DIR}`,
+        `/${SESSIONS_WORKTREE_DIR}/`,
+    ];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (patterns.includes(trimmed)) {
+            return false; // Already present
+        }
+    }
+    return true;
+}
+export async function ensureSessionsGitignore(projectRoot) {
+    const gitignorePath = path.join(projectRoot, ".gitignore");
+    const entry = `${SESSIONS_WORKTREE_DIR}/`;
+    try {
+        const needed = await needsSessionsGitignore(projectRoot);
+        if (!needed) {
+            return false;
+        }
+        let content = "";
+        try {
+            content = await fs.readFile(gitignorePath, "utf-8");
+        }
+        catch {
+            // File doesn't exist, will create
+        }
+        // Add to gitignore
+        const newContent = content.endsWith("\n") || content === ""
+            ? `${content}${entry}\n`
+            : `${content}\n${entry}\n`;
+        await fs.writeFile(gitignorePath, newContent, "utf-8");
+        return true;
+    }
+    catch (error) {
+        throw new ShadowError(`Failed to update .gitignore with sessions directory: ${error}`, "GIT_ERROR", "Check file permissions for .gitignore");
+    }
+}
+/**
+ * Add sessions/ to .kspec/.gitignore to prevent legacy session data
+ * from being tracked on kspec-meta shadow branch.
+ *
+ * AC: @session-legacy-migration ac-shadow-gitignore
+ *
+ * @param projectRoot Git repository root
+ * @param options Optional shadow configuration for directory name
+ * @returns true if entry was added, false if already present
+ */
+export async function needsShadowSessionsGitignore(projectRoot, options) {
+    const directoryName = getDirectoryName(options);
+    const shadowGitignorePath = path.join(projectRoot, directoryName, ".gitignore");
+    const entry = "sessions/";
+    try {
+        const content = await fs.readFile(shadowGitignorePath, "utf-8");
+        const lines = content.split("\n");
+        if (lines.some((line) => line.trim() === entry || line.trim() === "sessions")) {
+            return false; // Already present
+        }
+        return true;
+    }
+    catch {
+        // File doesn't exist — can't add to non-existent file
+        return false;
+    }
+}
+export async function ensureShadowSessionsGitignore(projectRoot, options) {
+    const directoryName = getDirectoryName(options);
+    const shadowGitignorePath = path.join(projectRoot, directoryName, ".gitignore");
+    const entry = "sessions/";
+    try {
+        const needed = await needsShadowSessionsGitignore(projectRoot, options);
+        if (!needed) {
+            return false;
+        }
+        let content = "";
+        try {
+            content = await fs.readFile(shadowGitignorePath, "utf-8");
+        }
+        catch {
+            // File doesn't exist — this shouldn't happen since init creates it,
+            // but handle gracefully
+            return false;
+        }
+        // Add to gitignore
+        const newContent = content.endsWith("\n") || content === ""
+            ? `${content}${entry}\n`
+            : `${content}\n${entry}\n`;
+        await fs.writeFile(shadowGitignorePath, newContent, "utf-8");
+        return true;
+    }
+    catch (error) {
+        // Non-fatal — shadow gitignore update is best-effort
+        return false;
+    }
+}
 /**
  * Generate initial manifest content for shadow branch
  */
@@ -1350,14 +2019,32 @@ export async function initializeShadow(projectRoot, options = {}) {
     if (remoteExists) {
         remoteHasShadow = await remoteBranchExists(projectRoot, branchName, remoteName);
     }
+    let stashedWorktreeDir = null;
     try {
         // Step 1: Update .gitignore first (before creating worktree)
         result.gitignoreUpdated = await ensureGitignore(projectRoot, options.shadow);
+        // Step 1b: Also add .kspec-sessions/ to .gitignore
+        // AC: @session-storage-modes ac-gitignore
+        const sessionsAdded = await ensureSessionsGitignore(projectRoot);
+        if (sessionsAdded) {
+            // Commit .kspec-sessions/ gitignore entry (may be separate commit if .kspec/ was already present)
+            await runGitAsync(projectRoot, ["add", ".gitignore"]);
+            await runGitAsync(projectRoot, [
+                "commit",
+                "-m",
+                `chore: add ${SESSIONS_WORKTREE_DIR}/ to .gitignore for session storage`,
+            ]);
+        }
+        // Step 1c: Create .kspec-sessions/ directory
+        // AC: @session-storage-modes ac-sessions-dir-autocreate
+        const sessionsDir = path.join(projectRoot, SESSIONS_WORKTREE_DIR);
+        await fs.mkdir(sessionsDir, { recursive: true });
+        result.sessionsDirectoryCreated = true;
         // Step 2: Create worktree with orphan branch (or attach to existing branch)
         if (!status.worktreeExists || !status.worktreeLinked) {
             // Remove existing directory if present but not linked
             if (status.worktreeExists && !status.worktreeLinked) {
-                await fs.rm(worktreeDir, { recursive: true, force: true });
+                stashedWorktreeDir = await stashBrokenWorktreeDir(worktreeDir);
             }
             // Remove stale worktree reference if any
             try {
@@ -1405,14 +2092,20 @@ export async function initializeShadow(projectRoot, options = {}) {
             else if (!status.branchExists) {
                 // AC: @shadow-init-remote ac-2 ac-3 - No remote branch or no remote - create orphan branch
                 // AC: @config-shadow ac-1 — use configured branch name
-                await runGitAsync(projectRoot, [
-                    "worktree",
-                    "add",
-                    "--orphan",
-                    "-b",
-                    branchName,
-                    directoryName,
-                ]);
+                // AC: @config-shadow ac-10 — fallback for git < 2.42
+                if (gitSupportsOrphanWorktree(projectRoot)) {
+                    await runGitAsync(projectRoot, [
+                        "worktree",
+                        "add",
+                        "--orphan",
+                        "-b",
+                        branchName,
+                        directoryName,
+                    ]);
+                }
+                else {
+                    await createOrphanBranchFallback(projectRoot, branchName, directoryName);
+                }
                 result.branchCreated = true;
             }
             else {
@@ -1454,7 +2147,8 @@ export async function initializeShadow(projectRoot, options = {}) {
             // AC: @artifacts-directory ac-init-creates, ac-gitignore-entry
             const artifactsDir = path.join(worktreeDir, "artifacts");
             await fs.mkdir(artifactsDir, { recursive: true });
-            await fs.writeFile(path.join(worktreeDir, ".gitignore"), "# Ephemeral artifacts - reports, exports, generated files\n# Not tracked in shadow branch\nartifacts/\n", "utf-8");
+            // AC: @session-legacy-migration ac-shadow-gitignore — sessions/ not tracked on kspec-meta
+            await fs.writeFile(path.join(worktreeDir, ".gitignore"), "# Ephemeral artifacts - reports, exports, generated files\n# Not tracked in shadow branch\nartifacts/\n\n# Sessions stored in .kspec-sessions/ at project root, not on shadow branch\nsessions/\n", "utf-8");
             filesCreated = true;
         }
         // Step 4: Initial commit if files were created
@@ -1470,10 +2164,23 @@ export async function initializeShadow(projectRoot, options = {}) {
         // Step 7: Configure merge driver for semantic YAML merging
         // AC: @yaml-merge-driver ac-12
         await configureMergeDriver(projectRoot, worktreeDir);
+        // Step 8: Initialize session branch worktree if sessions.storage is "branch"
+        // AC: @session-branch-worktree ac-init
+        if (options.sessions?.storage === "branch") {
+            const { initializeSessionBranch } = await import("./session-branch.js");
+            const sessionBranchName = options.sessions.branch || "kspec-sessions";
+            const sessionResult = await initializeSessionBranch(projectRoot, sessionBranchName);
+            if (sessionResult.success) {
+                result.sessionBranchCreated = true;
+            }
+            // Non-fatal: session branch failure doesn't block shadow init
+        }
+        await discardStashedWorktreeDir(stashedWorktreeDir);
         result.success = true;
         return result;
     }
     catch (error) {
+        await restoreStashedWorktreeDir(stashedWorktreeDir, worktreeDir).catch(() => { });
         result.error = error instanceof Error ? error.message : String(error);
         return result;
     }
@@ -1492,6 +2199,8 @@ export async function repairShadow(projectRoot, options) {
     const branchName = getBranchName(options);
     const directoryName = getDirectoryName(options);
     const status = await getShadowStatus(projectRoot, options);
+    const remoteQueryTarget = getRemoteQueryTarget(options);
+    const remoteHasShadow = await remoteShadowBranchExists(projectRoot, options);
     if (status.healthy) {
         return {
             success: true,
@@ -1504,7 +2213,7 @@ export async function repairShadow(projectRoot, options) {
             pushedToRemote: false,
         };
     }
-    if (!status.branchExists) {
+    if (!status.branchExists && !remoteHasShadow) {
         // Can't repair without a branch - need full init
         return {
             success: false,
@@ -1518,8 +2227,9 @@ export async function repairShadow(projectRoot, options) {
             error: "Shadow branch does not exist. Run `kspec init` instead.",
         };
     }
-    // Branch exists but worktree is broken - repair it
+    // The branch exists locally or remotely, but the worktree is broken - repair it.
     const worktreeDir = path.join(projectRoot, directoryName);
+    let stashedWorktreeDir = null;
     try {
         // Remove stale worktree reference
         try {
@@ -1534,7 +2244,7 @@ export async function repairShadow(projectRoot, options) {
             // Ignore - worktree may not be in git's list
         }
         // Remove directory if exists (handles corrupted .git file case)
-        await fs.rm(worktreeDir, { recursive: true, force: true });
+        stashedWorktreeDir = await stashBrokenWorktreeDir(worktreeDir);
         // Prune stale worktree references (cleans up orphaned entries)
         try {
             await runGitAsync(projectRoot, ["worktree", "prune"]);
@@ -1542,6 +2252,13 @@ export async function repairShadow(projectRoot, options) {
         catch {
             // Ignore - prune is best-effort
         }
+        if (!status.branchExists && remoteHasShadow) {
+            await runGitAsync(projectRoot, [
+                "fetch",
+                remoteQueryTarget,
+                `${branchName}:${branchName}`,
+            ]);
+        }
         // Recreate worktree
         await runGitAsync(projectRoot, [
             "worktree",
@@ -1549,6 +2266,13 @@ export async function repairShadow(projectRoot, options) {
             directoryName,
             branchName,
         ]);
+        if (remoteHasShadow) {
+            const tracking = await ensureRemoteTracking(worktreeDir, projectRoot, options);
+            if (!tracking.success) {
+                throw new Error(tracking.guidance || "Failed to configure shadow branch remote tracking");
+            }
+        }
+        await discardStashedWorktreeDir(stashedWorktreeDir);
         // Install pre-commit hook
         await installShadowHook(projectRoot);
         // AC: @artifacts-directory ac-repair-recreates
@@ -1561,11 +2285,12 @@ export async function repairShadow(projectRoot, options) {
             gitignoreUpdated: false,
             initialCommit: false,
             alreadyExists: false,
-            createdFromRemote: false,
+            createdFromRemote: !status.branchExists && remoteHasShadow,
             pushedToRemote: false,
         };
     }
     catch (error) {
+        await restoreStashedWorktreeDir(stashedWorktreeDir, worktreeDir).catch(() => { });
         return {
             success: false,
             branchCreated: false,