@shanesaravia/hive 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to Hive will be documented in this file.
 
+## 0.2.0 — 2026-08-25
+
+Adds the visual office, a second presentation of the same fleet state alongside the existing cards.
+
+### Highlights
+
+- Global **Cards | Office** presentation switch, with both views reading one shared fleet snapshot
+- Spatial headquarters with a shared Direct studio, per-mission orchestration rooms, a Review hall, hallways, and an elevator, plus deterministic overflow floors
+- Stable, ID-derived room, desk, and avatar assignment that costs no model tokens
+- Direct manipulation throughout: desks, managers, workers, rooms, and notices open the mission, worker, or tab they represent
+- Mission details available in room view without leaving the office, with Conversation as the default panel
+- Spatial search and filtering, dimming direct and review seats independently while orchestration missions filter by room
+- Living office behavior for working, typing, thinking, idle, waiting, blocked, failed, reviewing, and paused states, with status-aware desks, monitors, and room lighting
+- Manager and worker lifecycle movement — entrances, delegation, worker-to-manager handoffs, review transfers, and exits — ordered by per-identity FIFO transition queues
+- Factual speech, ambient thought, alert, and output dialogue whose cadence scales with floor activity
+- System, Reduced, and Full motion modes with configurable dialogue settings
+- Guided mission launch and plan approval, refined mission controls, and live provider skill discovery
+
+### Fixed
+
+- Fleet and detail room views share transition state, so entering a room no longer replays a completed animation
+- Room lighting, chat continuity, and startup transitions no longer flash stale state on arrival or reload
+
+## 0.1.1 — 2026-08-23
+
+- Add `hive update`, with read-only checks, interactive or unattended installation, setup refresh, and automatic restart of an active local server.
+
 ## 0.1.0 — 2026-08-23
 
 Initial public preview of Hive, a provider-neutral local mission-control interface for Claude Code, Codex, and agent fleets.
@@ -14,4 +41,5 @@ Initial public preview of Hive, a provider-neutral local mission-control interfa
 - Mission health, lifecycle, recovery, policies, budgets, templates, notifications, and searchable history
 - Repository-aware working directories, skills, MCP configuration, and Git worktrees where supported
 - Installable `hive` CLI with diagnostics, optional setup, persistent local state, and graceful lifecycle commands
+- Browser-origin enforcement protecting the loopback control API and WebSocket from foreign websites
 - Verified npm artifact across macOS and Ubuntu on Node.js 20 and 22

package/README.md

@@ -7,7 +7,13 @@
 
 [![Release verification](https://github.com/shanesaravia/hive/actions/workflows/release-verification.yml/badge.svg)](https://github.com/shanesaravia/hive/actions/workflows/release-verification.yml)
 
-![Hive fleet dashboard showing provider-tagged missions, live status, worker counts, token usage, health alerts, search, and filters](docs/assets/hive-fleet-dashboard.png)
+### Cards dashboard
+
+![Hive Cards dashboard showing provider-tagged missions, direct mission controls, live status, worker counts, token usage, search, and filters](docs/assets/hive-cards-dashboard.png)
+
+### Visual office
+
+![Hive Visual Office showing the shared direct studio, orchestration rooms, managers, workers, review hall, elevator, and live room state](docs/assets/hive-visual-office.png)
 
 ## What Hive is
 
@@ -33,6 +39,10 @@ Hive does not resell model access or replace provider authentication. It gives l
 - Direct and orchestrated execution modes for either provider
 - Per-mission Claude Code or Codex provider and model selection
 - Provider model discovery from the locally installed CLIs
+- Switchable **Cards** and deterministic 2.5D **Office** presentations backed by the same live mission state
+- Multi-floor visual capacity with a shared direct studio, orchestration rooms, review hall, and off-floor arrival notices
+- Clickable rooms, managers, workers, and direct desks with spatial mission drill-down
+- Token-free avatar identity, entrances/exits, live posture, monitor state, room lighting, dialogue, and worker handoffs
 - Structured phased plans, weighted progress, dependency graphs, revisions, and evidence
 - Parallel worker visibility, assignments, elapsed time, activity, token usage, changed files, tests, and outputs
 - Separate mission lifecycle and runtime activity states
@@ -41,6 +51,7 @@ Hive does not resell model access or replace provider authentication. It gives l
 - User-controlled Pause, Resume, Complete, Reopen, Archive, manager handoff, task retry, cancellation, reassignment, and reprioritization
 - Orchestrator-proposed **Awaiting acceptance** state
 - Completion gates with verification evidence, explicit waivers, and user acceptance
+- Optional **Plan first** workflow that requires approval before implementation and worker fan-out
 - Reusable built-in, user, and repository mission templates with a visual editor
 - Workspace and mission policies, permissions, worker/token/time budgets, and usage projections
 - Semantic activity feed plus parallel manager/worker timeline
@@ -120,12 +131,23 @@ Useful commands:
 | `hive status` | Report whether Hive is running and its local address. |
 | `hive open` | Open an already-running dashboard. |
 | `hive stop` | Gracefully stop Hive. |
+| `hive update --check` | Check npm for a newer Hive release without changing anything. |
+| `hive update` | Confirm and install the latest release, refreshing setup and restarting Hive when needed. |
+| `hive update --yes` | Install the latest release without an interactive confirmation. |
 | `hive --version` | Show the installed version. |
 
 ## Update or uninstall
 
 Update to the newest release:
 
+```bash
+hive update
+```
+
+Use `hive update --check` for a read-only version check or `hive update --yes` to skip confirmation. If Hive is running, the updater stops it gracefully and restarts it on the same port after installation. It also refreshes Hive's additive provider setup. Mission history and configuration remain in the platform data directory.
+
+You can still update directly through npm if the installed Hive command is unavailable:
+
 ```bash
 npm install --global @shanesaravia/hive@latest
 ```
@@ -140,13 +162,18 @@ Uninstalling the npm package intentionally retains mission history, configuratio
 
 ## Create a mission
 
+For a focused direct task, the fleet's quick-start bar provides provider and model selectors and uses worktree isolation when the selected Claude repository supports it. If the task needs parallel workers, switch to orchestrated setup; Hive carries the entered prompt into the full **New mission** flow with the cursor preserved at the end.
+
+Use **New mission** when you want the full configuration:
+
 1. Select **New mission**.
 2. Enter the intended working directory. Absolute paths and paths beginning with `~` are supported; matching local folders appear as you type.
 3. Choose **Claude** or **Codex**, then optionally select a model. Leaving model blank uses that CLI's configured default.
 4. Choose **Direct** or **Orchestrated** mode.
 5. Describe the task and optionally provide a mission name.
-6. For Claude missions, choose whether to work in a new Git worktree. Codex missions currently use Codex's workspace-write sandbox in the selected repository; Hive-created Codex worktrees are not yet available.
-7. Start the mission and open its card to follow progress or continue the conversation.
+6. Configure launch behavior: Claude worktree isolation, optional **Plan first** approval for orchestrated missions, and any template.
+7. Expand **Advanced settings** when the mission needs policy overrides or worker, concurrency, token, or time budgets.
+8. Start the mission. You can follow it from either the Cards dashboard or visual Office without changing its underlying state.
 
 The selected working directory matters. The provider CLI is launched from that directory so it can resolve the same repository instructions, configuration, MCP servers, and skills it would see when launched manually there.
 
@@ -154,7 +181,9 @@ The selected working directory matters. The provider CLI is launched from that d
 
 Open a mission card and send a follow-up from the Conversation panel. Both providers preserve their native conversation/thread identity while Hive records each turn under the same durable mission.
 
-For Claude missions, type `/` in either the new-mission prompt or an existing conversation to search registered project, user, plugin, and built-in skills. Recognized skills are highlighted and sent as ordinary prompt text, leaving Claude Code responsible for skill execution and permissions. Hive discovers skill metadata only; it does not preload entire skill bodies into mission context.
+Type `/` in either the new-mission prompt or an existing conversation to search the skills available to that provider in the selected working directory. Hive reads Claude skills for Claude missions and Codex skills for Codex missions; slash-form Codex selections are translated to the provider's native invocation form behind the scenes. Recognized skills are highlighted and sent as ordinary prompt text, leaving the provider CLI responsible for execution and permissions. Hive discovers skill metadata only; it does not preload entire skill bodies into mission context.
+
+If a provider or deliberately interactive skill asks a structured question, Hive surfaces it in **Needs you** and the mission conversation. Answering there resumes the same mission; skill prompts are not silently bypassed.
 
 ## Navigate the fleet
 
@@ -166,19 +195,38 @@ The fleet is organized around attention rather than process creation time:
 
 Search covers mission names, conversations, plans, workers, files, errors, decisions, evidence, and outputs. Filters are available for lifecycle/activity status, repository, template, and date. Claude sessions started outside Hive appear separately as discovered local sessions; they can be adopted, stopped, or hidden without pretending they are already durable Hive missions.
 
+### Use the visual office
+
+Use the global **Cards | Office** control to switch presentation. The choice is remembered locally and follows you into mission details, so the visual workflow does not unexpectedly send you back to the data dashboard.
+
+The office is a second presentation of the same mission data, not a simulation or separate runtime:
+
+- A desk in the shared **Direct studio** represents one direct mission. Select a desk to open that mission, or select the studio itself for its aggregate worker list and bulk **Clear completed desks** action.
+- An **orchestration room** represents one orchestrated mission. The manager has a distinct position and appearance; each active worker receives a stable desk and can be opened directly.
+- Managers move to the shared **Review hall** when their missions reach **Awaiting acceptance**. Selecting an occupant opens the corresponding mission.
+- Headquarters contains the direct studio, orchestration rooms, and review hall. Additional operations floors are allocated deterministically when orchestration capacity fills; off-floor arrivals are called out without pulling you away from the floor you are viewing.
+- Search and filters dim nonmatching rooms or individual direct/review seats while retaining spatial context.
+
+Room plaques and avatar/desk hover states expose mission identity. Room lighting, desk accents, monitor symbols, postures, and bubbles communicate observed activity, waiting, failure, review, and occupancy. Entrances, exits, elevator travel, and worker-to-manager handoffs are driven by a local FIFO presentation queue so backend events remain ordered and do not spend model tokens.
+
+Office controls let you follow the operating-system motion preference or explicitly reduce/enable motion, and choose how much work/personality dialogue appears. Dialogue cadence scales with floor occupancy to keep quiet floors alive without covering the workspace in bubbles.
+
 ## Understand a mission
 
-Each mission has four primary views:
+Each mission has five primary views in the standard details presentation. The spatial room presentation exposes the same controls and panels beside the room, with **Conversation** selected by default:
 
 | View | What it shows |
 | --- | --- |
 | Conversation | The durable user/orchestrator thread across all provider turns |
-| Plan & workers | Goal, current work, next work, blockers, phased plan, dependencies, gates, evidence, budgets, skills, workers, and outputs |
+| Plan | Goal, current work, next work, blockers, phased plan, dependencies, gates, evidence, and weighted progress |
+| Workers | Manager/worker roster, assignments, runtime state, timing, tools, files, outputs, and worker controls |
 | Activity | A semantic event feed or parallel timeline for the manager and workers |
 | Technical | Provider job history, bounded handoff context, policies, and mission-report export |
 
 Worker rows open a detail drawer containing the assignment, role, current tool/command, files read or changed, tests, artifacts, timing, tokens, termination state, and task-specific controls. Runtime job IDs remain available for diagnosis without becoming the mission's product identity.
 
+Mission names can be edited from either presentation. Renaming changes Hive's durable mission label without pretending to rename an already-running provider job or breaking the underlying conversation.
+
 ## Plans, progress, and dependencies
 
 For non-trivial work, orchestrators publish a structured plan with phases, milestones, tasks, optional subtasks, dependencies, owners, weights, blockers, acceptance criteria, and evidence. Hive then derives progress from completed task weights rather than asking an LLM to estimate a percentage.
@@ -193,7 +241,7 @@ The plan begins with:
 
 Use **Plan** for the readable phased workflow and **Dependencies** for the interactive work graph and critical path. Completed and future phases collapse by default, task operational details are expandable, and dependency IDs are translated into task names.
 
-An optional plan checkpoint appears only before execution begins. It lets you approve the proposed approach or request changes, but autonomous missions do not require that checkpoint. Once any work starts, stale plan-approval controls disappear. This is separate from accepting the completed mission.
+Enable **Plan first** when creating an orchestrated mission to require a pre-implementation checkpoint. The manager publishes the proposal and waits; approving it from the Plan view or global decision inbox records the same decision and resumes implementation. Requesting changes returns feedback to the manager. Missions created without this option remain autonomous, and stale approval controls disappear once implementation starts. Plan approval is separate from accepting a completed mission.
 
 ## Completion and acceptance
 
@@ -280,7 +328,10 @@ Orchestrated managers cannot directly edit files: Hive launches them with `Edit`
 
 ```text
 Browser UI (React + Vite)
-        │ REST + WebSocket
+        │
+        ├── Cards dashboard
+        ├── deterministic SVG visual office
+        └── REST + WebSocket
 Hive server (Fastify)
         │
         ├── adapts Claude and Codex runtime state into provider-neutral turns
@@ -358,7 +409,11 @@ npm run hive -- serve
 npm run hive -- orchestrator start "<task>" [--worktree] [--name <name>]
 ```
 
-The product roadmap and completion checklist live in [`docs/IMPROVEMENTS.md`](docs/IMPROVEMENTS.md).
+Project planning is split by scope:
+
+- [`docs/IMPROVEMENTS.md`](docs/IMPROVEMENTS.md) — core product roadmap and completion checklist
+- [`docs/VISUAL_OFFICE_PLAN.md`](docs/VISUAL_OFFICE_PLAN.md) — completed visual-office foundation
+- [`docs/VISUAL_OFFICE_FEEL_ALIVE_PLAN.md`](docs/VISUAL_OFFICE_FEEL_ALIVE_PLAN.md) — current and upcoming atmosphere, interaction, and polish phases
 
 ## Troubleshooting
 
@@ -396,7 +451,7 @@ This means the mission remains unfinished while Hive sees no meaningful runtime
 
 ### Accept & complete says completion gates remain
 
-Open **Plan & workers** and inspect Completion gates. Tests, CI, review, documentation, and other technical gates must be satisfied or waived with a reason. A pending user-approval gate is satisfied automatically by **Accept & complete** and should not block that action.
+Open **Plan** and inspect Completion gates. Tests, CI, review, documentation, and other technical gates must be satisfied or waived with a reason. A pending user-approval gate is satisfied automatically by **Accept & complete** and should not block that action.
 
 ### Data after a restart
 
@@ -408,6 +463,8 @@ Restart Hive with `hive`, then reopen the same mission card. Hive reloads durabl
 - Codex uses its workspace-write sandbox in the selected repository; Hive-created Codex worktrees are not yet available.
 - Claude hooks provide richer tool-level evidence than providers or workers that do not emit equivalent structured events.
 - Policies and budgets combine launch-time enforcement with orchestrator guidance; they are not a substitute for operating-system isolation.
+- The visual office is a deterministic status presentation, not a claim that agents are physically active; snapshot state remains authoritative and animation yields to accessibility preferences.
+- Mission artifacts, shared hallway events beyond lifecycle/handoffs, an activity ticker, ambient sound, and celebrations remain planned visual-office polish rather than current functionality.
 - Optional multi-mission initiatives remain intentionally deferred. A mission is the primary durable unit of work.
 
 ## Project status

package/dist/bin/hive.js

@@ -3,6 +3,7 @@ import { spawn, spawnSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { createInterface } from "node:readline/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
 const currentFile = fileURLToPath(import.meta.url);
 const sourceMode = currentFile.endsWith(".ts");
@@ -132,6 +133,42 @@ export function parseStartOptions(args) {
     }
     return { port, open };
 }
+export function parseUpdateOptions(args) {
+    const options = { check: false, assumeYes: false };
+    for (const arg of args) {
+        if (arg === "--check")
+            options.check = true;
+        else if (arg === "--yes")
+            options.assumeYes = true;
+        else
+            throw new Error(`Unknown update option: ${arg}`);
+    }
+    if (options.check && options.assumeYes) {
+        throw new Error("Use either `hive update --check` or `hive update --yes`, not both.");
+    }
+    return options;
+}
+export function compareVersions(left, right) {
+    const parse = (value) => {
+        const match = value.trim().replace(/^v/, "").match(/^(\d+)\.(\d+)\.(\d+)(?:-([^+]+))?/);
+        if (!match)
+            throw new Error(`Invalid package version: ${value}`);
+        return { numbers: match.slice(1, 4).map(Number), prerelease: match[4] };
+    };
+    const a = parse(left);
+    const b = parse(right);
+    for (let index = 0; index < a.numbers.length; index++) {
+        if (a.numbers[index] !== b.numbers[index])
+            return a.numbers[index] < b.numbers[index] ? -1 : 1;
+    }
+    if (a.prerelease === b.prerelease)
+        return 0;
+    if (!a.prerelease)
+        return 1;
+    if (!b.prerelease)
+        return -1;
+    return a.prerelease.localeCompare(b.prerelease);
+}
 function readRuntimeState() {
     try {
         const state = JSON.parse(fs.readFileSync(runtimePath(), "utf8"));
@@ -352,6 +389,124 @@ async function runStop() {
     clearRuntimeState(state.pid);
     console.log("Hive stopped.");
 }
+function npmExecutable() {
+    return process.platform === "win32" ? "npm.cmd" : "npm";
+}
+function latestPackageVersion() {
+    const result = spawnSync(npmExecutable(), ["view", "@shanesaravia/hive@latest", "version", "--json"], {
+        encoding: "utf8",
+        timeout: 30_000,
+    });
+    if (result.error || result.status !== 0) {
+        const detail = result.error?.message ?? result.stderr.trim() ?? "npm registry request failed";
+        throw new Error(`Could not check for Hive updates: ${detail}`);
+    }
+    const output = result.stdout.trim();
+    try {
+        const parsed = JSON.parse(output);
+        if (typeof parsed === "string")
+            return parsed;
+    }
+    catch {
+        if (output)
+            return output;
+    }
+    throw new Error("Could not read the latest Hive version from npm.");
+}
+async function confirmUpdate(current, latest) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new Error("Confirmation requires an interactive terminal. Re-run with `hive update --yes`.");
+    }
+    const prompt = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await prompt.question(`Update Hive ${current} → ${latest}? [y/N] `);
+        return /^(y|yes)$/i.test(answer.trim());
+    }
+    finally {
+        prompt.close();
+    }
+}
+async function waitForRuntime(port, timeoutMs = 12_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (await health(port))
+            return;
+        await new Promise((resolve) => setTimeout(resolve, 150));
+    }
+    throw new Error(`Hive did not restart on port ${port} within ${timeoutMs / 1000} seconds.`);
+}
+async function relaunchUpdatedHive(port) {
+    const child = spawn(process.execPath, [currentFile, "start", "--port", String(port), "--no-open"], {
+        detached: true,
+        stdio: "ignore",
+    });
+    child.unref();
+    await waitForRuntime(port);
+    console.log(`Hive restarted at http://127.0.0.1:${port}`);
+}
+async function runUpdate(args) {
+    const options = parseUpdateOptions(args);
+    if (sourceMode) {
+        throw new Error("`hive update` is only available from the globally installed CLI. Update a source checkout with Git instead.");
+    }
+    const current = packageVersion();
+    const latest = latestPackageVersion();
+    const comparison = compareVersions(current, latest);
+    if (comparison >= 0) {
+        console.log(comparison === 0
+            ? `Hive ${current} is already the latest version.`
+            : `Hive ${current} is newer than the npm latest version (${latest}).`);
+        return;
+    }
+    console.log(`Hive ${latest} is available (installed: ${current}).`);
+    if (options.check)
+        return;
+    if (!options.assumeYes && !(await confirmUpdate(current, latest))) {
+        console.log("Update cancelled.");
+        return;
+    }
+    const state = readRuntimeState();
+    const wasRunning = Boolean(state && processExists(state.pid));
+    const restartPort = state?.port ?? defaultPort;
+    if (wasRunning)
+        await runStop();
+    let updateError;
+    try {
+        const install = spawnSync(npmExecutable(), ["install", "--global", "@shanesaravia/hive@latest"], { stdio: "inherit" });
+        if (install.error || install.status !== 0) {
+            throw new Error(install.error?.message ?? `npm install exited with code ${install.status ?? "unknown"}`);
+        }
+        const installed = spawnSync(process.execPath, [currentFile, "--version"], { encoding: "utf8" });
+        if (installed.error || installed.status !== 0) {
+            throw new Error("Hive was installed, but the updated CLI could not be verified.");
+        }
+        const installedVersion = installed.stdout.trim();
+        if (compareVersions(installedVersion, latest) < 0) {
+            throw new Error(`npm completed, but Hive ${installedVersion} is still installed; expected ${latest}.`);
+        }
+        const setup = spawnSync(process.execPath, [currentFile, "setup", "--yes"], { stdio: "inherit" });
+        if (setup.error || setup.status !== 0) {
+            throw new Error("Hive updated, but provider setup could not be refreshed. Run `hive setup --yes` manually.");
+        }
+        console.log(`Hive updated successfully: ${current} → ${installedVersion}`);
+    }
+    catch (error) {
+        updateError = error;
+    }
+    if (wasRunning) {
+        try {
+            await relaunchUpdatedHive(restartPort);
+        }
+        catch (restartError) {
+            if (updateError) {
+                throw new Error(`${updateError.message} Hive also failed to restart: ${restartError.message}`);
+            }
+            throw restartError;
+        }
+    }
+    if (updateError)
+        throw updateError;
+}
 function commandVersion(command) {
     const result = spawnSync(command, ["--version"], { encoding: "utf8", timeout: 3_000 });
     if (result.error || result.status !== 0)
@@ -453,6 +608,7 @@ Usage:
   hive status                              Show whether Hive is running
   hive open                                Open the running dashboard
   hive stop                                Gracefully stop a recorded Hive server
+  hive update [--check] [--yes]            Check for or install the latest release
   hive --version                           Print the installed version
   hive --help                              Show this help
 
@@ -471,6 +627,7 @@ export async function main(argv = process.argv.slice(2)) {
         case "status": return runStatus();
         case "open": return runOpen();
         case "stop": return runStop();
+        case "update": return runUpdate(args);
         case "--version":
         case "-v":
             console.log(packageVersion());

package/node_modules/@hive/shared/dist/directStudio.d.ts

@@ -0,0 +1,7 @@
+import type { OrchestratorNode } from "./types.js";
+/**
+ * A deliberately conservative definition of an idle Direct Studio desk.
+ * Bulk cleanup must never accept gates or dismiss a mission that still needs
+ * work or user attention.
+ */
+export declare function canClearDirectStudioMission(node: OrchestratorNode): boolean;

package/node_modules/@hive/shared/dist/directStudio.js

@@ -0,0 +1,17 @@
+const CLEARABLE_ACTIVITY = new Set(["idle", "done", "offline"]);
+/**
+ * A deliberately conservative definition of an idle Direct Studio desk.
+ * Bulk cleanup must never accept gates or dismiss a mission that still needs
+ * work or user attention.
+ */
+export function canClearDirectStudioMission(node) {
+    if (node.mission.mode !== "direct" || node.lifecycleStatus !== "active")
+        return false;
+    if (!CLEARABLE_ACTIVITY.has(node.activityStatus) || node.inFlight.tasks > 0 || node.inFlight.queued > 0)
+        return false;
+    if (node.workers.some((worker) => !worker.doneAt && (worker.jobState === "working" || worker.jobState === "busy")))
+        return false;
+    if (node.alerts.length > 0)
+        return false;
+    return !(node.plan?.gates ?? []).some((gate) => gate.required && gate.status !== "satisfied" && gate.status !== "waived");
+}

package/node_modules/@hive/shared/dist/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./types.js";
 export * from "./status.js";
+export * from "./directStudio.js";

package/node_modules/@hive/shared/dist/index.js

@@ -1,2 +1,3 @@
 export * from "./types.js";
 export * from "./status.js";
+export * from "./directStudio.js";

package/node_modules/@hive/shared/dist/status.d.ts

@@ -6,7 +6,7 @@ import type { ClaudeJob, ClaudeSession, DerivedStatus, HiveEvent } from "./types
  * since that's the one case pure file-watching can otherwise miss (the
  * process died without a clean shutdown).
  */
-export declare function deriveStatus(session: ClaudeSession | undefined, job: ClaudeJob | undefined, recentEvents?: HiveEvent[]): {
+export declare function deriveStatus(session: ClaudeSession | undefined, job: ClaudeJob | undefined, recentEvents?: HiveEvent[], now?: number): {
     status: DerivedStatus;
     stale: boolean;
 };

package/node_modules/@hive/shared/dist/status.js

@@ -1,4 +1,5 @@
 const STALE_JOB_STATES = new Set(["working", "busy"]);
+const JOB_SESSION_STARTUP_GRACE_MS = 15_000;
 /**
  * Pure status derivation — no network/LLM calls. Joins the raw session/job
  * records already on disk. A job still marked "working" with no matching
@@ -6,7 +7,7 @@ const STALE_JOB_STATES = new Set(["working", "busy"]);
  * since that's the one case pure file-watching can otherwise miss (the
  * process died without a clean shutdown).
  */
-export function deriveStatus(session, job, recentEvents = []) {
+export function deriveStatus(session, job, recentEvents = [], now = Date.now()) {
     // The daemon's idle notification ("Claude is waiting for your input") fires
     // after every completed turn — it means "session idle", not "the assistant
     // asked you something", so it must not read as waiting_on_you. Permission
@@ -21,6 +22,14 @@ export function deriveStatus(session, job, recentEvents = []) {
     const latestEventTs = recentEvents.at(-1)?.ts ?? 0;
     const blockedEventIsCurrent = blockedEvent !== undefined && blockedEvent.ts >= latestEventTs;
     if (!session && job && STALE_JOB_STATES.has(job.state)) {
+        // Claude publishes a resumed background job before its matching live
+        // session record. Keep that normal startup gap in "working" instead of
+        // briefly presenting a failed mission. Truly orphaned jobs still become
+        // stale errors when this short grace period expires.
+        const createdAt = job.createdAt ? Date.parse(job.createdAt) : NaN;
+        if (Number.isFinite(createdAt) && Math.max(0, now - createdAt) < JOB_SESSION_STARTUP_GRACE_MS) {
+            return { status: "working", stale: false };
+        }
         return { status: "error", stale: true };
     }
     if (!session) {
@@ -29,12 +38,15 @@ export function deriveStatus(session, job, recentEvents = []) {
     if (session.status === "waiting") {
         return { status: "waiting_on_you", stale: false };
     }
-    if (job?.state === "blocked") {
-        return { status: "waiting_on_you", stale: false };
-    }
-    // Mid-turn park: a permission prompt keeps state "working" but the daemon
-    // flips tempo to blocked and puts the ask in needs ("approve Bash: …").
-    if (job?.tempo === "blocked" && job.needs) {
+    // Claude also labels conversational closing questions such as "Anything
+    // else?" as blocked. Those are completed, optional follow-up turns—not
+    // actionable decisions. Treat the provider block as authoritative only
+    // when it carries a permission ask, explicit choices, or a current
+    // structured blocked_on_user event.
+    const actionableProviderBlock = Boolean(job?.needs && (/^approve\s/i.test(job.needs)
+        || (job.promptChoices?.length ?? 0) > 0
+        || blockedEventIsCurrent));
+    if ((job?.state === "blocked" || job?.tempo === "blocked") && actionableProviderBlock) {
         return { status: "waiting_on_you", stale: false };
     }
     // A busy session outranks event-inferred waiting: the runtime is provably

package/node_modules/@hive/shared/dist/types.d.ts

@@ -48,6 +48,8 @@ export interface ClaudeJob {
     fan: JobFanEntry[];
     tokens?: number;
     needs?: string;
+    /** Structured choices for a provider prompt parked by Hive. */
+    promptChoices?: string[];
     output?: unknown;
     /**
      * Hive-augmented (not part of the daemon's state.json): the latest assistant
@@ -105,6 +107,8 @@ export interface MissionSummary {
     policy?: MissionPolicy;
     provider?: MissionProvider;
     model?: string;
+    /** Require explicit user approval of the proposed plan before implementation or worker delegation begins. */
+    planFirst?: boolean;
     /** Repositories beyond the working directory this mission also touches; each grants --add-dir access on every turn. */
     additionalRepositories?: string[];
 }
@@ -230,6 +234,7 @@ export interface CompletionGate {
     status: CompletionGateStatus;
     required: boolean;
     evidence: string[];
+    source?: "orchestrator" | "template" | "user";
     waiver?: {
         reason: string;
         waivedAt: number;

package/node_modules/@hive/shared/package.json

@@ -10,9 +10,12 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "test": "tsx --test src/*.test.ts",
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
     "typescript": "^5.6.0"
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shanesaravia/hive",
   "private": false,
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Provider-neutral local mission control for Claude Code, Codex, and agent fleets.",
   "license": "MIT",