santree 0.7.4 → 0.7.6

package/dist/lib/dashboard/IssueList.js

@@ -45,11 +45,30 @@ function workIndicator(wt) {
 function ciIndicator(checks) {
     if (!checks || checks.length === 0)
         return { glyph: "·", color: "gray" };
+    // `gh` buckets: pass | fail | pending | skipping | cancel. Only `fail` blocks
+    // (red) and only `pending` is genuinely still running (yellow). `skipping` /
+    // `cancel` don't run under the current conditions and don't block — GitHub
+    // reports them as "skipped" and still shows "all checks passed", so they must
+    // not turn the glyph yellow.
     if (checks.some((c) => c.bucket === "fail"))
         return { glyph: "✗", color: "red" };
-    if (checks.every((c) => c.bucket === "pass"))
-        return { glyph: "✓", color: "green" };
-    return { glyph: "●", color: "yellow" };
+    if (checks.some((c) => c.bucket === "pending"))
+        return { glyph: "●", color: "yellow" };
+    return { glyph: "✓", color: "green" };
+}
+/**
+ * While a fix loop is actively running (or stalled), it owns the CI column — a ⟳
+ * conveys "being auto-fixed" better than the underlying check state. Stopped loops
+ * fall back to the real CI glyph (CI green ≈ stopped clean, CI red ≈ stopped stuck).
+ */
+function fixLoopOverride(loop) {
+    if (!loop)
+        return null;
+    if (loop.phase === "running")
+        return { glyph: "⟳", color: "cyan" };
+    if (loop.phase === "stalled")
+        return { glyph: "⟳", color: "yellow" };
+    return null;
 }
 export function buildIssueListRows(groups, flatIssues) {
     const rows = [];
@@ -109,7 +128,7 @@ function readinessGlyph(di) {
             return { glyph: "·", color: "gray" };
     }
 }
-export default function IssueList({ groups, flatIssues, selectedIndex, scrollOffset, height, width, selectionBg = "#1e3a5f", variant = "default", deletingIds, }) {
+export default function IssueList({ groups, flatIssues, selectedIndex, scrollOffset, height, width, selectionBg = "#1e3a5f", variant = "default", deletingIds, fixLoops, }) {
     const isTriage = variant === "triage";
     const isIssues = variant === "issues";
     const rightFixed = isTriage ? SLA_COL_WIDTH : isIssues ? READY_COL_WIDTH : RIGHT_FIXED;
@@ -146,7 +165,7 @@ export default function IssueList({ groups, flatIssues, selectedIndex, scrollOff
                 const prio = snoozed ? { glyph: " ", color: "gray" } : priorityMarker(di.issue.priority);
                 const isDeleting = deletingIds?.has(di.issue.identifier) ?? false;
                 const work = isDeleting ? { glyph: "⌫", color: "yellow" } : workIndicator(di.worktree);
-                const ci = ciIndicator(di.checks);
+                const ci = fixLoopOverride(fixLoops?.[di.issue.identifier]) ?? ciIndicator(di.checks);
                 const nestPrefix = depth > 0 ? "  ".repeat(depth - 1) + "└ " : "";
                 const adjustedTitleWidth = Math.max(titleMaxWidth - nestPrefix.length, 5);
                 const title = di.issue.title.length > adjustedTitleWidth

package/dist/lib/dashboard/MultilineTextArea.js

@@ -162,7 +162,7 @@ export function MultilineTextArea({ value, onChange, onSubmit, onCancel, placeho
             onSubmit();
             return;
         }
-        // Ctrl+O: escalate to $SANTREE_EDITOR / $VISUAL / $EDITOR. On save+close
+        // Ctrl+O: escalate to the configured editor / $VISUAL / $EDITOR. On save+close
         // the buffer is replaced and control returns to the textbox so the
         // user can keep editing or submit with Ctrl+D.
         if (key.ctrl && input === "o") {

package/dist/lib/dashboard/Overlays.js

@@ -68,6 +68,8 @@ const LEGEND = [
             { glyph: "✗", color: "red", meaning: "CI column: a check is failing" },
             { glyph: "●", color: "yellow", meaning: "CI column: checks pending / running" },
             { glyph: "·", color: "gray", meaning: "CI column: no PR or no checks" },
+            { glyph: "⟳", color: "cyan", meaning: "CI column: auto-fix loop running (every 5 min)" },
+            { glyph: "⟳", color: "yellow", meaning: "CI column: fix loop stalled (no recent activity)" },
             { glyph: "◷", color: "red", meaning: "SLA column (Triage): breached / under a day" },
             { glyph: "◷", color: "yellow", meaning: "SLA column (Triage): under two days" },
             { glyph: "●", color: "gray", meaning: "Triage row greyed: snoozed (parked, sunk to bottom)" },
@@ -86,10 +88,7 @@ const LEGEND = [
             { glyph: "✓ clean", color: "green", meaning: "Working tree clean" },
             { glyph: "↑ N", color: "cyan", meaning: "N commits ahead of base" },
             { glyph: "↓ N behind", color: "yellow", meaning: "Main repo: N commits to pull from origin" },
-            { glyph: "◆", color: "red", meaning: "Session needs input (permission prompt)" },
-            { glyph: "◆", color: "green", meaning: "Session active (Claude is working)" },
-            { glyph: "◆", color: "yellow", meaning: "Session idle (waiting for prompt)" },
-            { glyph: "◇", color: "cyan", meaning: "Session id stored, no live signal" },
+            { glyph: "◇", color: "cyan", meaning: "Resumable Claude session id stored" },
             { glyph: "◇", color: "gray", meaning: "No session" },
         ],
     },

package/dist/lib/dashboard/ReviewDetailPanel.js

@@ -223,16 +223,20 @@ export default function ReviewDetailPanel({ item, scrollOffset, height, width })
     }
     // ── Checks ────────────────────────────────────────────────────────
     if (checks && checks.length > 0) {
+        // `skipping`/`cancel` checks don't run under the current conditions and
+        // don't block — GitHub counts them as "skipped" while still reporting all
+        // checks passed. Treat them as a non-blocking aside, never as pending.
         const passing = checks.filter((c) => c.bucket === "pass");
         const failing = checks.filter((c) => c.bucket === "fail");
-        const pending = checks.filter((c) => c.bucket !== "pass" && c.bucket !== "fail");
+        const pending = checks.filter((c) => c.bucket === "pending");
+        const skipped = checks.filter((c) => c.bucket === "skipping" || c.bucket === "cancel");
         const headerColor = failing.length > 0 ? "red" : pending.length > 0 ? "yellow" : "green";
         lines.push(ruleLine);
         const headerSegs = [
             { text: "✓ ", color: "cyan", bold: true },
             { text: "Checks", bold: true },
             { text: "   " },
-            { text: `${passing.length}/${checks.length} passing`, color: headerColor },
+            { text: `${passing.length} passed`, color: headerColor },
         ];
         if (failing.length > 0) {
             headerSegs.push({ text: "  ·  ", dim: true });
@@ -242,8 +246,13 @@ export default function ReviewDetailPanel({ item, scrollOffset, height, width })
             headerSegs.push({ text: "  ·  ", dim: true });
             headerSegs.push({ text: `${pending.length} pending`, color: "yellow" });
         }
+        if (skipped.length > 0) {
+            headerSegs.push({ text: "  ·  ", dim: true });
+            headerSegs.push({ text: `${skipped.length} skipped`, dim: true });
+        }
         lines.push({ text: "", segments: headerSegs });
         // Order: failing first (most important), then pending, then passing.
+        // Skipped checks aren't listed individually — just summarized above.
         for (const check of failing) {
             const desc = check.description ? ` — ${check.description}` : "";
             lines.push({ text: `  ✗ ${check.name}${desc}`, color: "red" });

package/dist/lib/dashboard/ReviewList.js

@@ -3,11 +3,14 @@ import { Box, Text } from "ink";
 function checksIndicator(checks) {
     if (!checks || checks.length === 0)
         return { text: "-", color: "gray" };
+    // Only `fail` blocks (red) and only `pending` is genuinely running (yellow);
+    // `skipping`/`cancel` don't run under the current conditions and don't block,
+    // so they must not turn the glyph yellow (matches GitHub's "all checks passed").
     if (checks.some((c) => c.bucket === "fail"))
         return { text: "✗", color: "red" };
-    if (checks.every((c) => c.bucket === "pass"))
-        return { text: "✓", color: "green" };
-    return { text: "●", color: "yellow" };
+    if (checks.some((c) => c.bucket === "pending"))
+        return { text: "●", color: "yellow" };
+    return { text: "✓", color: "green" };
 }
 const HEADER_ROWS = 1;
 export function getReviewListRowCount(flatReviews) {

package/dist/lib/dashboard/data.js

@@ -1,5 +1,6 @@
-import { listWorktrees, extractTicketId, getBaseBranch, getDefaultBranch, readAllMetadata, readSessionState, isSessionAlive, clearSessionState, clearSessionId, getGitStatusAsync, getCommitsAheadAsync, getCommitsBehindAsync, getDiffShortstatAsync, } from "../git.js";
+import { listWorktrees, extractTicketId, getBaseBranch, getDefaultBranch, readAllMetadata, clearSessionId, getGitStatusAsync, getCommitsAheadAsync, getCommitsBehindAsync, getDiffShortstatAsync, } from "../git.js";
 import { runAsync } from "../exec.js";
+import { readFixLoopRuntime } from "../fix-loop.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";
@@ -46,13 +47,6 @@ export async function loadDashboardData(repoRoot) {
                 getPRInfoAsync(wt.branch),
                 getDiffShortstatAsync(wt.path, base),
             ]);
-            let sessState = readSessionState(repoRoot, issue.identifier);
-            // Validate against the active multiplexer — if the session has gone, clear stale state
-            if (sessState && !isSessionAlive(issue.identifier)) {
-                clearSessionState(repoRoot, issue.identifier);
-                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
@@ -69,10 +63,7 @@ export async function loadDashboardData(repoRoot) {
                 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;
+            const claudeTodos = sessionId ? readMainAgentTodos(sessionId) : null;
             worktreeInfo = {
                 path: wt.path,
                 branch: wt.branch,
@@ -82,8 +73,6 @@ export async function loadDashboardData(repoRoot) {
                 sessionId,
                 sessionCwd,
                 gitStatus: gitStatusOutput,
-                sessionState: ss === "exited" ? null : ss,
-                sessionMessage: sessState?.message ?? null,
                 diffStats: shortstat,
                 claudeTodos,
             };
@@ -101,6 +90,7 @@ export async function loadDashboardData(repoRoot) {
             pr: prInfo,
             checks: checksInfo,
             reviews: reviewsInfo,
+            fixLoop: readFixLoopRuntime(repoRoot, issue.identifier),
         };
     }));
     // Build orphan DashboardIssue objects for worktrees not matched to any fetched issue
@@ -132,12 +122,6 @@ export async function loadDashboardData(repoRoot) {
             : wt.branch.replace(/^[^/]+\//, ""))
             .replace(/-/g, " ")
             .trim() || tid;
-        let sessState = readSessionState(repoRoot, tid);
-        if (sessState && !isSessionAlive(tid)) {
-            clearSessionState(repoRoot, tid);
-            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;
@@ -145,7 +129,7 @@ export async function loadDashboardData(repoRoot) {
             clearSessionId(repoRoot, tid);
             sessionId = null;
         }
-        const claudeTodos = sessionId && ss !== "exited" ? readMainAgentTodos(sessionId) : null;
+        const claudeTodos = sessionId ? readMainAgentTodos(sessionId) : null;
         return {
             issue: {
                 identifier: tid,
@@ -168,14 +152,13 @@ export async function loadDashboardData(repoRoot) {
                 sessionId,
                 sessionCwd,
                 gitStatus: gitStatusOutput,
-                sessionState: ss === "exited" ? null : ss,
-                sessionMessage: sessState?.message ?? null,
                 diffStats: shortstat,
                 claudeTodos,
             },
             pr,
             checks: checksInfo,
             reviews: reviewsInfo,
+            fixLoop: readFixLoopRuntime(repoRoot, tid),
         };
     }));
     // ── Compute parent-child relationships ──────────────────────────
@@ -367,8 +350,6 @@ async function buildMainEntry(repoRoot) {
             sessionId: null,
             sessionCwd: null,
             gitStatus: gitStatusOutput,
-            sessionState: null,
-            sessionMessage: null,
             diffStats: shortstat,
             claudeTodos: null,
         },
@@ -421,12 +402,6 @@ export async function loadReviewsData(repoRoot) {
                     getCommitsAheadAsync(wt.path, base),
                     getDiffShortstatAsync(wt.path, base),
                 ]);
-                let sessState = ticketId ? readSessionState(repoRoot, ticketId) : null;
-                if (sessState && ticketId && !isSessionAlive(ticketId)) {
-                    clearSessionState(repoRoot, ticketId);
-                    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;
@@ -434,7 +409,7 @@ export async function loadReviewsData(repoRoot) {
                     clearSessionId(repoRoot, ticketId);
                     sessionId = null;
                 }
-                const claudeTodos = sessionId && ss !== "exited" ? readMainAgentTodos(sessionId) : null;
+                const claudeTodos = sessionId ? readMainAgentTodos(sessionId) : null;
                 worktreeInfo = {
                     path: wt.path,
                     branch: wt.branch,
@@ -444,8 +419,6 @@ export async function loadReviewsData(repoRoot) {
                     sessionId,
                     sessionCwd,
                     gitStatus: gitStatusOutput,
-                    sessionState: ss === "exited" ? null : ss,
-                    sessionMessage: sessState?.message ?? null,
                     diffStats: shortstat,
                     claudeTodos,
                 };

package/dist/lib/dashboard/external-editor.d.ts

@@ -7,6 +7,6 @@ export interface EditExternallyResult {
  * Open the user's editor on a temp file seeded with `initial`, then return the
  * saved content. Empty buffer is treated as cancel (matches `git commit`).
  *
- * Editor resolution: SANTREE_EDITOR > VISUAL > EDITOR > "vim".
+ * Editor resolution: santree config editor (or SANTREE_EDITOR) > VISUAL > EDITOR > "vim".
  */
 export declare function editExternally(initial: string, ext?: string): EditExternallyResult;

package/dist/lib/dashboard/external-editor.js

@@ -2,6 +2,7 @@ import { spawnSync } from "child_process";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
+import { getConfiguredEditor } from "../config-store.js";
 // GUI editors that detach by default and need a `--wait` flag to make spawnSync
 // block until the file is closed. Terminal editors (vim, nvim, nano, emacs -nw)
 // already block, so they aren't listed here.
@@ -17,10 +18,10 @@ const GUI_EDITORS_NEEDING_WAIT = new Set([
  * Open the user's editor on a temp file seeded with `initial`, then return the
  * saved content. Empty buffer is treated as cancel (matches `git commit`).
  *
- * Editor resolution: SANTREE_EDITOR > VISUAL > EDITOR > "vim".
+ * Editor resolution: santree config editor (or SANTREE_EDITOR) > VISUAL > EDITOR > "vim".
  */
 export function editExternally(initial, ext = "md") {
-    const editorRaw = process.env["SANTREE_EDITOR"] || process.env["VISUAL"] || process.env["EDITOR"] || "vim";
+    const editorRaw = getConfiguredEditor() || process.env["VISUAL"] || process.env["EDITOR"] || "vim";
     const filePath = path.join(os.tmpdir(), `santree-edit-${Date.now()}.${ext.replace(/^\./, "")}`);
     try {
         fs.writeFileSync(filePath, initial);

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

@@ -1,6 +1,8 @@
 import type { PRInfo, PRCheck, PRReview, PRConversationComment, SearchPR } from "../github.js";
 import type { ClaudeTodo } from "../claude-todos.js";
+import type { FixLoopRuntime } from "../fix-loop.js";
 import type { AssignedIssue, Comment, Issue, TriageSchedule } from "../trackers/types.js";
+export type { FixLoopRuntime } from "../fix-loop.js";
 export type { AssignedIssue, Comment, Issue, TriageSchedule } from "../trackers/types.js";
 export interface WorktreeInfo {
     path: string;
@@ -22,8 +24,6 @@ export interface WorktreeInfo {
      * sessionId is null or the underlying file can't be located. */
     sessionCwd: string | null;
     gitStatus: string;
-    sessionState: "waiting" | "idle" | "active" | null;
-    sessionMessage: string | null;
     diffStats: {
         filesChanged: number;
         insertions: number;
@@ -37,6 +37,8 @@ export interface DashboardIssue {
     pr: PRInfo | null;
     checks: PRCheck[] | null;
     reviews: PRReview[] | null;
+    /** Active/recent auto-fix loop for this ticket (from .santree/fix-loops/). */
+    fixLoop?: FixLoopRuntime | null;
     parentTicketId?: string;
     children?: DashboardIssue[];
 }
@@ -163,6 +165,18 @@ export interface DashboardState {
     creationError: string | null;
     /** In-flight (and just-finished) worktree deletions, keyed by ticket id. */
     deletingTickets: Record<string, DeleteStatus>;
+    /**
+     * Optimistic PRs just created from the dashboard, keyed by ticket id. They
+     * make the "Open PR" action appear immediately (before the next refresh
+     * surfaces the real PR), and are reconciled away by SET_DATA.
+     */
+    pendingPrs: Record<string, PRInfo>;
+    /**
+     * Active/recent auto-fix loops keyed by ticket id, used to render the per-row
+     * ⟳ badge + detail line. Seeded optimistically by FIXLOOP_START and rebuilt
+     * from the `.santree/fix-loops/` markers on every SET_DATA.
+     */
+    fixLoopTickets: Record<string, FixLoopRuntime>;
     commitPhase: CommitPhase;
     commitMessage: string;
     commitError: string | null;
@@ -355,6 +369,9 @@ export type DashboardAction = {
     type: "DELETE_ERROR";
     ticketId: string;
     error: string;
+} | {
+    type: "FIXLOOP_START";
+    ticketId: string;
 } | {
     type: "COMMIT_START";
     /** Null when committing on a non-ticket branch (e.g. the main

package/dist/lib/dashboard/types.js

@@ -48,6 +48,8 @@ export const initialState = {
     creationLogs: "",
     creationError: null,
     deletingTickets: {},
+    pendingPrs: {},
+    fixLoopTickets: {},
     commitPhase: "idle",
     commitMessage: "",
     commitError: null,
@@ -117,12 +119,36 @@ export function reducer(state, action) {
             // keep their row, so their entries survive and stay visible.
             const presentTreeIds = new Set(action.flatTrees.map((d) => d.issue.identifier));
             const deletingTickets = Object.fromEntries(Object.entries(state.deletingTickets).filter(([id]) => presentTreeIds.has(id)));
+            // Reconcile optimistic PRs: keep the placeholder until the refresh
+            // actually surfaces the PR (GitHub may not have indexed it yet), then
+            // drop it once real PR data — or the worktree itself — is gone.
+            let reconciledTrees = action.flatTrees;
+            const pendingPrs = {};
+            for (const [id, optimistic] of Object.entries(state.pendingPrs)) {
+                const idx = reconciledTrees.findIndex((d) => d.issue.identifier === id);
+                if (idx < 0)
+                    continue; // worktree gone → drop
+                if (reconciledTrees[idx].pr)
+                    continue; // real PR arrived → reconciled
+                reconciledTrees = reconciledTrees.map((d, i) => (i === idx ? { ...d, pr: optimistic } : d));
+                pendingPrs[id] = optimistic; // still pending → keep showing it
+            }
+            // Rebuild the fix-loop badge map authoritatively from the freshly-read
+            // markers (drops loops whose marker was cleared); optimistic FIXLOOP_START
+            // entries are superseded here once the marker file is picked up.
+            const fixLoopTickets = {};
+            for (const d of reconciledTrees) {
+                if (d.fixLoop)
+                    fixLoopTickets[d.issue.identifier] = d.fixLoop;
+            }
             return {
                 ...state,
                 groups: action.groups,
                 flatIssues: action.flatIssues,
                 treeGroups: action.treeGroups,
-                flatTrees: action.flatTrees,
+                flatTrees: reconciledTrees,
+                pendingPrs,
+                fixLoopTickets,
                 triageGroups: action.triageGroups,
                 flatTriage: action.flatTriage,
                 deletingTickets,
@@ -344,6 +370,23 @@ export function reducer(state, action) {
                 },
             };
         }
+        case "FIXLOOP_START": {
+            // Optimistic running badge until SET_DATA reads the marker the launcher wrote.
+            const now = new Date().toISOString();
+            return {
+                ...state,
+                fixLoopTickets: {
+                    ...state.fixLoopTickets,
+                    [action.ticketId]: {
+                        phase: "running",
+                        status: "running",
+                        startedAt: now,
+                        at: now,
+                        ageMs: 0,
+                    },
+                },
+            };
+        }
         case "COMMIT_START":
             return {
                 ...state,
@@ -408,14 +451,37 @@ export function reducer(state, action) {
             return { ...state, prCreateDraft: !state.prCreateDraft };
         case "PR_CREATE_EDIT":
             return { ...state, prCreatePhase: "review" };
-        case "PR_CREATE_DONE":
+        case "PR_CREATE_DONE": {
+            // Optimistically attach the new PR to its tree row so the "Open PR"
+            // action appears immediately, instead of waiting for the next refresh
+            // to surface it via `gh pr view`.
+            const ticketId = state.prCreateTicketId;
+            let flatTrees = state.flatTrees;
+            let pendingPrs = state.pendingPrs;
+            // Only attach the optimistic PR if we can parse a real number from the
+            // returned URL — a `"?"` placeholder would break later `gh pr view <n>`
+            // calls. If it doesn't match, the next refresh surfaces the real PR.
+            const prNumber = action.url.match(/\/pull\/(\d+)/)?.[1];
+            if (ticketId && prNumber) {
+                const optimistic = {
+                    number: prNumber,
+                    state: "OPEN",
+                    isDraft: state.prCreateDraft,
+                    url: action.url,
+                };
+                flatTrees = state.flatTrees.map((d) => d.issue.identifier === ticketId && !d.pr ? { ...d, pr: optimistic } : d);
+                pendingPrs = { ...state.pendingPrs, [ticketId]: optimistic };
+            }
             return {
                 ...state,
                 prCreatePhase: "done",
                 prCreateUrl: action.url,
                 prCreateBody: null,
                 prCreateTitle: null,
+                flatTrees,
+                pendingPrs,
             };
+        }
         case "PR_CREATE_CANCEL":
             return {
                 ...state,

package/dist/lib/exec.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Run a command with array args (NO shell) and return `{ stdout, stderr }`.
+ * Rejects on non-zero exit with an error carrying `.stdout`/`.stderr`/`.message`,
+ * matching promisified `exec` semantics. Use this — not a `exec(\`… ${x}\`)`
+ * template — whenever any argument is user-supplied, to avoid shell injection.
+ */
+export declare function execFileAsync(file: string, args: string[], options?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<{
+    stdout: string;
+    stderr: string;
+}>;
 /**
  * Run a shell command and return trimmed stdout, or null on failure.
  */

package/dist/lib/exec.js

@@ -1,6 +1,16 @@
-import { execSync, exec, spawn } from "child_process";
+import { execSync, exec, execFile, spawn } from "child_process";
 import { promisify } from "util";
 const execPromise = promisify(exec);
+const execFilePromise = promisify(execFile);
+/**
+ * Run a command with array args (NO shell) and return `{ stdout, stderr }`.
+ * Rejects on non-zero exit with an error carrying `.stdout`/`.stderr`/`.message`,
+ * matching promisified `exec` semantics. Use this — not a `exec(\`… ${x}\`)`
+ * template — whenever any argument is user-supplied, to avoid shell injection.
+ */
+export async function execFileAsync(file, args, options) {
+    return execFilePromise(file, args, { encoding: "utf-8", ...options });
+}
 /**
  * Run a shell command and return trimmed stdout, or null on failure.
  */

package/dist/lib/fix-loop.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Marker store for the auto-fix `/loop` (see `santree pr fix --loop`).
+ *
+ * Each running loop writes `.santree/fix-loops/<ticketId>.json` and heartbeats it
+ * every iteration. The dashboard reads these markers to render a per-ticket fix-loop
+ * badge — kept as files (not in dashboard memory) because the loop runs in a separate
+ * process/window and must survive dashboard restarts. Staleness is timestamp-based:
+ * the loop has a known cadence, so a "running" marker that hasn't heartbeat in a
+ * while is treated as stalled.
+ *
+ * Standalone module (only `fs`/`path`/`metadata`) so both commands and the dashboard
+ * data layer can import it without pulling in git/tracker cycles.
+ */
+/** Lifecycle status written by the loop. `stopped:*` are terminal. */
+export type FixLoopStatus = "running" | "merging" | "fixing" | "waiting-ci" | "stopped:clean" | "stopped:stuck";
+export interface FixLoopMarker {
+    status: FixLoopStatus;
+    /** Loop interval in minutes (used for staleness math). */
+    intervalMin: number;
+    /** ISO timestamp the loop first launched. */
+    startedAt: string;
+    /** ISO timestamp of the last heartbeat / status change. */
+    at: string;
+}
+/** Display phase derived from a marker + the current time. */
+export type FixLoopPhase = "running" | "stalled" | "stopped-clean" | "stopped-stuck";
+export interface FixLoopRuntime {
+    phase: FixLoopPhase;
+    status: FixLoopStatus;
+    startedAt: string;
+    at: string;
+    ageMs: number;
+}
+/** Create/overwrite a marker as a freshly-started running loop. */
+export declare function startFixLoop(repoRoot: string, ticketId: string, intervalMin: number): void;
+/**
+ * Update an existing marker's status and heartbeat. If no marker exists yet (e.g. a
+ * signal arrives before the launcher wrote one), a minimal one is created so the
+ * dashboard still reflects the loop.
+ */
+export declare function signalFixLoop(repoRoot: string, ticketId: string, status: FixLoopStatus): void;
+export declare function readFixLoopMarker(repoRoot: string, ticketId: string): FixLoopMarker | null;
+export declare function clearFixLoop(repoRoot: string, ticketId: string): void;
+/** Derive the dashboard-facing phase from a marker. Returns null if no marker. */
+export declare function readFixLoopRuntime(repoRoot: string, ticketId: string, now?: number): FixLoopRuntime | null;

package/dist/lib/fix-loop.js

@@ -0,0 +1,83 @@
+import * as fs from "fs";
+import * as path from "path";
+import { getSantreeDir } from "./metadata.js";
+function getFixLoopsDir(repoRoot) {
+    return path.join(getSantreeDir(repoRoot), "fix-loops");
+}
+function markerPath(repoRoot, ticketId) {
+    return path.join(getFixLoopsDir(repoRoot), `${ticketId}.json`);
+}
+/** Create/overwrite a marker as a freshly-started running loop. */
+export function startFixLoop(repoRoot, ticketId, intervalMin) {
+    const now = new Date().toISOString();
+    writeMarker(repoRoot, ticketId, {
+        status: "running",
+        intervalMin,
+        startedAt: now,
+        at: now,
+    });
+}
+/**
+ * Update an existing marker's status and heartbeat. If no marker exists yet (e.g. a
+ * signal arrives before the launcher wrote one), a minimal one is created so the
+ * dashboard still reflects the loop.
+ */
+export function signalFixLoop(repoRoot, ticketId, status) {
+    const prev = readFixLoopMarker(repoRoot, ticketId);
+    const now = new Date().toISOString();
+    writeMarker(repoRoot, ticketId, {
+        status,
+        intervalMin: prev?.intervalMin ?? 5,
+        startedAt: prev?.startedAt ?? now,
+        at: now,
+    });
+}
+function writeMarker(repoRoot, ticketId, marker) {
+    const dir = getFixLoopsDir(repoRoot);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(markerPath(repoRoot, ticketId), JSON.stringify(marker, null, 2) + "\n");
+}
+export function readFixLoopMarker(repoRoot, ticketId) {
+    const filePath = markerPath(repoRoot, ticketId);
+    if (!fs.existsSync(filePath))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function clearFixLoop(repoRoot, ticketId) {
+    try {
+        fs.unlinkSync(markerPath(repoRoot, ticketId));
+    }
+    catch {
+        // Ignore if missing.
+    }
+}
+/**
+ * A heartbeating loop that hasn't checked in for ~2.5 intervals is treated as
+ * stalled (its window was probably closed). Floor of 10 min so a slow first
+ * iteration isn't mistaken for a dead loop.
+ */
+function staleThresholdMs(intervalMin) {
+    return Math.max(intervalMin * 2.5, 10) * 60_000;
+}
+/** Derive the dashboard-facing phase from a marker. Returns null if no marker. */
+export function readFixLoopRuntime(repoRoot, ticketId, now = Date.now()) {
+    const marker = readFixLoopMarker(repoRoot, ticketId);
+    if (!marker)
+        return null;
+    const ageMs = now - new Date(marker.at).getTime();
+    let phase;
+    if (marker.status === "stopped:clean")
+        phase = "stopped-clean";
+    else if (marker.status === "stopped:stuck")
+        phase = "stopped-stuck";
+    else if (ageMs > staleThresholdMs(marker.intervalMin))
+        phase = "stalled";
+    else
+        phase = "running";
+    return { phase, status: marker.status, startedAt: marker.startedAt, at: marker.at, ageMs };
+}