@timqi/pier 0.0.9 → 0.0.16

package/dist/extensions/web/content.js

@@ -1,3 +1,8 @@
+// What a provider's answer becomes on the way to the model: sources, results,
+// the queries actually searched, usage, and the text of a fetched document.
+// One shape for both backends, so a tool renders its answer once instead of
+// per wire format — anthropic.ts and openai.ts parse into these, and nothing
+// past this file knows which one replied.
 import { isObject } from "./json.js";
 import { languageLabel } from "./language.js";
 /**

package/dist/extensions/web/language.js

@@ -1,3 +1,8 @@
+// The language-preservation policy in words: what the model is told to search
+// in, and how to tell afterwards whether it did. This is the reason the
+// extension exists at all — a hosted search that quietly translates a Chinese
+// query answers a question nobody asked — so the policy is one file, and the
+// audit that checks it reads from the same one.
 export function searchPrompt(query, mode) {
     const policy = mode === "preserve"
         ? "Use only the original language. Later searches may refine wording in that language, but must not translate or transliterate it."

package/dist/extensions/web/tools.js

@@ -1,3 +1,8 @@
+// The two tools as the model sees them: web_search and web_fetch — their
+// parameters, which backend answers a call, and what comes back when one
+// cannot. Every parameter is context the model pays for on every turn, so the
+// surface is deliberately small; the wire formats behind it are anthropic.ts
+// and openai.ts, and the answer's shape is content.ts.
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { callNativeTool } from "./anthropic.js";
@@ -16,11 +21,14 @@ const FULL_MAX_CHARS = 60_000;
  * not be the binding constraint: `DEFAULT_CONTEXT_CHARS` is what we are willing
  * to hand back (6k characters, which is ~1.5k English tokens and ~4k Chinese
  * ones), so a budget below that only produces briefings that stop mid-sentence.
- * It used to be 900, half the smaller of those. Output tokens are not the cost
- * here either — a hosted search is worth an order of magnitude more than the
- * prose about it — and a truncated answer is paid for twice.
+ * It used to be 900, half the smaller of those, and then 2k, which is the same
+ * bug in Chinese: it covered the English reading of 6k characters and cut every
+ * CJK briefing at the point this comment claimed was fixed. So the budget is
+ * the *larger* reading plus room for the search calls themselves. Output tokens
+ * are not the cost here either — a hosted search is worth an order of magnitude
+ * more than the prose about it — and a truncated answer is paid for twice.
  */
-const SEARCH_TOKENS = 2_000;
+const SEARCH_TOKENS = 4_500;
 /**
  * Same rule for a fetch, and one dial for it: `mode` says how much of the page
  * matters, so it decides all three sizes — what the provider fetches, what the
@@ -107,23 +115,36 @@ export const webSearch = defineTool({
             const run = { ctx, query: params.query, domains, backend: params.backend, signal: until, note };
             let outcome = await runSearch({ ...run, mode, maxUses: searchRounds(mode) });
             const wantedLanguage = languageLabel(params.query);
-            const inLanguage = (o) => preservesLanguage(params.query, o.queries[0]?.query);
-            let preserved = inLanguage(outcome);
+            const strayed = (o) => o.queries.filter((q) => !preservesLanguage(params.query, q.query)).map((q) => q.query);
+            // The prompt pins the first query verbatim, so auditing only that one
+            // audits the query that cannot fail. `preserve` promised every search
+            // stays in the language, so it audits all of them; auto and expand buy
+            // English supplements on purpose, so there the first query still decides
+            // and the strays are named in `details` instead of warned about.
+            const inLanguage = (o, auditAll) => auditAll
+                ? o.queries.length > 0 && strayed(o).length === 0
+                : preservesLanguage(params.query, o.queries[0]?.query);
+            let preserved = inLanguage(outcome, mode === "preserve");
             if (outcome.queries.length && !preserved) {
                 note(`the backend left ${wantedLanguage} — searching again, that language only`);
                 const retried = await runSearch({ ...run, mode: "preserve", maxUses: 1 });
                 // Only if it worked. The retry is one narrowed search against the
                 // first's three rounds, so a retry that *also* leaves the language is
                 // a worse answer, and swapping it in spent a search to get there.
-                if (inLanguage(retried)) {
+                if (inLanguage(retried, true)) {
                     outcome = retried;
                     preserved = true;
                 }
             }
             const auditAvailable = outcome.queries.length > 0;
+            const offLanguage = strayed(outcome);
+            // No query metadata means the audit never ran — under `preserve`, the one
+            // mode that promised it, an unaudited answer must not read like a clean one.
             const warning = auditAvailable && !preserved
                 ? `Warning: the search backend translated the query out of ${wantedLanguage} despite strict preservation.`
-                : "";
+                : mode === "preserve" && !auditAvailable
+                    ? "Note: the backend returned no query metadata, so strict language preservation could not be audited."
+                    : "";
             // A briefing that stopped at the output ceiling reads exactly like a
             // finished one; the caller decides whether to ask again, but only if it
             // is told (§5b).
@@ -153,6 +174,10 @@ export const webSearch = defineTool({
                     languageMode: mode,
                     queries: outcome.queries,
                     queryLanguagePreserved: auditAvailable ? preserved : undefined,
+                    // Legitimate under auto/expand, so not a warning — but the caller
+                    // cannot weigh a briefing built partly from English searches if it
+                    // is never told which searches those were.
+                    queriesOffLanguage: offLanguage.length ? offLanguage : undefined,
                     originalQueryVerbatim: auditAvailable
                         ? outcome.queries[0]?.query === params.query
                         : undefined,

package/dist/limits.js

@@ -0,0 +1,14 @@
+// The numbers more than one area has to agree on.
+//
+// Not policy or behaviour — a value several modules must spell the same way,
+// and a wrong copy makes two surfaces disagree about one session: a title
+// truncated to a different length depending on which path derived it.
+//
+// Here because a leaf may be imported by every area and depends on nothing
+// itself, which is the only shape that fits: agent/ derives a title and must
+// not import core/, web/ derives one too and must not import agent/, and the
+// browser needs the same numbers with no runtime behind them.
+/** How much of a message becomes a title, wherever one is derived: the listing
+ *  reading a transcript (agent/listing.ts), a rename's fallback (agent/pi.ts),
+ *  the fill at first prompt and the rename boundary (web/). */
+export const SESSION_TITLE_MAX = 80;

package/dist/main.js

@@ -14,7 +14,7 @@ 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, slackToolSpec } from "./channels/slack-tool.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 { pierDb } from "./db.js";
@@ -28,6 +28,8 @@ 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 { toolsTask } from "./tools-task.js";
 import { Secrets } from "./secrets.js";
 import { startUpdate, unitPath, updaterProblem } from "./service.js";
 import { SettingsStore } from "./settings.js";
@@ -52,6 +54,10 @@ const log = logger("pier");
 // again from this instance's own PIER_HOME.
 process.env.PI_CODING_AGENT_DIR = resolveAgentDir(process.env);
 process.env.PIER_AGENT_DIR = process.env.PI_CODING_AGENT_DIR;
+// Ahead of everything Pier spawns — sessions, tasks, the Web Terminal all
+// inherit this process's env. A tool switched on in the Console is Pier's
+// copy at Pier's version, so it goes first, not last.
+prependPath(process.env);
 // First, and explicitly: every store below shares this one connection, and a
 // schema that cannot be migrated must stop the process here — before a port is
 // open and before anything has written a row.
@@ -92,8 +98,9 @@ const factory = new PiAgentFactory([
             const config = channelStore.get("slack");
             return config.token ? new SlackApi(config.token, config.appToken) : null;
         },
-        // Which Slack thread this session is answering, so "post here" needs no
-        // ids. Looked up per call: the mapping is durable, the session is not.
+        // Which Slack thread this session is answering, so "post here" needs
+        // no ids. Looked up per call: the mapping is durable, the session is
+        // not.
         here: (sessionId) => {
             const key = router.conversationOf(sessionId);
             if (key?.channelId !== "slack")
@@ -102,7 +109,10 @@ const factory = new PiAgentFactory([
             return channel && threadTs ? { channel, threadTs } : null;
         },
         log: (m) => logger("slack.tool").warn(m),
-    }, params, callerSessionId)),
+    }, params, callerSessionId), 
+    // No Slack, no schema: an unconfigured tool would sit in every prompt of
+    // every session and be able to answer nothing.
+    () => slackToolAvailable(channelStore)),
 ], 
 // Called per session open, so a setting changed in the Console reaches the
 // next session without a restart.
@@ -135,6 +145,16 @@ tasks = new TaskService(new TaskStore(db), factory, router, hub, {
     modelMenu: () => settings.get().modelMenu,
 });
 tasks.start();
+// 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/.
+const managedTools = new ManagedTools();
+const toolsUpdate = toolsTask(tasks);
+// Before any route exists: two first flips could otherwise both find no task
+// and create one each. A failure here is logged, and the next flip retries.
+const reconciled = await toolsUpdate.reconcile();
+if ("problem" in reconciled)
+    log.error(`tools cannot be managed: ${reconciled.problem}`);
 channelStore = new ChannelStore(db, secrets);
 const control = createControl({ router, factory, conversations, store: channelStore });
 const channels = new ChannelRuntime(channelStore, router, control);
@@ -283,7 +303,7 @@ registerPushRoutes(app, {
     hub,
     unread: (id) => sessionState.unread(id),
     channelOf: (id) => router.conversationOf(id)?.channelId,
-    name: (id) => sessionState.name(id),
+    summary: (id) => factory.find(id),
     publicUrl: () => settings.get().publicUrl,
 });
 app.route("/", createServer({
@@ -296,7 +316,28 @@ app.route("/", createServer({
     settings,
     // The catalog is code, so the composition root is where it is read: web/
     // gets names and summaries, not a module that imports the Pi SDK.
-    extensions: () => bundledInfo(settings.get().extensions),
+    // One list, assembled where both halves are visible: the extensions Pier
+    // loads from inside itself and the binaries it installs are the same kind of
+    // switch to the person flipping it, and rtk is both.
+    catalog: async () => {
+        const { extensions, tools, customTools } = settings.get();
+        return {
+            entries: [...bundledInfo(extensions), ...await managedTools.status(tools, customTools)],
+            toolsTaskId: toolsUpdate.id(),
+        };
+    },
+    // Names only, and the same two lists the catalog above is built from: the
+    // route validates a switch against what this Pier *can* switch, which is
+    // code, 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) },
+    onToolsChanged: toolsUpdate.changed,
+    // The rule lives with the installer; the names the bundled catalog already
+    // owns live with the extensions. Only here are both in scope.
+    validateCustomTools: (raw) => {
+        const validated = normalizeCustomTools(raw, bundledInfo([]).map((entry) => entry.name));
+        return validated ? { tools: validated } : { error: CUSTOM_TOOL_RULES };
+    },
     secrets,
     updates,
     updater,

package/dist/paths.js

@@ -7,8 +7,13 @@
 // depend on and that depends on nothing.
 import { homedir } from "node:os";
 import { join } from "node:path";
+/** Empty is unset, not a value: `PIER_HOME=` in a shell would otherwise
+ *  resolve every path below relative to the working directory, and the
+ *  database, the boards and the master key would land wherever the process
+ *  happened to start. Pure, because that rule is worth a test. */
+export const resolveHome = (value, home = homedir()) => value || join(home, ".pier");
 /** `$PIER_HOME`, or `~/.pier`. Fixed for the life of the process. */
-export const PIER_HOME = process.env.PIER_HOME ?? join(homedir(), ".pier");
+export const PIER_HOME = resolveHome(process.env.PIER_HOME);
 /** A path inside it — `pierPath("boards")`. */
 export const pierPath = (...parts) => join(PIER_HOME, ...parts);
 /** The one SQLite file; every store opens this same path. In its own

package/dist/settings.js

@@ -9,6 +9,11 @@
 import { isThinkingLevel } from "./core/types.js";
 import { pierDb } from "./db.js";
 import { logger } from "./log.js";
+// The one place the custom-tool vocabulary lives (names, ubix sources, the
+// names Pier already owns). Imported rather than copied: a second validator
+// would be the third-copy bug one release later, and tools.ts is root-layer
+// like this file, so nothing crosses a seam.
+import { normalizeCustomTools } from "./tools.js";
 const log = logger("settings");
 /**
  * `""` clears it, `null` rejects it. Rejecting rather than repairing: a
@@ -94,6 +99,15 @@ export function normalizeTerminalInitCommand(raw) {
  * setting it cannot currently explain.
  */
 export function normalizeExtensions(raw) {
+    return normalizeNames(raw);
+}
+/** Same shape, same contract, same cap — the managed-tool set (src/tools.ts).
+ *  Shape only again: tools.ts owns the catalog, and a name it does not know is
+ *  ignored there rather than rejected here, so a downgrade cannot lose one. */
+export function normalizeTools(raw) {
+    return normalizeNames(raw);
+}
+function normalizeNames(raw) {
     if (!Array.isArray(raw) || raw.length > 32)
         return null;
     const names = new Set();
@@ -119,6 +133,8 @@ export class SettingsStore {
             autoUpdate: this.#value("autoUpdate") === "1",
             terminalInitCommand: this.#value("terminalInitCommand") ?? "",
             extensions: this.#json("extensions", normalizeExtensions, "a list of names") ?? [],
+            tools: this.#json("tools", normalizeTools, "a list of names") ?? [],
+            customTools: this.#json("customTools", normalizeCustomTools, "a list of {name, spec}") ?? [],
         };
     }
     /**
@@ -168,6 +184,34 @@ export class SettingsStore {
         this.#set("extensions", JSON.stringify(names));
         return this.get();
     }
+    /** Same contract again: hand this `normalizeTools`'s output. */
+    setTools(names) {
+        this.#set("tools", JSON.stringify(names));
+        return this.get();
+    }
+    /** Same contract again: hand this `normalizeCustomTools`'s output. */
+    setCustomTools(tools) {
+        this.#set("customTools", JSON.stringify(tools));
+        return this.get();
+    }
+    /**
+     * Several setters as one write. A request that declares a tool *and* the
+     * switch that turns it on must not be able to store one without the other:
+     * half of that pair is a switch nobody can explain — on and undeclared, or
+     * declared and invisible.
+     */
+    transact(work) {
+        this.#db.exec("BEGIN IMMEDIATE");
+        try {
+            const result = work();
+            this.#db.exec("COMMIT");
+            return result;
+        }
+        catch (err) {
+            this.#db.exec("ROLLBACK");
+            throw err;
+        }
+    }
     #set(key, value) {
         this.#db.prepare(`
       INSERT INTO settings(key, value) VALUES (?, ?)

package/dist/tasks/agent.js

@@ -1,5 +1,11 @@
+// A run that *is* a Pi session: which session it opens (reuse, fresh, fork),
+// 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
+// model's context and someone's rate limit.
 import { quietLabel, splitReply } from "../core/reply.js";
 import { Router } from "../core/router.js";
+import { runSource } from "./callbacks.js";
 import { TaskMessenger } from "./messages.js";
 import { TaskStore } from "./store.js";
 const MAX_ACTIVE_AGENTS = 4;
@@ -44,6 +50,12 @@ export class AgentTaskRunner {
             const session = await this.resolveSession(run, action);
             return await this.withSession(session.id, async () => {
                 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
+                // 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");
                 start();
                 // No input is no block: `<task_input>\nnull\n</task_input>` is four
                 // lines telling the agent nothing, on every run that has no input.
@@ -55,6 +67,10 @@ export class AgentTaskRunner {
                 const prompt = run.context.resumePrompt ?? `${preamble(run)}${action.prompt}${input}`;
                 run.context.sessionId = session.id;
                 run.context.model = session.model;
+                // The level the session settled on, not the one the task asked for:
+                // an unspecified effort inherits the caller's, and the card in the
+                // subagent's own transcript should say which one that was.
+                run.context.thinking = session.thinkingLevel;
                 run.context.renderedPrompt = prompt;
                 this.store.saveRun(run);
                 let text = "";
@@ -83,6 +99,7 @@ export class AgentTaskRunner {
                         taskId: run.taskId,
                         runId: run.id,
                         sourceSessionId: run.sourceSessionId,
+                        source: runSource(run),
                     }, "prompt");
                     await Promise.resolve();
                     this.messages.deliverPendingControls(run);
@@ -102,6 +119,10 @@ export class AgentTaskRunner {
                     return { type: "agent", text: reply.text || quietLabel(reply.silence), sessionId: session.id };
                 }
                 finally {
+                    // The run is what earns "short"; a reused interactive session goes
+                    // back to chat afterwards. For task-created sessions this is moot —
+                    // idle until the next run downgrades them again.
+                    session.setCacheRetention("long");
                     signal.removeEventListener("abort", abort);
                     unsubscribe();
                 }
@@ -115,9 +136,8 @@ export class AgentTaskRunner {
         if (run.targetSessionId) {
             return this.router.ensure({ channelId: "task", conversationId: run.targetSessionId });
         }
-        const listed = await this.factory.list();
         const source = run.sourceSessionId
-            ? listed.find((session) => session.id === run.sourceSessionId)
+            ? await this.factory.find(run.sourceSessionId)
             : undefined;
         const policy = action.session;
         let cwd;
@@ -130,7 +150,7 @@ export class AgentTaskRunner {
             cwd = policy.cwd;
         }
         else if (policy.mode === "reuse") {
-            cwd = listed.find((session) => session.id === policy.sessionId)?.cwd ?? "";
+            cwd = (await this.factory.find(policy.sessionId))?.cwd ?? "";
         }
         else {
             cwd = policy.cwd ?? source?.cwd ?? "";
@@ -145,7 +165,6 @@ export class AgentTaskRunner {
             model: action.launch?.model ??
                 (run.sourceSessionId ? this.router.modelOf(run.sourceSessionId) : undefined),
             thinking: action.launch?.thinking,
-            capabilities: action.launch?.capabilities,
         };
         const session = run.sessionMode === "fork"
             ? await this.factory.fork(run.sourceSessionId, opts)

package/dist/tasks/callbacks.js

@@ -3,6 +3,20 @@
 import { Router } from "../core/router.js";
 import { Outbox } from "./outbox.js";
 import { TaskStore } from "./store.js";
+/** How a run is named to the session that gets its result: the run id, and the
+ *  session that did the work — a relayer's next move is a deep link to it
+ *  (`#/session/<id>`), and without this line that costs a second tool call.
+ *  Shared with the group callback, which has always carried both. */
+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. Part
+ *  of the run vocabulary for the same reason `runRef` is: the callback, the
+ *  subagent messages and the delegation prompt all name a run, and three
+ *  spellings of "which task, on what model" would be three cards. */
+export const runSource = (run) => ({
+    taskName: run.context.definition.name,
+    ...(run.context.model ? { model: run.context.model } : {}),
+    ...(run.context.thinking ? { thinking: run.context.thinking } : {}),
+});
 export function runResultText(run) {
     let result = run.error ?? "No result";
     if (run.result?.type === "agent")
@@ -35,6 +49,11 @@ export class TaskCallbacks {
                     runId: runs[0].id,
                     sourceSessionId: runs[0].targetSessionId,
                     runIds: runs.map((run) => run.id),
+                    // Only when the input is about one run: a batch is several tasks in
+                    // one delivery, and the first one's name and model as the card's
+                    // caption would attribute every other result to it. The text names
+                    // each run; the card says nothing rather than something false.
+                    ...(runs.length === 1 ? { source: runSource(runs[0]) } : {}),
                 },
             }),
             describe: (run) => `the result of "${run.context.definition.name}"`,
@@ -69,7 +88,7 @@ export class TaskCallbacks {
     text(runs) {
         const sections = runs.map((run) => [
             `Task "${run.context.definition.name}" finished with state: ${run.state}`,
-            `Run: ${run.id}`,
+            runRef(run),
             "",
             runResultText(run),
         ].join("\n"));

package/dist/tasks/command.js

@@ -1,4 +1,9 @@
+// A bash task's script, run in its cwd with its input on stdin. The output is
+// capped as it arrives rather than after: a run that printed a gigabyte is a
+// run whose result still has to fit in a row, a transcript and a callback.
 import { spawn } from "node:child_process";
+import { logger } from "../log.js";
+const log = logger("tasks");
 const OUTPUT_LIMIT = 1024 * 1024;
 class CappedOutput {
     chunks = [];
@@ -69,6 +74,16 @@ export function runBash(script, cwd, input, signal) {
                 stderrTruncated: stderr.truncated,
             });
         });
+        // A script that never reads stdin is ordinary (`exit 0`, a one-line curl),
+        // and writing the input to a pipe nobody is holding raises EPIPE *here*.
+        // Unhandled, that is an `error` event on a stream, which is an uncaught
+        // exception, which is main.ts exiting the process: one task script could
+        // take every session and every other run down with it. The input not being
+        // wanted is not a failure of the run — anything else still gets said.
+        child.stdin.on("error", (err) => {
+            if (err.code !== "EPIPE")
+                log.warn(`run input could not be written: ${err.message}`);
+        });
         child.stdin.end(encodedInput);
     });
 }

package/dist/tasks/definitions.js

@@ -1,4 +1,8 @@
-import { randomUUID } from "node:crypto";
+// 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 —
+// arrives here, so a field is checked in one place or nowhere.
+import { randomBytes } from "node:crypto";
 import { stat } from "node:fs/promises";
 import { Cron } from "croner";
 import { isThinkingLevel } from "../core/types.js";
@@ -7,6 +11,46 @@ import { Router } from "../core/router.js";
 import { TaskStore } from "./store.js";
 const DEFAULT_TIMEOUT = 900;
 const MIN_WATCH_SECONDS = 5;
+/** Crockford's base32, lowercased: i, l, o and u are gone — the three that
+ *  misread as 1/0 and the one that completes most accidental words — and one
+ *  case throughout, so a model re-types an id it read verbatim. */
+const ID_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
+/** The one byte → symbol step, exported only so a test can walk all 256 byte
+ *  values: a repeated or omitted character in the alphabet above biases every
+ *  id ever minted, and no sample of finished ids can show it. */
+export const idSymbol = (byte) => ID_ALPHABET.charAt(byte & 31);
+/** The id every task record is minted with — runs, definitions, groups and
+ *  messages alike — because these ids ride through model context constantly:
+ *  every run summary, callback, get, steer and reply echoes one, and a UUID
+ *  spends ~12 tokens where this spends ~6. Nothing parses or orders by them —
+ *  every comparison in the area is string equality and every listing orders by
+ *  a timestamp column — so rows minted as UUIDs before this keep working
+ *  untouched; there is nothing to migrate. It lives here rather than in
+ *  types.ts because the browser type-checks that file and it stays node-free.
+ *
+ *  Sixteen characters, 80 bits (`& 31` is unbiased because 256 is a multiple
+ *  of 32). Sixty would have read the same and cost a token less, but a watch
+ *  task on a 5-second interval mints ~6M runs a year, and a collision here is
+ *  not an error: `saveRun`'s ON CONFLICT DO UPDATE would quietly overwrite the
+ *  older run with the newer one. Four more characters buy ~16 million times
+ *  the headroom for four bytes — cheaper than the alternative fix, which is a
+ *  strict INSERT and a retry loop on every one of the four mint sites. */
+export const newId = () => Array.from(randomBytes(16), idSymbol).join("");
+/**
+ * Seam decision (tasks/): a definition Pier's own code created is reconciled by
+ * that code, and edited by nobody.
+ *
+ * `creator` is `"http"` for the Console and `session:<id>` for the task tool.
+ * Anything else is an instance-layer owner — today the tools update task
+ * (src/tools-task.ts), whose script a switch in Settings runs on demand and
+ * cron runs nightly. Both
+ * public surfaces could rename it, point it at another script, pause it or
+ * archive it, and the switch would go on claiming Pier keeps the tools current
+ * while the run did something else entirely. The owner names itself in `by`;
+ * neither the routes nor the tool has a `by` to pass, so this one function
+ * closes both.
+ */
+const ownerOf = (task) => task.creator === "http" || task.creator.startsWith("session:") ? null : task.creator;
 export const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
     ? value
     : null;
@@ -76,12 +120,6 @@ function parseLaunch(raw) {
         }
         launch.thinking = value.thinking;
     }
-    if (value.capabilities !== undefined) {
-        if (value.capabilities !== "read" && value.capabilities !== "write") {
-            throw new Error("agent capabilities must be read or write");
-        }
-        launch.capabilities = value.capabilities;
-    }
     return Object.keys(launch).length ? launch : undefined;
 }
 export class TaskDefinitions {
@@ -110,7 +148,7 @@ export class TaskDefinitions {
         const draft = await this.parseDraft(value && value.trigger === undefined ? { ...value, trigger: { type: "manual" } } : raw);
         const now = Date.now();
         const task = {
-            id: randomUUID(),
+            id: newId(),
             kind,
             name: draft.name,
             description: draft.description ?? "",
@@ -133,8 +171,9 @@ export class TaskDefinitions {
         this.changed();
         return task;
     }
-    async update(id, raw) {
+    async update(id, raw, by) {
         const old = this.get(id);
+        this.assertOwner(old, by, "edited");
         if (old.archived)
             throw new Error("archived tasks cannot be edited");
         const draft = await this.parseDraft(raw);
@@ -158,8 +197,9 @@ export class TaskDefinitions {
         this.changed();
         return task;
     }
-    setEnabled(id, enabled) {
+    setEnabled(id, enabled, by) {
         const task = this.get(id);
+        this.assertOwner(task, by, enabled ? "resumed" : "paused");
         if (task.archived && enabled)
             throw new Error("archived tasks cannot be resumed");
         task.enabled = enabled;
@@ -169,8 +209,9 @@ export class TaskDefinitions {
         this.changed();
         return task;
     }
-    archive(id) {
+    archive(id, by) {
         const task = this.get(id);
+        this.assertOwner(task, by, "archived");
         task.archived = true;
         task.enabled = false;
         task.nextRunAt = null;
@@ -200,7 +241,14 @@ export class TaskDefinitions {
     }
     async sessionExists(sessionId) {
         return this.router.stateOf(sessionId) !== undefined ||
-            (await this.factory.list()).some((session) => session.id === sessionId);
+            (await this.factory.find(sessionId)) !== undefined;
+    }
+    /** The guard `ownerOf` exists for, on the three ways a definition changes. */
+    assertOwner(task, by, what) {
+        const owner = ownerOf(task);
+        if (owner && by !== owner) {
+            throw new Error(`"${task.name}" is Pier's own ${owner} task: it is reconciled by Pier, not ${what}`);
+        }
     }
     async parseDraft(raw) {
         const value = record(raw);

package/dist/tasks/execution.js

@@ -1,3 +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.
 import { logger } from "../log.js";
 import { AgentTaskRunner } from "./agent.js";
 import { TaskCallbacks } from "./callbacks.js";
@@ -56,7 +60,11 @@ export class TaskExecution {
                 run.result = await this.executeAction(run, controller.signal);
             run.state = "succeeded";
             if (definition.trigger.type === "watch" && !run.resumedFromRunId && definition.trigger.mode === "once" && run.matched) {
-                this.definitions.setEnabled(definition.id, false);
+                // As the definition's own creator: a one-shot watch retiring itself is
+                // the task layer keeping its own promise, not a surface editing
+                // somebody's task, and the owner guard (definitions.ts) would
+                // otherwise fail the run that had just succeeded.
+                this.definitions.setEnabled(definition.id, false, definition.creator);
             }
         }
         catch (error) {

package/dist/tasks/groups.js

@@ -1,7 +1,11 @@
-import { randomUUID } from "node:crypto";
+// The fan-out join: members start detached, and the group is what turns their
+// separate endings into one answer — when the join condition is met, which
+// members are cancelled, and the single aggregated callback that goes back.
+// Delivering it is the outbox's job; deciding it is this file's.
 import { Router } from "../core/router.js";
 import { logger } from "../log.js";
-import { runResultText } from "./callbacks.js";
+import { runRef, runResultText } from "./callbacks.js";
+import { newId } from "./definitions.js";
 import { Outbox } from "./outbox.js";
 import { TaskStore } from "./store.js";
 import { isTerminal } from "./types.js";
@@ -61,7 +65,7 @@ export class TaskGroups {
     }
     create(join, invokedBySessionId, callbackSessionId) {
         const group = {
-            id: randomUUID(),
+            id: newId(),
             join,
             invokedBySessionId,
             callbackSessionId,
@@ -137,7 +141,7 @@ export class TaskGroups {
         const sections = members.map((run) => {
             const head = [
                 `- "${run.context.definition.name}" \u2014 state: ${run.state}`,
-                `  Run: ${run.id}${run.targetSessionId ? ` / Session: ${run.targetSessionId}` : ""}`,
+                `  ${runRef(run)}`,
             ];
             const decision = this.host.openDecisionId(run.id);
             if (decision)