@shanesaravia/hive 0.1.1 → 0.2.1

package/packages/server/dist/roster/rosterBuilder.js

@@ -19,6 +19,7 @@ function resultText(job) {
 }
 /** Joins Claude's short-lived jobs into durable, Hive-managed missions. */
 export function buildFleetSnapshot(sessions, jobs, events, missions, messageStore, planStore, now = Date.now()) {
+    const workerCorrelationGraceMs = 8_000;
     const orchestrators = [];
     const other = [];
     const sessionsByJob = new Map();
@@ -51,6 +52,51 @@ export function buildFleetSnapshot(sessions, jobs, events, missions, messageStor
         group.push({ jobId, job });
         groups.set(missionId, group);
     }
+    // Per-mission pending decisions. Used both for the global inbox and, inside the
+    // mission loop, to keep a mission reading as waiting_on_you for as long as a
+    // decision is unanswered — even after the provider session record has gone
+    // quiet — so the office lighting, desk, status pill, and "?" badge agree.
+    const pendingDecisionsFor = (node) => {
+        if (node.lifecycleStatus === "completed" || node.lifecycleStatus === "archived")
+            return [];
+        const resolved = new Set(node.recentEvents.filter((event) => event.phase === "decision_resolved" && event.decisionId).map((event) => event.decisionId));
+        const missionContext = { missionObjective: node.mission.objective || undefined, repository: node.mission.repository };
+        // Only the current, mid-turn blocker belongs in the decision inbox. An
+        // unresolved event from an older/completed turn is history: the mission
+        // may remain open for optional follow-up, but it is not waiting on the
+        // user. Requiring the blocker to be the latest observed event also clears
+        // it as soon as provider activity resumes.
+        const latestEvent = node.recentEvents.at(-1);
+        const fromEvents = !node.turnCompleted && latestEvent?.phase === "blocked_on_user"
+            && latestEvent.decisionId && !resolved.has(latestEvent.decisionId)
+            && (!latestEvent.jobId || latestEvent.jobId === node.jobId)
+            ? [{
+                    id: latestEvent.decisionId, missionId: node.missionId, missionName: node.name,
+                    kind: latestEvent.decisionKind ?? "question", question: latestEvent.detail, context: latestEvent.context,
+                    choices: latestEvent.choices ?? [], recommendation: latestEvent.recommendation, impact: latestEvent.impact, createdAt: latestEvent.ts, ...missionContext,
+                }]
+            : [];
+        // A permission prompt parks the session mid-turn (tempo blocked, the ask
+        // in needs) with no TTY to answer it — surface it as an answerable
+        // decision. It self-clears once the job is no longer parked.
+        const latestJob = jobs.get(node.jobId);
+        const parked = !node.turnCompleted && latestJob?.tempo === "blocked" && latestJob.needs && /^approve\s/i.test(latestJob.needs) && !resolved.has(`perm:${node.jobId}`)
+            ? [{
+                    id: `perm:${node.jobId}`, missionId: node.missionId, missionName: node.name,
+                    kind: "permission", question: latestJob.needs, context: latestJob.detail,
+                    choices: ["Approve & continue", "Deny"], impact: "The session is parked at this prompt until you answer.", createdAt: node.updatedAt, ...missionContext,
+                }]
+            : [];
+        const hasStructuredPrompt = node.recentEvents.some((event) => event.jobId === node.jobId && event.phase === "blocked_on_user" && event.decisionId?.startsWith("skill-prompt:"));
+        const providerPrompt = !node.turnCompleted && latestJob?.tempo === "blocked" && latestJob.needs && (latestJob.promptChoices?.length ?? 0) > 0 && !/^approve\s/i.test(latestJob.needs) && !/rate limit|spend limit/i.test(latestJob.needs) && !hasStructuredPrompt && !resolved.has(`prompt:${node.jobId}`)
+            ? [{
+                    id: `prompt:${node.jobId}`, missionId: node.missionId, missionName: node.name,
+                    kind: "question", question: latestJob.needs, context: latestJob.detail,
+                    choices: latestJob.promptChoices ?? [], impact: "The provider is waiting for this answer before the skill can continue.", createdAt: node.updatedAt, ...missionContext,
+                }]
+            : [];
+        return [...fromEvents, ...parked, ...providerPrompt];
+    };
     for (const [missionId, group] of groups) {
         group.sort((a, b) => dateMs(a.job.createdAt) - dateMs(b.job.createdAt));
         const latest = group[group.length - 1];
@@ -73,28 +119,163 @@ export function buildFleetSnapshot(sessions, jobs, events, missions, messageStor
             eventIds.add(jobId);
         if (session)
             eventIds.add(session.sessionId);
-        const recentEvents = [...new Map([...eventIds]
-                .flatMap((id) => events.recentFor(id))
+        const allEvents = [...new Map([...eventIds]
+                .flatMap((id) => events.recentFor(id, 200))
                 .map((event) => [`${event.sessionId}:${event.jobId ?? ""}:${event.ts}:${event.phase}:${event.decisionId ?? ""}:${event.targetWorker ?? ""}:${event.detail}`, event])).values()]
-            .sort((a, b) => a.ts - b.ts)
-            .slice(-100);
-        const derived = deriveStatus(session, latest.job, recentEvents);
-        const workers = group.flatMap(({ jobId, job }) => (job.fan ?? []).map((worker) => ({
+            .sort((a, b) => a.ts - b.ts);
+        let recentEvents = allEvents.slice(-100);
+        let workers = group.flatMap(({ jobId, job }) => (job.fan ?? []).filter((worker) => worker.kind === "agent" || worker.kind === "subagent").map((worker) => ({
             ...worker,
             jobId,
             jobState: job.state,
             jobUpdatedAt: dateMs(job.updatedAt) || undefined,
         })));
+        const jobIdBySession = new Map(group.flatMap(({ jobId, job }) => {
+            const linkedSession = sessionsByJob.get(jobId);
+            return [...(job.sessionId ? [[job.sessionId, jobId]] : []), ...(linkedSession ? [[linkedSession.sessionId, jobId]] : [])];
+        }));
+        const jobStateById = new Map(group.map(({ jobId, job }) => [jobId, job.state]));
+        const parentTurnFinished = (jobId) => ["done", "completed", "failed", "error", "cancelled", "canceled", "stopped"].includes((jobStateById.get(jobId) ?? "").toLowerCase());
+        const eventJobId = (event) => event.jobId ?? jobIdBySession.get(event.sessionId);
+        // A job's fan array is only a current view and can drop an earlier worker
+        // as soon as a later worker starts. Rebuild the durable native roster from
+        // hook history, keyed by Claude's real agent id, and merge fan metadata.
+        const nativeEvidence = new Map();
+        for (const event of allEvents) {
+            const resolvedJobId = eventJobId(event);
+            const raw = event.rawPayload && typeof event.rawPayload === "object" ? event.rawPayload : {};
+            const response = raw.tool_response && typeof raw.tool_response === "object" ? raw.tool_response : {};
+            const input = raw.tool_input && typeof raw.tool_input === "object" ? raw.tool_input : {};
+            const launchId = typeof response.agentId === "string" ? response.agentId : typeof response.agent_id === "string" ? response.agent_id : undefined;
+            const nativeId = launchId ?? event.targetWorker;
+            if (!resolvedJobId || !nativeId || nativeId === "hive-orchestrator")
+                continue;
+            const isStart = event.hookEventName === "SubagentStart" || (event.hookEventName === "PostToolUse" && event.toolName === "Agent" && Boolean(launchId));
+            const isStop = event.hookEventName === "SubagentStop";
+            if (!isStart && !isStop)
+                continue;
+            const label = typeof response.description === "string" ? response.description : typeof input.description === "string" ? input.description : nativeId;
+            const key = `${resolvedJobId}:${nativeId}`;
+            const prior = nativeEvidence.get(key);
+            // A stop without any observed launch is often a nested/background task
+            // notification. It is evidence, but not enough to invent a person.
+            if (isStop && !prior)
+                continue;
+            nativeEvidence.set(key, {
+                id: nativeId,
+                jobId: resolvedJobId,
+                label: prior?.label !== prior?.id ? prior.label : label,
+                startedAt: Math.min(prior?.startedAt ?? event.ts, event.ts),
+                doneAt: isStop ? event.ts : isStart ? undefined : prior?.doneAt,
+                updatedAt: event.ts,
+                running: isStart,
+            });
+        }
+        const workerByNativeKey = new Map(workers.map((worker) => [`${worker.jobId}:${worker.id}`, worker]));
+        for (const native of nativeEvidence.values()) {
+            const key = `${native.jobId}:${native.id}`;
+            const fanWorker = workerByNativeKey.get(key);
+            const turnFinished = parentTurnFinished(native.jobId);
+            // SubagentStop is the worker's own terminal lifecycle boundary. The
+            // manager may remain idle/open for follow-up, but that must not keep a
+            // finished worker seated indefinitely. A later SubagentStart for the
+            // same native id clears native.doneAt above and resumes that person.
+            const workerFinished = Boolean(native.doneAt) || turnFinished;
+            const merged = fanWorker ? {
+                ...fanWorker,
+                label: fanWorker.label || native.label,
+                startedAt: Math.min(fanWorker.startedAt, native.startedAt),
+                doneAt: native.doneAt ?? (turnFinished ? fanWorker.doneAt : undefined),
+                updatedAt: Math.max(fanWorker.updatedAt ?? 0, native.updatedAt),
+                jobState: workerFinished ? "done" : native.running ? "working" : "idle",
+            } : {
+                id: native.id,
+                kind: "agent",
+                label: native.label,
+                startedAt: native.startedAt,
+                doneAt: native.doneAt,
+                updatedAt: native.updatedAt,
+                jobId: native.jobId,
+                jobState: workerFinished ? "done" : native.running ? "working" : "idle",
+            };
+            workerByNativeKey.set(key, merged);
+        }
+        workers = [...workerByNativeKey.values()];
+        // A resumed/follow-up job may address the same provider-native agent id.
+        // The mission roster is person-oriented, so expose that id once using its
+        // latest lifecycle state instead of creating duplicate React/desk actors
+        // for each short-lived parent job.
+        const workersByIdentity = new Map();
+        for (const worker of workers.sort((a, b) => a.startedAt - b.startedAt || a.id.localeCompare(b.id))) {
+            const prior = workersByIdentity.get(worker.id);
+            if (!prior) {
+                workersByIdentity.set(worker.id, worker);
+                continue;
+            }
+            const priorFreshness = prior.updatedAt ?? prior.doneAt ?? prior.startedAt;
+            const workerFreshness = worker.updatedAt ?? worker.doneAt ?? worker.startedAt;
+            const latest = workerFreshness >= priorFreshness ? worker : prior;
+            workersByIdentity.set(worker.id, {
+                ...latest,
+                label: latest.label || prior.label,
+                startedAt: Math.min(prior.startedAt, worker.startedAt),
+            });
+        }
+        workers = [...workersByIdentity.values()];
+        // Friendly/custom worker names are presentation aliases only. Native
+        // Claude ids remain canonical so close or repeated delegations can never
+        // swap React identities or manufacture an extra avatar.
+        const workerAliases = new Map();
+        const claimedNativeWorkers = new Set();
+        for (const event of allEvents.filter((candidate) => candidate.source === "custom" && candidate.phase === "delegating" && candidate.targetWorker)) {
+            const resolvedJobId = eventJobId(event);
+            if (!resolvedJobId)
+                continue;
+            const aliasKey = `${resolvedJobId}:${event.targetWorker}`;
+            const candidate = workers
+                .filter((worker) => worker.jobId === resolvedJobId && !claimedNativeWorkers.has(worker.id) && Math.abs(worker.startedAt - event.ts) <= 30_000)
+                .sort((a, b) => Math.abs(a.startedAt - event.ts) - Math.abs(b.startedAt - event.ts))[0];
+            workerAliases.set(aliasKey, candidate?.id ?? aliasKey);
+            if (!candidate)
+                continue;
+            claimedNativeWorkers.add(candidate.id);
+        }
+        if (workerAliases.size)
+            recentEvents = recentEvents.map((event) => {
+                if (!event.targetWorker)
+                    return event;
+                const resolvedJobId = eventJobId(event);
+                if (!resolvedJobId)
+                    return event;
+                const key = `${resolvedJobId}:${event.targetWorker}`;
+                const targetWorker = workerAliases.get(key);
+                return targetWorker ? { ...event, targetWorker } : event;
+            });
+        // Claude's fan file can arrive just before its delegation hook. Publishing
+        // that unmatched native id for a single poll makes the office animate a
+        // second person. Hold it briefly for correlation; canonical/event-backed
+        // workers remain immediate, and hookless workers appear after the grace.
+        const correlatedWorkerIds = new Set(recentEvents.filter((event) => event.source === "custom" && event.phase === "delegating").map((event) => event.targetWorker).filter((id) => Boolean(id)));
+        workers = workers.filter((worker) => nativeEvidence.has(`${worker.jobId}:${worker.id}`) || correlatedWorkerIds.has(worker.id) || now - worker.startedAt >= workerCorrelationGraceMs);
+        const derived = deriveStatus(session, latest.job, recentEvents, now);
         const workerIds = new Set(workers.map((worker) => worker.id));
         for (const event of recentEvents) {
             if (!event.targetWorker || workerIds.has(event.targetWorker))
                 continue;
             const related = recentEvents.filter((candidate) => candidate.targetWorker === event.targetWorker);
-            const start = related.find((candidate) => candidate.phase === "delegating" || candidate.phase?.toLowerCase().includes("subagentstart"));
+            const start = related.find((candidate) => candidate.phase === "delegating" || candidate.phase?.toLowerCase().includes("subagentstart") || candidate.hookEventName?.toLowerCase() === "subagentstart");
             if (!start)
                 continue;
-            const done = [...related].reverse().find((candidate) => candidate.phase === "worker_reported" || candidate.phase?.toLowerCase().includes("subagentstop"));
-            workers.push({ id: event.targetWorker, label: event.targetWorker, kind: "subagent", startedAt: start.ts, doneAt: done?.ts, updatedAt: related.at(-1)?.ts, jobId: event.jobId ?? latest.jobId, jobState: done ? "done" : latest.job.state });
+            // A friendly delegation target is an alias, not a person. Hold every
+            // unmatched identity through the correlation window; a native Agent id
+            // normally arrives within milliseconds and becomes the sole actor.
+            if (now - start.ts < workerCorrelationGraceMs)
+                continue;
+            const done = [...related].reverse().find((candidate) => candidate.phase === "worker_reported" || candidate.phase?.toLowerCase().includes("subagentstop") || candidate.hookEventName?.toLowerCase() === "subagentstop");
+            const resolvedJobId = eventJobId(event);
+            if (!resolvedJobId)
+                continue;
+            workers.push({ id: event.targetWorker, label: event.targetWorker, kind: "subagent", startedAt: start.ts, doneAt: done?.ts, updatedAt: related.at(-1)?.ts, jobId: resolvedJobId, jobState: done ? "done" : latest.job.state });
             workerIds.add(event.targetWorker);
         }
         const derivedMessages = group.flatMap(({ jobId, job }) => {
@@ -141,7 +322,15 @@ export function buildFleetSnapshot(sessions, jobs, events, missions, messageStor
         const missionPlan = planStore?.get(missionId);
         const inactiveForMs = Math.max(0, now - updatedAt);
         let activityStatus = derived.status;
-        if (mission.lifecycleStatus !== "active" && !session) {
+        if (mission.lifecycleStatus === "completed" || mission.lifecycleStatus === "archived") {
+            // Durable terminal lifecycle is authoritative over a stale provider ask,
+            // parked permission, or process record left behind by the final turn.
+            activityStatus = "done";
+        }
+        else if (mission.lifecycleStatus === "failed") {
+            activityStatus = "error";
+        }
+        else if (mission.lifecycleStatus !== "active" && !session) {
             activityStatus = "offline";
         }
         else if (mission.lifecycleStatus === "active") {
@@ -154,8 +343,15 @@ export function buildFleetSnapshot(sessions, jobs, events, missions, messageStor
                 activityStatus = "stalled";
             }
         }
+        const name = missions?.nameFor(missionId) ?? oldest.job.name ?? latest.job.name ?? missionId;
+        const turnCompleted = latest.job.state === "done";
+        const pendingDecisions = pendingDecisionsFor({ missionId, name, jobId: latest.jobId, mission, lifecycleStatus: mission.lifecycleStatus, turnCompleted, recentEvents, updatedAt });
+        // An unanswered decision is, by definition, waiting on the user. Do not let the
+        // runtime's quiet session decay it to idle/stalled while the question stands.
+        if (mission.lifecycleStatus === "active" && pendingDecisions.length && (activityStatus === "idle" || activityStatus === "stalled"))
+            activityStatus = "waiting_on_you";
         const runStartedAt = dateMs(latest.job.createdAt) || createdAt;
-        const alerts = deriveAlerts({ lifecycle: mission.lifecycleStatus, activity: activityStatus, stale: derived.stale, turnCompleted: latest.job.state === "done", workers, events: recentEvents, now, turnTokens: latest.job.tokens ?? 0, runStartedAt });
+        const alerts = deriveAlerts({ lifecycle: mission.lifecycleStatus, activity: activityStatus, stale: derived.stale, turnCompleted, workers, events: recentEvents, now, turnTokens: latest.job.tokens ?? 0, runStartedAt });
         orchestrators.push({
             missionId,
             threadId: missionId,
@@ -168,16 +364,13 @@ export function buildFleetSnapshot(sessions, jobs, events, missions, messageStor
                 latest.job.resumeSessionId ??
                 latest.jobId,
             pid: session?.pid ?? -1,
-            name: missions?.nameFor(missionId) ??
-                oldest.job.name ??
-                latest.job.name ??
-                missionId,
+            name,
             status: activityStatus,
             lifecycleStatus: mission.lifecycleStatus,
             activityStatus,
-            turnCompleted: latest.job.state === "done",
+            turnCompleted,
             inactiveForMs,
-            waitingFor: session?.waitingFor ?? latest.job.needs,
+            waitingFor: mission.lifecycleStatus === "completed" || mission.lifecycleStatus === "archived" ? undefined : session?.waitingFor ?? latest.job.needs,
             worktreePath: latest.job.worktreePath ?? oldest.job.worktreePath,
             worktreeBranch: latest.job.worktreeBranch ?? oldest.job.worktreeBranch,
             tokens: group.reduce((total, { job }) => total + (job.tokens ?? 0), 0),
@@ -203,7 +396,7 @@ export function buildFleetSnapshot(sessions, jobs, events, missions, messageStor
             continue;
         const jobEntry = session.jobId ? jobs.get(session.jobId) : undefined;
         const recentEvents = events.recentFor(session.sessionId);
-        const { status } = deriveStatus(session, jobEntry, recentEvents);
+        const { status } = deriveStatus(session, jobEntry, recentEvents, now);
         other.push({
             jobId: session.jobId,
             sessionId: session.sessionId,
@@ -218,26 +411,6 @@ export function buildFleetSnapshot(sessions, jobs, events, missions, messageStor
         });
     }
     orchestrators.sort((a, b) => b.updatedAt - a.updatedAt);
-    const decisions = orchestrators.flatMap((node) => {
-        const resolved = new Set(node.recentEvents.filter((event) => event.phase === "decision_resolved" && event.decisionId).map((event) => event.decisionId));
-        const missionContext = { missionObjective: node.mission.objective || undefined, repository: node.mission.repository };
-        const fromEvents = node.recentEvents.filter((event) => event.phase === "blocked_on_user" && event.decisionId && !resolved.has(event.decisionId)).map((event) => ({
-            id: event.decisionId, missionId: node.missionId, missionName: node.name,
-            kind: event.decisionKind ?? "question", question: event.detail, context: event.context,
-            choices: event.choices ?? [], recommendation: event.recommendation, impact: event.impact, createdAt: event.ts, ...missionContext,
-        }));
-        // A permission prompt parks the session mid-turn (tempo blocked, the ask
-        // in needs) with no TTY to answer it — surface it as an answerable
-        // decision. It self-clears once the job is no longer parked.
-        const latestJob = jobs.get(node.jobId);
-        const parked = latestJob?.tempo === "blocked" && latestJob.needs && /^approve\s/i.test(latestJob.needs) && !resolved.has(`perm:${node.jobId}`)
-            ? [{
-                    id: `perm:${node.jobId}`, missionId: node.missionId, missionName: node.name,
-                    kind: "permission", question: latestJob.needs, context: latestJob.detail,
-                    choices: ["Approve & continue", "Deny"], impact: "The session is parked at this prompt until you answer.", createdAt: node.updatedAt, ...missionContext,
-                }]
-            : [];
-        return [...fromEvents, ...parked];
-    }).sort((a, b) => b.createdAt - a.createdAt);
+    const decisions = orchestrators.flatMap((node) => pendingDecisionsFor(node)).sort((a, b) => b.createdAt - a.createdAt);
     return { orchestrators, decisions, other, generatedAt: Date.now() };
 }

package/packages/server/dist/skills/skillDiscovery.js

@@ -50,17 +50,19 @@ function collectPluginSkills(root) {
     }
     return output;
 }
-export function discoverSkills(cwd) {
+export function discoverSkills(cwd, provider = "claude") {
     const project = requireWorkingDirectory(cwd);
-    const all = [
+    const claudeConfig = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
+    const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+    const all = provider === "codex" ? [
+        ...collect(path.join(project, ".codex", "skills"), "project"),
+        ...collect(path.join(codexHome, "skills"), "user"),
+        ...collectPluginSkills(path.join(codexHome, "plugins", "cache")),
+    ] : [
         ...collect(path.join(project, ".claude", "skills"), "project"),
         ...collect(path.join(project, ".claude", "commands"), "project"),
-        ...collect(path.join(os.homedir(), ".claude", "skills"), "user"),
-        ...collect(path.join(os.homedir(), ".claude", "commands"), "user"),
-        ...collectPluginSkills(path.join(os.homedir(), ".claude", "plugins")),
-        ...collect(path.join(project, ".codex", "skills"), "project"),
-        ...collect(path.join(os.homedir(), ".codex", "skills"), "user"),
-        ...collectPluginSkills(path.join(os.homedir(), ".codex", "plugins", "cache")),
+        ...collect(path.join(claudeConfig, "skills"), "user"),
+        ...collect(path.join(claudeConfig, "commands"), "user"),
     ];
     const unique = new Map();
     for (const skill of all.reverse())

package/packages/server/dist/skills/skillInvocation.js

@@ -0,0 +1,11 @@
+/**
+ * Hive exposes one consistent `/skill` syntax in its UI. Codex invokes skills
+ * with `$skill`, so translate only names that were discovered for the active
+ * provider, machine, and working directory. Unknown slash-prefixed text is
+ * left alone (it may be a path or ordinary prose).
+ */
+export function translateSkillInvocations(text, provider, availableSkillNames) {
+    if (provider !== "codex" || availableSkillNames.size === 0)
+        return text;
+    return text.replace(/(^|\s)\/([a-zA-Z0-9][a-zA-Z0-9:_-]*)(?=\s|$)/g, (match, prefix, name) => availableSkillNames.has(name) ? `${prefix}$${name}` : match);
+}

package/packages/server/dist/worktrees/worktreeReclaim.js

@@ -0,0 +1,156 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Hive launches missions through the provider CLI's native `--worktree`
+ * primitive (see control/launcher.ts) but nothing ever reclaimed the result,
+ * so every templated mission leaked a checked-out worktree and a branch.
+ *
+ * Reclamation is deliberately scoped to worktrees Hive itself caused to
+ * exist: the CLI creates them under `<repo>/.claude/worktrees/<name>` on a
+ * `worktree-<name>` branch. Anything outside that layout is left alone, so a
+ * stale or wrong `worktreePath` on a job record can never delete a real
+ * checkout.
+ */
+/** Path segment the provider CLI uses for its managed worktrees. */
+const MANAGED_SEGMENT = path.join(".claude", "worktrees");
+function git(cwd, args) {
+    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+/**
+ * git may answer --git-common-dir with either an absolute or a
+ * repository-relative path depending on where it runs, and resolving a
+ * relative answer against the wrong base silently yields a bogus path.
+ * --path-format is authoritative where available (git 2.31+).
+ */
+function commonGitDir(cwd) {
+    try {
+        return git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
+    }
+    catch {
+        return path.resolve(cwd, git(cwd, ["rev-parse", "--git-common-dir"]));
+    }
+}
+/**
+ * A managed worktree lives under `.claude/worktrees/` AND reports a git common
+ * directory different from its own git dir. Both checks matter: the path shape
+ * alone would trust unverified job metadata, and the git check alone would
+ * happily remove a worktree the user created by hand somewhere else.
+ */
+export function isManagedWorktree(worktreePath) {
+    if (!worktreePath.includes(MANAGED_SEGMENT))
+        return false;
+    let gitEntry;
+    try {
+        gitEntry = fs.statSync(path.join(worktreePath, ".git"));
+    }
+    catch {
+        return false;
+    }
+    // A linked worktree records its git directory in a `.git` FILE; a main
+    // checkout has a `.git` DIRECTORY. That distinction is what stops a real
+    // repository from ever being reclaimed, and unlike comparing
+    // --git-dir against --git-common-dir it cannot be fooled by git mixing
+    // absolute and relative path output for a nested directory.
+    if (!gitEntry.isFile())
+        return false;
+    try {
+        return git(worktreePath, ["rev-parse", "--is-inside-work-tree"]) === "true";
+    }
+    catch {
+        return false;
+    }
+}
+/** Uncommitted tracked or untracked changes in the worktree. */
+export function isWorktreeDirty(worktreePath) {
+    try {
+        return git(worktreePath, ["status", "--porcelain"]).length > 0;
+    }
+    catch {
+        // Unreadable means unverifiable, and unverifiable must not be discarded.
+        return true;
+    }
+}
+/**
+ * `completed` is reversible — a follow-up message implicitly reopens a
+ * completed mission (see rest.ts), and "Clear completed desks" completes many
+ * missions at once — so uncommitted work survives it. `deleted` and `archived`
+ * are explicit, per-mission, terminal gestures and reclaim unconditionally.
+ */
+function discardsUncommittedWork(trigger) {
+    return trigger !== "completed";
+}
+/**
+ * Removes a mission's worktree and its branch. Safe to call for any mission:
+ * missions without a worktree, and worktrees already gone, report "absent".
+ */
+export function reclaimWorktree(target, trigger) {
+    const worktreePath = target.path;
+    if (!worktreePath)
+        return { status: "absent" };
+    if (!fs.existsSync(worktreePath))
+        return { status: "absent", path: worktreePath, branch: target.branch };
+    if (!isManagedWorktree(worktreePath)) {
+        return { status: "unmanaged", path: worktreePath, branch: target.branch, detail: "not a Hive-managed worktree" };
+    }
+    if (!discardsUncommittedWork(trigger) && isWorktreeDirty(worktreePath)) {
+        return { status: "kept_dirty", path: worktreePath, branch: target.branch, detail: "uncommitted changes preserved" };
+    }
+    // The main checkout owns the worktree administrative data, so removal and
+    // branch deletion must run from the common repository, not from inside the
+    // directory being deleted.
+    let repositoryRoot;
+    try {
+        repositoryRoot = path.dirname(commonGitDir(worktreePath));
+    }
+    catch (error) {
+        return { status: "failed", path: worktreePath, branch: target.branch, detail: error.message };
+    }
+    try {
+        // Locked worktrees are Hive's own (the CLI locks some during launch);
+        // unlock is a no-op when the worktree was never locked.
+        try {
+            git(repositoryRoot, ["worktree", "unlock", worktreePath]);
+        }
+        catch { /* not locked */ }
+        git(repositoryRoot, ["worktree", "remove", "--force", worktreePath]);
+    }
+    catch (error) {
+        return { status: "failed", path: worktreePath, branch: target.branch, detail: error.message };
+    }
+    let detail;
+    if (target.branch) {
+        const branch = target.branch.replace(/^refs\/heads\//, "");
+        try {
+            // -D rather than -d: the branch was just verified to hold no
+            // uncommitted work, and an unmerged experiment branch is exactly what
+            // this reclaim is meant to collect. The commits stay in the reflog.
+            git(repositoryRoot, ["branch", "-D", branch]);
+        }
+        catch {
+            detail = `worktree removed; branch ${branch} retained`;
+        }
+    }
+    try {
+        git(repositoryRoot, ["worktree", "prune"]);
+    }
+    catch { /* best effort */ }
+    return { status: "removed", path: worktreePath, branch: target.branch, detail };
+}
+/** Human-readable line for the mission activity timeline. */
+export function reclaimEventDetail(result, trigger) {
+    const name = result.path ? path.basename(result.path) : "worktree";
+    if (result.status === "removed") {
+        return `Worktree ${name} reclaimed after mission ${trigger}${result.detail ? ` · ${result.detail}` : ""}`;
+    }
+    if (result.status === "kept_dirty") {
+        return `Worktree ${name} kept: uncommitted changes remain after mission ${trigger}`;
+    }
+    if (result.status === "failed") {
+        return `Worktree ${name} could not be reclaimed: ${result.detail ?? "git error"}`;
+    }
+    if (result.status === "unmanaged") {
+        return `Worktree ${name} left in place: not a Hive-managed worktree`;
+    }
+    return undefined;
+}