@timqi/pier 0.1.14 → 0.2.0

package/dist/main.js

@@ -15,18 +15,19 @@ import { defaultBoardsDir, registerBoardRoutes, rotateBoardViews } from "./board
 import { ChannelStore } from "./channels/config.js";
 import { createControl } from "./channels/control.js";
 import { ConversationStore, resolveConversation } from "./channels/conversations.js";
-import { createHandoff } from "./channels/handoff.js";
 import { registerChannelRoutes } from "./channels/routes.js";
 import { ChannelRuntime } from "./channels/runtime.js";
+import { MainChain } from "./core/chain.js";
 import { EventHub } from "./core/hub.js";
 import { splitSpeaker } from "./core/identity.js";
 import { pierDb } from "./db.js";
 import { deliverLedger, drainForRestart, RestartLedger } from "./drain.js";
-import { surfacePrompt } from "./core/reply.js";
+import { surfacePrompt } from "./agent/roles.js";
 import { Router } from "./core/router.js";
 import { acquireInstanceLock } from "./lock.js";
 import { parseWebParams, runWeb } from "./websearch/run.js";
 import { logger } from "./log.js";
+import { openItemsStatus } from "./tasks/open-items.js";
 import { registerTaskRoutes } from "./tasks/routes.js";
 import { TaskService } from "./tasks/service.js";
 import { TaskStore } from "./tasks/store.js";
@@ -92,6 +93,7 @@ const configSync = new ConfigSync({
     reload: () => readyForConfigReload ? reloadInstance() : Promise.resolve(),
 });
 const skillsDir = fileURLToPath(new URL("../skills", import.meta.url));
+const taskStore = new TaskStore(db);
 const factory = new PiAgentFactory(
 // Getters, read per session open: a Console change reaches the next session
 // without a restart.
@@ -99,7 +101,7 @@ const factory = new PiAgentFactory(
 // Documents Pier's own tools, so it loads only inside a Pier session.
 [skillsDir], new CredentialStore(db, secrets), piConfig, () => settings.get().modelMenu, () => settings.get(), () => settings.get().titleModel, 
 // Transcripts carry the speaker header core wrote for the model.
-new IndexedListing(undefined, undefined, (text) => splitSpeaker(text).text));
+new IndexedListing(undefined, undefined, (text) => splitSpeaker(text).text), (id) => taskStore.roleOf(id));
 const hub = new EventHub();
 const router = new Router(hub, (key) => {
     // Web conversation ids are session ids; an IM id is a chat, resolved through
@@ -108,11 +110,28 @@ const router = new Router(hub, (key) => {
         return factory.resume(key.conversationId);
     }
     return resolveIm(key);
-}, (key) => conversations.get(key), (id) => conversations.keyOf(id));
+}, (key) => conversations.get(key), (id) => chatKeyOf(id));
+const chain = new MainChain(db, {
+    factory, router, home: pierPath("home"),
+    ledger: (ids, since) => tasks.ledger(ids, since),
+    status: (now) => openItemsStatus(tasks.openItems(now), now),
+    defaults: () => piConfig.readDefaults(),
+});
 const stopEviction = router.startIdleEviction();
-tasks = new TaskService(new TaskStore(db), factory, router, hub, {
+tasks = new TaskService(taskStore, factory, router, hub, {
     modelMenu: () => settings.get().modelMenu,
-    systemActions: { "config-sync": (signal) => configSync.sync(signal) },
+    systemActions: {
+        // A schema gap pauses the subscription mid-run; the task's own switch follows it.
+        "config-sync": async (signal) => {
+            try {
+                return await configSync.sync(signal);
+            }
+            finally {
+                await configurationSync.reconcile();
+            }
+        },
+    },
+    continuous: chain,
 });
 const configurationSync = configSyncTask(tasks, configSync);
 const managedTools = new ManagedTools();
@@ -130,24 +149,17 @@ const control = createControl({
     router, factory, conversations, store: channelStore,
     modelMenu: () => settings.get().modelMenu,
 });
-// The panel pulls through the handoff and the handoff posts through the
-// runtime: the runtime's half is reached lazily so both can be built.
-const handoff = createHandoff({
-    store: channelStore,
-    runtime: {
-        running: () => channels.running(),
-        openThread: (platform, chatId, note) => channels.openThread(platform, chatId, note),
-    },
-    conversations,
-    factory,
-    router,
-    hub,
-    publicUrl: () => settings.get().publicUrl,
-    taskSessions: () => tasks.taskSessions(),
-    workingSet: () => sessionState.flags(),
-    log: (m) => logger("channels").info(m),
-});
-const channels = new ChannelRuntime(channelStore, router, control, handoff);
+const channels = new ChannelRuntime(channelStore, router, chain, control);
+/** The head answers in the home chat while its adapter runs (docs/design/11), else on
+ *  the web with Web Push; an older member gets no home key, or an adapter's start
+ *  would re-key it over the head. Any other session: its conversations row. */
+function chatKeyOf(sessionId) {
+    const home = channelStore.home();
+    if (home && channels.live(home.platform) && chain.chainOf(sessionId)?.[0] === sessionId) {
+        return { channelId: home.platform, conversationId: home.chatId };
+    }
+    return conversations.keyOf(sessionId);
+}
 resolveIm = resolveConversation(conversations, factory, control.launchFor, (key, message) => {
     logger("channels").warn(`${key.channelId}:${key.conversationId} ${message}`);
     void channels.notify(key.channelId, key.conversationId, message)
@@ -169,16 +181,8 @@ const reloadInstance = async (includeWatched = false) => {
     await channels.reload();
     return router.evictIdle(0, Date.now(), { includeWatched });
 };
-// Remote outages keep the last local configuration available.
-if (configSync.status().enabled) {
-    // sync() already logged the cause; this line says what the boot did about it.
-    try {
-        await configSync.sync();
-    }
-    catch {
-        log.error("Startup configuration sync failed; using the last local configuration");
-    }
-}
+// No sync at boot: a restart is not a reason to replace the configuration;
+// the owned task's next check is.
 await configurationSync.reconcile();
 tasks.start();
 readyForConfigReload = true;
@@ -278,8 +282,8 @@ registerConfigSyncRoutes(app, {
     reconcile: configurationSync.reconcile,
     run: configurationSync.run,
 });
-registerTaskRoutes(app, tasks, { factory, router });
-registerChannelRoutes(app, channelStore, channels, handoff, conversations);
+registerTaskRoutes(app, tasks);
+registerChannelRoutes(app, channelStore, channels, conversations);
 registerVaultRoutes(app, { vault, doctor: () => secrets.doctor() });
 registerBoardRoutes(app);
 registerPushRoutes(app, {
@@ -299,6 +303,7 @@ app.route("/", createServer({
     packages,
     providers: factory,
     settings,
+    subscribed: () => configSync.status().enabled,
     // Assembled here: the catalog spawns ubix, which web/ may not.
     catalog: async () => {
         const { tools, customTools } = settings.get();
@@ -320,8 +325,12 @@ app.route("/", createServer({
     reload: () => reloadInstance(true),
     backgroundRuns: (id) => tasks.backgroundRuns(id),
     activeBackgroundRunCounts: () => tasks.activeBackgroundRunCounts(),
+    parkedMessages: (id) => tasks.parkedMessages(id),
     taskSessions: () => tasks.taskSessions(),
-    channelOf: (id) => conversations.keyOf(id)?.channelId,
+    leads: () => taskStore.leads(),
+    openItems: () => tasks.openItems(),
+    channelOf: (id) => chatKeyOf(id)?.channelId,
+    continuous: chain,
 }));
 const port = Number(process.env.PORT ?? 3141);
 const hostname = process.env.HOST ?? "127.0.0.1";

package/dist/settings.js

@@ -1,6 +1,6 @@
 // Instance settings: the facts about *this* Pier that are neither a credential
 // nor per-session. A key-value table, so the next setting is not the next table.
-import { isThinkingLevel } from "./core/types.js";
+import { isModelTier, isThinkingLevel, MODEL_TIERS, THINKING_LEVELS } from "./core/types.js";
 import { pierDb, transact } from "./db.js";
 import { logger } from "./log.js";
 import { normalizeCustomTools } from "./tools.js";
@@ -48,29 +48,33 @@ export function normalizePublicUrl(raw) {
     return `${url.origin}${url.pathname}`.replace(/\/+$/, "");
 }
 /** Rejecting rather than repairing: a "fixed" entry would advertise a model the
- *  operator never picked. Notes are capped; every session pays for their tokens. */
-export function normalizeModelMenu(raw) {
-    if (!Array.isArray(raw) || raw.length > 32)
-        return null;
+ *  operator never picked. The refusal names the row (1-based, as the Console
+ *  lists them) and the field. A `note` left by an older Pier is dropped. One
+ *  model may be pinned at several levels; the same model at the same level twice
+ *  is refused, naming both rows. */
+export function parseModelMenu(raw) {
+    if (!Array.isArray(raw))
+        return "modelMenu must be a list";
+    if (raw.length > 32)
+        return `modelMenu has ${String(raw.length)} rows; at most 32`;
     const menu = [];
-    for (const item of raw) {
+    for (const [i, item] of raw.entries()) {
+        const row = `modelMenu row ${String(i + 1)}`;
         const ref = normalizeModelRef(item);
         if (!ref)
-            return null;
-        const { thinking, note } = item;
+            return `${row}: provider and id must be non-empty strings`;
+        const { thinking, tier } = item;
         // Repaired, not rejected: rows stored before the level was required have
         // none, and dropping the menu over it would lose the pins.
         const level = thinking === undefined ? "medium" : thinking;
         if (!isThinkingLevel(level))
-            return null;
-        if (note !== undefined && typeof note !== "string")
-            return null;
-        const cleaned = note?.trim().slice(0, 200);
-        menu.push({
-            ...ref,
-            thinking: level,
-            ...(cleaned ? { note: cleaned } : {}),
-        });
+            return `${row} (${ref.provider}/${ref.id}): thinking must be one of ${THINKING_LEVELS.join(", ")}`;
+        if (tier !== undefined && !isModelTier(tier))
+            return `${row} (${ref.provider}/${ref.id}): tier must be one of ${MODEL_TIERS.join(", ")}, or none`;
+        const twin = menu.findIndex((e) => e.provider === ref.provider && e.id === ref.id && e.thinking === level);
+        if (twin >= 0)
+            return `${row} (${ref.provider}/${ref.id}): already pinned at ${level} by row ${String(twin + 1)}`;
+        menu.push({ ...ref, thinking: level, ...(tier !== undefined ? { tier } : {}) });
     }
     return menu;
 }
@@ -117,7 +121,10 @@ export class SettingsStore {
             log.warn("settings.accent is not a preset — ignoring it");
         return {
             publicUrl: this.#value("publicUrl") ?? "",
-            modelMenu: this.#json("modelMenu", normalizeModelMenu, "a valid menu") ?? [],
+            modelMenu: this.#json("modelMenu", (raw) => {
+                const menu = parseModelMenu(raw);
+                return typeof menu === "string" ? null : menu;
+            }, "a valid menu") ?? [],
             ...(titleModel ? { titleModel } : {}),
             autoUpdate: this.#value("autoUpdate") === "1",
             skillsOff: this.#json("skillsOff", normalizeNames, "a list of names") ?? [],

package/dist/tasks/agent.js

@@ -4,13 +4,14 @@
 import { quietLabel, splitReply } from "../core/reply.js";
 import { logger } from "../log.js";
 import { runSource } from "./callbacks.js";
+import { createdRole } from "./types.js";
 // Agent runs are I/O-bound: the cap is there for API pressure and runaway
 // fan-out, not for this machine's CPU.
 const MAX_ACTIVE_AGENTS = 6;
 const log = logger("tasks");
 /** Every session gets the chat-surface contract, task runs included, so the
  *  delegation prompt says which of it does not apply. Skipped on resume. */
-const preamble = (run, supervised) => {
+const preamble = (run, supervised, role) => {
     // A cron/watch task with a session callback is read by an agent too.
     const audience = run.invokedBySessionId
         ? "read by the agent that delegated this run"
@@ -19,8 +20,10 @@ const preamble = (run, supervised) => {
             : "read by the operator";
     return `[Pier task run ${run.id} — "${run.context.definition.name}"] ` +
         `Your final reply is recorded verbatim as the run result, ${audience}; ` +
-        `next-step buttons and file:// attachments do not render there. A question only that reader can answer is your result: state it and end your turn; the answer resumes this session.` +
-        (supervised ? " You cannot delegate from here — `pier task` is refused; if the work needs another agent, say so in your result and your supervisor will run it." : "") +
+        `next-step buttons and file:// attachments do not render there. Return the conclusion and the paths it rests on — no process, no log of attempts; a deliverable longer than a screen goes to a file the result names. A question only that reader can answer is your result: state it and end your turn; the answer resumes this session.` +
+        (role === "lead"
+            ? " You are a feature lead: you may delegate to workers with `pier task run` (never `--role lead`), and their results come back to you."
+            : supervised || role === "worker" ? " You cannot delegate from here — `pier task` is refused; if the work needs another agent, say so in your result and your supervisor will run it." : "") +
         "\n\n";
 };
 export class AgentTaskRunner {
@@ -61,7 +64,8 @@ export class AgentTaskRunner {
                 const input = run.input === undefined || run.input === null
                     ? ""
                     : `\n\n<task_input>\n${JSON.stringify(run.input).replaceAll("</task_input>", "<\\/task_input>")}\n</task_input>`;
-                const prompt = run.context.resumePrompt ?? `${preamble(run, this.store.supervised(run))}${action.prompt}${input}`;
+                const prompt = run.context.resumePrompt ??
+                    `${preamble(run, this.store.supervised(run), this.store.roleOf(session.id))}${action.prompt}${input}`;
                 run.context.sessionId = session.id;
                 run.context.model = session.model;
                 // The level the session settled on: an unspecified effort inherits the caller's.
@@ -144,12 +148,14 @@ export class AgentTaskRunner {
             throw new Error("could not resolve child working directory");
         const opts = {
             cwd,
-            name: `${run.context.definition.name} [${run.id.slice(0, 8)}]`,
+            // The session list's title: the caller's `--name`, else the prompt's first line.
+            name: run.context.definition.name,
             // Unspecified model inherits the caller's live model, not the global
             // default; falls back to the default when the caller isn't attached.
             model: action.launch?.model ??
                 (run.sourceSessionId ? this.router.modelOf(run.sourceSessionId) : undefined),
             thinking: action.launch?.thinking,
+            role: createdRole(run),
         };
         const opening = this.factory.create(opts).then(async (session) => {
             // SDK creation cannot be cancelled; a late session still belongs to this

package/dist/tasks/callbacks.js

@@ -10,6 +10,45 @@ export const runSource = (run) => ({
     ...(run.context.model ? { model: run.context.model } : {}),
     ...(run.context.thinking ? { thinking: run.context.thinking } : {}),
 });
+/** The directory a run worked in: the one its session opened on, else the one its action names. */
+export const runCwd = (run) => {
+    const action = run.context.definition.action;
+    return run.context.cwd ??
+        (action.type === "bash" ? action.cwd : action.type === "agent" && action.session.mode === "fresh" ? action.session.cwd : null);
+};
+/** What a callback's card says about the one run it carries. */
+const oneRun = (run) => {
+    const cwd = runCwd(run);
+    return { source: runSource(run), state: run.state, ...(cwd ? { cwd } : {}) };
+};
+/** Heads a milestone resume's prompt: the lead's reply is what its supervisor reads. */
+export const MILESTONE = "[Pier: the last result you were waiting on follows; nothing owed to you is still running. Your reply is the milestone your supervisor reads: what is done, what is next, any decision you need.]";
+/** The line a design lead ends on once the user confirms: its milestone, whether a run's or a turn outside any. */
+export const DESIGN_FINAL = /^Design final:/m;
+/** On the record of a lead run that owed its supervisor nothing, so the run says why. */
+export const LEAD_TURN = "a lead's turn, not a milestone";
+/** Decided once, as the run finishes. A lead reports milestones only: any
+ *  other turn of its the user reads in its session, and settles as `--callback none`.
+ *  A build lead's turn that leaves nothing coming to it is its milestone: it
+ *  declares its own completion, where only the user finalizes a design.
+ *  A turn that did not succeed is not a turn the user read: it calls back. */
+export function settleCallback(run, store) {
+    if (!run.callbackSessionId)
+        return;
+    // A watch probe that did not match is the interval passing, not a result.
+    if (run.matched === false && run.state === "succeeded")
+        return;
+    // The session's creator fixes its role: a `--session` or `--run` turn on a lead's session is a lead's.
+    const lead = run.targetSessionId;
+    const phase = lead === null ? undefined : store.leadPhaseOf(lead);
+    const milestone = () => run.context.resumePrompt?.startsWith(MILESTONE) === true ||
+        (run.result?.type === "agent" && DESIGN_FINAL.test(run.result.text)) ||
+        (phase === "build" && lead !== null && !store.awaitsResults(lead));
+    if (phase !== undefined && run.state === "succeeded" && !milestone())
+        run.callbackError = LEAD_TURN;
+    else
+        run.callbackState = "pending";
+}
 export function runResultText(run) {
     let result = run.error ?? "No result";
     if (run.result?.type === "agent" || run.result?.type === "system")
@@ -26,9 +65,17 @@ export function runResultText(run) {
 }
 export class TaskCallbacks {
     store;
+    headOf;
+    conversation;
     outbox;
-    constructor(store, router, changed, unreachable) {
+    constructor(store, router, changed, unreachable, 
+    /** Where a result owed to a session goes now: the continuous conversation's head, for a member. */
+    headOf = (id) => id, milestone, 
+    /** The continuous conversation's head, null before its first message. */
+    conversation = () => null) {
         this.store = store;
+        this.headOf = headOf;
+        this.conversation = conversation;
         this.outbox = new Outbox(router, {
             id: (run) => run.id,
             reload: (id) => this.store.getRun(id),
@@ -43,11 +90,12 @@ export class TaskCallbacks {
                     sourceSessionId: runs[0].targetSessionId,
                     runIds: runs.map((run) => run.id),
                     // Only for one run: a batch's caption would attribute every result
-                    // to the first run's name and model.
-                    ...(runs.length === 1 ? { source: runSource(runs[0]), state: runs[0].state } : {}),
+                    // to the first run's name, model and directory.
+                    ...(runs.length === 1 ? oneRun(runs[0]) : {}),
                 },
             }),
             abandoned: (run, sessionId, why) => unreachable(sessionId, `the result of "${run.context.definition.name}"`, why),
+            milestone,
         });
     }
     target(callback, origin) {
@@ -55,6 +103,8 @@ export class TaskCallbacks {
             return callback.sessionId;
         if (callback.type === "origin")
             return origin;
+        if (callback.type === "conversation")
+            return this.conversation();
         return null;
     }
     recover(now = Date.now()) {
@@ -67,10 +117,10 @@ export class TaskCallbacks {
         const first = this.store.getRun(candidate.id);
         if (!first?.callbackSessionId || (first.callbackState !== "pending" && first.callbackState !== "failed"))
             return;
-        const sessionId = first.callbackSessionId;
+        const sessionId = this.headOf(first.callbackSessionId);
         // Once one callback is deliverable, everything pending for the session rides along.
         const batch = this.store.listPendingCallbacks(Number.MAX_SAFE_INTEGER)
-            .filter((run) => run.callbackSessionId === sessionId);
+            .filter((run) => run.callbackSessionId !== null && this.headOf(run.callbackSessionId) === sessionId);
         if (!batch.some((run) => run.id === first.id))
             return;
         await this.outbox.deliver(sessionId, batch);

package/dist/tasks/cli.js

@@ -10,7 +10,7 @@ const OPTIONS = {
     timeout: { type: "string" }, callback: { type: "string" }, "callback-session": { type: "string" }, join: { type: "string" },
     bash: { type: "string" }, cron: { type: "string" }, tz: { type: "string" },
     watch: { type: "string" }, every: { type: "string" }, repeat: { type: "boolean" },
-    group: { type: "string" }, reason: { type: "string" },
+    group: { type: "string" }, reason: { type: "string" }, role: { type: "string" }, design: { type: "boolean" },
     help: { type: "boolean", short: "h" },
 };
 /** The usage line is the contract (docs/design/09-tasks-cli.md); the flags a
@@ -18,17 +18,21 @@ const OPTIONS = {
 const COMMANDS = {
     run: {
         usage: "run [--prompt <text|-> | --bash <script>] [--run <id> [--after]] [--task-id <id>] [--session <id>]\n" +
-            "        [--model <name|?>] [--thinking <level>] [--cwd <dir>] [--name <text>] [--timeout <seconds>]\n" +
+            "        [--model <name|?>] [--thinking <level>] [--role lead [--design]] [--cwd <dir>] [--name <text>] [--timeout <seconds>]\n" +
             "        [--callback origin|none|steer] [--callback-session <id>] [--join all|first] [--member <flags…>]…",
         help: "a new run (--prompt | --bash | --task-id | --session … --prompt), a batch (--member), or a prompt on an existing one (--run)",
     },
     save: {
         usage: "save [--task-id <id>] --name <text> (--prompt <text|-> | --bash <script>)\n" +
             "        [--cron \"<expr>\" --tz <zone> | --watch <script> --every <seconds> [--repeat]]\n" +
-            "        [--cwd <dir>] [--timeout <seconds>] [--model <name>] [--thinking <level>] [--callback-session <id>]",
-        help: "file a definition the operator sees, or update one by --task-id; no trigger means manual",
+            "        [--cwd <dir>] [--timeout <seconds>] [--model <name>] [--thinking <level>] [--callback-session <id|none>]",
+        help: "file a definition the operator sees, or update one by --task-id; no trigger means manual; results reach the continuous conversation unless --callback-session",
     },
-    list: { usage: "list", help: "stored definitions, as JSON" },
+    list: { usage: "list", help: "stored definitions with nextRun and lastRun, as JSON" },
+    pause: { usage: "pause --task-id <id>", help: "stop a definition's schedule; run --task-id still runs it" },
+    resume: { usage: "resume --task-id <id>", help: "restart a paused definition's schedule" },
+    archive: { usage: "archive --task-id <id>", help: "retire a definition for good" },
+    runs: { usage: "runs", help: "the runs you launched (in the continuous conversation, any of its sessions), in flight and finished in the last 24h, as JSON" },
     cancel: { usage: "cancel (--run <id> | --group <id>)", help: "a run or a group, descendants included" },
     recover: { usage: "recover (--run <id> | --group <id>) --reason <text>", help: "a finished result after its callback settled; never a progress check" },
 };
@@ -58,7 +62,9 @@ const seconds = (flag, raw) => {
     return Number.isInteger(n) ? n : refuse(`--${flag} must be a whole number of seconds`);
 };
 /** `launch` as the server takes it: `model` is a menu name it resolves. */
-const launchOf = (v) => v.model === undefined && v.thinking === undefined ? undefined : compact({ model: v.model, thinking: v.thinking });
+const launchOf = (v) => v.model === undefined && v.thinking === undefined && v.role === undefined && v.design === undefined
+    ? undefined
+    : compact({ model: v.model, thinking: v.thinking, role: v.role, design: v.design });
 /** Argv is split at each bare `--member`; a value equal to it is unreachable,
  *  since parseArgs (strict) refuses option-like values anyway. */
 function segments(argv) {
@@ -125,8 +131,8 @@ function build(name, parsed, io) {
     if (parsed.some((v) => v.model === "?"))
         return { operation: "run", launch: { model: "?" } };
     const [values, ...members] = parsed;
-    if (name === "list")
-        return { operation: "list" };
+    if (name === "list" || name === "runs")
+        return { operation: name };
     if (name === "cancel" || name === "recover") {
         if ((values.run === undefined) === (values.group === undefined))
             refuse(`${name} takes exactly one of --run or --group`);
@@ -136,13 +142,16 @@ function build(name, parsed, io) {
     }
     if (name === "save")
         return saveParams(values, text);
+    if (name === "pause" || name === "resume" || name === "archive") {
+        return { operation: name, task_id: values["task-id"] ?? refuse(`${name} needs --task-id`) };
+    }
     /** One new run, in the three shapes `tasks[]` accepts. A saved
      *  definition runs as is: batch defaults pass it by, its own flags are refused. */
     const entry = (v, own = v) => {
         const launch = launchOf(v);
         const timeoutSeconds = seconds("timeout", v.timeout);
         if (v["task-id"] !== undefined) {
-            const extra = flagsOf(own).find((flag) => ["prompt", "bash", "session", "cwd", "model", "thinking", "name", "timeout"].includes(flag));
+            const extra = flagsOf(own).find((flag) => ["prompt", "bash", "session", "cwd", "model", "thinking", "role", "design", "name", "timeout"].includes(flag));
             if (extra)
                 refuse(`--${extra} does not apply to a saved definition (--task-id)`);
             return { task_id: v["task-id"] };
@@ -151,7 +160,7 @@ function build(name, parsed, io) {
             if (v.prompt !== undefined)
                 refuse("a run takes exactly one of --prompt or --bash");
             if (launch)
-                refuse("--model/--thinking apply to a prompt, not --bash");
+                refuse("--model/--thinking/--role/--design apply to a prompt, not --bash");
             if (v.session !== undefined)
                 refuse("--session continues an agent session; --bash is a command, not a turn");
             return compact({ name: v.name, timeoutSeconds, action: compact({ type: "bash", script: v.bash, cwd: v.cwd }) });
@@ -216,7 +225,9 @@ function saveParams(v, text) {
         name: v.name,
         timeoutSeconds: seconds("timeout", v.timeout),
         trigger,
-        callback: v["callback-session"] === undefined ? undefined : { type: "session", sessionId: v["callback-session"] },
+        callback: v["callback-session"] === undefined
+            ? { type: "conversation" }
+            : v["callback-session"] === "none" ? { type: "none" } : { type: "session", sessionId: v["callback-session"] },
         ...(v.bash === undefined
             ? { prompt: text(v.prompt), cwd: v.cwd, launch }
             : { action: compact({ type: "bash", script: v.bash, cwd: v.cwd }) }),

package/dist/tasks/definitions.js

@@ -1,6 +1,6 @@
 // What a task *is* before it ever runs: the id it is minted with, the draft
 // validated into a definition, and when its trigger is next due. Every way a
-// definition can be created — HTTP, `pier task`, Pier's own owned task —
+// definition can be created — `pier task`, Pier's own owned task —
 // arrives here, so a field is checked in one place or nowhere.
 import { randomBytes } from "node:crypto";
 import { stat } from "node:fs/promises";
@@ -69,13 +69,27 @@ function parseTrigger(raw) {
 }
 /** Always computed from `from` (boot recomputes from *now*): cron runs missed
  *  while Pier was down are skipped, never caught up — no double fire. */
-export function nextRunAt(trigger, from) {
+function nextRunAt(trigger, from) {
     if (trigger.type === "manual")
         return null;
     if (trigger.type === "watch")
         return from + trigger.intervalSeconds * 1000;
     return new Cron(trigger.expression, { timezone: trigger.timezone }).nextRun(new Date(from))?.getTime() ?? null;
 }
+function parseModel(raw) {
+    const model = record(raw);
+    if (!model)
+        throw new Error("agent model must be an object");
+    return {
+        provider: requiredString(model.provider, "model provider"),
+        id: requiredString(model.id, "model id"),
+    };
+}
+function parseThinking(raw) {
+    if (!isThinkingLevel(raw))
+        throw new Error("invalid agent thinking level");
+    return raw;
+}
 function parseLaunch(raw) {
     if (raw === undefined)
         return undefined;
@@ -83,20 +97,19 @@ function parseLaunch(raw) {
     if (!value)
         throw new Error("agent launch policy must be an object");
     const launch = {};
-    if (value.model !== undefined) {
-        const model = record(value.model);
-        if (!model)
-            throw new Error("agent model must be an object");
-        launch.model = {
-            provider: requiredString(model.provider, "model provider"),
-            id: requiredString(model.id, "model id"),
-        };
+    if (value.model !== undefined)
+        launch.model = parseModel(value.model);
+    if (value.thinking !== undefined)
+        launch.thinking = parseThinking(value.thinking);
+    if (value.role !== undefined) {
+        if (value.role !== "lead")
+            throw new Error("agent role must be lead");
+        launch.role = "lead";
     }
-    if (value.thinking !== undefined) {
-        if (!isThinkingLevel(value.thinking)) {
-            throw new Error("invalid agent thinking level");
-        }
-        launch.thinking = value.thinking;
+    if (value.design !== undefined) {
+        if (value.design !== true || launch.role !== "lead")
+            throw new Error("agent design must be true, on a lead");
+        launch.design = true;
     }
     return Object.keys(launch).length ? launch : undefined;
 }
@@ -136,7 +149,7 @@ export class TaskDefinitions {
             revision: 1,
             trigger: draft.trigger,
             action: draft.action,
-            callback: draft.callback ?? { type: "none" },
+            callback: draft.callback ?? { type: "conversation" },
             timeoutSeconds: draft.timeoutSeconds ?? DEFAULT_TIMEOUT,
             nextRunAt: null,
             creator,
@@ -321,7 +334,7 @@ export class TaskDefinitions {
         if (raw === undefined)
             return undefined;
         const value = record(raw);
-        if (!value || (value.type !== "none" && value.type !== "origin" && value.type !== "session")) {
+        if (!value || (value.type !== "conversation" && value.type !== "none" && value.type !== "origin" && value.type !== "session")) {
             throw new Error("invalid callback");
         }
         if (value.type !== "session")

package/dist/tasks/execution.js

@@ -1,6 +1,7 @@
 // One queued run carried to a result: dispatched by action kind, abortable,
 // settled exactly once. The lifecycle command.ts and agent.ts share.
 import { logger } from "../log.js";
+import { settleCallback } from "./callbacks.js";
 import { runBash } from "./command.js";
 const log = logger("tasks");
 export class TaskExecution {
@@ -92,8 +93,7 @@ export class TaskExecution {
                 log.debug(`${settled} (watch did not match)`);
             else
                 log.info(settled);
-            if (run.callbackSessionId)
-                run.callbackState = "pending";
+            settleCallback(run, this.store);
             this.controllers.delete(run.id);
             try {
                 this.store.saveRun(run);

package/dist/tasks/groups.js

@@ -13,12 +13,14 @@ export class TaskGroups {
     host;
     changed;
     unreachable;
+    headOf;
     outbox;
-    constructor(store, router, host, changed, unreachable) {
+    constructor(store, router, host, changed, unreachable, headOf = (id) => id, milestone) {
         this.store = store;
         this.host = host;
         this.changed = changed;
         this.unreachable = unreachable;
+        this.headOf = headOf;
         this.outbox = new Outbox(router, {
             id: (group) => group.id,
             reload: (id) => this.store.getGroup(id),
@@ -31,6 +33,7 @@ export class TaskGroups {
                 origin: { kind: "task-callback", taskId: groups[0].id, runId: groups[0].id, sourceSessionId: null },
             }),
             abandoned: (group, sessionId, why) => unreachable(sessionId, `the result of a ${String(group.memberRunIds.length)}-run group`, why),
+            milestone,
         });
     }
     /** Enqueues every member or none: a partially started group is worse than
@@ -141,7 +144,7 @@ export class TaskGroups {
         const group = this.store.getGroup(candidate.id);
         if (!group?.callbackSessionId || (group.callbackState !== "pending" && group.callbackState !== "failed"))
             return;
-        await this.outbox.deliver(group.callbackSessionId, [group]);
+        await this.outbox.deliver(this.headOf(group.callbackSessionId), [group]);
     }
     text(group) {
         const members = group.memberRunIds.map((id) => this.host.getRun(id));