@phnx-labs/agents-cli 1.22.33 → 1.22.34

package/dist/commands/sessions.js

@@ -13,7 +13,7 @@ import * as path from 'path';
 import { spawn } from 'child_process';
 import { Option } from 'commander';
 import chalk from 'chalk';
-import { truncate, padRight } from '../lib/format.js';
+import { truncate, padRight, humanDuration } from '../lib/format.js';
 import { sanitizeForTerminal } from '../lib/redact.js';
 import { resolveProjectKey } from '../lib/project-key.js';
 import { listProjectDefs, resolveProjectNameForCwd } from '../lib/projects.js';
@@ -37,13 +37,14 @@ import { filterTeamSessions, shouldShowTeamSessions, safeTeamText, groupSessions
 import { parseSession } from '../lib/session/parse.js';
 import { runRemoteSessions, buildForwardedArgs, ensureWholeIndex } from '../lib/session/remote.js';
 import { formatRelativeTime, formatCompactAge, sessionAgeParts } from '../lib/session/relative-time.js';
-import { renderConversationMarkdown, renderSummary, renderSummaryHeader, computeSummaryStats, renderJson, filterEvents, parseRoleList, linkPath, linkUrl, shortenModel } from '../lib/session/render.js';
+import { renderConversationMarkdown, renderSummary, renderSummaryHeader, computeSummaryStats, renderJson, filterEvents, parseRoleList, linkPath, linkUrl, shortenModel, formatTokenCount } from '../lib/session/render.js';
 import { linearIssueUrl } from '../lib/session/linear.js';
 import { sessionOwnerDevice, RESUME_PINNED_ENV } from '../lib/session/resume-owner.js';
 import { renderMarkdown } from '../lib/markdown.js';
 import { AGENTS, colorAgent, resolveAgentName } from '../lib/agents.js';
 import { getShimsDir } from '../lib/state.js';
-import { listJobs, listJobsWithRuns, listRuns } from '../lib/routines.js';
+import { listJobs, listJobsWithRuns, listRuns, getRunDir } from '../lib/routines.js';
+import { formatUsd } from '../lib/pricing/cost.js';
 import { fuzzyMatch, FUZZY_PRESETS } from '../lib/fuzzy.js';
 import { itemPicker } from '../lib/picker.js';
 import { resolveSessionAlias } from '../lib/session/actor-sidecar.js';
@@ -72,7 +73,7 @@ import { registerSessionsBackfillCommand } from './sessions-backfill.js';
 import { registerSessionsStatsCommand } from './sessions-stats.js';
 import { registerSessionsInsightsCommand } from './insights.js';
 import { registerSessionsOptimizeCommand } from './sessions-optimize.js';
-import { runBrowserSessions } from '../lib/browser/sessions-list.js';
+import { runBrowserSessionsCommand } from './browser-sessions-picker.js';
 import { countToolProgramOccurrences, parseToolProgramCountClause, readToolIndexCoverage, searchToolCalls, TOOL_QUERY_MAX_CLAUSE_BYTES, TOOL_QUERY_MAX_CLAUSES, TOOL_QUERY_MAX_RESULT_SESSIONS, serializeToolSearchEnvelope, toolSearchRemoteReceiveBudget, } from '../lib/session/tool-index.js';
 const SESSION_AGENT_FILTER_HELP = `Filter by agent, e.g. claude, codex, claude@2.0.65`;
 function collectQueryClause(value, previous) {
@@ -1631,33 +1632,238 @@ function safeListJobsWithRuns() {
         return [];
     }
 }
-export async function filterSessionsByRoutine(sessions, routine, interactive) {
-    // The name universe is transcripts UNION routines that have any run record —
-    // so a routine whose attempts never produced a session still resolves.
+/**
+ * Resolve which routine the user is targeting for `--routine`. Returns `null` to
+ * ABORT the command (a bad `--routine <name>` printed an error, or the user
+ * cancelled the interactive pick). `{ name: null }` means "no routine was
+ * selected, don't filter" — the degenerate bare `--routine` piped to a
+ * non-interactive sink. `{ name }` is a chosen routine.
+ *
+ * The name universe is transcripts UNION every routine with a definition or a
+ * run record (`safeListJobsWithRuns`), so a command-only or never-ran routine —
+ * which produces no `SessionMeta` — still resolves and drills down.
+ */
+export async function selectRoutineTarget(sessions, routine, interactive) {
     const routineNames = [...new Set([
             ...sessions.map((session) => session.routineName).filter((name) => !!name),
             ...safeListJobsWithRuns(),
         ])].sort((a, b) => a.localeCompare(b));
-    let selectedRoutine = null;
     if (typeof routine === 'string') {
-        selectedRoutine = resolveRoutineName(routine, routineNames);
-        if (!selectedRoutine) {
+        const resolved = resolveRoutineName(routine, routineNames);
+        if (!resolved) {
             console.error(chalk.red(`No routine matches "${routine}".`));
             if (routineNames.length > 0)
                 console.error(chalk.gray(`Available routines: ${routineNames.join(', ')}`));
             process.exitCode = 1;
             return null;
         }
+        return { name: resolved };
     }
-    else if (interactive) {
-        selectedRoutine = await selectRoutineName(sessions);
-        if (!selectedRoutine)
+    if (interactive) {
+        const picked = await selectRoutineName(sessions);
+        if (!picked)
             return null;
+        return { name: picked };
     }
-    if (!selectedRoutine)
-        return sessions;
-    const matched = sessions.filter((session) => session.routineName === selectedRoutine);
-    return matched;
+    return { name: null };
+}
+export async function filterSessionsByRoutine(sessions, routine, interactive) {
+    const target = await selectRoutineTarget(sessions, routine, interactive);
+    if (!target)
+        return null;
+    return target.name
+        ? sessions.filter((session) => session.routineName === target.name)
+        : sessions;
+}
+export function executionKind(meta) {
+    if (meta.workflow)
+        return 'workflow';
+    if (meta.agent)
+        return 'agent';
+    return 'command';
+}
+/**
+ * Reconcile a routine's canonical run records (`listRuns`, local disk) with the
+ * indexed sessions for that routine (fleet-wide, keyed by `routineRunId`).
+ */
+export function buildRoutineDrilldown(name, sessions) {
+    const runs = listRuns(name);
+    const forRoutine = sessions.filter((s) => s.routineName === name);
+    const byRun = new Map();
+    for (const s of forRoutine) {
+        const rid = s.routineRunId ?? s.timestamp;
+        (byRun.get(rid) ?? byRun.set(rid, []).get(rid)).push(s);
+    }
+    const runIds = new Set(runs.map((r) => r.runId));
+    const entries = runs
+        .map((meta) => ({
+        meta,
+        sessions: (byRun.get(meta.runId) ?? []).sort((a, b) => (a.timestamp < b.timestamp ? 1 : -1)),
+    }))
+        // Newest run first: `startedAt`, then run id (an ISO-derived slot) as a tie-break.
+        .sort((a, b) => {
+        const at = a.meta.startedAt || a.meta.runId;
+        const bt = b.meta.startedAt || b.meta.runId;
+        return at < bt ? 1 : at > bt ? -1 : b.meta.runId.localeCompare(a.meta.runId);
+    });
+    const orphanSessions = buildRoutineRunGroups(forRoutine.filter((s) => !runIds.has(s.routineRunId ?? s.timestamp)));
+    return {
+        name,
+        runs: entries,
+        orphanSessions,
+        runRecordCount: runs.length,
+        linkedSessionCount: forRoutine.length,
+        // "Agent routine" = anything that isn't purely command runs. A workflow run
+        // carries no `agent` field but still expects a session, so key off
+        // executionKind, not `agent` alone.
+        isAgentRoutine: runs.some((r) => executionKind(r) !== 'command') || forRoutine.length > 0,
+    };
+}
+/** Glyph + word for a run's terminal status. */
+function runStatusCell(status) {
+    switch (status) {
+        case 'completed': return `${chalk.green('✓')} ${chalk.green('completed')}`;
+        case 'running': return `${chalk.cyan('◍')} ${chalk.cyan('running')}`;
+        case 'failed': return `${chalk.red('✗')} ${chalk.red('failed')}`;
+        case 'timeout': return `${chalk.red('✗')} ${chalk.red('timeout')}`;
+        case 'blocked': return `${chalk.yellow('⚠')} ${chalk.yellow('blocked')}`;
+        case 'skipped': return `${chalk.gray('↷')} ${chalk.gray('skipped')}`;
+        case 'missed': return `${chalk.gray('·')} ${chalk.gray('missed')}`;
+        default: return chalk.gray(status);
+    }
+}
+/** Where a run's body executed: a host, a cloud provider, or this machine. */
+function runPlacement(meta) {
+    if (meta.host)
+        return `host:${meta.host}`;
+    if (meta.cloudProvider)
+        return `cloud:${meta.cloudProvider}`;
+    return 'local';
+}
+/** The trigger clause: kind + who triggered it (dropping the noisy UNRESOLVED). */
+function runTrigger(meta) {
+    const kind = meta.triggerKind ?? 'schedule';
+    const who = meta.triggeredBy && !meta.triggeredBy.startsWith('UNRESOLVED') ? ` by ${meta.triggeredBy}` : '';
+    return `${kind}${who}`;
+}
+/** The tail clause explaining a run's outcome (exit code / error / skip reason). */
+function runOutcomeDetail(meta) {
+    if (meta.status === 'skipped' && meta.skipReason) {
+        const ref = meta.activeRunId ? ` → ${meta.activeRunId}` : '';
+        return `${meta.skipReason.replace(/_/g, ' ')}${ref}`;
+    }
+    if (meta.status === 'blocked') {
+        return meta.readiness ? `${meta.readiness.code}: ${meta.readiness.message}` : (meta.errorMessage ?? 'not ready');
+    }
+    if (meta.status === 'missed')
+        return 'daemon down at fire time';
+    if (meta.errorMessage)
+        return meta.errorMessage;
+    // A clean `exit 0` is already implied by the green "completed" status — only a
+    // non-zero code carries information worth a tail clause.
+    if (typeof meta.exitCode === 'number' && meta.exitCode !== 0)
+        return `exit ${meta.exitCode}`;
+    return '';
+}
+/** Compact per-session metadata line under a linked session row. */
+function linkedSessionMeta(session) {
+    const parts = [];
+    parts.push(session.version ? `${session.agent} v${session.version}` : session.agent);
+    if (session.account)
+        parts.push(session.account);
+    if (session.model)
+        parts.push(shortenModel(session.model));
+    if (typeof session.outputTokens === 'number')
+        parts.push(`${formatTokenCount(session.outputTokens)} out`);
+    else if (typeof session.tokenCount === 'number')
+        parts.push(`${formatTokenCount(session.tokenCount)} tok`);
+    if (typeof session.costUsd === 'number' && session.costUsd > 0)
+        parts.push(formatUsd(session.costUsd));
+    if (typeof session.durationMs === 'number' && session.durationMs > 0)
+        parts.push(humanDuration(session.durationMs));
+    if (typeof session.toolCallCount === 'number')
+        parts.push(`${session.toolCallCount} tools`);
+    return chalk.gray('      ' + parts.join(' · '));
+}
+/**
+ * Render the routine drilldown: canonical run history first, each run linked to
+ * its indexed agent session(s). This is the run/session seam made visible — a
+ * command routine shows its runs and states plainly that no session is expected;
+ * an agent routine shows the same runs plus each run's session metadata.
+ */
+export function printRoutineDrilldown(drill, liveIndex, opts = {}) {
+    const runWord = drill.runRecordCount === 1 ? 'run record' : 'run records';
+    const sessWord = drill.linkedSessionCount === 1 ? 'linked session' : 'linked sessions';
+    console.log(`${chalk.cyan.bold(drill.name)}  ` +
+        chalk.gray(`${drill.runRecordCount} ${runWord} · ${drill.linkedSessionCount} ${sessWord}`));
+    // A routine with no session ever produced is a command routine — say so up
+    // front so the empty session column reads as expected, not as missing data.
+    if (!drill.isAgentRoutine) {
+        console.log(chalk.gray('Command routine — runs execute a shell command; no agent session is produced.'));
+    }
+    console.log();
+    if (drill.runs.length === 0 && drill.orphanSessions.length === 0) {
+        console.log(chalk.gray('No run records yet for this routine.'));
+        return;
+    }
+    for (const entry of drill.runs) {
+        const m = entry.meta;
+        console.log(`${chalk.cyan('▸')} ${chalk.cyan.bold(m.runId)}  ` +
+            `${runStatusCell(m.status)}  ` +
+            chalk.gray(`${runTrigger(m)} · ${formatRelativeTime(m.startedAt)}`));
+        const kind = executionKind(m);
+        const detailParts = [kind];
+        if (typeof m.duration === 'number' && m.duration > 0)
+            detailParts.push(humanDuration(m.duration));
+        detailParts.push(runPlacement(m));
+        const outcome = runOutcomeDetail(m);
+        if (outcome)
+            detailParts.push(outcome);
+        console.log(chalk.gray('    ' + detailParts.join(' · ')));
+        // Log/report access — both are children of the run dir that a pre-execution
+        // terminal (blocked/skipped/missed) never wrote, so gate each on existence
+        // rather than pointing at a file that isn't there.
+        const runDir = getRunDir(drill.name, m.runId);
+        const logHints = [];
+        if (fs.existsSync(path.join(runDir, 'stdout.log')))
+            logHints.push(`log: ${path.join(runDir, 'stdout.log')}`);
+        if (fs.existsSync(path.join(runDir, 'report.md')))
+            logHints.push(`report: ${path.join(runDir, 'report.md')}`);
+        if (logHints.length > 0)
+            console.log(chalk.gray('    ' + logHints.join('  ·  ')));
+        if (entry.sessions.length > 0) {
+            for (const session of entry.sessions) {
+                console.log(treeSessionRow(session, liveIndex?.get(session.id)));
+                console.log(linkedSessionMeta(session));
+            }
+        }
+        else if (kind !== 'command') {
+            // An agent run that produced no session — say why (the run terminal
+            // explains it), never fake a session row.
+            console.log(chalk.gray('      no agent session archived for this run'));
+        }
+        console.log();
+    }
+    if (drill.orphanSessions.length > 0) {
+        console.log(chalk.gray('Sessions with no local run record (run archived on another host):'));
+        for (const group of drill.orphanSessions) {
+            console.log(`${chalk.cyan('▸')} ${chalk.cyan.bold(group.runId)}  ` +
+                chalk.gray(`${group.sessions.length} session${group.sessions.length === 1 ? '' : 's'} · ${formatRelativeTime(group.timestamp)}`));
+            for (const session of group.sessions) {
+                console.log(treeSessionRow(session, liveIndex?.get(session.id)));
+                console.log(linkedSessionMeta(session));
+            }
+            console.log();
+        }
+    }
+    console.log(chalk.gray(`Run history from .history/runs/${drill.name}/ · resume a session with agents sessions resume <id>.`));
+    // Every listing path must say what it dropped (sessions.ts invariant). Under
+    // --routine team-origin sessions are shown (hiddenCount is 0), but unmanaged
+    // installs may still be hidden — surface both footers when non-zero.
+    if (opts.hiddenCount && opts.hiddenCount > 0)
+        console.log(chalk.gray(formatTeamHiddenFooter(opts.hiddenCount)));
+    if (opts.hiddenUnmanaged && opts.hiddenUnmanaged > 0)
+        console.log(chalk.gray(formatUnmanagedHiddenFooter(opts.hiddenUnmanaged)));
 }
 /** The canonical `ag sessions …` command for a set of flags — the twin of the
  * browser's `y` hotkey (see --print-cmd). Normalizes to the stable flag form. */
@@ -2550,15 +2756,36 @@ limitSource) {
             }
         }
         if (options.routine) {
-            const filteredByRoutine = await filterSessionsByRoutine(sessions, options.routine, isInteractive);
-            if (!filteredByRoutine)
-                return;
-            sessions = filteredByRoutine;
+            const target = await selectRoutineTarget(sessions, options.routine, isInteractive);
+            if (!target)
+                return; // bad --routine <name> or cancelled pick (message printed)
+            if (target.name) {
+                sessions = sessions.filter((s) => s.routineName === target.name);
+                // A routine browse renders the run-first drilldown — canonical run history
+                // plus each run's linked session — instead of dead-ending a
+                // command/pre-session routine into the generic empty copy. An explicit
+                // --flat/--tree or a search query keeps the scoped session listing/picker,
+                // so `--routine x --flat` prints the plain table and `--routine x <id>`
+                // resolves a specific session within the routine.
+                if (!searchQuery && !options.flat && !options.tree) {
+                    const liveIndex = await maybeLiveIndex(options);
+                    printRoutineDrilldown(buildRoutineDrilldown(target.name, sessions), liveIndex, { hiddenCount, hiddenUnmanaged });
+                    return;
+                }
+            }
+            // target.name === null: bare `--routine` piped to a non-interactive sink —
+            // no routine chosen, fall through to the normal listing unfiltered.
         }
         if (sessions.length === 0) {
             if (pathFilter) {
                 console.log(chalk.gray(`No sessions found for ${pathFilter}.`));
             }
+            else if (options.routine) {
+                // A routine scoped to a flat/tree/query listing with no matching session
+                // (e.g. a command routine has none) — say so in routine terms, not the
+                // generic cwd/--all copy, and point at the run-history drilldown.
+                console.log(chalk.gray('No indexed agent sessions for this routine. Drop --flat/--tree to see its run history.'));
+            }
             else {
                 console.log(chalk.gray(formatNoSessionsMessage(options.all, options.project)));
             }
@@ -2584,10 +2811,6 @@ limitSource) {
         // Interact/resume via `agents sessions <project>` or `agents sessions resume`.
         if (wantsOverview) {
             const liveIndex = await maybeLiveIndex(options);
-            if (options.routine) {
-                printRoutineRunOverview(sessions, liveIndex, { hiddenCount, hiddenUnmanaged });
-                return;
-            }
             // Per-project row cap is fixed (--limit carries a default of 50 and drives
             // the fetch pool, not the display); `--all` expands every group instead.
             printSessionOverview(sessions, hiddenCount, liveIndex, { perProjectCap: OVERVIEW_ROWS_PER_PROJECT, expand: !!options.all, hiddenUnmanaged });
@@ -2911,25 +3134,6 @@ function printSessionOverview(pool, hiddenCount, liveIndex, opts) {
     if (opts.hiddenUnmanaged)
         console.log(chalk.gray(formatUnmanagedHiddenFooter(opts.hiddenUnmanaged)));
 }
-export function printRoutineRunOverview(sessions, liveIndex, opts = {}) {
-    const groups = buildRoutineRunGroups(sessions);
-    console.log(chalk.gray(`${sessions.length} session${sessions.length === 1 ? '' : 's'} · ${groups.length} routine run${groups.length === 1 ? '' : 's'} · newest run first\n`));
-    let first = true;
-    for (const group of groups) {
-        if (!first)
-            console.log();
-        first = false;
-        console.log(`${chalk.cyan('▸')} ${chalk.cyan.bold(group.runId)}  ` +
-            `${chalk.gray(`${group.sessions.length} session${group.sessions.length === 1 ? '' : 's'} · ${formatRelativeTime(group.timestamp)}`)}`);
-        for (const session of group.sessions)
-            console.log(treeSessionRow(session, liveIndex?.get(session.id)));
-    }
-    console.log(chalk.gray('\nGrouped by routine run id and timestamp.'));
-    if (opts.hiddenCount)
-        console.log(chalk.gray(formatTeamHiddenFooter(opts.hiddenCount)));
-    if (opts.hiddenUnmanaged)
-        console.log(chalk.gray(formatUnmanagedHiddenFooter(opts.hiddenUnmanaged)));
-}
 function printSessionTable(sessions, hiddenCount = 0, tree = false, liveIndex) {
     if (tree) {
         // Group by directory; drop the id/version columns from view. The short id
@@ -4673,8 +4877,10 @@ export function registerSessionsCommands(program) {
     });
     sessionsCmd.action(async (query, options, command) => {
         if (options.browser) {
-            // Alias for `agents browser sessions`: a profile positional narrows to one profile.
-            runBrowserSessions({ profile: query, json: options.json });
+            // Alias for `agents browser sessions`: a profile positional narrows to one
+            // profile. `--no-interactive` is already a top-level sessionsCmd option
+            // (options.interactive), so it carries through for free.
+            await runBrowserSessionsCommand({ profile: query, json: options.json, interactive: options.interactive });
             return;
         }
         await sessionsAction(query, options, command.getOptionValueSource('limit'));

package/dist/commands/ssh.js

@@ -28,6 +28,7 @@ import { DEFAULT_SERVE_PORT } from '../lib/serve/server.js';
 import { nodeToDeviceInput, parseTailscaleStatus, tailscaleStatusJson, } from '../lib/devices/tailscale.js';
 import { defaultPickerChecked, localLoginUser, planDeviceReconciliation, runDeviceSync, withDefaultUser } from '../lib/devices/sync.js';
 import { resolveDeviceTarget, splitUserHost } from '../lib/devices/resolve-target.js';
+import { deriveMirroredCwd } from '../lib/project-root.js';
 import { clearPendingSentinel } from '../lib/devices/pending.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { hostNameFor, renderSshConfig } from '../lib/devices/ssh-config.js';
@@ -1598,15 +1599,21 @@ function registerSshWrapper(program) {
         .allowUnknownOption()
         .addHelpText('after', `
 Examples:
-  agents ssh win-mini                       # interactive login
-  agents ssh win-mini hostname              # run a command (PowerShell on Windows)
-  agents ssh yosemite-s0 uptime             # run a command (POSIX)
-  agents ssh auto                           # affinity-pick a device (same engine as 'agents run --device auto')
+  agents ssh yosemite-s0                     # interactive login (mirrors your project dir)
+  agents ssh win-mini                        # interactive login
+  agents ssh win-mini hostname               # run a command (PowerShell on Windows)
+  agents ssh yosemite-s0 uptime              # run a command (POSIX)
+  agents ssh auto                            # affinity-pick a device (same engine as 'agents run --device auto')
 
 Devices come from 'agents devices'. Password auth pulls the secret from a
 secrets bundle via an askpass shim — the password never touches argv.
 'auto' picks a remote device by 14-day usage; a pick landing on this machine
 is refused with a clear message instead of self-dialing.
+
+An interactive login with no command mirrors the home-relative directory you
+launched from — 'agents ssh yosemite-s0' from ~/src/app lands in ~/src/app on
+the target when it exists, else the remote home. Same portable-cwd rule as
+'agents run --host'. Passing a command keeps the remote home.
 `)
         .action(async (name, cmd) => {
         // Hidden askpass bridge: ssh execs the shim, which re-invokes us here.
@@ -1664,7 +1671,12 @@ is refused with a clear message instead of self-dialing.
             ensureManagedKnownHostsDir();
             const addr = hostNameFor(device);
             const pinned = addr ? isHostPinned(addr) : false;
-            const { args, env } = buildSshInvocation(device, cmd, shim, { pinned });
+            // Interactive login (no cmd): mirror the caller's project directory on
+            // the target when the same home-relative checkout exists there, matching
+            // `agents run --host` (deriveMirroredCwd). Best-effort — a missing dir
+            // falls back to the remote home. An explicit `cmd` keeps its cwd (RUSH-2412).
+            const mirrorCwd = cmd.length === 0 ? deriveMirroredCwd(process.cwd()) : undefined;
+            const { args, env } = buildSshInvocation(device, cmd, shim, { pinned }, { interactiveCwd: mirrorCwd });
             // Interactive login: make the local terminal's terminfo (e.g.
             // xterm-ghostty) available on the remote so backspace/colors/clear work.
             // Best-effort + cached per host — never blocks the login (see terminfo.ts).

package/dist/commands/teams.d.ts

@@ -59,6 +59,34 @@ export type TeamMessageRoute = {
  *   - any actionable + no message   -> need-message
  */
 export declare function decideTeamMessageRoute(status: AgentStatus, hasMessage: boolean): TeamMessageRoute;
+/**
+ * Tell the user a worktree from a failed `teams add` is still on disk, and give
+ * them the exact commands to remove it. Reached only when we could not remove it
+ * ourselves — a leftover `agents/<name>` branch is what makes the retry fail with
+ * `fatal: a branch ... already exists`, so it must never be silent (RUSH-2356).
+ */
+/**
+ * Tear down a worktree a failed operation left behind — but ONLY if it is a
+ * genuine orphan.
+ *
+ * Extracted because this guard was hand-duplicated at two call sites (`teams
+ * add` and the pr-watch fixer) and the copy at the fixer path was written
+ * WITHOUT it, which is RUSH-2356 reoccurring at the one site that skipped the
+ * check. One implementation, one place to get it right.
+ *
+ * The two errors here are not symmetric, so the guard deliberately fails
+ * CLOSED: a spurious "claimed" strands a branch a human can delete, while a
+ * spurious "unclaimed" runs `git worktree remove --force` over a live
+ * teammate's checkout and destroys uncommitted work. So an unreadable record
+ * means "leave it alone and tell the user", never "assume it is free".
+ *
+ * A staged teammate is exactly the case that makes this necessary: `spawn()`
+ * persists its meta.json and only THEN runs the retention pass, which refreshes
+ * every sibling and can throw on a distributed one — so a failure can land here
+ * with a live, durably-recorded, merely-pending `--after` teammate already
+ * owning this worktree.
+ */
+export declare function tearDownOrphanWorktree(mgr: AgentManager, baseCwd: string, name: string): Promise<void>;
 /**
  * Register the generic cloud dispatcher — staged cloud teammates get
  * dispatched when their --after deps resolve, using repo/branch stored on