@sideboard-ai/core 0.1.50 → 0.1.52

package/dist/{chunk-FV6FN6V5.js → chunk-DZFH2KLT.js}

@@ -1,13 +1,17 @@
+import {
+  isWorkspaceScratchPath
+} from "./chunk-FKOIHGKV.js";
 import {
   listThreads
-} from "./chunk-O6W3P7V3.js";
+} from "./chunk-TSRXOSVD.js";
 import {
   worktreesRoot
 } from "./chunk-M37RITA6.js";
 import {
   gh,
-  git
-} from "./chunk-AJ6ROGD7.js";
+  git,
+  resolveGhAuthToken
+} from "./chunk-7LNGIP3X.js";
 
 // src/git/worktree.ts
 import { existsSync, readdirSync } from "fs";
@@ -969,6 +973,206 @@ function buildMergeGateChecks(gate, opts = {}) {
   return rows;
 }
 
+// src/git/stack.ts
+var cachedStatus = null;
+var STATUS_TTL_MS = 6e4;
+async function detectGhStack(cwd) {
+  const now = Date.now();
+  if (cachedStatus && now - cachedStatus.at < STATUS_TTL_MS) {
+    return cachedStatus.status;
+  }
+  const probe = await gh(["stack", "view", "--help"], cwd, { reject: false });
+  if (probe.exitCode === 0) {
+    const status2 = { available: true };
+    cachedStatus = { at: now, status: status2 };
+    return status2;
+  }
+  const err = `${probe.stderr}
+${probe.stdout}`;
+  const reason = /official extension|extension install|github\/gh-stack/i.test(err) ? "Install with: gh extension install github/gh-stack" : err.trim() || "gh stack is not available";
+  const status = { available: false, reason };
+  cachedStatus = { at: now, status };
+  return status;
+}
+function resetGhStackDetectCache() {
+  cachedStatus = null;
+}
+function str(v) {
+  return typeof v === "string" ? v : v == null ? "" : String(v);
+}
+function num(v) {
+  if (typeof v === "number" && Number.isFinite(v)) return v;
+  if (typeof v === "string" && v.trim() && Number.isFinite(Number(v))) {
+    return Number(v);
+  }
+  return null;
+}
+function parseGhStackViewJson(raw) {
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(data.branches) || data.branches.length === 0) return null;
+  const trunk = str(data.trunk) || "main";
+  const currentBranch2 = str(data.currentBranch);
+  const stackNumber = num(data.stackNumber) ?? num(data.number);
+  const layers = [];
+  for (let i = 0; i < data.branches.length; i++) {
+    const b = data.branches[i];
+    if (!b || typeof b !== "object") continue;
+    const name = str(b.name);
+    if (!name) continue;
+    const pr = b.pr && typeof b.pr === "object" ? b.pr : null;
+    layers.push({
+      position: i + 1,
+      branchName: name,
+      headSha: str(b.head) || void 0,
+      baseSha: str(b.base) || void 0,
+      isCurrent: Boolean(b.isCurrent) || name === currentBranch2,
+      isMerged: Boolean(b.isMerged),
+      isQueued: Boolean(b.isQueued),
+      needsRebase: Boolean(b.needsRebase),
+      prNumber: pr ? num(pr.number) : null,
+      prUrl: pr && str(pr.url) ? str(pr.url) : null,
+      prState: pr && str(pr.state) ? str(pr.state).toUpperCase() : null,
+      title: pr && str(pr.title) ? str(pr.title) : void 0
+    });
+  }
+  if (!layers.length) return null;
+  let currentIndex = layers.findIndex((l) => l.isCurrent);
+  if (currentIndex < 0 && currentBranch2) {
+    currentIndex = layers.findIndex((l) => l.branchName === currentBranch2);
+  }
+  const { readyToMerge, blockedReason } = stackMergeReadiness(layers, currentIndex);
+  return {
+    stackNumber,
+    trunk,
+    currentBranch: currentBranch2 || layers[currentIndex]?.branchName || layers[0].branchName,
+    layers,
+    currentIndex,
+    readyToMerge,
+    blockedReason
+  };
+}
+function stackMergeReadiness(layers, throughIndex) {
+  if (throughIndex < 0 || throughIndex >= layers.length) {
+    return { readyToMerge: false, blockedReason: "Not on a stack layer" };
+  }
+  for (let i = 0; i <= throughIndex; i++) {
+    const layer = layers[i];
+    if (layer.isMerged) continue;
+    if (!layer.prNumber) {
+      return {
+        readyToMerge: false,
+        blockedReason: `Layer ${layer.branchName} has no pull request yet`
+      };
+    }
+    if (layer.needsRebase) {
+      return {
+        readyToMerge: false,
+        blockedReason: `PR #${layer.prNumber} needs rebase`
+      };
+    }
+    const state = (layer.prState ?? "").toUpperCase();
+    if (state && state !== "OPEN" && state !== "QUEUED") {
+      return {
+        readyToMerge: false,
+        blockedReason: `PR #${layer.prNumber} is ${state}`
+      };
+    }
+  }
+  return { readyToMerge: true, blockedReason: null };
+}
+async function getPrStack(cwd) {
+  const status = await detectGhStack(cwd);
+  if (!status.available) return null;
+  const result = await gh(["stack", "view", "--json"], cwd, { reject: false });
+  if (result.exitCode === 2) return null;
+  if (result.exitCode !== 0) {
+    if (/not in a stack|no stack/i.test(`${result.stderr}
+${result.stdout}`)) {
+      return null;
+    }
+    if (result.exitCode === 9) return null;
+    return null;
+  }
+  const json = result.stdout.trim();
+  if (!json) return null;
+  return parseGhStackViewJson(json);
+}
+async function isInPrStack(cwd) {
+  return Boolean(await getPrStack(cwd));
+}
+async function mergePrStack(cwd, opts) {
+  const status = await detectGhStack(cwd);
+  if (!status.available) {
+    throw new Error(status.reason);
+  }
+  const method = opts.method ?? "squash";
+  const methodFlag = method === "rebase" ? "--rebase" : method === "merge" ? "--merge" : "--squash";
+  const args = [
+    "stack",
+    "merge",
+    String(opts.through),
+    "--yes",
+    methodFlag
+  ];
+  const { exitCode, stderr, stdout } = await gh(args, cwd, { reject: false });
+  if (exitCode !== 0) {
+    throw new Error(stderr.trim() || stdout.trim() || "gh stack merge failed");
+  }
+  return { stdout };
+}
+async function initPrStack(cwd, branches, opts) {
+  if (!branches.length) throw new Error("initPrStack requires at least one branch name");
+  const status = await detectGhStack(cwd);
+  if (!status.available) throw new Error(status.reason);
+  const args = ["stack", "init"];
+  if (opts?.base) args.push("--base", opts.base);
+  args.push(...branches);
+  const { exitCode, stderr, stdout } = await gh(args, cwd, { reject: false });
+  if (exitCode !== 0) {
+    throw new Error(stderr.trim() || stdout.trim() || "gh stack init failed");
+  }
+}
+async function addPrStackLayer(cwd, branchName) {
+  if (!branchName.trim()) throw new Error("branch name required");
+  const status = await detectGhStack(cwd);
+  if (!status.available) throw new Error(status.reason);
+  const { exitCode, stderr, stdout } = await gh(
+    ["stack", "add", branchName.trim()],
+    cwd,
+    { reject: false }
+  );
+  if (exitCode !== 0) {
+    throw new Error(stderr.trim() || stdout.trim() || "gh stack add failed");
+  }
+}
+async function submitPrStack(cwd, opts) {
+  const status = await detectGhStack(cwd);
+  if (!status.available) throw new Error(status.reason);
+  const args = ["stack", "submit", "--auto"];
+  if (opts?.open) args.push("--open");
+  const { exitCode, stderr, stdout } = await gh(args, cwd, { reject: false });
+  if (exitCode !== 0) {
+    throw new Error(stderr.trim() || stdout.trim() || "gh stack submit failed");
+  }
+}
+async function checkoutPrStackLayer(cwd, target) {
+  const status = await detectGhStack(cwd);
+  if (!status.available) throw new Error(status.reason);
+  const { exitCode, stderr, stdout } = await gh(
+    ["stack", "checkout", String(target)],
+    cwd,
+    { reject: false }
+  );
+  if (exitCode !== 0) {
+    throw new Error(stderr.trim() || stdout.trim() || "gh stack checkout failed");
+  }
+}
+
 // src/git/worktree.ts
 async function lookupGithubGraphqlReset(cwd) {
   const result = await gh(["api", "rate_limit"], cwd, { reject: false });
@@ -1476,18 +1680,31 @@ async function fetchPrHead(repoPath, number, localBranch) {
   const slug = await resolveGithubRepoSlug(repoPath);
   const refspec = `+pull/${number}/head:${localBranch}`;
   const errors = [];
-  const tryFetch = async (remote) => {
-    const result = await git(["fetch", remote, refspec], repoPath, {
-      reject: false
-    });
+  const httpsRemote = slug ? `https://github.com/${slug}.git` : null;
+  const tryFetch = async (remote, opts) => {
+    const label = opts?.ghAuth ? `${remote} (gh auth)` : remote;
+    const gitOpts = { reject: false };
+    if (opts?.ghAuth) {
+      const token = await resolveGhAuthToken(repoPath);
+      if (!token) {
+        errors.push(`${label}: gh auth token unavailable`);
+        return false;
+      }
+      gitOpts.env = { GIT_TERMINAL_PROMPT: "0" };
+      gitOpts.config = {
+        "http.extraHeader": `AUTHORIZATION: bearer ${token}`
+      };
+    }
+    const result = await git(["fetch", remote, refspec], repoPath, gitOpts);
     if (result.exitCode === 0) return true;
     const detail = (result.stderr || result.stdout).trim();
-    if (detail) errors.push(`${remote}: ${detail}`);
+    if (detail) errors.push(`${label}: ${detail}`);
     return false;
   };
   let fetched = await tryFetch("origin");
-  if (!fetched && slug) {
-    fetched = await tryFetch(`https://github.com/${slug}.git`);
+  if (!fetched && httpsRemote) {
+    fetched = await tryFetch(httpsRemote);
+    if (!fetched) fetched = await tryFetch(httpsRemote, { ghAuth: true });
   }
   const localOk = async () => {
     const verify = await git(["rev-parse", "--verify", localBranch], repoPath, {
@@ -1516,18 +1733,28 @@ async function fetchPrHead(repoPath, number, localBranch) {
       }
     }
     if (oid) {
-      const ensureOid = async (remote) => {
-        const got = await git(["fetch", remote, oid], repoPath, {
-          reject: false
-        });
+      const ensureOid = async (remote, opts) => {
+        const gitOpts = { reject: false };
+        if (opts?.ghAuth) {
+          const token = await resolveGhAuthToken(repoPath);
+          if (!token) return false;
+          gitOpts.env = { GIT_TERMINAL_PROMPT: "0" };
+          gitOpts.config = {
+            "http.extraHeader": `AUTHORIZATION: bearer ${token}`
+          };
+        }
+        const got = await git(["fetch", remote, oid], repoPath, gitOpts);
         return got.exitCode === 0;
       };
       let haveObject = (await git(["cat-file", "-e", `${oid}^{commit}`], repoPath, {
         reject: false
       })).exitCode === 0;
       if (!haveObject) haveObject = await ensureOid("origin");
-      if (!haveObject && slug) {
-        haveObject = await ensureOid(`https://github.com/${slug}.git`);
+      if (!haveObject && httpsRemote) {
+        haveObject = await ensureOid(httpsRemote);
+        if (!haveObject) {
+          haveObject = await ensureOid(httpsRemote, { ghAuth: true });
+        }
       }
       if (haveObject) {
         const branched = await git(["branch", "-f", localBranch, oid], repoPath, {
@@ -1622,6 +1849,52 @@ ${add.stdout}`;
   await ensureGhPreferOrigin(worktreePath);
   return { branchName, worktreePath };
 }
+async function createExistingBranchWorktree(opts) {
+  const branchName = opts.branchName.trim();
+  if (!branchName) throw new Error("branch name required");
+  const worktreePath = join(worktreesRoot(opts.repoPath), opts.slug);
+  if (existsSync(worktreePath)) {
+    throw new Error(`Worktree already exists at ${worktreePath}`);
+  }
+  await ensureGhPreferOrigin(opts.repoPath);
+  await git(["fetch", "origin", "--prune"], opts.repoPath, { reject: false });
+  if (!branchName.startsWith("origin/") && !branchName.startsWith("refs/")) {
+    await git(["fetch", "origin", branchName], opts.repoPath, { reject: false });
+  }
+  const existing = await listWorktrees(opts.repoPath);
+  const already = existing.find((w) => w.branch === branchName);
+  if (already?.path) {
+    throw new Error(
+      `Branch ${branchName} is already checked out at ${already.path}`
+    );
+  }
+  const startPoint = await resolveWorktreeStartPoint(opts.repoPath, branchName);
+  const add = await git(
+    ["worktree", "add", worktreePath, startPoint],
+    opts.repoPath,
+    { reject: false }
+  );
+  if (add.exitCode !== 0) {
+    const retry = await git(
+      ["worktree", "add", worktreePath, branchName],
+      opts.repoPath,
+      { reject: false }
+    );
+    if (retry.exitCode !== 0) {
+      throw new Error(
+        `Failed to create worktree for ${branchName}: ${retry.stderr.trim() || add.stderr.trim() || retry.stdout.trim() || add.stdout.trim() || `exit ${add.exitCode}`}`
+      );
+    }
+  }
+  const head = await git(["rev-parse", "--abbrev-ref", "HEAD"], worktreePath, {
+    reject: false
+  });
+  if (head.stdout.trim() === "HEAD" || head.stdout.trim() !== branchName) {
+    await git(["checkout", "-B", branchName], worktreePath, { reject: false });
+  }
+  await ensureGhPreferOrigin(worktreePath);
+  return { branchName, worktreePath };
+}
 async function removeWorktree(repoPath, worktreePath, opts) {
   await git(["worktree", "remove", "--force", worktreePath], repoPath, {
     reject: false
@@ -1651,8 +1924,27 @@ async function listWorktrees(repoPath) {
   return entries;
 }
 async function isDirty(worktreePath) {
-  const { stdout } = await git(["status", "--porcelain"], worktreePath);
-  return stdout.trim().length > 0;
+  const { stdout } = await git(["status", "--porcelain", "-uall"], worktreePath);
+  for (const line of stdout.split("\n")) {
+    if (!line.trim()) continue;
+    const rel = porcelainStatusPath(line);
+    if (!rel || isSideboardScratchPath(rel)) continue;
+    return true;
+  }
+  return false;
+}
+function isSideboardScratchPath(relativePath) {
+  return isWorkspaceScratchPath(relativePath);
+}
+function porcelainStatusPath(line) {
+  const rest = line.length >= 3 ? line.slice(3) : "";
+  if (!rest) return "";
+  const arrow = rest.lastIndexOf(" -> ");
+  const raw = arrow >= 0 ? rest.slice(arrow + 4) : rest;
+  if (raw.startsWith('"') && raw.endsWith('"')) {
+    return raw.slice(1, -1).replace(/\\([\\"])/g, "$1");
+  }
+  return raw;
 }
 async function currentBranch(worktreePath) {
   const { stdout } = await git(["rev-parse", "--abbrev-ref", "HEAD"], worktreePath);
@@ -1670,7 +1962,7 @@ async function pushBranch(worktreePath, branchName) {
 }
 async function mergePr(cwd, selector, opts) {
   const slug = await resolveGithubRepoSlug(cwd);
-  const viewArgs = ["pr", "view", selector, "--json", "url,state,isDraft"];
+  const viewArgs = ["pr", "view", selector, "--json", "url,state,isDraft,number"];
   if (slug) viewArgs.push("--repo", slug);
   const before = await gh(viewArgs, cwd, { reject: false });
   if (before.exitCode !== 0 || !before.stdout.trim()) {
@@ -1678,16 +1970,29 @@ async function mergePr(cwd, selector, opts) {
   }
   let url = "";
   let isDraft = false;
+  let prNumber = null;
   try {
     const parsed = JSON.parse(before.stdout);
     url = String(parsed.url ?? "");
     isDraft = Boolean(parsed.isDraft);
+    prNumber = typeof parsed.number === "number" && Number.isFinite(parsed.number) ? parsed.number : null;
     if (String(parsed.state ?? "").toUpperCase() === "MERGED") {
       return { url, state: "MERGED" };
     }
   } catch {
     throw new Error("Could not parse pull request details");
   }
+  const stack = await getPrStack(cwd);
+  const stackLayer = stack && prNumber != null ? stack.layers.find((l) => l.prNumber === prNumber) : null;
+  if (stack && stackLayer && prNumber != null) {
+    const throughIndex = stack.layers.findIndex((l) => l.prNumber === prNumber);
+    const gate = stackMergeReadiness(stack.layers, throughIndex);
+    if (!gate.readyToMerge) {
+      throw new Error(gate.blockedReason || "Stack is not ready to merge");
+    }
+    await mergePrStack(cwd, { through: prNumber, method: opts?.method ?? "squash" });
+    return { url, state: "MERGED" };
+  }
   if (isDraft) {
     const readyArgs = ["pr", "ready", selector];
     if (slug) readyArgs.push("--repo", slug);
@@ -1709,10 +2014,10 @@ async function mergePr(cwd, selector, opts) {
   const after = await gh(viewArgs, cwd, { reject: false });
   if (after.exitCode === 0 && after.stdout.trim()) {
     try {
-      const parsed = JSON.parse(after.stdout);
+      const parsed = after.stdout ? JSON.parse(after.stdout) : null;
       return {
-        url: String(parsed.url ?? url),
-        state: String(parsed.state ?? "MERGED")
+        url: String(parsed?.url ?? url),
+        state: String(parsed?.state ?? "MERGED")
       };
     } catch {
     }
@@ -1866,6 +2171,17 @@ export {
   extractGhErrorDetail,
   formatGhLandError,
   formatIpcInvokeError,
+  detectGhStack,
+  resetGhStackDetectCache,
+  parseGhStackViewJson,
+  stackMergeReadiness,
+  getPrStack,
+  isInPrStack,
+  mergePrStack,
+  initPrStack,
+  addPrStackLayer,
+  submitPrStack,
+  checkoutPrStackLayer,
   slugify,
   resolveRepoRoot,
   parseGithubSlugFromRemoteUrl,
@@ -1887,9 +2203,11 @@ export {
   fetchPrHead,
   resolveWorktreeStartPoint,
   createThreadWorktree,
+  createExistingBranchWorktree,
   removeWorktree,
   listWorktrees,
   isDirty,
+  isSideboardScratchPath,
   currentBranch,
   commitAll,
   pushBranch,

package/dist/chunk-FKOIHGKV.js

@@ -0,0 +1,21 @@
+// src/paths/workspace-scratch.ts
+var ATTACHMENTS_DIR = ".context/attachments";
+var LEGACY_ATTACHMENTS_DIR = ".sideboard/attachments";
+var ATTACHMENTS_GITIGNORE = `# Sideboard / workspace attachments (local only)
+*
+!.gitignore
+`;
+function attachmentsGitignoreBody() {
+  return ATTACHMENTS_GITIGNORE;
+}
+function isWorkspaceScratchPath(relativePath) {
+  const p = relativePath.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/$/, "");
+  return p === ATTACHMENTS_DIR || p.startsWith(`${ATTACHMENTS_DIR}/`) || p === LEGACY_ATTACHMENTS_DIR || p.startsWith(`${LEGACY_ATTACHMENTS_DIR}/`) || p === ".context" || p.startsWith(".context/");
+}
+
+export {
+  ATTACHMENTS_DIR,
+  LEGACY_ATTACHMENTS_DIR,
+  attachmentsGitignoreBody,
+  isWorkspaceScratchPath
+};

package/dist/{chunk-3NAS4MWH.js → chunk-GNML24AW.js}

@@ -1,10 +1,10 @@
 import {
   isGlobalRepoPath
-} from "./chunk-5WYEJ3F3.js";
+} from "./chunk-XX5BB7NV.js";
 import {
   ensureGhPreferOrigin,
   resolveRepoRoot
-} from "./chunk-FV6FN6V5.js";
+} from "./chunk-DZFH2KLT.js";
 import {
   appDataDir
 } from "./chunk-M37RITA6.js";

package/dist/{chunk-E35APBHV.js → chunk-H6GGDLYS.js}

@@ -2,7 +2,7 @@
 
 import {
   run
-} from "./chunk-ISY4EGF6.js";
+} from "./chunk-ZNM4MAN4.js";
 import {
   appDataDir
 } from "./chunk-7MV3RXSC.js";

package/dist/{chunk-EOYDCKQC.js → chunk-HLEX5AQ6.js}

@@ -41,6 +41,8 @@ function normalizeThread(raw) {
     agentPid: raw.agentPid ?? null,
     attachments: Array.isArray(raw.attachments) ? raw.attachments : [],
     prTitle: raw.prTitle ?? null,
+    stackId: raw.stackId ?? null,
+    stackLayer: raw.stackLayer ?? null,
     userSetTitle: Boolean(raw.userSetTitle),
     activeRuns: Array.isArray(raw.activeRuns) ? raw.activeRuns : [],
     quotaResumeAt: raw.quotaResumeAt ?? null,
@@ -65,6 +67,8 @@ function createEmptyThread(partial) {
     activeRuns: partial.activeRuns ?? [],
     prUrl: partial.prUrl ?? null,
     prTitle: partial.prTitle ?? null,
+    stackId: partial.stackId ?? null,
+    stackLayer: partial.stackLayer ?? null,
     userSetTitle: partial.userSetTitle ?? false,
     messages: partial.messages ?? [],
     attachments: partial.attachments ?? [],

package/dist/{chunk-ZQCQIWIP.js → chunk-LRLKJM3O.js}

@@ -1,6 +1,6 @@
 import {
   resolveGithubRepoSlug
-} from "./chunk-FV6FN6V5.js";
+} from "./chunk-DZFH2KLT.js";
 import {
   globalAgentCwd,
   sideboardReposDir
@@ -42,6 +42,7 @@ var COORDINATOR_TOOL_PLAYBOOK = [
   "Discover:",
   "- list_workspaces \u2014 registered repos (path + github slug when known)",
   "- list_branches / list_prs / list_issues \u2014 pass repoPath from list_workspaces (issues: Linear API or GitHub Issues)",
+  "- get_pr_stack / open_pr_stack_layers / add_stack_layer / create_pr_stack \u2014 GitHub stacked PRs (`gh stack`); one worktree per layer",
   "- list_models \u2014 only when you need a specific model (rare); otherwise leave model unset = Auto",
   "- list_threads / get_thread \u2014 fleet status (what is going on)",
   "Workspaces:",

package/dist/chunk-N5PM7HGQ.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+import {
+  ATTACHMENTS_DIR,
+  LEGACY_ATTACHMENTS_DIR,
+  attachmentsGitignoreBody
+} from "./chunk-B3SJXYIJ.js";
+
+// src/plan/plan-file.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+
+// src/plan/plan-present.ts
+var PLAN_FILE_REL = `${ATTACHMENTS_DIR}/plan.md`;
+var PLAN_FILE_NAME = "plan.md";
+var LEGACY_PLAN_FILE_REL = ".sideboard/plan.md";
+function asRecord(v) {
+  return v != null && typeof v === "object" && !Array.isArray(v) ? v : null;
+}
+function isPresentPlanToolName(name) {
+  if (!name) return false;
+  return /present_plan$/i.test(name) || /^mcp__sideboard__present_plan$/i.test(name);
+}
+function extractPresentedPlan(parts) {
+  if (!parts?.length) return null;
+  for (let i = parts.length - 1; i >= 0; i--) {
+    const p = parts[i];
+    if (p.type !== "tool" || !isPresentPlanToolName(p.name)) continue;
+    const input = asRecord(p.input) ?? {};
+    const content = typeof input.content === "string" ? input.content : typeof input.plan === "string" ? input.plan : typeof input.markdown === "string" ? input.markdown : "";
+    if (!content.trim()) continue;
+    const title = typeof input.title === "string" && input.title.trim() ? input.title.trim() : "Plan";
+    const path = typeof input.path === "string" && input.path.trim() ? input.path.trim() : PLAN_FILE_REL;
+    return { title, content: content.trim(), path, source: "present_plan" };
+  }
+  return null;
+}
+function resolvePlanMarkdown(opts) {
+  const fromTool = extractPresentedPlan(opts.parts);
+  if (fromTool) return fromTool;
+  const file = opts.fileContent?.trim();
+  if (file) {
+    return {
+      title: "Plan",
+      content: file,
+      path: PLAN_FILE_REL,
+      source: "exit_plan"
+    };
+  }
+  const text = opts.text?.trim();
+  if (text && text.length >= 80) {
+    return {
+      title: "Plan",
+      content: text,
+      path: PLAN_FILE_REL,
+      source: "text"
+    };
+  }
+  return null;
+}
+
+// src/plan/plan-file.ts
+function ensureAttachmentsGitignore(worktreePath) {
+  const gitignoreAbs = join(worktreePath, ATTACHMENTS_DIR, ".gitignore");
+  if (existsSync(gitignoreAbs)) return;
+  mkdirSync(dirname(gitignoreAbs), { recursive: true });
+  writeFileSync(gitignoreAbs, attachmentsGitignoreBody(), "utf8");
+}
+function planFileAbs(worktreePath) {
+  return join(worktreePath, PLAN_FILE_REL);
+}
+function readTextIfPresent(abs) {
+  if (!existsSync(abs)) return null;
+  try {
+    const content = readFileSync(abs, "utf8");
+    return content.trim() ? content : null;
+  } catch {
+    return null;
+  }
+}
+function readPlanFile(worktreePath) {
+  return readTextIfPresent(planFileAbs(worktreePath)) ?? readTextIfPresent(join(worktreePath, `${LEGACY_ATTACHMENTS_DIR}/plan.md`)) ?? readTextIfPresent(join(worktreePath, LEGACY_PLAN_FILE_REL));
+}
+function writePlanFile(worktreePath, content) {
+  ensureAttachmentsGitignore(worktreePath);
+  const abs = planFileAbs(worktreePath);
+  mkdirSync(dirname(abs), { recursive: true });
+  const body = content.trimEnd() + (content.endsWith("\n") ? "" : "\n");
+  writeFileSync(abs, body, "utf8");
+  return PLAN_FILE_REL;
+}
+
+export {
+  PLAN_FILE_REL,
+  PLAN_FILE_NAME,
+  LEGACY_PLAN_FILE_REL,
+  isPresentPlanToolName,
+  extractPresentedPlan,
+  resolvePlanMarkdown,
+  planFileAbs,
+  readPlanFile,
+  writePlanFile
+};