kitty-hive 0.6.11 → 0.7.1

package/dist/codex-supervisor.js

@@ -0,0 +1,317 @@
+/**
+ * Codex daemon supervisor.
+ *
+ * On hive serve boot, spawns one codex-channel daemon child per local agent
+ * registered with `tool='codex'`. Daemons get push delivery via WebSocket to
+ * a codex app-server they manage; the supervisor just keeps them alive.
+ *
+ * Design choices (settled with the user, 2026-05-20):
+ *   - DB is the single source of truth: `WHERE tool='codex' AND origin_peer=''`
+ *     decides what gets spawned. No separate config list, no opt-in flag —
+ *     same UX as Claude plugin (install once, just works).
+ *   - Restart with exponential backoff (1s → 2s → 4s → ... → cap 60s).
+ *   - On serve SIGTERM, supervisor kills all children with SIGTERM and waits.
+ *   - Daemon stderr/stdout are tee'd into serve's own stderr with an
+ *     `[codex:<display_name>]` prefix.
+ *
+ * Thread persistence (v0.7.0):
+ *   - daemon's codex thread_id is stored on agents.thread_id after first ready.
+ *   - On respawn, supervisor injects HIVE_AGENT_THREAD_ID so daemon calls
+ *     `thread/resume` (against the jsonl codex app-server already wrote to
+ *     ~/.codex/sessions/) instead of `thread/start`. Conversation survives
+ *     daemon kill / serve restart / machine reboot.
+ *
+ * Out of scope (deferred):
+ *   - Hot reload on DB changes (poll / watch). Add/remove agents → must
+ *     restart serve to pick up. Acceptable for now since codex agents are
+ *     long-lived once configured.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execSync } from 'node:child_process';
+import { log } from './log.js';
+import { listLocalCodexAgents, getAgentById, onAgentCreated, setAgentThreadId } from './db.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const daemons = new Map();
+let shuttingDown = false;
+let supervisorPort = 4123; // set by startCodexSupervisor
+function findNpx() {
+    const probe = process.platform === 'win32' ? 'where npx' : 'command -v npx';
+    try {
+        const out = execSync(probe, { encoding: 'utf8' }).trim().split(/\r?\n/)[0];
+        return out || 'npx';
+    }
+    catch {
+        return 'npx';
+    }
+}
+function locateCodexChannelScript() {
+    // dist/codex-supervisor.js → ../codex-channel.ts (package root)
+    const p = join(__dirname, '..', 'codex-channel.ts');
+    if (existsSync(p))
+        return p;
+    // Fallback if running from src/ directly via tsx (dev)
+    const dev = join(__dirname, '..', '..', 'codex-channel.ts');
+    if (existsSync(dev))
+        return dev;
+    throw new Error(`cannot locate codex-channel.ts (tried ${p})`);
+}
+function spawnDaemon(agentId, displayName, restartCount = 0) {
+    if (shuttingDown)
+        return;
+    if (daemons.has(agentId))
+        return; // already running
+    let scriptPath;
+    try {
+        scriptPath = locateCodexChannelScript();
+    }
+    catch (err) {
+        log('warn', `[codex-supervisor] ${err}`);
+        return;
+    }
+    log('info', `[codex-supervisor] spawning daemon for "${displayName}" (${agentId.slice(-12)}) restart=${restartCount}`);
+    // CRITICAL: scrub inherited HIVE_* env vars from the operator's shell.
+    // Without this, if `kitty-hive serve` was launched from a shell with
+    // HIVE_AGENT_KEY set (e.g. for a Claude session bound to a different
+    // agent), the daemon would carry that key over, and codex-channel.ts's
+    // hive_start() would `key`-match to the operator's agent — silently
+    // taking it over (display_name + tool overwritten). Real incident on
+    // 2026-05-20: smoke test renamed `kitty-hive` to `test-codex-1` because
+    // the operator shell had HIVE_AGENT_KEY=<kitty-hive's external_key>.
+    //
+    // Daemon gets a minimal env: system basics (PATH, HOME, etc.) + EXACTLY
+    // the hive identity overrides we want.
+    const cleanEnv = {};
+    for (const [k, v] of Object.entries(process.env)) {
+        if (k.startsWith('HIVE_'))
+            continue; // drop any HIVE_* inherited from operator shell
+        cleanEnv[k] = v;
+    }
+    cleanEnv.HIVE_AGENT_ID = agentId;
+    cleanEnv.HIVE_AGENT_NAME = displayName;
+    // HIVE_URL: explicitly set so daemon talks to *this* serve (whose port the
+    // supervisor knows), not whatever was in the operator shell or the daemon's
+    // own fallback default.
+    cleanEnv.HIVE_URL = `http://127.0.0.1:${supervisorPort}/mcp`;
+    // CODEX_APPSERVER_CWD: codex-channel.ts reads this and passes to thread/start
+    // as cwd. Determines where the codex agent thinks it's running — must match
+    // the operator's intent (the project the kitty pane was launched for), not
+    // the cwd hive serve happens to be running from. agent.project_dir is
+    // operator-set via `agent register --project-dir`; empty falls back to
+    // serve's own cwd.
+    const fresh = getAgentById(agentId);
+    if (fresh?.project_dir)
+        cleanEnv.CODEX_APPSERVER_CWD = fresh.project_dir;
+    // HIVE_AGENT_THREAD_ID: presence tells codex-channel to `thread/resume` an
+    // existing codex thread (jsonl already on disk in ~/.codex/sessions/)
+    // instead of `thread/start`. Set on every spawn after the first ready
+    // (markDaemonReady persists it to agents.thread_id). On a respawn after
+    // resume failure, codex-channel announces a brand-new thread_id and
+    // markDaemonReady overwrites — old jsonl is orphaned but content survives
+    // on disk.
+    if (fresh?.thread_id)
+        cleanEnv.HIVE_AGENT_THREAD_ID = fresh.thread_id;
+    const child = spawn(findNpx(), ['-y', 'tsx', scriptPath], {
+        env: cleanEnv,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (!child.pid) {
+        log('warn', `[codex-supervisor] failed to spawn daemon for ${displayName}: no pid`);
+        return;
+    }
+    const info = {
+        agentId, displayName, child, pid: child.pid,
+        startedAt: new Date(), restartCount,
+        wsUrl: null, threadId: null, readyAt: null,
+    };
+    daemons.set(agentId, info);
+    // Tee daemon output into serve's stderr with a label so user can see what
+    // each daemon is doing without separate log files. We forward both stdout
+    // and stderr to stderr (stdout would interleave with the http log lines).
+    const prefix = `[codex:${displayName}]`;
+    child.stdout?.on('data', (chunk) => process.stderr.write(`${prefix} ${chunk}`));
+    child.stderr?.on('data', (chunk) => process.stderr.write(`${prefix} ${chunk}`));
+    child.on('exit', (code, signal) => {
+        daemons.delete(agentId);
+        log('info', `[codex-supervisor] daemon "${displayName}" exited (code=${code}, signal=${signal})`);
+        if (shuttingDown)
+            return;
+        // Refresh agent record — it may have been removed or modified
+        const fresh = getAgentById(agentId);
+        if (!fresh || fresh.tool !== 'codex' || fresh.origin_peer !== '') {
+            log('info', `[codex-supervisor] daemon "${displayName}" no longer eligible for spawn (deleted / tool changed / now remote); not restarting`);
+            return;
+        }
+        // Exponential backoff: 1s, 2s, 4s, 8s, ... cap 60s
+        const delayMs = Math.min(60000, 1000 * Math.pow(2, restartCount));
+        log('warn', `[codex-supervisor] restarting "${fresh.display_name}" in ${delayMs}ms (attempt ${restartCount + 1})`);
+        setTimeout(() => {
+            spawnDaemon(fresh.id, fresh.display_name, restartCount + 1);
+        }, delayMs);
+    });
+    child.on('error', (err) => {
+        log('warn', `[codex-supervisor] daemon "${displayName}" process error: ${err}`);
+    });
+}
+export function startCodexSupervisor(port = 4123) {
+    supervisorPort = port;
+    const agents = listLocalCodexAgents();
+    if (agents.length === 0) {
+        log('info', '[codex-supervisor] no local tool=codex agents — nothing to spawn at boot');
+    }
+    else {
+        log('info', `[codex-supervisor] starting ${agents.length} codex daemon(s): ${agents.map(a => a.display_name).join(', ')}`);
+        for (const agent of agents) {
+            spawnDaemon(agent.id, agent.display_name, 0);
+        }
+    }
+    // Dynamic spawn: kitty / any other launcher may register a NEW codex agent
+    // while serve is running. Listen for agent-create events and spawn a daemon
+    // on the fly so the launcher doesn't have to restart serve. Subscribe AFTER
+    // initial boot scan so we don't double-spawn the already-spawned set above.
+    onAgentCreated((agent) => {
+        if (agent.tool !== 'codex' || agent.origin_peer !== '')
+            return;
+        if (daemons.has(agent.id))
+            return; // already spawning
+        log('info', `[codex-supervisor] new local tool=codex agent registered: "${agent.display_name}" (${agent.id.slice(-12)}) → spawning daemon`);
+        spawnDaemon(agent.id, agent.display_name, 0);
+    });
+}
+export function stopCodexSupervisor() {
+    shuttingDown = true;
+    if (daemons.size === 0)
+        return Promise.resolve();
+    log('info', `[codex-supervisor] stopping ${daemons.size} daemon(s)...`);
+    return new Promise((resolve) => {
+        const pending = new Set();
+        for (const info of daemons.values()) {
+            pending.add(info.agentId);
+            info.child.once('exit', () => {
+                pending.delete(info.agentId);
+                if (pending.size === 0)
+                    resolve();
+            });
+            try {
+                info.child.kill('SIGTERM');
+            }
+            catch { /* ignore */ }
+        }
+        // Hard timeout: if children don't exit in 5s, SIGKILL and resolve
+        setTimeout(() => {
+            if (pending.size === 0)
+                return;
+            log('warn', `[codex-supervisor] ${pending.size} daemon(s) didn't exit cleanly; SIGKILL`);
+            for (const info of daemons.values()) {
+                if (pending.has(info.agentId)) {
+                    try {
+                        info.child.kill('SIGKILL');
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+            resolve();
+        }, 5000);
+    });
+}
+export function getDaemonSnapshots() {
+    const now = Date.now();
+    return [...daemons.values()].map(info => ({
+        agent_id: info.agentId,
+        display_name: info.displayName,
+        pid: info.pid,
+        uptime_ms: now - info.startedAt.getTime(),
+        restart_count: info.restartCount,
+        ws_url: info.wsUrl,
+        thread_id: info.threadId,
+        ready: !!info.readyAt,
+    }));
+}
+/** Look up the live daemon for an agent, by agent_id or external_key.
+ *  Returns null when no daemon is running for that agent. */
+export function getDaemonForAgent(lookup) {
+    let info;
+    if (lookup.agentId) {
+        info = daemons.get(lookup.agentId);
+    }
+    else if (lookup.agentKey) {
+        // No reverse index — small N, just scan. Need DB lookup to map key→id.
+        // To avoid pulling db in here, callers should resolve key→agent_id
+        // upstream (the MCP tool does that) and pass agent_id.
+        return null;
+    }
+    if (!info)
+        return null;
+    return {
+        agent_id: info.agentId,
+        display_name: info.displayName,
+        pid: info.pid,
+        uptime_ms: Date.now() - info.startedAt.getTime(),
+        restart_count: info.restartCount,
+        ws_url: info.wsUrl,
+        thread_id: info.threadId,
+        ready: !!info.readyAt,
+    };
+}
+/** Called by /admin/codex-daemon-ready when a daemon's codex app-server is up
+ *  and its thread is created. Stores ws_url + thread_id on the DaemonInfo so
+ *  outside callers can attach via `codex --remote <ws_url>`. */
+export function markDaemonReady(agentId, wsUrl, threadId) {
+    const info = daemons.get(agentId);
+    if (!info)
+        return false;
+    info.wsUrl = wsUrl;
+    info.threadId = threadId;
+    info.readyAt = new Date();
+    // Persist thread_id so next spawn (after daemon kill / serve restart) can
+    // resume the same codex thread instead of starting fresh. Idempotent —
+    // setting the same id is a cheap UPDATE.
+    try {
+        setAgentThreadId(agentId, threadId);
+    }
+    catch (err) {
+        log('warn', `[codex-supervisor] failed to persist thread_id for ${agentId}: ${err}`);
+    }
+    log('info', `[codex-supervisor] daemon "${info.displayName}" ready: ws=${wsUrl} thread=${threadId.slice(0, 8)}...`);
+    return true;
+}
+/** Called by /admin/notify-agent-created when a CLI-side `agent register`
+ *  inserts a row. The CLI runs in its own process so the in-process
+ *  onAgentCreated hook doesn't reach the supervisor; this is the bridge.
+ *  Idempotent: returns false if already spawned, true if a new spawn started. */
+export function notifyAgentCreated(agentId) {
+    if (daemons.has(agentId))
+        return false;
+    const agent = getAgentById(agentId);
+    if (!agent)
+        return false;
+    if (agent.tool !== 'codex' || agent.origin_peer !== '')
+        return false;
+    log('info', `[codex-supervisor] notify-agent-created: "${agent.display_name}" (${agentId.slice(-12)}) → spawning daemon`);
+    spawnDaemon(agent.id, agent.display_name, 0);
+    return true;
+}
+/** Kill the daemon (if any) for an agent that just got removed. Mirror of
+ *  notifyAgentCreated for the delete path. Without this, `kitty-hive agent
+ *  remove` deletes the row but leaves a ghost daemon (and its codex
+ *  app-server + ws) running — see Bug 1 reported on 2026-05-20: a stale
+ *  ws confused TUI routing into a schism. SIGTERM the child; the existing
+ *  child.on('exit') handler in spawnDaemon checks `getAgentById(agentId)`
+ *  before respawning, so a deleted row naturally short-circuits the
+ *  respawn logic — no per-daemon "intentional kill" flag needed.
+ *  Returns true if a daemon was killed. */
+export function notifyAgentRemoved(agentId) {
+    const info = daemons.get(agentId);
+    if (!info)
+        return false;
+    log('info', `[codex-supervisor] notify-agent-removed: "${info.displayName}" (${agentId.slice(-12)}) → killing daemon`);
+    try {
+        info.child.kill('SIGTERM');
+    }
+    catch { /* ignore */ }
+    return true;
+}
+//# sourceMappingURL=codex-supervisor.js.map

package/dist/codex-supervisor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-supervisor.js","sourceRoot":"","sources":["../src/codex-supervisor.ts"],"names":[],"mappings":"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"}

package/dist/db.d.ts

@@ -19,9 +19,22 @@ export interface CreateAgentOpts {
     externalKey?: string;
     originPeer?: string;
     remoteId?: string;
+    projectDir?: string;
 }
+type AgentCreateListener = (agent: Agent) => void;
+export declare function onAgentCreated(fn: AgentCreateListener): void;
 export declare function createAgent(displayName: string, tool: string, roles: string, expertise: string, opts?: CreateAgentOpts): Agent;
 export declare function getAgentByExternalKey(key: string): Agent | undefined;
+/** Update an agent's project_dir hint (used by codex-supervisor as cwd when
+ *  spawning the daemon's codex app-server). Idempotent; empty string = clear.
+ *  No-op for unknown ids. */
+export declare function setAgentProjectDir(agentId: string, projectDir: string): void;
+/** Persist the codex thread/session uuid for a codex agent. Supervisor reads
+ *  this on daemon (re)spawn and injects via HIVE_AGENT_THREAD_ID env, so the
+ *  daemon calls `thread/resume` instead of `thread/start` — preserving the
+ *  jsonl-backed conversation history across daemon kill / serve restart.
+ *  Empty string clears (used as fallback when resume fails on a stale id). */
+export declare function setAgentThreadId(agentId: string, threadId: string): void;
 /** Try to set agent.external_key. Silently no-ops on UNIQUE conflict (another
  *  agent already owns that key). Returns true on success, false on conflict. */
 export declare function trySetAgentExternalKey(agentId: string, key: string): boolean;
@@ -33,6 +46,12 @@ export declare function getAgentByToken(token: string): Agent | undefined;
 export declare function getAgentById(id: string): Agent | undefined;
 export declare function getAgentsByName(name: string): Agent[];
 export declare function listAllAgents(activeOnly?: boolean): Agent[];
+/**
+ * Local agents registered with tool='codex'. Used by the codex-supervisor
+ * to decide which daemons to auto-spawn on hive serve boot. Excludes remote
+ * placeholders (origin_peer != '') since their codex lives on another node.
+ */
+export declare function listLocalCodexAgents(): Agent[];
 /**
  * Find an active local agent matching a role string.
  *
@@ -75,6 +94,7 @@ export declare function listTeams(activeOnly?: boolean): Team[];
 export declare function listTeamsHostedBy(agentId: string): Team[];
 export declare function countTeamMembers(teamId: string): number;
 export declare function transferTeamHost(teamId: string, newHostAgentId: string): void;
+export declare function setTeamRules(teamId: string, rules: string): void;
 export declare function getAgentTeams(agentId: string, activeOnly?: boolean): Team[];
 export declare function addTeamMember(teamId: string, agentId: string, nickname?: string | null): TeamMember;
 export declare function removeTeamMember(teamId: string, agentId: string): void;
@@ -112,6 +132,12 @@ export declare function getAgentTasks(agentId: string, status?: string): Task[];
 export declare function getTeamTasks(teamId: string, status?: string): Task[];
 export declare function appendTaskEvent(taskId: string, type: TaskEventType, actorAgentId: string | null, payload?: object): TaskEvent;
 export declare function getTaskEvents(taskId: string, since?: number, limit?: number): TaskEvent[];
+/** Latest seq number in task_events for a task (0 if no events). Used by the
+ *  MCP layer to build stable event_id values for push notifications — calling
+ *  this RIGHT AFTER a handler that appended events gives the seq of that
+ *  handler's last event. Stable across re-delivery, so channel-side dedup
+ *  can absorb duplicates from queue replay / daemon retry. */
+export declare function getLatestTaskEventSeq(taskId: string): number;
 export declare function getReadCursor(agentId: string, targetType: string, targetId: string): number;
 export declare function setReadCursor(agentId: string, targetType: string, targetId: string, seq: number): void;
 export interface UnreadSummary {
@@ -166,3 +192,4 @@ export declare function deletePendingInvite(tokenId: string): void;
 export declare function cleanupExpiredInvites(): number;
 export declare function isPeerExposed(peerName: string, agentName: string): boolean;
 export declare function cleanupStaleTasks(maxAgeDays?: number): number;
+export {};

package/dist/db.js

@@ -34,7 +34,8 @@ export function initDB(dbPath) {
       name            TEXT NOT NULL UNIQUE,
       host_agent_id   TEXT REFERENCES agents(id),
       created_at      TEXT NOT NULL,
-      closed_at       TEXT
+      closed_at       TEXT,
+      rules           TEXT NOT NULL DEFAULT ''
     );
 
     CREATE TABLE IF NOT EXISTS team_members (
@@ -168,12 +169,24 @@ export function initDB(dbPath) {
     CREATE UNIQUE INDEX IF NOT EXISTS idx_agents_external_key
       ON agents(external_key) WHERE external_key != '';
   `);
+    // project_dir: operator-supplied working directory hint. codex-supervisor
+    // uses it as cwd when spawning the daemon's codex app-server, so the TUI
+    // user attaches via `codex --remote` lands in the right project — without
+    // it, codex sees serve's cwd and the user sees the wrong files.
+    addColumnIfMissing('agents', 'project_dir', "TEXT NOT NULL DEFAULT ''");
+    // thread_id: persisted codex thread/session uuid for the agent's daemon.
+    // When the daemon respawns, supervisor injects this as HIVE_AGENT_THREAD_ID;
+    // daemon then calls `thread/resume {threadId}` instead of `thread/start`,
+    // so conversation history (stored as jsonl by codex app-server) survives
+    // daemon kill / serve restart / machine reboot.
+    addColumnIfMissing('agents', 'thread_id', "TEXT NOT NULL DEFAULT ''");
     // Migrate tasks.status CHECK constraint when an older DB lacks
     // 'awaiting_approval' (added in v0.5.6 but the schema migration was missed
     // until v0.5.9). SQLite has no ALTER COLUMN, so we recreate the table.
     migrateTasksStatusCheck(db);
     migrateTeamEventsTypeCheck(db);
     migrateClearChannelRoles(db);
+    migrateTeamsAddRules(db);
     db.exec(`
     CREATE INDEX IF NOT EXISTS idx_agents_remote ON agents(origin_peer, remote_id);
     CREATE INDEX IF NOT EXISTS idx_tasks_delegated ON tasks(delegated_peer, delegated_task_id);
@@ -302,6 +315,32 @@ function migrateClearChannelRoles(db) {
     db.prepare("UPDATE agents SET roles = '' WHERE roles = 'channel'").run();
     console.log(`[db] cleared channel-polluted roles on ${before.n} agent(s)`);
 }
+// Add teams.rules column on older DBs (introduced in v0.6.12).
+// SQLite ALTER TABLE supports adding a NOT NULL column when a DEFAULT is given,
+// so this is a single-statement, idempotent migration (PRAGMA detects existence).
+function migrateTeamsAddRules(db) {
+    const cols = db.prepare("PRAGMA table_info(teams)").all();
+    if (cols.some(c => c.name === 'rules'))
+        return; // already migrated (or fresh DB with new schema)
+    db.exec("ALTER TABLE teams ADD COLUMN rules TEXT NOT NULL DEFAULT ''");
+    console.log('[db] added teams.rules column');
+}
+const agentCreateListeners = [];
+export function onAgentCreated(fn) {
+    agentCreateListeners.push(fn);
+}
+function emitAgentCreated(agent) {
+    for (const fn of agentCreateListeners) {
+        try {
+            fn(agent);
+        }
+        catch (err) {
+            // listener errors are isolated; don't break createAgent
+            // eslint-disable-next-line no-console
+            console.error('[db] onAgentCreated listener threw:', err);
+        }
+    }
+}
 export function createAgent(displayName, tool, roles, expertise, opts = {}) {
     const agent = {
         id: opts.id || ulid(),
@@ -312,11 +351,14 @@ export function createAgent(displayName, tool, roles, expertise, opts = {}) {
         origin_peer: opts.originPeer || '',
         remote_id: opts.remoteId || '',
         external_key: opts.externalKey || '',
+        project_dir: opts.projectDir || '',
+        thread_id: '',
     };
     getDB().prepare(`
-    INSERT INTO agents (id, display_name, token, tool, roles, expertise, status, created_at, last_seen, origin_peer, remote_id, external_key)
-    VALUES (@id, @display_name, @token, @tool, @roles, @expertise, @status, @created_at, @last_seen, @origin_peer, @remote_id, @external_key)
+    INSERT INTO agents (id, display_name, token, tool, roles, expertise, status, created_at, last_seen, origin_peer, remote_id, external_key, project_dir)
+    VALUES (@id, @display_name, @token, @tool, @roles, @expertise, @status, @created_at, @last_seen, @origin_peer, @remote_id, @external_key, @project_dir)
   `).run(agent);
+    emitAgentCreated(agent);
     return agent;
 }
 export function getAgentByExternalKey(key) {
@@ -324,6 +366,20 @@ export function getAgentByExternalKey(key) {
         return undefined;
     return getDB().prepare('SELECT * FROM agents WHERE external_key = ?').get(key);
 }
+/** Update an agent's project_dir hint (used by codex-supervisor as cwd when
+ *  spawning the daemon's codex app-server). Idempotent; empty string = clear.
+ *  No-op for unknown ids. */
+export function setAgentProjectDir(agentId, projectDir) {
+    getDB().prepare('UPDATE agents SET project_dir = ? WHERE id = ?').run(projectDir || '', agentId);
+}
+/** Persist the codex thread/session uuid for a codex agent. Supervisor reads
+ *  this on daemon (re)spawn and injects via HIVE_AGENT_THREAD_ID env, so the
+ *  daemon calls `thread/resume` instead of `thread/start` — preserving the
+ *  jsonl-backed conversation history across daemon kill / serve restart.
+ *  Empty string clears (used as fallback when resume fails on a stale id). */
+export function setAgentThreadId(agentId, threadId) {
+    getDB().prepare('UPDATE agents SET thread_id = ? WHERE id = ?').run(threadId || '', agentId);
+}
 /** Try to set agent.external_key. Silently no-ops on UNIQUE conflict (another
  *  agent already owns that key). Returns true on success, false on conflict. */
 export function trySetAgentExternalKey(agentId, key) {
@@ -376,6 +432,14 @@ export function listAllAgents(activeOnly = false) {
         : 'SELECT * FROM agents ORDER BY last_seen DESC';
     return getDB().prepare(sql).all();
 }
+/**
+ * Local agents registered with tool='codex'. Used by the codex-supervisor
+ * to decide which daemons to auto-spawn on hive serve boot. Excludes remote
+ * placeholders (origin_peer != '') since their codex lives on another node.
+ */
+export function listLocalCodexAgents() {
+    return getDB().prepare("SELECT * FROM agents WHERE tool = 'codex' AND origin_peer = '' ORDER BY display_name").all();
+}
 /**
  * Find an active local agent matching a role string.
  *
@@ -476,10 +540,11 @@ export function createTeam(name, hostAgentId) {
         id: ulid(), name,
         host_agent_id: hostAgentId,
         created_at: nowISO(), closed_at: null,
+        rules: '',
     };
     getDB().prepare(`
-    INSERT INTO teams (id, name, host_agent_id, created_at, closed_at)
-    VALUES (@id, @name, @host_agent_id, @created_at, @closed_at)
+    INSERT INTO teams (id, name, host_agent_id, created_at, closed_at, rules)
+    VALUES (@id, @name, @host_agent_id, @created_at, @closed_at, @rules)
   `).run(team);
     return team;
 }
@@ -505,6 +570,9 @@ export function countTeamMembers(teamId) {
 export function transferTeamHost(teamId, newHostAgentId) {
     getDB().prepare('UPDATE teams SET host_agent_id = ? WHERE id = ?').run(newHostAgentId, teamId);
 }
+export function setTeamRules(teamId, rules) {
+    getDB().prepare('UPDATE teams SET rules = ? WHERE id = ?').run(rules ?? '', teamId);
+}
 export function getAgentTeams(agentId, activeOnly = true) {
     const sql = activeOnly
         ? `SELECT t.* FROM teams t JOIN team_members tm ON tm.team_id = t.id WHERE tm.agent_id = ? AND t.closed_at IS NULL ORDER BY tm.joined_at DESC`
@@ -684,6 +752,15 @@ export function appendTaskEvent(taskId, type, actorAgentId, payload = {}) {
 export function getTaskEvents(taskId, since = 0, limit = 100) {
     return getDB().prepare('SELECT * FROM task_events WHERE task_id = ? AND seq > ? ORDER BY seq ASC LIMIT ?').all(taskId, since, limit);
 }
+/** Latest seq number in task_events for a task (0 if no events). Used by the
+ *  MCP layer to build stable event_id values for push notifications — calling
+ *  this RIGHT AFTER a handler that appended events gives the seq of that
+ *  handler's last event. Stable across re-delivery, so channel-side dedup
+ *  can absorb duplicates from queue replay / daemon retry. */
+export function getLatestTaskEventSeq(taskId) {
+    const row = getDB().prepare('SELECT COALESCE(MAX(seq), 0) AS max_seq FROM task_events WHERE task_id = ?').get(taskId);
+    return row.max_seq;
+}
 // --- Read cursors ---
 export function getReadCursor(agentId, targetType, targetId) {
     const row = getDB().prepare('SELECT last_seq FROM read_cursors WHERE agent_id = ? AND target_type = ? AND target_id = ?').get(agentId, targetType, targetId);