@hheei/pi-subagents 0.8.0 → 0.9.0

package/README.md

@@ -15,7 +15,7 @@ children and `/subagents stop [id]` to stop one without conflicting with other e
 
 | Tool | Purpose |
 | --- | --- |
-| `agents_delegate({ task, agent?, id?, cwd?, wait? })` | Delegate work to a new agent (`agent`) or continue an existing one (`id`, which wins over `agent`). A new child runs in a new Herdr tab (or cmux surface) targeting the parent's workspace when a host is available, and headless in the background otherwise. **Prefer reusing existing agents** via `id` for related/follow-up work to keep context and maximize prompt-cache and memory efficiency. The tool description lists available agent names and roles, excluding disabled or hidden definitions. Deferred by default; discover via `tool_search({ query: "agent" })`. `wait:true` (default) returns the settled delegation, `wait:false` returns it as soon as it is accepted; either way the result arrives automatically, so do not poll. |
+| `agents_delegate({ task, agent?, id?, cwd?, wait? })` | Delegate work to a new agent (`agent`) or continue an existing one (`id`, which wins over `agent`). Omit `id` to create an agent: Pi assigns the id, so an unknown or blank id is never a way to create one. A new child runs in a new Herdr tab (or cmux surface) targeting the parent's workspace when a host is available, and headless in the background otherwise. **Prefer reusing existing agents** via `id` for related/follow-up work to keep context and maximize prompt-cache and memory efficiency. The tool description lists available agent names and roles, excluding disabled or hidden definitions. Deferred by default; discover via `tool_search({ query: "agent" })`. `wait:true` (default) returns the settled delegation, `wait:false` returns it as soon as it is accepted; either way the result arrives automatically, so do not poll. |
 | `agents_get({ id, revision?, includeOutput? })` | Read one delegation of an agent: the newest by default, `revision` for one specific delegation, and the result body only with `includeOutput: true` (bounded by the shared output limit). The view carries the delegation `status` and the runtime `progress.runtimeState` separately, so a new delegation never overwrites a historical result. From the second successful inspection of the same agent in this parent runtime, the result adds a short reminder that results return automatically and must not be polled. Deferred by default; discover via `tool_search({ query: "agent" })`. |
 | `agents_stop({ id })` | Stop one agent's runtime by id. Open delegations end as failed; finished results and the session are kept, so a later `agents_delegate` with this id resumes it. Deferred by default; discover via `tool_search({ query: "agent" })`. |
 | `agents_dashboard({})` | Summarise this session's agents: runtime counts plus each agent's latest delegation status and activity, never result bodies. Deferred by default; discover via `tool_search({ query: "agent" })`. |

package/dist/delegation.js

@@ -6,7 +6,7 @@ import { receiptCarriesOutput } from "./receipts.js";
  */
 export function delegationView(receipt, child, options) {
     if (receipt.childId === undefined || receipt.revision === undefined) {
-        throw new Error(`Delegation ${receipt.delegationId} has no public identity`);
+        throw new Error("Delegation has no public identity");
     }
     const text = receipt.resultText;
     const hasOutput = receiptCarriesOutput(receipt.status, text);

package/dist/lease.d.ts

@@ -57,14 +57,12 @@ export type LeaseReady = {
     readonly rebound: readonly string[];
     readonly rehydrated: readonly string[];
     readonly stopped: readonly string[];
-    /** Children whose runtime was dropped because the writer is gone. */
-    readonly released: readonly string[];
 } | {
     readonly ok: false;
     readonly reason: "unknown";
 };
 export interface ConversationLease {
-    commit(id: string, edge: LeaseEdge, expectedRevision?: number): Promise<SubagentRecord>;
+    commit(id: string, edge: LeaseEdge): Promise<SubagentRecord>;
     roster(): Promise<readonly SubagentRecord[]>;
     ready(): Promise<LeaseReady>;
 }
@@ -74,7 +72,7 @@ export declare function createConversationLease(options: {
     readonly hosts: HostDirectory;
     readonly processes: ProcessDirectory;
 }): ConversationLease;
-export declare function commitLease(registry: Pick<SubagentRegistry, "get" | "update">, id: string, edge: LeaseEdge, expectedRevision?: number, expectedRuntimeIdentity?: string): Promise<SubagentRecord>;
+export declare function commitLease(registry: Pick<SubagentRegistry, "get" | "update">, id: string, edge: LeaseEdge, expectedRuntimeIdentity?: string): Promise<SubagentRecord>;
 /** `undefined` means the edge changes nothing, so the caller must not write. */
 export declare function applyLeaseEdge(record: SubagentRecord, edge: LeaseEdge): SubagentRecord | undefined;
 export declare function readHostGeneration(filePath: string, parentSessionId: string): Promise<string | undefined>;

package/dist/lease.js

@@ -1,5 +1,3 @@
-import { existsSync } from "node:fs";
-import { processLockHeld, processLockPath } from "./process-lock.js";
 import { SubagentRegistryError } from "./registry.js";
 import { openStateDb, readMeta, writeMeta } from "./state-db.js";
 /**
@@ -23,8 +21,8 @@ export const LEASE_EDGES = [
 export function createConversationLease(options) {
     const { registry, hosts, processes } = options;
     return {
-        commit(id, edge, expectedRevision) {
-            return commitLease(registry, id, edge, expectedRevision);
+        commit(id, edge) {
+            return commitLease(registry, id, edge);
         },
         roster() {
             return registry.list();
@@ -34,7 +32,7 @@ export function createConversationLease(options) {
         },
     };
 }
-export async function commitLease(registry, id, edge, expectedRevision, expectedRuntimeIdentity) {
+export async function commitLease(registry, id, edge, expectedRuntimeIdentity) {
     const current = await registry.get(id);
     if (current === undefined) {
         throw new SubagentRegistryError("unknown_child", `Unknown child ${id}`);
@@ -42,7 +40,7 @@ export async function commitLease(registry, id, edge, expectedRevision, expected
     const next = applyLeaseEdge(current, edge);
     if (next === undefined)
         return current;
-    return registry.update(id, expectedRevision ?? current.revision, () => next, expectedRuntimeIdentity);
+    return registry.update(id, () => next, expectedRuntimeIdentity);
 }
 /** `undefined` means the edge changes nothing, so the caller must not write. */
 export function applyLeaseEdge(record, edge) {
@@ -131,26 +129,7 @@ async function reconcile(registry, hosts, processes) {
     if (!list.known)
         return { ok: false, reason: "unknown" };
     const all = await registry.list();
-    const released = new Set();
-    for (const record of all) {
-        if (record.runtime === undefined)
-            continue;
-        const lockPath = processLockPath(registry.path, record.parentSessionId, record.subagentId);
-        if (lockPath === undefined || !existsSync(lockPath))
-            continue;
-        let held = true;
-        try {
-            held = processLockHeld(lockPath);
-        }
-        catch {
-            continue;
-        }
-        if (held)
-            continue;
-        await releaseRuntime(registry, record, { type: "runtime-gone", outcome: "drop" });
-        released.add(record.subagentId);
-    }
-    const records = all.filter((record) => !released.has(record.subagentId));
+    const records = all;
     const parentSessionId = all[0]?.parentSessionId;
     const stored = parentSessionId === undefined
         ? undefined
@@ -200,16 +179,14 @@ async function reconcile(registry, hosts, processes) {
         const attachment = record.runtime?.attachment;
         if (attachment?.kind !== "process")
             continue;
-        if (processes.alive(attachment.pid)) {
+        // A dead pid is a liveness answer, and liveness is read from the lock, never written back.
+        // An alive one still has to be re-watched after a reload.
+        if (processes.alive(attachment.pid))
             rebound.push(record.subagentId);
-            continue;
-        }
-        await releaseRuntime(registry, record, { type: "runtime-gone", outcome: "drop" });
-        released.add(record.subagentId);
     }
     if (!held && parentSessionId !== undefined && stored !== list.generation)
         await writeHostGeneration(registry.path, parentSessionId, list.generation);
-    return { ok: true, rebound, rehydrated, stopped, released: [...released] };
+    return { ok: true, rebound, rehydrated, stopped };
 }
 function panelId(record) {
     const attachment = record.runtime?.attachment;

package/dist/manager.js

@@ -6,7 +6,8 @@ import { attachRetainedChild } from "./child-process.js";
 import { agentView, delegationView, } from "./delegation.js";
 import { isOperationError } from "./domain.js";
 import { stripHindsightContent } from "./launch-spec.js";
-import { commitLease, createConversationLease, RUNTIME_ENDED_RESUME, } from "./lease.js";
+import { commitLease, createConversationLease } from "./lease.js";
+import { processLockHeld, processLockPath } from "./process-lock.js";
 import { BridgeError, isChildInputPayload, isChildLifecyclePayload, isContactReportPayload, } from "./protocol.js";
 import { abandonReceipts, latestReceiptForChild, latestReceiptSummaries, maxRunBoundary, readReceiptRevision, readStoredReceipt, reserveReceipt, settleReceipts, sweepControlReceipts, terminalReceipt, updateReceipt, waitForReceipt, } from "./receipts.js";
 import { findSessionFile, planSessionPlacement } from "./session-bootstrap.js";
@@ -720,6 +721,33 @@ export class SubagentManager {
             return true;
         return this.#processes.get(id)?.alive === true;
     }
+    /**
+     * A child's writer holds its process lock for the whole run, so a free lock means no writer —
+     * including a child another parent process started, which this process never had a handle for.
+     * A probe that fails is not evidence of death.
+     */
+    #runtimeAlive(record) {
+        const lockPath = processLockPath(this.#deps.registry.path, record.parentSessionId, record.subagentId);
+        if (lockPath === undefined)
+            return false;
+        try {
+            return processLockHeld(lockPath);
+        }
+        catch {
+            return true;
+        }
+    }
+    /**
+     * The public projection every read returns: a record that still says `running` while no writer
+     * holds its lock reads as blocked. Nothing is written, so a death this process did not see happen
+     * still reads correctly.
+     */
+    #project(record) {
+        const snapshot = this.#withSnapshot(record);
+        const live = this.#isLive(record.subagentId) || this.#runtimeAlive(record);
+        const state = live || snapshot.state !== "running" ? snapshot.state : "blocked";
+        return publicChild({ ...snapshot, state }, live, this.#paths.get(record.subagentId));
+    }
     /**
      * True only when the host positively reports the panel is gone. An unobservable panel is not a
      * closed one, and treating it as closed is what would let a second runtime start for a session
@@ -1138,7 +1166,7 @@ export class SubagentManager {
         const active = input.id === undefined ? undefined : this.#waiters.get(input.id);
         if (wait && active !== undefined) {
             // Refused before anything is dispatched: a conflicted wait must not steer first.
-            return failure("delegate", `Child ${input.id ?? ""} already has a waiting delegation ${active.delegationId}`, input.id);
+            return failure("delegate", `Child ${input.id ?? ""} already has a waiting delegation`, input.id);
         }
         const target = {};
         const delivery = wait ? "pending" : "detached";
@@ -1480,8 +1508,7 @@ export class SubagentManager {
         const record = await this.#deps.registry.get(id);
         if (record === undefined)
             return failure("get", "Unknown child", id);
-        const live = this.#isLive(id);
-        return publicChild(this.#withSnapshot(record), live, this.#paths.get(id));
+        return this.#project(record);
     }
     /**
      * One delegation of one agent, by revision: the newest by default. The result body is only read
@@ -1500,7 +1527,9 @@ export class SubagentManager {
                 ? "This agent has no delegation"
                 : `This agent has no delegation revision ${input.revision}`, input.id, record.state);
         }
-        return agentView(receipt, publicChild(this.#withSnapshot(record), this.#isLive(input.id), this.#paths.get(input.id)), { includeOutput: input.includeOutput === true });
+        return agentView(receipt, this.#project(record), {
+            includeOutput: input.includeOutput === true,
+        });
     }
     /** Every agent of this parent: runtime state now, latest delegation status, no result bodies. */
     async dashboard() {
@@ -1511,15 +1540,15 @@ export class SubagentManager {
             const summary = summaries.get(record.subagentId);
             if (summary === undefined)
                 continue;
-            const live = this.#withSnapshot(record);
+            const child = this.#project(record);
             children.push({
-                id: record.subagentId,
-                agent: record.launchConfig.agent.name,
-                runtimeState: live.state,
+                id: child.id,
+                agent: child.agent,
+                runtimeState: child.state,
                 revision: summary.revision,
                 status: summary.status,
                 hasOutput: summary.hasOutput,
-                ...(live.latestSummary === undefined ? {} : { summary: live.latestSummary }),
+                ...(child.summary === undefined ? {} : { summary: child.summary }),
             });
         }
         const count = (state) => children.filter((child) => child.runtimeState === state).length;
@@ -1541,7 +1570,7 @@ export class SubagentManager {
     }
     async list() {
         const records = await this.#deps.registry.list();
-        return records.map((record) => publicChild(this.#withSnapshot(record), this.#isLive(record.subagentId), this.#paths.get(record.subagentId)));
+        return records.map((record) => this.#project(record));
     }
     stop(id) {
         this.#clearSettledPanelClose(id);
@@ -1918,7 +1947,6 @@ export class SubagentManager {
                 rebound: recovery.recovered,
                 rehydrated: [],
                 stopped: [],
-                released: [],
             };
         }
         const lease = createConversationLease({
@@ -1943,18 +1971,19 @@ export class SubagentManager {
                     this.#watchRuntime(id, runtime);
             }
         }
-        for (const id of result.released) {
-            await this.#noteReleasedRuntime(id);
-        }
+        // A writer that was already gone when this process started cannot report itself, and a
+        // projection is not a delivery. This is the one place liveness is written back, once per
+        // process because `ready` is memoized, through the edge an exit takes. A panel this pass just
+        // reopened is skipped: its writer is starting, not gone.
+        const gone = (await this.#deps.registry.list()).filter((record) => record.state === "running" &&
+            record.intent !== "stopped" &&
+            !result.rehydrated.includes(record.subagentId) &&
+            !this.#isLive(record.subagentId) &&
+            !this.#runtimeAlive(record));
+        for (const record of gone)
+            await this.#settleUnrecovered(record);
         return result;
     }
-    /** A writer the lease already dropped. Same ledger line as a watched exit. */
-    async #noteReleasedRuntime(id) {
-        const record = await this.#deps.registry.get(id);
-        if (record?.state !== "blocked" || record.interrupted !== RUNTIME_ENDED_RESUME)
-            return;
-        this.#scheduleAutoReport(id, record);
-    }
     #withSnapshot(record) {
         const projector = this.#projectors.get(record.subagentId);
         if (projector === undefined)
@@ -1973,9 +2002,9 @@ export class SubagentManager {
         return this.#mutate(id, () => this.#update(id, updater));
     }
     async #update(id, updater, workVersion) {
-        // The store re-reads the record inside its own write, so an undefined revision cannot
-        // lose a concurrent field update and no stale_revision retry is needed.
-        const next = await this.#deps.registry.update(id, undefined, updater);
+        // The store re-reads the record inside its own write, so the write cannot lose a concurrent
+        // field update and needs no retry.
+        const next = await this.#deps.registry.update(id, updater);
         if (workVersion === undefined || workVersion === (this.#workVersions.get(id) ?? 0)) {
             if (next.state === "running")
                 this.#working.add(id);

package/dist/markdown.d.ts

@@ -1,8 +1 @@
-/**
- * Transforms plain agent and background task identifiers (e.g. `agent-1`, `bash-1`)
- * in Markdown prose by wrapping them in inline code backticks, making them visually
- * distinct in terminal TUI rendering.
- *
- * Preserves text inside code blocks, inline code, and URLs intact.
- */
 export declare function transformSubagentsMarkdown(markdown: string): string;

package/dist/markdown.js

@@ -1,21 +1,19 @@
 /**
- * Transforms plain agent and background task identifiers (e.g. `agent-1`, `bash-1`)
+ * Transforms plain agent and background task identifiers (e.g. `agent-3f9a1c`, `bash-1`)
  * in Markdown prose by wrapping them in inline code backticks, making them visually
  * distinct in terminal TUI rendering.
  *
  * Preserves text inside code blocks, inline code, and URLs intact.
  */
+const IDENTIFIER = /(?:agent-[0-9a-f]{6}|bash-\d+)/;
+/** Word boundary: the id is not part of a longer word or a markdown link URL. */
+const PROSE_IDENTIFIER = /(?<![`/\w])((?:agent-[0-9a-f]{6}|bash-\d+))(?![`\w])/gu;
 export function transformSubagentsMarkdown(markdown) {
-    if (!/(?:agent|bash)-\d+/.test(markdown))
+    if (!IDENTIFIER.test(markdown))
         return markdown;
-    // Split by code blocks (```...```) and inline code (`...`) to only transform prose
-    const parts = markdown.split(/(```[\s\S]*?```|`[^`\n]+`)/g);
-    for (let i = 0; i < parts.length; i += 2) {
-        const part = parts[i];
-        if (part !== undefined && /(?:agent|bash)-\d+/.test(part)) {
-            // Match word boundary: agent-N or bash-N not inside markdown link URLs like (http.../agent-1)
-            parts[i] = part.replace(/(?<![`/\w])((?:agent|bash)-\d+)(?![`\w])/g, "`$1`");
-        }
-    }
-    return parts.join("");
+    // The split captures code blocks and inline code, so odd indexes are the parts to leave alone.
+    return markdown
+        .split(/(```[\s\S]*?```|`[^`\n]+`)/g)
+        .map((part, index) => (index % 2 === 1 ? part : part.replace(PROSE_IDENTIFIER, "`$1`")))
+        .join("");
 }

package/dist/registry.d.ts

@@ -1,5 +1,5 @@
 import type { SubagentRecord } from "./domain.js";
-export type RegistryErrorCode = "invalid_parent_session" | "corrupt_registry" | "unsupported_version" | "parent_mismatch" | "invalid_record" | "duplicate_child" | "unknown_child" | "stale_revision" | "runtime_mismatch" | "stopped_child";
+export type RegistryErrorCode = "invalid_parent_session" | "corrupt_registry" | "unsupported_version" | "parent_mismatch" | "invalid_record" | "duplicate_child" | "unknown_child" | "runtime_mismatch" | "stopped_child";
 export declare class SubagentRegistryError extends Error {
     readonly code: RegistryErrorCode;
     constructor(code: RegistryErrorCode, message: string);
@@ -17,12 +17,11 @@ export interface SubagentRegistry {
     list(signal?: AbortSignal): Promise<readonly SubagentRecord[]>;
     create(record: SubagentRecord, signal?: AbortSignal): Promise<SubagentRecord>;
     /**
-     * Conditional write. `expectedRevision` guards against stale writers, and
-     * `expectedRuntimeIdentity` additionally refuses updates whose target runtime has
-     * already been replaced by a newer one. The registry owns `revision` and
+     * Last write wins. `expectedRuntimeIdentity` refuses an update whose target runtime
+     * has already been replaced by a newer one. The registry owns `revision` and
      * `updatedAt`; the updater's values for those fields are ignored.
      */
-    update(id: string, expectedRevision: number | undefined, updater: (record: SubagentRecord) => SubagentRecord, expectedRuntimeIdentity?: string, signal?: AbortSignal): Promise<SubagentRecord>;
+    update(id: string, updater: (record: SubagentRecord) => SubagentRecord, expectedRuntimeIdentity?: string, signal?: AbortSignal): Promise<SubagentRecord>;
 }
 export interface CreateSubagentRegistryOptions {
     readonly parentSessionId: string;

package/dist/registry.js

@@ -406,10 +406,10 @@ export function createSubagentRegistry(options) {
     const now = options.now ?? (() => new Date());
     const db = openStateDb(path);
     const load = (id) => {
-        const row = readChild(db, parentSessionId, id);
-        if (row === undefined)
+        const record = readChild(db, parentSessionId, id);
+        if (record === undefined)
             return undefined;
-        return parseSubagentRecord(JSON.parse(row.record), id, parentSessionId, path);
+        return parseSubagentRecord(JSON.parse(record), id, parentSessionId, path);
     };
     return {
         path,
@@ -432,21 +432,18 @@ export function createSubagentRegistry(options) {
         },
         async create(record) {
             const candidate = parseSubagentRecord(record, record.subagentId, parentSessionId, path);
-            const inserted = withWrite(db, () => insertChild(db, parentSessionId, candidate.subagentId, candidate.revision, JSON.stringify(candidate)));
+            const inserted = withWrite(db, () => insertChild(db, parentSessionId, candidate.subagentId, JSON.stringify(candidate)));
             if (!inserted) {
                 throw new SubagentRegistryError("duplicate_child", `Child ${candidate.subagentId} already exists in ${path}`);
             }
             return candidate;
         },
-        async update(id, expectedRevision, updater, expectedRuntimeIdentity) {
+        async update(id, updater, expectedRuntimeIdentity) {
             return withWrite(db, () => {
                 const current = load(id);
                 if (current === undefined) {
                     throw new SubagentRegistryError("unknown_child", `Unknown child ${id} in ${path}`);
                 }
-                if (expectedRevision !== undefined && current.revision !== expectedRevision) {
-                    throw new SubagentRegistryError("stale_revision", `Child ${id} is at revision ${current.revision}, not ${expectedRevision}`);
-                }
                 if (expectedRuntimeIdentity !== undefined &&
                     current.runtime?.runtimeIdentity !== expectedRuntimeIdentity) {
                     throw new SubagentRegistryError("runtime_mismatch", `Child ${id} runtime is ${current.runtime?.runtimeIdentity ?? "none"}, not ${expectedRuntimeIdentity}`);
@@ -459,10 +456,7 @@ export function createSubagentRegistry(options) {
                     revision: current.revision + 1,
                     updatedAt: now().toISOString(),
                 }, id, parentSessionId, path);
-                const replaced = replaceChild(db, parentSessionId, id, current.revision, next.revision, JSON.stringify(next));
-                if (!replaced) {
-                    throw new SubagentRegistryError("stale_revision", `Child ${id} changed while it was being updated`);
-                }
+                replaceChild(db, parentSessionId, id, JSON.stringify(next));
                 return next;
             });
         },

package/dist/runtime.js

@@ -93,7 +93,7 @@ export async function launchChild(options) {
             failure: `Child ${record.subagentId} never connected to the parent bridge and did not stop (it may still be running)`,
         };
     }
-    await commitLease(options.registry, record.subagentId, { type: "runtime-gone", outcome: "clear" }, undefined, plan.runtimeIdentity);
+    await commitLease(options.registry, record.subagentId, { type: "runtime-gone", outcome: "clear" }, plan.runtimeIdentity);
     return { failure: `Child ${record.subagentId} never connected to the parent bridge` };
 }
 export async function openChildPanel(options) {
@@ -159,7 +159,7 @@ export async function openChildPanel(options) {
             failure: `Child ${record.subagentId} never connected to the parent bridge and its panel could not be closed (${cleanup.stderr || "its state could not be observed"}); close it manually`,
         };
     }
-    await commitLease(options.registry, record.subagentId, { type: "runtime-gone", outcome: "clear" }, undefined, plan.runtimeIdentity);
+    await commitLease(options.registry, record.subagentId, { type: "runtime-gone", outcome: "clear" }, plan.runtimeIdentity);
     const detail = earlyExitObserved?.detail ? ` (${earlyExitObserved.detail.trim()})` : "";
     return { failure: `Child ${record.subagentId} never connected to the parent bridge${detail}` };
 }

package/dist/session-bootstrap.d.ts

@@ -44,7 +44,12 @@ export declare function findSessionFile(sessionDir: string, sessionId: string):
  * random id; a flushed session must still prove its identity on disk.
  */
 export declare function planSessionPlacement(options: PlanSessionPlacementOptions): Promise<SessionPlacement>;
-export declare function resetSubagentIdCounter(value?: number): void;
+/**
+ * A child id is a label, not a capability: short enough for a status line and a lock file name,
+ * and lowercase so it cannot collide with a differently cased copy on a case-insensitive
+ * filesystem. Nothing arbitrates allocation across processes; `existingIds` is the local check and
+ * the ledger's primary key is the backstop.
+ */
 export declare function createSubagentId(existingIds?: readonly string[]): string;
 export interface ResolveSubagentLaunchOptions {
     readonly input: SpawnSubagentInput;

package/dist/session-bootstrap.js

@@ -1,4 +1,4 @@
-import { randomUUID } from "node:crypto";
+import { randomBytes, randomUUID } from "node:crypto";
 import { open, readdir, readFile, stat } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { getAgentDir, SessionManager } from "@earendil-works/pi-coding-agent";
@@ -135,27 +135,19 @@ export async function planSessionPlacement(options) {
     }
     return { sessionId: options.sessionId, sessionDir, persistence: "never_flushed" };
 }
-let nextSubagentIndex = 0;
-export function resetSubagentIdCounter(value = 0) {
-    nextSubagentIndex = value;
-}
-export function createSubagentId(existingIds) {
-    if (existingIds !== undefined && existingIds.length > 0) {
-        let max = 0;
-        for (const id of existingIds) {
-            const match = /^agent-(\d+)$/u.exec(id);
-            if (match?.[1]) {
-                const num = Number.parseInt(match[1], 10);
-                if (num > max)
-                    max = num;
-            }
-        }
-        if (max > 0) {
-            nextSubagentIndex = Math.max(nextSubagentIndex, max);
-        }
+/**
+ * A child id is a label, not a capability: short enough for a status line and a lock file name,
+ * and lowercase so it cannot collide with a differently cased copy on a case-insensitive
+ * filesystem. Nothing arbitrates allocation across processes; `existingIds` is the local check and
+ * the ledger's primary key is the backstop.
+ */
+export function createSubagentId(existingIds = []) {
+    for (let attempt = 0; attempt < 100; attempt++) {
+        const id = `agent-${randomBytes(3).toString("hex")}`;
+        if (!existingIds.includes(id))
+            return id;
     }
-    nextSubagentIndex += 1;
-    return `agent-${nextSubagentIndex}`;
+    throw new Error("Could not allocate a unique subagent id");
 }
 /**
  * One resolution chain for a spawn: agent definition + explicit parent defaults

package/dist/state-db.d.ts

@@ -15,13 +15,10 @@ export interface StoredCommand {
     readonly errorCode: string | null;
     readonly error: string | null;
 }
-export declare function insertChild(db: DatabaseSync, parentSessionId: string, subagentId: string, revision: number, record: string): boolean;
-export declare function readChild(db: DatabaseSync, parentSessionId: string, subagentId: string): {
-    readonly revision: number;
-    readonly record: string;
-} | undefined;
+export declare function insertChild(db: DatabaseSync, parentSessionId: string, subagentId: string, record: string): boolean;
+export declare function readChild(db: DatabaseSync, parentSessionId: string, subagentId: string): string | undefined;
 export declare function listChildRecords(db: DatabaseSync, parentSessionId: string): readonly string[];
-export declare function replaceChild(db: DatabaseSync, parentSessionId: string, subagentId: string, expectedRevision: number | undefined, revision: number, record: string): boolean;
+export declare function replaceChild(db: DatabaseSync, parentSessionId: string, subagentId: string, record: string): void;
 export declare function readMeta(db: DatabaseSync, parentSessionId: string, key: string): string | undefined;
 export declare function writeMeta(db: DatabaseSync, parentSessionId: string, key: string, value: string): void;
 export declare function enqueueCommand(db: DatabaseSync, command: {

package/dist/state-db.js

@@ -11,12 +11,11 @@ export function defaultStatePath() {
  * instead of being rewritten: this file is runtime state, but silently discarding another build's
  * records is worse than failing to start.
  */
-const SCHEMA_VERSION = 2;
+const SCHEMA_VERSION = 3;
 const TABLES = `
 CREATE TABLE IF NOT EXISTS children (
   parent_session_id TEXT NOT NULL,
   subagent_id TEXT NOT NULL,
-  revision INTEGER NOT NULL,
   record TEXT NOT NULL,
   PRIMARY KEY (parent_session_id, subagent_id)
 );
@@ -80,7 +79,15 @@ const ADDED_COLUMNS = [
     ["delegations", "safe_to_retry", "INTEGER"],
     ["delegations", "side_effects", "TEXT"],
 ];
+/** Columns dropped from a table that already exists, the mirror of {@link ADDED_COLUMNS}. */
+const DROPPED_COLUMNS = [
+    ["children", "revision"],
+];
 const connections = new Map();
+function hasColumn(db, table, column) {
+    const columns = db.prepare(`PRAGMA table_info(${table})`).all();
+    return columns.some((existing) => existing.name === column);
+}
 function schemaVersion(db) {
     return Number(db.prepare("PRAGMA user_version").get()?.user_version ?? 0);
 }
@@ -97,10 +104,12 @@ function migrate(db) {
             return;
         db.exec(TABLES);
         for (const [table, column, type] of ADDED_COLUMNS) {
-            const columns = db.prepare(`PRAGMA table_info(${table})`).all();
-            if (columns.some((existing) => existing.name === column))
-                continue;
-            db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`);
+            if (!hasColumn(db, table, column))
+                db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`);
+        }
+        for (const [table, column] of DROPPED_COLUMNS) {
+            if (hasColumn(db, table, column))
+                db.exec(`ALTER TABLE ${table} DROP COLUMN ${column}`);
         }
         // The bridge token had no reader once the mailbox replaced the socket handshake.
         db.exec("DROP TABLE IF EXISTS tokens");
@@ -159,19 +168,19 @@ function commandFromRow(row) {
     };
 }
 const COMMAND_COLUMNS = "id, parent_session_id, subagent_id, direction, operation, payload, status, result, error_code, error";
-export function insertChild(db, parentSessionId, subagentId, revision, record) {
+export function insertChild(db, parentSessionId, subagentId, record) {
     const result = db
-        .prepare(`INSERT INTO children (parent_session_id, subagent_id, revision, record)
-			 VALUES (?, ?, ?, ?)
+        .prepare(`INSERT INTO children (parent_session_id, subagent_id, record)
+			 VALUES (?, ?, ?)
 			 ON CONFLICT DO NOTHING`)
-        .run(parentSessionId, subagentId, revision, record);
+        .run(parentSessionId, subagentId, record);
     return Number(result.changes) === 1;
 }
 export function readChild(db, parentSessionId, subagentId) {
     const row = db
-        .prepare("SELECT revision, record FROM children WHERE parent_session_id = ? AND subagent_id = ?")
+        .prepare("SELECT record FROM children WHERE parent_session_id = ? AND subagent_id = ?")
         .get(parentSessionId, subagentId);
-    return row;
+    return row?.record;
 }
 export function listChildRecords(db, parentSessionId) {
     const rows = db
@@ -179,17 +188,9 @@ export function listChildRecords(db, parentSessionId) {
         .all(parentSessionId);
     return rows.map((row) => row.record);
 }
-export function replaceChild(db, parentSessionId, subagentId, expectedRevision, revision, record) {
-    const result = expectedRevision === undefined
-        ? db
-            .prepare(`UPDATE children SET revision = ?, record = ?
-						 WHERE parent_session_id = ? AND subagent_id = ?`)
-            .run(revision, record, parentSessionId, subagentId)
-        : db
-            .prepare(`UPDATE children SET revision = ?, record = ?
-						 WHERE parent_session_id = ? AND subagent_id = ? AND revision = ?`)
-            .run(revision, record, parentSessionId, subagentId, expectedRevision);
-    return Number(result.changes) === 1;
+export function replaceChild(db, parentSessionId, subagentId, record) {
+    db.prepare(`UPDATE children SET record = ?
+		 WHERE parent_session_id = ? AND subagent_id = ?`).run(record, parentSessionId, subagentId);
 }
 export function readMeta(db, parentSessionId, key) {
     const row = db

package/dist/tools.js

@@ -25,7 +25,7 @@ const delegateSchema = Type.Object({
     })),
     id: Type.Optional(Type.String({
         minLength: 1,
-        description: "Existing agent id, e.g. agent-1. Takes precedence over agent and reuses its session.",
+        description: "Existing agent id, e.g. agent-3f9a1c. Takes precedence over agent and reuses its session.",
     })),
     agent: Type.Optional(Type.String({
         minLength: 1,
@@ -34,7 +34,7 @@ const delegateSchema = Type.Object({
     cwd: Type.Optional(Type.String({ description: "Working directory for a new agent; ignored with id." })),
 }, { additionalProperties: false });
 const getSchema = Type.Object({
-    id: Type.String({ minLength: 1, description: "Agent id, e.g. agent-1" }),
+    id: Type.String({ minLength: 1, description: "Agent id, e.g. agent-3f9a1c" }),
     revision: Type.Optional(Type.Integer({
         minimum: 1,
         description: "Delegation revision of this agent. Defaults to the newest one.",
@@ -44,7 +44,7 @@ const getSchema = Type.Object({
     })),
 }, { additionalProperties: false });
 const idSchema = Type.Object({
-    id: Type.String({ minLength: 1, description: "Agent id, e.g. agent-1" }),
+    id: Type.String({ minLength: 1, description: "Agent id, e.g. agent-3f9a1c" }),
 });
 const dashboardSchema = Type.Object({}, { additionalProperties: false });
 const contactSchema = Type.Object({
@@ -77,14 +77,15 @@ export function formatAvailableAgents(agents) {
 }
 function getDelegateDescription(agents) {
     return [
-        "Delegate work to a new or existing agent. Supply agent to start a new session, or id to continue an existing one; with both, id wins and agent is ignored.",
+        "Delegate work to an agent. New: omit id and supply agent. Continue: use an existing id; agent/cwd are ignored. Unknown or blank ids fail.",
+        'Create: agents_delegate({ agent: "worker", task: "..." }). Continue: agents_delegate({ id: "agent-3f9a1c", task: "..." }).',
         "Returns { id, revision, status, hasOutput }: revision identifies this delegation of that agent, and a finished delegation carries its result when wait is true. Results are delivered automatically when the task finishes, so do independent work or end your turn instead of polling agents_get.",
         "Related agent tools: agents_get, agents_stop, agents_dashboard.",
         formatAvailableAgents(agents),
     ].join("\n");
 }
 const GET_DESCRIPTION = "Read one agent delegation: the newest by default, or one revision, with its result body when includeOutput is true. Use it for inspection, not completion polling. Related agent tools: agents_delegate, agents_stop, agents_dashboard.";
-const STOP_DESCRIPTION = "Stop an agent runtime by id (e.g. 'agent-1'). Open delegations end as failed; finished results and the session are kept, so a later agents_delegate with this id resumes it. Related agent tools: agents_delegate, agents_get, agents_dashboard.";
+const STOP_DESCRIPTION = "Stop an agent runtime by id (e.g. 'agent-3f9a1c'). Open delegations end as failed; finished results and the session are kept, so a later agents_delegate with this id resumes it. Related agent tools: agents_delegate, agents_get, agents_dashboard.";
 const DASHBOARD_DESCRIPTION = "List this session's agents with their runtime state and latest delegation. Related agent tools: agents_delegate, agents_get, agents_stop.";
 const CONTACT_DESCRIPTION = "Notify the parent session when you are BLOCKED and cannot continue without parent decision or intervention. Do NOT call this on success or task completion: simply output your final answer directly as normal text in your response, and the harness will automatically capture and report your result to the parent.";
 const CONTACT_SNIPPET = "Report a blocker to the parent. Do NOT call on success: write normal text to finish.";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hheei/pi-subagents",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Independent background Pi subagent sessions with durable identity and RPC control.",
   "type": "module",
   "main": "dist/index.js",
@@ -27,30 +27,29 @@
     "pi",
     "pi-package",
     "pi-extension",
-    "hepi",
     "subagents"
   ],
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/hheei/hepi-mono.git",
+    "url": "git+https://github.com/hheei/pi-mono.git",
     "directory": "packages/pi-subagents"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@hheei/pi-ext-core": "^0.7.0",
+    "@hheei/pi-ext-core": "^0.8.0",
     "@modelcontextprotocol/server": "2.4.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=1.3.0",
-    "@earendil-works/pi-tui": ">=1.3.0",
+    "@earendil-works/pi-coding-agent": ">=1.1.0",
+    "@earendil-works/pi-tui": ">=1.1.0",
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "1.3.0",
-    "@earendil-works/pi-tui": "1.3.0",
+    "@earendil-works/pi-coding-agent": "^1.4.0",
+    "@earendil-works/pi-tui": "^1.4.0",
     "linkedom": "^0.18.14"
   },
   "scripts": {