pi-onlyne 0.8.0 → 0.9.1

package/dist/index.js

@@ -1,13 +1,14 @@
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { randomUUID } from "node:crypto";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { existsSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
 import { Type } from "typebox";
-import { broadcast, connectDaemon, consumeEvent, loopback, markConsumed, sendWithRetry, shutdownDaemon, stopProcess, subscribe, swarmReady, swarmRecycled } from "./onlyne.js";
+import { broadcast, connectDaemon, consumeEvent, loopback, markConsumed, sendWithRetry, sendSwarmReport, shutdownDaemon, stopProcess, subscribe, swarmBusy, swarmIdle, swarmReady, swarmRecycled } from "./onlyne.js";
 import { inboundModeFor, loadConfig, saveConfig } from "./config.js";
 import { findWorkspace } from "./workspace.js";
-import { envTaskId, parseSwarmCtl, parseSwarmHeader, readSwarmEnabled, readSwarmModel, terminalHandle, treePathForWorkspace } from "./swarm.js";
+import { envTaskId, hopActivityBody, isSwarmReportFrame, isSwarmTaskId, parseSwarmCtl, parseSwarmHeader, readSwarmEnabled, readSwarmModel, renderSwarmReport, selectHistoryDelivery, terminalHandle, treePathForWorkspace } from "./swarm.js";
 import { SwarmSlot } from "./swarm-slot.js";
+import { SwarmSessionState, restoreSwarmState } from "./session.js";
 const swarmSlot = new SwarmSlot();
 const state = { cwd: process.cwd(), workspace: null, watching: false, owner: "stopped", swarm: false };
 let cachedCtx = undefined;
@@ -19,6 +20,122 @@ function consumeIfNotified(inbound) { if (state.workspace && inbound.messageId)
     void markConsumed(state.workspace.socketPath, inbound.messageId).catch(() => { }); }
 function clearReminder() { if (state.reminderTimer)
     clearTimeout(state.reminderTimer); state.reminderTimer = undefined; }
+function swarmOpId(kind, suffix) {
+    const taskId = state.swarmSession?.taskId ?? state.swarmTask?.taskId ?? state.swarmTaskKey ?? `session:${terminalHandle() || state.workspace?.root || "unknown"}`;
+    const generation = state.swarmSession?.generation ?? 0;
+    return `swarm:${taskId}:g${generation}:${kind}${suffix ? `:${suffix}` : ""}`;
+}
+async function awaitSubscriptionAck(socket, timeoutMs = 5_000) {
+    let timer;
+    try {
+        return await Promise.race([
+            socket.ack,
+            new Promise((_, reject) => { timer = setTimeout(() => reject(new Error("swarm subscribe_events ack timeout")), timeoutMs); }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+function awaitIntent(intent) { void Promise.resolve(intent).catch(() => { }); }
+/** Task identity the scheduler owns, for lifecycle evidence. The claimed hop
+ * wins; before a claim an env-assigned task is already a scheduler row. A
+ * synthetic session key returns null and the report stays home: a frame the
+ * ledger cannot attribute raises an unknown-session alert on that side. */
+function swarmReportTaskId() {
+    for (const candidate of [state.swarmTask?.taskId, state.swarmSession?.taskId]) {
+        if (candidate && isSwarmTaskId(candidate))
+            return candidate.trim();
+    }
+    return null;
+}
+/** A report that failed to build or reach the daemon is recorded locally. The
+ * entry names the kind and the error, so a gap in the scheduler's view of this
+ * session is traceable to a frame this side can show. */
+function reportFault(kind, e) {
+    const message = e instanceof Error ? e.message : String(e);
+    try {
+        state.swarmSession?.transition({}, `swarm_report_fault:${kind}:${message}`);
+    }
+    catch { /* ledger unavailable */ }
+}
+/** Send the frame for an already-persisted watermark. One attempt per point:
+ * the op_id names (task, seq), and the next beat carries a fresh watermark, so
+ * a dropped frame costs one step of liveness evidence. */
+async function sendSwarmReportFrame(kind, seq) {
+    const session = state.swarmSession;
+    const ws = state.workspace;
+    const taskId = swarmReportTaskId();
+    if (!session || !ws || !taskId)
+        return false;
+    let frame;
+    try {
+        frame = renderSwarmReport(kind, taskId, session.generation, seq);
+    }
+    catch (e) {
+        reportFault(kind, e);
+        return false;
+    }
+    try {
+        await sendSwarmReport(ws.socketPath, frame, swarmOpId(`report_${kind}`, `${taskId}:${seq}`));
+        return true;
+    }
+    catch (e) {
+        reportFault(kind, e);
+        return false;
+    }
+}
+/** Advance the durable watermark and carry it to the daemon. Persisting under
+ * the report's own kind names the lifecycle point in the local ledger, and
+ * persisting before sending gives every point its own strictly increasing seq
+ * within this generation — the ordering the reducer's watermark compares
+ * against. */
+async function emitSwarmReport(kind) {
+    const session = state.swarmSession;
+    if (!session)
+        return false;
+    try {
+        return await sendSwarmReportFrame(kind, session.transition({}, `swarm_report_${kind}`).seq);
+    }
+    catch (e) {
+        reportFault(kind, e);
+        return false;
+    }
+}
+function swarmHeartbeat() {
+    const session = state.swarmSession;
+    if (!session)
+        return;
+    let seq;
+    try {
+        seq = session.heartbeat().seq;
+    }
+    catch (e) {
+        session.transition({ recovery: "idle_fault" }, `swarm_heartbeat_fault:${e instanceof Error ? e.message : String(e)}`);
+        session.stopHeartbeat();
+        return;
+    }
+    awaitIntent(sendSwarmReportFrame("heartbeat", seq));
+}
+function swarmSessionTransition(patch, kind) { state.swarmSession?.transition(patch, kind); }
+async function sendSwarmIntent(kind, payload, send, maxAttempts = 3, opId = swarmOpId(kind)) {
+    const session = state.swarmSession;
+    if (!session)
+        return send(opId);
+    session.recordIntent(kind, payload, opId);
+    const intent = await session.retry(opId, async () => {
+        const receipt = await send(opId);
+        if (receipt && typeof receipt === "object" && receipt.ok === false)
+            throw new Error(JSON.stringify(receipt.error ?? receipt));
+        return receipt;
+    }, maxAttempts);
+    if (intent.status !== "accepted") {
+        session.transition({ agent: "gone", resource: "closed", recovery: "idle_fault" }, `${kind}_fault`);
+        throw new Error(`${kind} intent exhausted${intent.last_error ? `: ${intent.last_error}` : ""}`);
+    }
+    return intent.receipt;
+}
 function needsReply(inbound = state.currentInbound) { return !!inbound && !inbound.replied && !inbound.noReply && !!state.workspace; }
 function scheduleReminder(pi, delayMs = 30_000) {
     clearReminder();
@@ -50,7 +167,7 @@ function scheduleReconnect(pi) {
         if (!state.watching)
             return;
         try {
-            await startWatch(pi);
+            await startWatch(pi, state.swarmContext);
         }
         catch {
             scheduleReconnect(pi);
@@ -98,54 +215,45 @@ async function historyTaskDone(taskId) {
 async function catchUpSwarmHistory(pi, ctx) {
     if (swarmSlot.task().taskId)
         return;
-    try {
-        const { request } = await import("./onlyne.js");
-        if (!state.workspace)
-            return;
-        const env = envTaskId();
-        const res = await request(state.workspace.socketPath, { id: "hist", op: "fetch_channel_history", channel_id: "loopback", limit: 30 });
-        const items = res?.data ?? res ?? [];
-        if (!Array.isArray(items))
-            return;
-        const inbounds = [];
-        const outs = new Set();
-        for (const m of items) {
-            const text = m?.text ?? m?.content ?? "";
-            if (typeof text !== "string" || !text.startsWith("---swarm"))
-                continue;
-            if (text.startsWith("---swarm-ctl"))
-                continue;
-            const p = parseSwarmHeader(text);
-            if (!p)
-                continue;
-            if (m?.direction === "outbound")
-                outs.add(p.header.task_id);
-            else
-                inbounds.push(text);
-        }
-        // Env task first: exact task_id match on inbound, even if an out exists
-        // (out may belong to a previous generation; scheduler owns the truth).
-        if (env) {
-            for (const text of inbounds) {
-                const p = parseSwarmHeader(text);
-                if (p.header.task_id === env) {
-                    if (handleSwarmInbound(pi, text, undefined, ctx))
-                        return;
-                }
-            }
-        }
-        // Fallback: newest inbound with no out yet.
-        for (let i = inbounds.length - 1; i >= 0; i--) {
-            const p = parseSwarmHeader(inbounds[i]);
-            if (outs.has(p.header.task_id))
-                continue;
-            if (p.header.task_id === env)
-                continue; // already tried above
-            if (handleSwarmInbound(pi, inbounds[i]))
-                return;
+    const { request } = await import("./onlyne.js");
+    if (!state.workspace)
+        return;
+    const env = envTaskId();
+    const res = await request(state.workspace.socketPath, { id: "hist", op: "fetch_channel_history", channel_id: "loopback", limit: 30 });
+    const items = res?.data ?? res ?? [];
+    if (!Array.isArray(items))
+        return;
+    const inbounds = [];
+    const outs = new Set();
+    for (const m of items) {
+        const text = m?.text ?? m?.content ?? "";
+        if (typeof text !== "string" || !text.startsWith("---swarm"))
+            continue;
+        if (text.startsWith("---swarm-ctl"))
+            continue;
+        // Own lifecycle evidence shares this history. A report frame carries no
+        // task header, so it must pass before the malformed-header check.
+        if (isSwarmReportFrame(text))
+            continue;
+        const p = parseSwarmHeader(text);
+        if (!p) {
+            if (text.startsWith("---swarm"))
+                state.swarmSession?.transition({ agent: "gone", resource: "closed", recovery: "idle_fault" }, "swarm_protocol_fault");
+            continue;
         }
+        if (m?.direction === "outbound")
+            outs.add(p.header.task_id);
+        else
+            inbounds.push(text);
     }
-    catch { /* best effort; live events still arrive */ }
+    // A scheduler-created terminal has an env task id. In that case this
+    // selector returns only the matching wire or undefined: it must never
+    // fall back to an old history task while the new FIFO write races the
+    // initial catchup. Manual ready-pool sessions have no env and retain
+    // newest-unclosed fallback selection.
+    const selected = selectHistoryDelivery(env || undefined, inbounds, outs);
+    if (selected)
+        handleSwarmInbound(pi, selected, undefined, ctx);
 }
 /** Pin the tab title for a claimed hop. Pi rewrites the create-time title on
  * boot and on idle transitions, and the scheduler-side rename races those
@@ -159,27 +267,58 @@ function pinSwarmTitle(ctx, taskId) {
 }
 /** Swarm-mode inbound path: claim one hop, inject via followUp, never wait. */
 function handleSwarmInbound(pi, text, eventSeq, ctx) {
-    const parsed = parseSwarmHeader(text);
-    if (!parsed)
+    // A report frame is this session's own evidence relayed back on the event
+    // stream. It is neither a task delivery nor a protocol fault.
+    if (isSwarmReportFrame(text))
+        return false;
+    let parsed;
+    try {
+        parsed = parseSwarmHeader(text);
+    }
+    catch (e) {
+        state.swarmSession?.transition({ agent: "gone", resource: "closed", recovery: "idle_fault" }, `swarm_protocol_fault:${e instanceof Error ? e.message : String(e)}`);
+        return false;
+    }
+    if (!parsed) {
+        if (text.startsWith("---swarm"))
+            state.swarmSession?.transition({ agent: "gone", resource: "closed", recovery: "idle_fault" }, "swarm_protocol_fault");
         return false;
+    }
     if (state.socket && eventSeq !== undefined)
-        void consumeEvent(state.socket, eventSeq).catch(() => { });
+        awaitIntent(consumeEvent(state.socket, eventSeq).catch(() => { }));
     // Slot transitions live in SwarmSlot (unit-tested); here we only mirror
     // 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, envTaskId() || undefined, state.workspace?.root);
+    const outcome = (() => { try {
+        return swarmSlot.handle(pi, text, envTaskId() || undefined, state.workspace?.root);
+    }
+    catch (e) {
+        state.swarmSession?.transition({ agent: "gone", resource: "closed", recovery: "idle_fault" }, `swarm_slot_fault:${e instanceof Error ? e.message : String(e)}`);
+        return "fault";
+    } })();
     if (outcome === "claimed" || outcome === "yielded") {
         const cur = swarmSlot.task();
         state.swarmTask = { taskId: cur.taskId, from: cur.from, transferSendTo: cur.transferSendTo, attempt: cur.attempt };
+        state.swarmTaskKey = cur.taskId;
+        const sessionCtx = state.swarmContext;
+        if (sessionCtx?.appendEntry) {
+            const restored = restoreSwarmState(sessionCtx, cur.taskId);
+            state.swarmSession?.stopHeartbeat();
+            state.swarmSession = new SwarmSessionState(sessionCtx, cur.taskId, restored);
+            state.swarmSession.startSession();
+            state.swarmSession.transition({ agent: "ready", resource: "attached", lifecycle: "working", recovery: "idle_waiting" }, "swarm_task_claimed");
+            state.swarmSession.startHeartbeat(10_000, swarmHeartbeat);
+        }
         if (ctx)
             void pinSwarmTitle(ctx, cur.taskId);
     }
     return outcome === "claimed" || outcome === "yielded";
 }
-async function startWatch(pi) {
+async function startWatch(pi, ctx) {
     state.workspace = findWorkspace(state.cwd);
     if (!state.workspace)
         throw new Error("current workspace has no .onlyne configuration");
+    state.swarmContext = ctx ?? state.swarmContext ?? cachedCtx;
     refreshSwarmFlag();
     if (state.reconnectTimer)
         clearTimeout(state.reconnectTimer);
@@ -212,20 +351,41 @@ async function startWatch(pi) {
             // the slot guard + scheduler task_id dedup.
             if (parseSwarmCtl(inbound.text)) {
                 const ctl = parseSwarmCtl(inbound.text);
-                void handleSwarmRecycle(ctl.task_id, ctl.reason);
+                awaitIntent(handleSwarmRecycle(ctl.task_id, ctl.reason));
                 return;
             }
-            void catchUpSwarmHistory(pi);
+            void Promise.resolve(catchUpSwarmHistory(pi)).catch((e) => state.swarmSession?.transition({ agent: "gone", resource: "closed", recovery: "idle_fault" }, `history_catchup_fault:${e instanceof Error ? e.message : String(e)}`));
             handleSwarmInbound(pi, inbound.text, line.event_seq);
         }, () => { if (state.socket === socket)
             scheduleReconnect(pi); }, { priority: 1 });
         state.socket = socket;
         state.watching = true;
-        const task = envTaskId();
         try {
-            await swarmReady(ws.socketPath, ws.root, terminalHandle());
+            await awaitSubscriptionAck(socket);
+        }
+        catch (e) {
+            state.swarmSession?.transition({ agent: "gone", resource: "closed", recovery: "idle_fault" }, "subscribe_events_fault");
+            throw e;
+        }
+        const task = envTaskId();
+        const sessionTaskId = task || state.swarmTaskKey || `session:${terminalHandle() || randomUUID()}`;
+        state.swarmTaskKey = sessionTaskId;
+        const sessionCtx = state.swarmContext;
+        if (sessionCtx?.appendEntry) {
+            const restored = restoreSwarmState(sessionCtx, sessionTaskId);
+            state.swarmSession?.stopHeartbeat();
+            state.swarmSession = new SwarmSessionState(sessionCtx, sessionTaskId, restored);
+            state.swarmSession.startSession();
+        }
+        const readyPayload = { workspace: ws.root, terminal_handle: terminalHandle() };
+        await sendSwarmIntent("swarm_ready", readyPayload, (opId) => swarmReady(ws.socketPath, ws.root, terminalHandle(), state.swarmSession?.snapshot(), opId), currentConfig().outbound.retry.attempts);
+        if (state.swarmSession) {
+            state.swarmSession.transition({ agent: "ready", resource: "attached", lifecycle: "idle", recovery: "idle_waiting" }, "swarm_ready");
+            // Awaits the daemon receipt: the scheduler holds this session's first
+            // watermark before it reads anything else from the workspace.
+            await emitSwarmReport("ready");
+            state.swarmSession.startHeartbeat(10_000, swarmHeartbeat);
         }
-        catch { /* scheduler may read env fallback */ }
         // The task may already sit in history (scheduler wrote in before this
         // session finished starting). Claim it now instead of waiting for a
         // live event that already fired.
@@ -252,8 +412,13 @@ async function startWatch(pi) {
     state.watching = true;
     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; swarmSlot.clear(); return "watch stopped"; }
+function stopWatch(clearSession = true) { if (state.reconnectTimer)
+    clearTimeout(state.reconnectTimer); state.reconnectTimer = undefined; clearReminder(); state.socket?.destroy(); state.socket = undefined; stopProcess(state.child); state.child = undefined; if (clearSession) {
+    state.swarmSession?.shutdown();
+    state.swarmSession = undefined;
+}
+else
+    state.swarmSession?.stopHeartbeat(); 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)
@@ -272,7 +437,6 @@ function swarmTreePath() {
         throw new Error("onlyne workspace not found");
     return treePathForWorkspace(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");
@@ -281,63 +445,80 @@ async function swarmComplete(text) {
         throw new Error("no active swarm task");
     const { renderSwarmHeader } = await import("./swarm.js");
     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;
-        swarmSlot.clear();
-    }
-    return { ...res, taskId: task.taskId };
-}
-/** swarm_quit: speak, then die by our own hand. Sends the exit notice
- * (same op the recycle path uses, reason quit:<reason>) so the scheduler
- * records failed immediately instead of leaving the task pinned running;
- * then releases the watch and exits this process. The scheduler only ever
- * closes the tab. */
+    const payload = { task_id: task.taskId, text: wire };
+    const result = await sendSwarmIntent("swarm_complete", payload, (opId) => sendWithRetry(state.workspace.socketPath, { channelId: "loopback" }, wire, 1, false, opId), currentConfig().outbound.retry.attempts, swarmOpId("swarm_complete", task.taskId));
+    state.swarmSession?.transition({ agent: "ready", resource: "closing", lifecycle: "exited", recovery: "draining" }, "swarm_complete");
+    // Awaits the daemon receipt on the terminal evidence for this generation.
+    await emitSwarmReport("complete");
+    state.swarmTask = undefined;
+    swarmSlot.clear();
+    clearReminder();
+    try {
+        stopWatch(false);
+    }
+    catch { /* lifecycle cleanup */ }
+    setTimeout(() => process.exit(0), 300);
+    return { ...(result && typeof result === "object" ? result : { ok: true }), taskId: task.taskId };
+}
 async function swarmQuit(reason) {
     const task = state.swarmTask;
     const taskId = task?.taskId ?? "";
     const why = `quit:${reason ?? ""}`;
-    try {
-        if (state.workspace && taskId) {
-            await swarmRecycled(state.workspace.socketPath, taskId, terminalHandle(), why);
+    if (state.workspace && taskId) {
+        try {
+            await sendSwarmIntent("swarm_recycled", { task_id: taskId, reason: why }, (opId) => swarmRecycled(state.workspace.socketPath, taskId, terminalHandle(), why, opId), currentConfig().outbound.retry.attempts, swarmOpId("swarm_recycled", `quit:${taskId}`));
         }
+        catch { /* fault persists; quit still exits */ }
     }
-    catch { /* daemon may be gone; exit anyway */ }
+    // A quit writes no out, so Failed is the accurate projection of this hop.
+    // The report carries this session's own watermark next to the swarm_recycled
+    // ack above, and its receipt is collected before the exit path runs.
+    await emitSwarmReport("fault");
     clearReminder();
     try {
-        stopWatch();
+        stopWatch(false);
     }
-    catch { /* already stopped */ }
+    catch { /* lifecycle cleanup */ }
     state.swarmTask = undefined;
     swarmSlot.clear();
     setTimeout(() => process.exit(0), 300);
     return { quit: true, taskId, reason: reason ?? "" };
 }
-/** Handle a downlink recycle signal: accept, ack, release, self-terminate.
- * No out is written (the scheduler already recorded the terminal state). */
 async function handleSwarmRecycle(ctlTaskId, reason) {
     const claimed = swarmSlot.task().taskId;
     const taskId = ctlTaskId === "*" ? (claimed ?? "") : ctlTaskId;
     if (claimed && ctlTaskId !== "*" && claimed !== ctlTaskId)
         return false;
     const why = `recycle:${reason}`;
-    try {
-        if (state.workspace && taskId) {
-            await swarmRecycled(state.workspace.socketPath, taskId, terminalHandle(), why);
+    // The scheduler initiated this recycle, so its own ledger already holds the
+    // truth about the hop. A report from here would restate a transition that
+    // side drove, hence no lifecycle report on this path.
+    if (state.workspace && taskId) {
+        try {
+            await sendSwarmIntent("swarm_recycled", { task_id: taskId, reason: why }, (opId) => swarmRecycled(state.workspace.socketPath, taskId, terminalHandle(), why, opId), currentConfig().outbound.retry.attempts, swarmOpId("swarm_recycled", `recycle:${taskId}`));
         }
+        catch { /* fault persists; recycle still exits */ }
     }
-    catch { /* daemon may be gone; exit anyway */ }
     clearReminder();
     try {
-        stopWatch();
+        stopWatch(false);
     }
-    catch { /* already stopped */ }
+    catch { /* lifecycle cleanup */ }
     state.swarmTask = undefined;
     swarmSlot.clear();
     setTimeout(() => process.exit(0), 300);
     return true;
 }
-/** swarm_send: spawn downstream. New UUID, transfer_send_to = current task, fire-and-forget. */
+/** Resolve a scheduler target symlink to that workspace's daemon socket. */
+function swarmTargetSocket(linkPath, workspaceRoot) {
+    const targetIn = realpathSync(linkPath);
+    const root = resolve(workspaceRoot);
+    if (!targetIn.startsWith(root + "/") || !targetIn.endsWith("/.onlyne/channels/loopback/in"))
+        throw new Error(`invalid swarm_send target: ${linkPath}`);
+    const targetOnlyne = dirname(dirname(dirname(targetIn)));
+    return join(targetOnlyne, "run", "s");
+}
+/** swarm_send: spawn downstream through the target daemon's loopback RPC. */
 async function swarmSend(to, text) {
     if (!state.workspace)
         throw new Error("onlyne workspace not found");
@@ -345,27 +526,13 @@ async function swarmSend(to, text) {
     if (!task)
         throw new Error("no active swarm task");
     const { renderSwarmHeader } = await import("./swarm.js");
-    // 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 linkPath = to === "." || to === "_root" ? join(wsRoot, "onlyne_in", "_root") : join(wsRoot, "onlyne_in", ...to.split("/").filter(Boolean));
     const childId = randomUUID();
     const wire = renderSwarmHeader({ task_id: childId, from: swarmTreePath(), transfer_send_to: task.taskId, attempt: 1 }, "", text);
-    try {
-        writeFileSync(linkPath, wire);
-    }
-    catch (e) {
-        throw new Error(`swarm_send failed for ${to}: ${e instanceof Error ? e.message : String(e)}`);
-    }
+    const targetSocket = swarmTargetSocket(linkPath, wsRoot);
+    const payload = { child_id: childId, to, task_id: task.taskId, text: wire };
+    await sendSwarmIntent("swarm_send", payload, (opId) => loopback(targetSocket, wire, true, opId), currentConfig().outbound.retry.attempts, swarmOpId("swarm_send", childId));
     swarmSlot.noteSpawned(childId);
     return { childId, to };
 }
@@ -420,15 +587,16 @@ export default function onlyne(pi) {
         process.once(sig, () => stopWatch());
     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_start", async () => { clearReminder(); swarmSessionTransition({ agent: "running", lifecycle: "working", recovery: "idle_waiting" }, "turn_start"); awaitIntent(emitSwarmReport("turn_started")); reportHopBusy().catch(() => { }); });
     pi.on("agent_end", async () => { if (state.swarm) {
         const cur = swarmSlot.task();
         if (cur.taskId && cachedCtx)
             void pinSwarmTitle(cachedCtx, cur.taskId);
+        swarmSessionTransition({ agent: "idle", lifecycle: "idle", recovery: "idle_waiting" }, "turn_idle");
         scheduleSwarmExitReminder(pi);
     }
     else
-        scheduleReminder(pi); });
+        scheduleReminder(pi); reportHopIdle().catch(() => { }); });
     pi.registerCommand("onlyne", {
         description: "Onlyne watch/status/config commands",
         getArgumentCompletions: (prefix) => {
@@ -496,9 +664,9 @@ function applyToolSurface(pi) {
 }
 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_stop", label: "Onlyne daemon stop", description: "Stop the current workspace-local Onlyne daemon through pi-onlyne lifecycle management. The tool also sends shutdown to a daemon already running in this workspace.", 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_reply", label: "Onlyne reply", description: "Reply with Markdown to the current Onlyne inbound message. Use Markdown by default and preserve the message as one document.", 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_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)
@@ -513,9 +681,27 @@ function registerNormalTools(pi) {
 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_send", label: "Swarm send", description: "Spawn a downstream swarm task through the target workspace daemon loopback RPC with transfer_send_to set to the current task. Stable op_id makes retries idempotent; 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 })); } }));
 }
+/** R4 hop activity reporters: turn-granularity busy/idle over the existing
+ * swarm event channel. Fire-and-forget (failures silent): the scheduler
+ * treats missing rows as race residue, and its TTLs are the backstop.
+ * busy fires only with a live claimed task; idle fires only when the turn
+ * ended without an out (swarmTask still set). The decision (guard +
+ * pending_exit) is the shared, unit-tested hopActivityBody. */
+async function reportHopBusy() {
+    const body = hopActivityBody("busy", { swarm: state.swarm, workspaceRoot: state.workspace?.root, terminal: terminalHandle(), taskId: state.swarmTask?.taskId });
+    if (!body || !state.workspace)
+        return;
+    await sendSwarmIntent("swarm_busy", body, (opId) => swarmBusy(state.workspace.socketPath, body, opId), currentConfig().outbound.retry.attempts, swarmOpId("swarm_busy", `${state.swarmTask?.taskId ?? ""}:${state.swarmSession?.seq ?? 0}`));
+}
+async function reportHopIdle() {
+    const body = hopActivityBody("idle", { swarm: state.swarm, workspaceRoot: state.workspace?.root, terminal: terminalHandle(), taskId: state.swarmTask?.taskId });
+    if (!body || !state.workspace)
+        return;
+    await sendSwarmIntent("swarm_idle", body, (opId) => swarmIdle(state.workspace.socketPath, body, opId), currentConfig().outbound.retry.attempts, swarmOpId("swarm_idle", `${state.swarmTask?.taskId ?? ""}:${state.swarmSession?.seq ?? 0}`));
+}
 /** Swarm exit guard: at agent end, an unfinished hop gets one reminder, then auto-quit. */
 function scheduleSwarmExitReminder(pi, delayMs = 30_000) {
     clearReminder();
@@ -574,3 +760,21 @@ async function setSwarm(pi, enabled) {
     }
     return `swarm ${enabled ? "on" : "off"} (watch not running)`;
 }
+/** Test seam: drive the lifecycle-report wiring against a stub daemon socket.
+ * No live pi session and no real daemon are involved; the seam exposes the
+ * same closures the hooks call. Mirrors `__swarmSlotForTest`. */
+export function __swarmReportForTest() {
+    return {
+        setWorkspace: (ws) => { state.workspace = ws; },
+        beginSession: (appendEntry, taskId) => {
+            state.swarmSession?.shutdown();
+            state.swarmSession = new SwarmSessionState({ appendEntry }, taskId);
+            state.swarmSession.startSession();
+            return { generation: state.swarmSession.generation, seq: state.swarmSession.seq };
+        },
+        setTask: (task) => { state.swarmTask = task; },
+        reportTaskId: swarmReportTaskId,
+        emit: emitSwarmReport,
+        beat: swarmHeartbeat,
+    };
+}