opencode-superagent 0.1.0 → 0.2.1

package/dist/src/state.d.ts

@@ -1,27 +1,8 @@
 import type { Plugin } from "@opencode/plugin/effect";
 import type { Session } from "@opencode/schema/session";
 import { Effect, type Schema } from "effect";
-export type WorkerState = "running" | "idle" | "failed" | "done" | "aborted";
-export interface WorkerRecord {
-    readonly sessionID: string;
-    readonly title?: string;
-    /**
-     * Primary thread this worker was dispatched for. Legacy records decode to
-     * `""` and `hydrate` backfills it from `thread.workers`, so every live record
-     * carries a forward link to its thread without losing the multi-thread
-     * `threads` list.
-     */
-    threadID: string;
-    /** Trigger that authorized the dispatch, when the record knows it. */
-    triggerID?: string;
-    readonly threads: Array<string>;
-    state: WorkerState;
-    readonly createdAt: number;
-    /** Last persisted write. Refreshed by `saveWorker`, so an aborted record keeps a traceable timestamp. */
-    updatedAt?: number;
-    lastReport?: string;
-    directory?: string;
-}
+import { type WorkerRecord } from "./worker-state.js";
+export type { WorkerRecord, WorkerState } from "./worker-state.js";
 export interface ThreadRecord {
     readonly threadID: string;
     readonly workers: Array<string>;
@@ -99,6 +80,8 @@ export declare const threadKey: (threadID: string) => string;
 export declare const triggerKey: (id: string) => string;
 /** Brands are compile-time only, so a validated session id string converts freely. */
 export declare const toSessionID: (id: string) => Session.ID;
+/** A Session is running while `time.busy` is newer than the last completed execution's `time.idle`. */
+export declare function isRunning(info: Session.Info): boolean;
 export declare function decodeWorker(value: Schema.Json | undefined): WorkerRecord | undefined;
 export declare function decodeThread(value: Schema.Json | undefined): ThreadRecord | undefined;
 export declare function decodeTrigger(value: Schema.Json | undefined): TriggerRecord | undefined;

package/dist/src/state.js

@@ -1,4 +1,8 @@
-import { Effect } from "effect";
+import { DateTime, Effect } from "effect";
+import { buildReport, lastAssistantText, reportSummary, saveReport } from "./report.js";
+import { closeTicketsForWorker } from "./ticket.js";
+import { closeOutcomeForWorkerState } from "./ticket-state.js";
+import { WORKER_STATES, workers } from "./worker-state.js";
 const ROUTES = ["router", "worker"];
 /** Host context for fire-and-forget KV writes from synchronous interception points. Set during hydrate. */
 let persistHost;
@@ -104,7 +108,7 @@ export function upsertDirectTrigger(input, sessionID) {
 export const store = {
     routerID: undefined,
     routerBusy: false,
-    workers: new Map(),
+    workers,
     threads: new Map(),
     pending: new PendingQueue(),
     triggers: new Map(),
@@ -120,7 +124,14 @@ export const threadKey = (threadID) => `${THREAD_PREFIX}${threadID}`;
 export const triggerKey = (id) => `${TRIGGER_PREFIX}${id}`;
 /** Brands are compile-time only, so a validated session id string converts freely. */
 export const toSessionID = (id) => id;
-const STATES = ["running", "idle", "failed", "done", "aborted"];
+/** A Session is running while `time.busy` is newer than the last completed execution's `time.idle`. */
+export function isRunning(info) {
+    const busy = info.time.busy;
+    if (busy === undefined)
+        return false;
+    const idle = info.time.idle;
+    return idle === undefined || DateTime.toEpochMillis(busy) > DateTime.toEpochMillis(idle);
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }
@@ -144,7 +155,7 @@ export function decodeWorker(value) {
         return undefined;
     if (typeof value["sessionID"] !== "string")
         return undefined;
-    if (typeof value["state"] !== "string" || !STATES.includes(value["state"]))
+    if (typeof value["state"] !== "string" || !WORKER_STATES.includes(value["state"]))
         return undefined;
     const threads = stringArray(value["threads"]);
     if (threads === undefined)
@@ -260,6 +271,44 @@ const removeWorker = Effect.fn("superagent.removeWorker")(function* (ctx, sessio
         .remove(workerKey(sessionID))
         .pipe(Effect.catch((cause) => Effect.logWarning("superagent failed to remove worker", { cause })));
 });
+/**
+ * Reconcile one hydrated `running` record with the live session. A session
+ * that is still executing keeps `running`; one that finished while the plugin
+ * was down is backfilled the same way the watcher would have handled it:
+ * capture the last assistant report, persist the terminal/interrupted state,
+ * and close its ticket for `done`/`failed`.
+ */
+const reconcileRunningWorker = Effect.fn("superagent.reconcileRunningWorker")(function* (ctx, record, info) {
+    if (isRunning(info))
+        return;
+    const state = info.outcome === "succeeded" ? "done" : info.outcome === "failed" ? "failed" : "idle";
+    record.state = state;
+    const sessions = ctx.session;
+    const messages = typeof sessions.context === "function"
+        ? yield* sessions
+            .context({ sessionID: toSessionID(record.sessionID) })
+            .pipe(Effect.catch(() => Effect.succeed([])))
+        : [];
+    const report = lastAssistantText(messages);
+    if (report !== undefined) {
+        const captured = buildReport(record.sessionID, report);
+        yield* saveReport(ctx, captured);
+        record.lastReport = reportSummary(captured);
+    }
+    yield* saveWorker(ctx, record);
+    const outcome = closeOutcomeForWorkerState(state);
+    if (outcome !== undefined) {
+        yield* closeTicketsForWorker(ctx, {
+            sessionID: record.sessionID,
+            outcome,
+            summary: record.lastReport ?? report ?? `${outcome} (worker ${record.sessionID})`,
+        }).pipe(Effect.catch((cause) => Effect.logWarning("superagent failed to close ticket for rehydrated worker", {
+            sessionID: record.sessionID,
+            cause,
+        })));
+    }
+    yield* Effect.logInfo("superagent rehydrated ended worker", { sessionID: record.sessionID, state });
+});
 /**
  * Load KV state into the in-memory maps. Storage is the unique source of
  * truth; every loaded session is validated with `session.get` and stale
@@ -296,6 +345,8 @@ export const hydrate = Effect.fn("superagent.hydrate")(function* (ctx) {
                 continue;
             }
             store.workers.set(record.sessionID, record);
+            if (record.state === "running")
+                yield* reconcileRunningWorker(ctx, record, info);
         }
         after = page.next;
     } while (after !== undefined);

package/dist/src/ticket-state.d.ts

@@ -0,0 +1,97 @@
+import type { WorkerState } from "./worker-state.js";
+/**
+ * Pure ticket domain model: records, the state machine, and the selectors
+ * shared by the ticket store, the dispatcher and the worker lifecycle.
+ *
+ * Nothing here touches the KV store, Effect or the worker registry, so this
+ * module can be imported from any layer without recreating the state ↔ ticket
+ * import cycle. `ticket.ts` keeps the effectful store and re-exports these
+ * names, so its public API is unchanged.
+ */
+export type TicketState = "open" | "in_progress" | "blocked" | "done" | "failed" | "cancelled" | "superseded";
+export type TicketPriority = "p0" | "p1" | "p2";
+export type TicketCloseOutcome = "done" | "failed" | "cancelled";
+export interface TicketRequester {
+    readonly source: string;
+    readonly threadID: string;
+    readonly author?: string;
+}
+/** Which trigger authorized the ticket: the id plus a short quote of what the user said. */
+export interface TicketAuthorization {
+    readonly triggerID: string;
+    readonly quote: string;
+    readonly at: number;
+}
+export interface TicketAttempt {
+    readonly at: number;
+    readonly sessionID?: string;
+    readonly note?: string;
+}
+export interface TicketHistoryEntry {
+    readonly at: number;
+    readonly kind: "created" | "state" | "note" | "dispatch" | "closed";
+    readonly from?: TicketState;
+    readonly to?: TicketState;
+    readonly note?: string;
+}
+export interface Ticket {
+    readonly id: string;
+    state: TicketState;
+    readonly title: string;
+    readonly objective: string;
+    readonly acceptance: ReadonlyArray<string>;
+    readonly requester: TicketRequester;
+    readonly authorization: TicketAuthorization;
+    readonly threadID: string;
+    workerSessionID?: string;
+    readonly attempts: Array<TicketAttempt>;
+    readonly priority: TicketPriority;
+    directory?: string;
+    readonly dedupeKey: string;
+    readonly parentTicketID?: string;
+    readonly tags: Array<string>;
+    readonly createdAt: number;
+    updatedAt: number;
+    closedAt?: number;
+    closeReason?: string;
+    readonly history: Array<TicketHistoryEntry>;
+}
+export declare const PRIORITIES: ReadonlyArray<TicketPriority>;
+export declare const TICKET_STATES: ReadonlyArray<TicketState>;
+/** A ticket can be dispatched while it is one of these. */
+export declare const ACTIVE_STATES: ReadonlyArray<TicketState>;
+export declare function isTerminalState(state: TicketState): boolean;
+export declare function allowedTransitions(state: TicketState): ReadonlyArray<TicketState>;
+/** Same-state moves are no-ops, not transitions. */
+export declare function canTransition(from: TicketState, to: TicketState): boolean;
+/** Human-readable reason a move is illegal, or `undefined` when it is allowed. */
+export declare function transitionError(from: TicketState, to: TicketState): string | undefined;
+/** Minimal shape a worker-bound ticket needs, so the selector stays pure and generic. */
+export interface WorkerBoundTicket {
+    readonly workerSessionID?: string;
+    readonly state: TicketState;
+}
+/**
+ * The `in_progress` ticket attached to a worker session, if any. Shared by the
+ * dispatch link and worker-end closing so both sides agree on "active ticket
+ * for this worker"; insertion order decides ties, as before.
+ */
+export declare function findActiveTicketForWorker<T extends WorkerBoundTicket>(candidates: Iterable<T>, sessionID: string): T | undefined;
+/**
+ * Ticket outcome for a worker that just ended, or `undefined` when the worker
+ * end closes nothing. `idle`/`aborted`/`running` leave the ticket for the abort
+ * path or a deliberate re-dispatch.
+ */
+export declare function closeOutcomeForWorkerState(state: WorkerState): "done" | "failed" | undefined;
+/**
+ * Reason recorded when a worker end closes its ticket: an explicit summary
+ * wins, then the caller's note, then a generated `done (worker <id>)` line.
+ * The store still compacts it to `SUMMARY_MAX` before persisting, exactly as
+ * before this helper existed.
+ */
+export declare function workerCloseSummary(input: {
+    readonly sessionID: string;
+    readonly outcome: "done" | "failed";
+    readonly summary?: string | undefined;
+    readonly note?: string | undefined;
+}): string;

package/dist/src/ticket-state.js

@@ -0,0 +1,70 @@
+export const PRIORITIES = ["p0", "p1", "p2"];
+export const TICKET_STATES = [
+    "open",
+    "in_progress",
+    "blocked",
+    "done",
+    "failed",
+    "cancelled",
+    "superseded",
+];
+/** A ticket can be dispatched while it is one of these. */
+export const ACTIVE_STATES = ["open", "in_progress"];
+const TRANSITIONS = {
+    // A ticket can close from any active state: `done`/`failed` also cover work
+    // finished outside the worker (or a dispatch that never started).
+    open: ["in_progress", "blocked", "done", "failed", "cancelled", "superseded"],
+    in_progress: ["blocked", "done", "failed", "cancelled", "superseded"],
+    blocked: ["in_progress", "done", "failed", "cancelled", "superseded"],
+    done: [],
+    failed: [],
+    cancelled: [],
+    superseded: [],
+};
+export function isTerminalState(state) {
+    return TRANSITIONS[state].length === 0;
+}
+export function allowedTransitions(state) {
+    return TRANSITIONS[state];
+}
+/** Same-state moves are no-ops, not transitions. */
+export function canTransition(from, to) {
+    return from === to || TRANSITIONS[from].includes(to);
+}
+/** Human-readable reason a move is illegal, or `undefined` when it is allowed. */
+export function transitionError(from, to) {
+    if (canTransition(from, to))
+        return undefined;
+    if (isTerminalState(from))
+        return `ticket is already closed (${from}); cannot move to ${to}`;
+    return `illegal transition ${from} -> ${to}; allowed: ${TRANSITIONS[from].join(", ")}`;
+}
+/**
+ * The `in_progress` ticket attached to a worker session, if any. Shared by the
+ * dispatch link and worker-end closing so both sides agree on "active ticket
+ * for this worker"; insertion order decides ties, as before.
+ */
+export function findActiveTicketForWorker(candidates, sessionID) {
+    for (const ticket of candidates) {
+        if (ticket.workerSessionID === sessionID && ticket.state === "in_progress")
+            return ticket;
+    }
+    return undefined;
+}
+/**
+ * Ticket outcome for a worker that just ended, or `undefined` when the worker
+ * end closes nothing. `idle`/`aborted`/`running` leave the ticket for the abort
+ * path or a deliberate re-dispatch.
+ */
+export function closeOutcomeForWorkerState(state) {
+    return state === "done" || state === "failed" ? state : undefined;
+}
+/**
+ * Reason recorded when a worker end closes its ticket: an explicit summary
+ * wins, then the caller's note, then a generated `done (worker <id>)` line.
+ * The store still compacts it to `SUMMARY_MAX` before persisting, exactly as
+ * before this helper existed.
+ */
+export function workerCloseSummary(input) {
+    return input.summary ?? input.note ?? `${input.outcome} (worker ${input.sessionID})`;
+}

package/dist/src/ticket.d.ts

@@ -1,7 +1,24 @@
 import type { Plugin } from "@opencode/plugin/effect";
 import { Tool } from "@opencode/schema/tool";
 import { Effect, type Schema } from "effect";
-import { type TriggerInput } from "./state.js";
+import { type Ticket, type TicketAuthorization, type TicketCloseOutcome, type TicketPriority, type TicketState } from "./ticket-state.js";
+export type { Ticket, TicketAttempt, TicketAuthorization, TicketCloseOutcome, TicketHistoryEntry, TicketPriority, TicketRequester, TicketState, } from "./ticket-state.js";
+export { ACTIVE_STATES, allowedTransitions, canTransition, isTerminalState, TICKET_STATES, transitionError, } from "./ticket-state.js";
+export { isWorkerTerminal, TERMINAL_WORKER_STATES } from "./worker-state.js";
+/**
+ * Structural copy of the queued trigger input. The ticket layer must not import
+ * `state.ts` (that is the cycle this module just broke), and the shape is all
+ * `noteRouterTrigger` needs.
+ */
+export interface TicketTriggerNoteInput {
+    readonly id?: string;
+    readonly source: string;
+    readonly threadID: string;
+    readonly author?: string;
+    readonly text: string;
+    readonly title?: string;
+    readonly createdAt?: number;
+}
 /**
  * Ticket (work order) store for the Super-agent P0.
  *
@@ -23,54 +40,6 @@ import { type TriggerInput } from "./state.js";
  *
  * `done`, `failed`, `cancelled` and `superseded` are terminal.
  */
-export type TicketState = "open" | "in_progress" | "blocked" | "done" | "failed" | "cancelled" | "superseded";
-export type TicketPriority = "p0" | "p1" | "p2";
-export type TicketCloseOutcome = "done" | "failed" | "cancelled";
-export interface TicketRequester {
-    readonly source: string;
-    readonly threadID: string;
-    readonly author?: string;
-}
-/** Which trigger authorized the ticket: the id plus a short quote of what the user said. */
-export interface TicketAuthorization {
-    readonly triggerID: string;
-    readonly quote: string;
-    readonly at: number;
-}
-export interface TicketAttempt {
-    readonly at: number;
-    readonly sessionID?: string;
-    readonly note?: string;
-}
-export interface TicketHistoryEntry {
-    readonly at: number;
-    readonly kind: "created" | "state" | "note" | "dispatch" | "closed";
-    readonly from?: TicketState;
-    readonly to?: TicketState;
-    readonly note?: string;
-}
-export interface Ticket {
-    readonly id: string;
-    state: TicketState;
-    readonly title: string;
-    readonly objective: string;
-    readonly acceptance: ReadonlyArray<string>;
-    readonly requester: TicketRequester;
-    readonly authorization: TicketAuthorization;
-    readonly threadID: string;
-    workerSessionID?: string;
-    readonly attempts: Array<TicketAttempt>;
-    readonly priority: TicketPriority;
-    directory?: string;
-    readonly dedupeKey: string;
-    readonly parentTicketID?: string;
-    readonly tags: Array<string>;
-    readonly createdAt: number;
-    updatedAt: number;
-    closedAt?: number;
-    closeReason?: string;
-    readonly history: Array<TicketHistoryEntry>;
-}
 export declare const TICKET_PREFIX = "ticket:";
 export declare const TICKET_STATUS_PREFIX = "ticketidx:status:";
 export declare const TICKET_THREAD_PREFIX = "ticketidx:thread:";
@@ -87,15 +56,6 @@ export declare const INDEX_LIMIT = 200;
 export declare const MEMORY_LIMIT = 500;
 export declare const LIST_DEFAULT = 20;
 export declare const LIST_MAX = 100;
-export declare const TICKET_STATES: ReadonlyArray<TicketState>;
-/** A ticket can be dispatched while it is one of these. */
-export declare const ACTIVE_STATES: ReadonlyArray<TicketState>;
-export declare function isTerminalState(state: TicketState): boolean;
-export declare function allowedTransitions(state: TicketState): ReadonlyArray<TicketState>;
-/** Same-state moves are no-ops, not transitions. */
-export declare function canTransition(from: TicketState, to: TicketState): boolean;
-/** Human-readable reason a move is illegal, or `undefined` when it is allowed. */
-export declare function transitionError(from: TicketState, to: TicketState): string | undefined;
 /** Lowercased, whitespace-collapsed objective, so wording drift does not defeat dedupe. */
 export declare function normalizeObjective(text: string): string;
 export declare function dedupeKeyFor(input: {
@@ -122,7 +82,7 @@ export interface RouterTriggerNote {
     readonly text: string;
     readonly at: number;
 }
-export declare function noteRouterTrigger(trigger: TriggerInput): void;
+export declare function noteRouterTrigger(trigger: TicketTriggerNoteInput): void;
 export declare function currentTrigger(): RouterTriggerNote | undefined;
 /** Reset memory (hydrate and tests): the map and its thread index are rebuilt together. */
 export declare function resetTickets(): void;
@@ -209,7 +169,7 @@ export declare function listTickets(input?: ListTicketsInput): Array<Ticket>;
  * Gate every dispatch must pass: a dispatch always names a ticket, and that
  * ticket must be workable right now. The rules are enforced here (not in the
  * prompt) so a Router cannot dispatch without a ticket, onto a closed ticket,
- * across threads, or onto a ticket that already has a running worker.
+ * across threads, or onto a ticket that already has a live (non-terminal) worker.
  */
 export declare const requireDispatchTicket: (ticketID: string | undefined, threadID: string | undefined) => Effect.Effect<Ticket, Tool.Error, never>;
 export interface LinkTicketInput {

package/dist/src/ticket.js

@@ -2,8 +2,32 @@ import { Tool } from "@opencode/schema/tool";
 import { Effect } from "effect";
 import { createHash } from "node:crypto";
 import { normalizeDirectory } from "./dirs.js";
-import { store } from "./state.js";
+import { ACTIVE_STATES, findActiveTicketForWorker, isTerminalState, PRIORITIES, TICKET_STATES, transitionError, workerCloseSummary, } from "./ticket-state.js";
+import { isWorkerTerminal, workers } from "./worker-state.js";
 import { displayWidth, wrapText } from "./tools.js";
+export { ACTIVE_STATES, allowedTransitions, canTransition, isTerminalState, TICKET_STATES, transitionError, } from "./ticket-state.js";
+export { isWorkerTerminal, TERMINAL_WORKER_STATES } from "./worker-state.js";
+/**
+ * Ticket (work order) store for the Super-agent P0.
+ *
+ * A ticket is the durable statement of "what the user asked for and how we
+ * will know it is done". The Router creates one before dispatching work; the
+ * dispatch records the worker session on it and the worker's terminal state
+ * closes it. Records live in KV under `ticket:<id>`; the `ticketidx:*` keys
+ * are derived accelerators, so hydration always rebuilds them from the
+ * record prefix (a lost index never loses a ticket).
+ *
+ * State machine:
+ *
+ *   open ─┬─▶ in_progress ─┬─▶ done
+ *         │                ├─▶ failed
+ *         │                ├─▶ blocked ──▶ in_progress
+ *         ├─▶ blocked      └─▶ cancelled
+ *         ├─▶ cancelled
+ *         └─▶ superseded
+ *
+ * `done`, `failed`, `cancelled` and `superseded` are terminal.
+ */
 export const TICKET_PREFIX = "ticket:";
 export const TICKET_STATUS_PREFIX = "ticketidx:status:";
 export const TICKET_THREAD_PREFIX = "ticketidx:thread:";
@@ -20,47 +44,6 @@ export const INDEX_LIMIT = 200;
 export const MEMORY_LIMIT = 500;
 export const LIST_DEFAULT = 20;
 export const LIST_MAX = 100;
-const PRIORITIES = ["p0", "p1", "p2"];
-export const TICKET_STATES = [
-    "open",
-    "in_progress",
-    "blocked",
-    "done",
-    "failed",
-    "cancelled",
-    "superseded",
-];
-/** A ticket can be dispatched while it is one of these. */
-export const ACTIVE_STATES = ["open", "in_progress"];
-const TRANSITIONS = {
-    // A ticket can close from any active state: `done`/`failed` also cover work
-    // finished outside the worker (or a dispatch that never started).
-    open: ["in_progress", "blocked", "done", "failed", "cancelled", "superseded"],
-    in_progress: ["blocked", "done", "failed", "cancelled", "superseded"],
-    blocked: ["in_progress", "done", "failed", "cancelled", "superseded"],
-    done: [],
-    failed: [],
-    cancelled: [],
-    superseded: [],
-};
-export function isTerminalState(state) {
-    return TRANSITIONS[state].length === 0;
-}
-export function allowedTransitions(state) {
-    return TRANSITIONS[state];
-}
-/** Same-state moves are no-ops, not transitions. */
-export function canTransition(from, to) {
-    return from === to || TRANSITIONS[from].includes(to);
-}
-/** Human-readable reason a move is illegal, or `undefined` when it is allowed. */
-export function transitionError(from, to) {
-    if (canTransition(from, to))
-        return undefined;
-    if (isTerminalState(from))
-        return `ticket is already closed (${from}); cannot move to ${to}`;
-    return `illegal transition ${from} -> ${to}; allowed: ${TRANSITIONS[from].join(", ")}`;
-}
 /** Lowercased, whitespace-collapsed objective, so wording drift does not defeat dedupe. */
 export function normalizeObjective(text) {
     return text.toLowerCase().replace(/\s+/g, " ").trim();
@@ -125,7 +108,10 @@ export function getTicket(ticketID) {
 /** Same-thread, same-dedupe-key ticket still open or in progress, if any. */
 export function findDuplicate(threadID, dedupeKey) {
     const ids = byThread.get(threadID);
-    const candidates = ids === undefined ? [...tickets.values()] : [...ids].flatMap((id) => tickets.get(id) ?? []);
+    // No ids means this thread owns no in-memory ticket, so there is nothing to reuse.
+    if (ids === undefined)
+        return undefined;
+    const candidates = [...ids].flatMap((id) => tickets.get(id) ?? []);
     return candidates.find((ticket) => ticket.dedupeKey === dedupeKey && ACTIVE_STATES.includes(ticket.state));
 }
 export function isActive(ticket) {
@@ -159,7 +145,7 @@ export function activeTicketSummary(threadID, limit = 3) {
 }
 /** Active ticket for a worker session, used when a worker ends. */
 export function activeTicketForWorker(sessionID) {
-    return [...tickets.values()].find((ticket) => ticket.workerSessionID === sessionID && ticket.state === "in_progress");
+    return findActiveTicketForWorker(tickets.values(), sessionID);
 }
 // ── validation ────────────────────────────────────────────────────────────────
 export function validateCreateInput(input) {
@@ -525,7 +511,7 @@ export function listTickets(input = {}) {
  * Gate every dispatch must pass: a dispatch always names a ticket, and that
  * ticket must be workable right now. The rules are enforced here (not in the
  * prompt) so a Router cannot dispatch without a ticket, onto a closed ticket,
- * across threads, or onto a ticket that already has a running worker.
+ * across threads, or onto a ticket that already has a live (non-terminal) worker.
  */
 export const requireDispatchTicket = Effect.fn("superagent.requireDispatchTicket")(function* (ticketID, threadID) {
     if (ticketID === undefined || ticketID.trim() === "") {
@@ -551,11 +537,16 @@ export const requireDispatchTicket = Effect.fn("superagent.requireDispatchTicket
         });
     }
     // One ticket never runs two workers at once: the previous worker must be
-    // terminal (aborted, failed, done) before anything is dispatched again.
+    // terminal (done, failed, aborted) before anything is dispatched again.
+    // `idle` is NOT terminal — the session may still be resumed — so it blocks
+    // a re-dispatch exactly like `running`. A worker record that is gone blocks
+    // nothing: there is no live worker left to wait for.
     const workerID = ticket.workerSessionID;
-    if (workerID !== undefined && store.workers.get(workerID)?.state === "running") {
+    const worker = workerID === undefined ? undefined : workers.get(workerID);
+    if (workerID !== undefined && worker !== undefined && !isWorkerTerminal(worker.state)) {
+        const article = worker.state === "idle" ? "an" : "a";
         return yield* new Tool.Error({
-            message: `ticket ${ticket.id} already has a running worker ${workerID}; wait for it or abort_session it first, then ticket_create a new ticket for the re-dispatch`,
+            message: `ticket ${ticket.id} already has ${article} ${worker.state} worker ${workerID}; wait for it to finish, abort_session it, or ticket_create a new ticket for the re-dispatch`,
         });
     }
     return ticket;
@@ -602,7 +593,7 @@ export const closeTicketsForWorker = Effect.fn("superagent.closeTicketsForWorker
     return yield* closeTicket(ctx, {
         ticketID: ticket.id,
         outcome: input.outcome,
-        summary: input.summary ?? input.note ?? `${input.outcome} (worker ${input.sessionID})`,
+        summary: workerCloseSummary(input),
         ...(input.now === undefined ? {} : { now: input.now }),
     });
 });

package/dist/src/tools.js

@@ -49,6 +49,22 @@ export const ROUTER_TOOL_SPECS = [
             "派发成功即绑定工单：workerSessionID 写入、attempts+1、state → in_progress；Worker 结束自动结单。",
         ],
     },
+    {
+        name: "sleep",
+        group: "control",
+        description: 'Pause the router for a bounded number of seconds (default 30, range 1..600) with a real timer, never a busy loop, and return "slept Ns". In Goal mode, call it after dispatch to pause and give the Worker execution time before you check in again. Only the router may call it; tracked worker sessions neither see nor may call it.',
+        summary: "暂停指定秒数（默认 30，范围 1..600），给 Worker 预留执行时间。",
+        params: [{ name: "seconds", required: false, type: "number", note: "默认 30，1..600 的整数" }],
+        risk: "read",
+        permission: "status",
+        confirmation: "只读等待，自动执行（permission: status）；非法秒数直接报错。",
+        usage: [
+            "Goal 模式：dispatch 后先 sleep，再回来汇总，不要空转轮询 Worker。",
+            "seconds 缺省 30；必须是 1..600 的整数，0/负数/超界/非数字都报错。",
+            "真实定时器（Effect.sleep）：等待期间 Router 与其他任务照常推进。",
+            "仅 Router 可见：Worker 会话的工具列表里没有它，直调也会被拒绝。",
+        ],
+    },
     {
         name: "ticket_create",
         group: "dispatch",
@@ -134,11 +150,14 @@ export const ROUTER_TOOL_SPECS = [
         name: "status",
         group: "query",
         description: "Show a compact summary of the router, pending triggers and worker sessions.",
-        summary: "查看 Router、pending 触发器数量与全部 Worker 的 thread/状态/最近报告。",
+        summary: "查看插件版本、Router、pending 触发器数量与全部 Worker 的 thread/状态/最近报告。",
         params: [],
         risk: "read",
         confirmation: "只读，自动执行（permission: status）。",
-        usage: ["system 状态行只给计数，细节用 status / thread_detail。"],
+        usage: [
+            "首行是插件版本与「升级后需重启网关」提示，用来判断网关是否还在跑旧代码。",
+            "system 状态行只给计数，细节用 status / thread_detail。",
+        ],
     },
     {
         name: "thread_detail",

package/dist/src/version.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Plugin version, read from the package's own `package.json`.
+ *
+ * The version is the only thing this module exposes: it is deliberately not a
+ * diagnostics dump, so logging it can never leak config, tokens, absolute
+ * paths or session ids.
+ */
+/** Shown when no candidate `package.json` can be read or parsed. */
+export declare const UNKNOWN_VERSION = "0.0.0-unknown";
+/** Extract `version` from raw `package.json` text; `undefined` when unusable. */
+export declare function versionFromPackageJson(raw: string): string | undefined;
+export type ReadFile = (file: string) => string | undefined;
+/**
+ * Read the first usable candidate, falling back to {@link UNKNOWN_VERSION}.
+ *
+ * `read` is injectable so the fallback path is testable without touching the
+ * filesystem: pass `() => undefined` for a missing package, or a stub that
+ * returns unparsable JSON.
+ */
+export declare function loadVersion(read?: ReadFile): string;
+/** Cached plugin version; the process never changes version at runtime. */
+export declare function pluginVersion(): string;
+/**
+ * One-line startup notice. Says what is loaded and that upgrading an already
+ * running gateway is not enough — the plugin has no hot reload, so a service
+ * restart is required before the new code is active.
+ */
+export declare function versionNotice(): string;