@timqi/pier 0.1.2 → 0.1.4

package/dist/main.js

@@ -9,6 +9,7 @@ import { ConfigSync } from "./config-sync.js";
 import { configSyncTask } from "./config-sync-task.js";
 import { CredentialStore } from "./agent/credentials.js";
 import { IndexedListing } from "./agent/listing.js";
+import { PiPackageStore } from "./agent/packages.js";
 import { PiAgentFactory } from "./agent/pi.js";
 import { defaultBoardsDir, registerBoardRoutes } from "./boards/boards.js";
 import { ChannelStore } from "./channels/config.js";
@@ -16,15 +17,11 @@ import { createControl } from "./channels/control.js";
 import { ConversationStore, resolveConversation } from "./channels/conversations.js";
 import { registerChannelRoutes } from "./channels/routes.js";
 import { ChannelRuntime } from "./channels/runtime.js";
-import { SlackApi } from "./channels/slack-api.js";
-import { SlackDirectory } from "./channels/slack-directory.js";
-import { handleSlackTool, slackToolAvailable, slackToolSpec } from "./channels/slack-tool.js";
-import { parseConversation as parseSlackConversation } from "./channels/slack.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 { bundledInfo } from "./extensions/index.js";
+import { BUNDLED } from "./extensions/index.js";
 import { surfacePrompt } from "./core/reply.js";
 import { Router } from "./core/router.js";
 import { acquireInstanceLock } from "./lock.js";
@@ -32,19 +29,21 @@ import { logger } from "./log.js";
 import { registerTaskRoutes } from "./tasks/routes.js";
 import { TaskService } from "./tasks/service.js";
 import { TaskStore } from "./tasks/store.js";
-import { taskToolSpec } from "./tasks/tool.js";
 import { PIER_HOME, pierPath, resolveAgentDir } from "./paths.js";
-import { CUSTOM_TOOL_RULES, MANAGED, ManagedTools, normalizeCustomTools, prependPath } from "./tools.js";
+import { CUSTOM_TOOL_RULES, MANAGED, ManagedTools, normalizeCustomTools, prependPath, writePierShim } from "./tools.js";
 import { toolsTask } from "./tools-task.js";
 import { Secrets } from "./secrets.js";
 import { startUpdate, unitPath, updaterProblem } from "./service.js";
 import { SettingsStore } from "./settings.js";
-import { startAutoUpdate, UpdateCheck } from "./update.js";
+import { currentVersion, startAutoUpdate, UpdateCheck } from "./update.js";
+import { Vault } from "./vault.js";
+import { servePier } from "./socket.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";
+import { registerVaultRoutes } from "./web/vault.js";
 const log = logger("pier");
 // Before any SDK call resolves a path, so everything Pi derives from its agent
 // dir lands under PIER_HOME. PIER_AGENT_DIR marks the value as ours: a second
@@ -53,6 +52,7 @@ const log = logger("pier");
 process.env.PI_CODING_AGENT_DIR = resolveAgentDir(process.env);
 process.env.PIER_AGENT_DIR = process.env.PI_CODING_AGENT_DIR;
 prependPath(process.env);
+writePierShim();
 // Before the database and before task recovery, which would mark the running
 // instance's queued and active runs interrupted; the port is discovered far too
 // late, and a second Pier on another port would never notice at all.
@@ -76,44 +76,26 @@ const settings = new SettingsStore(db);
 // Unlocked below: vt mode waits on a human approval, and nothing that needs a
 // token may run before the key arrives.
 const secrets = new Secrets();
+const vault = new Vault(secrets, db);
 let tasks;
 const conversations = new ConversationStore(db);
 let resolveIm;
 let channelStore;
-// Shared by the adapter and the tool: one display-name lookup per process.
-const slackDirectory = new SlackDirectory((m) => logger("slack").warn(m));
 let readyForConfigReload = false;
 const piConfig = new PiConfigStore();
+// Before anything reads settings.json: a first boot gets Pier's seed file.
+await piConfig.seedSettings();
 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({
-        store: channelStore,
-        directory: slackDirectory,
-        // Per call: the Console can change the token underneath us.
-        client: () => {
-            const config = channelStore.get("slack");
-            return config.token ? new SlackApi(config.token, config.appToken) : null;
-        },
-        // Per call: the mapping is durable, the session is not.
-        here: (sessionId) => {
-            const key = router.conversationOf(sessionId);
-            if (key?.channelId !== "slack")
-                return null;
-            const { channel, threadTs } = parseSlackConversation(key.conversationId);
-            return channel && threadTs ? { channel, threadTs } : null;
-        },
-        log: (m) => logger("slack.tool").warn(m),
-    }, params, callerSessionId), () => slackToolAvailable(channelStore)),
-], 
+const skillsDir = fileURLToPath(new URL("../skills", import.meta.url));
+const factory = new PiAgentFactory(
 // Getters, read per session open: a Console change reaches the next session
 // without a restart.
 () => surfacePrompt({ boardsDir: defaultBoardsDir(), publicUrl: settings.get().publicUrl }), 
 // Documents Pier's own tools, so it loads only inside a Pier session.
-[fileURLToPath(new URL("../skills", import.meta.url))], new CredentialStore(db, secrets), piConfig, () => settings.get().modelMenu, () => settings.get().extensions, () => settings.get().titleModel, 
+[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));
 const hub = new EventHub();
@@ -137,7 +119,10 @@ const toolsUpdate = toolsTask(tasks);
 const reconciled = await toolsUpdate.reconcile();
 if ("problem" in reconciled)
     log.error(`tools cannot be managed: ${reconciled.problem}`);
-channelStore = new ChannelStore(db, secrets);
+const packages = new PiPackageStore(piConfig, { version: currentVersion(), settings }, [skillsDir]);
+// At boot, not lazily: the answer waits for the next Console open (update.ts).
+packages.watchUpdates();
+channelStore = new ChannelStore(db, vault);
 const control = createControl({ router, factory, conversations, store: channelStore });
 const channels = new ChannelRuntime(channelStore, router, control);
 resolveIm = resolveConversation(conversations, factory, control.launchFor, (message) => logger("channels").warn(message));
@@ -264,6 +249,7 @@ registerConfigSyncRoutes(app, {
 });
 registerTaskRoutes(app, tasks, { factory, router });
 registerChannelRoutes(app, channelStore, channels);
+registerVaultRoutes(app, { vault, doctor: () => secrets.doctor() });
 registerBoardRoutes(app);
 const sessionState = new SessionStateStore(db);
 registerPushRoutes(app, {
@@ -280,23 +266,20 @@ app.route("/", createServer({
     hub,
     sessions: sessionState,
     config: piConfig,
+    packages,
     providers: factory,
     settings,
-    // Assembled here so web/ gets names and summaries, not a module that
-    // imports the Pi SDK; extensions and binaries are one kind of switch.
+    // Assembled here: the catalog spawns ubix, which web/ may not.
     catalog: async () => {
-        const { extensions, tools, customTools } = settings.get();
-        return {
-            entries: [...bundledInfo(extensions), ...await managedTools.status(tools, customTools)],
-            toolsTaskId: toolsUpdate.id(),
-        };
+        const { tools, customTools } = settings.get();
+        return { entries: await managedTools.status(tools, customTools), toolsTaskId: toolsUpdate.id() };
     },
     // A switch is validated against what this Pier *can* switch, never against
     // a catalog whose custom half the request may be rewriting.
-    names: { extensions: bundledInfo([]).map((entry) => entry.name), tools: MANAGED.map((tool) => tool.name) },
+    names: MANAGED.map((tool) => tool.name),
     onToolsChanged: toolsUpdate.changed,
     validateCustomTools: (raw) => {
-        const validated = normalizeCustomTools(raw, bundledInfo([]).map((entry) => entry.name));
+        const validated = normalizeCustomTools(raw, BUNDLED.map((ext) => ext.name));
         return validated ? { tools: validated } : { error: CUSTOM_TOOL_RULES };
     },
     secrets,
@@ -311,6 +294,15 @@ app.route("/", createServer({
 }));
 const port = Number(process.env.PORT ?? 3141);
 const hostname = process.env.HOST ?? "127.0.0.1";
+servePier({
+    vault,
+    // The deep link an agent's "no secret named X" error carries; loopback when
+    // no public URL is set, since nothing in the process can discover one.
+    fileUrl: (name) => `${settings.get().publicUrl || `http://127.0.0.1:${String(port)}`}/#/settings/vault?name=${name}`,
+    task: (params, callerSessionId) => tasks.handle(params, callerSessionId),
+    // Live in the router, or on disk: the same two places a callback target is looked for.
+    knows: async (id) => router.stateOf(id) !== undefined || (await factory.find(id)) !== undefined,
+});
 // Every command a turn runs inherits this env: `NODE_ENV=production` makes an
 // agent's `npm install` skip devDependencies, and PORT/HOST would aim its dev
 // server at Pier's socket.

package/dist/paths.js

@@ -12,6 +12,9 @@ export const PIER_DB = pierPath("db", "pier.db");
 /** At the root of PIER_HOME: the claim is the whole instance directory, not the
  *  database (lock.ts). */
 export const PIER_LOCK = pierPath("pier.lock");
+/** Where the `pier` CLI reaches the running Pier; the CLI needs the name
+ *  without opening the database (socket.ts). */
+export const PIER_SOCK = pierPath("pier.sock");
 /** `PI_CODING_AGENT_DIR` is an operator override — unless it equals
  *  `PIER_AGENT_DIR`, the value Pier itself set: then a Pier spawned from inside
  *  another inherited it, and a leak is not an instruction. */

package/dist/secrets.js

@@ -146,7 +146,8 @@ function open(key, sealed, aad) {
     decipher.setAuthTag(tag);
     return Buffer.concat([decipher.update(ct), decipher.final()]);
 }
-const vtCli = {
+/** The real vt; vault.ts creates its `approve` records through the same client. */
+export const vtCli = {
     read: (record) => run("vt", ["read", record]),
     create: async (plaintext) => {
         const out = await run("vt", ["create"], plaintext);

package/dist/settings.js

@@ -99,6 +99,7 @@ export class SettingsStore {
             ...(titleModel ? { titleModel } : {}),
             autoUpdate: this.#value("autoUpdate") === "1",
             extensions: this.#json("extensions", normalizeExtensions, "a list of names") ?? [],
+            skillsOff: this.#json("skillsOff", normalizeNames, "a list of names") ?? [],
             tools: this.#json("tools", normalizeTools, "a list of names") ?? [],
             // `"drop"`: a row the bundled catalog has since taken is redundant, not malformed.
             customTools: this.#json("customTools", (raw) => normalizeCustomTools(raw, [], "drop"), "a list of {name, toml}") ?? [],
@@ -144,6 +145,10 @@ export class SettingsStore {
         this.#set("extensions", JSON.stringify(names));
         return this.get();
     }
+    setSkillsOff(names) {
+        this.#set("skillsOff", JSON.stringify(names));
+        return this.get();
+    }
     setTools(names) {
         this.#set("tools", JSON.stringify(names));
         return this.get();

package/dist/socket.js

@@ -0,0 +1,95 @@
+// The local socket the `pier` CLI reaches the running instance through: one
+// route per verb the CLI has, the socket's permission bits as the whole auth.
+// Not a workbench route — that server sits behind a proxy at a public
+// hostname — so plaintext crosses this socket into a local process of Pier's
+// user and nowhere else.
+import { chmodSync, rmSync } from "node:fs";
+import { createServer } from "node:http";
+import { logger } from "./log.js";
+import { PIER_SOCK } from "./paths.js";
+import { isVaultName, UnknownSecret, VaultLocked } from "./vault.js";
+const log = logger("socket");
+/** Generous for a task draft; a `--prompt -` past it is told so, not hung up on. */
+const MAX_BODY = 64 * 1024;
+const ROUTES = {
+    async "/resolve"({ vault, fileUrl }, { names }, sessionId, answer) {
+        if (!Array.isArray(names) || !names.length || !names.every((n) => typeof n === "string" && isVaultName(n))) {
+            return answer(400, { error: "names must be a non-empty list of vault names" });
+        }
+        try {
+            answer(200, { values: vault.resolve(names, `session ${sessionId}`) });
+        }
+        catch (err) {
+            if (err instanceof UnknownSecret)
+                return answer(404, { error: err.message, file: fileUrl(err.secret) });
+            if (err instanceof VaultLocked)
+                return answer(423, { error: err.message });
+            log.error(`resolve ${names.join(",")} failed`, err);
+            answer(500, { error: String(err) });
+        }
+    },
+    // 422, not 400: the request was well-formed; what the operation refused is
+    // the caller's to read.
+    async "/task"({ task }, { params }, sessionId, answer) {
+        try {
+            answer(200, { result: await task(params, sessionId) });
+        }
+        catch (err) {
+            answer(422, { error: err instanceof Error ? err.message : String(err) });
+        }
+    },
+};
+export function servePier(hosts, path = PIER_SOCK) {
+    const server = createServer((req, res) => void handle(hosts, req, res).catch((err) => {
+        log.error(`${req.method ?? "?"} ${req.url ?? "?"} failed`, err);
+        if (!res.headersSent)
+            res.writeHead(500).end(JSON.stringify({ error: String(err) }));
+    }));
+    // A crash leaves the old socket file behind, and listen() on it is EADDRINUSE.
+    rmSync(path, { force: true });
+    // bind() runs inside listen(): the umask covers the instant the file exists
+    // with default bits; the chmod sets the exact mode once it is bound. A bind
+    // that failed reports through the error event and left no file to chmod.
+    const umask = process.umask(0o077);
+    try {
+        server.listen(path, () => log.info(`cli socket at ${path}`));
+    }
+    finally {
+        process.umask(umask);
+    }
+    if (server.listening)
+        chmodSync(path, 0o600);
+    server.on("error", (err) => log.error(`cli socket ${path} failed`, err));
+    process.once("exit", () => rmSync(path, { force: true }));
+    return server;
+}
+async function handle(hosts, req, res) {
+    const answer = (status, body) => {
+        res.writeHead(status, { "content-type": "application/json" });
+        res.end(JSON.stringify(body));
+    };
+    const route = req.method === "POST" ? ROUTES[req.url ?? ""] : undefined;
+    if (!route)
+        return answer(404, { error: `POST ${Object.keys(ROUTES).join(" | ")} only` });
+    let raw = "";
+    for await (const chunk of req) {
+        raw += chunk.toString();
+        // Answered before the body is drained: leaving the loop destroys the
+        // request stream, and the response already queued still reaches the client.
+        if (raw.length > MAX_BODY)
+            return answer(413, { error: `body exceeds ${String(MAX_BODY / 1024)} KiB` });
+    }
+    let body;
+    try {
+        body = JSON.parse(raw);
+    }
+    catch {
+        return answer(400, { error: "body must be a JSON object" });
+    }
+    const { sessionId, ...fields } = typeof body === "object" && body !== null ? body : {};
+    if (typeof sessionId !== "string" || !sessionId)
+        return answer(400, { error: "PIER_SESSION_ID is required" });
+    if (!(await hosts.knows(sessionId)))
+        return answer(403, { error: `${sessionId} is not a session of this Pier` });
+    await route(hosts, fields, sessionId, answer);
+}

package/dist/tasks/agent.js

@@ -10,19 +10,18 @@ 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) => {
+const preamble = (run, supervised) => {
     // 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"
         : run.callbackSessionId
             ? "read by the agent session it is delivered to"
             : "read by the operator";
-    const contact = run.invokedBySessionId
-        ? ' Mid-run, the task tool\'s contact operation reaches that agent: reason "progress" is fire-and-forget, "decision" waits for a reply — state what you await and end your turn.'
-        : "";
     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.${contact}\n\n`;
+        `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." : "") +
+        "\n\n";
 };
 export class AgentTaskRunner {
     factory;
@@ -62,7 +61,7 @@ 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)}${action.prompt}${input}`;
+                const prompt = run.context.resumePrompt ?? `${preamble(run, this.store.supervised(run))}${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.

package/dist/tasks/callbacks.js

@@ -2,7 +2,7 @@
 // belongs to outbox.ts; this file owns the run vocabulary and the batching.
 import { Outbox } from "./outbox.js";
 /** The run id and the session that did the work: a relayer's next move is a
- *  deep link to it, and without this that costs a second tool call. */
+ *  deep link to it, and without this that costs a second call. */
 export const runRef = (run) => `Run: ${run.id}${run.targetSessionId ? ` / Session: ${run.targetSessionId}` : ""}`;
 /** What the card in the recipient's transcript says the input came from. */
 export const runSource = (run) => ({
@@ -21,7 +21,7 @@ export function runResultText(run) {
     if (run.result?.type === "watch")
         result = "Watch condition did not match";
     if (result.length > 8000)
-        result = `${result.slice(0, 8000)}\n[truncated — task tool recover run_id ${run.id} with a reason returns the full text]`;
+        result = `${result.slice(0, 8000)}\n[truncated — pier task recover --run ${run.id} --reason … returns the full text]`;
     return result;
 }
 export class TaskCallbacks {

package/dist/tasks/cli.js

@@ -0,0 +1,215 @@
+// `pier task <command> …`: argv → the params object `/task` takes. Argv shape
+// is the only thing checked here; the server validates the operation, and its
+// answer comes back verbatim.
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+const OPTIONS = {
+    prompt: { type: "string" }, run: { type: "string" }, after: { type: "boolean" },
+    "task-id": { type: "string" }, session: { type: "string" },
+    model: { type: "string" }, thinking: { type: "string" }, cwd: { type: "string" }, name: { type: "string" },
+    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" },
+    help: { type: "boolean", short: "h" },
+};
+/** The usage line is the contract (docs/design/09-tasks-cli.md); the flags a
+ *  command accepts are read off it, so the two cannot drift. */
+const COMMANDS = {
+    run: {
+        usage: "run [--prompt <text|->] [--run <id> [--after]] [--task-id <id>] [--session <id>]\n" +
+            "        [--model <name|?>] [--thinking <level>] [--cwd <dir>] [--name <text>] [--timeout <seconds>]\n" +
+            "        [--callback origin|none|steer] [--callback-session <id>] [--join all|first] [--member <flags…>]…",
+        help: "a prompt on a run: a new one (--prompt | --task-id | --session … --prompt), a batch (--member), or 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",
+    },
+    list: { usage: "list", help: "stored definitions, 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" },
+};
+const USAGE = [
+    "usage: pier task <command> … — subagents and scheduled tasks (skills/pier-tasks)",
+    ...Object.values(COMMANDS).map(({ usage, help }) => `  ${usage}\n      ${help}`),
+    "`--prompt -` reads stdin. The receipt is one line of JSON, exit 0; a refusal is one `task:` line, exit 1.",
+].join("\n");
+/** Flags that belong to the batch, never to one member. */
+const GROUP_FLAGS = ["join", "callback", "callback-session"];
+const processIo = {
+    stdout: (line) => process.stdout.write(`${line}\n`),
+    stderr: (line) => process.stderr.write(`${line}\n`),
+    stdin: () => readFileSync(0, "utf8"),
+};
+class ArgvError extends Error {
+}
+const refuse = (message) => {
+    throw new ArgvError(message);
+};
+const compact = (value) => Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
+const flagsOf = (values) => Object.keys(values).filter((flag) => flag !== "help");
+const seconds = (flag, raw) => {
+    if (raw === undefined)
+        return undefined;
+    const n = Number(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 });
+/** 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) {
+    const out = [[]];
+    for (const arg of argv) {
+        if (arg === "--member")
+            out.push([]);
+        else
+            out.at(-1).push(arg);
+    }
+    return out;
+}
+export async function runTaskCli(argv, post, io = processIo) {
+    const [name, ...rest] = argv;
+    if (!name || name === "--help" || name === "-h") {
+        io.stdout(USAGE);
+        return name ? 0 : 2;
+    }
+    const cmd = COMMANDS[name];
+    const usage = (message) => {
+        io.stderr(`task: ${message}\n${cmd ? `pier task ${cmd.usage}` : USAGE}`);
+        return 2;
+    };
+    if (!cmd)
+        return usage(`unknown command "${name}"`);
+    const allowed = new Set((cmd.usage.match(/--[a-z-]+/g) ?? []).map((flag) => flag.slice(2)));
+    let params;
+    try {
+        const parsed = (name === "run" ? segments(rest) : [rest]).map((args) => {
+            const values = parseArgs({ args, options: OPTIONS, allowPositionals: false, strict: true }).values;
+            const stray = flagsOf(values).find((flag) => !allowed.has(flag));
+            return stray ? refuse(`--${stray} is not an option of ${name}`) : values;
+        });
+        if (parsed.some((values) => values.help)) {
+            io.stdout(`pier task ${cmd.usage}\n    ${cmd.help}`);
+            return 0;
+        }
+        params = build(name, parsed, io);
+    }
+    catch (err) {
+        return usage(err instanceof Error ? err.message : String(err));
+    }
+    const { status, body } = await post(params);
+    if (status === 200) {
+        // Compact: the reader is a model, and the ids are what it keeps.
+        io.stdout(JSON.stringify(body.result));
+        return 0;
+    }
+    io.stderr(`task: ${body.error ?? `socket answered ${String(status)}`}`);
+    return 1;
+}
+/** Argv → the exact params object, or an ArgvError before the socket is touched. */
+function build(name, parsed, io) {
+    let stdinReads = 0;
+    const text = (raw) => {
+        if (raw !== "-")
+            return raw === undefined ? undefined : String(raw);
+        if (stdinReads++)
+            refuse("only one --prompt may read stdin (-)");
+        // An agent's shell has no TTY: a `-` with nothing piped is an empty prompt, named here rather than by the server.
+        return io.stdin() || refuse("--prompt - read nothing from stdin");
+    };
+    if (parsed.some((v) => v.model === "?"))
+        return { operation: "run", launch: { model: "?" } };
+    const [values, ...members] = parsed;
+    if (name === "list")
+        return { operation: "list" };
+    if (name === "cancel" || name === "recover") {
+        if ((values.run === undefined) === (values.group === undefined))
+            refuse(`${name} takes exactly one of --run or --group`);
+        if (name === "recover" && values.reason === undefined)
+            refuse("recover needs --reason");
+        return compact({ operation: name, run_id: values.run, group_id: values.group, reason: values.reason });
+    }
+    if (name === "save")
+        return saveParams(values, text);
+    /** 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", "session", "cwd", "model", "thinking", "name", "timeout"].includes(flag));
+            if (extra)
+                refuse(`--${extra} does not apply to a saved definition (--task-id)`);
+            return { task_id: v["task-id"] };
+        }
+        const prompt = text(v.prompt) ?? refuse("a new run needs --prompt or --task-id");
+        if (v.session === undefined)
+            return compact({ prompt, cwd: v.cwd, launch, name: v.name, timeoutSeconds });
+        if (v.cwd !== undefined)
+            refuse("--cwd applies to a fresh session, not --session");
+        return compact({ name: v.name, timeoutSeconds, action: compact({ type: "agent", session: { mode: "reuse", sessionId: v.session }, prompt, launch }) });
+    };
+    const delivery = compact({ callback: values.callback, callback_session_id: values["callback-session"] });
+    if (values.run !== undefined) {
+        if (members.length)
+            refuse("--run addresses one existing run; --member starts new ones");
+        const extra = flagsOf(values).find((flag) => !["run", "after", "prompt", "callback", "callback-session"].includes(flag));
+        if (extra)
+            refuse(`--${extra} does not apply to an existing run (--run)`);
+        const message = text(values.prompt) ?? refuse("--run needs --prompt");
+        return compact({ operation: "message", run_id: values.run, message, after: values.after || undefined, ...delivery });
+    }
+    if (values.after)
+        refuse("--after applies to --run only");
+    if (members.length) {
+        if (members.length < 2)
+            refuse("a batch needs at least two --member");
+        if (values["task-id"] !== undefined)
+            refuse("--task-id names one member's definition; put it after a --member");
+        const grouped = members.find((m) => flagsOf(m).some((flag) => GROUP_FLAGS.includes(flag)));
+        if (grouped)
+            refuse(`--${flagsOf(grouped).find((flag) => GROUP_FLAGS.includes(flag))} belongs before the first --member`);
+        const defaults = Object.fromEntries(Object.entries(values).filter(([flag]) => !GROUP_FLAGS.includes(flag)));
+        return compact({ operation: "run", tasks: members.map((m) => entry({ ...defaults, ...m }, m)), join: values.join, ...delivery });
+    }
+    if (values.join !== undefined)
+        refuse("--join applies to a batch (--member)");
+    const single = entry(values);
+    if (single.task_id !== undefined || single.action === undefined)
+        return { operation: "run", ...single, ...delivery };
+    return { operation: "run", task: single, ...delivery };
+}
+function saveParams(v, text) {
+    if ((v.prompt === undefined) === (v.bash === undefined))
+        refuse("save takes exactly one of --prompt or --bash");
+    const cron = v.cron !== undefined || v.tz !== undefined;
+    const watch = v.watch !== undefined || v.every !== undefined || v.repeat !== undefined;
+    if (cron && watch)
+        refuse("a task has one trigger: --cron/--tz or --watch/--every/--repeat");
+    if (cron && (v.cron === undefined || v.tz === undefined))
+        refuse("--cron and --tz go together");
+    if (watch && (v.watch === undefined || v.every === undefined))
+        refuse("--watch and --every go together");
+    const launch = launchOf(v);
+    if (launch && v.bash !== undefined)
+        refuse("--model/--thinking apply to a prompt, not --bash");
+    const trigger = cron
+        ? { type: "cron", expression: v.cron, timezone: v.tz }
+        : watch
+            ? compact({ type: "watch", script: v.watch, cwd: v.cwd, intervalSeconds: seconds("every", v.every), mode: v.repeat ? "repeat" : "once" })
+            : { type: "manual" };
+    const task = compact({
+        name: v.name,
+        timeoutSeconds: seconds("timeout", v.timeout),
+        trigger,
+        callback: v["callback-session"] === undefined ? undefined : { 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 }) }),
+    });
+    return compact({ operation: "save", task_id: v["task-id"], task });
+}

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, the task tool, Pier's own owned task —
+// definition can be created — HTTP, `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";
@@ -24,7 +24,7 @@ export const idSymbol = (byte) => ID_ALPHABET.charAt(byte & 31);
  *  not an error — `saveRun`'s ON CONFLICT DO UPDATE would quietly overwrite. */
 export const newId = () => Array.from(randomBytes(16), idSymbol).join("");
 /** A definition Pier's own code created is reconciled by that code and edited
- *  by nobody: `creator` is `"http"` (Console) or `session:<id>` (task tool);
+ *  by nobody: `creator` is `"http"` (Console) or `session:<id>` (`pier task`);
  *  anything else is an instance-layer owner, which names itself in `by`.
  *  Otherwise a public surface could repoint the tools task while its switch
  *  went on claiming Pier keeps the tools current. */
@@ -258,7 +258,7 @@ export class TaskDefinitions {
         if (trigger.type === "watch")
             await this.assertDirectory(trigger.cwd);
         const actionRaw = record(value.action);
-        // Self-documenting: tool callers (models) recover from this in one retry.
+        // Self-documenting: a model recovers from this in one retry.
         if (!actionRaw) {
             throw new Error('action required, e.g. {"type":"agent","session":{"mode":"fresh","cwd":"/abs/path"},"prompt":"..."}');
         }

package/dist/tasks/execution.js

@@ -92,9 +92,7 @@ export class TaskExecution {
                 log.debug(`${settled} (watch did not match)`);
             else
                 log.info(settled);
-            // A run that ends awaiting a supervisor decision suppresses its
-            // completion callback: the pending question is the notification.
-            if (run.callbackSessionId && !this.host.openDecisionId(run.id))
+            if (run.callbackSessionId)
                 run.callbackState = "pending";
             this.controllers.delete(run.id);
             try {

package/dist/tasks/groups.js

@@ -35,12 +35,12 @@ export class TaskGroups {
     }
     /** Enqueues every member or none: a partially started group is worse than
      * a rejected one. */
-    runAll(definitions, join, callerSessionId, parentRunId, callbackSessionId, callbackMode) {
+    runAll(definitions, join, callerSessionId, callbackSessionId, callbackMode) {
         if (definitions.length < 2)
             throw new Error("a task group needs at least 2 members");
         const { group, runs } = this.store.transact(() => {
             const group = this.create(join, callerSessionId, callbackSessionId, callbackMode);
-            const runs = definitions.map((definition) => this.host.prepareMember(definition.id, group.id, callerSessionId, parentRunId));
+            const runs = definitions.map((definition) => this.host.prepareMember(definition.id, group.id, callerSessionId));
             group.memberRunIds = runs.map((run) => run.id);
             this.store.saveGroup(group);
             return { group, runs };
@@ -150,9 +150,6 @@ export class TaskGroups {
                 `- "${run.context.definition.name}" \u2014 state: ${run.state}`,
                 `  ${runRef(run)}`,
             ];
-            const decision = this.host.openDecisionId(run.id);
-            if (decision)
-                head.push(`  Needs a decision: reply to message ${decision}`);
             if (group.join === "first" && run.id !== group.winnerRunId) {
                 head.push("  Cancelled after the winning run; resume its session to recover partial work.");
                 return head.join("\n");