@timqi/pier 0.0.17 → 0.0.20

package/dist/main.js

@@ -4,6 +4,9 @@ import { fileURLToPath } from "node:url";
 import { serve } from "@hono/node-server";
 import { Hono } from "hono";
 import { PiConfigStore } from "./agent/config.js";
+import { normalizeAgentSnapshot } from "./agent/config-sync.js";
+import { ConfigSync } from "./config-sync.js";
+import { configSyncTask } from "./config-sync-task.js";
 import { CredentialStore } from "./agent/credentials.js";
 import { PiAgentFactory } from "./agent/pi.js";
 import { defaultBoardsDir, registerBoardRoutes } from "./boards/boards.js";
@@ -35,6 +38,7 @@ import { startUpdate, unitPath, updaterProblem } from "./service.js";
 import { SettingsStore } from "./settings.js";
 import { startAutoUpdate, UpdateCheck } from "./update.js";
 import { AuthStore, registerAuthRoutes, requireAuth } from "./web/auth.js";
+import { registerConfigShareRoute, registerConfigSyncRoutes } from "./web/config-sync.js";
 import { PushStore, registerPushRoutes } from "./web/push.js";
 import { SessionStateStore } from "./web/session-state.js";
 import { createServer } from "./web/server.js";
@@ -86,7 +90,12 @@ let channelStore;
 // Shared by the adapter and the tool: a display name is looked up once per
 // process, not once per message and again per transcript.
 const slackDirectory = new SlackDirectory((m) => logger("slack").warn(m));
+let readyForConfigReload = false;
 const piConfig = new PiConfigStore();
+const configSync = new ConfigSync({
+    db, settings, config: piConfig, normalizeAgent: normalizeAgentSnapshot,
+    reload: () => readyForConfigReload ? reloadInstance() : Promise.resolve(),
+});
 const factory = new PiAgentFactory([
     taskToolSpec((params, callerSessionId) => tasks.tool(params, callerSessionId)),
     slackToolSpec((params, callerSessionId) => handleSlackTool({
@@ -143,8 +152,9 @@ const router = new Router(hub, (key) => {
 const stopEviction = router.startIdleEviction();
 tasks = new TaskService(new TaskStore(db), factory, router, hub, {
     modelMenu: () => settings.get().modelMenu,
+    systemActions: { "config-sync": (signal) => configSync.sync(signal) },
 });
-tasks.start();
+const configurationSync = configSyncTask(tasks, configSync);
 // The managed CLI tools (src/tools.ts), and the daily task that keeps them
 // current (src/tools-task.ts) — an ordinary bash task on an ordinary cron,
 // wired here because tools.ts may not import tasks/.
@@ -181,6 +191,19 @@ const reloadInstance = async (includeWatched = false) => {
     await channels.reload();
     return router.evictIdle(0, Date.now(), { includeWatched });
 };
+// Bound the startup check before sessions and scheduled work can start.
+// Remote outages keep the last local configuration available.
+if (configSync.status().enabled) {
+    try {
+        await configSync.sync();
+    }
+    catch {
+        log.error("Startup configuration sync failed; using the last local configuration");
+    }
+}
+await configurationSync.reconcile();
+tasks.start();
+readyForConfigReload = true;
 void secrets.unlock().then(startChannels, (err) => log.error("secrets locked — channels not started; unlock from Console → Settings → Security, or repair master.key", err));
 // Replacing Pier is systemd's job, not this process's: the oneshot unit stops
 // the service, snapshots the database, installs and starts it again. Without
@@ -289,8 +312,15 @@ app.onError((err, c) => {
 // so a surface added later is covered without knowing this exists. Built
 // before the listener: a first run generates and prints its password here.
 const auth = new AuthStore(db);
+registerConfigShareRoute(app, configSync);
 app.use("*", requireAuth(auth));
 registerAuthRoutes(app, auth);
+registerConfigSyncRoutes(app, {
+    sync: configSync,
+    status: () => ({ ...configurationSync.status(), publicUrl: settings.get().publicUrl }),
+    reconcile: configurationSync.reconcile,
+    run: configurationSync.run,
+});
 registerTaskRoutes(app, tasks, { factory, router });
 registerChannelRoutes(app, channelStore, channels);
 registerBoardRoutes(app);
@@ -345,6 +375,7 @@ app.route("/", createServer({
     onUnlocked: () => void startChannels(),
     reload: () => reloadInstance(true),
     backgroundRuns: (id) => tasks.backgroundRuns(id),
+    activeBackgroundRunCounts: () => tasks.activeBackgroundRunCounts(),
     channelOf: (id) => conversations.channelOf(id),
 }));
 const port = Number(process.env.PORT ?? 3141);

package/dist/secrets.js

@@ -119,6 +119,15 @@ export class Secrets {
         this.#file = next;
         log.info(`KEK rotated (${mode} mode, dek ${file.dekId} unchanged)`);
     }
+    /**
+     * What vt says about itself. A refused or impossible unlock is almost never
+     * Pier's fault — missing binary, no agent listening, config pointing
+     * elsewhere — and `lockedReason` only carries the last error. Read-only, so
+     * it is safe to run while locked; vt's own report is the repair instruction.
+     */
+    doctor() {
+        return this.vt.doctor();
+    }
     /** First boot: random KEK and DEK, file mode. */
     #create() {
         const kek = randomBytes(KEY_BYTES);
@@ -172,20 +181,23 @@ export const vtCli = {
             throw new Error("vt create printed no vt:// record");
         return record;
     },
+    // Bounded: doctor probes an agent socket and a worker over the network, and
+    // a hung probe would leave the Console waiting on a diagnosis forever.
+    doctor: () => run("vt", ["doctor"], undefined, 15_000),
 };
-function run(cmd, args, stdin) {
+function run(cmd, args, stdin, timeoutMs) {
     return new Promise((resolvePromise, reject) => {
-        const child = spawn(cmd, args, { stdio: ["pipe", "pipe", "pipe"] });
+        const child = spawn(cmd, args, { stdio: ["pipe", "pipe", "pipe"], timeout: timeoutMs });
         let out = "";
         let err = "";
         child.stdout.on("data", (d) => (out += d.toString()));
         child.stderr.on("data", (d) => (err += d.toString()));
         child.on("error", reject);
-        child.on("close", (code) => {
+        child.on("close", (code, signal) => {
             if (code === 0)
-                resolvePromise(out.trim());
-            else
-                reject(new Error(`${cmd} ${args[0]} exited ${code}: ${err.trim() || out.trim()}`));
+                return resolvePromise(out.trim());
+            const how = signal ? `timed out after ${timeoutMs}ms (${signal})` : `exited ${code}`;
+            reject(new Error(`${cmd} ${args[0]} ${how}: ${err.trim() || out.trim()}`));
         });
         child.stdin.on("error", reject); // EPIPE if vt exits before reading
         if (stdin !== undefined)

package/dist/tasks/agent.js

@@ -1,4 +1,4 @@
-// A run that *is* a Pi session: which session it opens (reuse, fresh, fork),
+// A run that *is* a Pi session: which session it opens (fresh or reused),
 // what the child is told before the prompt, and how many may run at once. The
 // concurrency caps are here rather than in execution.ts because they bound
 // agents specifically — a bash run costs a process, an agent run costs a
@@ -52,7 +52,7 @@ export class AgentTaskRunner {
                 await this.waitUntilIdle(session, signal);
                 // Task requests come seconds apart — the 1h Anthropic cache-write premium
                 // never earns its 2× back, so task runs use the 5m TTL. Set here, not in
-                // resolveSession: this covers create, fork, reuse and resume alike, on
+                // resolveSession: this covers create, reuse and resume alike, on
                 // every attempt — and only after the session is idle, so a reused
                 // interactive session's in-flight turn keeps its 1h writes.
                 session.setCacheRetention("short");
@@ -74,9 +74,17 @@ export class AgentTaskRunner {
                 run.context.renderedPrompt = prompt;
                 this.store.saveRun(run);
                 let text = "";
+                // Not only what the turn said but how it ended: a provider outage ends
+                // it with an empty reply, and a run that settles on that reports "no
+                // reply" — the one wording for a turn that *chose* to say nothing, so
+                // the outage arrives at the caller looking like an answer (§5b). Pi has
+                // already retried by the time this lands; the run only reports.
+                let failure;
                 const unsubscribe = session.subscribe((event) => {
-                    if (event.type === "turn-end")
+                    if (event.type === "turn-end") {
                         text = event.text;
+                        failure = event.error;
+                    }
                 });
                 // The race below also settles this attempt if Pi ignores the abort:
                 // a hung turn must not hold one of the 4 slots (and its waiters)
@@ -106,6 +114,11 @@ export class AgentTaskRunner {
                     await Promise.race([turn, abortedTurn]);
                     if (signal.aborted)
                         throw new Error("cancelled");
+                    // Before the fallback below: on a reused session that reads the
+                    // *previous* turn's answer back out of history and reports it as
+                    // this run's result.
+                    if (failure)
+                        throw new Error(failure);
                     if (!text) {
                         const history = await session.history();
                         text = [...history].reverse().find((turn) => turn.role === "assistant")?.text ?? "";
@@ -136,25 +149,16 @@ export class AgentTaskRunner {
         if (run.targetSessionId) {
             return this.router.ensure({ channelId: "task", conversationId: run.targetSessionId });
         }
-        const source = run.sourceSessionId
-            ? await this.factory.find(run.sourceSessionId)
-            : undefined;
         const policy = action.session;
-        let cwd;
-        if (run.sessionMode === "fork") {
-            if (!run.sourceSessionId)
-                throw new Error("fork requires a source session");
-            cwd = policy.mode === "fork" && policy.cwd ? policy.cwd : source?.cwd ?? "";
-        }
-        else if (policy.mode === "fresh") {
-            cwd = policy.cwd;
-        }
-        else if (policy.mode === "reuse") {
-            cwd = (await this.factory.find(policy.sessionId))?.cwd ?? "";
-        }
-        else {
-            cwd = policy.cwd ?? source?.cwd ?? "";
+        // Definitions stored before fork was removed still say `"fork"`. Refused by
+        // name: every directory this could pick instead is a guess at what the
+        // author meant, and a child in the wrong tree edits real files.
+        if (run.sessionMode === "fork" || policy.mode === "fork") {
+            throw new Error(`task "${run.context.definition.name}" uses the removed fork session mode; recreate it with {"mode":"fresh","cwd":"/abs/path"}`);
         }
+        const cwd = policy.mode === "fresh"
+            ? policy.cwd
+            : (await this.factory.find(policy.sessionId))?.cwd ?? "";
         if (!cwd)
             throw new Error("could not resolve child working directory");
         const opts = {
@@ -166,9 +170,7 @@ export class AgentTaskRunner {
                 (run.sourceSessionId ? this.router.modelOf(run.sourceSessionId) : undefined),
             thinking: action.launch?.thinking,
         };
-        const session = run.sessionMode === "fork"
-            ? await this.factory.fork(run.sourceSessionId, opts)
-            : await this.factory.create(opts);
+        const session = await this.factory.create(opts);
         run.targetSessionId = session.id;
         run.context.sessionId = session.id;
         run.context.cwd = cwd;

package/dist/tasks/callbacks.js

@@ -19,7 +19,7 @@ export const runSource = (run) => ({
 });
 export function runResultText(run) {
     let result = run.error ?? "No result";
-    if (run.result?.type === "agent")
+    if (run.result?.type === "agent" || run.result?.type === "system")
         result = run.result.text;
     if (run.result?.type === "bash")
         result = run.result.stdout || run.result.stderr || `exit ${String(run.result.exitCode)}`;

package/dist/tasks/definitions.js

@@ -127,11 +127,13 @@ export class TaskDefinitions {
     factory;
     router;
     hub;
-    constructor(store, factory, router, hub) {
+    systemActions;
+    constructor(store, factory, router, hub, systemActions = {}) {
         this.store = store;
         this.factory = factory;
         this.router = router;
         this.hub = hub;
+        this.systemActions = systemActions;
     }
     list() { return this.store.listTasks(); }
     get(id) {
@@ -145,7 +147,7 @@ export class TaskDefinitions {
         // means manual. Update keeps requiring it: replacing a cron task with a
         // draft that forgot its trigger must not silently unschedule it.
         const value = record(raw);
-        const draft = await this.parseDraft(value && value.trigger === undefined ? { ...value, trigger: { type: "manual" } } : raw);
+        const draft = await this.parseDraft(value && value.trigger === undefined ? { ...value, trigger: { type: "manual" } } : raw, creator);
         const now = Date.now();
         const task = {
             id: newId(),
@@ -176,7 +178,7 @@ export class TaskDefinitions {
         this.assertOwner(old, by, "edited");
         if (old.archived)
             throw new Error("archived tasks cannot be edited");
-        const draft = await this.parseDraft(raw);
+        const draft = await this.parseDraft(raw, ownerOf(old) ? by : undefined);
         const now = Date.now();
         const task = {
             ...old,
@@ -228,7 +230,9 @@ export class TaskDefinitions {
     }
     claimDue(now) {
         const due = [];
-        for (const task of this.store.listTasks()) {
+        // The store narrows to the tasks with a next run at or before `now`; the
+        // JSON is still the record, so its own fields decide.
+        for (const task of this.store.listDueTasks(now)) {
             if (!task.enabled || task.archived || task.nextRunAt === null || task.nextRunAt > now)
                 continue;
             task.nextRunAt = nextRunAt(task.trigger, now);
@@ -250,7 +254,17 @@ export class TaskDefinitions {
             throw new Error(`"${task.name}" is Pier's own ${owner} task: it is reconciled by Pier, not ${what}`);
         }
     }
-    async parseDraft(raw) {
+    /** Checked again at execution: persisted definitions can outlive registration. */
+    systemAction(name, owner) {
+        if (!owner || owner === "http" || owner.startsWith("session:") || owner !== name) {
+            throw new Error(`system action "${name}" requires its trusted owner`);
+        }
+        if (!Object.hasOwn(this.systemActions, name) || typeof this.systemActions[name] !== "function") {
+            throw new Error(`unregistered system action: ${name}`);
+        }
+        return this.systemActions[name];
+    }
+    async parseDraft(raw, owner) {
         const value = record(raw);
         if (!value)
             throw new Error("task definition required");
@@ -277,8 +291,13 @@ export class TaskDefinitions {
             this.get(taskId);
             action = { type: "task", taskId };
         }
+        else if (actionRaw.type === "system") {
+            const name = requiredString(actionRaw.name, "system action name");
+            this.systemAction(name, owner);
+            action = { type: "system", name };
+        }
         else if (actionRaw.type === "agent") {
-            action = await this.parseAgentAction(actionRaw, trigger);
+            action = await this.parseAgentAction(actionRaw);
         }
         else
             throw new Error("unknown action type");
@@ -292,7 +311,7 @@ export class TaskDefinitions {
             timeoutSeconds,
         };
     }
-    async parseAgentAction(raw, trigger) {
+    async parseAgentAction(raw) {
         const prompt = requiredString(raw.prompt, "agent prompt");
         const launch = parseLaunch(raw.launch);
         const input = record(raw.session);
@@ -308,21 +327,13 @@ export class TaskDefinitions {
             await this.assertDirectory(cwd);
             session = { mode: "fresh", cwd };
         }
-        else if (input?.mode === "fork") {
-            if (trigger.type !== "manual")
-                throw new Error("fork Agent tasks must use a manual trigger");
-            const cwd = typeof input.cwd === "string" && input.cwd.trim() ? input.cwd.trim() : undefined;
-            if (cwd)
-                await this.assertDirectory(cwd);
-            session = { mode: "fork", ...(cwd ? { cwd } : {}) };
-        }
         else {
             // Validation never mutates: a dedicated session is created explicitly
             // (POST /api/sessions) and then referenced with mode:"reuse".
-            throw new Error('agent session policy required, e.g. {"mode":"fresh","cwd":"/abs/path"} or {"mode":"fork"} or {"mode":"reuse","sessionId":"..."}');
+            throw new Error('agent session policy required, e.g. {"mode":"fresh","cwd":"/abs/path"} or {"mode":"reuse","sessionId":"..."}');
         }
         if (session.mode === "reuse" && launch)
-            throw new Error("launch policy only applies to fresh or fork sessions");
+            throw new Error("launch policy only applies to fresh sessions");
         return { type: "agent", session, prompt, ...(launch ? { launch } : {}) };
     }
     async parseCallback(raw) {

package/dist/tasks/execution.js

@@ -1,7 +1,7 @@
 // One queued run carried to a result: dispatched by action kind (a bash
-// script, an agent session, another task), abortable while it goes, settled
-// exactly once. What the two action kinds actually do lives in command.ts and
-// agent.ts; this file owns only the lifecycle they share.
+// script, an agent session, another task or an owned system action), abortable
+// while it goes, settled exactly once. Command and agent work lives in
+// command.ts and agent.ts; this file owns the lifecycle they share.
 import { logger } from "../log.js";
 import { AgentTaskRunner } from "./agent.js";
 import { TaskCallbacks } from "./callbacks.js";
@@ -125,6 +125,14 @@ export class TaskExecution {
             }
             return output;
         }
+        if (action.type === "system") {
+            this.markRunning(run);
+            const handler = this.definitions.systemAction(action.name, run.context.definition.creator);
+            signal.throwIfAborted();
+            const text = await handler(signal);
+            signal.throwIfAborted();
+            return { type: "system", text };
+        }
         if (action.type === "task") {
             this.markRunning(run);
             const child = this.host.runChild(action.taskId, run);

package/dist/tasks/messages.js

@@ -84,8 +84,7 @@ export class TaskMessenger {
      * `inject` dedupes on the recipient transcript, so a retry cannot double
      * deliver. Controls aimed at a finished run are dead and expire here. */
     retryUndelivered(now = Date.now()) {
-        for (const message of this.store.listUndeliveredMessages()) {
-            const run = this.store.getRun(message.runId);
+        for (const { message, run } of this.store.listUndeliveredMessages()) {
             if (!run)
                 continue;
             // Expiring a dead control is not a retry, so it ignores the backoff.
@@ -96,6 +95,30 @@ export class TaskMessenger {
                 this.changed(message);
                 continue;
             }
+            // A reply that resumed a terminal run was never a system input: its text
+            // is the continuation's prompt, so the transcript read below would find
+            // nothing and re-inject a second copy, starting a turn no run owns. The
+            // continuation is the proof instead. `startedAt` is written one statement
+            // before the prompt reaches the session (agent.ts), so `delivered` here
+            // means "handed to the run that reports for it" — a `systemInput` that
+            // then throws fails *that* run, and the failure reaches the replier
+            // through its callback.
+            if (message.kind === "reply" && isTerminal(run.state)) {
+                const resumed = message.resumeRunId ? this.store.getRun(message.resumeRunId) : undefined;
+                if (resumed?.startedAt)
+                    this.confirmed(message.id);
+                else if (!resumed)
+                    this.abandon(message, `continuation ${message.resumeRunId ?? "(none)"} is gone`);
+                else if (isTerminal(resumed.state)) {
+                    // Never started, and never will: say so rather than wait for a
+                    // ceiling that would only report the same thing four minutes later.
+                    // Both ends hear it here; the supervisor may also get the
+                    // continuation's own cancelled callback, and a duplicate beats a
+                    // special case that could suppress the only report either gets.
+                    this.abandon(message, `continuation ${resumed.id} ${resumed.state} before it started`);
+                }
+                continue;
+            }
             if ((message.nextAttemptAt ?? 0) > now)
                 continue;
             const target = message.toSessionId || run.targetSessionId;
@@ -149,9 +172,11 @@ export class TaskMessenger {
             this.deliver(reply, run, run.targetSessionId);
         }
         else if (isTerminal(run.state)) {
-            this.resumeRun(run.id, this.format(reply, run), fromSessionId);
-            reply.state = "delivered";
-            reply.deliveredAt = Date.now();
+            // Creating the continuation is not delivering the reply: the run is
+            // queued, and a restart or a cancel before it starts loses the prompt
+            // that carries the text. So the id is recorded and the sweep below
+            // settles it against the continuation's own `startedAt`.
+            reply.resumeRunId = this.resumeRun(run.id, this.format(reply, run), fromSessionId).id;
             this.store.saveMessage(reply);
             this.changed(reply);
         }
@@ -209,6 +234,17 @@ export class TaskMessenger {
         this.store.saveMessage(message);
         this.changed(message);
     }
+    /** Waiting is not a failed attempt: the message is in flight or the turn it
+     *  has to wait for is still running, so it is tried again shortly and the
+     *  ceiling is left for the deliveries that actually failed (the rule
+     *  outbox.ts keeps for callbacks). */
+    defer(id) {
+        const message = this.store.getMessage(id);
+        if (!message || message.state !== "pending")
+            return;
+        message.nextAttemptAt = Date.now() + 1000;
+        this.store.saveMessage(message);
+    }
     /** Counts one hand-off and says whether it may happen: a recipient that
      *  never records the message must not be re-sent once a second forever.
      *  False means the ceiling was reached and the message is now expired. */
@@ -248,10 +284,12 @@ export class TaskMessenger {
             this.store.saveRun(run);
         }
     }
-    /** A decision steers — a follow-up would land only after the supervisor runs
-     * out of tool calls, leaving the child waiting out the whole turn. */
+    /** Steer whatever someone is blocked on: a decision, and the reply that
+     * answers it — a follow-up lands only once the recipient runs out of tool
+     * calls, so each would wait out a whole turn (the reply waited 3 minutes
+     * behind one on 2026-09-07). Progress is a follow-up because nobody waits. */
     mode(message) {
-        return message.kind === "steer" || message.kind === "decision" ? "steer" : "follow_up";
+        return message.kind === "follow_up" || message.kind === "progress" ? "follow_up" : "steer";
     }
     failed(id, error, spent) {
         const message = this.store.getMessage(id);
@@ -286,14 +324,13 @@ export class TaskMessenger {
             const recorded = async () => (await session.history()).some((turn) => turn.role === "system" && turn.origin?.kind === "task-message" && turn.origin.messageId === message.id);
             if (await recorded())
                 return this.confirmed(message.id);
-            // Accepted and waiting in Pi's queue for the running turn to drain it:
-            // not recorded yet, and sending again would deliver the same steer twice.
-            // Unlike a callback this is not deferred — a steer's whole point is to
-            // reach the turn already running — so the queue is where it sits, and
-            // waiting for it to drain costs no attempt.
-            const queue = await session.pendingQueue();
-            if ([...queue.steering, ...queue.followUp].some((text) => text.includes(message.id)))
-                return;
+            // Accepted and waiting in the recipient's queue for the running turn to
+            // drain it: not recorded yet, and sending again would deliver the same
+            // guidance twice. Unlike a callback this is not deferred on a busy
+            // target — a steer's whole point is to reach the turn already running —
+            // so the queue is where it sits, and waiting for it costs no attempt.
+            if (await this.queued(session, message.id))
+                return this.defer(message.id);
             spent = this.spend(message.id);
             if (!spent)
                 return;
@@ -305,6 +342,11 @@ export class TaskMessenger {
             this.failed(message.id, error, spent);
         }
     }
+    /** In the recipient's queue, by the id its origin carries — the transcript
+     *  read above answers "landed", this answers "handed over and waiting". */
+    async queued(session, id) {
+        return (await session.pendingSystemInputs()).some((origin) => origin.kind === "task-message" && origin.messageId === id);
+    }
     format(message, run) {
         const title = run.context.definition.name;
         if (message.kind === "progress") {

package/dist/tasks/routes.js

@@ -3,6 +3,47 @@
 // its body, names the caller and hands the decision to TaskService — policy
 // that lives here would be policy the task tool does not get.
 import { record, requiredString } from "./definitions.js";
+/** Reject malformed filters instead of silently widening a global query. */
+function runQuery(params) {
+    const query = {};
+    const states = ["queued", "running", "succeeded", "failed", "cancelled", "interrupted", "skipped"];
+    const sources = ["manual", "cron", "watch", "agent", "task"];
+    if (params.state) {
+        if (!states.includes(params.state))
+            throw new Error("invalid state");
+        query.state = params.state;
+    }
+    if (params.source) {
+        if (!sources.includes(params.source))
+            throw new Error("invalid source");
+        query.source = params.source;
+    }
+    if (params.taskId)
+        query.taskId = params.taskId;
+    for (const key of ["since", "until", "limit"]) {
+        if (params[key] === undefined)
+            continue;
+        const value = Number(params[key]);
+        if (!params[key] || !Number.isSafeInteger(value) || value < 0 || (key === "limit" && (value < 1 || value > 200)))
+            throw new Error(`invalid ${key}`);
+        query[key] = value;
+    }
+    if (query.since !== undefined && query.until !== undefined && query.since > query.until)
+        throw new Error("since exceeds until");
+    if (params.showUnmatched !== undefined) {
+        if (!["true", "false"].includes(params.showUnmatched))
+            throw new Error("invalid showUnmatched");
+        query.showUnmatched = params.showUnmatched === "true";
+    }
+    if (params.cursor) {
+        const cursor = JSON.parse(params.cursor);
+        const value = record(cursor);
+        if (!value || !Number.isSafeInteger(value.queuedAt) || Number(value.queuedAt) < 0 || typeof value.id !== "string" || !value.id)
+            throw new Error("invalid cursor");
+        query.cursor = { queuedAt: Number(value.queuedAt), id: value.id };
+    }
+    return query;
+}
 const jsonBody = async (req) => req.json().catch(() => null);
 export function registerTaskRoutes(app, tasks, activity) {
     if (activity)
@@ -50,13 +91,21 @@ export function registerTaskRoutes(app, tasks, activity) {
                 messages,
             });
         });
+    app.get("/api/task-runs", (c) => {
+        try {
+            return c.json(tasks.queryRuns(runQuery(c.req.query())));
+        }
+        catch (err) {
+            return c.json({ error: String(err) }, 400);
+        }
+    });
     app.get("/api/tasks", (c) => {
         const trigger = c.req.query("trigger");
         const state = c.req.query("state");
         const kind = c.req.query("kind");
         let rows = tasks.list();
         // Subagent one-shots are hidden unless explicitly requested via ?kind=subagent.
-        rows = kind ? rows.filter((task) => task.kind === kind) : rows.filter((task) => task.kind !== "subagent");
+        rows = rows.filter((task) => task.kind === (kind ?? "task"));
         if (trigger)
             rows = rows.filter((task) => task.trigger.type === trigger);
         if (state === "archived")
@@ -93,10 +142,7 @@ export function registerTaskRoutes(app, tasks, activity) {
     });
     app.get("/api/task-runs/:id", (c) => {
         try {
-            const run = tasks.getRun(c.req.param("id"));
-            // Same view as the task tool: a pending decision is the one run fact that
-            // lives on the messages, and HTTP callers need it too.
-            return c.json({ ...run, pendingDecisionId: tasks.openDecisionId(run.id) });
+            return c.json(tasks.getRunView(c.req.param("id")));
         }
         catch (err) {
             return c.json({ error: String(err) }, 404);
@@ -181,13 +227,15 @@ export function registerTaskRoutes(app, tasks, activity) {
         const body = record(await jsonBody(c.req));
         const input = body && "input" in body ? body.input : null;
         try {
-            const sessionMode = body?.sessionMode === "fresh" || body?.sessionMode === "fork" ? body.sessionMode : undefined;
+            // A caller that names a mode gets an answer about it: dropping an
+            // unsupported override would run the definition's own policy instead —
+            // on a reuse definition, work injected into a live session.
+            if (body?.sessionMode !== undefined && body.sessionMode !== "fresh") {
+                throw new Error(`unsupported sessionMode: ${String(body.sessionMode)}`);
+            }
+            const sessionMode = body?.sessionMode;
             const sourceSessionId = typeof body?.sourceSessionId === "string" && body.sourceSessionId ? body.sourceSessionId : null;
             const task = tasks.get(c.req.param("id"));
-            const effectiveMode = task.action.type === "agent" ? sessionMode ?? task.action.session.mode : null;
-            if (effectiveMode === "fork" && (!sourceSessionId || !(await tasks.sessionExists(sourceSessionId)))) {
-                throw new Error("fork requires a known sourceSessionId");
-            }
             return c.json({ runId: tasks.run(task.id, input, "manual", null, {
                     invokedBySessionId: sourceSessionId,
                     sourceSessionId,

package/dist/tasks/runs.js

@@ -38,11 +38,6 @@ export class TaskRunQueue {
         const sessionMode = definition.action.type === "agent"
             ? provenance.sessionMode ?? definition.action.session.mode
             : null;
-        if (sessionMode === "fork" && !sourceSessionId)
-            throw new Error("fork requires a source session");
-        if (sessionMode === "fork" && (source === "cron" || source === "watch")) {
-            throw new Error("scheduled and watch runs cannot fork a caller session");
-        }
         const targetSessionId = provenance.targetSessionId ?? (definition.action.type === "agent" && sessionMode === "reuse" && definition.action.session.mode === "reuse"
             ? definition.action.session.sessionId
             : null);