@cmgmyr/hive 1.11.8 → 1.12.0

package/README.md

@@ -57,7 +57,7 @@ hive is a personal daily-driver tool, released low-key. It is single-user by des
 
 | Page | What's there |
 |---|---|
-| [Architecture](docs/architecture.md) | Seven diagrams: process topology, module layering, spawn sequence, wake lifecycle, worker state, project scoping, store and server identity |
+| [Architecture](docs/architecture.md) | Eight diagrams: process topology, module layering, spawn sequence, wake lifecycle, worker state (with the lead handoff), project scoping, store and server identity |
 | [Patterns](docs/patterns.md) | Standing trades, refused approaches, evidence standards, and guard shapes distilled from the project's own decisions and dead-ends |
 | [Concepts](docs/concepts.md) | Vocabulary, why not subagents, identity, the workflow, project scope, the shared store |
 | [Daily driver](docs/daily-driver.md) | A day with hive, starting a session, watching workers, wake-ups |

package/claude-plugin/README.md

@@ -51,4 +51,4 @@ path is ever written into a committed file.
 
 ## The crew mod
 
-`crew/` is a second, separate plugin (`hive-crew`) that `hive lead` loads with `--plugin-dir` only when `lead_sidebar: true` is set and the lead is Claude. It is not part of the symlink install above and workers never load it. See [docs/crew.md](../docs/crew.md).
+`crew/` is a second, separate plugin (`hive-crew`) that `hive lead` loads with `--plugin-dir` for Claude leads by default. Set `lead_sidebar: false` to disable it. It is not part of the symlink install above and workers never load it. See [docs/crew.md](../docs/crew.md).

package/dist/agentResume.js

@@ -0,0 +1,222 @@
+import { existsSync } from "node:fs";
+import { db } from "./db.js";
+import { getAgentRow } from "./agentRecords.js";
+import { getProject } from "./context.js";
+import { workerCommandString } from "./brief.js";
+import { codexHomeDir, codexLaunchArgs, ensureCodexHooksFile, refreshCodexMcpEnv, } from "./codexHome.js";
+import { agentIdentityEnv, branchAt, LEAD_KIND, resumeAgent, storedLaunchOptions } from "./spawn.js";
+import { ensureWorkerHooksFile } from "./hooks.js";
+import { harnessFor, resolvedCommandPrefix } from "./harnesses.js";
+import { loadProjectYml } from "./projectYml.js";
+import { limitedHarness, observeProjectUsageLimits } from "./usageLimit.js";
+import { DEFAULT_LAYOUT } from "./tmux.js";
+export function refuseLimitedHarness(projectId, harness, action = "agent_spawn") {
+    const now = Date.now();
+    observeProjectUsageLimits(projectId, harness, now);
+    const held = limitedHarness(projectId, harness, now);
+    if (held) {
+        throw new Error(`[${action}:usage-limit] ${harness} is stopped by a usage limit until ${held.until}. ` +
+            `This ${action === "agent_resume" ? "resume" : action === "agent_fork" ? "fork" : "spawn"} was not queued; retry it after that time.`);
+    }
+}
+export function contextCheckpointEnv(config) {
+    const value = config?.context_checkpoint_percent;
+    return value == null ? {} : { HIVE_CONTEXT_CHECKPOINT_PERCENT: String(value) };
+}
+function commandTokens(command) {
+    const tokens = [];
+    let token = "";
+    let quote = null;
+    let escaped = false;
+    for (const char of command) {
+        if (escaped) {
+            token += char;
+            escaped = false;
+        }
+        else if (char === "\\" && quote !== "'") {
+            escaped = true;
+        }
+        else if (quote) {
+            if (char === quote)
+                quote = null;
+            else
+                token += char;
+        }
+        else if (char === "'" || char === '"') {
+            quote = char;
+        }
+        else if (/\s/.test(char)) {
+            if (token) {
+                tokens.push(token);
+                token = "";
+            }
+        }
+        else {
+            token += char;
+        }
+    }
+    if (escaped)
+        token += "\\";
+    if (token)
+        tokens.push(token);
+    return tokens;
+}
+function extractCommandFlag(command, flag) {
+    const tokens = commandTokens(command);
+    const i = tokens.indexOf(flag);
+    return i === -1 || i + 1 >= tokens.length ? undefined : tokens[i + 1];
+}
+function stripSessionArgs(args) {
+    const stripped = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--resume" || arg === "--session-id" || arg === "-r") {
+            i++;
+        }
+        else if (arg === "--last" || arg === "--fork-session" || arg.startsWith("--resume=") || arg.startsWith("--session-id=")) {
+            continue;
+        }
+        else {
+            stripped.push(arg);
+        }
+    }
+    return stripped;
+}
+export function validateResumeWorker(project, agent, options) {
+    const harness = harnessFor(agent.command);
+    let stateProblem;
+    let blocker;
+    if (agent.status !== "closed") {
+        stateProblem = `Agent ${agent.id} ("${agent.name}") is not closed (status: ${agent.status}).`;
+    }
+    else if (agent.kind === LEAD_KIND) {
+        stateProblem = `Agent ${agent.id} ("${agent.name}") is this project's lead session. agent_resume is for workers; start a lead session with \`hive lead\`.`;
+    }
+    else if (options.recoveryOnly && (agent.recovery_state !== "pending" || agent.parked_at)) {
+        stateProblem = "row is not marked for crash recovery";
+    }
+    else if (!harness.supportsResume) {
+        blocker =
+            `Agent ${agent.id} ("${agent.name}")'s harness ("${harness.name}", command: "${agent.command}") ` +
+                "does not support resume, so it has no session id to resume from.";
+    }
+    else if (!agent.session_id) {
+        blocker =
+            `Agent ${agent.id} ("${agent.name}") has no recorded session id, so it cannot be resumed. It may ` +
+                "predate this feature, or it may have closed before its first hook event ever fired. Spawn a new worker instead.";
+    }
+    else if (harness.name === "codex" && !agent.codex_home) {
+        blocker =
+            `Agent ${agent.id} ("${agent.name}") has no recorded CODEX_HOME, so its session cannot be resumed. ` +
+                (agent.parked_at
+                    ? "This should not happen for a parked codex worker - its home is only reaped on agent_close. Check agent_status for how it actually got here."
+                    : "Its Codex home was released after close, so there is nothing here to resume; spawn a new worker instead.");
+    }
+    else if (!agent.cwd || !existsSync(agent.cwd)) {
+        const recreate = agent.parked_branch
+            ? `git worktree add ${agent.cwd} ${agent.parked_branch}`
+            : `recreate a checkout at ${agent.cwd || "(empty)"} (no branch was recorded for it - agent_park records one)`;
+        const reason = harness.name === "codex" ? "It resumes into that directory as its working directory" : "Its transcript is resolved from that path";
+        blocker =
+            `Agent ${agent.id} ("${agent.name}")'s working directory is gone: ${agent.cwd || "(empty)"}. ${reason}, ` +
+                `so recreate it and the resume works unchanged: ${recreate}`;
+    }
+    else if (options.recoveryOnly && options.parentActor == null) {
+        blocker = "no recorded parent actor for recovery placement";
+    }
+    else if (options.recoveryOnly && harness.name === "codex" && !existsSync(codexHomeDir(agent.codex_home))) {
+        blocker = "Codex home is missing";
+    }
+    else {
+        const running = db
+            .prepare("SELECT id, name FROM agents WHERE project_id = ? AND status = 'running' ORDER BY id")
+            .all(project.id);
+        const collision = running.find((row) => row.id !== agent.id && row.name.toLowerCase() === agent.name.toLowerCase());
+        if (collision) {
+            blocker = options.recoveryOnly
+                ? "a running worker already uses this name"
+                : `Cannot resume agent ${agent.id} ("${agent.name}") under its recorded name: a running agent ` +
+                    `(agent ${collision.id}) already has it. agent_resume does not rename on your behalf - the ` +
+                    `${agent.parked_at ? "parked" : "closed"} lane is not lost, it just cannot come back under a name ` +
+                    "someone else is using. Free the name first (agent_rename or agent_close on the running one), " +
+                    `then retry agent_resume(agent_id: ${agent.id}).`;
+        }
+    }
+    return { project, agent, harness, stateProblem, blocker };
+}
+export async function resumeWorker(projectId, agentId, options) {
+    const project = getProject(projectId);
+    if (!project)
+        throw new Error(`Project ${projectId} is no longer registered.`);
+    const agent = getAgentRow(project.id, agentId, "Call agent_list(include_closed: true).");
+    const validation = validateResumeWorker(project, agent, options);
+    const resumeHarness = validation.harness;
+    if (validation.stateProblem)
+        throw new Error(validation.stateProblem);
+    refuseLimitedHarness(project.id, validation.harness.name, "agent_resume");
+    if (validation.blocker)
+        throw new Error(validation.blocker);
+    const branchNow = agent.parked_branch ? branchAt(agent.cwd) : "";
+    const branchDrift = branchNow && branchNow !== agent.parked_branch
+        ? { parked_branch: agent.parked_branch, branch_now: branchNow }
+        : undefined;
+    const { config: projectConfig } = loadProjectYml(project.path);
+    const placement = projectConfig?.placement ?? (process.env.HIVE_SPAWN_PLACEMENT === "window" ? "window" : "split");
+    const layout = projectConfig?.layout ?? DEFAULT_LAYOUT;
+    const launchOptions = storedLaunchOptions(agent.extra_args);
+    let commandString;
+    let resumeEnv = contextCheckpointEnv(projectConfig);
+    if (resumeHarness.name === "codex") {
+        commandString = workerCommandString({
+            command: resolvedCommandPrefix(agent.command) || "codex",
+            model: agent.model ?? extractCommandFlag(agent.command, "--model"),
+            displayName: agent.name,
+            extraArgs: [
+                ...codexLaunchArgs(agent.cwd, launchOptions.readOnly),
+                ...stripSessionArgs(launchOptions.args),
+                "resume",
+                agent.session_id,
+            ],
+        });
+        resumeEnv = { ...resumeEnv, CODEX_HOME: codexHomeDir(agent.codex_home) };
+        ensureCodexHooksFile(agent.codex_home, { includePostToolUse: projectConfig?.context_checkpoint_percent != null });
+        refreshCodexMcpEnv(agent.codex_home, agentIdentityEnv(agent.actor_id, agent.name, project.path));
+    }
+    else {
+        commandString = workerCommandString({
+            command: resolvedCommandPrefix(agent.command) || "claude",
+            displayName: agent.name,
+            model: agent.model ?? undefined,
+            extraArgs: [...stripSessionArgs(launchOptions.args), "--resume", agent.session_id],
+            settingsPath: ensureWorkerHooksFile(agent.id, {
+                readOnly: launchOptions.readOnly,
+                includePostToolUse: projectConfig?.context_checkpoint_percent != null,
+            }),
+        });
+    }
+    const { target, landedInProjectId } = resumeAgent({
+        agentId: agent.id,
+        actorId: agent.actor_id,
+        name: agent.name,
+        projectId: project.id,
+        projectName: project.name,
+        projectPath: project.path,
+        cwd: agent.cwd,
+        commandString,
+        env: resumeEnv,
+        placement,
+        layout,
+        parentActor: options.parentActor,
+        recoveryOnly: options.recoveryOnly,
+    });
+    return {
+        agent_id: agent.id,
+        actor_id: agent.actor_id,
+        name: agent.name,
+        tmux_target: target,
+        resumed_session_id: agent.session_id,
+        ...(agent.parked_at ? { was_parked_at: agent.parked_at } : {}),
+        ...(branchDrift ? { branch_drift: branchDrift } : {}),
+        ...(landedInProjectId != null ? { landed_in_project: getProject(landedInProjectId)?.name ?? `project ${landedInProjectId}` } : {}),
+    };
+}

package/dist/build-info.json

@@ -1 +1 @@
-{"version":"1.11.8","sha":"500220b","dirty":false,"build_id":"1286494bf19194350611bfbf75688ec5a3c7e4b033b7c8dc84a101f57528dcbb"}
+{"version":"1.12.0","sha":"aea4e1b","dirty":false,"build_id":"29032035781c51496a882c8bca3ea8edc17cab379acdac96b255751bf5bd67a1"}

package/dist/claudeWake.js

@@ -1,7 +1,9 @@
 import { createConnection } from "node:net";
 import { join } from "node:path";
-import { db } from "./db.js";
-import { loadProjectYml } from "./projectYml.js";
+import { dataDir, db } from "./db.js";
+import { harnessFor } from "./harnesses.js";
+import { loadProjectYml, quietMessagingEnabled } from "./projectYml.js";
+import { shellQuote } from "./tmux.js";
 export { DELIVERY_METHOD } from "./wakeSql.js";
 export const CROSS_SESSION_CLOSE = "</cross-session-message>";
 export const ENVELOPE_OPEN = '<cross-session-message from="';
@@ -23,7 +25,12 @@ function claudeWakeFrame(sender, text) {
 }
 export function quietMessagingOn(projectId) {
     const project = db.prepare("SELECT path FROM projects WHERE id = ?").get(projectId);
-    return project !== undefined && loadProjectYml(project.path).config?.quiet_messaging === true;
+    return project !== undefined && quietMessagingEnabled(loadProjectYml(project.path).config);
+}
+export function quietMessagingHooksLaunched(projectId, command) {
+    const path = join(dataDir, `lead-${projectId}-hooks.json`);
+    const args = harnessFor("claude").briefDelivery?.settingsArgs(path);
+    return args !== undefined && command.includes(args.map(shellQuote).join(" "));
 }
 export function promptMarkerEvidenceSql(markerAt) {
     const evPrompt = "(CASE WHEN json_valid(ev.payload) THEN COALESCE(json_extract(ev.payload, '$.prompt'), '') ELSE ev.payload END)";

package/dist/cli.js

@@ -34,12 +34,15 @@ import { probeSessionInterpreter, reexecTarget, sessionStartVerdict, } from "./s
 import { backupHealth, backupNow, backupsDir, formatBytes, listSnapshots, previewRestore, restoreSnapshot, totalSizeBytes, } from "./backup.js";
 import { describeTeardownWindow, readTeardowns, teardownLogPath, } from "./teardown.js";
 import { asNameClash, buildEnvFlags, closeAgentRow, isReservedAgentName, launchAgent, LEAD_KIND, LEAD_NAME, mintLeadActorId, relayoutAfterPaneLeft, upsertActor, withWindowClaim, } from "./spawn.js";
-import { adoptableWindow, applyLayout, claimInitialWindow, configureHiveWindow, controlModeFor, createWindow, DEFAULT_LAYOUT, describePaneChoice, ensureSession, findProjectWindow, foreignSocket, isViewSessionName, listOwnedWindows, liveTargets, observationFailed, observeRowOwnership, ORPHAN_MIN_AGE_MS, orphanScratchServers, orphansWorthWarningAbout, paneIsAloneInWindow, paneVisibility, panePidForRecord, PROCESSES_LAYOUT, processesPaneTitle, processesWindowName, projectWindows, RAW_ATTACH_TMUX_CONFIG, renderAttachCommand, resolveAttachTarget, resolveInTmuxTarget, rowLive, rowOwnership, SESSION_PREFIX, appendGlobalHook, globalHooks, replaceGlobalHooks, sessionName, setPaneTitle, shellQuote, shownPaneTitle, makeProcessesWindow, tmux, TMUX_DOC, tmuxSaysNothingThere, tmuxTimeoutOverride, tmuxSocketPath, untrustedTmuxServer, waitForPaneEstablished, windowLayout, } from "./tmux.js";
+import { adoptableWindow, applyLayout, claimInitialWindow, configureHiveWindow, controlModeFor, createWindow, DEFAULT_LAYOUT, describePaneChoice, ensureSession, findProjectWindow, foreignSocket, isViewSessionName, listOwnedWindows, liveTargets, observationFailed, observeRowOwnership, ORPHAN_MIN_AGE_MS, orphanScratchServers, orphansWorthWarningAbout, paneIsAloneInWindow, paneWindow, paneVisibility, panePidForRecord, PROCESSES_LAYOUT, processesPaneTitle, processesWindowName, projectWindows, RAW_ATTACH_TMUX_CONFIG, renderAttachCommand, resolveAttachTarget, resolveInTmuxTarget, rowLive, rowOwnership, SESSION_PREFIX, appendGlobalHook, globalHooks, replaceGlobalHooks, sessionName, setPaneTitle, shellQuote, shownPaneTitle, makeProcessesWindow, tmux, TMUX_DOC, tmuxSaysNothingThere, tmuxTimeoutOverride, tmuxSocketPath, untrustedTmuxServer, waitForPaneEstablished, windowLayout, } from "./tmux.js";
 import { collectCrew, crewStoreProblem } from "./crew.js";
+import { resumeWorker, validateResumeWorker } from "./agentResume.js";
+import { markWorkerLost } from "./workerRecovery.js";
 import { describeVisibility, formatLocal, processCounts } from "./dashboard.js";
 import { runningCommandRow, runningCommandRows, snapshotProcesses, stopAllProcesses, stopLine, stopProcess, renderStart, STOP_REASONS, } from "./processes.js";
-import { activeProfile, agentVarKeys, BUILT_IN_PROJECT_YML, configHash, loadProjectYml, mergedProjectVars, NO_PROFILE, PROJECT_YML_KEYS, resolveCommandDir, resolveFirstMessage, } from "./projectYml.js";
+import { activeProfile, agentVarKeys, BUILT_IN_PROJECT_YML, configHash, leadSidebarEnabled, loadProjectYml, mergedProjectVars, NO_PROFILE, PROJECT_YML_KEYS, quietMessagingEnabled, resolveCommandDir, resolveFirstMessage, } from "./projectYml.js";
 import { appendClaudeLeadArgs, crewPluginDir, isTrusted, leadIdentityEnv, renderLeadPosture } from "./leadLaunch.js";
+import { completionGateTrust } from "./todoCompletionGate.js";
 import { handoffStatusSegment } from "./leadHandoff.js";
 import { cmdLeadHandoff, runHandoffGrace, runHandoffStart } from "./leadHandoffCli.js";
 import { harnessFor, hasTranscriptSignal, paneClassifierFor, transcriptDirFor } from "./harnesses.js";
@@ -75,6 +78,9 @@ Usage:
   hive stop <process> [path]  stop one running process; --all stops every one
   hive show <process> [path]  move a running process's pane beside the lead
   hive hide <process> [path]  move it back into the <project>/processes window
+  hive layout               gather this project's live workers and restore its configured layout
+  hive crew-restore [--dry-run] [--json]
+                             resume this project's workers marked for crash recovery
   hive status                overview of agents, todos, and wake-ups everywhere
   hive crew --json           this project's workers, todos and wakes as one JSON
                              snapshot; read-only, writes nothing
@@ -411,6 +417,12 @@ async function cmdLead(argv) {
             if (!untrusted && config) {
                 untrusted = Object.entries(config.processes).find(([name, proc]) => proc.auto_start !== false && !isTrusted(project.id, name, proc.command, proc.dir, proc.env))?.[0];
             }
+            if (!untrusted && config?.completion_gate) {
+                const gateTrust = completionGateTrust(config.completion_gate);
+                if (!isTrusted(project.id, gateTrust.name, gateTrust.command, gateTrust.dir, gateTrust.env)) {
+                    untrusted = "completion gate";
+                }
+            }
             if (untrusted) {
                 console.error(`hive lead: "${untrusted}" is not trusted; run hive lead <path> interactively once`);
                 process.exitCode = 1;
@@ -421,7 +433,7 @@ async function cmdLead(argv) {
         for (const w of warnings)
             console.log(`! ${w}`);
         const session = sessionName();
-        const hooksPath = ensureLeadHooksFile(project.id, config?.quiet_messaging === true);
+        const hooksPath = ensureLeadHooksFile(project.id, quietMessagingEnabled(config));
         let leadCommand = "claude";
         if (!config) {
             console.log("No hive.yml here; starting a plain claude lead. Add a hive.yml to define project commands and a custom lead (run hive --help for the format).");
@@ -434,6 +446,10 @@ async function cmdLead(argv) {
                 console.log("Using the default claude lead instead.");
             }
         }
+        if (config?.completion_gate) {
+            const gateTrust = completionGateTrust(config.completion_gate);
+            await ensureTrusted(project.id, gateTrust.name, gateTrust.command, gateTrust.dir, gateTrust.env);
+        }
         const leadHarness = harnessFor(leadCommand);
         let firstMessage = resolveFirstMessage(config, sources).message;
         if (firstMessage !== "" && !(await (await import("./kickoff.js")).kickoffGate(project.path)).ok)
@@ -464,7 +480,7 @@ async function cmdLead(argv) {
                 projectId: project.id,
                 projectName: project.name,
                 hooksPath,
-                sidebarPluginDir: config?.lead_sidebar === true && leadHarness.name === "claude" ? crewPluginDir() : null,
+                sidebarPluginDir: leadSidebarEnabled(config) && leadHarness.name === "claude" ? crewPluginDir() : null,
                 posture: renderedPosture,
                 firstMessage,
             }));
@@ -748,14 +764,15 @@ const HIVE_YML_TEMPLATE = `# hive project config. Read by \`hive lead\` from the
 # first_message: "..."         # a lead's first turn; absent or "" sends none
 
 # context_checkpoint_percent: null # unset means off; integer 1-100 to enable
+# completion_gate: null       # optional project todo check; null keeps it disabled
 
-# lead_turn_budget: {warn: 300, stop: 600} # optional lead statusline thresholds
+# lead_turn_budget: {warn: 300, stop: 600} # optional thresholds; auto_handoff defaults on
 
 # dashboard: true               # write .hive/dashboard.html (default: false)
 
-# lead_sidebar: true            # a crew pane in a claude lead (default: false; restart the lead)
+# lead_sidebar: false           # disable the crew pane in a claude lead; restart the lead
 
-# quiet_messaging: true        # wakes and worker messages reach a claude lead as one row (default: false; restart the lead)
+# quiet_messaging: false       # use typed wakes and worker messages instead of one row; restart the lead
 
 # vars:                         # substituted into the profile runbook
 #   repo: owner/name            # {{repo}}
@@ -1612,6 +1629,108 @@ function cmdHide(argv) {
         return `${name}: hidden`;
     }));
 }
+function cmdLayout(argv) {
+    const parsed = parseArgs(argv, {});
+    rejectUnknownFlags("layout", parsed, "none");
+    if (parsed.positional.length > 0) {
+        console.error("Usage: hive layout");
+        process.exit(1);
+    }
+    const project = resolveProjectForRead("layout");
+    const { config } = loadProjectYml(project.path);
+    if (config?.placement === "window") {
+        console.log("placement is window in hive.yml; nothing to gather");
+        return;
+    }
+    const layout = config?.layout ?? DEFAULT_LAYOUT;
+    const session = sessionName();
+    const result = withWindowClaim(() => {
+        const snapshot = liveTargets();
+        if (observationFailed(snapshot)) {
+            return { lines: ["tmux could not be probed; nothing was changed"], exitCode: 1 };
+        }
+        const windows = projectWindows(session, project.id);
+        if (windows === null) {
+            return { lines: ["tmux could not be probed; nothing was changed"], exitCode: 1 };
+        }
+        if (!windows.project) {
+            return { lines: ["this project has no window yet; run hive first"], exitCode: 1 };
+        }
+        const lead = db
+            .prepare("SELECT tmux_target, tmux_socket, pane_pid FROM agents WHERE project_id = ? AND kind = ? AND status = 'running' ORDER BY id LIMIT 1")
+            .get(project.id, LEAD_KIND);
+        if (!lead || rowOwnership(lead, snapshot) !== "live") {
+            return { lines: ["the lead pane could not be verified; nothing was changed"], exitCode: 1 };
+        }
+        const leadWindow = paneWindow(lead.tmux_target);
+        if (!leadWindow || leadWindow.split(":")[1] !== windows.project.split(":")[1]) {
+            return {
+                lines: [`the lead pane is not in this project's window (${leadWindow ?? "unknown"} vs ${windows.project}); nothing was changed`],
+                exitCode: 1,
+            };
+        }
+        const ownedWindows = listOwnedWindows(session);
+        const workers = db
+            .prepare("SELECT id, name, tmux_target, tmux_socket, pane_pid FROM agents WHERE project_id = ? AND kind = 'agent' AND status = 'running' ORDER BY id")
+            .all(project.id);
+        const moved = [];
+        const sourceWindows = new Set();
+        for (const worker of workers) {
+            if (rowOwnership(worker, snapshot) !== "live")
+                continue;
+            const source = paneWindow(worker.tmux_target);
+            if (!source || source.split(":")[1] === windows.project.split(":")[1])
+                continue;
+            const sourceId = source.split(":")[1];
+            const stamped = ownedWindows.find((window) => window.window.split(":")[1] === sourceId);
+            if (stamped &&
+                ((stamped.projectId !== "" && Number(stamped.projectId) !== project.id) ||
+                    (stamped.processesOf !== "" && Number(stamped.processesOf) !== project.id))) {
+                continue;
+            }
+            tmux("join-pane", "-d", "-s", worker.tmux_target, "-t", windows.project);
+            sourceWindows.add(source);
+            moved.push({ name: worker.name, pane: worker.tmux_target });
+        }
+        const leadPanes = tmux("list-panes", "-t", windows.project, "-F", "#{pane_id}").split("\n").filter(Boolean);
+        if (leadPanes[0] !== lead.tmux_target) {
+            tmux("swap-pane", "-s", lead.tmux_target, "-t", leadPanes[0]);
+        }
+        applyLayout(windows.project, layout);
+        const layoutApplied = windowLayout(windows.project) === layout;
+        const projectRunningRows = db
+            .prepare("SELECT tmux_target, tmux_socket, pane_pid FROM agents WHERE project_id = ? AND status = 'running' AND tmux_target != ''")
+            .all(project.id);
+        const projectRunningTargets = new Set(projectRunningRows.filter((row) => rowOwnership(row, snapshot) === "live").map((row) => row.tmux_target));
+        const leftWindows = [];
+        for (const source of sourceWindows) {
+            let remaining;
+            try {
+                remaining = tmux("list-panes", "-t", source, "-F", "#{pane_id}").split("\n").filter(Boolean);
+            }
+            catch (error) {
+                if (tmuxSaysNothingThere(error))
+                    continue;
+                throw error;
+            }
+            if (remaining.some((pane) => !projectRunningTargets.has(pane)))
+                leftWindows.push(source);
+        }
+        const lines = moved.map(({ name, pane }) => `moved ${name} pane ${pane} into ${windows.project}`);
+        if (leftWindows.length > 0)
+            lines.push(`left windows with panes remaining: ${leftWindows.join(", ")}`);
+        if (moved.length === 0)
+            lines.push("nothing to move");
+        if (!layoutApplied) {
+            lines.push(`layout ${layout} could not be applied; ${moved.length > 0 ? "panes were moved" : "no panes were moved"}`);
+            return { lines, exitCode: 1 };
+        }
+        lines.push(`moved ${moved.length} pane${moved.length === 1 ? "" : "s"} into ${windows.project}; layout ${layout}`);
+        return { lines, exitCode: 0 };
+    });
+    console.log(result.lines.join("\n"));
+    process.exitCode = result.exitCode;
+}
 const LEAD_OWNERSHIP_LABEL = {
     live: "running",
     gone: "no live pane",
@@ -3004,6 +3123,144 @@ function cmdCrew(argv) {
     }
     console.log(JSON.stringify(collectCrew(project, new Date())));
 }
+async function cmdCrewRestore(argv) {
+    const parsed = parseArgs(argv, { flags: ["--dry-run", "--json"] });
+    if (parsed.positional.length > 0)
+        parsed.unknown.push(parsed.positional[0]);
+    rejectUnknownFlags("crew-restore", parsed, "--dry-run and --json");
+    const dryRun = parsed.flags.has("--dry-run");
+    let project;
+    try {
+        project = pinnedOrCwdProject();
+    }
+    catch (e) {
+        console.error(`hive crew-restore: ${errorMessage(e)}`);
+        process.exitCode = 1;
+        return;
+    }
+    if (!project) {
+        console.error("hive crew-restore: this directory is not a registered hive project.");
+        process.exitCode = 1;
+        return;
+    }
+    const snapshot = liveTargets();
+    const workers = db
+        .prepare("SELECT * FROM agents WHERE project_id = ? AND kind = 'agent' ORDER BY id")
+        .all(project.id);
+    const candidates = workers.filter((worker) => {
+        if (worker.parked_at)
+            return false;
+        if (worker.status === "closed")
+            return worker.recovery_state === "pending";
+        return worker.status === "running";
+    });
+    const notConsidered = workers.length - candidates.length;
+    const rows = [];
+    for (const initial of candidates) {
+        let candidate = initial;
+        if (candidate.status === "running") {
+            if (!candidate.tmux_target) {
+                rows.push({ agent_id: candidate.id, name: candidate.name, outcome: "skipped", reason: "resume is already in flight or was interrupted before pane publication; inspect manually" });
+                continue;
+            }
+            const ownership = rowOwnership(candidate, snapshot);
+            if (ownership === "live") {
+                rows.push({ agent_id: candidate.id, name: candidate.name, outcome: "skipped", reason: "the recorded pane is still live" });
+                continue;
+            }
+            if (ownership === "unknown") {
+                rows.push({ agent_id: candidate.id, name: candidate.name, outcome: "skipped", reason: snapshot === null ? "tmux ownership could not be checked" : "pane ownership is unknown" });
+                continue;
+            }
+            if (ownership !== "gone" && ownership !== "reissued") {
+                rows.push({ agent_id: candidate.id, name: candidate.name, outcome: "skipped", reason: "the row changed while it was inspected" });
+                continue;
+            }
+            if (!dryRun) {
+                const expected = {
+                    tmux_target: candidate.tmux_target,
+                    tmux_socket: candidate.tmux_socket,
+                    pane_pid: candidate.pane_pid,
+                };
+                if (!markWorkerLost(candidate.id, expected)) {
+                    const latest = db.prepare("SELECT * FROM agents WHERE id = ? AND project_id = ?").get(candidate.id, project.id);
+                    if (!latest || latest.status !== "closed" || latest.recovery_state !== "pending") {
+                        rows.push({ agent_id: initial.id, name: initial.name, outcome: "skipped", reason: "the row changed before crash recovery could be claimed" });
+                        continue;
+                    }
+                    candidate = latest;
+                }
+                else {
+                    const latest = db.prepare("SELECT * FROM agents WHERE id = ? AND project_id = ?").get(candidate.id, project.id);
+                    if (!latest) {
+                        rows.push({ agent_id: initial.id, name: initial.name, outcome: "skipped", reason: "the row was removed during crash recovery" });
+                        continue;
+                    }
+                    candidate = latest;
+                }
+            }
+            else {
+                candidate = { ...candidate, status: "closed", recovery_state: "pending" };
+            }
+        }
+        if (candidate.parked_at) {
+            rows.push({ agent_id: candidate.id, name: candidate.name, outcome: "skipped", reason: "parked workers are not crash recoveries" });
+            continue;
+        }
+        if (candidate.status !== "closed" || candidate.recovery_state !== "pending") {
+            rows.push({ agent_id: candidate.id, name: candidate.name, outcome: "skipped", reason: "row is not marked for crash recovery" });
+            continue;
+        }
+        const validation = validateResumeWorker(project, candidate, {
+            parentActor: candidate.parent_actor_id,
+            recoveryOnly: true,
+        });
+        candidate = validation.agent;
+        if (validation.stateProblem) {
+            rows.push({ agent_id: candidate.id, name: candidate.name, outcome: "skipped", reason: "the row changed before recovery validation" });
+            continue;
+        }
+        if (validation.blocker) {
+            rows.push({ agent_id: candidate.id, name: candidate.name, outcome: dryRun ? "skipped" : "failed", reason: validation.blocker });
+            continue;
+        }
+        if (dryRun) {
+            rows.push({ agent_id: candidate.id, name: candidate.name, outcome: "would_restore" });
+            continue;
+        }
+        try {
+            const receipt = await resumeWorker(project.id, candidate.id, {
+                parentActor: candidate.parent_actor_id,
+                recoveryOnly: true,
+            });
+            rows.push({ agent_id: receipt.agent_id, name: receipt.name, outcome: "restored", tmux_target: receipt.tmux_target });
+        }
+        catch (e) {
+            const latest = db.prepare("SELECT status, recovery_state FROM agents WHERE id = ? AND project_id = ?").get(candidate.id, project.id);
+            if (latest?.status !== "closed" || latest.recovery_state !== "pending") {
+                rows.push({ agent_id: candidate.id, name: candidate.name, outcome: "skipped", reason: "the row changed before the guarded recovery claim" });
+            }
+            else {
+                rows.push({ agent_id: candidate.id, name: candidate.name, outcome: "failed", reason: errorMessage(e) });
+            }
+        }
+    }
+    if (parsed.flags.has("--json")) {
+        console.log(JSON.stringify({ project_id: project.id, dry_run: dryRun, rows, not_considered: notConsidered }));
+    }
+    else {
+        const counts = { restored: 0, would_restore: 0, skipped: 0, failed: 0 };
+        for (const row of rows) {
+            counts[row.outcome]++;
+            const target = row.tmux_target ? ` ${row.tmux_target}` : "";
+            const reason = row.reason ? `: ${row.reason}` : "";
+            console.log(`${row.outcome.padEnd(13)} agent ${row.agent_id} ${row.name}${target}${reason}`);
+        }
+        console.log(`crew-restore: ${counts.restored} restored, ${counts.would_restore} would restore, ${counts.skipped} skipped, ${counts.failed} failed, ${notConsidered} not considered`);
+    }
+    if (rows.some((row) => row.outcome === "failed"))
+        process.exitCode = 1;
+}
 function cmdPortfolio(argv) {
     const parsed = parseArgs(argv, { flags: ["--json"] });
     if (parsed.positional.length > 0)
@@ -3535,7 +3792,7 @@ if (command === "--version" || command === "-v") {
     process.exit(0);
 }
 const COMMANDS = [
-    "lead", "queen", "queen-audit", "init", "attach", "start", "stop", "show", "hide", "status", "portfolio", "crew", "next", "setup", "upgrade", "doctor",
+    "lead", "queen", "queen-audit", "init", "attach", "start", "stop", "show", "hide", "layout", "status", "portfolio", "crew", "crew-restore", "next", "setup", "upgrade", "doctor",
     LEAD_PANE_EXITED_VERB,
     LEAD_HANDOFF_GRACE_VERB,
     LEAD_HANDOFF_START_VERB,
@@ -3595,6 +3852,9 @@ try {
         case "hide":
             cmdHide(rest);
             break;
+        case "layout":
+            cmdLayout(rest);
+            break;
         case "status":
             rejectUnknownFlags("status", parseArgs(rest, {}), "none");
             cmdStatus();
@@ -3605,6 +3865,9 @@ try {
         case "crew":
             cmdCrew(rest);
             break;
+        case "crew-restore":
+            await cmdCrewRestore(rest);
+            break;
         case "queen-audit":
             cmdQueenAudit(rest);
             break;