pi-onlyne 0.8.0 → 0.9.1

package/dist/onlyne.d.ts

@@ -4,12 +4,15 @@ import type { Workspace } from "./workspace.js";
 export interface OnlyneRequest {
     id: string;
     op: string;
+    op_id?: string;
     channel_id?: string;
+    conversation_id?: string;
     message_id?: string;
     text?: string;
     format?: "plain" | "markdown";
     raw_text?: boolean;
     limit?: number;
+    offset?: number;
     priority?: number;
     consume_timeout_ms?: number;
     event_seq?: number;
@@ -22,10 +25,13 @@ export interface SendResult extends SendTarget {
     error?: string;
 }
 export declare function request(socketPath: string, req: OnlyneRequest): Promise<any>;
+export interface SwarmSubscription extends Socket {
+    ack: Promise<any>;
+}
 export declare function subscribe(socketPath: string, onLine: (line: any) => void, onDisconnect?: () => void, opts?: {
     priority?: number;
     consumeTimeoutMs?: number;
-}): Socket;
+}): SwarmSubscription;
 export declare function waitForSocket(socketPath: string, timeoutMs?: number): Promise<void>;
 export declare function connectDaemon(ws: Workspace, startIfMissing?: boolean): Promise<{
     owner: "external" | "extension";
@@ -33,10 +39,32 @@ export declare function connectDaemon(ws: Workspace, startIfMissing?: boolean):
 }>;
 export declare function shutdownDaemon(ws: Workspace, child?: ChildProcess): Promise<void>;
 export declare function stopProcess(child?: ChildProcess): void;
-export declare function swarmReady(socketPath: string, workspace: string, terminalHandle: string): Promise<any>;
-export declare function swarmRecycled(socketPath: string, taskId: string, terminalHandle: string, reason: string): Promise<any>;
+export declare function swarmReady(socketPath: string, workspace: string, terminalHandle: string, snapshot?: unknown, opId?: string): Promise<any>;
+export declare function swarmRecycled(socketPath: string, taskId: string, terminalHandle: string, reason: string, opId?: string): Promise<any>;
+/** R4 hop activity: turn started. Fire-and-forget; the scheduler treats a
+ * missing task row as race residue and drops it silently. `body` comes from
+ * swarm.ts hopActivityBody (the shared, unit-tested decision). */
+export declare function swarmBusy(socketPath: string, body: {
+    workspace: string;
+    terminal_handle: string;
+    task_id: string;
+}, opId?: string): Promise<any>;
+/** R4 hop activity: turn ended with no out. `body.pending_exit` mirrors whether
+ * the hop still awaits swarm_complete — the scheduler only records it. */
+export declare function swarmIdle(socketPath: string, body: {
+    workspace: string;
+    terminal_handle: string;
+    task_id: string;
+    pending_exit?: boolean;
+}, opId?: string): Promise<any>;
 export declare function consumeEvent(socket: Socket, eventSeq: number): Promise<void>;
-export declare function loopback(socketPath: string, text: string, rawText?: boolean): Promise<any>;
+export declare function loopback(socketPath: string, text: string, rawText?: boolean, opId?: string): Promise<any>;
+/** Versioned lifecycle evidence for the scheduler reducer. The frame travels as
+ * a raw-text loopback inbound: the daemon stores `text` verbatim and publishes
+ * it on the same event stream the report consumer reads. `raw_text` keeps the
+ * frame out of Markdown processing, and `opId` makes a socket-level retry
+ * return the stored receipt. */
+export declare function sendSwarmReport(socketPath: string, frame: string, opId?: string): Promise<any>;
 export declare function markConsumed(socketPath: string, messageId: string): Promise<any>;
-export declare function sendWithRetry(socketPath: string, target: SendTarget, text: string, attempts: number, rawText?: boolean): Promise<SendResult>;
+export declare function sendWithRetry(socketPath: string, target: SendTarget, text: string, attempts: number, rawText?: boolean, opId?: string): Promise<SendResult>;
 export declare function broadcast(socketPath: string, targets: SendTarget[], text: string, attempts: number, concurrency: number, rawText?: boolean): Promise<SendResult[]>;

package/dist/onlyne.js

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import { createConnection } from "node:net";
+import { SWARM_REPORT_PREFIX } from "./swarm.js";
 export function request(socketPath, req) {
     return new Promise((resolve, reject) => {
         const socket = createConnection(socketPath);
@@ -10,7 +11,11 @@ export function request(socketPath, req) {
         socket.on("data", (chunk) => { data += chunk; const idx = data.indexOf("\n"); if (idx >= 0) {
             socket.end();
             try {
-                resolve(JSON.parse(data.slice(0, idx)));
+                const response = JSON.parse(data.slice(0, idx));
+                if (response && response.ok === false)
+                    reject(new Error(response.error?.message ?? JSON.stringify(response.error ?? response)));
+                else
+                    resolve(response);
             }
             catch (e) {
                 reject(e);
@@ -23,8 +28,11 @@ export function subscribe(socketPath, onLine, onDisconnect, opts) {
     let buf = "";
     let closed = false;
     socket.setEncoding("utf8");
+    let resolveAck;
+    let rejectAck;
+    socket.ack = new Promise((resolve, reject) => { resolveAck = resolve; rejectAck = reject; });
     const disconnect = () => { if (closed)
-        return; closed = true; onDisconnect?.(); };
+        return; closed = true; rejectAck(new Error("onlyne subscription disconnected")); onDisconnect?.(); };
     socket.on("error", disconnect);
     socket.on("close", disconnect);
     socket.on("connect", () => { if (!socket.destroyed)
@@ -38,9 +46,16 @@ export function subscribe(socketPath, onLine, onDisconnect, opts) {
         if (!raw.trim())
             continue;
         try {
-            onLine(JSON.parse(raw));
+            const line = JSON.parse(raw);
+            if (line.id === "sub") {
+                if (line.ok)
+                    resolveAck(line);
+                else
+                    rejectAck(new Error(line.error?.message ?? "subscribe_events rejected"));
+            }
+            onLine(line);
         }
-        catch { /* ignore */ }
+        catch { /* malformed event lines stay outside the lifecycle protocol */ }
     } });
     return socket;
 }
@@ -109,11 +124,22 @@ export function stopProcess(child) { if (!child || child.killed)
     child.kill("SIGTERM");
 }
 catch { /* ignore */ } }
-export async function swarmReady(socketPath, workspace, terminalHandle) {
-    return request(socketPath, { id: `swarm-ready-${Date.now()}`, op: "swarm_ready", text: JSON.stringify({ workspace, terminal_handle: terminalHandle }) });
+export async function swarmReady(socketPath, workspace, terminalHandle, snapshot, opId) {
+    return request(socketPath, { id: `swarm-ready-${Date.now()}`, op: "swarm_ready", op_id: opId, text: JSON.stringify({ protocol: 2, workspace, terminal_handle: terminalHandle, snapshot }) });
+}
+export async function swarmRecycled(socketPath, taskId, terminalHandle, reason, opId) {
+    return request(socketPath, { id: `swarm-recycled-${Date.now()}`, op: "swarm_recycled", op_id: opId, text: JSON.stringify({ task_id: taskId, terminal_handle: terminalHandle, reason }) });
 }
-export async function swarmRecycled(socketPath, taskId, terminalHandle, reason) {
-    return request(socketPath, { id: `swarm-recycled-${Date.now()}`, op: "swarm_recycled", text: JSON.stringify({ task_id: taskId, terminal_handle: terminalHandle, reason }) });
+/** R4 hop activity: turn started. Fire-and-forget; the scheduler treats a
+ * missing task row as race residue and drops it silently. `body` comes from
+ * swarm.ts hopActivityBody (the shared, unit-tested decision). */
+export async function swarmBusy(socketPath, body, opId) {
+    return request(socketPath, { id: `swarm-busy-${Date.now()}`, op: "swarm_busy", op_id: opId, text: JSON.stringify(body) });
+}
+/** R4 hop activity: turn ended with no out. `body.pending_exit` mirrors whether
+ * the hop still awaits swarm_complete — the scheduler only records it. */
+export async function swarmIdle(socketPath, body, opId) {
+    return request(socketPath, { id: `swarm-idle-${Date.now()}`, op: "swarm_idle", op_id: opId, text: JSON.stringify(body) });
 }
 export async function consumeEvent(socket, eventSeq) {
     return new Promise((resolve) => { try {
@@ -123,17 +149,27 @@ export async function consumeEvent(socket, eventSeq) {
         resolve();
     } });
 }
-export async function loopback(socketPath, text, rawText = true) {
-    return request(socketPath, { id: `loopback-${Date.now()}`, op: "loopback", text, raw_text: rawText });
+export async function loopback(socketPath, text, rawText = true, opId) {
+    return request(socketPath, { id: `loopback-${Date.now()}`, op: "loopback", op_id: opId, text, raw_text: rawText });
+}
+/** Versioned lifecycle evidence for the scheduler reducer. The frame travels as
+ * a raw-text loopback inbound: the daemon stores `text` verbatim and publishes
+ * it on the same event stream the report consumer reads. `raw_text` keeps the
+ * frame out of Markdown processing, and `opId` makes a socket-level retry
+ * return the stored receipt. */
+export async function sendSwarmReport(socketPath, frame, opId) {
+    if (!frame.startsWith(SWARM_REPORT_PREFIX))
+        throw new Error("swarm report frame needs the ---swarm-report header");
+    return loopback(socketPath, frame, true, opId);
 }
 export async function markConsumed(socketPath, messageId) {
     return request(socketPath, { id: `consume-${Date.now()}`, op: "mark_io_consumed", message_id: messageId });
 }
-export async function sendWithRetry(socketPath, target, text, attempts, rawText = false) {
+export async function sendWithRetry(socketPath, target, text, attempts, rawText = false, opId) {
     let error = "unknown error";
     for (let i = 0; i < Math.max(1, attempts); i++) {
         try {
-            const res = await request(socketPath, { id: `send-${Date.now()}-${i}`, op: "send_message", channel_id: target.channelId, text, raw_text: rawText });
+            const res = await request(socketPath, { id: `send-${Date.now()}-${i}`, op: "send_message", op_id: opId, channel_id: target.channelId, text, raw_text: rawText });
             if (res.ok)
                 return { ...target, ok: true };
             error = res.error?.message ?? JSON.stringify(res.error ?? res);

package/dist/session.d.ts

@@ -0,0 +1,82 @@
+export declare const SWARM_STATE_ENTRY = "pi-onlyne:swarm-state";
+export declare const SWARM_PROTOCOL = 2;
+export type AgentState = "booting" | "ready" | "running" | "idle" | "gone";
+export type DeliveryState = "none" | "pending" | "retrying" | "accepted" | "exhausted";
+export type ResourceState = "detached" | "attached" | "closing" | "closed";
+export type Lifecycle = "created" | "working" | "idle" | "exited";
+export type RecoveryState = "idle_waiting" | "idle_fault" | "draining";
+export interface SwarmSnapshot {
+    protocol: 2;
+    task_id: string;
+    generation: number;
+    seq: number;
+    agent: AgentState;
+    delivery: DeliveryState;
+    resource: ResourceState;
+    lifecycle: Lifecycle;
+    recovery: RecoveryState;
+    pending_intents: string[];
+    at: string;
+}
+export interface SwarmIntent {
+    op_id: string;
+    kind: string;
+    payload: unknown;
+    attempts: number;
+    status: "pending" | "retrying" | "accepted" | "exhausted";
+    receipt?: unknown;
+    last_error?: string;
+}
+export interface SwarmStateData {
+    protocol: 2;
+    task_id: string;
+    generation: number;
+    seq: number;
+    snapshot: SwarmSnapshot;
+    intents: SwarmIntent[];
+}
+export interface SessionEntry {
+    type?: string;
+    customType?: string;
+    data?: unknown;
+}
+export interface StateContext {
+    appendEntry: (customType: string, data?: unknown) => void;
+    sessionManager?: {
+        getEntries(): readonly SessionEntry[];
+    };
+}
+export declare function restoreSwarmState(ctx: StateContext, taskId: string): SwarmStateData | undefined;
+export declare class SwarmSessionState {
+    readonly taskId: string;
+    private append;
+    private _generation;
+    private _seq;
+    private _snapshot;
+    private _intents;
+    private timers;
+    private heartbeatTimer?;
+    constructor(ctx: StateContext, taskId: string, restored?: SwarmStateData);
+    startSession(): SwarmSnapshot;
+    get generation(): number;
+    get seq(): number;
+    get intents(): SwarmIntent[];
+    snapshot(): SwarmSnapshot;
+    private makeSnapshot;
+    private persist;
+    transition(patch: Partial<SwarmSnapshot>, kind?: string): SwarmSnapshot;
+    heartbeat(): SwarmSnapshot;
+    recordIntent(kind: string, payload: unknown, opId: string): SwarmIntent;
+    receipt(opId: string, receipt: unknown): boolean;
+    retry(opId: string, send: (intent: SwarmIntent) => Promise<unknown>, maxAttempts?: number): Promise<SwarmIntent>;
+    startHeartbeat(intervalMs?: number, run?: () => void): void;
+    stopHeartbeat(): void;
+    shutdown(): void;
+}
+export declare function compareSwarmVersion(a: {
+    generation: number;
+    seq: number;
+}, b: {
+    generation: number;
+    seq: number;
+}): "stale" | "duplicate" | "new";

package/dist/session.js

@@ -0,0 +1,91 @@
+export const SWARM_STATE_ENTRY = "pi-onlyne:swarm-state";
+export const SWARM_PROTOCOL = 2;
+function isObject(v) { return !!v && typeof v === "object" && !Array.isArray(v); }
+function validState(v) {
+    if (!isObject(v) || v.protocol !== 2 || typeof v.task_id !== "string" || typeof v.generation !== "number" || typeof v.seq !== "number" || !isObject(v.snapshot) || !Array.isArray(v.intents))
+        return false;
+    return v.snapshot.protocol === 2 && v.snapshot.task_id === v.task_id && v.snapshot.generation === v.generation && typeof v.snapshot.seq === "number";
+}
+export function restoreSwarmState(ctx, taskId) {
+    let found;
+    for (const entry of ctx.sessionManager?.getEntries() ?? []) {
+        if (entry.type !== "custom" || entry.customType !== SWARM_STATE_ENTRY)
+            continue;
+        if (!validState(entry.data))
+            throw new Error("malformed swarm v2 state entry");
+        if (entry.data.task_id !== taskId)
+            continue;
+        if (!found || entry.data.seq > found.seq || entry.data.generation > found.generation)
+            found = entry.data;
+    }
+    return found;
+}
+export class SwarmSessionState {
+    taskId;
+    append;
+    _generation = 0;
+    _seq = 0;
+    _snapshot;
+    _intents = new Map();
+    timers = new Set();
+    heartbeatTimer;
+    constructor(ctx, taskId, restored) {
+        this.taskId = taskId;
+        this.append = ctx.appendEntry;
+        if (restored) {
+            this._generation = restored.generation;
+            this._seq = restored.seq;
+            this._snapshot = structuredClone(restored.snapshot);
+            for (const i of restored.intents)
+                this._intents.set(i.op_id, structuredClone(i));
+        }
+        else
+            this._snapshot = this.makeSnapshot();
+    }
+    startSession() { this._generation++; return this.persist("session_start", { generation: this._generation }); }
+    get generation() { return this._generation; }
+    get seq() { return this._seq; }
+    get intents() { return [...this._intents.values()].map((x) => structuredClone(x)); }
+    snapshot() { return structuredClone(this._snapshot); }
+    makeSnapshot() { return { protocol: 2, task_id: this.taskId, generation: this._generation, seq: this._seq, agent: "booting", delivery: "none", resource: "detached", lifecycle: "created", recovery: "idle_waiting", pending_intents: [...this._intents.keys()], at: new Date().toISOString() }; }
+    persist(kind, patch) { this._seq++; this._snapshot = { ...this._snapshot, ...patch, protocol: 2, task_id: this.taskId, generation: this._generation, seq: this._seq, pending_intents: [...this._intents.values()].filter((i) => i.status !== "accepted").map((i) => i.op_id), at: new Date().toISOString() }; this.append(SWARM_STATE_ENTRY, { protocol: 2, task_id: this.taskId, generation: this._generation, seq: this._seq, snapshot: this._snapshot, intents: this.intents, kind }); return this.snapshot(); }
+    transition(patch, kind = "snapshot") { return this.persist(kind, patch); }
+    heartbeat() { return this.persist("swarm_heartbeat"); }
+    recordIntent(kind, payload, opId) { if (this._intents.has(opId))
+        return structuredClone(this._intents.get(opId)); const intent = { op_id: opId, kind, payload, attempts: 0, status: "pending" }; this._intents.set(opId, intent); this.persist(kind, { delivery: "pending" }); return structuredClone(intent); }
+    receipt(opId, receipt) { const i = this._intents.get(opId); if (!i)
+        return false; i.status = "accepted"; i.receipt = receipt; this.persist("intent_receipt", { delivery: "accepted", lifecycle: i.kind === "swarm_complete" ? "exited" : this._snapshot.lifecycle }); return true; }
+    async retry(opId, send, maxAttempts = 3) { const i = this._intents.get(opId); if (!i)
+        throw new Error(`unknown intent ${opId}`); for (let n = i.attempts; n < maxAttempts && i.status !== "accepted"; n++) {
+        i.attempts++;
+        i.status = "retrying";
+        this.persist("intent_attempt", { delivery: "retrying" });
+        try {
+            const receipt = await send(structuredClone(i));
+            this.receipt(opId, receipt);
+        }
+        catch (e) {
+            i.last_error = e instanceof Error ? e.message : String(e);
+            if (i.attempts >= maxAttempts) {
+                i.status = "exhausted";
+                this.persist("intent_exhausted", { delivery: "exhausted", recovery: "idle_fault" });
+            }
+            else {
+                const delay = 1000 * 2 ** (i.attempts - 1);
+                await new Promise((resolve) => { const t = setTimeout(() => { this.timers.delete(t); resolve(); }, delay); this.timers.add(t); });
+            }
+        }
+    } return structuredClone(i); }
+    startHeartbeat(intervalMs = 10_000, run = () => this.heartbeat()) {
+        this.stopHeartbeat();
+        this.heartbeatTimer = setInterval(() => run(), Math.max(1, intervalMs));
+        this.heartbeatTimer.unref?.();
+    }
+    stopHeartbeat() { if (this.heartbeatTimer)
+        clearInterval(this.heartbeatTimer); this.heartbeatTimer = undefined; }
+    shutdown() { this.stopHeartbeat(); for (const t of this.timers)
+        clearTimeout(t); this.timers.clear(); }
+}
+export function compareSwarmVersion(a, b) { if (a.generation < b.generation || (a.generation === b.generation && a.seq < b.seq))
+    return "stale"; if (a.generation === b.generation && a.seq === b.seq)
+    return "duplicate"; return "new"; }

package/dist/swarm-slot.d.ts

@@ -1,12 +1,6 @@
 export type SwarmHandleResult = "claimed" | "yielded" | "not-swarm";
 export interface SwarmPi {
-    sendMessage: (message: {
-        customType: string;
-        content: string;
-        display: boolean;
-        details?: unknown;
-    }, opts: {
-        triggerTurn: true;
+    sendUserMessage: (content: string, opts: {
         deliverAs: "followUp";
     }) => void;
 }

package/dist/swarm-slot.js

@@ -15,32 +15,35 @@ export class SwarmSlot {
         const parsed = parseSwarmHeader(text);
         if (!parsed)
             return "not-swarm";
-        const { header, payload } = parsed;
+        const { header, delivery, payload } = parsed;
+        // A scheduler-created terminal carries ONLYNE_SWARM_TASK. Its task id
+        // is a hard delivery binding: history replay or a stale live event for
+        // another task must never claim this session. Without this guard a
+        // freshly spawned pane can run an expired workspace-local payload
+        // before its assigned FIFO write reaches history.
+        if (preferredTaskId && header.task_id !== preferredTaskId)
+            return "not-swarm";
+        // Only the scheduler's second delivery is claimable. A worker's raw
+        // swarm_send relay and every out wire omit this structured field, so
+        // history catchup cannot claim either one as an executable task.
+        if (delivery !== "scheduler")
+            return "not-swarm";
         if (!this.taskId) {
             this.taskId = header.task_id;
             this.from = header.from;
             this.transfer = header.transfer_send_to;
             this.attempt = header.attempt;
             this.sentChildIds = [];
-            // Cold start needs triggerTurn: followUp alone only queues behind an
-            // active turn, and a fresh session has none. sendMessage with
-            // triggerTurn starts the model turn immediately.
-            pi.sendMessage({ customType: "onlyne-swarm-task", content: resolveSwarmPrompt(workspaceRoot ?? process.cwd(), header, payload) ?? payload, display: true }, { triggerTurn: true, deliverAs: "followUp" });
+            // A scheduler delivery is a real user task. `sendUserMessage` always
+            // triggers a turn, including during a fresh Pi session; custom
+            // `sendMessage` follow-ups can remain queued until a later event while
+            // the session_start hook is still settling.
+            pi.sendUserMessage(resolveSwarmPrompt(workspaceRoot ?? process.cwd(), header, payload) ?? payload, { deliverAs: "followUp" });
             return "claimed";
         }
-        // Env-task preemption: the scheduler injected ONLYNE_SWARM_TASK for
-        // this terminal. If the slot holds a stale claim (history catchup
-        // grabbed an already-done task) and the env task arrives, yield the
-        // slot silently — the stale claim never did work, so nothing is lost.
-        if (preferredTaskId && header.task_id === preferredTaskId && this.taskId !== preferredTaskId) {
-            this.taskId = header.task_id;
-            this.from = header.from;
-            this.transfer = header.transfer_send_to;
-            this.attempt = header.attempt;
-            this.sentChildIds = [];
-            pi.sendMessage({ customType: "onlyne-swarm-task", content: resolveSwarmPrompt(workspaceRoot ?? process.cwd(), header, payload) ?? payload, display: true }, { triggerTurn: true, deliverAs: "followUp" });
-            return "yielded";
-        }
+        // A claimed session normally receives no further delivery. The
+        // preferred-id guard above already protected an env-bound pane, so this
+        // branch only applies to manual ready-pool sessions with no env task.
         return "not-swarm";
     }
     task() {

package/dist/swarm.d.ts

@@ -5,10 +5,37 @@ export interface SwarmHeader {
     transfer_send_to: string;
     attempt: number;
 }
+/** `scheduler` identifies the scheduler's second delivery. Raw relay and out
+ * wires omit it, so a cold-start history scan cannot claim them. */
 export interface SwarmMessage {
     header: SwarmHeader;
+    delivery: string;
     payload: string;
 }
+/** Frame header for versioned lifecycle evidence consumed by the scheduler
+ * reducer. A distinct prefix from `---swarm` / `---swarm-ctl`, so a report
+ * never enters the task delivery paths on either side. */
+export declare const SWARM_REPORT_PREFIX = "---swarm-report\n";
+/** Report kinds accepted by the scheduler's report parser. */
+export declare const SWARM_REPORT_KINDS: readonly ["heartbeat", "ready", "turn_started", "snapshot", "complete", "fault"];
+export type SwarmReportKind = (typeof SWARM_REPORT_KINDS)[number];
+/** Whether a value carries scheduler task identity: a UUID. The session's own
+ * composite keys (`session:<handle>`) name no scheduler row, so a report built
+ * from one would land as unknown-session noise on that side. */
+export declare function isSwarmTaskId(value: string): boolean;
+/** Whether a loopback text is a lifecycle report frame. Reports live in the
+ * same loopback history and event stream as task wires, so every task scan
+ * skips them ahead of its malformed-header check. */
+export declare function isSwarmReportFrame(text: string): boolean;
+/** Render one lifecycle report frame:
+ * `---swarm-report\nprotocol: 2\nop: <kind>\ntask_id: <uuid>\ngeneration: <n>\nseq: <n>\n---\n`
+ * Field order, labels, values, and the closing delimiter match the scheduler
+ * parser byte for byte; its `fields()` rejects missing, unknown, and duplicate
+ * keys, so the frame carries exactly those five fields. The trailing `---\n`
+ * closes the header region the parser reads.
+ * Invalid input fails here with a diagnostic: a synthetic task id and an
+ * out-of-range counter never reach the wire. */
+export declare function renderSwarmReport(kind: SwarmReportKind, taskId: string, generation: number, seq: number): string;
 /** Parse a `---swarm` body header. Returns null for non-swarm messages. */
 export declare function parseSwarmHeader(text: string): SwarmMessage | null;
 /** Downlink control wire (scheduler -> session). Header-only marker the
@@ -38,5 +65,32 @@ export declare function readSwarmModel(onlyneDir: string): {
 export declare function treePathForWorkspace(workspaceRoot: string): string;
 /** Terminal handle for swarm_ready correlation (injected by the scheduler). */
 export declare function terminalHandle(): string;
+/** Choose a scheduler-delivered history wire for a fresh swarm session.
+ *
+ * A terminal with ONLYNE_SWARM_TASK has one assigned task. History may still
+ * contain arbitrary old unclosed wires for the same workspace, so it may
+ * replay only that exact id. If the assigned delivery has not reached history
+ * yet, return undefined and let the live inbound event deliver it. Sessions
+ * without an env assignment (manual ready pool) retain newest-unclosed
+ * fallback behavior. This is pure so the replay race is regression-tested.
+ */
+export declare function selectHistoryDelivery(expectedTaskId: string | undefined, inbounds: readonly string[], outs: ReadonlySet<string>): string | undefined;
 /** Task id injected by the scheduler via env (fallback before swarm_ready handshake). */
 export declare function envTaskId(): string;
+/** R4 hop-activity decision, pure so the guard and the pending_exit bit are
+ * unit-tested without a live daemon. Returns the daemon op body, or null when
+ * nothing should be reported: busy/idle only make sense for a swarm session
+ * that has a workspace and a live claimed task. An idle report always carries
+ * pending_exit=true — the plugin never sends idle after swarm_complete cleared
+ * the task (that path writes no event; the scheduler owns the recycle). */
+export declare function hopActivityBody(kind: "busy" | "idle", opts: {
+    swarm: boolean;
+    workspaceRoot?: string;
+    terminal: string;
+    taskId?: string;
+}): {
+    workspace: string;
+    terminal_handle: string;
+    task_id: string;
+    pending_exit?: boolean;
+} | null;