@timqi/pier 0.1.0 → 0.1.2

package/dist/tasks/service.js

@@ -1,9 +1,6 @@
-// The one object the rest of Pier talks to about tasks, and the clock behind
-// it: the tick that finds what is due, the boot recovery that writes off runs
-// a restart interrupted, and the pause a drain needs. Every decision it looks
-// like it makes belongs to a file beside it (definitions, runs, execution,
-// groups, messages, callbacks) — what is genuinely here is scheduling and the
-// facade, so the HTTP routes and the task tool cannot drift apart.
+// The facade the rest of Pier talks to about tasks, and the clock behind it:
+// the tick, the boot recovery that writes off interrupted runs, and the pause a
+// drain needs. Decisions belong to the files beside it.
 import { logger } from "../log.js";
 import { AgentTaskRunner } from "./agent.js";
 import { TaskCallbacks } from "./callbacks.js";
@@ -15,9 +12,8 @@ import { TaskRunQueue } from "./runs.js";
 import { handleTaskTool } from "./tool.js";
 import { isTerminal } from "./types.js";
 const log = logger("tasks");
-/** The text a run was given, as the operator wrote it: a resume's follow-up,
- *  else the action's own prompt or script. Not `renderedPrompt` — that is the
- *  preamble and the input wrapper, which the delegating session did not send. */
+/** Not `renderedPrompt`: that carries the preamble and input wrapper, which the
+ *  delegating session did not send. */
 const runPrompt = (run) => {
     if (run.context.resumePrompt)
         return run.context.resumePrompt;
@@ -40,8 +36,7 @@ export class TaskService {
     runs;
     execution;
     constructor(store, factory, router, hub, 
-    /** Structural on purpose: tasks/ must not import settings.ts — main.ts
-     *  hands in a closure over the store instead. Absent in bare test rigs. */
+    /** Structural: tasks/ must not import settings.ts. Absent in bare test rigs. */
     instance) {
         this.store = store;
         this.factory = factory;
@@ -108,10 +103,8 @@ export class TaskService {
         }, tickMs);
         this.timer.unref();
     }
-    /** Undo a `pause()` that was not followed by an exit — the auto-updater
-     *  drains before handing over, and a handover that never started must not
-     *  leave the scheduler switched off. Deliberately not `start()`: the boot
-     *  recovery in there would write off runs this process is still running. */
+    /** For a handover that never started. Not `start()`: its boot recovery would
+     *  write off runs this process is still running. */
     unpause(tickMs = 1000) {
         if (this.timer)
             return;
@@ -122,11 +115,8 @@ export class TaskService {
         this.pause();
         this.execution.stop();
     }
-    /** Stop taking new work but leave running runs alone — a graceful restart
-     *  (src/drain.ts) waits for them, where stop() would abort them. The
-     *  scheduler timer goes, and new root runs are refused; children of a run
-     *  that is still finishing stay allowed, because refusing them would fail
-     *  the very work the drain is waiting for. */
+    /** New root runs are refused, running ones left for the drain to wait on;
+     *  children of a finishing run stay allowed, or the drain fails its own work. */
     pause() {
         this.paused = true;
         if (this.timer)
@@ -143,11 +133,8 @@ export class TaskService {
     activeRunCount() {
         return this.store.countActiveRuns();
     }
-    /** The run this task has in flight, if any. The store already answers this
-     *  for the overlap guard (runs.ts); a caller that has just been refused as
-     *  an overlap needs the same answer to know what to wait for, and scanning
-     *  run history for it finds nothing once the skipped rows outnumber the
-     *  window. */
+    /** A caller refused as an overlap needs this to know what to wait for;
+     *  scanning run history finds nothing once skipped rows outnumber the window. */
     activeRun(taskId) {
         return this.store.findActiveRun(taskId);
     }
@@ -160,8 +147,7 @@ export class TaskService {
     create(raw, creator = "http") {
         return this.definitions.create(raw, creator);
     }
-    /** `by` is how the code that owns a definition says so; the HTTP routes and
-     *  the task tool have none, which is what closes both (definitions.ts). */
+    /** `by` is how owning code says so; the routes and the tool have none (definitions.ts). */
     update(id, raw, by) {
         return this.definitions.update(id, raw, by);
     }
@@ -202,16 +188,13 @@ export class TaskService {
     recentMessages(since) {
         return this.messages.recent(since);
     }
-    /** Every run this session delegated: the card is the message that started
-     *  it, and a message does not leave the transcript because the run ended. */
+    /** Every run, not the last hour's: the card is a message in the transcript. */
     backgroundRuns(sessionId) {
         return this.store.listRunsForSession(sessionId, 200)
             .filter((run) => run.background)
             .reverse()
             .map((run) => this.backgroundRun(run));
     }
-    /** The same runs `backgroundRuns` reports as in flight, counted per session
-     *  in one query — a list needs the number, not the runs. */
     activeBackgroundRunCounts() {
         return this.store.countActiveBackgroundRunsBySession();
     }
@@ -326,9 +309,7 @@ export class TaskService {
     tool(raw, callerSessionId) {
         return handleTaskTool(this, this.definitions, this.store, this.messages, raw, callerSessionId);
     }
-    /** The deployment's model advice: the operator's pinned menu when one is
-     * set, the curated live catalog otherwise — an agent picks from names that
-     * exist right now, never from memory. */
+    /** An agent picks from names that exist right now, never from memory. */
     async models() {
         const menu = this.instance?.modelMenu() ?? [];
         if (menu.length)
@@ -342,8 +323,17 @@ export class TaskService {
         try {
             const now = Date.now();
             this.sweep("schedule", () => {
-                for (const task of this.definitions.claimDue(now)) {
-                    this.run(task.id, null, task.trigger.type === "watch" ? "watch" : "cron");
+                // Per task: one enqueue that throws must not spend the other due tasks'
+                // occurrence, and its own stays due for the next tick.
+                for (const task of this.definitions.due(now)) {
+                    this.sweep(`schedule ${task.name}`, () => {
+                        const run = this.store.transact(() => {
+                            this.definitions.advance(task, now);
+                            return this.prepareRun(task.id, null, task.trigger.type === "watch" ? "watch" : "cron", null, {});
+                        });
+                        this.hub.emitWorkspace({ type: "tasks-changed" });
+                        this.runs.start(run);
+                    });
                 }
             });
             this.sweep("run callbacks", () => this.callbacks.recover(now));
@@ -354,16 +344,13 @@ export class TaskService {
             this.ticking = false;
         }
     }
-    /** A delivery nobody can complete. Retrying it forever costs the same
-     * silence as dropping it, so it stops here and says so on three surfaces:
-     * the operator's log, the record the tool and Console read, and the event
-     * stream of the session that was supposed to receive it (§5b). */
+    /** Retrying forever costs the same silence as dropping, so it stops and says
+     *  so on the log, the record and the recipient's event stream (§5). */
     unreachable(sessionId, what, why) {
         log.error(`gave up delivering ${what} to session ${sessionId}: ${why}`);
         this.router.reportTo(sessionId, `${what} could not be delivered — ${why}`);
     }
-    /** Four independent sweeps, isolated: one throwing (a group whose member row
-     * is gone throws on every pass) must not starve the retries behind it. */
+    /** Isolated: one sweep throwing on every pass must not starve the others. */
     sweep(what, run) {
         try {
             run();

package/dist/tasks/store.js

@@ -1,9 +1,10 @@
-// Every query this area makes against pier.db, and nothing else: definitions,
-// runs, groups and messages are rows here, read and written through one
-// connection db.ts opened. A store owns its queries, never its own tables or
-// its own handle — the schema is db.ts's migration list.
+// Every query this area makes against pier.db, and nothing else; the schema is
+// db.ts's migration list.
 import { pierDb, statements, transact } from "../db.js";
 const clamp = (limit, cap) => Math.min(Math.max(limit, 1), cap);
+/** Kept unmatched probes per watch: one page of history, which is all any
+ *  surface lists of a probe that found nothing. */
+const KEPT_PROBES = 50;
 export class TaskStore {
     db;
     /** Every query below is a fixed string, so each is compiled once. */
@@ -16,9 +17,7 @@ export class TaskStore {
     transact(work) {
         return transact(this.db, work);
     }
-    // Every table is one JSON column plus query columns; these two are the only
-    // readers, and the one seam where a future schema change normalizes old rows
-    // (pre-v1 databases are refused outright in db.ts).
+    // The only readers of the JSON columns, and where a schema change normalizes old rows.
     #one(sql, ...params) {
         const row = this.sql(sql).get(...params);
         return row ? JSON.parse(row.json) : undefined;
@@ -39,9 +38,7 @@ export class TaskStore {
       ON CONFLICT(id) DO UPDATE SET updated_at=excluded.updated_at, json=excluded.json
     `).run(task.id, task.updatedAt, JSON.stringify(task));
     }
-    /** The tick's whole question, asked of the index rather than of every
-     *  document: a task with no next run (disabled, archived, manual) is not in
-     *  it, so an idle second reads no row. */
+    /** Asked of the index, not every document: an idle second reads no row. */
     listDueTasks(now) {
         return this.#many("SELECT json FROM tasks WHERE next_run_at IS NOT NULL AND next_run_at <= ?", now);
     }
@@ -62,9 +59,28 @@ export class TaskStore {
         state=excluded.state, callback_state=excluded.callback_state, json=excluded.json
     `).run(run.id, run.taskId, run.queuedAt, run.state, run.callbackState, JSON.stringify(run));
     }
-    /** The global list: filters precede the limit, and the id breaks timestamp
-     *  ties so a page boundary never repeats or skips a row. The statement is
-     *  built per call and not cached — the filter set makes it. */
+    /** A watch at the five-second floor mints 17k rows a day, ~1.6 kB each, that
+     *  no list shows; only rows nothing can dangle from are dropped — a child
+     *  run is named in its parent's stored result. */
+    pruneUnmatchedProbes(taskId) {
+        this.sql(`
+      DELETE FROM task_runs WHERE id IN (
+        SELECT r.id FROM task_runs r
+        WHERE r.task_id = ? AND r.state = 'succeeded' AND json_extract(r.json, '$.matched') IS 0
+          AND r.callback_state IS NULL AND json_extract(r.json, '$.groupId') IS NULL
+          AND json_extract(r.json, '$.parentRunId') IS NULL
+          AND NOT EXISTS (SELECT 1 FROM task_messages m WHERE m.run_id = r.id)
+          -- A NULL in this list would make NOT IN unknown for every candidate.
+          AND r.id NOT IN (
+            SELECT json_extract(c.json, '$.resumedFromRunId') FROM task_runs c
+            WHERE c.task_id = ? AND json_extract(c.json, '$.resumedFromRunId') IS NOT NULL
+          )
+        ORDER BY r.queued_at DESC, r.id DESC LIMIT -1 OFFSET ?
+      )
+    `).run(taskId, taskId, KEPT_PROBES);
+    }
+    /** The id breaks timestamp ties so a page boundary never repeats or skips a
+     *  row. Built per call, not cached: the filter set makes it. */
     queryRuns(query = {}) {
         const where = [];
         const params = [];
@@ -143,9 +159,7 @@ export class TaskStore {
       ORDER BY CASE state WHEN 'running' THEN 0 ELSE 1 END, queued_at DESC LIMIT 1
     `, sessionId);
     }
-    /** How many background runs each session has in flight, for a list that
-     *  draws one dot per row: the state column narrows the scan to the handful
-     *  of live runs, and no row's JSON is parsed. */
+    /** The state column narrows the scan to live runs; no JSON is parsed. */
     countActiveBackgroundRunsBySession() {
         const rows = this.sql(`
       SELECT json_extract(json, '$.invokedBySessionId') AS session_id, COUNT(*) AS n
@@ -157,10 +171,8 @@ export class TaskStore {
     `).all();
         return new Map(rows.map((row) => [row.session_id, row.n]));
     }
-    /** Every session a run created for itself — `fresh` is the one mode that
-     *  makes a session rather than borrowing one, and a resumed run reuses the
-     *  session its `fresh` predecessor already stamped. These are the agent's
-     *  conversations with itself, which the rail does not list. */
+    /** `fresh` is the one mode that makes a session rather than borrowing one;
+     *  these are the agent's conversations with itself, which the rail does not list. */
     taskOwnedSessionIds() {
         const rows = this.sql(`
       SELECT DISTINCT json_extract(json, '$.context.sessionId') AS id
@@ -214,10 +226,8 @@ export class TaskStore {
     listRecentMessages(since) {
         return this.#many("SELECT json FROM task_messages WHERE created_at >= ? ORDER BY created_at DESC LIMIT 200", since);
     }
-    /** Messages whose injection never landed, each beside the run it belongs to:
-     *  the delivery sweep needs both, and fetching the run per message made one
-     *  sweep cost a query per undelivered message. A message whose run is gone
-     *  comes back with `run: undefined` — the sweep drops it. */
+    /** Each beside its run, so the sweep costs one query. A message whose run is
+     *  gone comes back with `run: undefined`. */
     listUndeliveredMessages() {
         const rows = this.sql(`
       SELECT m.json AS json, r.json AS run_json
@@ -237,9 +247,8 @@ export class TaskStore {
       WHERE state = 'pending' AND json_extract(json, '$.kind') != 'decision'
     `).map((message) => {
             message.state = "expired";
-            // "Confirmed", not "completed": the input may well have been read — the
-            // proof of it lives in the recipient's transcript, which this layer
-            // cannot see, and the run it steered is interrupted by the same restart.
+            // "Confirmed", not "completed": the proof lives in a transcript this
+            // layer cannot see.
             message.error = "Pier restarted before delivery could be confirmed";
             this.saveMessage(message);
             return message;

package/dist/tasks/tool.js

@@ -6,17 +6,9 @@ import { isTerminal } from "./types.js";
 const log = logger("tasks");
 // JSON-Schema enum emits ~1/3 the tokens of typebox's anyOf-of-consts.
 const strEnum = (...values) => Type.Unsafe({ type: "string", enum: [...values] });
-/**
- * Drop the fields with nothing in them instead of sending `null`.
- *
- * A run summary has eighteen fields and most are empty for most of a run's
- * life; a model reads "absent" and "null" the same way. On a group summary
- * that lists several runs this is a third of the payload.
- *
- * The input names every field — a summary that forgot one would otherwise pass
- * as "that field was empty" — and the result is the type with the empty ones
- * gone, which is why those are declared optional above.
- */
+/** Absent instead of `null`: a model reads both the same way, and on a group
+ *  summary the nulls are a third of the payload. The input names every field
+ *  so a summary that forgot one cannot pass as "empty". */
 const defined = (value) => Object.fromEntries(Object.entries(value).filter(([, v]) => v !== null && v !== undefined));
 const summarize = (run, pendingDecisionId) => defined({
     runId: run.id,
@@ -40,9 +32,8 @@ const summarize = (run, pendingDecisionId) => defined({
     skipReason: run.skipReason,
     next: null,
 });
-/** What a run receipt says happens next. The callback is the whole answer, so
- *  the receipt says so — a model that just launched work otherwise reaches
- *  for a status call. `none` is stated as what it is: no delivery at all. */
+/** The receipt says the callback is the whole answer, or a model that just
+ *  launched work reaches for a status call. */
 const receipt = (summary, callbackSessionId, mode, callerSessionId) => ({
     ...summary,
     next: callbackSessionId === null
@@ -53,6 +44,19 @@ const receipt = (summary, callbackSessionId, mode, callerSessionId) => ({
                 ? "the result interrupts your running turn as a steer message; nothing to query"
                 : "the result arrives as a callback message once your turn ends; nothing to query",
 });
+const SUBAGENT_REDIRECT = "subagents cannot redirect callbacks (callback_session_id)";
+/** Who a new run's result goes to — the caller, nobody, or a named session that
+ *  must exist. Shared by `run` and `resume`: a resumed run is a new run. */
+const callbackTarget = async (input, definitions, callerSessionId) => {
+    if (input.callback_session_id === undefined)
+        return input.callback === "none" ? null : callerSessionId;
+    if (input.callback === "none")
+        throw new Error("callback none and callback_session_id conflict: pick one delivery target");
+    const target = requiredString(input.callback_session_id, "callback_session_id");
+    if (!(await definitions.sessionExists(target)))
+        throw new Error(`unknown session: ${target}`);
+    return target;
+};
 /** A group echoes many results at once, so each is capped; a single-run
  * `recover` stays whole — it is the escape hatch every truncation note points at. */
 const trimResult = (summary) => {
@@ -66,13 +70,10 @@ const trimResult = (summary) => {
         },
     };
 };
-/** Whether a callback record has said its last word: the input is in the
- *  recipient's transcript, delivery was given up on and reported, or there
- *  was never one to wait for (`callback:"none"`). Anything else is still on
- *  its way, and reading the result here would be reading it twice. */
+/** Delivered, given up on and reported, or never owed (`callback:"none"`).
+ *  Anything else is still on its way, and reading it here would be reading it twice. */
 const settled = (callback) => callback.callbackState === null || callback.callbackState === "delivered" || callback.callbackState === "abandoned";
-/** The one refusal `recover` gives before a result is readable. Deliberately
- *  the same words for queued, running, pending and retrying: a refusal that
+/** The same words for queued, running, pending and retrying: a refusal that
  *  named the state would be the status query this operation replaced. */
 const notRecoverable = (what, callback) => {
     throw new Error(callback.callbackSessionId === null
@@ -93,8 +94,8 @@ const LaunchSchema = Type.Object({
     model: Type.Optional(Type.Object({ provider: Type.String(), id: Type.String() })),
     thinking: Type.Optional(Type.String()),
 });
-// Model-facing draft shape. Guidance only: runtime truth stays in parseDraft,
-// so schema drift can never loosen boundary validation.
+// Guidance only: runtime truth stays in parseDraft, so schema drift cannot
+// loosen boundary validation.
 const DraftSchema = Type.Object({
     name: Type.Optional(Type.String({ description: "Defaults to the prompt's first line." })),
     description: Type.Optional(Type.String()),
@@ -134,7 +135,7 @@ export function taskToolSpec(execute) {
     return {
         name: "task",
         label: "Pier Task",
-        description: "Manage durable Pier tasks and subagents. Agent tasks run in a fresh session or a reused one. create files a definition the operator sees in the Console — only for schedules or roles you will run again; a one-off is run with a prompt. Run executes a stored task by task_id, a one-shot subagent from a prompt (shorthand: prompt + optional cwd/launch/name — cwd defaults to your own directory, relative paths resolve against it, name comes from the prompt) or from a full inline task draft, or a core-joined fan-out via tasks[] with join all|first. Every operation returns immediately: results, group joins, and decision replies arrive as callback messages once your turn ends — there is no status query; pass callback 'steer' to have a result interrupt your running turn instead, or 'none' for no callback at all. recover (run_id or group_id, plus a reason) re-reads a finished result after its callback has settled — for truncated text or lost context, never to check progress. Use steer/follow_up/resume for child control and contact/reply for supervisor decisions. models lists the deployment's model menu (operator pins with intent notes, else the live catalog).",
+        description: "Manage durable Pier tasks and subagents. Agent tasks run in a fresh session or a reused one. create files a definition the operator sees in the Console — only for schedules or roles you will run again; a one-off is run with a prompt. Run executes a stored task by task_id, a one-shot subagent from a prompt (shorthand: prompt + optional cwd/launch/name/timeoutSeconds — cwd defaults to your own directory, relative paths resolve against it, name comes from the prompt) or from a full inline task draft, or a core-joined fan-out via tasks[] with join all|first. Every operation returns immediately: results, group joins, and decision replies arrive as callback messages once your turn ends — there is no status query; pass callback 'steer' to have a result interrupt your running turn instead, or 'none' for no callback at all. recover (run_id or group_id, plus a reason) re-reads a finished result after its callback has settled — for truncated text or lost context, never to check progress. Use steer/follow_up/resume for child control and contact/reply for supervisor decisions. models lists the deployment's model menu (operator pins with intent notes, else the live catalog).",
         parameters: Type.Object({
             operation: strEnum("list", "create", "update", "run", "recover", "cancel", "steer", "follow_up", "resume", "contact", "reply", "models"),
             task_id: Type.Optional(Type.String()),
@@ -144,19 +145,17 @@ export function taskToolSpec(execute) {
             message: Type.Optional(Type.String()),
             reason: Type.Optional(Type.String({ description: "contact: progress | decision. recover: why the delivered callback is not enough (required)." })),
             session_mode: Type.Optional(strEnum("fresh")),
-            // The one-shot shorthand: a prompt is the whole delegation, and the
-            // fresh session in the caller's own directory is what it means.
             prompt: Type.Optional(Type.String()),
             cwd: Type.Optional(Type.String()),
             launch: Type.Optional(LaunchSchema),
             name: Type.Optional(Type.String()),
+            timeoutSeconds: Type.Optional(Type.Number({ description: "1–86400; defaults to 3600." })),
             task: Type.Optional(DraftSchema),
-            // The same draft again, spelled out, cost more tokens in every session
-            // than the whole rest of this contract. One copy is the guidance; this
-            // one points at it, and `parseDraft` is what actually validates either.
+            // Spelled out, the draft schema costs more tokens per session than the
+            // rest of this contract; `parseDraft` validates either shape.
             tasks: Type.Optional(Type.Unsafe({
                 type: "array",
-                description: "2+ entries, each a prompt string, {prompt, cwd?, launch?, name?}, a task draft shaped exactly like `task`, or {task_id}.",
+                description: "2+ entries, each a prompt string, {prompt, cwd?, launch?, name?, timeoutSeconds?}, a task draft shaped exactly like `task`, or {task_id}.",
                 items: { type: "object" },
             })),
             join: Type.Optional(strEnum("all", "first")),
@@ -187,15 +186,19 @@ export async function handleTaskTool(host, definitions, store, messages, raw, ca
         return definitions.update(requiredString(input.task_id, "task_id"), await expandDraft(definitions, input.task, callerSessionId));
     }
     if (input.operation === "run") {
-        // One reading of `callback` for both shapes below: a run and a fan-out
-        // choose the same way, and two readings are two things to keep in step.
         const callbackMode = input.callback === "steer" ? "steer" : "followUp";
+        // A run's own callback is its parent's link back; a child that could point
+        // it elsewhere would strand the supervisor waiting for a result.
+        if (active && input.callback_session_id !== undefined)
+            throw new Error(SUBAGENT_REDIRECT);
         if (Array.isArray(input.tasks)) {
             // Core-joined fan-out: members run detached, one aggregated callback.
             if (input.task !== undefined || input.task_id !== undefined)
                 throw new Error("use either task/task_id or tasks[]");
             if (input.session_mode !== undefined)
                 throw new Error("session_mode applies to a single run only");
+            if (input.callback_session_id !== undefined)
+                throw new Error("callback_session_id applies to a single run only");
             if (input.tasks.length < 2)
                 throw new Error("tasks[] needs at least 2 entries; use task for a single run");
             const resolved = [];
@@ -221,12 +224,7 @@ export async function handleTaskTool(host, definitions, store, messages, raw, ca
             throw new Error(`unsupported session_mode: ${String(input.session_mode)}`);
         }
         const sessionMode = input.session_mode;
-        let callbackSessionId = input.callback === "none" ? null : callerSessionId;
-        if (!active && callbackSessionId && typeof input.callback_session_id === "string") {
-            callbackSessionId = requiredString(input.callback_session_id, "callback_session_id");
-            if (!(await definitions.sessionExists(callbackSessionId)))
-                throw new Error(`unknown session: ${callbackSessionId}`);
-        }
+        const callbackSessionId = await callbackTarget(input, definitions, callerSessionId);
         const run = host.run(task.id, input.input, "agent", active?.id ?? null, {
             invokedBySessionId: callerSessionId,
             sourceSessionId: callerSessionId,
@@ -238,18 +236,14 @@ export async function handleTaskTool(host, definitions, store, messages, raw, ca
         return receipt(summarize(run, null), callbackSessionId, callbackMode, callerSessionId);
     }
     if (input.operation === "recover") {
-        // History only, never status: a result is readable here once its callback
-        // has said its last word, so nothing a caller could learn by asking is
-        // something it would not have been told. The reason is the friction — a
-        // caller states why the callback did not suffice, and the operator sees it.
+        // History only, never status: readable once the callback has said its last
+        // word. The required reason is the friction, and the operator sees it.
         const reason = requiredString(input.reason, "reason");
-        // A finished run with an open decision sends no completion callback — the
-        // question is the notification, and the reply's continuation reports.
+        // The open question is the notification; the reply's continuation reports.
         const decisionOpen = (run) => {
             throw new Error(`run ${run.id} finished awaiting your decision ${messages.openDecisionId(run.id) ?? ""}; reply to it — the continuation's callback brings the result`);
         };
-        // A member waits for its group's callback, but a race winner need not
-        // wait for losing members to finish cancelling before recovering its text.
+        // A race winner need not wait for losing members to finish cancelling.
         const groupReady = (group) => {
             if (!group.finishedAt || !settled(group))
                 notRecoverable(`group ${group.id}`, group);
@@ -302,13 +296,19 @@ export async function handleTaskTool(host, definitions, store, messages, raw, ca
     if (input.operation === "resume") {
         const prior = host.getRun(requiredString(input.run_id, "run_id"));
         assertOwns(store, callerSessionId, active, prior);
-        const callbackSessionId = input.callback === "none" ? null : callerSessionId;
+        // The resumed run is a new run, so it carries its own callback options,
+        // under the same rule as `run`: a subagent may not redirect them.
+        if (active && input.callback_session_id !== undefined)
+            throw new Error(SUBAGENT_REDIRECT);
+        const callbackMode = input.callback === "steer" ? "steer" : "followUp";
+        const callbackSessionId = await callbackTarget(input, definitions, callerSessionId);
         const run = host.resume(prior.id, requiredString(input.message, "message"), {
             invokedBySessionId: callerSessionId,
             callbackSessionId,
+            callbackMode,
             background: true,
         });
-        return receipt(summarize(run, null), callbackSessionId, "followUp", callerSessionId);
+        return receipt(summarize(run, null), callbackSessionId, callbackMode, callerSessionId);
     }
     if (input.operation === "contact") {
         if (!active)
@@ -327,28 +327,22 @@ export async function handleTaskTool(host, definitions, store, messages, raw, ca
 }
 /** A single run's draft: the top-level shorthand (`prompt` …) or `task`, never both. */
 function inlineDraft(input) {
-    const { prompt, cwd, launch, name } = input;
+    const { prompt, cwd, launch, name, timeoutSeconds } = input;
     if (prompt === undefined)
         return record(input.task) ?? undefined;
     if (input.task !== undefined)
         throw new Error("use either prompt or task");
-    return { prompt, cwd, launch, name };
+    return { prompt, cwd, launch, name, timeoutSeconds };
 }
-/** The prompt's first line, unmarked and cut short: a label for the Console,
- *  not an identifier — the run's id is what anything addresses. */
+/** A label for the Console, not an identifier. */
 function nameFromPrompt(prompt) {
     const line = prompt.split("\n")
         .map((l) => l.replace(/^[\s#>*-]+/, "").replace(/[*_`]/g, "").replace(/\s+/g, " ").trim())
         .find(Boolean) ?? "subagent";
     return line.length > 60 ? `${line.slice(0, 59).trimEnd()}…` : line;
 }
-/**
- * The shape a draft is validated in, from the shapes a caller may write it in.
- * A `prompt` shorthand becomes a fresh Agent action; a fresh session's cwd
- * resolves against the caller's own directory (and is that directory when
- * omitted); a missing name is the prompt's first line. Everything the caller
- * did spell out passes through untouched — parseDraft still judges it.
- */
+/** A `prompt` shorthand becomes a fresh Agent action in the caller's own
+ *  directory; everything the caller did spell out passes through to parseDraft. */
 async function expandDraft(definitions, raw, callerSessionId) {
     let draft = record(raw);
     if (!draft)
@@ -371,8 +365,8 @@ async function expandDraft(definitions, raw, callerSessionId) {
         draft = { ...draft, name: nameFromPrompt(action.prompt) };
     return draft;
 }
-/** Inline one-shot subagent: persisted like any task (kind "subagent",
- * filtered from default lists) so runs stay auditable and resumable. */
+/** Persisted like any task (kind "subagent", filtered from default lists) so
+ *  runs stay auditable and resumable. */
 async function resolveDraft(definitions, raw, active, callerSessionId) {
     const draft = record(await expandDraft(definitions, raw, callerSessionId));
     if (!draft)
@@ -380,6 +374,11 @@ async function resolveDraft(definitions, raw, active, callerSessionId) {
     if (draft.trigger !== undefined && record(draft.trigger)?.type !== "manual") {
         throw new Error("inline subagent tasks must use a manual trigger");
     }
+    // Delivery of a one-off run is the top-level fields' business; a nested
+    // callback only means anything on a stored definition's schedule.
+    if (draft.callback !== undefined || draft.callback_session_id !== undefined) {
+        throw new Error("an inline task draft cannot set callback; use the top-level callback / callback_session_id");
+    }
     if (active) {
         const action = record(draft.action);
         if (action?.type !== "agent")