@shanesaravia/hive 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to Hive will be documented in this file.
+
+## 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.
+
+### Highlights
+
+- Durable direct and orchestrated missions with continuous threaded follow-up
+- Claude Code and Codex provider/model selection using existing local authentication
+- Parallel manager and worker visibility, phased plans, progress, evidence, outputs, and completion gates
+- 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
+- Verified npm artifact across macOS and Ubuntu on Node.js 20 and 22

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shane Saravia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,417 @@
+<div align="center">
+  <img src="docs/assets/hive-logo.svg" width="104" alt="Hive bee and honeycomb logo" />
+  <h1>Hive</h1>
+  <p><strong>Provider-neutral mission control for Claude Code, Codex, and agent fleets.</strong></p>
+  <p>Direct, supervise, and recover durable AI missions from one local, observable interface.</p>
+</div>
+
+[![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)
+
+## What Hive is
+
+Hive is a provider-neutral, local mission-control layer for working with Claude Code, Codex, orchestrators, and their worker fleets without losing the outcome behind a stream of short-lived jobs and terminal windows.
+
+In Hive, a **mission** is the durable unit of work. Its name, conversation, status, history, and outputs remain attached to one card even when Claude resumes into a new job ID. A mission can run in either of two modes:
+
+- **Direct** — one selected-provider agent works directly. Best for questions, small fixes, and focused tasks.
+- **Orchestrated** — a manager plans the work and delegates implementation to parallel worker agents, using isolated worktrees where the provider supports them.
+
+Hive is currently a local development project. It stores provider-neutral mission data locally and uses the installed `claude` or `codex` CLI to launch, resume, and stop work. Authentication remains entirely owned by the selected CLI.
+
+## Why Hive
+
+Provider applications are good places to run an individual agent. Hive is designed for the operational layer above them: maintaining one durable mission across provider turns, coordinating managers and parallel workers, exposing evidence-backed progress, detecting unhealthy work, enforcing human checkpoints, and preserving a searchable record of how an outcome was produced.
+
+Hive does not resell model access or replace provider authentication. It gives locally authenticated providers a shared mission model and a consistent supervision surface, so teams and individuals are not locked into one agent runtime or forced to operate a fleet through disconnected terminal sessions.
+
+## Highlights
+
+- Durable mission cards across Claude job resumptions
+- Continuous threaded follow-up conversations
+- 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
+- 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
+- Decision inbox, optional desktop notifications, and mission search/filtering
+- Idle, stalled, retry-loop, overlap, stale-process, and token-without-progress detection
+- 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
+- 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
+- Markdown/JSON mission reports and optional GitHub issue/PR publishing
+- Repository-aware Claude skill discovery and `/skill` autocomplete
+- Repository/working-directory selection with `~` expansion and path suggestions
+- Claude-native graceful stopping through `claude stop <jobId>`
+- Indexed SQLite conversation history with search, paginated loading, and bounded model context
+- Durable recovery across Hive, terminal, and computer restarts
+
+## Requirements
+
+- macOS or Linux
+- Node.js 20 or newer
+- npm
+- At least one supported CLI installed and authenticated: Claude Code as `claude`, Codex as `codex`, or both
+- Git for worktree-based orchestrated missions
+
+Confirm the main prerequisites:
+
+```bash
+node --version
+claude --version
+codex --version
+git --version
+```
+
+## Install
+
+Install Hive globally from npm:
+
+```bash
+npm install --global @shanesaravia/hive
+```
+
+Preview Hive's optional Claude integration setup:
+
+```bash
+hive setup
+```
+
+The preview does not modify files. Apply it explicitly if you use Claude Code and want Hive's orchestrator persona and activity relay hooks:
+
+```bash
+hive setup --yes
+```
+
+Setup performs two additive local changes:
+
+1. Installs `~/.claude/agents/hive-orchestrator.md`.
+2. Additively merges Hive hooks into `~/.claude/settings.json` while preserving existing hooks and writing `~/.claude/settings.json.hive-backup`.
+
+Setup is safe to rerun after an upgrade. Codex missions are adapted directly by Hive and do not depend on Claude's hook installation.
+
+## Run Hive
+
+Start Hive and open the local dashboard:
+
+```bash
+hive
+```
+
+Hive serves the dashboard and API from one local production process, normally at:
+
+```text
+http://127.0.0.1:4317
+```
+
+Useful commands:
+
+| Command | Purpose |
+| --- | --- | --- |
+| `hive` or `hive start` | Start Hive and open the dashboard. |
+| `hive doctor` | Check Node, provider CLIs, authentication, paths, and configuration. |
+| `hive setup` | Preview optional provider integration changes. |
+| `hive setup --yes` | Apply the previewed setup. |
+| `hive status` | Report whether Hive is running and its local address. |
+| `hive open` | Open an already-running dashboard. |
+| `hive stop` | Gracefully stop Hive. |
+| `hive --version` | Show the installed version. |
+
+## Update or uninstall
+
+Update to the newest release:
+
+```bash
+npm install --global @shanesaravia/hive@latest
+```
+
+Uninstall the executable:
+
+```bash
+npm uninstall --global @shanesaravia/hive
+```
+
+Uninstalling the npm package intentionally retains mission history, configuration, logs, and provider integration files. Run `hive doctor` before uninstalling to see their exact platform-specific locations if you also want to remove that data manually.
+
+## Create a mission
+
+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.
+
+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.
+
+## Continue a conversation
+
+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.
+
+## Navigate the fleet
+
+The fleet is organized around attention rather than process creation time:
+
+1. **Needs you** decisions appear globally with context, choices, recommendations, and the impact of waiting.
+2. **Awaiting acceptance** missions appear before active work because they require your review and sign-off.
+3. Active, failed, paused, completed, and archived missions remain in separate operational sections.
+
+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.
+
+## Understand a mission
+
+Each mission has four primary views:
+
+| 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 |
+| 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.
+
+## 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.
+
+The plan begins with:
+
+- the durable mission goal;
+- distinct task, phase, and completion-gate progress;
+- **Now**, **Next**, and **Needs attention** summaries;
+- the current phase and next milestone;
+- revision age and warnings when live worker activity no longer matches the plan.
+
+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.
+
+## Completion and acceptance
+
+Templates and orchestrators can define required completion gates for tests, typecheck, lint, CI, review, PRs, screenshots, documentation, user approval, or a custom requirement. Technical gates must be satisfied or explicitly waived with a recorded reason before completion.
+
+When an orchestrator believes the work and verification are complete, it moves the mission to **Awaiting acceptance**. From there:
+
+- **Accept & complete** records the user's acceptance, satisfies pending `user_approval` gates, and completes the mission;
+- **Request changes** reopens the mission for another conversational turn;
+- unresolved technical gates continue to block completion and identify exactly what remains.
+
+The orchestrator proposing completion never silently marks the durable mission complete; the user remains the final authority.
+
+## Templates
+
+Hive includes workflows for feature implementation, bug fixing, PR review, incident investigation, security audit, refactoring, dependency upgrades, and UI implementation. A template can define manager instructions, stages, worker roles, dependencies, completion gates, budgets, permissions, mode, and worktree behavior.
+
+Open **Templates** from the fleet header to inspect a template before use. Built-ins are read-only; they can be duplicated into editable user or repository templates. Custom templates are validated, versioned, and can be previewed, edited, or deleted without mutating missions that already retained an earlier version.
+
+Template files live in:
+
+| Scope | Path |
+| --- | --- |
+| User | `~/.claude-hive/templates/*.json` |
+| Repository | `<repository>/.hive/templates/*.json` |
+
+Repository templates can override matching built-in/user template IDs for that repository.
+
+## Policies, permissions, and budgets
+
+Workspace policy defaults can restrict allowed roots, tools, network access, commits, pushes, pull requests, releases, and destructive actions. A mission receives a durable policy snapshot that can be changed later only with explicit confirmation.
+
+Mission budgets can set maximum total workers, concurrent workers, tokens, and elapsed minutes. Hive shows consumption and projected exhaustion. These are coordination limits: orchestrators are instructed to stop and request approval before exceeding them, while filesystem and tool restrictions are also applied to provider launch configuration where supported.
+
+## Decisions, health, and recovery
+
+Hive turns structured user questions into a global decision inbox and can optionally send desktop notifications. Answers are delivered back to the same durable mission and retained in its history.
+
+Health alerts explain the condition, supporting evidence, and a suggested recovery action. Detection includes quiet workers, finished workers with an idle orchestrator, retry loops, duplicate delegation, overlapping file ownership, stale processes, high token growth without progress, and unclear waiting states. Card-level notices are deduplicated so the most actionable condition is shown first.
+
+Mission and task controls include pause/resume, graceful or confirmed force stop, manager replacement, retry, cancellation, worker replacement/reassignment, priority changes, plan revision, fresh review, verification pass, completion, reopening, archive, and permanent deletion. Control actions are recorded in the activity timeline.
+
+## Reports and GitHub
+
+The Technical view exports a mission report as Markdown or JSON. Reports include the request, plan, decisions, workers, changed files, verification, outputs, resource use, conversation, and remaining risks. With a locally authenticated `gh` CLI, Hive can post a report to a GitHub issue or pull request after explicit confirmation; it does not publish automatically.
+
+## Mission lifecycle and activity
+
+Hive deliberately separates the durable mission lifecycle from current runtime activity.
+
+| Mission lifecycle | Meaning |
+| --- | --- |
+| Active | The mission remains in progress |
+| Awaiting acceptance | The orchestrator reports that work and verification are complete and requests your acceptance |
+| Paused | Inactivity is intentional; stalled warnings are suppressed |
+| Completed | The user accepted the outcome or manually completed the mission |
+| Failed | The mission ended unsuccessfully |
+| Archived | The mission is retained as a terminal historical record |
+
+| Runtime activity | Meaning |
+| --- | --- |
+| Working | An orchestrator or worker is currently active |
+| Needs you | The provider is waiting for a decision or input |
+| Idle | The mission is active, but nothing is currently running |
+| Stalled | An active mission has exceeded the inactivity threshold |
+| Offline | A paused or terminal mission has no live process |
+
+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.
+
+## MCP servers, skills, and project configuration
+
+Hive launches the normal local provider CLI rather than a separate container or account.
+
+- User-scoped Claude configuration is available to launched agents.
+- Project-scoped MCP servers, skills, plugins, settings, and `CLAUDE.md` files depend on the selected working directory.
+- MCP authentication and required environment variables must be available to the Hive server process.
+- Worker agents do not automatically inherit a skill invoked earlier in the manager conversation; the orchestrator must explicitly assign relevant skills to workers.
+
+Codex likewise uses the locally authenticated `codex` CLI. Whether that CLI is authenticated through a ChatGPT subscription or API-key billing is outside Hive; no provider credentials are stored by Hive.
+
+Orchestrated managers cannot directly edit files: Hive launches them with `Edit`, `Write`, and `NotebookEdit` disabled. They delegate repository changes to worker agents. Direct missions do not apply that manager-only restriction.
+
+## Local data and architecture
+
+```text
+Browser UI (React + Vite)
+        │ REST + WebSocket
+Hive server (Fastify)
+        │
+        ├── adapts Claude and Codex runtime state into provider-neutral turns
+        ├── launches/resumes/stops the selected local CLI
+        ├── persists mission metadata in Hive's local data directory
+        └── stores indexed conversation history in SQLite
+```
+
+Hive uses filesystem watchers and local runtime adapters for live provider state instead of polling an LLM. Full conversation history is stored separately from model context; normal follow-ups use the provider's native thread, while manager handoff context is deliberately bounded to a compact summary, recent messages, and a small set of relevant older messages.
+
+Restarting Hive does not erase missions. On startup, it reloads mission metadata, conversations, plans, revisions, events, policies, Codex adapter state, and provider job relationships. Completed or interrupted provider turns are reconciled with live processes. A stopped mission can be resumed later; a computer restart may end a live CLI process, but the durable mission and conversation remain available for recovery or manager replacement.
+
+New CLI installations use platform-standard local directories. Existing installations with `~/.claude-hive` continue using it automatically, so upgrading does not relocate or lose mission data. Run `hive doctor` to see the exact paths selected on the current machine.
+
+| Platform | Data/configuration | Logs |
+| --- | --- | --- |
+| macOS | `~/Library/Application Support/Hive` | `~/Library/Logs/Hive/hive.log` |
+| Linux | `$XDG_DATA_HOME/hive` and `$XDG_CONFIG_HOME/hive` | `$XDG_STATE_HOME/hive/logs/hive.log` |
+| Windows | `%LOCALAPPDATA%\Hive` and `%APPDATA%\Hive` | `%LOCALAPPDATA%\Hive\logs\hive.log` |
+| Existing Hive installation | `~/.claude-hive` | `~/.claude-hive/logs/hive.log` |
+
+Important files below are relative to the selected Hive data directory unless stated otherwise:
+
+| Path | Contents |
+| --- | --- |
+| `missions.json` | Durable mission metadata and Claude job relationships |
+| `hive.db` | Indexed mission conversation history and plans |
+| `events.jsonl` | Activity event log |
+| `hook-spool.jsonl` | Claude hook events buffered while Hive is unavailable |
+| `policies.json` | Workspace policy defaults |
+| `templates` | User-created mission templates |
+| `codex-jobs` | Hive's durable Codex turn adapters and JSONL output |
+| `codex-sessions` | Live Codex process adapters |
+| `~/.claude/agents/hive-orchestrator.md` | Installed Hive manager persona |
+| `~/.claude/settings.json` | Claude settings with additive Hive hooks |
+
+## Configuration
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `HIVE_PORT` | `4317` | Hive server and event relay port |
+| `HIVE_DATA_DIR` | Platform data directory | Override Hive mission and database storage |
+| `HIVE_CONFIG_DIR` | Platform configuration directory | Override CLI configuration storage |
+| `HIVE_STATE_DIR` | Platform state directory | Override runtime PID and port storage |
+| `HIVE_LOG_DIR` | Platform log directory | Override durable server-log storage |
+| `HIVE_ALLOWED_ORIGINS` | Hive's own local origins | Comma-separated additional browser origins allowed to access the local API |
+| `VITE_HIVE_PORT` | `4317` | Server port used by the web application |
+| `HIVE_STALLED_AFTER_MS` | `600000` | Inactivity duration before an active mission is marked stalled |
+
+If you change `HIVE_PORT`, use the same value for `VITE_HIVE_PORT` when starting the web application.
+
+## Development commands
+
+Clone the repository and install dependencies when contributing from source:
+
+```bash
+git clone https://github.com/shanesaravia/hive.git
+cd hive
+npm install
+```
+
+```bash
+npm run dev        # Start server and web development processes
+npm test           # Run workspace tests
+npm run typecheck  # Type-check server, shared package, web, and CLI
+npm run build      # Create production builds for all workspaces
+```
+
+Useful CLI commands:
+
+```bash
+npm run hive -- setup
+npm run hive -- setup --yes
+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).
+
+## Troubleshooting
+
+### The UI says it is connecting to the Hive server
+
+Confirm the health endpoint responds:
+
+```bash
+curl http://127.0.0.1:4317/health
+```
+
+If it does not, run `hive status`, restart with `hive`, and inspect the log path reported by `hive doctor`. Contributors using the source development environment can restart `npm run dev`.
+
+### A working directory is rejected
+
+Use an existing directory. Hive supports `~`, `~/path`, absolute paths, and relative paths based on the directory from which Hive was launched.
+
+### Project skills or MCP servers are missing
+
+Confirm the mission uses the intended repository directory. Project-scoped configuration is resolved from that directory. For MCP authentication issues, open a normal Claude Code session in the same directory and run `/mcp`.
+
+### New orchestrators do not report Awaiting acceptance
+
+Refresh the installed persona after upgrading Hive:
+
+```bash
+hive setup --yes
+```
+
+Already-running Claude sessions may retain their earlier instructions; lifecycle controls can still be used manually.
+
+### A mission is Active but Stalled
+
+This means the mission remains unfinished while Hive sees no meaningful runtime activity. Send a follow-up, pause it if inactivity is intentional, or complete/archive it from the mission header.
+
+### 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.
+
+### Data after a restart
+
+Restart Hive with `hive`, then reopen the same mission card. Hive reloads durable state from the platform path shown by `hive doctor`; existing installations using `~/.claude-hive` continue to use it automatically. Do not delete the selected data directory if you want to preserve mission history.
+
+## Current limitations
+
+- Hive is local-first and has no multi-user authentication or remote deployment model.
+- 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.
+- Optional multi-mission initiatives remain intentionally deferred. A mission is the primary durable unit of work.
+
+## Project status
+
+Hive is under active development. Persistence formats, APIs, and UI behavior may evolve. Review the [improvements roadmap](docs/IMPROVEMENTS.md) before relying on it for critical or unattended workflows.
+
+Hive is available under the [MIT License](LICENSE).

package/dist/bin/hive-emit.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// Plain non-LLM HTTP POST — safe to call from any agent's Bash tool. Fails
+// silently and fast if the Hive server isn't running, so it never blocks or
+// costs extra agent turns.
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const PORT = process.env.HIVE_PORT ?? "4317";
+const SESSIONS_DIR = path.join(os.homedir(), ".claude", "sessions");
+function parseArgs(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith("--")) {
+            out[arg.slice(2)] = argv[i + 1];
+            i++;
+        }
+    }
+    return out;
+}
+/**
+ * There's no documented env var carrying the calling session's ID, so when
+ * --sessionId isn't passed explicitly, fall back to walking up from this
+ * process's parent looking for a matching ~/.claude/sessions/<pid>.json —
+ * hive-emit is invoked as a child of the claude CLI process (possibly via an
+ * intermediate shell), so one of the first few ancestors should match.
+ */
+function detectSessionId() {
+    let pid = process.ppid;
+    for (let hops = 0; hops < 4 && pid > 1; hops++) {
+        try {
+            const raw = fs.readFileSync(path.join(SESSIONS_DIR, `${pid}.json`), "utf-8");
+            return JSON.parse(raw).sessionId;
+        }
+        catch {
+            // not this pid — walk up one more level
+        }
+        try {
+            // `ps` works on both macOS and Linux, unlike /proc which is Linux-only.
+            const out = execFileSync("ps", ["-o", "ppid=", "-p", String(pid)], {
+                encoding: "utf-8",
+            }).trim();
+            pid = Number(out) || -1;
+        }
+        catch {
+            break;
+        }
+    }
+    return undefined;
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    const sessionId = args.sessionId ?? detectSessionId();
+    const { phase, detail, target: targetWorker, task: targetTask, jobId } = args;
+    if (!sessionId || !phase || !detail) {
+        console.error('Usage: hive-emit --phase <phase> --detail "<text>" [--target <worker>] [--task <task-id>] [--sessionId <id>] [--jobId <id>]');
+        process.exit(1);
+    }
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 1000);
+        await fetch(`http://127.0.0.1:${PORT}/events`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ sessionId, jobId, phase, detail, targetWorker, targetTask }),
+            signal: controller.signal,
+        });
+        clearTimeout(timeout);
+    }
+    catch {
+        // Hive server not running — silently no-op, never block the agent's turn.
+    }
+}
+main();