pi-onlyne 0.6.0 → 0.7.0

package/README.md

@@ -122,6 +122,8 @@ The extension merges partial JSON with the defaults. `inbound.rules` accepts cha
 
 ## Agent tools
 
+Normal mode:
+
 ```text
 onlyne_daemon_start()
 onlyne_daemon_stop()
@@ -131,9 +133,24 @@ onlyne_send({ channelId, text, rawText? })
 onlyne_broadcast({ targets, text, rawText? })
 onlyne_loopback({ text, rawText? })
 onlyne_mark_no_reply({ reason? })
-onlyne_swarm_reply({ text, rawText? })
 ```
 
+Swarm mode (`[swarm] enabled`):
+
+```text
+onlyne_daemon_start()
+onlyne_daemon_stop()
+onlyne_daemon_restart()
+swarm_complete({ text })
+swarm_quit({ reason? })
+swarm_send({ to, text })
+swarm_status()
+```
+
+One session sees one toolset, chosen at session start. Generic send/reply
+tools stay out of the swarm surface so unheaded writes cannot pollute the
+protocol.
+
 Messages use Markdown by default. `rawText: true` preserves literal text for scripts and protocol payloads.
 
 ### Send one message
@@ -173,7 +190,7 @@ Swarm mode lets `onlyne-swarm` own task routing for a generated agent workspace.
 enabled = true
 ```
 
-A swarm Pi session subscribes to loopback events, reports `swarm_ready`, accepts one task atomically, receives child callbacks through `followUp`, and completes with `onlyne_swarm_reply`. `onlyne_mark_no_reply` closes a task without an outbound result.
+A swarm Pi session subscribes to loopback events, reports `swarm_ready`, accepts one hop atomically, spawns continuations with `swarm_send` (fire-and-forget), and exits with `swarm_complete` (done signal) or `swarm_quit` (silent, scheduler records failed). Downstream results travel through files and the ledger; nothing waits.
 
 For automatic startup in a generated workspace, add `.pi/onlyne.json`:
 

package/SPEC.md

@@ -8,7 +8,7 @@ Pi extension for Onlyne. Onlyne remains a workspace-local IM broker; this extens
 
 - Watch is configurable; default manual.
 - `/onlyne` provides argument completions for its supported subcommands, including daemon lifecycle commands.
-- `watch on` connects to the workspace-local `.onlyne/run/onlyne.sock`; if unavailable, it starts a Pi-owned workspace daemon.
+- `watch on` connects to the workspace-local `.onlyne/run/s`; if unavailable, it starts a Pi-owned workspace daemon.
 - `/onlyne daemon start|stop|restart` is the preferred lifecycle surface. Agents must not use ad-hoc `nohup onlyne run`, `pkill -f 'onlyne run'`, or global launchd/systemd jobs when pi-onlyne owns the daemon.
 - Inbound events come from Onlyne `subscribe_events`; no polling.
 - Inbound mode is rule-based: `auto-handle`, `queue-only`, or `muted`.
@@ -38,11 +38,25 @@ Stored in project `.pi/onlyne.json`:
 
 ## Tools
 
+Normal mode (default):
+
 - `onlyne_reply({ text })`
 - `onlyne_send({ channelId, text, rawText? })`
 - `onlyne_broadcast({ targets, text, rawText? })`
 - `onlyne_loopback({ text, rawText? })`
 - `onlyne_mark_no_reply({ reason? })`
+- `onlyne_daemon_start/stop/restart`
+
+Swarm mode (`[swarm] enabled`, see below):
+
+- `swarm_complete({ text })`
+- `swarm_quit({ reason? })`
+- `swarm_send({ to, text })`
+- `swarm_status()`
+- `onlyne_daemon_start/stop/restart`
+
+One session sees one toolset. The surface is chosen at `session_start` from
+`[swarm]` and applied with `setActiveTools` when the Pi API exists.
 
 ## Deferred
 
@@ -51,7 +65,7 @@ Stored in project `.pi/onlyne.json`:
 - Schedules.
 - Target groups.
 
-## Swarm mode (v2)
+## Swarm mode (v2, amendment-1)
 
 - Switch: `/onlyne swarm on|off|status`. On/off persists to the workspace
   `.onlyne/config.toml` `[swarm] enabled` flag and restarts watch. Status line
@@ -59,16 +73,26 @@ Stored in project `.pi/onlyne.json`:
 - When swarm is on, generic in/out auto-handling is disabled: the scheduler owns
   input/output. Only loopback messages carrying a `---swarm` body header enter
   the session, via the `followUp` task queue.
-- Session model: one session carries exactly one task (atomic slot). A new
-  header claims the slot; headers with matching `reply_to`/`task_id` arrive as
-  followUp callbacks for the suspended parent; headers for other tasks while
-  busy are ignored with an `[onlyne-internal]` notice.
+- Session model: one session carries exactly one hop, no exceptions. A new
+  header claims the slot; any further header while claimed is ignored
+  (the scheduler always opens a new session, so this guard never fires
+  on the normal path). No waiting, no callbacks, no parent bookkeeping.
 - Startup handshake: swarm watch sends the `swarm_ready` op
   (`{workspace, terminal_handle}`) so the scheduler can match a pending task.
   `ONLYNE_SWARM_TASK` env and `ORCA_TERMINAL_HANDLE`/`ONLYNE_TERMINAL_HANDLE`
   provide fallback correlation.
-- Tools: `onlyne_swarm_reply({text, rawText?})` writes the out message carrying
-  the task header (the scheduler's success signal) and ends the task slot.
-  `onlyne_mark_no_reply` additionally clears the swarm slot.
+- Tools: `swarm_complete({text})` writes the out message carrying this hop's
+  header (the scheduler's done signal). `swarm_quit({reason?})` exits silently
+  (scheduler records failed). `swarm_send({to, text})` spawns a downstream
+  task with `transfer_send_to` set to the current task and returns the child
+  id without waiting. `swarm_status()` reports the current task and spawned
+  ids. Daemon lifecycle tools stay available in both modes.
+- Generic send/reply tools are not registered in the swarm surface: unheaded
+  or misheaded writes would pollute the protocol. All swarm IO goes through
+  the `swarm_*` tools, whose headers are constructed inside the plugin
+  (`renderSwarmHeader`).
+- Exit guard: at `agent_end` with an unfinished hop, one followUp reminder
+  fires; a second quiet window auto-runs `swarm_quit` (failed ledger row).
 - Body protocol lives in `src/swarm.ts` (`parseSwarmHeader`,
   `renderSwarmHeader`, `readSwarmEnabled`); covered by `test/swarm.test.mjs`.
+  Old `reply_to` headers parse as ordinary (non-swarm) messages.

package/dist/index.js

@@ -6,8 +6,7 @@ import { findWorkspace } from "./workspace.js";
 import { envTaskId, parseSwarmHeader, readSwarmEnabled, terminalHandle } from "./swarm.js";
 import { SwarmSlot } from "./swarm-slot.js";
 const swarmSlot = new SwarmSlot();
-const slotTaskId = () => swarmSlot.task().taskId;
-const state = { cwd: process.cwd(), workspace: null, watching: false, owner: "stopped", swarm: false, swarmPending: 0 };
+const state = { cwd: process.cwd(), workspace: null, watching: false, owner: "stopped", swarm: false };
 const textResult = (text, details) => ({ content: [{ type: "text", text }], details });
 const currentConfig = () => loadConfig(state.cwd);
 function refreshSwarmFlag() { state.swarm = state.workspace ? readSwarmEnabled(state.workspace.onlyneDir) : false; }
@@ -54,7 +53,7 @@ function scheduleReconnect(pi) {
         }
     }, 1000);
 }
-/** Swarm-mode inbound path: single atomic task slot + followUp callbacks. */
+/** Swarm-mode inbound path: claim one hop, inject via followUp, never wait. */
 function handleSwarmInbound(pi, text, eventSeq) {
     const parsed = parseSwarmHeader(text);
     if (!parsed)
@@ -62,19 +61,14 @@ function handleSwarmInbound(pi, text, eventSeq) {
     if (state.socket && eventSeq !== undefined)
         void consumeEvent(state.socket, eventSeq).catch(() => { });
     // Slot transitions live in SwarmSlot (unit-tested); here we only mirror
-    // the outcome into session state (pending counter + task record).
-    const before = slotTaskId();
+    // the claimed task into session state. A claimed session never accepts
+    // another task; downstream work spawns new tasks via swarm_send.
     const outcome = swarmSlot.handle(pi, text);
-    const after = slotTaskId();
     if (outcome === "claimed") {
         const cur = swarmSlot.task();
-        state.swarmTask = { taskId: cur.taskId, from: cur.from, replyTo: cur.replyTo, attempt: cur.attempt, pendingReplies: 0 };
-        state.swarmPending = 0;
+        state.swarmTask = { taskId: cur.taskId, from: cur.from, transferSendTo: cur.transferSendTo, attempt: cur.attempt };
     }
-    else if (outcome === "callback" && before !== undefined && before === after) {
-        state.swarmPending = Math.max(0, state.swarmPending - 1);
-    }
-    return true;
+    return outcome === "claimed";
 }
 async function startWatch(pi) {
     state.workspace = findWorkspace(state.cwd);
@@ -136,7 +130,7 @@ async function startWatch(pi) {
     return `watching ${state.workspace.root} (${state.owner})`;
 }
 function stopWatch() { if (state.reconnectTimer)
-    clearTimeout(state.reconnectTimer); state.reconnectTimer = undefined; clearReminder(); state.socket?.destroy(); state.socket = undefined; stopProcess(state.child); state.child = undefined; state.watching = false; state.owner = "stopped"; state.swarmTask = undefined; state.swarmPending = 0; swarmSlot.clear(); return "watch stopped"; }
+    clearTimeout(state.reconnectTimer); state.reconnectTimer = undefined; clearReminder(); state.socket?.destroy(); state.socket = undefined; stopProcess(state.child); state.child = undefined; state.watching = false; state.owner = "stopped"; state.swarmTask = undefined; swarmSlot.clear(); return "watch stopped"; }
 async function startDaemon() { state.workspace = findWorkspace(state.cwd); if (!state.workspace)
     throw new Error("current workspace has no .onlyne configuration"); refreshSwarmFlag(); const conn = await connectDaemon(state.workspace, true); state.owner = conn.owner; state.child = conn.process; return `daemon ${state.owner === "extension" ? "started" : "already running"} for ${state.workspace.root}`; }
 async function stopDaemon() { if (!state.workspace)
@@ -149,28 +143,77 @@ async function reply(text) { if (!state.workspace)
     inbound.replied = true;
     clearReminder();
 } return res; }
-/** Swarm reply: writes the out message carrying the task header (success signal), ends the task slot. */
-async function swarmReply(text, rawText = false) {
+/** Resolve the current workspace tree path from the workspace root dir name. Root itself is ".". */
+function swarmTreePath() {
+    if (!state.workspace)
+        throw new Error("onlyne workspace not found");
+    const { basename } = require("node:path");
+    return state.workspace.root === process.cwd() ? "." : basename(state.workspace.root);
+}
+/** swarm_complete: hand over. Writes the out message carrying this hop's header (done signal). */
+async function swarmComplete(text) {
     if (!state.workspace)
         throw new Error("onlyne workspace not found");
     const task = state.swarmTask;
     if (!task)
         throw new Error("no active swarm task");
     const { renderSwarmHeader } = await import("./swarm.js");
-    const wire = renderSwarmHeader({ task_id: task.taskId, from: ".", reply_to: task.replyTo, attempt: task.attempt }, "", text);
-    const res = await sendWithRetry(state.workspace.socketPath, { channelId: "loopback" }, wire, currentConfig().outbound.retry.attempts, rawText);
+    const wire = renderSwarmHeader({ task_id: task.taskId, from: swarmTreePath(), transfer_send_to: task.transferSendTo, attempt: task.attempt }, "", text);
+    const res = await sendWithRetry(state.workspace.socketPath, { channelId: "loopback" }, wire, currentConfig().outbound.retry.attempts);
     if (res.ok) {
         state.swarmTask = undefined;
-        state.swarmPending = 0;
         swarmSlot.clear();
     }
     return { ...res, taskId: task.taskId };
 }
+/** swarm_quit: silent exit. No out written; the scheduler records failed. */
+async function swarmQuit(reason) {
+    const task = state.swarmTask;
+    state.swarmTask = undefined;
+    swarmSlot.clear();
+    return { quit: true, taskId: task?.taskId, reason: reason ?? "" };
+}
+/** swarm_send: spawn downstream. New UUID, transfer_send_to = current task, fire-and-forget. */
+async function swarmSend(to, text) {
+    if (!state.workspace)
+        throw new Error("onlyne workspace not found");
+    const task = state.swarmTask;
+    if (!task)
+        throw new Error("no active swarm task");
+    const { randomUUID } = await import("node:crypto");
+    const { renderSwarmHeader } = await import("./swarm.js");
+    const { existsSync } = await import("node:fs");
+    const { join, resolve } = await import("node:path");
+    // Resolve the target workspace dir: root "." or a tree path under the swarm tree.
+    // The scheduler owns the tree; here we only verify the send-side symlink exists
+    // (missing target = dangling link = error, never a blind FIFO write).
+    const wsRoot = state.workspace.root;
+    const linkPath = to === "." || to === "_root"
+        ? join(wsRoot, "onlyne_in", "_root")
+        : join(wsRoot, "onlyne_in", ...to.split("/").filter(Boolean));
+    const resolved = resolve(wsRoot);
+    const linkDir = resolve(linkPath);
+    if (!linkDir.startsWith(resolved))
+        throw new Error(`invalid swarm_send target: ${to}`);
+    if (!existsSync(linkPath))
+        throw new Error(`unknown swarm_send target (missing onlyne_in link): ${to}`);
+    const childId = randomUUID();
+    const wire = renderSwarmHeader({ task_id: childId, from: swarmTreePath(), transfer_send_to: task.taskId, attempt: 1 }, "", text);
+    const { writeFileSync } = await import("node:fs");
+    try {
+        writeFileSync(linkPath, wire);
+    }
+    catch (e) {
+        throw new Error(`swarm_send failed for ${to}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    swarmSlot.noteSpawned(childId);
+    return { childId, to };
+}
 export default function onlyne(pi) {
     pi.on("session_start", async (_event, ctx) => { const resumeWatch = state.watching; if (state.owner === "extension")
         await stopDaemon().catch(() => { });
     else
-        stopWatch(); state.cwd = ctx.cwd; state.workspace = findWorkspace(ctx.cwd); state.currentInbound = undefined; state.lastValidOutput = undefined; state.swarmTask = undefined; state.swarmPending = 0; swarmSlot.clear(); refreshSwarmFlag(); ctx.ui.setStatus("onlyne", state.workspace ? (state.swarm ? "onlyne: swarm" : "onlyne: ready") : "onlyne: no .onlyne"); if ((currentConfig().watch.autoStart || resumeWatch) && state.workspace) {
+        stopWatch(); state.cwd = ctx.cwd; state.workspace = findWorkspace(ctx.cwd); state.currentInbound = undefined; state.lastValidOutput = undefined; state.swarmTask = undefined; swarmSlot.clear(); refreshSwarmFlag(); applyToolSurface(pi); ctx.ui.setStatus("onlyne", state.workspace ? (state.swarm ? "onlyne: swarm" : "onlyne: ready") : "onlyne: no .onlyne"); if ((currentConfig().watch.autoStart || resumeWatch) && state.workspace) {
         try {
             ctx.ui.notify(await startWatch(pi), "info");
         }
@@ -187,7 +230,10 @@ export default function onlyne(pi) {
     pi.on("message_end", async (event) => { const text = typeof event.content === "string" ? event.content.trim() : ""; if (text && !text.startsWith("{") && !text.startsWith("[onlyne-internal]"))
         state.lastValidOutput = text; });
     pi.on("agent_start", async () => clearReminder());
-    pi.on("agent_end", async () => scheduleReminder(pi));
+    pi.on("agent_end", async () => { if (state.swarm)
+        scheduleSwarmExitReminder(pi);
+    else
+        scheduleReminder(pi); });
     pi.registerCommand("onlyne", {
         description: "Onlyne watch/status/config commands",
         getArgumentCompletions: (prefix) => {
@@ -211,8 +257,10 @@ export default function onlyne(pi) {
                     ctx.ui.notify(await restartDaemon(), "info");
                 else if (cmd === "status")
                     ctx.ui.notify(`onlyne ${state.watching ? "watching" : "stopped"}; owner=${state.owner}; swarm=${state.swarm ? "on" : "off"}; workspace=${state.workspace?.root ?? "none"}`, "info");
-                else if (cmd === "swarm" && sub === "status")
-                    ctx.ui.notify(`swarm=${state.swarm ? "on" : "off"}; task=${state.swarmTask?.taskId ?? "none"}; pending=${state.swarmPending}`, "info");
+                else if (cmd === "swarm" && sub === "status") {
+                    const cur = swarmSlot.task();
+                    ctx.ui.notify(`swarm=${state.swarm ? "on" : "off"}; task=${cur.taskId ?? "none"}; spawned=${cur.sentChildIds.length}`, "info");
+                }
                 else if (cmd === "swarm" && (sub === "on" || sub === "off")) {
                     ctx.ui.notify(await setSwarm(pi, sub === "on"), "info");
                 }
@@ -230,11 +278,32 @@ export default function onlyne(pi) {
             }
         },
     });
+    registerNormalTools(pi);
+    registerSwarmTools(pi);
+    applyToolSurface(pi);
+}
+const NORMAL_TOOLS = ["onlyne_daemon_start", "onlyne_daemon_stop", "onlyne_daemon_restart", "onlyne_reply", "onlyne_send", "onlyne_broadcast", "onlyne_loopback", "onlyne_mark_no_reply"];
+const SWARM_TOOLS = ["onlyne_daemon_start", "onlyne_daemon_stop", "onlyne_daemon_restart", "swarm_complete", "swarm_quit", "swarm_send", "swarm_status"];
+/** Tool surface follows [swarm] at session start: one mode, one toolset. */
+function applyToolSurface(pi) {
+    try {
+        const active = new Set(typeof pi.getActiveTools === "function" ? pi.getActiveTools() : []);
+        const all = typeof pi.getAllTools === "function" ? pi.getAllTools().map((t) => t.name) : [];
+        const keep = state.swarm ? SWARM_TOOLS : NORMAL_TOOLS;
+        const next = [...active].filter((n) => all.includes(n) && !(NORMAL_TOOLS.includes(n) || SWARM_TOOLS.includes(n)));
+        for (const n of keep)
+            if (all.includes(n) && !next.includes(n))
+                next.push(n);
+        if (typeof pi.setActiveTools === "function")
+            pi.setActiveTools(next);
+    }
+    catch { /* older pi without tool-surface API: both sets stay registered */ }
+}
+function registerNormalTools(pi) {
     pi.registerTool(defineTool({ name: "onlyne_daemon_start", label: "Onlyne daemon start", description: "Start or connect to the current workspace-local Onlyne daemon managed by pi-onlyne.", parameters: Type.Object({}), executionMode: "parallel", async execute() { const res = await startDaemon(); return textResult(res, { owner: state.owner, workspace: state.workspace?.root }); } }));
     pi.registerTool(defineTool({ name: "onlyne_daemon_stop", label: "Onlyne daemon stop", description: "Stop the current workspace-local Onlyne daemon when pi-onlyne manages it, without shelling out to pkill/nohup.", parameters: Type.Object({}), executionMode: "parallel", async execute() { const res = await stopDaemon(); return textResult(res, { owner: state.owner, workspace: state.workspace?.root }); } }));
     pi.registerTool(defineTool({ name: "onlyne_daemon_restart", label: "Onlyne daemon restart", description: "Restart the current workspace-local Onlyne daemon through pi-onlyne lifecycle management.", parameters: Type.Object({}), executionMode: "parallel", async execute() { const res = await restartDaemon(); return textResult(res, { owner: state.owner, workspace: state.workspace?.root }); } }));
     pi.registerTool(defineTool({ name: "onlyne_reply", label: "Onlyne reply", description: "Reply with plain text to the current Onlyne inbound message.", parameters: Type.Object({ text: Type.String() }), executionMode: "parallel", async execute(_id, params) { return textResult(JSON.stringify(await reply(params.text))); } }));
-    pi.registerTool(defineTool({ name: "onlyne_swarm_reply", label: "Onlyne swarm reply", description: "Swarm mode: write the task out message carrying the task header (the success signal) and end the task slot. Use for the active swarm task only.", parameters: Type.Object({ text: Type.String(), rawText: Type.Optional(Type.Boolean()) }), executionMode: "parallel", async execute(_id, params) { return textResult(JSON.stringify(await swarmReply(params.text, params.rawText ?? false))); } }));
     pi.registerTool(defineTool({ name: "onlyne_send", label: "Onlyne send", description: "Send Markdown to the channel's configured Onlyne conversation. Set rawText=true only for literal plain text.", parameters: Type.Object({ channelId: Type.String(), text: Type.String(), rawText: Type.Optional(Type.Boolean()) }), executionMode: "parallel", async execute(_id, params) { if (!state.workspace)
             throw new Error("onlyne workspace not found"); const res = await sendWithRetry(state.workspace.socketPath, params, params.text, currentConfig().outbound.retry.attempts, params.rawText ?? false); return textResult(JSON.stringify(res), res); } }));
     pi.registerTool(defineTool({ name: "onlyne_broadcast", label: "Onlyne broadcast", description: "Send Markdown to many configured Onlyne channels concurrently. Set rawText=true only for literal plain text.", parameters: Type.Object({ targets: Type.Array(Type.Object({ channelId: Type.String() })), text: Type.String(), rawText: Type.Optional(Type.Boolean()) }), executionMode: "parallel", async execute(_id, params) { if (!state.workspace)
@@ -244,12 +313,33 @@ export default function onlyne(pi) {
     pi.registerTool(defineTool({ name: "onlyne_mark_no_reply", label: "Onlyne no reply", description: "Mark the current Onlyne inbound message as intentionally not replied.", parameters: Type.Object({ reason: Type.Optional(Type.String()) }), executionMode: "parallel", async execute(_id, params) { if (state.currentInbound) {
             state.currentInbound.noReply = true;
             clearReminder();
-        } if (state.swarmTask) {
-            state.swarmTask = undefined;
-            state.swarmPending = 0;
-            swarmSlot.clear();
         } return textResult("marked no reply", params); } }));
 }
+function registerSwarmTools(pi) {
+    pi.registerTool(defineTool({ name: "swarm_complete", label: "Swarm complete", description: "Hand over this swarm hop: write the out message carrying this task header (done signal). The session becomes recyclable. Use once per swarm task.", parameters: Type.Object({ text: Type.String() }), executionMode: "parallel", async execute(_id, params) { return textResult(JSON.stringify(await swarmComplete(params.text))); } }));
+    pi.registerTool(defineTool({ name: "swarm_quit", label: "Swarm quit", description: "Quit this swarm hop silently: no out is written and the scheduler records failed. Use when the task premise does not hold or there is nothing to do.", parameters: Type.Object({ reason: Type.Optional(Type.String()) }), executionMode: "parallel", async execute(_id, params) { return textResult(JSON.stringify(await swarmQuit(params.reason))); } }));
+    pi.registerTool(defineTool({ name: "swarm_send", label: "Swarm send", description: "Spawn a downstream swarm task: write a new task to onlyne_in/<to>/ with transfer_send_to set to the current task. Fire-and-forget; returns the child id without waiting. Errors on missing targets.", parameters: Type.Object({ to: Type.String(), text: Type.String() }), executionMode: "parallel", async execute(_id, params) { return textResult(JSON.stringify(await swarmSend(params.to, params.text))); } }));
+    pi.registerTool(defineTool({ name: "swarm_status", label: "Swarm status", description: "Read-only swarm state: current task id, from, workspace path, and spawned child ids.", parameters: Type.Object({}), executionMode: "parallel", async execute() { const cur = swarmSlot.task(); return textResult(JSON.stringify({ taskId: cur.taskId ?? null, from: cur.from, transferSendTo: cur.transferSendTo, workspace: state.workspace?.root ?? null, spawned: cur.sentChildIds })); } }));
+}
+/** Swarm exit guard: at agent end, an unfinished hop gets one reminder, then auto-quit. */
+function scheduleSwarmExitReminder(pi, delayMs = 30_000) {
+    clearReminder();
+    if (!state.swarmTask)
+        return;
+    state.reminderTimer = setTimeout(() => {
+        state.reminderTimer = undefined;
+        if (!state.swarmTask)
+            return;
+        if (state.swarmTask) {
+            pi.sendUserMessage(`Swarm hop ${state.swarmTask.taskId} has no exit yet. Call swarm_complete with the handover summary, or swarm_quit when there is nothing to do.`, { deliverAs: "followUp" });
+            state.reminderTimer = setTimeout(() => {
+                state.reminderTimer = undefined;
+                if (state.swarmTask)
+                    void swarmQuit("auto-quit: no explicit exit").catch(() => { });
+            }, delayMs);
+        }
+    }, delayMs);
+}
 /** Toggle swarm mode: persists to .onlyne/config.toml [swarm] enabled, restarts watch. */
 async function setSwarm(pi, enabled) {
     if (!state.workspace)

package/dist/swarm-slot.d.ts

@@ -1,4 +1,4 @@
-export type SwarmHandleResult = "claimed" | "callback" | "busy-ignored" | "not-swarm";
+export type SwarmHandleResult = "claimed" | "not-swarm";
 export interface SwarmSlotMessage {
     text: string;
     deliverAs: "followUp";
@@ -16,21 +16,32 @@ export interface SwarmPi {
 export declare class SwarmSlot {
     private taskId?;
     private from;
-    private replyTo;
+    private transfer;
     private attempt;
+    private sentChildIds;
     handle(pi: SwarmPi, text: string): SwarmHandleResult;
     task(): {
         taskId?: string;
         from: string;
-        replyTo: string;
+        transferSendTo: string;
         attempt: number;
+        sentChildIds: string[];
     };
+    noteSpawned(childId: string): void;
     taskIdOf(): string | undefined;
     clear(): void;
 }
 /** Test seam: fresh slot without touching module-global pi-onlyne state. */
 export declare function __swarmSlotForTest(): {
     handle: (pi: SwarmPi, text: string) => SwarmHandleResult;
+    task: () => {
+        taskId?: string;
+        from: string;
+        transferSendTo: string;
+        attempt: number;
+        sentChildIds: string[];
+    };
     taskId: () => string | undefined;
+    noteSpawned: (childId: string) => void;
     clear: () => void;
 };

package/dist/swarm-slot.js

@@ -7,8 +7,9 @@ import { parseSwarmHeader } from "./swarm.js";
 export class SwarmSlot {
     taskId;
     from = ".";
-    replyTo = "";
+    transfer = "";
     attempt = 1;
+    sentChildIds = [];
     handle(pi, text) {
         const parsed = parseSwarmHeader(text);
         if (!parsed)
@@ -17,20 +18,19 @@ export class SwarmSlot {
         if (!this.taskId) {
             this.taskId = header.task_id;
             this.from = header.from;
-            this.replyTo = header.reply_to;
+            this.transfer = header.transfer_send_to;
             this.attempt = header.attempt;
-            pi.sendUserMessage(`Onlyne swarm task ${header.task_id} (from ${header.from}):\n\n${payload}\n\nWork this task atomically. Child task callbacks arrive as followUp messages. Finish with onlyne_swarm_reply carrying the reply Markdown, or onlyne_mark_no_reply to end without output.`, { deliverAs: "followUp" });
+            this.sentChildIds = [];
+            pi.sendUserMessage(`Onlyne swarm task ${header.task_id} (from ${header.from}):\n\n${payload}\n\nThis session carries this one task only. Restore context from files, work, spawn continuations with swarm_send when another unit must continue, then exit with swarm_complete. Downstream results travel through files and the ledger; nothing waits here.`, { deliverAs: "followUp" });
             return "claimed";
         }
-        if (header.reply_to === this.taskId || header.task_id === this.taskId) {
-            pi.sendUserMessage(`Onlyne swarm callback for ${this.taskId} (from ${header.from}):\n\n${payload}`, { deliverAs: "followUp" });
-            return "callback";
-        }
-        pi.sendUserMessage(`[onlyne-internal] swarm task ${header.task_id} ignored: session busy with ${this.taskId}.`, { deliverAs: "followUp" });
-        return "busy-ignored";
+        return "not-swarm";
     }
     task() {
-        return { taskId: this.taskId, from: this.from, replyTo: this.replyTo, attempt: this.attempt };
+        return { taskId: this.taskId, from: this.from, transferSendTo: this.transfer, attempt: this.attempt, sentChildIds: [...this.sentChildIds] };
+    }
+    noteSpawned(childId) {
+        this.sentChildIds.push(childId);
     }
     taskIdOf() {
         return this.taskId;
@@ -38,8 +38,9 @@ export class SwarmSlot {
     clear() {
         this.taskId = undefined;
         this.from = ".";
-        this.replyTo = "";
+        this.transfer = "";
         this.attempt = 1;
+        this.sentChildIds = [];
     }
 }
 /** Test seam: fresh slot without touching module-global pi-onlyne state. */
@@ -47,7 +48,9 @@ export function __swarmSlotForTest() {
     const slot = new SwarmSlot();
     return {
         handle: (pi, text) => slot.handle(pi, text),
+        task: () => slot.task(),
         taskId: () => slot.taskIdOf(),
+        noteSpawned: (childId) => slot.noteSpawned(childId),
         clear: () => slot.clear(),
     };
 }

package/dist/swarm.d.ts

@@ -2,7 +2,7 @@
 export interface SwarmHeader {
     task_id: string;
     from: string;
-    reply_to: string;
+    transfer_send_to: string;
     attempt: number;
 }
 export interface SwarmMessage {

package/dist/swarm.js

@@ -26,8 +26,9 @@ export function parseSwarmHeader(text) {
     }
     let task_id;
     let from = ".";
-    let reply_to = "";
+    let transfer_send_to = "";
     let attempt = 1;
+    let sawTransfer = false;
     for (const line of headRaw.split("\n")) {
         const t = line.trim();
         if (!t || t.startsWith("#"))
@@ -41,18 +42,24 @@ export function parseSwarmHeader(text) {
             task_id = v;
         else if (k === "from")
             from = v || ".";
+        else if (k === "transfer_send_to") {
+            transfer_send_to = v;
+            sawTransfer = true;
+        }
         else if (k === "reply_to")
-            reply_to = v;
+            return null;
         else if (k === "attempt")
             attempt = Number.parseInt(v, 10) || 1;
     }
+    if (!sawTransfer)
+        return null;
     if (!task_id || !UUID_RE.test(task_id.trim()))
         return null;
-    return { header: { task_id: task_id.trim(), from, reply_to, attempt }, payload };
+    return { header: { task_id: task_id.trim(), from, transfer_send_to, attempt }, payload };
 }
 /** Render a swarm body header in front of a Markdown payload. */
 export function renderSwarmHeader(header, role, payloadMarkdown) {
-    let s = `---swarm\ntask_id: ${header.task_id}\nfrom: ${header.from}\nreply_to: ${header.reply_to}\nattempt: ${header.attempt}\n---\n`;
+    let s = `---swarm\ntask_id: ${header.task_id}\nfrom: ${header.from}\ntransfer_send_to: ${header.transfer_send_to}\nattempt: ${header.attempt}\n---\n`;
     if (role)
         s += `## role: ${role}\n\n${role}\n`;
     s += payloadMarkdown;

package/dist/workspace.js

@@ -5,7 +5,7 @@ export function findWorkspace(start) {
     for (;;) {
         const onlyneDir = join(dir, ".onlyne");
         if (existsSync(onlyneDir))
-            return { root: dir, onlyneDir, socketPath: join(onlyneDir, "run", "onlyne.sock") };
+            return { root: dir, onlyneDir, socketPath: join(onlyneDir, "run", "s") };
         const parent = dirname(dir);
         if (parent === dir)
             return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-onlyne",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Pi extension tools for sending messages through Onlyne.",
   "type": "module",
   "main": "./dist/index.js",