@cmgmyr/hive 1.10.0 → 1.11.0

package/claude-plugin/crew/model.mjs

@@ -66,6 +66,7 @@ function workerRow(lane, snapshot, nowMs, memory, nextMemory) {
   else {
     const since = state === "blocked" ? null : w.state_changed_at;
     head.push(`${state} ${duration(w, { label: state, since, lower_bound: false }, nowMs, memory, nextMemory)}`);
+    if (state !== "blocked" && w.activity?.label) head.push(w.activity.label);
   }
   const tail = [ago(w.age_seconds)];
   if (w.commits_ahead !== null && w.commits_ahead !== undefined) tail.push(`+${w.commits_ahead} commits`);
@@ -120,6 +121,8 @@ export function buildCrewView(snapshot, previousView, nowMs) {
   const { wakes } = snapshot;
   const workers = snapshot.lanes.filter((l) => l.worker).length;
   const footer = [{ text: nextLine(wakes.next, nowMs) }];
+  const questionsPending = snapshot.questions?.pending ?? 0;
+  if (questionsPending > 0) footer.push({ text: `questions pending: ${questionsPending}` });
   if (wakes.watching.length > 0) footer.push({ text: `watching: ${wakes.watching.map(watchText).join(", ")}` });
   else if (workers > 0 && !covered(snapshot)) footer.push({ text: "unwatched: no standing watch on running workers", amber: true });
   return {

package/dist/build-info.json

@@ -1 +1 @@
-{"version":"1.10.0","sha":"9dd5fee","dirty":false,"build_id":"d7050d60f67cf44e2ca833e2ba422563b4e6b8fbdd68bccd51772e429cac1fa5"}
+{"version":"1.11.0","sha":"7534ff6","dirty":false,"build_id":"bd31535e0eaed043ebe60b90c2e95925e21567baf82b5142e3a6c0e6908a58ac"}

package/dist/cli.js

@@ -17,6 +17,7 @@ import { dataDir, db, migrate, storeSchemaAhead } from "./db.js";
 import { cacheIsStale, queryUpdate, readCachedUpdate, refreshUpdate, shouldAutoRefresh, updateLine } from "./updateCheck.js";
 import { checkoutUpgradeSteps, detectInstallShape, globalUpgradeSteps } from "./upgrade.js";
 import { isLowHeadroom, orphanLoginShellDetails, ptyHeadroom } from "./ptys.js";
+import { staleHiveServers } from "./staleServers.js";
 import { addProject, agentProjectPin, assertQueenCrossProjectWrite, captureQueenWriteIdentity, currentActor, effectiveProjectId, findProjectForCwd, findProjectForDir, getProjectByPath, gitPrimaryRoot, getProject, listProjects, QUEEN_PROFILE, queenHomeDir, registeredAncestor, takeRegistrationNotice, } from "./context.js";
 import { confirmQueenWrite, listQueenAudit } from "./queenAudit.js";
 import { formatRowCounts, projectRowCounts, removeProject } from "./projectRemove.js";
@@ -37,8 +38,10 @@ import { collectCrew, crewStoreProblem } from "./crew.js";
 import { describeVisibility, formatLocal, processCounts } from "./dashboard.js";
 import { runningCommandRow, runningCommandRows, snapshotProcesses, stopAllProcesses, stopLine, stopProcess, 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 { writeProjectPosture } from "./brief.js";
-import { carriesNameFlag, harnessFor, hasTranscriptSignal, paneClassifierFor, transcriptDirFor } from "./harnesses.js";
+import { appendClaudeLeadArgs, crewPluginDir, isTrusted, leadIdentityEnv, renderLeadPosture } from "./leadLaunch.js";
+import { handoffStatusSegment } from "./leadHandoff.js";
+import { cmdLeadHandoff, runHandoffGrace, runHandoffStart } from "./leadHandoffCli.js";
+import { harnessFor, hasTranscriptSignal, paneClassifierFor, transcriptDirFor } from "./harnesses.js";
 import { codexHomeDir, codexInstructionsPhrase, ensureCodexHome, reapCodexHome } from "./codexHome.js";
 import { FIRST_MESSAGE_SHA_ENV, firstMessageDigest } from "./firstMessage.js";
 import { ageSecondsSince, deriveProvenance, describeForHuman, describeLastLogEvent, humanizeAge, lastLogEvent, lastPermissionMode, reportsAgentStateLog, } from "./stateProvenance.js";
@@ -46,6 +49,7 @@ import { awaitingFirstPromptSql } from "./firstPrompt.js";
 import { checkoutRoot, createProfile, forkProfile, PROFILE_FILES, ProfileError, profileExists, profileFileNames, profileNames, profileStatus, readProfileFile, referencedPads, referencedPaths, renderProfileFile, resolveProfileFile, REWRITE_THRESHOLD, templateVars, userProfilesDir, } from "./profiles.js";
 import { getTodoDetail, listTodoSummaries, OPEN_BLOCKERS_SQL, TODO_STATUSES, } from "./tools/todos.js";
 import { createPad, getActivePadByName, listActivePads, overwritePadContent, } from "./tools/pads.js";
+import { answerQuestion, listQuestions } from "./questions.js";
 function usage() {
     console.log(`hive — run a crew of Claude Code and Codex workers from one lead session
 
@@ -99,6 +103,10 @@ Usage:
   hive todos [--all] [--status <s>] [--tag <t>]
                              list this project's todos; open work by default
   hive todo <id>             print one todo in full, comments included
+  hive questions [--json]   list pending and defaulted questions
+  hive answer <id> <answer> [--notes <text>]
+                             record an answer to a pending question
+                             use -- before an answer that starts with a dash
   hive backups               list automatic store snapshots
   hive restore <name> [--yes] [--force]  overwrite the live store from a snapshot
   hive project rm <id|path> [--yes]
@@ -109,6 +117,7 @@ Usage:
   hive kickoff [--explain]   SessionStart hook output; silent unless this is a lead checkout
   hive profile [list|path|fork|create|read]  standing instructions shared across projects
   hive statusline            one-line store summary; silent outside hive projects
+  hive lead-handoff          a lead confirms its persisted handoff pad (run from a handoff request)
 
 hive lead reads hive.yml from the project root when present; hive init
 writes this starter file (uncomment what you need):
@@ -204,12 +213,6 @@ async function ensureTrusted(projectId, name, command, dir, env) {
     db.prepare("INSERT OR IGNORE INTO command_trust (project_id, name, config_hash) VALUES (?, ?, ?)").run(projectId, name, hash);
     return true;
 }
-function isTrusted(projectId, name, command, dir, env) {
-    const hash = configHash(name, command, dir, env);
-    return !!db
-        .prepare("SELECT 1 FROM command_trust WHERE project_id = ? AND name = ? AND config_hash = ?")
-        .get(projectId, name, hash);
-}
 function startYmlCommand(project, name, proc, config) {
     if (isReservedAgentName(name)) {
         return `skipped: "lead" is reserved for this project's lead session and cannot be used as a process name`;
@@ -426,18 +429,9 @@ async function cmdLead(argv) {
         // Posture is rendered once, then delivered through whichever channel this harness has: a
         // claude lead gets it as --append-system-prompt-file below; a codex lead gets the identical
         // text as config.toml's developer_instructions, built after ensureLeadRow (it needs leadActorId).
-        const profile = activeProfile(config);
-        let renderedPosture = null;
-        let postureSource;
-        if (profile) {
-            const posture = resolveProfileFile(profile, "posture.md");
-            if (!posture) {
-                console.log(`! profile "${profile}" has no posture.md on this machine; starting without it.`);
-            }
-            else {
-                renderedPosture = renderProfileFile(profile, "posture.md", mergedProjectVars(config)) ?? "";
-                postureSource = posture.source;
-            }
+        const { profile, rendered: renderedPosture, source: postureSource } = renderLeadPosture(config);
+        if (profile && renderedPosture === null) {
+            console.log(`! profile "${profile}" has no posture.md on this machine; starting without it.`);
         }
         if (leadHarness.needsHome) {
             // Wired below, once leadActorId is known - a codex lead's hooks/posture/triage all live in
@@ -451,21 +445,19 @@ async function cmdLead(argv) {
             }
         }
         else {
-            if (!carriesNameFlag(leadCommand.trim().split(/\s+/))) {
-                leadCommand += ` --name ${shellQuote(project.name)}`;
-            }
-            leadCommand += ` ${leadHarness.briefDelivery.settingsArgs(hooksPath).map(shellQuote).join(" ")}`;
-            if (config?.lead_sidebar === true && leadHarness.name === "claude") {
-                leadCommand += ` ${["--plugin-dir", crewPluginDir()].map(shellQuote).join(" ")}`;
-            }
+            ({ command: leadCommand, promptSuffix } = appendClaudeLeadArgs({
+                command: leadCommand,
+                harness: leadHarness,
+                projectId: project.id,
+                projectName: project.name,
+                hooksPath,
+                sidebarPluginDir: config?.lead_sidebar === true && leadHarness.name === "claude" ? crewPluginDir() : null,
+                posture: renderedPosture,
+                firstMessage,
+            }));
             if (renderedPosture !== null) {
-                const posturePath = writeProjectPosture(project.id, renderedPosture);
-                leadCommand += ` ${leadHarness.briefDelivery.systemPromptArgs(posturePath).map(shellQuote).join(" ")}`;
                 console.log(`- profile: ${profile} (${postureSource} posture; see it with: hive posture)`);
             }
-            if (leadHarness.initialPromptArgs && firstMessage !== "") {
-                promptSuffix = ` ${leadHarness.initialPromptArgs(firstMessage).map(shellQuote).join(" ")}`;
-            }
         }
         const windowName = project.name;
         const { agentId: leadAgentId, actorId: leadActorId, previousTarget, previousSocket, previousPanePid, previousCommand, previousCodexHome, casExpected, casSocket, casPid, } = ensureLeadRow(project, leadCommand);
@@ -475,14 +467,7 @@ async function cmdLead(argv) {
         // actually starts under it) and correct regardless of whether this invocation ends up creating
         // a pane or adopting one. Which home ends up orphaned - this one, or the previous invocation's -
         // is decided after createdPane is known, below.
-        const leadEnv = {
-            HIVE_AGENT_ID: leadActorId,
-            HIVE_AGENT_NAME: LEAD_NAME,
-            HIVE_LEAD: "1",
-            HIVE_DATA_DIR: dataDir,
-            HIVE_PROJECT_LOCK: "",
-            HIVE_PROJECT_PATH: "",
-        };
+        const leadEnv = leadIdentityEnv(leadActorId);
         let newCodexHomeKey;
         if (leadHarness.needsHome) {
             newCodexHomeKey = randomUUID();
@@ -1288,9 +1273,6 @@ function cmdProfile(argv) {
         throw e;
     }
 }
-function crewPluginDir() {
-    return join(checkoutRoot, "claude-plugin", "crew");
-}
 const DASHBOARD_OPENED_KV_KEY = "hive:dashboard_opened";
 const DASHBOARD_OPENED_TTL_SECONDS = 8 * 60 * 60;
 function maybeOpenDashboard(project, dashboardEnabled) {
@@ -1436,6 +1418,8 @@ function resolveNamedProcess(argv, verb) {
 }
 const LEAD_PANE_EXITED_HOOK = "pane-exited";
 const LEAD_PANE_EXITED_VERB = "lead-pane-exited";
+const LEAD_HANDOFF_GRACE_VERB = "lead-handoff-grace";
+const LEAD_HANDOFF_START_VERB = "lead-handoff-start";
 // tmux runs a hook with the SERVER's environment and no login shell, so a bare `hive` resolves to
 // nothing (the iTerm rule in .claude/rules/tmux-and-panes.md) and HIVE_DATA_DIR is not there at all
 // - without it the backstop would open the DEFAULT store and find no project. Absolute interpreter,
@@ -2364,6 +2348,18 @@ function cmdDoctor(argv) {
         }
         return `${dataDir} (schema v${n})`;
     });
+    check("stale hive servers", () => {
+        const { applied_at: appliedAt } = db.prepare("SELECT MAX(applied_at) AS applied_at FROM migrations").get();
+        const result = staleHiveServers(appliedAt, dataDir);
+        if ("skipped" in result) {
+            info("stale hive servers", `check skipped: ${result.skipped}`);
+            return "check skipped";
+        }
+        for (const server of result.servers) {
+            warn("stale hive server", `pid ${server.pid} started ${server.startedAt} (parent pid ${server.ppid}: ${server.parentCommand ?? "unknown"})`, `command: ${server.command}`, "restart that session to load the current build");
+        }
+        return `${result.servers.length} stale server${result.servers.length === 1 ? "" : "s"}`;
+    });
     check("hooks file", () => ensureHooksFile());
     const here = findProjectForCwd();
     reportDispatcher();
@@ -2810,11 +2806,13 @@ function cmdStatusline() {
         parts.push("store ahead (update hive)");
     let turns = null;
     let budget = null;
+    let handoff = null;
     try {
         const actorId = process.env.HIVE_AGENT_ID;
         if (actorId) {
-            const lead = db.prepare("SELECT 1 AS lead FROM agents WHERE project_id = ? AND actor_id = ? AND kind = 'lead' AND status = 'running'").get(project.id, actorId);
+            const lead = db.prepare("SELECT id AS lead FROM agents WHERE project_id = ? AND actor_id = ? AND kind = 'lead' AND status = 'running'").get(project.id, actorId);
             if (lead) {
+                handoff = handoffStatusSegment(lead.lead);
                 let inputPath = "";
                 if (!process.stdin.isTTY) {
                     try {
@@ -2834,6 +2832,8 @@ function cmdStatusline() {
         const color = budget === null ? "" : turns >= budget.stop ? "\x1b[31m" : turns >= budget.warn ? "\x1b[33m" : "";
         parts.push(`${color}turns ${turns}${color ? "\x1b[0m" : ""}`);
     }
+    if (handoff !== null)
+        parts.push(handoff);
     console.log(`\x1b[33m⬡\x1b[0m \x1b[2mhive:\x1b[0m ${parts.join(" \x1b[2m·\x1b[0m ")}`);
 }
 function padSlug(name) {
@@ -3006,7 +3006,7 @@ function cmdPortfolio(argv) {
             `  lead ${leadText(p)}; workers ${w.working} working, ${w.idle} idle, ${w.needs_input} needs input, ` +
             `${w.other} other, ${w.unreachable} unreachable, ${w.unconfirmed} unconfirmed\n` +
             `  todos ${t.open} open, ${t.in_progress} in progress, ${t.blocked} blocked, ${t.high} high; ` +
-            `needs human ${p.needs_human}; wakes ${p.wakes.pending} pending, ${p.wakes.overdue} overdue\n` +
+            `needs human ${p.needs_human}; questions ${p.questions_pending} pending; wakes ${p.wakes.pending} pending, ${p.wakes.overdue} overdue\n` +
             `  last activity ${p.last_activity_at} UTC`);
     }
     const l = report.totals.lanes;
@@ -3314,6 +3314,67 @@ function cmdTodo(argv) {
         }
     }
 }
+function cmdQuestions(argv) {
+    const parsed = parseArgs(argv, { flags: ["--json"] });
+    if (parsed.positional.length > 0)
+        parsed.unknown.push(parsed.positional[0]);
+    rejectUnknownFlags("questions", parsed, "--json");
+    const project = resolveProjectForRead("questions");
+    const questions = listQuestions(project.id);
+    if (parsed.flags.has("--json")) {
+        console.log(JSON.stringify({ questions }));
+        return;
+    }
+    if (questions.length === 0) {
+        console.log("No pending or defaulted questions.");
+        return;
+    }
+    for (const q of questions) {
+        console.log(`#${q.id} [${q.state}] ${q.header}`);
+        console.log(`Question: ${q.question}`);
+        console.log(`Default: ${q.default_answer}`);
+        if (q.options) {
+            console.log("Options:");
+            for (const option of q.options) {
+                console.log(`  ${option.label}${option.recommended ? " (Recommended)" : ""}: ${option.description}`);
+            }
+        }
+    }
+}
+function cmdAnswer(argv) {
+    const endOfFlags = argv.indexOf("--");
+    const optionArgs = endOfFlags === -1 ? argv : argv.slice(0, endOfFlags);
+    if (optionArgs.filter((arg) => arg === "--notes").length > 1) {
+        console.error("hive answer: --notes may be passed only once.");
+        process.exit(1);
+    }
+    const parsed = parseArgs(argv, { valued: ["--notes"] });
+    rejectUnknownFlags("answer", parsed, "--notes <text>");
+    requireFlagValues("answer", parsed);
+    if (parsed.values.has("--notes") && parsed.values.get("--notes") === undefined) {
+        console.error("hive answer: --notes requires a value.");
+        process.exit(1);
+    }
+    if (parsed.positional.length !== 2) {
+        console.error("hive answer: usage: hive answer <positive id> <one answer argument> [--notes <text>]");
+        process.exit(1);
+    }
+    const [rawId, answer] = parsed.positional;
+    if (!/^\d+$/.test(rawId) || !Number.isSafeInteger(Number(rawId)) || Number(rawId) <= 0) {
+        console.error(`hive answer: question id must be a positive safe integer, got ${JSON.stringify(rawId)}.`);
+        process.exit(1);
+    }
+    const project = resolveProjectForRead("answer");
+    const id = Number(rawId);
+    const receipt = answerQuestion(project.id, currentActor(), id, answer, parsed.values.get("--notes"));
+    console.log(`Question #${receipt.question_id} answered.`);
+    if (receipt.wake_id === null) {
+        console.log(`No wake queued: ${receipt.wake_skipped ?? "the asking session could not be reached"}.`);
+    }
+    else {
+        console.log(`Wake #${receipt.wake_id} queued for the asking session.`);
+    }
+}
 function cmdPads() {
     const project = resolveProjectForRead("pads");
     const pads = listActivePads(project.id);
@@ -3435,7 +3496,10 @@ if (command === "--version" || command === "-v") {
 const COMMANDS = [
     "lead", "queen", "queen-audit", "init", "attach", "start", "stop", "show", "hide", "status", "portfolio", "crew", "next", "setup", "upgrade", "doctor",
     LEAD_PANE_EXITED_VERB,
-    "pads", "pad", "todos", "todo", "backups", "restore", "project", "runbook", "posture", "profile", "kickoff", "statusline",
+    LEAD_HANDOFF_GRACE_VERB,
+    LEAD_HANDOFF_START_VERB,
+    "lead-handoff",
+    "pads", "pad", "todos", "todo", "questions", "answer", "backups", "restore", "project", "runbook", "posture", "profile", "kickoff", "statusline",
 ];
 if (!COMMANDS.includes(command)) {
     if (command.startsWith("--")) {
@@ -3475,6 +3539,15 @@ try {
         case LEAD_PANE_EXITED_VERB:
             cmdLeadPaneExited(rest);
             break;
+        case "lead-handoff":
+            process.exitCode = await cmdLeadHandoff(rest);
+            break;
+        case LEAD_HANDOFF_GRACE_VERB:
+            process.exitCode = await runHandoffGrace(rest);
+            break;
+        case LEAD_HANDOFF_START_VERB:
+            process.exitCode = await runHandoffStart(rest);
+            break;
         case "show":
             cmdShow(rest);
             break;
@@ -3517,6 +3590,12 @@ try {
         case "todo":
             cmdTodo(rest);
             break;
+        case "questions":
+            cmdQuestions(rest);
+            break;
+        case "answer":
+            cmdAnswer(rest);
+            break;
         case "backups":
             cmdBackups();
             break;

package/dist/context.js

@@ -24,7 +24,7 @@ export function currentActor() {
         return cachedActorId;
     }
     const envId = process.env.HIVE_AGENT_ID;
-    const id = envId ?? `user:${userInfo().username}`;
+    const id = envId ?? `${HUMAN_ACTOR_PREFIX}${userInfo().username}`;
     const name = process.env.HIVE_AGENT_NAME ?? id;
     const kind = envId ? "agent" : "human";
     db.prepare(`INSERT INTO actors (id, name, kind, tmux_pane) VALUES (?, ?, ?, ?)
@@ -330,6 +330,11 @@ export const QUEEN_REACH = {
     todo_unblock: "home",
     kv_set: "home",
     kv_delete: "home",
+    question_ask: "home",
+    question_get: "home",
+    question_list: "home",
+    question_update: "home",
+    question_answer: "home",
     lease_acquire: "home",
     lease_release: "home",
     agent_spawn: "home",
@@ -445,3 +450,4 @@ function queenRefusal(operation, targetProjectId, problem) {
         "queen may only todo_create, todo_comment, send text or wakes to its running lead, start its lead " +
         "with `hive lead <path>`, and run project_prune or `hive project rm` on it. Everything else there is its lead's to do.");
 }
+export const HUMAN_ACTOR_PREFIX = "user:";

package/dist/crew.js

@@ -5,6 +5,7 @@ import { awaitingFirstPrompt } from "./firstPrompt.js";
 import { heldReasonLabel } from "./heldLabel.js";
 import { harnessFor, paneClassifierFor } from "./harnesses.js";
 import { NEEDS_HUMAN_TAG } from "./portfolio.js";
+import { pendingQuestionCount } from "./questions.js";
 import { loadProjectYml } from "./projectYml.js";
 import { parseTags } from "./result.js";
 import { ACTIVE_TIMER_WHERE } from "./scheduler.js";
@@ -20,6 +21,8 @@ export function crewStoreProblem(database = db) {
     const columns = database.prepare("SELECT name FROM pragma_table_info('agents')").all();
     if (!columns.some((c) => c.name === "todo_id"))
         return "the store predates the worker-to-todo link (agents.todo_id)";
+    if (!tables.has("questions"))
+        return "the store has no questions table";
     return null;
 }
 function isoUtc(value) {
@@ -235,12 +238,26 @@ function tokenize(segment) {
     return tokens;
 }
 const ENV_ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+const SHELL_PREFIX_KEYWORDS = new Set(["if", "elif", "while", "until", "do", "then", "else", "!", "{"]);
+const SHELL_HEADER_KEYWORDS = new Set(["for", "select", "case"]);
+const SHELL_CLOSING_KEYWORDS = new Set(["done", "fi", "esac", "}"]);
 function toSegment(segment) {
     const tokens = tokenize(segment);
     let start = 0;
     while (start < tokens.length && ENV_ASSIGNMENT.test(tokens[start]))
         start++;
-    const rest = tokens.slice(start);
+    let rest = tokens.slice(start);
+    while (rest.length > 0) {
+        if (SHELL_HEADER_KEYWORDS.has(rest[0]) || SHELL_CLOSING_KEYWORDS.has(rest[0])) {
+            rest = [];
+            break;
+        }
+        if (!SHELL_PREFIX_KEYWORDS.has(rest[0]))
+            break;
+        rest = rest.slice(1);
+        while (rest.length > 0 && ENV_ASSIGNMENT.test(rest[0]))
+            rest = rest.slice(1);
+    }
     return { tokens: rest[0] === "cd" ? [] : rest, writes: writesToFile(segment) };
 }
 function segmentsOf(command) {
@@ -272,7 +289,7 @@ function matchesPrefix(tokens, matcher) {
     return tokens.length >= matcher.tokens.length && matcher.tokens.every((re, i) => re.test(tokens[i]));
 }
 const READING_EXES = new Set(["rg", "grep", "cat", "head", "tail", "sed"]);
-const FALLBACK_SKIP = new Set(["printf", "echo", "true", ":"]);
+const FALLBACK_SKIP = new Set(["printf", "echo", "true", ":", "[", "[[", "test"]);
 const NODE_RUNNERS = new Set(["npm", "pnpm", "yarn"]);
 const TEST_BINARIES = new Set(["pest", "phpunit", "vitest", "jest"]);
 const BUILD_BINARIES = new Set(["pint", "phpstan"]);
@@ -482,6 +499,7 @@ export function collectCrew(project, now) {
         read_at: now.toISOString(),
         lanes,
         needs_you: needsYou,
+        questions: { pending: pendingQuestionCount(project.id) },
         wakes: {
             pending: pending.length,
             next: pending[0]

package/dist/db.js

@@ -430,6 +430,145 @@ ALTER TABLE agent_messages ADD COLUMN sender_tag TEXT;
 CREATE INDEX idx_agent_messages_delivery ON agent_messages(delivery_status, id) WHERE delivery_status IS NOT NULL;
 `,
     `ALTER TABLE agents ADD COLUMN todo_id INTEGER REFERENCES todos(id) ON DELETE SET NULL;`,
+    `
+ALTER TABLE lead_turn_state ADD COLUMN snapshot_pane_pid TEXT NOT NULL DEFAULT '';
+ALTER TABLE lead_turn_state ADD COLUMN snapshot_session_id TEXT NOT NULL DEFAULT '';
+ALTER TABLE lead_turn_state ADD COLUMN prompt_seq INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE lead_turn_state ADD COLUMN human_prompt_seq INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE lead_turn_state ADD COLUMN human_prompt_at TEXT;
+ALTER TABLE lead_turn_state ADD COLUMN transcript_path TEXT NOT NULL DEFAULT '';
+ALTER TABLE lead_turn_state ADD COLUMN stop_prompt_seq INTEGER;
+ALTER TABLE lead_turn_state ADD COLUMN stop_background TEXT;
+ALTER TABLE lead_turn_state ADD COLUMN stop_at TEXT;
+
+CREATE TABLE lead_handoffs (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  project_id INTEGER NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  lead_agent_id INTEGER NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
+  pane_target TEXT NOT NULL,
+  tmux_socket TEXT NOT NULL DEFAULT '',
+  predecessor_pane_pid TEXT NOT NULL,
+  predecessor_session_id TEXT NOT NULL,
+  reason TEXT NOT NULL CHECK (reason IN ('warn', 'stop')),
+  state TEXT NOT NULL CHECK (state IN ('pending', 'wind_down', 'requested', 'grace', 'postponed',
+    'respawning', 'started', 'completed', 'failed', 'ambiguous')),
+  pass INTEGER NOT NULL DEFAULT 1,
+  request_reason TEXT CHECK (request_reason IN ('warn', 'stop')),
+  pass_started_at TEXT,
+  request_wake_id INTEGER,
+  attempt INTEGER NOT NULL DEFAULT 0,
+  owner_token TEXT,
+  owner_pid INTEGER,
+  grace_seconds INTEGER,
+  grace_started_at TEXT,
+  human_prompt_baseline INTEGER,
+  pad_id INTEGER,
+  pad_revision INTEGER,
+  pad_length INTEGER,
+  pad_sha256 TEXT,
+  respawn_claimed_at TEXT,
+  predecessor_turns INTEGER,
+  hold_since TEXT,
+  hold_released_at TEXT,
+  blocked_reason TEXT,
+  successor_pane_pid TEXT,
+  successor_session_id TEXT,
+  delivered_pad_id INTEGER,
+  delivered_pad_revision INTEGER,
+  started_at TEXT,
+  completed_at TEXT,
+  failure TEXT,
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%d %H:%M:%f', 'now')),
+  updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%d %H:%M:%f', 'now'))
+);
+CREATE UNIQUE INDEX idx_lead_handoffs_epoch
+  ON lead_handoffs(project_id, lead_agent_id, predecessor_pane_pid, predecessor_session_id);
+CREATE UNIQUE INDEX idx_lead_handoffs_active
+  ON lead_handoffs(lead_agent_id) WHERE state NOT IN ('completed', 'failed');
+`,
+    `
+CREATE TRIGGER fence_handoff_held_claim
+BEFORE UPDATE OF fire_count, delivery_method ON wakes
+FOR EACH ROW
+WHEN (NEW.fire_count > OLD.fire_count
+      OR (NEW.delivery_method IS 'pty-after-socket-timeout'
+          AND OLD.delivery_method IS NOT 'pty-after-socket-timeout'
+          AND NEW.typed_at IS NULL))
+  AND EXISTS (
+    SELECT 1 FROM lead_handoffs h
+     WHERE h.lead_agent_id = (SELECT a.id FROM agents a
+                               WHERE a.actor_id = NEW.deliver_actor
+                               ORDER BY (a.status = 'running') DESC,
+                                        a.id DESC
+                               LIMIT 1)
+       AND h.state NOT IN ('completed', 'failed')
+       AND h.request_wake_id IS NOT NEW.id
+       AND (h.state = 'grace'
+            OR (h.hold_released_at IS NULL AND (
+                  h.state IN ('respawning', 'ambiguous', 'wind_down')
+                  OR (h.state = 'requested'
+                      AND (h.reason = 'stop' OR h.pass >= 2))
+                  OR (h.state = 'postponed' AND h.reason = 'stop'))))
+       AND (julianday('now') - julianday(h.updated_at)) * 86400 < 3600)
+BEGIN
+  SELECT RAISE(IGNORE);
+END;
+`,
+    `DROP TRIGGER fence_handoff_held_claim;`,
+    `
+CREATE TRIGGER fence_handoff_held_claim
+BEFORE UPDATE OF fire_count, delivery_method ON wakes
+FOR EACH ROW
+WHEN (NEW.fire_count > OLD.fire_count
+      OR (NEW.delivery_method IS 'pty-after-socket-timeout'
+          AND OLD.delivery_method IS NOT 'pty-after-socket-timeout'
+          AND NEW.typed_at IS NULL))
+  AND EXISTS (
+    SELECT 1 FROM lead_handoffs h
+     WHERE h.lead_agent_id = (SELECT a.id FROM agents a
+                               WHERE a.actor_id = NEW.deliver_actor
+                               ORDER BY (a.status = 'running') DESC,
+                                        a.id DESC
+                               LIMIT 1)
+       AND h.state NOT IN ('completed', 'failed')
+       AND h.request_wake_id IS NOT NEW.id
+       AND (h.state IN ('grace', 'started')
+            OR (h.hold_released_at IS NULL AND (
+                  h.state IN ('respawning', 'ambiguous', 'wind_down')
+                  OR (h.state = 'requested'
+                      AND (h.reason = 'stop' OR h.pass >= 2))
+                  OR (h.state = 'postponed' AND h.reason = 'stop'))))
+       AND (julianday('now') - julianday(h.updated_at)) * 86400 < 3600)
+BEGIN
+  SELECT RAISE(IGNORE);
+END;
+`,
+    `
+CREATE TABLE questions (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  project_id INTEGER NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  asker TEXT NOT NULL,
+  kind TEXT NOT NULL CHECK (kind IN ('choice', 'free_text')),
+  question TEXT NOT NULL CHECK (trim(question) != ''),
+  header TEXT NOT NULL CHECK (trim(header) != ''),
+  options TEXT,
+  default_answer TEXT NOT NULL CHECK (trim(default_answer) != ''),
+  ref_kind TEXT CHECK (ref_kind IN ('todo', 'pr')),
+  ref_number INTEGER CHECK (ref_number > 0),
+  state TEXT NOT NULL DEFAULT 'pending' CHECK (state IN ('pending', 'answered', 'defaulted', 'withdrawn')),
+  answer TEXT,
+  notes TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_by TEXT NOT NULL,
+  answered_by TEXT,
+  CHECK ((ref_kind IS NULL) = (ref_number IS NULL)),
+  CHECK ((kind = 'choice') = (options IS NOT NULL))
+);
+CREATE UNIQUE INDEX idx_questions_pending_ref ON questions(project_id, ref_kind, ref_number)
+  WHERE state = 'pending' AND ref_kind IS NOT NULL;
+CREATE INDEX idx_questions_project_state ON questions(project_id, state, id);
+`,
 ];
 export function storeSchemaAhead(database) {
     try {

package/dist/help.js

@@ -40,6 +40,9 @@ KV — small shared status values (with optional TTL)
 LEASES — advisory expiring claims on shared state
   lease_acquire, lease_release
 
+QUESTIONS — open questions for the human, recorded in the store
+  question_ask, question_get, question_list, question_update, question_answer
+
 PROJECTS — scope management
   project_list, project_add, project_select, project_prune
 
@@ -246,6 +249,9 @@ Delivery contract:
   and the next action. Plain English, no markup.
   Waking your OWN lead pane is the exception: it is not cold, so carry the
   action and the ids and point at where the detail lives.
+  With lead_turn_budget.auto_handoff on, a lead past its warn budget gets
+  a "hive lead handoff request #N" wake: follow its steps, then run
+  hive lead-handoff. A human prompt during the grace postpones it.
 
 Receiving wake-ups:
   Spawned workers can always receive (deliver_to their name or id).
@@ -378,6 +384,27 @@ todo_list without marking anything done.`,
 
 Use kv for values another session needs to discover: current branch, a port,
 a phase flag. Use pads for anything longer than a line or two.`,
+    questions: `QUESTIONS — open questions for the human, recorded in the store
+
+  question_ask(kind, question, header, default_answer, options?, ref?) —
+    record a question. kind=choice takes 2-4 options (label, description,
+    recommended; exactly one recommended, and default_answer is its label).
+    kind=free_text takes no options. header is 12 characters or fewer. ref
+    ({kind: "todo"|"pr", number}) is the dedupe key: asking again with a ref
+    that has a pending question in this project updates that row. The
+    receipt lists similar pending questions so you can question_update one.
+  question_get(question_id) — one question, any state, with its answer
+  question_list() — pending questions, then defaulted ones, oldest first
+  question_update(question_id, ...) — edit a pending question's text, or set
+    state to defaulted (you acted on your default) or withdrawn (moot)
+  question_answer(question_id, answer, notes?) — record the human's answer
+    to a pending or defaulted question
+
+hive stores the question; it never puts it to the human. Render it in your
+own turn. Answering queues a wake to the asker carrying the question,
+answer and notes, unless the answerer is the asker or the asker cannot be
+reached; the answer is kept either way. Nothing expires or defaults on its
+own: only the asker or the human moves a question out of pending.`,
     leases: `LEASES — advisory expiring claims on shared state
 
   lease_acquire(key, ttl_seconds) — non-blocking; returns the holder if