opencode-superagent 0.0.0-stage → 0.1.0

package/dist/src/ticket.js

@@ -0,0 +1,700 @@
+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 { displayWidth, wrapText } from "./tools.js";
+export const TICKET_PREFIX = "ticket:";
+export const TICKET_STATUS_PREFIX = "ticketidx:status:";
+export const TICKET_THREAD_PREFIX = "ticketidx:thread:";
+export const TICKET_ALL_KEY = "ticketidx:all";
+export const TITLE_MAX = 80;
+export const OBJECTIVE_MAX = 2000;
+export const ACCEPTANCE_MAX = 10;
+export const ACCEPTANCE_ITEM_MAX = 300;
+export const QUOTE_MAX = 300;
+export const SUMMARY_MAX = 500;
+/** Index buckets are capped so a long-lived gateway never writes an unbounded list. */
+export const INDEX_LIMIT = 200;
+/** Newest-N tickets kept in memory; older records stay in KV and reappear after hydrate. */
+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();
+}
+export function dedupeKeyFor(input) {
+    return createHash("sha1")
+        .update(`${input.source}\n${input.threadID}\n${normalizeObjective(input.objective)}`)
+        .digest("hex");
+}
+export const ticketKey = (id) => `${TICKET_PREFIX}${id}`;
+export const ticketStatusKey = (state) => `${TICKET_STATUS_PREFIX}${state}`;
+export const ticketThreadKey = (threadID) => `${TICKET_THREAD_PREFIX}${threadID}`;
+/** In-memory mirror of every hydrated ticket, rebuilt from KV at startup. */
+export const tickets = new Map();
+const byThread = new Map();
+let routerTrigger;
+export function noteRouterTrigger(trigger) {
+    routerTrigger = {
+        id: trigger.id ?? `${trigger.source}:${trigger.threadID}:${trigger.createdAt ?? Date.now()}`,
+        source: trigger.source,
+        threadID: trigger.threadID,
+        ...(trigger.author === undefined ? {} : { author: trigger.author }),
+        text: trigger.text,
+        at: trigger.createdAt ?? Date.now(),
+    };
+}
+export function currentTrigger() {
+    return routerTrigger;
+}
+/** Reset memory (hydrate and tests): the map and its thread index are rebuilt together. */
+export function resetTickets() {
+    tickets.clear();
+    byThread.clear();
+    routerTrigger = undefined;
+}
+function remember(ticket) {
+    tickets.set(ticket.id, ticket);
+    const ids = byThread.get(ticket.threadID) ?? new Set();
+    ids.add(ticket.id);
+    byThread.set(ticket.threadID, ids);
+}
+function forget(ticket) {
+    tickets.delete(ticket.id);
+    byThread.get(ticket.threadID)?.delete(ticket.id);
+}
+/** Cap memory by dropping the oldest closed tickets; they remain in KV. */
+function trimMemory() {
+    if (tickets.size <= MEMORY_LIMIT)
+        return;
+    const closable = [...tickets.values()]
+        .filter((ticket) => isTerminalState(ticket.state))
+        .sort((left, right) => left.updatedAt - right.updatedAt);
+    for (const ticket of closable) {
+        if (tickets.size <= MEMORY_LIMIT)
+            return;
+        forget(ticket);
+    }
+}
+export function getTicket(ticketID) {
+    return tickets.get(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) ?? []);
+    return candidates.find((ticket) => ticket.dedupeKey === dedupeKey && ACTIVE_STATES.includes(ticket.state));
+}
+export function isActive(ticket) {
+    return ACTIVE_STATES.includes(ticket.state);
+}
+export function ticketStats() {
+    const stats = { total: 0, open: 0, inProgress: 0, blocked: 0, closed: 0 };
+    for (const ticket of tickets.values()) {
+        stats.total += 1;
+        if (ticket.state === "open")
+            stats.open += 1;
+        else if (ticket.state === "in_progress")
+            stats.inProgress += 1;
+        else if (ticket.state === "blocked")
+            stats.blocked += 1;
+        else
+            stats.closed += 1;
+    }
+    return stats;
+}
+/** Compact "tk_x title; tk_y title" line for the system status, empty when there is nothing active. */
+export function activeTicketSummary(threadID, limit = 3) {
+    const active = [...tickets.values()]
+        .filter((ticket) => ACTIVE_STATES.includes(ticket.state))
+        .filter((ticket) => threadID === undefined || ticket.threadID === threadID)
+        .sort((left, right) => right.updatedAt - left.updatedAt);
+    return active
+        .slice(0, limit)
+        .map((ticket) => `${ticket.id} ${ticket.title}`)
+        .join("; ");
+}
+/** 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");
+}
+// ── validation ────────────────────────────────────────────────────────────────
+export function validateCreateInput(input) {
+    if ((input.threadID ?? "").trim() === "")
+        return "ticket_create needs a threadID";
+    const title = (input.title ?? "").trim();
+    if (title === "")
+        return "ticket_create needs a non-empty title";
+    if (title.length > TITLE_MAX)
+        return `title must be at most ${TITLE_MAX} characters`;
+    const objective = (input.objective ?? "").trim();
+    if (objective === "")
+        return "ticket_create needs a non-empty objective; ask the user first";
+    if (objective.length > OBJECTIVE_MAX)
+        return `objective must be at most ${OBJECTIVE_MAX} characters`;
+    const acceptance = (input.acceptance ?? []).map((item) => item.trim()).filter((item) => item !== "");
+    if (acceptance.length === 0) {
+        return "ticket_create needs at least one acceptance criterion; ask the user instead of creating an empty ticket";
+    }
+    if (acceptance.length > ACCEPTANCE_MAX)
+        return `acceptance takes at most ${ACCEPTANCE_MAX} items`;
+    if (acceptance.some((item) => item.length > ACCEPTANCE_ITEM_MAX)) {
+        return `each acceptance item must be at most ${ACCEPTANCE_ITEM_MAX} characters`;
+    }
+    if ((input.directory ?? "").trim() === "")
+        return "ticket_create needs a directory (absolute path)";
+    if (normalizeDirectory(input.directory ?? "") === undefined)
+        return "directory must be an absolute path";
+    return undefined;
+}
+function compact(text, limit) {
+    const clean = text.replace(/\s+/g, " ").trim();
+    if (clean.length <= limit)
+        return clean;
+    return `${clean.slice(0, limit - 1).trimEnd()}…`;
+}
+function clamp(value, min, max) {
+    if (!Number.isFinite(value))
+        return min;
+    return Math.min(max, Math.max(min, Math.floor(value)));
+}
+function newTicketID(now) {
+    for (let attempt = 0; attempt < 8; attempt++) {
+        const suffix = Math.floor(Math.random() * 36 ** 4)
+            .toString(36)
+            .padStart(4, "0");
+        const id = `tk_${now.toString(36)}_${suffix}`;
+        if (!tickets.has(id))
+            return id;
+    }
+    return `tk_${now.toString(36)}_${Math.random().toString(36).slice(2, 6).padEnd(4, "0")}`;
+}
+// ── encoding ──────────────────────────────────────────────────────────────────
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function optionalString(record, key) {
+    const value = record[key];
+    return typeof value === "string" ? value : undefined;
+}
+function optionalNumber(record, key) {
+    const value = record[key];
+    return typeof value === "number" ? value : undefined;
+}
+function stringArray(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    return value.every((item) => typeof item === "string") ? [...value] : undefined;
+}
+export function decodeTicket(value) {
+    if (!isRecord(value))
+        return undefined;
+    const id = optionalString(value, "id");
+    const state = optionalString(value, "state");
+    const title = optionalString(value, "title");
+    const objective = optionalString(value, "objective");
+    const threadID = optionalString(value, "threadID");
+    const dedupeKey = optionalString(value, "dedupeKey");
+    const acceptance = stringArray(value["acceptance"]);
+    if (id === undefined || state === undefined || title === undefined || objective === undefined)
+        return undefined;
+    if (threadID === undefined || dedupeKey === undefined)
+        return undefined;
+    if (acceptance === undefined || acceptance.length === 0)
+        return undefined;
+    if (!TICKET_STATES.includes(state))
+        return undefined;
+    const createdAt = optionalNumber(value, "createdAt");
+    if (createdAt === undefined)
+        return undefined;
+    const priority = optionalString(value, "priority");
+    const requester = isRecord(value["requester"]) ? value["requester"] : {};
+    const authorization = isRecord(value["authorization"]) ? value["authorization"] : {};
+    const attempts = Array.isArray(value["attempts"])
+        ? value["attempts"].flatMap((item) => {
+            if (!isRecord(item))
+                return [];
+            const at = optionalNumber(item, "at");
+            if (at === undefined)
+                return [];
+            const sessionID = optionalString(item, "sessionID");
+            const note = optionalString(item, "note");
+            return [{ at, ...(sessionID === undefined ? {} : { sessionID }), ...(note === undefined ? {} : { note }) }];
+        })
+        : [];
+    const history = Array.isArray(value["history"])
+        ? value["history"].flatMap((item) => {
+            if (!isRecord(item))
+                return [];
+            const at = optionalNumber(item, "at");
+            const kind = optionalString(item, "kind");
+            if (at === undefined || kind === undefined)
+                return [];
+            const from = optionalString(item, "from");
+            const to = optionalString(item, "to");
+            const note = optionalString(item, "note");
+            return [
+                {
+                    at,
+                    kind: kind,
+                    ...(from === undefined ? {} : { from: from }),
+                    ...(to === undefined ? {} : { to: to }),
+                    ...(note === undefined ? {} : { note }),
+                },
+            ];
+        })
+        : [];
+    const workerSessionID = optionalString(value, "workerSessionID");
+    const directory = optionalString(value, "directory");
+    const parentTicketID = optionalString(value, "parentTicketID");
+    const closedAt = optionalNumber(value, "closedAt");
+    const closeReason = optionalString(value, "closeReason");
+    return {
+        id,
+        state: state,
+        title,
+        objective,
+        acceptance,
+        requester: {
+            source: optionalString(requester, "source") ?? "unknown",
+            threadID: optionalString(requester, "threadID") ?? threadID,
+            ...(optionalString(requester, "author") === undefined ? {} : { author: optionalString(requester, "author") }),
+        },
+        authorization: {
+            triggerID: optionalString(authorization, "triggerID") ?? "unknown",
+            quote: optionalString(authorization, "quote") ?? "",
+            at: optionalNumber(authorization, "at") ?? createdAt,
+        },
+        threadID,
+        ...(workerSessionID === undefined ? {} : { workerSessionID }),
+        attempts,
+        priority: PRIORITIES.includes(priority) ? priority : "p1",
+        ...(directory === undefined ? {} : { directory }),
+        dedupeKey,
+        ...(parentTicketID === undefined ? {} : { parentTicketID }),
+        tags: stringArray(value["tags"]) ?? [],
+        createdAt,
+        updatedAt: optionalNumber(value, "updatedAt") ?? createdAt,
+        ...(closedAt === undefined ? {} : { closedAt }),
+        ...(closeReason === undefined ? {} : { closeReason }),
+        history,
+    };
+}
+export function encodeTicket(ticket) {
+    return {
+        id: ticket.id,
+        state: ticket.state,
+        title: ticket.title,
+        objective: ticket.objective,
+        acceptance: [...ticket.acceptance],
+        requester: {
+            source: ticket.requester.source,
+            threadID: ticket.requester.threadID,
+            ...(ticket.requester.author === undefined ? {} : { author: ticket.requester.author }),
+        },
+        authorization: {
+            triggerID: ticket.authorization.triggerID,
+            quote: ticket.authorization.quote,
+            at: ticket.authorization.at,
+        },
+        threadID: ticket.threadID,
+        ...(ticket.workerSessionID === undefined ? {} : { workerSessionID: ticket.workerSessionID }),
+        attempts: ticket.attempts.map((attempt) => ({
+            at: attempt.at,
+            ...(attempt.sessionID === undefined ? {} : { sessionID: attempt.sessionID }),
+            ...(attempt.note === undefined ? {} : { note: attempt.note }),
+        })),
+        priority: ticket.priority,
+        ...(ticket.directory === undefined ? {} : { directory: ticket.directory }),
+        dedupeKey: ticket.dedupeKey,
+        ...(ticket.parentTicketID === undefined ? {} : { parentTicketID: ticket.parentTicketID }),
+        tags: [...ticket.tags],
+        createdAt: ticket.createdAt,
+        updatedAt: ticket.updatedAt,
+        ...(ticket.closedAt === undefined ? {} : { closedAt: ticket.closedAt }),
+        ...(ticket.closeReason === undefined ? {} : { closeReason: ticket.closeReason }),
+        history: ticket.history.map((entry) => ({
+            at: entry.at,
+            kind: entry.kind,
+            ...(entry.from === undefined ? {} : { from: entry.from }),
+            ...(entry.to === undefined ? {} : { to: entry.to }),
+            ...(entry.note === undefined ? {} : { note: entry.note }),
+        })),
+    };
+}
+// ── persistence ───────────────────────────────────────────────────────────────
+function collect(predicate) {
+    return [...tickets.values()]
+        .filter(predicate)
+        .sort((left, right) => right.createdAt - left.createdAt)
+        .slice(0, INDEX_LIMIT)
+        .map((ticket) => ticket.id);
+}
+const writeIds = Effect.fn("superagent.persistTicketIndex")(function* (ctx, key, ids) {
+    yield* ctx.storage
+        .set(key, ids)
+        .pipe(Effect.catch((cause) => Effect.logWarning("superagent failed to persist ticket index", { key, cause })));
+});
+const persistTicket = Effect.fn("superagent.persistTicket")(function* (ctx, ticket) {
+    yield* ctx.storage
+        .set(ticketKey(ticket.id), encodeTicket(ticket))
+        .pipe(Effect.catch((cause) => Effect.logWarning("superagent failed to persist ticket", { cause })));
+});
+/** Only the buckets the ticket touches are rewritten; the record prefix stays authoritative. */
+const persistIndexes = Effect.fn("superagent.persistTicketIndexes")(function* (ctx, ticket) {
+    yield* writeIds(ctx, TICKET_ALL_KEY, collect(() => true));
+    yield* writeIds(ctx, ticketStatusKey(ticket.state), collect((item) => item.state === ticket.state));
+    yield* writeIds(ctx, ticketThreadKey(ticket.threadID), collect((item) => item.threadID === ticket.threadID));
+});
+const rewriteIndexes = Effect.fn("superagent.rewriteTicketIndexes")(function* (ctx) {
+    yield* writeIds(ctx, TICKET_ALL_KEY, collect(() => true));
+    for (const state of TICKET_STATES) {
+        yield* writeIds(ctx, ticketStatusKey(state), collect((ticket) => ticket.state === state));
+    }
+    for (const threadID of [...new Set([...tickets.values()].map((ticket) => ticket.threadID))]) {
+        yield* writeIds(ctx, ticketThreadKey(threadID), collect((ticket) => ticket.threadID === threadID));
+    }
+});
+/**
+ * Create a ticket, or return the still-open same-key ticket in the same
+ * thread (`reused: true`). Objective, acceptance and directory are required;
+ * an empty acceptance is rejected so no placeholder ticket can exist.
+ */
+export const createTicket = Effect.fn("superagent.createTicket")(function* (ctx, input) {
+    const failure = validateCreateInput(input);
+    if (failure !== undefined)
+        return yield* new Tool.Error({ message: failure });
+    const now = input.now ?? Date.now();
+    const directory = normalizeDirectory(input.directory);
+    if (directory === undefined)
+        return yield* new Tool.Error({ message: "directory must be an absolute path" });
+    const acceptance = input.acceptance.map((item) => item.trim()).filter((item) => item !== "");
+    const dedupeKey = input.dedupeKey?.trim() ||
+        dedupeKeyFor({ source: input.source, threadID: input.threadID, objective: input.objective });
+    const duplicate = findDuplicate(input.threadID, dedupeKey);
+    if (duplicate !== undefined)
+        return { ticket: duplicate, reused: true };
+    const trigger = routerTrigger;
+    const authorization = input.authorization ??
+        (trigger === undefined
+            ? { triggerID: "unknown", quote: "", at: now }
+            : { triggerID: trigger.id, quote: compact(trigger.text, QUOTE_MAX), at: trigger.at });
+    const ticket = {
+        id: newTicketID(now),
+        state: "open",
+        title: compact(input.title, TITLE_MAX),
+        objective: input.objective.trim(),
+        acceptance,
+        requester: {
+            source: input.source,
+            threadID: input.threadID,
+            ...(input.author === undefined ? {} : { author: input.author }),
+        },
+        authorization,
+        threadID: input.threadID,
+        attempts: [],
+        priority: input.priority ?? "p1",
+        directory,
+        dedupeKey,
+        ...(input.parentTicketID === undefined ? {} : { parentTicketID: input.parentTicketID }),
+        tags: [...(input.tags ?? [])],
+        createdAt: now,
+        updatedAt: now,
+        history: [{ at: now, kind: "created", to: "open" }],
+    };
+    remember(ticket);
+    trimMemory();
+    yield* persistTicket(ctx, ticket);
+    yield* persistIndexes(ctx, ticket);
+    return { ticket, reused: false };
+});
+/** Move a ticket through the state machine. Illegal moves fail with a `Tool.Error`. */
+export const updateTicket = Effect.fn("superagent.updateTicket")(function* (ctx, input) {
+    const ticket = tickets.get(input.ticketID);
+    if (ticket === undefined)
+        return yield* new Tool.Error({ message: `unknown ticket ${input.ticketID}` });
+    const now = input.now ?? Date.now();
+    if (input.state !== undefined && input.state !== ticket.state) {
+        const failure = transitionError(ticket.state, input.state);
+        if (failure !== undefined)
+            return yield* new Tool.Error({ message: failure });
+        ticket.history.push({
+            at: now,
+            kind: "state",
+            from: ticket.state,
+            to: input.state,
+            ...(input.note === undefined ? {} : { note: input.note }),
+        });
+        ticket.state = input.state;
+        if (isTerminalState(input.state)) {
+            ticket.closedAt = now;
+            ticket.closeReason = compact(input.note ?? input.state, SUMMARY_MAX);
+        }
+    }
+    else if (input.note !== undefined) {
+        ticket.history.push({ at: now, kind: "note", note: compact(input.note, SUMMARY_MAX) });
+    }
+    if (input.workerSessionID !== undefined)
+        ticket.workerSessionID = input.workerSessionID;
+    ticket.updatedAt = now;
+    yield* persistTicket(ctx, ticket);
+    yield* persistIndexes(ctx, ticket);
+    return ticket;
+});
+/** Close a ticket with an outcome, recording summary/closedAt in the record and history. */
+export const closeTicket = Effect.fn("superagent.closeTicket")(function* (ctx, input) {
+    const ticket = tickets.get(input.ticketID);
+    if (ticket === undefined)
+        return yield* new Tool.Error({ message: `unknown ticket ${input.ticketID}` });
+    // Re-closing with the same outcome is idempotent; a different outcome is a conflict.
+    if (isTerminalState(ticket.state)) {
+        if (ticket.state === input.outcome)
+            return ticket;
+        return yield* new Tool.Error({
+            message: `ticket ${ticket.id} is already closed (${ticket.state}); cannot close as ${input.outcome}`,
+        });
+    }
+    const failure = transitionError(ticket.state, input.outcome);
+    if (failure !== undefined)
+        return yield* new Tool.Error({ message: failure });
+    const now = input.now ?? Date.now();
+    const summary = compact(input.summary, SUMMARY_MAX);
+    ticket.history.push({ at: now, kind: "closed", from: ticket.state, to: input.outcome, note: summary });
+    ticket.state = input.outcome;
+    ticket.closedAt = now;
+    ticket.closeReason = summary;
+    ticket.updatedAt = now;
+    yield* persistTicket(ctx, ticket);
+    yield* persistIndexes(ctx, ticket);
+    return ticket;
+});
+/** Newest-updated first; filters are combined with AND. */
+export function listTickets(input = {}) {
+    const limit = clamp(input.limit ?? LIST_DEFAULT, 1, LIST_MAX);
+    return [...tickets.values()]
+        .filter((ticket) => input.threadID === undefined || ticket.threadID === input.threadID)
+        .filter((ticket) => input.status === undefined || ticket.state === input.status)
+        .filter((ticket) => input.since === undefined || ticket.updatedAt >= input.since)
+        .sort((left, right) => right.updatedAt - left.updatedAt)
+        .slice(0, limit);
+}
+/**
+ * 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.
+ */
+export const requireDispatchTicket = Effect.fn("superagent.requireDispatchTicket")(function* (ticketID, threadID) {
+    if (ticketID === undefined || ticketID.trim() === "") {
+        return yield* new Tool.Error({ message: "dispatch requires ticketID; create a ticket with ticket_create first" });
+    }
+    const ticket = tickets.get(ticketID);
+    if (ticket === undefined) {
+        return yield* new Tool.Error({
+            message: `unknown ticket ${ticketID}; create it with ticket_create first, then dispatch({ ticketID })`,
+        });
+    }
+    if (!ACTIVE_STATES.includes(ticket.state)) {
+        const hint = ticket.state === "blocked"
+            ? 'reopen it with ticket_update({ status: "in_progress" })'
+            : "create a new ticket with ticket_create";
+        return yield* new Tool.Error({
+            message: `ticket ${ticket.id} is ${ticket.state}; only open/in_progress tickets can be dispatched — ${hint}`,
+        });
+    }
+    if (threadID !== undefined && threadID !== ticket.threadID) {
+        return yield* new Tool.Error({
+            message: `ticket ${ticket.id} belongs to thread ${ticket.threadID}, not ${threadID}; dispatch with threadID=${ticket.threadID} or ticket_create a ticket for ${threadID}`,
+        });
+    }
+    // One ticket never runs two workers at once: the previous worker must be
+    // terminal (aborted, failed, done) before anything is dispatched again.
+    const workerID = ticket.workerSessionID;
+    if (workerID !== undefined && store.workers.get(workerID)?.state === "running") {
+        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`,
+        });
+    }
+    return ticket;
+});
+/**
+ * Attach a dispatched worker to its ticket and move `open` to `in_progress`.
+ * Only `open`/`in_progress` tickets accept a worker.
+ */
+export const linkTicketToWorker = Effect.fn("superagent.linkTicketToWorker")(function* (ctx, input) {
+    const ticket = tickets.get(input.ticketID);
+    if (ticket === undefined)
+        return yield* new Tool.Error({ message: `unknown ticket ${input.ticketID}` });
+    if (!ACTIVE_STATES.includes(ticket.state)) {
+        return yield* new Tool.Error({
+            message: `ticket ${ticket.id} is ${ticket.state}; only open/in_progress tickets can be dispatched`,
+        });
+    }
+    const now = input.now ?? Date.now();
+    ticket.workerSessionID = input.sessionID;
+    ticket.attempts.push({
+        at: now,
+        sessionID: input.sessionID,
+        ...(input.note === undefined ? {} : { note: input.note }),
+    });
+    ticket.history.push({ at: now, kind: "dispatch", note: `worker ${input.sessionID}` });
+    if (ticket.state === "open") {
+        ticket.history.push({ at: now, kind: "state", from: "open", to: "in_progress" });
+        ticket.state = "in_progress";
+    }
+    ticket.updatedAt = now;
+    yield* persistTicket(ctx, ticket);
+    yield* persistIndexes(ctx, ticket);
+    return ticket;
+});
+/**
+ * Close the in-progress ticket attached to a worker that just ended. Tickets
+ * in any other state are left alone: a closed ticket never reopens and an
+ * aborted worker is handled by its own path.
+ */
+export const closeTicketsForWorker = Effect.fn("superagent.closeTicketsForWorker")(function* (ctx, input) {
+    const ticket = activeTicketForWorker(input.sessionID);
+    if (ticket === undefined)
+        return undefined;
+    return yield* closeTicket(ctx, {
+        ticketID: ticket.id,
+        outcome: input.outcome,
+        summary: input.summary ?? input.note ?? `${input.outcome} (worker ${input.sessionID})`,
+        ...(input.now === undefined ? {} : { now: input.now }),
+    });
+});
+/**
+ * Load every `ticket:<id>` record and rebuild the indexes. Older workers are
+ * never backfilled: a worker with no ticket stays without one, silently.
+ */
+export const hydrateTickets = Effect.fn("superagent.hydrateTickets")(function* (ctx) {
+    resetTickets();
+    let after;
+    do {
+        const page = yield* ctx.storage
+            .scan({ prefix: TICKET_PREFIX, after, limit: 100 })
+            .pipe(Effect.catch(() => Effect.succeed({ entries: [], next: undefined })));
+        for (const entry of page.entries) {
+            const ticket = decodeTicket(entry.value);
+            if (ticket === undefined) {
+                yield* ctx.storage.remove(entry.key).pipe(Effect.catch(() => Effect.void));
+                continue;
+            }
+            remember(ticket);
+        }
+        after = page.next;
+    } while (after !== undefined);
+    trimMemory();
+    yield* rewriteIndexes(ctx);
+    yield* Effect.logInfo("superagent tickets hydrated", { count: tickets.size });
+});
+// ── rendering (shared by tools and the TUI, narrow-terminal first) ─────────────
+export const DETAIL_WIDTH = 52;
+function wrapBullet(text, width) {
+    return wrapText(text, width - 2).map((line, index) => (index === 0 ? `· ${line}` : `  ${line}`));
+}
+function wrapLabel(label, text, width) {
+    const indent = " ".repeat(displayWidth(label));
+    return wrapText(`${label}${text}`, width).map((line, index) => (index === 0 ? line : `${indent}${line}`));
+}
+function shortTime(epoch) {
+    const date = new Date(epoch);
+    const pad = (value) => `${value}`.padStart(2, "0");
+    return `${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+export function renderTicketList(items, width = DETAIL_WIDTH) {
+    if (items.length === 0)
+        return "暂无工单（用户交代新任务时先 ticket_create）";
+    const active = items.filter((ticket) => ACTIVE_STATES.includes(ticket.state)).length;
+    const lines = [`工单 ${items.length} · 进行中 ${active}`];
+    for (const state of TICKET_STATES) {
+        const group = items.filter((ticket) => ticket.state === state);
+        if (group.length === 0)
+            continue;
+        lines.push("", `${state} (${group.length})`);
+        for (const ticket of group) {
+            const worker = ticket.workerSessionID === undefined ? "" : ` w=${ticket.workerSessionID.slice(-6)}`;
+            const tail = `${shortTime(ticket.updatedAt)}${worker}`;
+            lines.push(...wrapBullet(`${ticket.id} ${ticket.priority} ${ticket.title}`, width));
+            lines.push(...wrapBullet(tail, width));
+        }
+    }
+    return lines.join("\n");
+}
+export function renderTicketDetail(ticket, width = DETAIL_WIDTH) {
+    const lines = [`${ticket.id} · ${ticket.state} · ${ticket.priority}`, ...wrapText(ticket.title, width)];
+    lines.push("", ...wrapLabel("目标：", ticket.objective, width));
+    lines.push("", "验收：");
+    ticket.acceptance.forEach((item, index) => {
+        lines.push(...wrapBullet(`${index + 1}. ${item}`, width));
+    });
+    lines.push("");
+    lines.push(...wrapLabel("thread：", ticket.threadID, width));
+    lines.push(...wrapLabel("目录：", ticket.directory ?? "-", width));
+    lines.push(...wrapLabel("worker：", ticket.workerSessionID ?? "-", width));
+    lines.push(...wrapLabel("尝试：", `${ticket.attempts.length}`, width));
+    lines.push(...wrapLabel("建档：", shortTime(ticket.createdAt), width));
+    lines.push(...wrapLabel("更新：", shortTime(ticket.updatedAt), width));
+    if (ticket.closedAt !== undefined)
+        lines.push(...wrapLabel("关闭：", shortTime(ticket.closedAt), width));
+    if (ticket.closeReason !== undefined)
+        lines.push(...wrapLabel("结论：", ticket.closeReason, width));
+    if (ticket.parentTicketID !== undefined)
+        lines.push(...wrapLabel("父单：", ticket.parentTicketID, width));
+    if (ticket.authorization.quote !== "") {
+        lines.push("", ...wrapLabel("原话：", ticket.authorization.quote, width));
+    }
+    const history = ticket.history.slice(-5);
+    if (history.length > 0) {
+        lines.push("", `历史（最近 ${history.length} 条）：`);
+        for (const entry of history) {
+            const move = entry.from === undefined ? entry.kind : `${entry.from}→${entry.to ?? entry.kind}`;
+            const note = entry.note === undefined ? "" : ` ${entry.note}`;
+            lines.push(...wrapBullet(`${shortTime(entry.at)} ${move}${note}`, width));
+        }
+    }
+    return lines.join("\n");
+}