santree 0.5.6 → 0.6.0

package/dist/lib/dashboard/data.js

@@ -1,6 +1,8 @@
-import { listWorktrees, extractTicketId, getBaseBranch, readAllMetadata, readSessionState, isSessionAlive, clearSessionState, getGitStatusAsync, getCommitsAheadAsync, getDiffShortstatAsync, } from "../git.js";
-import { getPRInfoAsync, getPRChecksAsync, getPRReviewsAsync, getPRConversationCommentsAsync, getPRViewAsync, getReviewRequestedPRsAsync, getRepoNameAsync, } from "../github.js";
-import { getIssueTracker } from "../trackers/index.js";
+import { listWorktrees, extractTicketId, getBaseBranch, getDefaultBranch, readAllMetadata, readSessionState, isSessionAlive, clearSessionState, clearSessionId, getGitStatusAsync, getCommitsAheadAsync, getCommitsBehindAsync, getDiffShortstatAsync, } from "../git.js";
+import { runAsync } from "../exec.js";
+import { readMainAgentTodos, findClaudeSessionCwd } from "../claude-todos.js";
+import { getPRInfoAsync, getPRChecksAsync, getPRReviewsAsync, getPRConversationCommentsAsync, getPRViewAsync, getReviewRequestedPRsAsync, getRepoNameAsync, getGitHubUserNameAsync, } from "../github.js";
+import { getIssueTracker, getCandidateTrackers } from "../trackers/index.js";
 export async function loadDashboardData(repoRoot) {
     // Fetch issues and worktrees in parallel
     const tracker = getIssueTracker(repoRoot);
@@ -50,16 +52,39 @@ export async function loadDashboardData(repoRoot) {
                 sessState = null;
             }
             const ss = sessState?.state ?? null;
+            const storedId = metadata[issue.identifier]?.session_id ?? null;
+            // Verify the session is still resumable. Claude Code clears old
+            // transcript files (or `/clear` mints a new ID), leaving our stored
+            // session_id pointing at nothing. Without this check the dashboard
+            // offers `[↵] Resume`, which fails with "No conversation found with
+            // session ID". `findClaudeSessionCwd` also returns the real cwd
+            // where the session lives — needed because project conventions
+            // (direnv, shell init) sometimes cd into a subdir before Claude
+            // was launched, so resume must run from there. On a miss we drop
+            // the stored ID from metadata so the next refresh skips this work.
+            const sessionCwd = storedId ? findClaudeSessionCwd(wt.path, storedId) : null;
+            let sessionId = storedId;
+            if (storedId && !sessionCwd) {
+                clearSessionId(repoRoot, issue.identifier);
+                sessionId = null;
+            }
+            // Hide stale todos when the session has exited or its file is gone —
+            // the on-disk todos file outlives the process and showing them
+            // would lie about state.
+            const claudeTodos = sessionId && ss !== "exited" ? readMainAgentTodos(sessionId) : null;
             worktreeInfo = {
                 path: wt.path,
                 branch: wt.branch,
                 dirty: Boolean(gitStatusOutput),
                 commitsAhead: ahead,
-                sessionId: metadata[issue.identifier]?.session_id ?? null,
+                commitsBehind: null,
+                sessionId,
+                sessionCwd,
                 gitStatus: gitStatusOutput,
                 sessionState: ss === "exited" ? null : ss,
                 sessionMessage: sessState?.message ?? null,
                 diffStats: shortstat,
+                claudeTodos,
             };
             prInfo = pr;
             if (pr) {
@@ -112,6 +137,14 @@ export async function loadDashboardData(repoRoot) {
             sessState = null;
         }
         const ss = sessState?.state ?? null;
+        const storedId = metadata[tid]?.session_id ?? null;
+        const sessionCwd = storedId ? findClaudeSessionCwd(wt.path, storedId) : null;
+        let sessionId = storedId;
+        if (storedId && !sessionCwd) {
+            clearSessionId(repoRoot, tid);
+            sessionId = null;
+        }
+        const claudeTodos = sessionId && ss !== "exited" ? readMainAgentTodos(sessionId) : null;
         return {
             issue: {
                 identifier: tid,
@@ -130,11 +163,14 @@ export async function loadDashboardData(repoRoot) {
                 branch: wt.branch,
                 dirty: Boolean(gitStatusOutput),
                 commitsAhead: ahead,
-                sessionId: metadata[tid]?.session_id ?? null,
+                commitsBehind: null,
+                sessionId,
+                sessionCwd,
                 gitStatus: gitStatusOutput,
                 sessionState: ss === "exited" ? null : ss,
                 sessionMessage: sessState?.message ?? null,
                 diffStats: shortstat,
+                claudeTodos,
             },
             pr,
             checks: checksInfo,
@@ -235,8 +271,75 @@ export async function loadDashboardData(repoRoot) {
         return result;
     }
     const flatIssues = groups.flatMap((g) => g.statusGroups.flatMap((sg) => sg.issues.flatMap(flattenWithChildren)));
+    // Synthesize a "Main repo" row at the very top so users can commit /
+    // view diffs / inspect drift on whatever branch their main checkout
+    // happens to be on. The row uses the same WorktreeInfo shape but with
+    // state.type === "main" so the renderer can differentiate.
+    const mainEntry = await buildMainEntry(repoRoot);
+    if (mainEntry) {
+        groups.unshift({
+            name: "Main repo",
+            id: null,
+            statusGroups: [{ name: "Main", type: "main", issues: [mainEntry] }],
+        });
+        flatIssues.unshift(mainEntry);
+    }
     return { groups, flatIssues };
 }
+/** Build the synthetic dashboard row for the main repo checkout — the
+ * non-worktree clone that the user typically commits master/main from.
+ * Returns null only if we can't read the current branch (e.g. detached
+ * HEAD with no commits). */
+async function buildMainEntry(repoRoot) {
+    const branch = (await runAsync(`git -C "${repoRoot}" rev-parse --abbrev-ref HEAD`))?.trim();
+    if (!branch || branch === "HEAD")
+        return null;
+    // `commitsAhead` here is "how many local commits haven't been pushed",
+    // `commitsBehind` is "how many upstream commits I haven't pulled" —
+    // both relative to origin/<currentBranch>. If there's no upstream,
+    // both come back as 0; the renderer treats that as "in sync".
+    const [gitStatusOutput, ahead, behind, shortstat] = await Promise.all([
+        getGitStatusAsync(repoRoot),
+        getCommitsAheadAsync(repoRoot, `origin/${branch}`),
+        getCommitsBehindAsync(repoRoot, branch),
+        // Diff vs origin so the +/- numbers reflect unpushed work.
+        getDiffShortstatAsync(repoRoot, `origin/${branch}`),
+    ]);
+    const defaultBranch = getDefaultBranch();
+    const isDefault = branch === defaultBranch;
+    const title = isDefault ? `${branch} (default)` : branch;
+    return {
+        issue: {
+            identifier: branch.toUpperCase(),
+            title,
+            description: null,
+            url: "",
+            priority: 0,
+            priorityLabel: "None",
+            state: { name: "Main", type: "main" },
+            labels: [],
+            projectId: null,
+            projectName: "Main repo",
+        },
+        worktree: {
+            path: repoRoot,
+            branch,
+            dirty: Boolean(gitStatusOutput),
+            commitsAhead: ahead,
+            commitsBehind: behind,
+            sessionId: null,
+            sessionCwd: null,
+            gitStatus: gitStatusOutput,
+            sessionState: null,
+            sessionMessage: null,
+            diffStats: shortstat,
+            claudeTodos: null,
+        },
+        pr: null,
+        checks: null,
+        reviews: null,
+    };
+}
 export async function loadReviewsData(repoRoot) {
     const repo = await getRepoNameAsync();
     if (!repo)
@@ -251,13 +354,22 @@ export async function loadReviewsData(repoRoot) {
             branchToWt.set(wt.branch, { path: wt.path, branch: wt.branch });
     }
     const metadata = readAllMetadata(repoRoot);
+    // Trackers worth trying when extracting a ticket ID from a PR's branch.
+    // We hit the reviews tab to look at OTHER people's PRs — their branches
+    // may follow a different convention than the current repo's active
+    // tracker (e.g. a GitHub-tracker repo reviewing PRs from a Linear team
+    // where branches encode `TEAM-1234`). The active tracker comes first;
+    // `getCandidateTrackers` appends Linear as a fallback when GitHub is
+    // active and Linear creds exist.
+    const candidates = getCandidateTrackers(repoRoot);
     // Enrich each PR in parallel
     const enriched = await Promise.all(prs.map(async (pr) => {
-        const [view, checks, reviews, comments] = await Promise.all([
+        const [view, checks, reviews, comments, authorName] = await Promise.all([
             getPRViewAsync(pr.number),
             getPRChecksAsync(String(pr.number)),
             getPRReviewsAsync(String(pr.number)),
             getPRConversationCommentsAsync(String(pr.number)),
+            getGitHubUserNameAsync(pr.author.login),
         ]);
         // Check if we have a local worktree for this PR's branch
         let worktreeInfo = null;
@@ -278,19 +390,56 @@ export async function loadReviewsData(repoRoot) {
                     sessState = null;
                 }
                 const ss = sessState?.state ?? null;
+                const storedId = ticketId ? (metadata[ticketId]?.session_id ?? null) : null;
+                const sessionCwd = storedId ? findClaudeSessionCwd(wt.path, storedId) : null;
+                let sessionId = storedId;
+                if (storedId && ticketId && !sessionCwd) {
+                    clearSessionId(repoRoot, ticketId);
+                    sessionId = null;
+                }
+                const claudeTodos = sessionId && ss !== "exited" ? readMainAgentTodos(sessionId) : null;
                 worktreeInfo = {
                     path: wt.path,
                     branch: wt.branch,
                     dirty: Boolean(gitStatusOutput),
                     commitsAhead: ahead,
-                    sessionId: ticketId ? (metadata[ticketId]?.session_id ?? null) : null,
+                    commitsBehind: null,
+                    sessionId,
+                    sessionCwd,
                     gitStatus: gitStatusOutput,
                     sessionState: ss === "exited" ? null : ss,
                     sessionMessage: sessState?.message ?? null,
                     diffStats: shortstat,
+                    claudeTodos,
                 };
             }
         }
+        // Resolve linked tracker issue. Try inputs in priority order:
+        // branch first (most likely to encode the canonical ID), then PR
+        // title (e.g. `[MSG-4084] …`). Each candidate tracker's
+        // `extractIdFromBranch` regex is unanchored and works on any
+        // text, not just branches — that's the (slightly misnamed but
+        // load-bearing) reuse this fallback depends on.
+        // Stops at the first hit. Failures stay silent.
+        let ticket = null;
+        const idInputs = [branch, pr.title].filter((s) => Boolean(s));
+        outer: for (const cand of candidates) {
+            for (const text of idInputs) {
+                const ticketId = cand.extractIdFromBranch(text);
+                if (!ticketId)
+                    continue;
+                try {
+                    const res = await cand.getIssue(ticketId, repoRoot);
+                    if (res.ok) {
+                        ticket = res.value;
+                        break outer;
+                    }
+                }
+                catch {
+                    // swallow — try the next candidate / input
+                }
+            }
+        }
         return {
             pr,
             body: view?.body ?? null,
@@ -303,6 +452,8 @@ export async function loadReviewsData(repoRoot) {
             reviews,
             comments,
             worktree: worktreeInfo,
+            ticket,
+            authorName,
         };
     }));
     return { flatReviews: enriched };

package/dist/lib/dashboard/types.d.ts

@@ -1,12 +1,26 @@
 import type { PRInfo, PRCheck, PRReview, PRConversationComment, SearchPR } from "../github.js";
-import type { AssignedIssue } from "../trackers/types.js";
-export type { AssignedIssue } from "../trackers/types.js";
+import type { ClaudeTodo } from "../claude-todos.js";
+import type { AssignedIssue, Issue } from "../trackers/types.js";
+export type { AssignedIssue, Issue } from "../trackers/types.js";
 export interface WorktreeInfo {
     path: string;
     branch: string;
     dirty: boolean;
     commitsAhead: number;
+    /** How many commits HEAD is behind origin/<branch>. Populated for the
+     * synthetic main-repo row so users can see how stale their local
+     * checkout is. Null on ticket worktrees (the answer is uninteresting
+     * because the ticket branch usually has no upstream yet). */
+    commitsBehind: number | null;
     sessionId: string | null;
+    /** Real-path cwd from which `claude --resume <sessionId>` actually
+     * succeeds. Usually equals `path`, but project conventions (direnv,
+     * shell init) sometimes cd into a subdirectory like `backend/canary`
+     * before Claude is launched, in which case the session is resumable
+     * only from there. The dashboard prepends `cd <sessionCwd>` to the
+     * resume command so it survives tmux send-keys cwd drift. Null when
+     * sessionId is null or the underlying file can't be located. */
+    sessionCwd: string | null;
     gitStatus: string;
     sessionState: "waiting" | "idle" | "active" | null;
     sessionMessage: string | null;
@@ -15,6 +29,7 @@ export interface WorktreeInfo {
         insertions: number;
         deletions: number;
     } | null;
+    claudeTodos: ClaudeTodo[] | null;
 }
 export interface DashboardIssue {
     issue: AssignedIssue;
@@ -48,9 +63,17 @@ export interface EnrichedReviewPR {
     reviews: PRReview[] | null;
     comments: PRConversationComment[] | null;
     worktree: WorktreeInfo | null;
+    /** Linked tracker issue, parsed from the PR's branch name first, then
+     * falling back to the PR title. Null when no recognizable ID is found,
+     * the tracker fails, or the issue is gone. The detail panel renders a
+     * Ticket section only when this is set. */
+    ticket: Issue | null;
+    /** GitHub display name for the PR author (`name` field on /users/:login).
+     * Null when the user hasn't set one or the lookup failed. */
+    authorName: string | null;
 }
 export type DashboardTab = "issues" | "reviews";
-export type ActionOverlay = "mode-select" | "context-input" | "base-select" | "confirm-delete" | "confirm-setup" | "commit" | "pr-create" | "diff" | null;
+export type ActionOverlay = "mode-select" | "context-input" | "base-select" | "confirm-delete" | "confirm-setup" | "commit" | "pr-create" | "diff" | "help" | null;
 export type DiffFileStatus = "M" | "A" | "D" | "R" | "C" | "U" | "?";
 export interface DiffFile {
     path: string;
@@ -60,7 +83,7 @@ export interface DiffFile {
     workingStatus?: string;
     isUntracked?: boolean;
 }
-export type CommitPhase = "idle" | "confirm-stage" | "awaiting-message" | "committing" | "pushing" | "done" | "error";
+export type CommitPhase = "idle" | "confirm-stage" | "choose-mode" | "filling" | "awaiting-message" | "committing" | "pushing" | "done" | "error";
 export type PrCreatePhase = "idle" | "choose-mode" | "pushing" | "filling" | "review" | "confirm" | "creating" | "done" | "error";
 export interface DashboardState {
     activeTab: DashboardTab;
@@ -107,6 +130,12 @@ export interface DashboardState {
     diffWorktreePath: string | null;
     diffBaseBranch: string | null;
     diffMergeBase: string | null;
+    /** When set, the diff is sourced from `gh pr diff <n>` rather than local
+     * `git diff` — used by the reviews tab when a PR has no local worktree.
+     * The file list and per-file content are parsed from the unified diff
+     * once and held in `diffPRContentByPath`. */
+    diffPRNumber: number | null;
+    diffPRContentByPath: Record<string, string>;
     diffFiles: DiffFile[];
     diffFileIndex: number;
     diffFileScrollOffset: number;
@@ -167,7 +196,9 @@ export type DashboardAction = {
     type: "DELETE_DONE";
 } | {
     type: "COMMIT_START";
-    ticketId: string;
+    /** Null when committing on a non-ticket branch (e.g. the main
+     * repo row) — the commit message gets no `[ID]` prefix. */
+    ticketId: string | null;
     worktreePath: string;
     branch: string;
     gitStatus: string;
@@ -255,6 +286,15 @@ export type DashboardAction = {
     ticketId: string;
     worktreePath: string;
     baseBranch: string;
+} | {
+    type: "DIFF_OPEN_PR";
+    label: string;
+    prNumber: number;
+    baseBranch: string;
+} | {
+    type: "DIFF_PR_LOADED";
+    files: DiffFile[];
+    contentByPath: Record<string, string>;
 } | {
     type: "DIFF_FILES_LOADED";
     files: DiffFile[];

package/dist/lib/dashboard/types.js

@@ -44,6 +44,8 @@ export const initialState = {
     diffWorktreePath: null,
     diffBaseBranch: null,
     diffMergeBase: null,
+    diffPRNumber: null,
+    diffPRContentByPath: {},
     diffFiles: [],
     diffFileIndex: 0,
     diffFileScrollOffset: 0,
@@ -288,6 +290,8 @@ export function reducer(state, action) {
                 diffWorktreePath: action.worktreePath,
                 diffBaseBranch: action.baseBranch,
                 diffMergeBase: null,
+                diffPRNumber: null,
+                diffPRContentByPath: {},
                 diffFiles: [],
                 diffFileIndex: 0,
                 diffFileScrollOffset: 0,
@@ -299,6 +303,40 @@ export function reducer(state, action) {
                 diffPendingDiscard: null,
                 diffRefreshTick: 0,
             };
+        case "DIFF_OPEN_PR":
+            return {
+                ...state,
+                overlay: "diff",
+                diffTicketId: action.label,
+                diffWorktreePath: null,
+                diffBaseBranch: action.baseBranch,
+                diffMergeBase: null,
+                diffPRNumber: action.prNumber,
+                diffPRContentByPath: {},
+                diffFiles: [],
+                diffFileIndex: 0,
+                diffFileScrollOffset: 0,
+                diffContent: null,
+                diffContentScrollOffset: 0,
+                diffLoadingFiles: true,
+                // Hold loadingContent on through the DIFF_PR_LOADED dispatch so the
+                // right pane shows "Loading diff..." until the content effect fires
+                // (avoids a one-frame "(empty diff)" flash between file-list
+                // arrival and content selection).
+                diffLoadingContent: true,
+                diffError: null,
+                diffPendingDiscard: null,
+                diffRefreshTick: 0,
+            };
+        case "DIFF_PR_LOADED":
+            return {
+                ...state,
+                diffFiles: action.files,
+                diffPRContentByPath: action.contentByPath,
+                diffFileIndex: 0,
+                diffLoadingFiles: false,
+                diffError: null,
+            };
         case "DIFF_FILES_LOADED": {
             // Preserve the user's selection across reloads (after stage/unstage/
             // discard) by matching the previously-selected file's path. Falls back
@@ -396,6 +434,8 @@ export function reducer(state, action) {
                 diffWorktreePath: null,
                 diffBaseBranch: null,
                 diffMergeBase: null,
+                diffPRNumber: null,
+                diffPRContentByPath: {},
                 diffFiles: [],
                 diffFileIndex: 0,
                 diffFileScrollOffset: 0,

package/dist/lib/diff-parse.d.ts

@@ -0,0 +1,25 @@
+import type { DiffFile } from "./dashboard/types.js";
+export interface ParsedDiff {
+    files: DiffFile[];
+    contentByPath: Record<string, string>;
+}
+/**
+ * Parse a unified diff blob (e.g. `gh pr diff <n>`) into per-file records
+ * suitable for DiffOverlay. Each section starts at `^diff --git a/PATH b/PATH`
+ * and runs until the next such header (or EOF).
+ *
+ * Status is derived from the per-file metadata git emits:
+ *   - `new file mode …`            → "A"
+ *   - `deleted file mode …`        → "D"
+ *   - `rename from / rename to`    → "R"
+ *   - everything else              → "M"
+ *
+ * For renames, `path` is the new path and `oldPath` is preserved on the file
+ * record so DiffOverlay's tree shows the destination location. Deletes use the
+ * old path (the new side doesn't exist).
+ *
+ * Robustness: an unparseable header (a `diff --git` line that doesn't match the
+ * expected `a/PATH b/PATH` shape) is skipped rather than fatal — we'd rather
+ * lose one entry than crash the overlay.
+ */
+export declare function parseUnifiedDiff(text: string): ParsedDiff;

package/dist/lib/diff-parse.js

@@ -0,0 +1,60 @@
+/**
+ * Parse a unified diff blob (e.g. `gh pr diff <n>`) into per-file records
+ * suitable for DiffOverlay. Each section starts at `^diff --git a/PATH b/PATH`
+ * and runs until the next such header (or EOF).
+ *
+ * Status is derived from the per-file metadata git emits:
+ *   - `new file mode …`            → "A"
+ *   - `deleted file mode …`        → "D"
+ *   - `rename from / rename to`    → "R"
+ *   - everything else              → "M"
+ *
+ * For renames, `path` is the new path and `oldPath` is preserved on the file
+ * record so DiffOverlay's tree shows the destination location. Deletes use the
+ * old path (the new side doesn't exist).
+ *
+ * Robustness: an unparseable header (a `diff --git` line that doesn't match the
+ * expected `a/PATH b/PATH` shape) is skipped rather than fatal — we'd rather
+ * lose one entry than crash the overlay.
+ */
+export function parseUnifiedDiff(text) {
+    const files = [];
+    const contentByPath = {};
+    if (!text)
+        return { files, contentByPath };
+    const lines = text.split("\n");
+    let i = 0;
+    while (i < lines.length) {
+        while (i < lines.length && !lines[i].startsWith("diff --git "))
+            i++;
+        if (i >= lines.length)
+            break;
+        const sectionStart = i;
+        const headerMatch = lines[i].match(/^diff --git a\/(.+?) b\/(.+)$/);
+        if (!headerMatch) {
+            i++;
+            continue;
+        }
+        const oldPath = headerMatch[1];
+        const newPath = headerMatch[2];
+        i++;
+        let status = "M";
+        while (i < lines.length && !lines[i].startsWith("diff --git ")) {
+            const line = lines[i];
+            if (line.startsWith("new file mode"))
+                status = "A";
+            else if (line.startsWith("deleted file mode"))
+                status = "D";
+            else if (line.startsWith("rename from") || line.startsWith("rename to"))
+                status = "R";
+            i++;
+        }
+        const path = status === "D" ? oldPath : newPath;
+        const file = { status, path };
+        if (status === "R" && oldPath !== newPath)
+            file.oldPath = oldPath;
+        files.push(file);
+        contentByPath[path] = lines.slice(sectionStart, i).join("\n");
+    }
+    return { files, contentByPath };
+}

package/dist/lib/git.d.ts

@@ -104,6 +104,16 @@ export declare function getSessionId(repoRoot: string, ticketId: string): string
  * Store a session ID for a given ticket in .santree/metadata.json.
  */
 export declare function setSessionId(repoRoot: string, ticketId: string, sessionId: string): void;
+/**
+ * Remove the stored session_id for a ticket. Used when the underlying Claude
+ * session file is no longer on disk (Claude Code clears old transcripts) — the
+ * stored ID is unresumable, so we drop it to avoid showing a "Resume" action
+ * that will fail with "No conversation found with session ID".
+ *
+ * Leaves any other metadata fields (e.g. `base_branch`) intact and only drops
+ * the entry entirely when nothing remains.
+ */
+export declare function clearSessionId(repoRoot: string, ticketId: string): void;
 /**
  * Get the base branch for a given branch name.
  * Looks up metadata first, falls back to the default branch.
@@ -151,6 +161,12 @@ export declare function getGitStatusAsync(cwd: string): Promise<string>;
  * Returns empty string on failure.
  */
 export declare function getStagedDiffStat(): string;
+/**
+ * Get the full staged diff body for AI commit-message generation.
+ * Runs: `git diff --cached`. Uses a 5MB max buffer; very large diffs
+ * are truncated by the caller before sending to Claude.
+ */
+export declare function getStagedDiffContent(cwd?: string): string;
 /**
  * Count how many commits the current branch is behind origin/baseBranch.
  * Runs: `git rev-list --count HEAD..origin/<baseBranch>`
@@ -168,6 +184,12 @@ export declare function getCommitsAhead(baseBranch: string): number;
  * Returns 0 on failure.
  */
 export declare function getCommitsAheadAsync(cwd: string, baseBranch: string): Promise<number>;
+/**
+ * Count how many commits HEAD is BEHIND origin/<baseBranch> in the given
+ * cwd. Used by the dashboard's main-repo row to show how stale the local
+ * checkout is. Returns 0 on failure (e.g. no upstream tracking branch).
+ */
+export declare function getCommitsBehindAsync(cwd: string, baseBranch: string): Promise<number>;
 /**
  * Read the SANTREE_DIFF_TOOL env var, returning the configured diff pager
  * command (e.g. "delta", "diff-so-fancy") or null if unset/invalid.

package/dist/lib/git.js

@@ -293,6 +293,30 @@ export function setSessionId(repoRoot, ticketId, sessionId) {
     all[ticketId] = { ...all[ticketId], session_id: sessionId };
     writeAllMetadata(repoRoot, all);
 }
+/**
+ * Remove the stored session_id for a ticket. Used when the underlying Claude
+ * session file is no longer on disk (Claude Code clears old transcripts) — the
+ * stored ID is unresumable, so we drop it to avoid showing a "Resume" action
+ * that will fail with "No conversation found with session ID".
+ *
+ * Leaves any other metadata fields (e.g. `base_branch`) intact and only drops
+ * the entry entirely when nothing remains.
+ */
+export function clearSessionId(repoRoot, ticketId) {
+    const all = readAllMetadata(repoRoot);
+    const entry = all[ticketId];
+    if (!entry || entry.session_id === undefined)
+        return;
+    const rest = { ...entry };
+    delete rest.session_id;
+    if (Object.keys(rest).length === 0) {
+        delete all[ticketId];
+    }
+    else {
+        all[ticketId] = rest;
+    }
+    writeAllMetadata(repoRoot, all);
+}
 /**
  * Get the base branch for a given branch name.
  * Looks up metadata first, falls back to the default branch.
@@ -383,6 +407,14 @@ export async function getGitStatusAsync(cwd) {
 export function getStagedDiffStat() {
     return run("git diff --cached --stat") ?? "";
 }
+/**
+ * Get the full staged diff body for AI commit-message generation.
+ * Runs: `git diff --cached`. Uses a 5MB max buffer; very large diffs
+ * are truncated by the caller before sending to Claude.
+ */
+export function getStagedDiffContent(cwd) {
+    return run("git diff --cached", { cwd, maxBuffer: 5 * 1024 * 1024 }) ?? "";
+}
 /**
  * Count how many commits the current branch is behind origin/baseBranch.
  * Runs: `git rev-list --count HEAD..origin/<baseBranch>`
@@ -409,6 +441,15 @@ export async function getCommitsAheadAsync(cwd, baseBranch) {
     const output = await runAsync(`git -C "${cwd}" rev-list --count ${baseBranch}..HEAD`);
     return output ? parseInt(output, 10) || 0 : 0;
 }
+/**
+ * Count how many commits HEAD is BEHIND origin/<baseBranch> in the given
+ * cwd. Used by the dashboard's main-repo row to show how stale the local
+ * checkout is. Returns 0 on failure (e.g. no upstream tracking branch).
+ */
+export async function getCommitsBehindAsync(cwd, baseBranch) {
+    const output = await runAsync(`git -C "${cwd}" rev-list --count HEAD..origin/${baseBranch}`);
+    return output ? parseInt(output, 10) || 0 : 0;
+}
 /**
  * Read the SANTREE_DIFF_TOOL env var, returning the configured diff pager
  * command (e.g. "delta", "diff-so-fancy") or null if unset/invalid.

package/dist/lib/github.d.ts

@@ -133,6 +133,12 @@ export declare function getPRViewAsync(prNumber: number): Promise<PRViewDetail |
  * Returns null if not in a GitHub repo or gh is unavailable.
  */
 export declare function getRepoNameAsync(): Promise<string | null>;
+/**
+ * Look up a GitHub user's display name (`name` field). Returns null if the
+ * user has no display name set, the API call fails, or `gh` isn't available.
+ * Caches per process — repeated calls for the same login are free.
+ */
+export declare function getGitHubUserNameAsync(login: string): Promise<string | null>;
 /**
  * Fetch open PRs where the current user's review is still pending (async).
  * Uses the GitHub search API with `user-review-requested:@me` which excludes

package/dist/lib/github.js

@@ -256,6 +256,35 @@ export async function getRepoNameAsync() {
         return null;
     }
 }
+/**
+ * Per-process cache of `login → display name`. GitHub display names rarely
+ * change inside a dashboard session, and `gh api users/<login>` is a network
+ * call we don't want to repeat per refresh. Resolves to `null` for users
+ * with no display name set (we'll fall back to login at the call site).
+ */
+const githubUserNameCache = new Map();
+/**
+ * Look up a GitHub user's display name (`name` field). Returns null if the
+ * user has no display name set, the API call fails, or `gh` isn't available.
+ * Caches per process — repeated calls for the same login are free.
+ */
+export function getGitHubUserNameAsync(login) {
+    const cached = githubUserNameCache.get(login);
+    if (cached)
+        return cached;
+    const promise = (async () => {
+        try {
+            const { stdout } = await execAsync(`gh api users/${login} --jq .name`);
+            const name = stdout.trim();
+            return name && name !== "null" ? name : null;
+        }
+        catch {
+            return null;
+        }
+    })();
+    githubUserNameCache.set(login, promise);
+    return promise;
+}
 /**
  * Fetch open PRs where the current user's review is still pending (async).
  * Uses the GitHub search API with `user-review-requested:@me` which excludes

package/dist/lib/open-url.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Open a URL in the platform's default browser.
+ *   macOS → `open <url>`
+ *   else  → `xdg-open <url>`
+ *
+ * Returns true on apparent success, false on failure. Callers decide how to
+ * surface failures (e.g. a dashboard action message). Uses execSync with
+ * `stdio: "ignore"` — fast, no output leak into the dashboard's alt screen.
+ */
+export declare function openUrl(url: string): boolean;