@shanesaravia/hive 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 All notable changes to Hive will be documented in this file.
 
+## 0.2.1 — 2026-08-25
+
+### Added
+
+- Plan tab shows a "Phases" / "Tasks" section header, clarifying that task numbers are global across phases.
+- Pending decisions appear in the top notice slot as a compact strip and slide-over, visible from every tab and both presentations, replacing the Conversation-tab-only placement.
+- Office desks are click targets that behave exactly like their avatar, across manager, worker, and direct seats in both the fleet floor and the mission room.
+- Shared `DetailDrawer` shell so worker inspection and pending decisions match in width, background, header rhythm, and dismissal.
+
+### Changed
+
+- Mission room collapses its goal to one line, compacts summary tiles, drops duplicate side-panel titles, and lets the room and chat grow with the viewport, adding roughly 100px of chat at 900px tall and 320px on tall displays.
+- Widened the mission room viewBox so the whole floor stays inside the canvas, with height capped to avoid empty canvas beneath it.
+
+### Fixed
+
+- Reclaim a mission's worktree and branch when it is deleted, archived, or completed, instead of leaving every worktree-isolated mission behind on disk forever. Completion keeps a worktree that holds uncommitted changes, since a follow-up message reopens a completed mission and **Clear completed desks** completes many at once.
+- Resume a reopened mission in its base repository when its worktree has already been reclaimed, rather than resuming into a path that no longer exists.
+- An unanswered decision keeps a mission in `waiting_on_you` instead of decaying to idle or stalled once the session record goes quiet, so office lighting, desks, status pill, and the attention badge stay in agreement.
+- Suppressed the duplicate "Waiting for your reply" banner when a structured decision already covers it.
+
+## 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.

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
@@ -151,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.
 
@@ -165,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
 
@@ -177,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.
@@ -204,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
 
@@ -274,6 +311,20 @@ Hive deliberately separates the durable mission lifecycle from current runtime a
 
 A Claude job ending does **not** automatically mean its mission succeeded. Orchestrators move missions to **Awaiting acceptance**; the user accepts completion or requests changes. Manual lifecycle controls are available in the mission header.
 
+### Worktree reclamation
+
+Missions launched with worktree isolation get a checked-out worktree under `.claude/worktrees/` and a matching `worktree-` branch. Hive reclaims both when a mission reaches a terminal state, so repositories do not accumulate abandoned checkouts.
+
+| Mission reaches | Worktree |
+| --- | --- |
+| Deleted | Removed |
+| Archived | Removed |
+| Completed | Removed when clean; **kept** when it holds uncommitted changes |
+
+Completion is treated more cautiously than deletion or archiving because it is reversible — sending a follow-up message to a completed mission reopens it — and because **Clear completed desks** completes many Direct missions at once. Uncommitted work in a worktree therefore survives completion, and a worktree left behind for that reason is recorded in the mission's Activity tab.
+
+Reclamation only ever touches worktrees in Hive's managed layout; a repository or a hand-made directory is never removed, whatever a stale job record claims. If a reopened mission's worktree has already been reclaimed, Hive resumes it in the repository the worktree was cut from and records the change.
+
 ## MCP servers, skills, and project configuration
 
 Hive launches the normal local provider CLI rather than a separate container or account.
@@ -291,7 +342,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
@@ -369,7 +423,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
 
@@ -407,7 +465,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
 
@@ -419,6 +477,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/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.1",
+  "version": "0.2.1",
   "type": "module",
   "description": "Provider-neutral local mission control for Claude Code, Codex, and agent fleets.",
   "license": "MIT",