Skip to content

an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions

fix(hive): keep hire role out of live status captions

George Burchell585c1cdbf3f9
diff --git a/package.json b/package.json
index 8dc851de..97a794df 100644
--- a/package.json
+++ b/package.json
@@ -19,7 +19,7 @@
"typecheck:node": "tsc --noEmit -p tsconfig.node.json",
"typecheck:web": "tsc --noEmit -p tsconfig.web.json",
"typecheck": "npm run typecheck:node && npm run typecheck:web",
- "test:focused": "node --test test/codex-remote.test.cjs test/control.test.cjs test/provider-automation.test.cjs test/provider-config.test.cjs test/queue-delivery.test.cjs test/terminal-automation.test.cjs test/terminal-recovery.test.cjs test/roster.test.cjs test/proc-kill.test.cjs test/expand-tilde.test.cjs test/hive-cwd.test.cjs test/hive-hook-node.test.cjs test/hive-roster-injection.test.cjs test/hive-runtime-path.test.cjs test/cli-install-ladder.test.cjs test/node-install.test.cjs test/office-gl-recovery.test.cjs test/update-state.test.cjs test/transcript-project-dir.test.cjs test/commit-graph.test.cjs",
+ "test:focused": "node --test test/codex-remote.test.cjs test/control.test.cjs test/provider-automation.test.cjs test/provider-config.test.cjs test/queue-delivery.test.cjs test/terminal-automation.test.cjs test/terminal-recovery.test.cjs test/roster.test.cjs test/proc-kill.test.cjs test/expand-tilde.test.cjs test/hive-cwd.test.cjs test/hive-hook-node.test.cjs test/hive-roster-injection.test.cjs test/hive-runtime-path.test.cjs test/cli-install-ladder.test.cjs test/node-install.test.cjs test/office-gl-recovery.test.cjs test/update-state.test.cjs test/transcript-project-dir.test.cjs test/commit-graph.test.cjs test/agent-role.test.cjs",
"check:links": "node tools/check-release-links.cjs",
"dist": "npm run build && electron-builder",
"dist:mac": "npm run build && electron-builder --mac",
diff --git a/src/main/hive.ts b/src/main/hive.ts
index 16f5235c..eada491a 100644
--- a/src/main/hive.ts
+++ b/src/main/hive.ts
@@ -5,8 +5,9 @@
* process commits to (agents never call git — they just write files). See
* HIVE.md for the full design. Responsibilities:
* - per-agent workspace (identity.md, memory.md, inbox/, outbox/, cursor.json)
- * - a roster (registry.json), shared blackboard (board.md), task ledger,
- * and an append-only event log (log.jsonl)
+ * - hive identity (registry.json: id/role/cwd/session — what agents read),
+ * separate from the UI floor roster (`<harnessHome>/roster.json`)
+ * - shared blackboard (board.md), task ledger, and an append-only event log (log.jsonl)
* - a router that drains each agent's outbox into recipients' inboxes
*
* Human-in-the-loop is native to each agent's Claude Code session: permission
@@ -36,6 +37,7 @@ import {
type AgentProvider
} from '../shared/agentProvider';
import { MCP_CATALOG } from '../shared/mcpCatalog';
+import { preferredAgentRole } from '../shared/agentRole';
import { expandTilde } from './fs';
/** The subset of HarnessConfig the hive consumes for the default-MCP merge.
@@ -548,6 +550,15 @@ export class HiveManager {
mkdirSync(join(dir, 'inbox', '.done'), { recursive: true });
mkdirSync(join(dir, 'outbox', '.sent'), { recursive: true });
+ // Resolve role BEFORE writing identity.md. A restart passes the floor
+ // roster's `description`, which can be a status caption ("on standby").
+ // identity.md and registry.role are the durable job from the hire.
+ const reg = this.registry();
+ const prev = reg.agents[meta.id];
+ if (meta.cwd) meta = { ...meta, cwd: expandTilde(meta.cwd) };
+ const role = preferredAgentRole(meta.role, prev?.role, !!meta.isGod);
+ meta = { ...meta, role };
+
const identity = join(dir, 'identity.md');
writeFileSync(identity, this.identityText(meta), 'utf8'); // refresh on each spawn
@@ -570,19 +581,16 @@ export class HiveManager {
// ensureAgent (which runs before the resume lookup in the pty:spawn handler)
// would wipe the recorded session id, so `lastSession()` returns undefined and
// `--resume` is never attached — i.e. every restart starts a fresh thread.
- const reg = this.registry();
- const prev = reg.agents[meta.id];
// Validate the working directory at the source so a bad value is visible on
// the roster (cwdValid) rather than silently spawning into a nonexistent dir.
// Store the EXPANDED cwd, never the raw `~/…` the user typed — the registry is
// read by hooks, the roster and the worker watcher, none of which run a shell.
- if (meta.cwd) meta = { ...meta, cwd: expandTilde(meta.cwd) };
const cwd = this.cwdValidity(meta.cwd);
reg.agents[meta.id] = {
...prev,
...meta,
- capabilities: meta.capabilities ?? [],
- role: meta.role ?? (meta.isGod ? 'orchestrator' : 'agent'),
+ capabilities: meta.capabilities ?? prev?.capabilities ?? [],
+ role,
status: 'idle',
cwdValid: cwd.valid,
// A (re)spawn always means a live terminal — clear any prior archived flag.
@@ -770,6 +778,30 @@ export class HiveManager {
return { args, env };
}
+ /** Update the durable job string (hire role) without respawning. Refreshes
+ * registry.json + identity.md so the floor editor and the hive stay aligned. */
+ patchAgentRole(id: string, role: string): { ok: boolean; error?: string } {
+ const root = this.root();
+ if (!root) return { ok: false, error: 'hive disabled' };
+ const next = role.trim();
+ if (!next) return { ok: false, error: 'empty role' };
+ try {
+ const reg = this.registry();
+ const agent = reg.agents[id];
+ if (!agent) return { ok: false, error: 'unknown agent' };
+ if (agent.role === next) return { ok: true };
+ agent.role = next;
+ agent.lastSeen = Date.now();
+ this.writeJson(join(root, 'registry.json'), reg);
+ writeFileSync(join(this.agentDir(id), 'identity.md'), this.identityText(agent), 'utf8');
+ this.appendLog({ kind: 'role', agentId: id, role: next });
+ this.commit(`hive: role ${id}`);
+ return { ok: true };
+ } catch (e) {
+ return { ok: false, error: e instanceof Error ? e.message : String(e) };
+ }
+ }
+
/**
* Flip an agent's archived flag and persist the registry. Closing a terminal
* tab archives the agent (retained + flagged, NOT deleted); a (re)spawn clears
diff --git a/src/main/index.ts b/src/main/index.ts
index cb30da18..8064ac61 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -3088,6 +3088,12 @@ ipcMain.handle('hive:setArchived', (_evt, id: unknown, archived: unknown) => {
hive.setArchived(id, archived === true);
return { ok: true };
});
+ipcMain.handle('hive:patchAgentRole', (_evt, id: unknown, role: unknown) => {
+ if (typeof id !== 'string') return { ok: false, error: 'invalid id' };
+ if (typeof role !== 'string') return { ok: false, error: 'invalid role' };
+ if (!hive.enabled()) return { ok: false, error: 'hive disabled (no harnessHome)' };
+ return hive.patchAgentRole(id, role);
+});
// ─── IPC: semantic memory (MemPalace CLI) ───────────────────────────────────
ipcMain.handle('hive:memoryStatus', () => { memory.resetBinCache(); return memory.status(); });
diff --git a/src/main/roster.ts b/src/main/roster.ts
index 16b8751d..889a09f7 100644
--- a/src/main/roster.ts
+++ b/src/main/roster.ts
@@ -3,7 +3,12 @@
* restorable entries, and parked message queues, stored as one JSON file beside
* the hive.
*
- * WHY THIS EXISTS. All of that used to live only in the renderer's localStorage,
+ * WHY THIS EXISTS. This is the UI floor (cards, notes, queues, worktrees).
+ * Hive identity — id, role, cwd, session — lives in `<harnessHome>/hive/registry.json`
+ * and is what agents read. The two must not drift: `description` here is the
+ * same durable job string as registry `role`, never live status (pause/idle).
+ *
+ * All of that used to live only in the renderer's localStorage,
* and localStorage is partitioned by ORIGIN. A dev run loads the renderer from
* `http://localhost:5173` and a packaged build loads it from `file://`, so the
* two never see each other's storage: switching between them showed an empty
diff --git a/src/preload/index.ts b/src/preload/index.ts
index a04efc67..4ea0b1f7 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -692,6 +692,9 @@ const api = {
// ─── Hive (multi-agent coordination) ─────────────────────────────────────
hiveRegistry: (): Promise<HiveRegistry> => ipcRenderer.invoke('hive:registry'),
+ /** Persist a hire/job role to hive registry.json + identity.md (no respawn). */
+ hivePatchAgentRole: (id: string, role: string): Promise<{ ok: boolean; error?: string }> =>
+ ipcRenderer.invoke('hive:patchAgentRole', id, role),
hiveBoard: (): Promise<string> => ipcRenderer.invoke('hive:board'),
hiveTasks: (): Promise<unknown> => ipcRenderer.invoke('hive:tasks'),
hiveLog: (n?: number): Promise<unknown[]> => ipcRenderer.invoke('hive:log', n ?? 200),
diff --git a/src/renderer/src/components/AddAgentModal.tsx b/src/renderer/src/components/AddAgentModal.tsx
index c7467558..0c2cbdaa 100644
--- a/src/renderer/src/components/AddAgentModal.tsx
+++ b/src/renderer/src/components/AddAgentModal.tsx
@@ -118,7 +118,7 @@ const SECTIONS: { key: SectionKey; label: string; hint: string }[] = [
{ key: 'identity', label: 'Identity', hint: 'name · character · color' },
{ key: 'workspace', label: 'Workspace', hint: 'folder · isolation · resume' },
{ key: 'engine', label: 'Engine', hint: 'provider · model · command' },
- { key: 'briefing', label: 'Briefing', hint: 'description · goal' }
+ { key: 'briefing', label: 'Briefing', hint: 'role · goal' }
];
function basename(path: string): string {
@@ -930,11 +930,11 @@ export function AddAgentModal({ onClose, config, onConfigChange }: AddAgentModal
</div>
</Row>
- <Row label="Description">
+ <Row label="Role">
<input
value={description}
onChange={(e) => setDescription(e.target.value)}
- placeholder="what is this agent for"
+ placeholder="job — what this agent is for, not live status"
style={inputStyle}
/>
</Row>
diff --git a/src/renderer/src/components/CommandCenterPanel.tsx b/src/renderer/src/components/CommandCenterPanel.tsx
index 9353d608..6d1b98d6 100644
--- a/src/renderer/src/components/CommandCenterPanel.tsx
+++ b/src/renderer/src/components/CommandCenterPanel.tsx
@@ -16,6 +16,7 @@ import { Icon } from './Icon';
import { MemoryGraphPanel } from './MemoryGraphPanel';
import { useFleetTelemetry } from '@/hooks/useTelemetry';
import { COMMAND_GROUPS } from '@shared/claudeCommands';
+import { roleForHiveSpawn } from '@shared/agentRole';
import { useStore, triggerHistoryVisible, type Agent } from '@/store/store';
import { usePtyParser } from '@/hooks/usePtyParser';
import {
@@ -422,11 +423,15 @@ function FloorTab({ seed }: { seed: { text: string; seq: number } }) {
}
const command = buildSpawnCommand(cfg, model, provider);
const [exe, ...args] = tokenizeCommand(command.trim());
- const hive = a.isGod
- ? { id: a.id, name: a.name, cwd: a.cwd, provider, isGod: true, role: 'orchestrator (god)' }
- : a.isAssistant
- ? { id: a.id, name: a.name, cwd: a.cwd, provider, isAssistant: true, role: "Michael's prep assistant" }
- : { id: a.id, name: a.name, cwd: a.cwd, provider, role: a.description };
+ const hive = {
+ id: a.id,
+ name: a.name,
+ cwd: a.cwd,
+ provider,
+ isGod: a.isGod,
+ isAssistant: a.isAssistant,
+ role: roleForHiveSpawn(a)
+ };
const res = await window.cth.spawnPty({
id: a.ptyId,
cwd: a.cwd,
diff --git a/src/renderer/src/hooks/useHive.ts b/src/renderer/src/hooks/useHive.ts
index c7b10fd3..5b496454 100644
--- a/src/renderer/src/hooks/useHive.ts
+++ b/src/renderer/src/hooks/useHive.ts
@@ -16,6 +16,7 @@ import {
} from '../../../shared/providerAutomation';
import { DEFAULT_CONTEXT_TRIGGER, type ContextRule } from '../../../shared/triggers';
import type { AgentProvider } from '../../../shared/agentProvider';
+import { isDurableRole, preferredAgentRole, roleForHiveSpawn } from '../../../shared/agentRole';
import { acquireTerminal, resetTerminal, isTerminalAutomationSafe } from '@/components/terminalPool';
import { deliverWithAcknowledgement } from './queueDelivery';
import { OFFICE_CAST, DEFAULT_CHARACTER } from '@/scene/office/cast';
@@ -292,6 +293,26 @@ export function useHive(config: HarnessConfig | null): void {
// back to 'working' (the flicker the spec calls out); only a genuine Stop clears it.
const breakerLevel = useRef<Record<string, string>>({});
+ // 0) Heal roster `description` from hive `role` when the floor caption was
+ // overwritten by a status string ("on standby") after hire.
+ useEffect(() => {
+ if (!config?.onboardingComplete) return;
+ void window.cth.hiveRegistry().then((reg) => {
+ const roles: Record<string, string> = {};
+ for (const [id, entry] of Object.entries(reg.agents ?? {})) {
+ if (typeof entry.role === 'string' && entry.role.trim()) roles[id] = entry.role.trim();
+ }
+ useStore.getState().syncDescriptionsFromRoles(roles);
+ const { agents, archivedAgents } = useStore.getState();
+ for (const a of [...agents, ...archivedAgents]) {
+ const next = preferredAgentRole(a.description, roles[a.id], !!a.isGod);
+ if (isDurableRole(next) && next !== roles[a.id]) {
+ void window.cth.hivePatchAgentRole(a.id, next);
+ }
+ }
+ }).catch(() => { /* hive not ready yet */ });
+ }, [config?.onboardingComplete]);
+
// 1) Bootstrap the god agent (source of truth = live PTYs, to dodge restarts).
useEffect(() => {
if (!config?.onboardingComplete || !config.harnessHome) return;
@@ -1020,10 +1041,10 @@ export function useHive(config: HarnessConfig | null): void {
const command = (a.command ?? '').trim() || buildSpawnCommand(cfg, a.model, provider);
const [exe, ...args] = tokenizeCommand(command);
const hive = a.isGod
- ? { id: a.id, name: a.name, cwd, provider, isGod: true, role: 'orchestrator (god)' }
+ ? { id: a.id, name: a.name, cwd, provider, isGod: true, role: roleForHiveSpawn(a) }
: a.isAssistant
- ? { id: a.id, name: a.name, cwd, provider, isAssistant: true, role: "Michael's prep assistant" }
- : { id: a.id, name: a.name, cwd, provider, role: a.description };
+ ? { id: a.id, name: a.name, cwd, provider, isAssistant: true, role: roleForHiveSpawn(a) }
+ : { id: a.id, name: a.name, cwd, provider, role: roleForHiveSpawn(a) };
// Spawn at the terminal's real grid so the TUI's absolute cursor moves land
// in the right cells (a size mismatch scatters the redraw).
const entry = acquireTerminal(deadId);
diff --git a/src/renderer/src/hooks/useRestoreTeam.ts b/src/renderer/src/hooks/useRestoreTeam.ts
index eabf61b6..c877198c 100644
--- a/src/renderer/src/hooks/useRestoreTeam.ts
+++ b/src/renderer/src/hooks/useRestoreTeam.ts
@@ -1,6 +1,7 @@
import { useEffect, useSyncExternalStore } from 'react';
import { useStore, type Agent } from '@/store/store';
import { buildSpawnCommand, inferAgentProvider, tokenizeCommand, type HarnessConfig } from '@/store/config';
+import { roleForHiveSpawn } from '@shared/agentRole';
/** "Restore team" — respawn every worker from the previous session.
*
@@ -146,7 +147,7 @@ export function useRestoreTeam(config?: HarnessConfig | null): RestoreTeamState
// agent id is preserved across restart, so its registry entry,
// memory.md and inbox reattach by id. No-op without a recorded session.
resume: true,
- hive: { id: a.id, name: a.name, provider, cwd, role: a.description }
+ hive: { id: a.id, name: a.name, provider, cwd, role: roleForHiveSpawn(a) }
});
if (res.ok) {
restored++;
diff --git a/src/renderer/src/store/mockEvents.ts b/src/renderer/src/store/mockEvents.ts
index b05c0491..dac3f2ab 100644
--- a/src/renderer/src/store/mockEvents.ts
+++ b/src/renderer/src/store/mockEvents.ts
@@ -13,7 +13,7 @@ const STATION_BY_TOOL: Record<ToolKind, StationKind> = {
interface ToolSample {
tool: ToolKind;
- what: string; // short — used as the action text and description
+ what: string; // short — used as the action text
lines: string[]; // terminal stream output
thought: string; // first-person assistant text, streamed in the sidebar
}
@@ -94,7 +94,6 @@ function stepAgent(agent: Agent) {
updateAgent(agent.id, {
status: 'working',
action: sample.what,
- description: sample.what,
carrying: tool,
progress: Math.min(agent.progress + 1, 8),
recentAssistantText: sample.thought,
diff --git a/src/renderer/src/store/store.ts b/src/renderer/src/store/store.ts
index 230af954..a1c654ed 100644
--- a/src/renderer/src/store/store.ts
+++ b/src/renderer/src/store/store.ts
@@ -7,6 +7,7 @@ import type { AgentProvider } from '@shared/agentProvider';
import type { HireManifest } from '@shared/hire';
import { DEFAULT_ORG_TRIGGER, type OrgTriggerConfig, type WebhookTrigger } from '@shared/triggers';
import { isCompactionCommand } from '@shared/providerAutomation';
+import { preferredAgentRole } from '@shared/agentRole';
export type ToolKind =
| 'Read' | 'Edit' | 'Write' | 'Bash' | 'WebFetch' | 'WebSearch'
@@ -33,7 +34,8 @@ export interface Agent {
/** which Office character represents this agent on the floor */
character: OfficeCharacterName;
accent: AccentColorName;
- /** persistent short context — what is this agent for (shown on the floor) */
+ /** persistent job / hire one-liner — same string as hive registry `role`.
+ * Live status belongs on `status` / `action`, never here. */
description: string;
project: string;
/** legacy field — populated only for the seeded mock agents */
@@ -173,6 +175,9 @@ interface State {
setGodStatus: (status: GodStatus) => void;
select: (id: string) => void;
updateAgent: (id: string, patch: Partial<Agent>) => void;
+ /** Copy durable hive roles onto roster descriptions (and the reverse is a
+ * no-op when the roster already has a real job string). */
+ syncDescriptionsFromRoles: (roles: Record<string, string>) => void;
setAgentNote: (id: string, note: string) => void;
pushFeed: (id: string, line: string) => void;
addAgent: (agent: Agent) => void;
@@ -597,6 +602,29 @@ export const useStore = create<State>((set) => ({
if (touchesDurableAgentField(patch)) persistAgents(agents, s.selectedId);
return { agents };
}),
+ syncDescriptionsFromRoles: (roles) =>
+ set((s) => {
+ const apply = (list: Agent[]): Agent[] => {
+ let changed = false;
+ const next = list.map((a) => {
+ const description = preferredAgentRole(a.description, roles[a.id], !!a.isGod);
+ if (description === a.description) return a;
+ changed = true;
+ return { ...a, description };
+ });
+ return changed ? next : list;
+ };
+ const agents = apply(s.agents);
+ const archivedAgents = apply(s.archivedAgents);
+ const restorableAgents = apply(s.restorableAgents);
+ if (agents === s.agents && archivedAgents === s.archivedAgents && restorableAgents === s.restorableAgents) {
+ return s;
+ }
+ persistAgents(agents, s.selectedId);
+ if (archivedAgents !== s.archivedAgents) persistArchived(archivedAgents);
+ if (restorableAgents !== s.restorableAgents) persistRestorable(restorableAgents);
+ return { agents, archivedAgents, restorableAgents };
+ }),
setAgentNote: (id, note) =>
set((s) => {
const agents = s.agents.map((a) => a.id === id ? { ...a, note } : a);
diff --git a/src/shared/agentRole.ts b/src/shared/agentRole.ts
new file mode 100644
index 00000000..f046ffb0
--- /dev/null
+++ b/src/shared/agentRole.ts
@@ -0,0 +1,50 @@
+/**
+ * Durable agent role vs live status.
+ *
+ * Hive `registry.json` stores `role` (job / hire one-liner). The floor roster
+ * stores the same string as `description`. Live run-state belongs on
+ * `status` / `action` — never on role. Pause, idle, and Cursor "standby"
+ * captions are status, not a job.
+ */
+
+const TRANSIENT_ROLE_RE = /^(on\s+)?standby$|^(idle|awaiting|paused|resumed|working|thinking|archived|starting up|reconnecting…?|running the floor|a fresh harness)$/i;
+
+export function isDurableRole(text: string | undefined | null): boolean {
+ const value = (text ?? '').trim();
+ if (!value) return false;
+ return !TRANSIENT_ROLE_RE.test(value);
+}
+
+/**
+ * Pick the job string that should survive a respawn or roster/registry sync.
+ * A real hire role always beats a status-like caption. When both are durable,
+ * `candidate` wins (the value the operator just set).
+ */
+export function preferredAgentRole(
+ candidate: string | undefined | null,
+ fallback: string | undefined | null,
+ isGod = false
+): string {
+ const incoming = (candidate ?? '').trim();
+ const existing = (fallback ?? '').trim();
+ if (isDurableRole(incoming)) return incoming;
+ if (isDurableRole(existing)) return existing;
+ if (incoming) return incoming;
+ if (existing) return existing;
+ return isGod ? 'orchestrator (god)' : 'agent';
+}
+
+/** Role to send on spawn/restart. Omit a transient roster caption so the hive
+ * registry can keep the last real hire role. */
+export function roleForHiveSpawn(agent: {
+ description?: string;
+ isGod?: boolean;
+ isAssistant?: boolean;
+}): string | undefined {
+ if (agent.isGod) return preferredAgentRole(agent.description, 'orchestrator (god)', true);
+ if (agent.isAssistant) {
+ return preferredAgentRole(agent.description, "Michael's prep assistant");
+ }
+ const role = agent.description?.trim();
+ return role && isDurableRole(role) ? role : undefined;
+}
diff --git a/test/agent-role.test.cjs b/test/agent-role.test.cjs
new file mode 100644
index 00000000..8473824d
--- /dev/null
+++ b/test/agent-role.test.cjs
@@ -0,0 +1,38 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const loadTs = require('./load-ts.cjs');
+
+const {
+ isDurableRole,
+ preferredAgentRole,
+ roleForHiveSpawn
+} = loadTs('src/shared/agentRole.ts');
+
+test('status captions are not durable roles', () => {
+ for (const text of ['on standby', 'standby', 'idle', 'awaiting', 'a fresh harness', 'reconnecting…', '']) {
+ assert.equal(isDurableRole(text), false, text);
+ }
+ assert.equal(isDurableRole('Head of Marketing — owns marketing-control-room'), true);
+});
+
+test('preferredAgentRole keeps a hire role over standby', () => {
+ const hire = 'Head of Marketing — owns marketing-control-room and coordinates structured marketing work across the portfolio.';
+ assert.equal(preferredAgentRole('on standby', hire), hire);
+ assert.equal(preferredAgentRole(hire, 'on standby'), hire);
+ assert.equal(preferredAgentRole('on standby', 'idle', true), 'on standby');
+ assert.equal(preferredAgentRole(undefined, undefined, true), 'orchestrator (god)');
+});
+
+test('roleForHiveSpawn omits a transient roster caption', () => {
+ assert.equal(roleForHiveSpawn({ description: 'on standby' }), undefined);
+ assert.equal(
+ roleForHiveSpawn({ description: 'SRT product steward — owns marketing execution' }),
+ 'SRT product steward — owns marketing execution'
+ );
+ assert.equal(
+ roleForHiveSpawn({ description: 'on standby', isGod: true }),
+ 'orchestrator (god)'
+ );
+});