santree 0.7.4 → 0.7.6

package/dist/lib/git.d.ts

@@ -1,10 +1,4 @@
 export { getSantreeDir, readAllMetadata, writeAllMetadata } from "./metadata.js";
-export interface SessionState {
-    state: "waiting" | "idle" | "active" | "exited";
-    message: string | null;
-    session_id: string;
-    at: string;
-}
 export interface Worktree {
     path: string;
     branch: string;
@@ -191,17 +185,14 @@ export declare function getCommitsAheadAsync(cwd: string, baseBranch: string): P
  */
 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.
+ * Resolve the configured diff pager command (e.g. "delta", "diff-so-fancy"),
+ * or null if unset/invalid. Source order: `SANTREE_DIFF_TOOL` env override →
+ * santree's config file (set from `santree config`). See `lib/config-store.ts`.
  *
  * The CLI `worktree diff` flow lets the pager do its full job (render +
  * scroll) via git's `core.pager`. The dashboard's `[v]` overlay only uses
  * the rendering half — it captures the pager's stdout as a string and
  * handles scrolling itself in Ink.
- *
- * The value is restricted to a safe shell-token character set since it ends
- * up in arguments passed to spawn() — even though we never use shell:true,
- * keeping the surface tight defends against accidental misconfigurations.
  */
 export declare function getDiffTool(): string | null;
 export interface DiffShortstat {
@@ -315,20 +306,3 @@ export declare function unstageAll(cwd: string): Promise<void>;
  * - Untracked: deletes the file from disk via fs.unlink.
  */
 export declare function discardFile(cwd: string, filePath: string, isUntracked: boolean): Promise<void>;
-/**
- * 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 session for the given ticket is still alive in the active multiplexer.
- * Delegates to the configured multiplexer (tmux: pane_pid + pgrep claude;
- * cmux: workspace lookup; none: always false). Callers should also consult the
- * .santree/session-states/<ticketId>.json file — that's the authoritative signal
- * written by Claude Code hooks, while this is the "is the terminal still up" backstop.
- */
-export declare function isSessionAlive(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

@@ -3,7 +3,7 @@ import { promisify } from "util";
 import * as path from "path";
 import * as fs from "fs";
 import { run, runAsync, spawnAsync } from "./exec.js";
-import { getMultiplexer } from "./multiplexer/index.js";
+import { getConfiguredDiffTool } from "./config-store.js";
 import { getSantreeDir, readAllMetadata, writeAllMetadata } from "./metadata.js";
 import { getIssueTracker } from "./trackers/index.js";
 export { getSantreeDir, readAllMetadata, writeAllMetadata } from "./metadata.js";
@@ -217,7 +217,7 @@ export async function removeWorktree(branchName, repoRoot, force = false, onProg
             }
             fs.rmSync(worktreePath, { recursive: true, force: true });
         }
-        // Clean up centralized metadata entry and session state
+        // Clean up centralized metadata entry
         const ticketId = extractTicketId(branchName);
         if (ticketId) {
             const all = readAllMetadata(repoRoot);
@@ -225,7 +225,6 @@ export async function removeWorktree(branchName, repoRoot, force = false, onProg
                 delete all[ticketId];
                 writeAllMetadata(repoRoot, all);
             }
-            clearSessionState(repoRoot, ticketId);
         }
         // Also delete the branch
         report("Deleting branch…");
@@ -457,26 +456,17 @@ export async function getCommitsBehindAsync(cwd, 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.
+ * Resolve the configured diff pager command (e.g. "delta", "diff-so-fancy"),
+ * or null if unset/invalid. Source order: `SANTREE_DIFF_TOOL` env override →
+ * santree's config file (set from `santree config`). See `lib/config-store.ts`.
  *
  * The CLI `worktree diff` flow lets the pager do its full job (render +
  * scroll) via git's `core.pager`. The dashboard's `[v]` overlay only uses
  * the rendering half — it captures the pager's stdout as a string and
  * handles scrolling itself in Ink.
- *
- * The value is restricted to a safe shell-token character set since it ends
- * up in arguments passed to spawn() — even though we never use shell:true,
- * keeping the surface tight defends against accidental misconfigurations.
  */
 export function getDiffTool() {
-    const raw = process.env["SANTREE_DIFF_TOOL"];
-    if (!raw || !raw.trim())
-        return null;
-    const tool = raw.trim();
-    if (!/^[a-zA-Z0-9_\-/.+]+$/.test(tool))
-        return null;
-    return tool;
+    return getConfiguredDiffTool() ?? null;
 }
 /**
  * Compute branch-only diff stats vs base (uses merge-base, like a GitHub PR
@@ -704,49 +694,3 @@ export async function discardFile(cwd, filePath, isUntracked) {
         throw new Error(`git checkout HEAD failed: ${output.trim()}`);
     }
 }
-/**
- * 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 session for the given ticket is still alive in the active multiplexer.
- * Delegates to the configured multiplexer (tmux: pane_pid + pgrep claude;
- * cmux: workspace lookup; none: always false). Callers should also consult the
- * .santree/session-states/<ticketId>.json file — that's the authoritative signal
- * written by Claude Code hooks, while this is the "is the terminal still up" backstop.
- */
-export function isSessionAlive(ticketId) {
-    return getMultiplexer().isSessionAlive(ticketId);
-}
-/**
- * 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/github.d.ts

@@ -10,6 +10,34 @@ export interface PRInfo {
  * Returns null if no PR exists for the branch or gh CLI fails.
  */
 export declare function getPRInfoAsync(branchName: string): Promise<PRInfo | null>;
+/** GitHub's mergeability signals for a PR (subset we act on). */
+export interface PRMergeState {
+    /** "MERGEABLE" | "CONFLICTING" | "UNKNOWN" */
+    mergeable: string;
+    /** "BEHIND" | "BLOCKED" | "CLEAN" | "DIRTY" | "DRAFT" | "HAS_HOOKS" | "UNKNOWN" | "UNSTABLE" */
+    mergeStateStatus: string;
+    /** True when the branch has conflicts with its base that need resolving. */
+    hasConflicts: boolean;
+}
+/**
+ * Fetch a PR's mergeability for a branch. `CONFLICTING` (or a `DIRTY` merge-state)
+ * means the branch conflicts with its base and needs a merge/resolve before CI can
+ * pass. Returns null if no PR exists or gh fails. GitHub computes mergeability
+ * asynchronously, so `mergeable` is `UNKNOWN` briefly after a push — callers should
+ * treat `UNKNOWN` as "don't know yet", not "no conflicts".
+ */
+export declare function getPRMergeStateAsync(branchName: string): Promise<PRMergeState | null>;
+/**
+ * Classify a CI check as something an AI agent can plausibly fix on its own
+ * ("fixable" — tests, types, lint, format, coverage) vs. one that needs a human or
+ * infra ("manual" — deploys, releases, image builds, e2e, security scans). Matched
+ * case-insensitively against the check's name + workflow. **Unknown ⇒ "manual"**:
+ * the fix loop should only touch failures it's confident about and stop otherwise.
+ * Extend the keyword lists as new check conventions appear (cf. HIDDEN_STATE_NAMES).
+ */
+export declare const FIXABLE_CHECK_PATTERN: RegExp;
+export declare const MANUAL_CHECK_PATTERN: RegExp;
+export declare function classifyCheck(check: Pick<PRCheck, "name" | "workflow">): "fixable" | "manual";
 /**
  * Check if the GitHub CLI (gh) is available on PATH.
  * Runs: `which gh`
@@ -50,6 +78,48 @@ export declare function getPRReviewsAsync(prNumber: string): Promise<PRReview[]
  * Fetch inline review comments for a pull request via the GitHub API (async).
  */
 export declare function getPRReviewCommentsAsync(prNumber: string): Promise<PRReviewComment[] | null>;
+/**
+ * The authenticated GitHub user's login (GraphQL `viewer`). Cached per process.
+ * Used to gate auto-applying a review comment on the PR owner's OWN 👍 — a
+ * reviewer can't self-approve their comment for the fix loop.
+ */
+export declare function getViewerLoginAsync(): Promise<string | null>;
+export interface PRReviewThreadComment {
+    author: string;
+    body: string;
+    path: string | null;
+    /** Current line, falling back to the original line for outdated comments. */
+    line: number | null;
+    diffHunk: string;
+    createdAt: string;
+    /** Logins of users who reacted 👍 (THUMBS_UP) to this comment. */
+    thumbsUpBy: string[];
+}
+/** A PR review thread (an inline comment + its replies) with resolution state. */
+export interface PRReviewThread {
+    /** GraphQL node id — used to resolve the thread after the fix is applied. */
+    id: string;
+    isResolved: boolean;
+    isOutdated: boolean;
+    path: string | null;
+    /** Anchor line in the current diff, falling back to the original line. */
+    line: number | null;
+    comments: PRReviewThreadComment[];
+}
+/**
+ * Fetch a PR's review threads with resolution state and per-comment 👍 reactions.
+ * The REST comments endpoint exposes neither, so this goes through GraphQL.
+ * Returns null if the repo can't be resolved or gh fails.
+ */
+export declare function getPRReviewThreadsAsync(prNumber: string): Promise<PRReviewThread[] | null>;
+/**
+ * Filter review threads to the ones the fix loop should act on: **unresolved**
+ * AND whose **last comment carries a 👍 from `approver`** (the viewer's own
+ * approval). Resolved threads are dropped entirely — resolved means the ask was
+ * already applied or deliberately declined. The 👍 gate stops the loop from
+ * applying a comment the moment it's left, before the PR owner has vetted it.
+ */
+export declare function getApprovedReviewThreads(threads: PRReviewThread[], approver: string): PRReviewThread[];
 /**
  * Fetch structured conversation comments on a pull request (async).
  */

package/dist/lib/github.js

@@ -22,6 +22,50 @@ export async function getPRInfoAsync(branchName) {
         return null;
     }
 }
+/**
+ * Fetch a PR's mergeability for a branch. `CONFLICTING` (or a `DIRTY` merge-state)
+ * means the branch conflicts with its base and needs a merge/resolve before CI can
+ * pass. Returns null if no PR exists or gh fails. GitHub computes mergeability
+ * asynchronously, so `mergeable` is `UNKNOWN` briefly after a push — callers should
+ * treat `UNKNOWN` as "don't know yet", not "no conflicts".
+ */
+export async function getPRMergeStateAsync(branchName) {
+    try {
+        const { stdout } = await execAsync(`gh pr view "${branchName}" --json mergeable,mergeStateStatus`);
+        const data = JSON.parse(stdout);
+        const mergeable = String(data.mergeable ?? "UNKNOWN");
+        const mergeStateStatus = String(data.mergeStateStatus ?? "UNKNOWN");
+        return {
+            mergeable,
+            mergeStateStatus,
+            hasConflicts: mergeable === "CONFLICTING" || mergeStateStatus === "DIRTY",
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Classify a CI check as something an AI agent can plausibly fix on its own
+ * ("fixable" — tests, types, lint, format, coverage) vs. one that needs a human or
+ * infra ("manual" — deploys, releases, image builds, e2e, security scans). Matched
+ * case-insensitively against the check's name + workflow. **Unknown ⇒ "manual"**:
+ * the fix loop should only touch failures it's confident about and stop otherwise.
+ * Extend the keyword lists as new check conventions appear (cf. HIDDEN_STATE_NAMES).
+ */
+// Trailing \b only (no leading boundary) so test-runner prefixes and plurals
+// match: "pytest", "tests", "rspec", "codecov" all count as fixable.
+export const FIXABLE_CHECK_PATTERN = /(tests?|specs?|jest|vitest|mocha|junit|phpunit|lint|format|prettier|eslint|ruff|black|gofmt|rustfmt|type[\s-]?check|tsc|mypy|pyright|coverage|cov)\b/i;
+export const MANUAL_CHECK_PATTERN = /\b(deploy|release|publish|build[\s-]?image|docker|e2e|end[\s-]?to[\s-]?end|integration|smoke|terraform|infra|migrat|codeql|security|scan|sign|notariz)\b/i;
+export function classifyCheck(check) {
+    const haystack = `${check.name} ${check.workflow}`;
+    // Manual wins ties: a "deploy tests" job is safer treated as manual.
+    if (MANUAL_CHECK_PATTERN.test(haystack))
+        return "manual";
+    if (FIXABLE_CHECK_PATTERN.test(haystack))
+        return "fixable";
+    return "manual";
+}
 /**
  * Check if the GitHub CLI (gh) is available on PATH.
  * Runs: `which gh`
@@ -137,6 +181,90 @@ export async function getPRReviewCommentsAsync(prNumber) {
         return null;
     }
 }
+/** Per-process cache of the authenticated GitHub login (the "viewer"). */
+let viewerLoginCache = null;
+/**
+ * The authenticated GitHub user's login (GraphQL `viewer`). Cached per process.
+ * Used to gate auto-applying a review comment on the PR owner's OWN 👍 — a
+ * reviewer can't self-approve their comment for the fix loop.
+ */
+export function getViewerLoginAsync() {
+    if (viewerLoginCache)
+        return viewerLoginCache;
+    viewerLoginCache = (async () => {
+        try {
+            const { stdout } = await execAsync(`gh api graphql -f query='{ viewer { login } }' --jq .data.viewer.login`);
+            return stdout.trim() || null;
+        }
+        catch {
+            return null;
+        }
+    })();
+    return viewerLoginCache;
+}
+/**
+ * Fetch a PR's review threads with resolution state and per-comment 👍 reactions.
+ * The REST comments endpoint exposes neither, so this goes through GraphQL.
+ * Returns null if the repo can't be resolved or gh fails.
+ */
+export async function getPRReviewThreadsAsync(prNumber) {
+    const repo = await getRepoNameAsync();
+    if (!repo)
+        return null;
+    const [owner, name] = repo.split("/");
+    if (!owner || !name)
+        return null;
+    // Single-line query (GraphQL ignores whitespace); single-quoted for the shell.
+    // `first` bounds keep us well under GitHub's query-complexity cap.
+    const query = `query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){` +
+        `pullRequest(number:$number){reviewThreads(first:100){nodes{id isResolved isOutdated path line originalLine ` +
+        `comments(first:50){nodes{author{login} body path line originalLine diffHunk createdAt ` +
+        `reactions(first:50){nodes{content user{login}}}}}}}}}}`;
+    const output = await runAsync(`gh api graphql -f query='${query}' -f owner='${owner}' -f name='${name}' -F number=${Number(prNumber)}`);
+    if (!output)
+        return null;
+    try {
+        const data = JSON.parse(output);
+        const nodes = data?.data?.repository?.pullRequest?.reviewThreads?.nodes ?? [];
+        return nodes.map((t) => ({
+            id: String(t.id),
+            isResolved: !!t.isResolved,
+            isOutdated: !!t.isOutdated,
+            path: t.path ?? null,
+            line: t.line ?? t.originalLine ?? null,
+            comments: (t.comments?.nodes ?? []).map((c) => ({
+                author: c.author?.login ?? "unknown",
+                body: c.body ?? "",
+                path: c.path ?? null,
+                line: c.line ?? c.originalLine ?? null,
+                diffHunk: c.diffHunk ?? "",
+                createdAt: c.createdAt ?? "",
+                thumbsUpBy: (c.reactions?.nodes ?? [])
+                    .filter((r) => r.content === "THUMBS_UP")
+                    .map((r) => r.user?.login)
+                    .filter(Boolean),
+            })),
+        }));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Filter review threads to the ones the fix loop should act on: **unresolved**
+ * AND whose **last comment carries a 👍 from `approver`** (the viewer's own
+ * approval). Resolved threads are dropped entirely — resolved means the ask was
+ * already applied or deliberately declined. The 👍 gate stops the loop from
+ * applying a comment the moment it's left, before the PR owner has vetted it.
+ */
+export function getApprovedReviewThreads(threads, approver) {
+    return threads.filter((t) => {
+        if (t.isResolved)
+            return false;
+        const last = t.comments[t.comments.length - 1];
+        return !!last && last.thumbsUpBy.includes(approver);
+    });
+}
 /**
  * Fetch structured conversation comments on a pull request (async).
  */

package/dist/lib/multiplexer/cmux.js

@@ -28,16 +28,112 @@ function findWorkspaceByTitle(title) {
         return null;
     }
 }
+// `list-pane-surfaces --workspace X` reports one pane (the active one) and its
+// surfaces (tabs). Enough for our two flows: the work workspace has a single
+// pane, and a freshly-created temp workspace has a single pane + single surface.
+function paneSurfaces(workspaceRef) {
+    const r = cmuxRun(`cmux --json list-pane-surfaces --workspace ${shellEscape(workspaceRef)}`);
+    if (!r.ok)
+        return null;
+    try {
+        return JSON.parse(r.stdout);
+    }
+    catch {
+        return null;
+    }
+}
+function renameTab(workspaceRef, surfaceRef, title) {
+    cmuxRun(`cmux rename-tab --workspace ${shellEscape(workspaceRef)} --surface ${shellEscape(surfaceRef)} ${shellEscape(title)}`);
+}
+// cmux exposes workspace-group (sidebar folder) operations only over the RPC
+// socket, not as first-class subcommands. `cmux rpc <method> '<json>'`.
+function cmuxRpc(method, params) {
+    const arg = params ? ` ${shellEscape(JSON.stringify(params))}` : "";
+    const result = cmuxRun(`cmux rpc ${method}${arg}`);
+    if (!result.ok)
+        return { ok: false };
+    try {
+        return { ok: true, data: JSON.parse(result.stdout) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+function findGroupIdByName(name) {
+    const r = cmuxRpc("workspace.group.list");
+    if (!r.ok)
+        return null;
+    const groups = r.data?.groups ?? [];
+    return groups.find((g) => g.name === name)?.id ?? null;
+}
+// Snapshot every workspace's current group membership (ref -> group id), so we
+// can detect and undo the side effect described in `createGroup` below.
+function snapshotMemberships() {
+    const map = new Map();
+    const r = cmuxRpc("workspace.group.list");
+    if (!r.ok)
+        return map;
+    for (const g of r.data?.groups ?? []) {
+        if (!g.id)
+            continue;
+        for (const ref of g.member_workspace_refs ?? [])
+            map.set(ref, g.id);
+    }
+    return map;
+}
+// Create a sidebar group (folder) named `name` and return its id.
+//
+// Two cmux quirks shape this:
+//  1. A group renders as a folder whose header IS its "anchor" workspace
+//     (auto-titled with the group name); members nest under it. We must keep
+//     that anchor — closing it removes the folder label and cmux flattens the
+//     members back to top-level rows (visually ungrouped).
+//  2. `workspace.group.create` also pulls the *currently-selected* workspace
+//     into the new group as a stray member. We undo that: restore each stray to
+//     whatever group it was in before (or detach it if none), so creating a
+//     project folder never disturbs the user's existing folders or their
+//     dashboard window.
+function createGroup(name) {
+    const before = snapshotMemberships();
+    const created = cmuxRpc("workspace.group.create", { name });
+    if (!created.ok)
+        return null;
+    const group = created.data?.group;
+    if (!group?.id)
+        return null;
+    const anchor = group.anchor_workspace_ref;
+    for (const ref of group.member_workspace_refs ?? []) {
+        if (ref === anchor)
+            continue;
+        const prev = before.get(ref);
+        if (prev && prev !== group.id) {
+            cmuxRpc("workspace.group.add", { group_id: prev, workspace_id: ref });
+        }
+        else {
+            cmuxRpc("workspace.group.remove", { group_id: group.id, workspace_id: ref });
+        }
+    }
+    return group.id;
+}
+// Place an already-created workspace into a sidebar group named `groupName`,
+// creating the group on first use. Best-effort: any failure leaves the
+// workspace ungrouped but otherwise intact.
+function placeWorkspaceInGroup(groupName, workspaceRef) {
+    const groupId = findGroupIdByName(groupName) ?? createGroup(groupName);
+    if (!groupId)
+        return;
+    cmuxRpc("workspace.group.add", { group_id: groupId, workspace_id: workspaceRef });
+}
 export const cmuxMultiplexer = {
     kind: "cmux",
     isActive() {
         return !!process.env["CMUX_SURFACE_ID"];
     },
-    async createWindow({ name, cwd, command }) {
+    async createWindow({ name, cwd, command, group, tabName, }) {
         // `new-workspace` accepts --name, --cwd, --command in a single atomic call.
-        // `--command` sends "<text>\n" to the new surface after creation. cmux #1472 means
-        // programmatically created workspaces have dead PTYs, so the command may not actually
-        // execute — but the workspace + name are created, which is the visible win.
+        // `--command` sends "<text>\n" to the new surface after creation, which IS
+        // the one reliable way to get a live PTY (cmux #1472 only breaks commands on
+        // surfaces created *after* the workspace exists).
         const parts = [`cmux new-workspace --name ${shellEscape(name)} --cwd ${shellEscape(cwd)}`];
         if (command)
             parts.push(`--command ${shellEscape(command)}`);
@@ -45,6 +141,49 @@ export const cmuxMultiplexer = {
         if (!created.ok) {
             return { ok: false, reason: "failed", message: "cmux new-workspace failed" };
         }
+        // Grouping / tab-naming are best-effort and must never fail the launch.
+        // `new-workspace` prints the new workspace ref (`OK workspace:N`) to stdout.
+        const ref = created.stdout.match(/workspace:\d+/)?.[0];
+        if (group && ref)
+            placeWorkspaceInGroup(group, ref);
+        if (tabName && ref) {
+            const surface = paneSurfaces(ref)?.surfaces?.[0]?.ref;
+            if (surface)
+                renameTab(ref, surface, tabName);
+        }
+        return { ok: true };
+    },
+    async addTab({ windowName, tabName, cwd, command, group }) {
+        const target = findWorkspaceByTitle(windowName);
+        // No existing workspace for this ticket — create one named after it, with
+        // the command as its (renamed) tab.
+        if (!target?.ref) {
+            return this.createWindow({ name: windowName, cwd, command, group, tabName });
+        }
+        const targetPane = paneSurfaces(target.ref)?.pane_ref;
+        if (!targetPane) {
+            return { ok: false, reason: "failed", message: "could not resolve target pane" };
+        }
+        // A surface only gets a live PTY when its command is baked in at workspace
+        // creation. So we spawn the command in a throwaway workspace, then relocate
+        // the (already-running) surface into the target pane and discard the husk.
+        const tmpName = `__santree_tab_${windowName}`;
+        const tmp = cmuxRun(`cmux new-workspace --name ${shellEscape(tmpName)} --cwd ${shellEscape(cwd)} --command ${shellEscape(command)}`);
+        if (!tmp.ok) {
+            return { ok: false, reason: "failed", message: "could not launch tab command" };
+        }
+        const tmpRef = tmp.stdout.match(/workspace:\d+/)?.[0];
+        const surface = tmpRef ? paneSurfaces(tmpRef)?.surfaces?.[0]?.ref : undefined;
+        if (!tmpRef || !surface) {
+            return { ok: false, reason: "failed", message: "could not resolve new tab surface" };
+        }
+        const moved = cmuxRun(`cmux move-surface --surface ${shellEscape(surface)} --pane ${shellEscape(targetPane)}`);
+        if (!moved.ok) {
+            // Leave the command running in its own workspace rather than losing it.
+            return { ok: false, reason: "failed", message: "could not move tab into workspace" };
+        }
+        cmuxRun(`cmux workspace close --workspace ${shellEscape(tmpRef)}`);
+        renameTab(target.ref, surface, tabName);
         return { ok: true };
     },
     async selectWindow(name) {
@@ -66,17 +205,4 @@ export const cmuxMultiplexer = {
             message: "blocked by manaflow-ai/cmux#1472",
         };
     },
-    isSessionAlive(ticketId) {
-        const result = cmuxRun("cmux --json list-workspaces");
-        if (!result.ok)
-            return false;
-        try {
-            const parsed = JSON.parse(result.stdout);
-            const items = parsed.workspaces ?? [];
-            return items.some((w) => typeof w.title === "string" && w.title.startsWith(ticketId));
-        }
-        catch {
-            return false;
-        }
-    },
 };

package/dist/lib/multiplexer/none.js

@@ -7,13 +7,13 @@ export const noneMultiplexer = {
     async createWindow() {
         return NOT_ACTIVE;
     },
+    async addTab() {
+        return NOT_ACTIVE;
+    },
     async selectWindow() {
         return NOT_ACTIVE;
     },
     sendCommand() {
         return NOT_ACTIVE;
     },
-    isSessionAlive() {
-        return false;
-    },
 };

package/dist/lib/multiplexer/tmux.js

@@ -30,6 +30,11 @@ export const tmuxMultiplexer = {
         }
         return { ok: true };
     },
+    async addTab({ windowName, tabName, cwd, command }) {
+        // tmux has no in-window tab concept, so a "tab" becomes its own window named
+        // `<tabName>-<windowName>` (e.g. fix-loop-TEAM-123).
+        return this.createWindow({ name: `${tabName}-${windowName}`, cwd, command });
+    },
     async selectWindow(name) {
         if (!this.isActive())
             return { ok: false, reason: "not-active" };
@@ -42,33 +47,4 @@ export const tmuxMultiplexer = {
         const ok = tmuxSync(`tmux send-keys -t ${shellEscape(name)} ${shellEscape(command)} Enter`);
         return ok ? { ok: true } : { ok: false, reason: "failed" };
     },
-    isSessionAlive(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;
-                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 {
-                    return false;
-                }
-            }
-        }
-        catch {
-            // tmux not available
-        }
-        return false;
-    },
 };

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

@@ -10,13 +10,46 @@ export interface CreateWindowOpts {
     name: string;
     cwd: string;
     command?: string;
+    /**
+     * Optional sidebar group/folder to place the new window in. Backends that
+     * have no grouping concept (tmux, none) ignore it; cmux files the workspace
+     * under a group of this name (creating it on first use). Used to cluster all
+     * windows for one Linear project together.
+     */
+    group?: string;
+    /**
+     * Optional name for the window's initial tab/surface. cmux renames the tab
+     * after creation; backends without an in-window tab concept ignore it.
+     */
+    tabName?: string;
+}
+export interface AddTabOpts {
+    /** Name of the existing window/workspace to add the tab to. */
+    windowName: string;
+    /** Name for the new tab. */
+    tabName: string;
+    cwd: string;
+    command: string;
+    /**
+     * Group to use only if the target window doesn't exist yet and a fresh one
+     * has to be created as a fallback (cmux only).
+     */
+    group?: string;
 }
 export interface Multiplexer {
     readonly kind: MultiplexerKind;
     isActive(): boolean;
     createWindow(opts: CreateWindowOpts): Promise<SessionResult>;
+    /**
+     * Add a tab running `command` to an existing window/workspace named
+     * `windowName`. cmux relocates a live surface into that workspace so the two
+     * tabs (e.g. `work` + `fix-loop`) share one ticket workspace. Backends with
+     * no in-window tab concept (tmux, none) create a separate window named
+     * `<tabName>-<windowName>` instead. Falls back to creating the window when it
+     * doesn't exist yet.
+     */
+    addTab(opts: AddTabOpts): Promise<SessionResult>;
     selectWindow(name: string): Promise<SessionResult>;
     sendCommand(name: string, command: string): SessionResult;
-    isSessionAlive(ticketId: string): boolean;
 }
 export declare function shellEscape(s: string): string;