santree 0.2.6 → 0.2.8

package/README.md

@@ -121,10 +121,16 @@ With the `stw` alias: `stw create`, `stw list`, `stw switch`, `stw work`, `stw c
 
 ### Helpers (`santree helpers`)
 
-| Command                      | Description                       |
-| ---------------------------- | --------------------------------- |
-| `santree helpers shell-init` | Output shell integration script   |
-| `santree helpers statusline` | Custom statusline for Claude Code |
+| Command                                        | Description                                      |
+| ---------------------------------------------- | ------------------------------------------------ |
+| `santree helpers shell-init`                   | Output shell integration script                  |
+| `santree helpers statusline`                   | Custom statusline for Claude Code                |
+| `santree helpers session-signal notification`  | Signal waiting state (Notification hook)         |
+| `santree helpers session-signal stop`          | Signal idle state (Stop hook)                    |
+| `santree helpers session-signal prompt`        | Signal active state (UserPromptSubmit hook)      |
+| `santree helpers session-signal end`           | Signal exited state (SessionEnd hook)            |
+| `santree helpers session-signal install`       | Auto-install session-signal hooks in Claude Code |
+| `santree helpers session-signal install --dry` | Print the hooks JSON without writing             |
 
 ### Top-level
 
@@ -252,6 +258,65 @@ Enable [Remote Control](https://code.claude.com/docs/en/remote-control) to conti
 
 Enable it for all sessions by running `/config` inside Claude Code and setting **Enable Remote Control for all sessions** to `true`. This writes `remoteControlAtStartup: true` to `~/.claude.json`. Run `santree doctor` to verify.
 
+### Session State Signaling (Optional)
+
+Surfaces the current Claude Code session state in the dashboard, statusline, and tmux window names. Shows whether a session is actively working, waiting for permission approval, idle, or exited.
+
+**States:**
+| State | Meaning |
+|-------|---------|
+| `active` | User submitted a prompt, Claude is working |
+| `waiting` | Claude needs permission approval |
+| `idle` | Claude finished and is waiting for next prompt |
+| `exited` | Session ended |
+
+**Install:**
+
+```bash
+santree helpers session-signal install
+```
+
+This adds hooks for `Notification`, `Stop`, `UserPromptSubmit`, and `SessionEnd` to `~/.claude/settings.json`. Existing hooks are preserved.
+
+To preview the JSON without writing: `santree helpers session-signal install --dry`
+
+Verify with `santree doctor` — look for the "Session Signal Hooks" row under Claude Code.
+
+### Session Hooks (Optional)
+
+Run custom scripts when Claude's session state changes. Create executable scripts in `.santree/hooks/`:
+
+```
+.santree/hooks/
+  on-waiting.sh    # Runs when session needs permission approval
+  on-active.sh     # Runs when user submits a new prompt
+  on-idle.sh       # Runs when session finishes and waits for next prompt
+  on-exited.sh     # Runs when session ends
+```
+
+Each script receives these environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `SANTREE_TICKET_ID` | e.g. `TEAM-123` |
+| `SANTREE_SESSION_STATE` | `waiting`, `active`, `idle`, or `exited` |
+| `SANTREE_SESSION_ID` | The Claude session ID |
+| `SANTREE_WORKTREE_PATH` | Absolute path to the worktree |
+| `SANTREE_REPO_ROOT` | Absolute path to the main repo |
+| `SANTREE_MESSAGE` | Notification message (only for `waiting`) |
+
+Scripts are optional — only executed if they exist and are executable. They run fire-and-forget with a 5-second timeout.
+
+**Example** — log when Claude is waiting for approval:
+
+```bash
+#!/bin/bash
+# .santree/hooks/on-waiting.sh
+echo "$(date): $SANTREE_TICKET_ID waiting — $SANTREE_MESSAGE" >> /tmp/santree-hooks.log
+```
+
+Make it executable: `chmod +x .santree/hooks/on-waiting.sh`
+
 ---
 
 ## Command Options

package/dist/commands/doctor.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { Box, Text } from "ink";
 import Spinner from "ink-spinner";
 import { useEffect, useState } from "react";
@@ -56,7 +56,8 @@ async function checkTool(name, description, required, versionCommand, hint) {
     };
 }
 /**
- * Checks GitHub CLI auth status using JSON output.
+ * Checks GitHub CLI auth status.
+ * Uses `gh api user` which works across all gh versions.
  */
 async function checkGhAuth() {
     const path = await getPath("gh");
@@ -70,22 +71,8 @@ async function checkGhAuth() {
         };
     }
     const version = await tryExec("gh --version | head -1");
-    const authJson = await tryExec("gh auth status --json hosts 2>/dev/null");
-    let authStatus;
-    if (authJson) {
-        try {
-            const auth = JSON.parse(authJson);
-            const githubHosts = auth.hosts?.["github.com"];
-            const activeAccount = githubHosts?.find((h) => h.active);
-            if (activeAccount?.login) {
-                authStatus = `Authenticated as ${activeAccount.login}`;
-            }
-        }
-        catch {
-            // JSON parse failed, auth might not be configured
-        }
-    }
-    if (!authStatus) {
+    const login = await tryExec("gh api user --jq .login 2>/dev/null");
+    if (!login) {
         return {
             name: "gh",
             description: "GitHub CLI for PR operations",
@@ -103,7 +90,7 @@ async function checkGhAuth() {
         installed: true,
         version: version || "unknown",
         path,
-        authStatus,
+        authStatus: `Authenticated as ${login}`,
     };
 }
 /**
@@ -207,6 +194,79 @@ async function checkStatusline() {
         hint,
     };
 }
+/**
+ * Checks if session-signal hooks are configured in ~/.claude/settings.json.
+ * Looks for hooks on Notification, Stop, UserPromptSubmit, and SessionEnd
+ * that run "santree helpers session-signal".
+ */
+function checkSessionSignalHooks() {
+    const home = process.env.HOME || "";
+    const claudeSettingsPath = path.join(home, ".claude", "settings.json");
+    const requiredEvents = ["Notification", "Stop", "UserPromptSubmit", "SessionEnd"];
+    const missingHooks = [];
+    try {
+        if (fs.existsSync(claudeSettingsPath)) {
+            const content = fs.readFileSync(claudeSettingsPath, "utf-8");
+            const settings = JSON.parse(content);
+            const hooks = settings.hooks || {};
+            for (const event of requiredEvents) {
+                const eventHooks = hooks[event];
+                if (!Array.isArray(eventHooks)) {
+                    missingHooks.push(event);
+                    continue;
+                }
+                // Check if any hook entry has a nested hook command containing session-signal
+                const found = eventHooks.some((entry) => {
+                    const innerHooks = entry.hooks || [];
+                    return innerHooks.some((h) => typeof h.command === "string" && h.command.includes("session-signal"));
+                });
+                if (!found)
+                    missingHooks.push(event);
+            }
+        }
+        else {
+            missingHooks.push(...requiredEvents);
+        }
+    }
+    catch {
+        missingHooks.push(...requiredEvents);
+    }
+    // Check hook script files in .santree/hooks/
+    const hookScripts = [];
+    const mainRepoRoot = findMainRepoRoot();
+    let hooksDir = null;
+    if (mainRepoRoot) {
+        hooksDir = path.join(mainRepoRoot, ".santree", "hooks");
+        const scriptNames = ["on-waiting.sh", "on-active.sh", "on-idle.sh", "on-exited.sh"];
+        for (const name of scriptNames) {
+            const scriptPath = path.join(hooksDir, name);
+            const exists = fs.existsSync(scriptPath);
+            let executable = false;
+            if (exists) {
+                try {
+                    fs.accessSync(scriptPath, fs.constants.X_OK);
+                    executable = true;
+                }
+                catch {
+                    // not executable
+                }
+            }
+            if (exists) {
+                hookScripts.push({ name, exists, executable });
+            }
+        }
+    }
+    if (missingHooks.length === 0) {
+        return { configured: true, missingHooks: [], hookScripts, hooksDir };
+    }
+    return {
+        configured: false,
+        missingHooks,
+        hookScripts,
+        hooksDir,
+        hint: `Missing: ${missingHooks.join(", ")}. Run: santree helpers session-signal install`,
+    };
+}
 /**
  * Checks if a path is gitignored (via .gitignore or .git/info/exclude).
  */
@@ -301,6 +361,15 @@ function StatuslineRow({ status }) {
 function RemoteControlRow({ status }) {
     return (_jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [_jsxs(Box, { children: [_jsx(StatusIcon, { ok: status.enabled, required: false }), _jsx(Text, { children: " " }), _jsx(Text, { bold: true, children: "Remote Control" }), _jsx(Text, { dimColor: true, children: " - Continue sessions from any device" }), _jsx(Text, { dimColor: true, children: " (optional)" })] }), _jsxs(Box, { marginLeft: 2, flexDirection: "column", children: [_jsxs(Text, { dimColor: true, children: ["Enabled: ", status.enabled ? "yes" : "no"] }), status.hint && _jsxs(Text, { color: "yellow", children: ["\u21B3 ", status.hint] })] })] }));
 }
+function SessionSignalRow({ status }) {
+    const allScriptNames = ["on-waiting.sh", "on-active.sh", "on-idle.sh", "on-exited.sh"];
+    const existingNames = new Set(status.hookScripts.map((s) => s.name));
+    const missingScripts = allScriptNames.filter((n) => !existingNames.has(n));
+    const nonExecutable = status.hookScripts.filter((s) => !s.executable);
+    return (_jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [_jsxs(Box, { children: [_jsx(StatusIcon, { ok: status.configured && nonExecutable.length === 0, required: false }), _jsx(Text, { children: " " }), _jsx(Text, { bold: true, children: "Session Signal Hooks" }), _jsx(Text, { dimColor: true, children: " - Surface session state in dashboard/tmux" }), _jsx(Text, { dimColor: true, children: " (optional)" })] }), _jsxs(Box, { marginLeft: 2, flexDirection: "column", children: [status.configured ? (_jsx(Text, { dimColor: true, children: "All hooks configured" })) : (_jsxs(_Fragment, { children: [_jsxs(Text, { dimColor: true, children: ["Missing: ", status.missingHooks.join(", ")] }), status.hint && _jsxs(Text, { color: "yellow", children: ["\u21B3 ", status.hint] })] })), status.hooksDir && (_jsxs(Text, { dimColor: true, children: ["Hook scripts:", " ", status.hookScripts.length > 0
+                                ? status.hookScripts.map((s) => s.name).join(", ")
+                                : "none"] })), status.hooksDir && missingScripts.length > 0 && (_jsxs(Text, { color: "yellow", children: ["\u21B3 Create in ", status.hooksDir, ": ", missingScripts.join(", ")] })), nonExecutable.map((s) => (_jsxs(Text, { color: "yellow", children: ["\u21B3 ", s.name, " is not executable. Run: chmod +x .santree/hooks/", s.name] }, s.name)))] })] }));
+}
 function SantreeSetupRow({ status }) {
     const isOk = status.santreeFolderExists &&
         status.initShExists &&
@@ -322,6 +391,7 @@ export default function Doctor() {
     const [shellStatus, setShellStatus] = useState(null);
     const [remoteControl, setRemoteControl] = useState(null);
     const [statusline, setStatusline] = useState(null);
+    const [sessionSignal, setSessionSignal] = useState(null);
     const [santreeSetup, setSantreeSetup] = useState(null);
     const [loading, setLoading] = useState(true);
     useEffect(() => {
@@ -359,6 +429,7 @@ export default function Doctor() {
             setShellStatus(checkShellIntegration());
             setRemoteControl(checkRemoteControl());
             setStatusline(statuslineResult);
+            setSessionSignal(checkSessionSignalHooks());
             setSantreeSetup(checkSantreeSetup());
             setLoading(false);
         }
@@ -371,5 +442,5 @@ export default function Doctor() {
     const optionalMissing = tools.filter((t) => !t.required && !t.installed);
     const linearOk = linear?.authenticated && linear?.tokenValid && linear?.repoLinked;
     const allRequired = requiredMissing.length === 0 && linearOk && shellStatus?.configured;
-    return (_jsxs(Box, { flexDirection: "column", padding: 1, children: [_jsxs(Box, { marginBottom: 1, children: [_jsx(Text, { bold: true, color: "cyan", children: "Santree Doctor" }), _jsxs(Text, { dimColor: true, children: [" v", version] })] }), _jsx(Box, { marginBottom: 1, flexDirection: "column", children: _jsx(Text, { bold: true, underline: true, children: "CLI Tools" }) }), tools.map((tool) => (_jsx(ToolRow, { tool: tool }, tool.name))), _jsx(Box, { marginBottom: 1, marginTop: 1, flexDirection: "column", children: _jsx(Text, { bold: true, underline: true, children: "Integrations" }) }), linear && _jsx(LinearRow, { linear: linear }), shellStatus && _jsx(ShellRow, { configured: shellStatus.configured, shell: shellStatus.shell }), santreeSetup && _jsx(SantreeSetupRow, { status: santreeSetup }), _jsx(Box, { marginBottom: 1, marginTop: 1, flexDirection: "column", children: _jsx(Text, { bold: true, underline: true, children: "Claude Code" }) }), remoteControl && _jsx(RemoteControlRow, { status: remoteControl }), statusline && _jsx(StatuslineRow, { status: statusline }), _jsx(Box, { marginTop: 1, borderStyle: "single", borderColor: allRequired ? "green" : "yellow", paddingX: 2, children: allRequired ? (_jsx(Text, { color: "green", children: "All requirements satisfied! Santree is ready to use." })) : (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { color: "yellow", children: [requiredMissing.length + (linearOk ? 0 : 1) + (shellStatus?.configured ? 0 : 1), " ", "required item(s) need attention"] }), optionalMissing.length > 0 && (_jsxs(Text, { dimColor: true, children: [optionalMissing.length, " optional item(s) not installed"] }))] })) })] }));
+    return (_jsxs(Box, { flexDirection: "column", padding: 1, children: [_jsxs(Box, { marginBottom: 1, children: [_jsx(Text, { bold: true, color: "cyan", children: "Santree Doctor" }), _jsxs(Text, { dimColor: true, children: [" v", version] })] }), _jsx(Box, { marginBottom: 1, flexDirection: "column", children: _jsx(Text, { bold: true, underline: true, children: "CLI Tools" }) }), tools.map((tool) => (_jsx(ToolRow, { tool: tool }, tool.name))), _jsx(Box, { marginBottom: 1, marginTop: 1, flexDirection: "column", children: _jsx(Text, { bold: true, underline: true, children: "Integrations" }) }), linear && _jsx(LinearRow, { linear: linear }), shellStatus && _jsx(ShellRow, { configured: shellStatus.configured, shell: shellStatus.shell }), santreeSetup && _jsx(SantreeSetupRow, { status: santreeSetup }), _jsx(Box, { marginBottom: 1, marginTop: 1, flexDirection: "column", children: _jsx(Text, { bold: true, underline: true, children: "Claude Code" }) }), remoteControl && _jsx(RemoteControlRow, { status: remoteControl }), statusline && _jsx(StatuslineRow, { status: statusline }), sessionSignal && _jsx(SessionSignalRow, { status: sessionSignal }), _jsx(Box, { marginTop: 1, borderStyle: "single", borderColor: allRequired ? "green" : "yellow", paddingX: 2, children: allRequired ? (_jsx(Text, { color: "green", children: "All requirements satisfied! Santree is ready to use." })) : (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { color: "yellow", children: [requiredMissing.length + (linearOk ? 0 : 1) + (shellStatus?.configured ? 0 : 1), " ", "required item(s) need attention"] }), optionalMissing.length > 0 && (_jsxs(Text, { dimColor: true, children: [optionalMissing.length, " optional item(s) not installed"] }))] })) })] }));
 }

package/dist/commands/helpers/session-signal/end.d.ts

@@ -0,0 +1,2 @@
+export declare const description = "Signal exited state (SessionEnd hook)";
+export default function End(): null;

package/dist/commands/helpers/session-signal/end.js

@@ -0,0 +1,13 @@
+import { useEffect, useRef } from "react";
+import { signalState } from "../../../lib/session-signal.js";
+export const description = "Signal exited state (SessionEnd hook)";
+export default function End() {
+    const hasRun = useRef(false);
+    useEffect(() => {
+        if (hasRun.current)
+            return;
+        hasRun.current = true;
+        signalState("exited");
+    }, []);
+    return null;
+}

package/dist/commands/helpers/session-signal/index.d.ts

@@ -0,0 +1 @@
+export declare const description = "Signal session state for Claude Code hooks";

package/dist/commands/helpers/session-signal/index.js

@@ -0,0 +1 @@
+export const description = "Signal session state for Claude Code hooks";

package/dist/commands/helpers/session-signal/install.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+export declare const description = "Install session-signal hooks into Claude Code settings";
+export declare const options: z.ZodObject<{
+    dry: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export default function Install({ options: opts }: {
+    options: z.infer<typeof options>;
+}): null;

package/dist/commands/helpers/session-signal/install.js

@@ -0,0 +1,24 @@
+import { useEffect, useRef } from "react";
+import { z } from "zod";
+import { getHooksJson, installHooks } from "../../../lib/session-signal.js";
+export const description = "Install session-signal hooks into Claude Code settings";
+export const options = z.object({
+    dry: z.boolean().optional().describe("Print the hooks JSON without writing"),
+});
+export default function Install({ options: opts }) {
+    const hasRun = useRef(false);
+    useEffect(() => {
+        if (hasRun.current)
+            return;
+        hasRun.current = true;
+        if (opts?.dry) {
+            const snippet = { hooks: getHooksJson() };
+            process.stdout.write(JSON.stringify(snippet, null, 2) + "\n");
+            process.exit(0);
+        }
+        const settingsPath = installHooks();
+        process.stdout.write(`Session-signal hooks installed in ${settingsPath}\n`);
+        process.exit(0);
+    }, []);
+    return null;
+}

package/dist/commands/helpers/session-signal/notification.d.ts

@@ -0,0 +1,2 @@
+export declare const description = "Signal waiting state (Notification hook)";
+export default function Notification(): null;

package/dist/commands/helpers/session-signal/notification.js

@@ -0,0 +1,13 @@
+import { useEffect, useRef } from "react";
+import { signalState } from "../../../lib/session-signal.js";
+export const description = "Signal waiting state (Notification hook)";
+export default function Notification() {
+    const hasRun = useRef(false);
+    useEffect(() => {
+        if (hasRun.current)
+            return;
+        hasRun.current = true;
+        signalState("waiting");
+    }, []);
+    return null;
+}

package/dist/commands/helpers/session-signal/prompt.d.ts

@@ -0,0 +1,2 @@
+export declare const description = "Signal active state (UserPromptSubmit hook)";
+export default function Prompt(): null;

package/dist/commands/helpers/session-signal/prompt.js

@@ -0,0 +1,13 @@
+import { useEffect, useRef } from "react";
+import { signalState } from "../../../lib/session-signal.js";
+export const description = "Signal active state (UserPromptSubmit hook)";
+export default function Prompt() {
+    const hasRun = useRef(false);
+    useEffect(() => {
+        if (hasRun.current)
+            return;
+        hasRun.current = true;
+        signalState("active");
+    }, []);
+    return null;
+}

package/dist/commands/helpers/session-signal/stop.d.ts

@@ -0,0 +1,2 @@
+export declare const description = "Signal idle state (Stop hook)";
+export default function Stop(): null;

package/dist/commands/helpers/session-signal/stop.js

@@ -0,0 +1,13 @@
+import { useEffect, useRef } from "react";
+import { signalState } from "../../../lib/session-signal.js";
+export const description = "Signal idle state (Stop hook)";
+export default function Stop() {
+    const hasRun = useRef(false);
+    useEffect(() => {
+        if (hasRun.current)
+            return;
+        hasRun.current = true;
+        signalState("idle");
+    }, []);
+    return null;
+}

package/dist/commands/helpers/statusline.js

@@ -83,6 +83,28 @@ function isWorktree(cwd) {
 function isSantreeWorktree(cwd) {
     return cwd.includes("/.santree/worktrees/");
 }
+// Read session state from per-ticket state file
+function readSessionStateFile(cwd) {
+    const marker = "/.santree/worktrees/";
+    const idx = cwd.indexOf(marker);
+    if (idx === -1)
+        return null;
+    const repoRoot = cwd.slice(0, idx);
+    const rest = cwd.slice(idx + marker.length);
+    const ticketId = rest.split("/")[0];
+    if (!ticketId)
+        return null;
+    const filePath = path.join(repoRoot, ".santree", "session-states", `${ticketId}.json`);
+    try {
+        const data = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+        if (data.state === "exited")
+            return null;
+        return data.state;
+    }
+    catch {
+        return null;
+    }
+}
 // Extract ticket ID from branch name (e.g., feature/TEAM-123-desc -> TEAM-123)
 function extractTicketId(branch) {
     const match = branch.match(/([a-zA-Z]+)-(\d+)/);
@@ -141,15 +163,23 @@ function buildSantreeStatusline(cwd, model, usedPercentage) {
     // Git changes
     const changes = getGitChanges(cwd);
     parts.push(formatChanges(changes));
+    // Session state
+    const sessState = readSessionStateFile(cwd);
+    if (sessState === "waiting") {
+        parts.push(`${c.red}WAITING${c.reset}`);
+    }
+    else if (sessState === "idle") {
+        parts.push(`${c.yellow}idle${c.reset}`);
+    }
     // Model
     if (model) {
         parts.push(`${c.blue}${model}${c.reset}`);
     }
-    // Usable context % (accounting for 80% auto-compact threshold)
+    // Context usage %
     if (usedPercentage !== null) {
-        const usable = Math.round(usedPercentage * 1.25);
-        const color = usable >= 80 ? c.red : usable >= 60 ? c.yellow : c.green;
-        parts.push(`${color}${usable}%${c.reset}`);
+        const used = Math.round(usedPercentage);
+        const color = used >= 80 ? c.red : used >= 60 ? c.yellow : c.green;
+        parts.push(`${color}${used}%${c.reset}`);
     }
     return parts.join(" | ");
 }
@@ -170,11 +200,11 @@ function buildGitStatusline(cwd, model, usedPercentage) {
     if (model) {
         parts.push(`${c.blue}${model}${c.reset}`);
     }
-    // Usable context %
+    // Context usage %
     if (usedPercentage !== null) {
-        const usable = Math.round(usedPercentage * 1.25);
-        const color = usable >= 80 ? c.red : usable >= 60 ? c.yellow : c.green;
-        parts.push(`${color}${usable}%${c.reset}`);
+        const used = Math.round(usedPercentage);
+        const color = used >= 80 ? c.red : used >= 60 ? c.yellow : c.green;
+        parts.push(`${color}${used}%${c.reset}`);
     }
     return parts.join(" | ");
 }
@@ -188,11 +218,11 @@ function buildPlainStatusline(cwd, model, usedPercentage) {
     if (model) {
         parts.push(`${c.blue}${model}${c.reset}`);
     }
-    // Usable context %
+    // Context usage %
     if (usedPercentage !== null) {
-        const usable = Math.round(usedPercentage * 1.25);
-        const color = usable >= 80 ? c.red : usable >= 60 ? c.yellow : c.green;
-        parts.push(`${color}${usable}%${c.reset}`);
+        const used = Math.round(usedPercentage);
+        const color = used >= 80 ? c.red : used >= 60 ? c.yellow : c.green;
+        parts.push(`${color}${used}%${c.reset}`);
     }
     return parts.join(" | ");
 }

package/dist/lib/dashboard/DetailPanel.js

@@ -163,6 +163,18 @@ export default function DetailPanel({ issue, scrollOffset, height, width, creati
         else {
             lines.push({ text: "  session: none", color: "red" });
         }
+        if (worktree.sessionState === "waiting") {
+            const msg = worktree.sessionMessage
+                ? `NEEDS INPUT: ${worktree.sessionMessage}`
+                : "NEEDS INPUT";
+            lines.push({ text: `  ${msg}`, color: "red" });
+        }
+        else if (worktree.sessionState === "idle") {
+            lines.push({ text: "  session idle (waiting for prompt)", color: "yellow" });
+        }
+        else if (worktree.sessionState === "active") {
+            lines.push({ text: "  session active (working)", color: "green" });
+        }
     }
     else {
         lines.push({ text: "  –", dim: true });

package/dist/lib/dashboard/IssueList.js

@@ -63,6 +63,13 @@ function sessionIndicator(wt, isCreating, isDeleting) {
         return { text: " creating", color: "yellow" };
     if (!wt)
         return { text: " -", color: "gray" };
+    // Session state takes priority over session ID
+    if (wt.sessionState === "waiting")
+        return { text: " waiting!", color: "red" };
+    if (wt.sessionState === "active")
+        return { text: " active", color: "green" };
+    if (wt.sessionState === "idle")
+        return { text: " idle", color: "yellow" };
     if (wt.sessionId)
         return { text: " " + wt.sessionId.slice(0, 8), color: "cyan" };
     return { text: " none", color: "red" };

package/dist/lib/dashboard/data.js

@@ -1,4 +1,4 @@
-import { listWorktrees, extractTicketId, getBaseBranch, readAllMetadata, getGitStatusAsync, getCommitsAheadAsync, } from "../git.js";
+import { listWorktrees, extractTicketId, getBaseBranch, readAllMetadata, readSessionState, isSessionAliveInTmux, clearSessionState, getGitStatusAsync, getCommitsAheadAsync, } from "../git.js";
 import { getPRInfoAsync, getPRChecksAsync, getPRReviewsAsync, } from "../github.js";
 import { fetchAssignedIssues } from "../linear.js";
 export async function loadDashboardData(repoRoot) {
@@ -38,6 +38,13 @@ export async function loadDashboardData(repoRoot) {
                 getCommitsAheadAsync(wt.path, base),
                 getPRInfoAsync(wt.branch),
             ]);
+            let sessState = readSessionState(repoRoot, issue.identifier);
+            // Validate against tmux — if no claude process is running, clear stale state
+            if (sessState && !isSessionAliveInTmux(issue.identifier)) {
+                clearSessionState(repoRoot, issue.identifier);
+                sessState = null;
+            }
+            const ss = sessState?.state ?? null;
             worktreeInfo = {
                 path: wt.path,
                 branch: wt.branch,
@@ -45,6 +52,8 @@ export async function loadDashboardData(repoRoot) {
                 commitsAhead: ahead,
                 sessionId: metadata[issue.identifier]?.session_id ?? null,
                 gitStatus: gitStatusOutput,
+                sessionState: ss === "exited" ? null : ss,
+                sessionMessage: sessState?.message ?? null,
             };
             prInfo = pr;
             if (pr) {
@@ -86,6 +95,12 @@ export async function loadDashboardData(repoRoot) {
             .replace(/^[A-Z]+-\d+-?/, "") // strip ticket ID
             .replace(/-/g, " ")
             .trim() || tid;
+        let sessState = readSessionState(repoRoot, tid);
+        if (sessState && !isSessionAliveInTmux(tid)) {
+            clearSessionState(repoRoot, tid);
+            sessState = null;
+        }
+        const ss = sessState?.state ?? null;
         return {
             issue: {
                 identifier: tid,
@@ -106,6 +121,8 @@ export async function loadDashboardData(repoRoot) {
                 commitsAhead: ahead,
                 sessionId: metadata[tid]?.session_id ?? null,
                 gitStatus: gitStatusOutput,
+                sessionState: ss === "exited" ? null : ss,
+                sessionMessage: sessState?.message ?? null,
             },
             pr,
             checks: checksInfo,

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

@@ -21,6 +21,8 @@ export interface WorktreeInfo {
     commitsAhead: number;
     sessionId: string | null;
     gitStatus: string;
+    sessionState: "waiting" | "idle" | "active" | null;
+    sessionMessage: string | null;
 }
 export interface DashboardIssue {
     issue: LinearAssignedIssue;

package/dist/lib/git.d.ts

@@ -1,3 +1,9 @@
+export interface SessionState {
+    state: "waiting" | "idle" | "active" | "exited";
+    message: string | null;
+    session_id: string;
+    at: string;
+}
 export interface Worktree {
     path: string;
     branch: string;
@@ -245,3 +251,18 @@ export declare function getDiffStat(baseBranch: string): string | null;
  * Returns null if there are no changes or on failure.
  */
 export declare function getDiffContent(baseBranch: string): string | null;
+/**
+ * Read the session state file for a given ticket.
+ * Returns null if missing or "exited".
+ */
+export declare function readSessionState(repoRoot: string, ticketId: string): SessionState | null;
+/**
+ * Check if a claude process is running in a tmux window for the given ticket.
+ * Windows are named after ticket IDs (possibly with suffixes like " !" or " ~").
+ * Gets the pane PID and walks the process tree looking for a "claude" process.
+ */
+export declare function isSessionAliveInTmux(ticketId: string): boolean;
+/**
+ * Delete the session state file for a given ticket.
+ */
+export declare function clearSessionState(repoRoot: string, ticketId: string): void;

package/dist/lib/git.js

@@ -216,7 +216,7 @@ export async function removeWorktree(branchName, repoRoot, force = false) {
             }
             fs.rmSync(worktreePath, { recursive: true, force: true });
         }
-        // Clean up centralized metadata entry
+        // Clean up centralized metadata entry and session state
         const ticketId = extractTicketId(branchName);
         if (ticketId) {
             const all = readAllMetadata(repoRoot);
@@ -224,6 +224,7 @@ export async function removeWorktree(branchName, repoRoot, force = false) {
                 delete all[ticketId];
                 writeAllMetadata(repoRoot, all);
             }
+            clearSessionState(repoRoot, ticketId);
         }
         // Also delete the branch
         const deleteFlag = force ? "-D" : "-d";
@@ -584,3 +585,75 @@ export function getDiffStat(baseBranch) {
 export function getDiffContent(baseBranch) {
     return run(`git diff ${baseBranch}..HEAD`, { maxBuffer: 10 * 1024 * 1024 }) || null;
 }
+/**
+ * Get the path to the .santree/session-states directory.
+ */
+function getSessionStatesDir(repoRoot) {
+    return path.join(getSantreeDir(repoRoot), "session-states");
+}
+/**
+ * Read the session state file for a given ticket.
+ * Returns null if missing or "exited".
+ */
+export function readSessionState(repoRoot, ticketId) {
+    const filePath = path.join(getSessionStatesDir(repoRoot), `${ticketId}.json`);
+    if (!fs.existsSync(filePath))
+        return null;
+    try {
+        const data = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+        if (data.state === "exited")
+            return null;
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if a claude process is running in a tmux window for the given ticket.
+ * Windows are named after ticket IDs (possibly with suffixes like " !" or " ~").
+ * Gets the pane PID and walks the process tree looking for a "claude" process.
+ */
+export function isSessionAliveInTmux(ticketId) {
+    try {
+        const output = execSync('tmux list-windows -F "#{window_name}\t#{pane_pid}"', {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "ignore"],
+        }).trim();
+        for (const line of output.split("\n")) {
+            const [name, pidStr] = line.split("\t");
+            if (!name?.startsWith(ticketId))
+                continue;
+            if (!pidStr)
+                return false;
+            // Check if any descendant of the shell PID is a claude process
+            try {
+                const ps = execSync(`pgrep -P ${pidStr} -a`, {
+                    encoding: "utf-8",
+                    stdio: ["pipe", "pipe", "ignore"],
+                }).trim();
+                return ps.split("\n").some((proc) => proc.includes("claude"));
+            }
+            catch {
+                // pgrep exits 1 when no matches — shell has no children
+                return false;
+            }
+        }
+    }
+    catch {
+        // tmux not available or not in a tmux session
+    }
+    return false;
+}
+/**
+ * Delete the session state file for a given ticket.
+ */
+export function clearSessionState(repoRoot, ticketId) {
+    const filePath = path.join(getSessionStatesDir(repoRoot), `${ticketId}.json`);
+    try {
+        fs.unlinkSync(filePath);
+    }
+    catch {
+        // Ignore if file doesn't exist
+    }
+}

package/dist/lib/session-signal.d.ts

@@ -0,0 +1,15 @@
+export type SessionStateValue = "waiting" | "idle" | "active" | "exited";
+export declare function readStdin(): string;
+export declare function extractRepoAndTicket(cwd: string): {
+    repoRoot: string;
+    ticketId: string;
+} | null;
+export declare function renameTmuxWindow(ticketId: string, state: SessionStateValue): void;
+export declare function runHookScript(repoRoot: string, state: SessionStateValue, env: Record<string, string>): void;
+/**
+ * Unified helper: reads stdin, extracts repo/ticket, writes state file,
+ * renames tmux window, runs hook script, then exits.
+ */
+export declare function signalState(state: SessionStateValue): void;
+export declare function getHooksJson(): Record<string, unknown>;
+export declare function installHooks(): string;

package/dist/lib/session-signal.js

@@ -0,0 +1,150 @@
+import * as fs from "fs";
+import * as path from "path";
+import { execSync, spawn } from "child_process";
+export function readStdin() {
+    try {
+        return fs.readFileSync(0, "utf-8");
+    }
+    catch {
+        return "";
+    }
+}
+export function extractRepoAndTicket(cwd) {
+    const marker = "/.santree/worktrees/";
+    const idx = cwd.indexOf(marker);
+    if (idx === -1)
+        return null;
+    const repoRoot = cwd.slice(0, idx);
+    const rest = cwd.slice(idx + marker.length);
+    const ticketId = rest.split("/")[0];
+    if (!ticketId)
+        return null;
+    return { repoRoot, ticketId };
+}
+export function renameTmuxWindow(ticketId, state) {
+    if (!process.env.TMUX)
+        return;
+    let name;
+    switch (state) {
+        case "waiting":
+            name = `${ticketId} !`;
+            break;
+        case "idle":
+            name = `${ticketId} ~`;
+            break;
+        default:
+            name = ticketId;
+            break;
+    }
+    try {
+        execSync(`tmux rename-window "${name}"`, { stdio: "ignore" });
+    }
+    catch {
+        // Ignore tmux errors
+    }
+}
+export function runHookScript(repoRoot, state, env) {
+    const script = path.join(repoRoot, ".santree", "hooks", `on-${state}.sh`);
+    try {
+        fs.accessSync(script, fs.constants.X_OK);
+    }
+    catch {
+        return;
+    }
+    const child = spawn(script, [], {
+        cwd: env.SANTREE_WORKTREE_PATH,
+        env: { ...process.env, ...env },
+        stdio: "ignore",
+        detached: true,
+    });
+    child.unref();
+}
+/**
+ * Unified helper: reads stdin, extracts repo/ticket, writes state file,
+ * renames tmux window, runs hook script, then exits.
+ */
+export function signalState(state) {
+    const input = readStdin();
+    let data;
+    try {
+        data = JSON.parse(input);
+    }
+    catch {
+        process.exit(0);
+    }
+    const cwd = data.cwd || process.cwd();
+    const info = extractRepoAndTicket(cwd);
+    if (!info) {
+        process.exit(0);
+    }
+    const { repoRoot, ticketId } = info;
+    const statesDir = path.join(repoRoot, ".santree", "session-states");
+    fs.mkdirSync(statesDir, { recursive: true });
+    const stateFile = path.join(statesDir, `${ticketId}.json`);
+    const payload = {
+        state,
+        message: state === "waiting" ? (data.message ?? null) : null,
+        session_id: data.session_id ?? "",
+        at: new Date().toISOString(),
+    };
+    fs.writeFileSync(stateFile, JSON.stringify(payload, null, 2) + "\n");
+    renameTmuxWindow(ticketId, state);
+    const worktreePath = path.join(repoRoot, ".santree", "worktrees", ticketId);
+    runHookScript(repoRoot, state, {
+        SANTREE_TICKET_ID: ticketId,
+        SANTREE_SESSION_STATE: state,
+        SANTREE_SESSION_ID: data.session_id ?? "",
+        SANTREE_WORKTREE_PATH: worktreePath,
+        SANTREE_REPO_ROOT: repoRoot,
+        SANTREE_MESSAGE: payload.message ?? "",
+    });
+    process.exit(0);
+}
+export function getHooksJson() {
+    const base = "santree helpers session-signal";
+    const opts = { async: true, timeout: 10 };
+    return {
+        Notification: [
+            {
+                matcher: "permission_prompt",
+                hooks: [{ type: "command", command: `${base} notification`, ...opts }],
+            },
+        ],
+        Stop: [{ hooks: [{ type: "command", command: `${base} stop`, ...opts }] }],
+        UserPromptSubmit: [{ hooks: [{ type: "command", command: `${base} prompt`, ...opts }] }],
+        SessionEnd: [{ hooks: [{ type: "command", command: `${base} end`, ...opts }] }],
+    };
+}
+export function installHooks() {
+    const home = process.env.HOME || "";
+    const settingsPath = path.join(home, ".claude", "settings.json");
+    let settings = {};
+    try {
+        if (fs.existsSync(settingsPath)) {
+            settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+        }
+    }
+    catch {
+        // Start fresh if file is invalid
+    }
+    const requiredHooks = getHooksJson();
+    const existingHooks = settings.hooks || {};
+    for (const [event, hookEntries] of Object.entries(requiredHooks)) {
+        const existing = existingHooks[event];
+        if (!Array.isArray(existing)) {
+            existingHooks[event] = hookEntries;
+            continue;
+        }
+        // Remove existing session-signal entries, then add the current ones
+        const filtered = existing.filter((entry) => {
+            const inner = entry.hooks || [];
+            return !inner.some((h) => typeof h.command === "string" && h.command.includes("session-signal"));
+        });
+        existingHooks[event] = [...filtered, ...hookEntries];
+    }
+    settings.hooks = existingHooks;
+    const claudeDir = path.join(home, ".claude");
+    fs.mkdirSync(claudeDir, { recursive: true });
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    return settingsPath;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "santree",
-	"version": "0.2.6",
+	"version": "0.2.8",
 	"description": "Git worktree manager",
 	"license": "MIT",
 	"author": "Santiago Toscanini",
@@ -29,7 +29,7 @@
 		"node": ">=20"
 	},
 	"scripts": {
-		"build": "tsc && chmod +x dist/cli.js",
+		"build": "rm -rf dist && tsc && chmod +x dist/cli.js",
 		"dev": "tsc --watch",
 		"start": "node dist/cli.js",
 		"lint": "eslint source",