@timqi/pier 0.1.0 → 0.1.2

package/dist/drain.js

@@ -1,20 +1,12 @@
 // A graceful restart: refuse new work, let running turns finish, and write
-// down what the deadline had to cut off so the next boot can tell the chats.
-//
-// The trigger is SIGUSR2 (main.ts); systemd's `Restart=always` is the "start
-// again" half. SIGTERM stays the fast path systemd expects — this file is only
-// the slow one. Nothing here is persisted for its own sake: everything durable
-// (transcripts, the chat → session map, task runs) already survives a restart,
-// so the ledger below holds only the one thing that would otherwise vanish
-// silently — turns and queued messages the deadline aborted (§5b).
+// down what the deadline cut off so the next boot can tell the chats (§5).
+// Everything else durable already survives a restart.
 import { logger } from "./log.js";
 const log = logger("drain");
-/** How long running turns may take before they are aborted. Generous: a turn
- *  can be a subagent fan-out, and an abort still persists the partial work. */
+/** Generous: a turn can be a subagent fan-out. */
 const DRAIN_DEADLINE_MS = 5 * 60_000;
 const POLL_MS = 1_000;
-/** Shared cleanup window after the deadline. All sessions use the same clock,
- *  so N hung seams still cost at most this long rather than N times as long. */
+/** Shared across sessions, so N hung seams cost this long, not N times it. */
 const CLEANUP_BOUND_MS = 10_000;
 /** What the dying process owes the chats, held for the next one to deliver. */
 export class RestartLedger {
@@ -38,13 +30,9 @@ export class RestartLedger {
         this.db.prepare("DELETE FROM restart_ledger WHERE id = ?").run(id);
     }
 }
-/**
- * Resolve when the process may exit: every turn settled and every task run
- * terminal, or the deadline reached and the stragglers aborted into the
- * ledger. The caller (main.ts) owns what happens next — the ordinary shutdown,
- * minus aborting task runs: the boot-time interrupted marking is the recovery
- * path (tasks/service.ts start()), not a teardown race against dying channels.
- */
+/** Resolves when the process may exit: everything settled, or the deadline
+ *  reached and the stragglers aborted into the ledger. Task runs are left to
+ *  the boot-time interrupted marking (tasks/service.ts). */
 export async function drainForRestart(deps, deadlineMs = DRAIN_DEADLINE_MS, pollMs = POLL_MS, cleanupBoundMs = CLEANUP_BOUND_MS) {
     const { router, tasks, ledger } = deps;
     router.beginDrain();
@@ -53,29 +41,38 @@ export async function drainForRestart(deps, deadlineMs = DRAIN_DEADLINE_MS, poll
     let lastReport = "";
     for (;;) {
         // Sleep first: a prompt accepted just before the gate closed may not have
-        // flipped its session to streaming yet, and exiting on that blink would
-        // cut off the very turn the drain exists to protect.
+        // flipped its session to streaming yet.
         await new Promise((resolve) => setTimeout(resolve, pollMs));
         const busy = router.busy();
         const runs = tasks.activeRunCount();
         if (busy.length === 0 && runs === 0) {
             log.info("drained — nothing running");
+            await queuesToLedger(router, ledger, new Set(), Date.now() + cleanupBoundMs);
             return;
         }
+        const turns = busy.filter((b) => !b.sending);
+        const sends = busy.filter((b) => b.sending);
         if (Date.now() >= deadline) {
-            log.warn(`drain deadline after ${String(Math.round(deadlineMs / 1000))}s — aborting ${String(busy.length)} turn(s); ` +
-                `${String(runs)} task run(s) will be marked interrupted at boot`);
+            log.warn(`drain deadline after ${String(Math.round(deadlineMs / 1000))}s — aborting ${String(turns.length)} turn(s), ` +
+                `${String(sends.length)} reply(ies) still sending; ${String(runs)} task run(s) will be marked interrupted at boot`);
+            // A send cannot be aborted, only owned up to: the exit will cut it off.
+            for (const { key } of sends) {
+                ledger.record({
+                    channelId: key.channelId, conversationId: key.conversationId,
+                    note: "Pier restarted while sending the last answer — it may have arrived incomplete; the session transcript has all of it.",
+                });
+            }
             const cleanupDeadline = Date.now() + cleanupBoundMs;
-            await Promise.all(busy.map(({ session, key }) => abortToLedger(session, key, ledger, cleanupDeadline)));
+            await Promise.all(turns.map(({ session, key }) => abortToLedger(session, key, ledger, cleanupDeadline)));
+            await queuesToLedger(router, ledger, new Set(turns.map(({ session }) => session.id)), cleanupDeadline);
             return;
         }
-        const report = `draining: ${String(busy.length)} turn(s), ${String(runs)} active task run(s)`;
+        const report = `draining: ${String(turns.length)} turn(s), ${String(sends.length)} reply(ies) sending, ${String(runs)} active task run(s)`;
         if (report !== lastReport)
             log.info((lastReport = report));
     }
 }
-/** A seam call the deadline cannot wait on forever: a hang or a rejection is
- *  logged and answered with the fallback, and cleanup moves on. */
+/** A hang or a rejection is logged and answered with the fallback. */
 async function bounded(work, ms, what, fallback) {
     let timer;
     const timeout = new Promise((resolve) => {
@@ -99,37 +96,47 @@ async function bounded(work, ms, what, fallback) {
             clearTimeout(timer);
     }
 }
-/** Write the chat's entry, then abort the turn. The ledger comes first so a
- *  hung abort cannot cost the note; the abort persists the partial transcript;
- *  the pending queue would just vanish, so its texts ride along. */
+/** Ledger first, so a hung abort cannot cost the note; the pending queue would
+ *  just vanish, so its texts ride along. */
 async function abortToLedger(session, key, ledger, cleanupDeadline) {
     const remaining = () => Math.max(0, cleanupDeadline - Date.now());
-    const queued = await bounded(session.pendingQueue(), remaining(), `queue snapshot of session ${session.id}`, { steering: [], followUp: [] });
-    const pending = [...queued.steering, ...queued.followUp];
-    // A web or task key has no chat to write to: the transcript shows the
-    // aborted turn, and a task run's interruption is reported by its callback
-    // recovery. Only a dropped queue would be invisible there, so it is at
-    // least logged.
+    recordRestartNote(ledger, session, key, await queueSnapshot(session, remaining()));
+    await bounded(session.abort(), remaining(), `abort of session ${session.id}`, undefined);
+}
+/** Pi's queue lives only in the runtime, so the exit ends it whether a turn was
+ *  running or not: an attached session nobody was waiting on still owes its
+ *  chat the texts it never got to (§5). `handled` are the aborted turns, whose
+ *  note already carries their queue. */
+async function queuesToLedger(router, ledger, handled, cleanupDeadline) {
+    await Promise.all(router.attachedSessions()
+        .filter(({ session }) => !handled.has(session.id))
+        .map(async ({ session, key }) => {
+        const pending = await queueSnapshot(session, Math.max(0, cleanupDeadline - Date.now()));
+        if (pending.length)
+            recordRestartNote(ledger, session, key, pending);
+    }));
+}
+async function queueSnapshot(session, boundMs) {
+    const queued = await bounded(session.pendingQueue(), boundMs, `queue snapshot of session ${session.id}`, { steering: [], followUp: [] });
+    return [...queued.steering, ...queued.followUp];
+}
+function recordRestartNote(ledger, session, key, pending) {
+    // A web or task key has no chat: the transcript shows the aborted turn, and
+    // only a dropped queue would be invisible, so that is logged.
     if (key.channelId === "web" || key.channelId === "task") {
         if (pending.length) {
             log.warn(`session ${session.id}: ${String(pending.length)} queued message(s) dropped by the restart`);
         }
+        return;
     }
-    else {
-        const note = [
-            "Pier restarted before this turn finished — the last message may be unanswered.",
-            ...(pending.length ? ["Queued and not delivered:", ...pending.map((text) => `> ${text}`)] : []),
-        ].join("\n");
-        ledger.record({ channelId: key.channelId, conversationId: key.conversationId, note });
-    }
-    await bounded(session.abort(), remaining(), `abort of session ${session.id}`, undefined);
+    const note = [
+        "Pier restarted before this turn finished — the last message may be unanswered.",
+        ...(pending.length ? ["Queued and not delivered:", ...pending.map((text) => `> ${text}`)] : []),
+    ].join("\n");
+    ledger.record({ channelId: key.channelId, conversationId: key.conversationId, note });
 }
-/**
- * Deliver what a previous process wrote on its way out. Runs at boot once the
- * adapters are up, and again on a Console unlock. Each entry is removed only
- * after confirmed delivery. A missing adapter or a thrown notification keeps
- * the debt for the next start: a duplicate apology is preferable to silence.
- */
+/** Each entry is removed only after confirmed delivery: a duplicate apology is
+ *  preferable to silence. */
 export async function deliverLedger(ledger, notify) {
     for (const entry of ledger.list()) {
         const target = `${entry.channelId}:${entry.conversationId}`;

package/dist/extensions/index.js

@@ -1,14 +1,6 @@
-// The extensions Pier ships with — the list, and nothing else.
-//
-// An extension is Pi-shaped by construction (it takes an ExtensionAPI), so
-// this area is the second one allowed to import the Pi SDK. Nothing outside
-// agent/ imports it: the Console sees names and summaries, which agent/ hands
-// over as plain data through the ConfigStore seam.
-//
-// Bundled rather than dropped in <agentDir>/extensions because a copy on disk
-// has an owner problem — an update either clobbers the user's edits or skips
-// them forever. These ship inside the package, load as inline factories, and
-// stand down when a copy on disk already registers the same tools.
+// The extensions Pier ships with. Bundled rather than dropped in
+// <agentDir>/extensions because a copy on disk has an owner problem: an update
+// either clobbers the user's edits or skips them forever.
 import web from "./web/index.js";
 export const BUNDLED = [
     {

package/dist/extensions/web/anthropic.js

@@ -22,14 +22,8 @@ const findCode = (value) => {
         return undefined;
     return typeof value.error_code === "string" ? value.error_code : findCode(value.content);
 };
-/**
- * Every server-tool failure in the turn. A list, not the first one, and not a
- * throw: these arrive per invocation — the third search can fail while the
- * first two are in the transcript and the briefing is written from them. This
- * used to abort the whole call on any of them, which threw away a good answer
- * over `max_uses_exceeded`, a code we provoke ourselves by budgeting the
- * searches the prompt then asks for.
- */
+/** A list, not a throw: the third search can fail (`max_uses_exceeded`, which
+ *  our own budget provokes) while the briefing is written from the first two. */
 function toolErrors(content) {
     const codes = [];
     for (const block of content) {
@@ -58,7 +52,7 @@ function hasContent(content) {
 }
 export async function callNativeTool(request, name, prompt, options, signal, 
 /** Progress for the surface the call came from: a hosted search is tens of
- *  seconds of nothing otherwise (§5b). */
+ *  seconds of nothing otherwise (§5). */
 note) {
     const tool = {
         type: NATIVE_TOOL_TYPES[name],

package/dist/extensions/web/artifacts.js

@@ -38,11 +38,8 @@ const digest = (value) => createHash("sha256").update(value).digest("hex").slice
 export async function saveArtifact(url, text, retrievedAt) {
     await mkdir(ARTIFACT_DIR, { recursive: true, mode: 0o700 });
     const host = url.hostname.replace(/[^a-zA-Z0-9.-]+/g, "-").slice(0, 80) || "page";
-    // The URL alone is not the file's identity: a page fetched again is a
-    // different document, and keying on the URL overwrote the copy an older
-    // transcript's `artifactPath` still points at — the one promise this file
-    // makes. Content decides, so a refetch that changed writes a new file and one
-    // that did not costs nothing.
+    // Content in the key: keying on the URL alone would overwrite the copy an
+    // older transcript's `artifactPath` still points at.
     const path = join(ARTIFACT_DIR, `${host}-${digest(url.toString())}-${digest(text)}.md`);
     const temporary = `${path}.${randomUUID()}.tmp`;
     const header = [

package/dist/extensions/web/content.js

@@ -1,17 +1,9 @@
-// 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.
+// What a provider's answer becomes on the way to the model: one shape for both
+// backends, so nothing past this file knows which one replied.
 import { isObject } from "./json.js";
 import { languageLabel } from "./language.js";
-/**
- * The one reader of a cited page, wherever it turns up: an Anthropic search
- * result, a citation on a text block, a fetch result, an OpenAI action source.
- * All four spell it `{url, title?}` (OpenAI sometimes as a bare string), all
- * four had their own copy of this, and they disagreed about the fallback
- * title. Keyed by url; the first real title wins over a url used as one.
- */
+/** The one reader of a cited page: `{url, title?}`, or a bare string from
+ *  OpenAI. Keyed by url; the first real title wins over a url used as one. */
 export function putSource(into, value) {
     const url = typeof value === "string"
         ? value

package/dist/extensions/web/http.js

@@ -33,12 +33,8 @@ function retryDelay(response, attempt) {
     // instant, so a fixed backoff has them all come back at the same instant too.
     return Math.round(500 * 2 ** attempt * (0.5 + Math.random()));
 }
-/**
- * Interruptible, because the backoff is inside the caller's deadline: a
- * `retry-after` sleep of up to 20s followed by a whole further request is how a
- * 90-second ceiling turned into two minutes. Rejects on abort; the caller
- * reports the failure that caused the backoff, which is the useful half.
- */
+/** Interruptible: the backoff is inside the caller's deadline, and a 20s
+ *  `retry-after` plus another request would overrun a 90-second ceiling. */
 const sleep = (ms, signal) => new Promise((resolve, reject) => {
     if (signal?.aborted)
         return reject(signal.reason);

package/dist/extensions/web/language.js

@@ -1,8 +1,6 @@
-// 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.
+// The language-preservation policy: what the model is told to search in, and
+// the audit that checks it read from the same file. A hosted search that
+// quietly translates a Chinese query answers a question nobody asked.
 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."
@@ -18,22 +16,14 @@ export function searchPrompt(query, mode) {
         "Do not describe your process.",
     ].join("\n");
 }
-/**
- * The audit rule: the backend must stay in the query's language. Verbatim echo is
- * not the test — OpenAI's hosted search always composes its own wording, and
- * demanding an exact match there would buy a second search on every call.
- */
+/** Verbatim echo is not the test: OpenAI's hosted search always composes its
+ *  own wording, and an exact match would buy a second search on every call. */
 export function preservesLanguage(query, searched) {
     return searched !== undefined && languageLabel(searched) === languageLabel(query);
 }
-/**
- * A script, not a language, and named as loosely as the audit needs: it only
- * has to tell "the backend stayed where the query was" from "it translated".
- * Kana before Han, because Japanese is mostly Han characters and the reverse
- * order labelled 「東京 の天気」 Chinese in the warning it printed. Kanji-only
- * Japanese is still indistinguishable from Chinese here, and no ordering fixes
- * that — it needs a dictionary, which this is deliberately not.
- */
+/** A script, not a language. Kana before Han: Japanese is mostly Han
+ *  characters. Kanji-only Japanese stays indistinguishable from Chinese; that
+ *  needs a dictionary, which this is deliberately not. */
 export function languageLabel(text) {
     if (/\p{Script=Hiragana}|\p{Script=Katakana}/u.test(text))
         return "Japanese";

package/dist/extensions/web/openai.js

@@ -61,7 +61,7 @@ function parse(data, output, model) {
     };
 }
 export async function webSearchViaResponses(request, prompt, options, signal, 
-/** Progress for the surface the call came from (§5b). */
+/** Progress for the surface the call came from (§5). */
 note) {
     const tool = { type: "web_search" };
     const filters = {};

package/dist/extensions/web/provider.js

@@ -9,15 +9,8 @@ const DEFAULT_MODEL = {
 };
 /** The one escape hatch: an endpoint that has neither default model. */
 const CONFIGURED_MODEL = process.env.PIER_WEB_MODEL?.trim();
-/**
- * Candidates for a backend, best first: the configured tool model, the
- * backend's cheap default, then the session's own model when it happens to be
- * on the right API. Every one of those is a model somebody named — there is
- * deliberately no "any other model on this API" step, because the model a
- * search runs on decides its cost, its refusals and its results, and picking
- * an unnamed one on the user's behalf is how a search ends up on whatever
- * unreleased id a gateway happened to list first.
- */
+/** Every candidate is a model somebody named; no "any other model on this API"
+ *  step, or a search ends up on whatever unreleased id a gateway listed first. */
 function candidates(ctx, backend) {
     const api = BACKEND_API[backend];
     const registry = ctx.modelRegistry;
@@ -78,10 +71,8 @@ async function target(ctx, backend, model, outputTokens) {
     if (!hasAuthHeader(headers))
         throw new Error(`No ${backend} authentication resolved`);
     const limit = typeof model.maxTokens === "number" && model.maxTokens > 0 ? model.maxTokens : 4096;
-    // Responses spends reasoning tokens out of `max_output_tokens` too, so the
-    // same budget buys a fraction of the prose there — a reasoning model can burn
-    // the lot and return an empty answer. The caller asks for what it wants to
-    // read; this is the one place that knows which wire it goes out on.
+    // Responses spends reasoning tokens out of `max_output_tokens` too; a
+    // reasoning model can burn the lot and return an empty answer.
     const wanted = backend === "openai" ? outputTokens * 2 : outputTokens;
     return {
         backend,
@@ -91,11 +82,7 @@ async function target(ctx, backend, model, outputTokens) {
         maxTokens: Math.max(128, Math.min(wanted, limit)),
     };
 }
-/**
- * `capable` narrows the backends that can serve the call — web_fetch is an
- * Anthropic-only server tool, so it passes ["anthropic"]. `requested` is the
- * caller's explicit choice; without one both are tried in order.
- */
+/** `capable`: web_fetch is an Anthropic-only server tool. */
 export async function resolveTarget(ctx, outputTokens, capable = ["anthropic", "openai"], requested) {
     const wanted = (requested ? [requested] : capable).filter((backend) => capable.includes(backend));
     if (!wanted.length) {

package/dist/extensions/web/tools.js

@@ -1,8 +1,5 @@
-// 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.
+// The two tools as the model sees them. Every parameter is context the model
+// pays for on every turn, so the surface is deliberately small.
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { callNativeTool } from "./anthropic.js";
@@ -15,29 +12,13 @@ const DEFAULT_CONTEXT_CHARS = 6_000;
 const SEARCH_RESULTS = 8;
 /** `mode: "full"` is "the document", not "the transcript's whole budget". */
 const FULL_MAX_CHARS = 60_000;
-/**
- * What we pay the search model to generate. It has to cover the whole assistant
- * turn — the search calls it makes plus the briefing it writes — and it must
- * 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, 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.
- */
+/** Must cover the CJK reading of `DEFAULT_CONTEXT_CHARS` (6k chars ≈ 4k
+ *  Chinese tokens, ~1.5k English) plus the search calls, or briefings stop
+ *  mid-sentence. A hosted search costs an order of magnitude more than the prose. */
 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
- * model may generate, and how much of the digest reaches the caller. They were
- * two tool parameters (`max_context_chars`, `max_content_tokens`) that only
- * ever restated the mode, and every parameter is read by the model on every
- * turn. `full` returns the document itself, so its digest budget is an
- * acknowledgement — generation nobody reads.
- */
+/** One dial: `mode` decides all three sizes, since separate parameters only
+ *  ever restated it. `full` returns the document, so its digest budget is an
+ *  acknowledgement nobody reads. */
 const FETCH_LIMITS = {
     concise: { fetch: 10_000, generate: 1_200, digest: 6_000 },
     thorough: { fetch: 25_000, generate: 3_500, digest: 12_000 },
@@ -53,14 +34,8 @@ function clampText(text, maxChars) {
         return text;
     return `${text.slice(0, maxChars).trimEnd()}\n\n[truncated ${text.length - maxChars} characters]`;
 }
-/**
- * One ceiling for the whole tool call. The per-request timeout in http.ts is
- * not one: three attempts, times up to three continuation rounds, times a
- * language-audit retry, is tens of minutes — and Pi puts no timeout of its own
- * on a custom tool, so that is a turn held open with nothing to show. An
- * aborted caller signal already stops the retry loop, so this is the only
- * thing needed to bound it.
- */
+/** The per-request timeout is not a ceiling: attempts × continuation rounds ×
+ *  the audit retry is tens of minutes, and Pi puts no timeout on a custom tool. */
 const CALL_CEILING_MS = 90_000;
 const ceiling = (signal) => {
     const own = AbortSignal.timeout(CALL_CEILING_MS);
@@ -78,11 +53,6 @@ async function runSearch(run) {
     const result = await callNativeTool(target, "web_search", prompt, { maxUses, ...domains }, signal, note);
     return searchOutcomeFrom(result.content, result.model, target.backend, result);
 }
-// Every parameter here is read by the model on every turn it might search, so
-// each one is a standing cost. `max_uses` and `max_results` were knobs nobody
-// turned: the first did nothing on the OpenAI backend and had to say so out
-// loud in its own results, and the second only sliced a list the caller can
-// read the whole of.
 export const webSearch = defineTool({
     name: "web_search",
     label: "Web Search",
@@ -116,11 +86,8 @@ export const webSearch = defineTool({
             let outcome = await runSearch({ ...run, mode, maxUses: searchRounds(mode) });
             const wantedLanguage = languageLabel(params.query);
             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.
+            // `preserve` promised every search stays in the language; auto and expand
+            // buy English supplements on purpose, so there only the first query decides.
             const inLanguage = (o, auditAll) => auditAll
                 ? o.queries.length > 0 && strayed(o).length === 0
                 : preservesLanguage(params.query, o.queries[0]?.query);
@@ -147,7 +114,7 @@ export const webSearch = defineTool({
                     : "";
             // 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).
+            // is told (§5).
             const cut = outcome.truncated
                 ? "Warning: the briefing hit the search model's output limit and stops mid-sentence."
                 : "";
@@ -240,12 +207,9 @@ export const webFetch = defineTool({
                 : document.text
                     ? clampText(document.text, limits.digest)
                     : "Fetch completed.";
-            // `full` means the document, not the digest — but not without a ceiling:
-            // max_content_tokens is the model's to choose and reaches 100k, which is
-            // a transcript nobody can read and a context nobody can afford. The whole
-            // copy is on disk either way, and the note below points at it. A question
-            // is still answered, above the document; "OK" is not, it is the receipt
-            // for a digest we asked it not to write.
+            // `full` still has a ceiling: 100k tokens is a context nobody can afford,
+            // and the whole copy is on disk. "OK" is the receipt for a digest we
+            // asked it not to write, not an answer.
             const output = mode !== "full" ? distilled : [
                 question && answer ? clampText(answer, FETCH_LIMITS.concise.digest) : "",
                 document.text ? clampText(document.text, limits.digest) : "",
@@ -291,17 +255,9 @@ function parsePublicUrl(value) {
     url.hash = "";
     return url;
 }
-/**
- * Throwing is the only way to report a failed tool call: Pi's agent loop marks
- * the result an error when `execute` throws and ignores an `isError` field in a
- * returned result (`agent-loop.js`: `return { result, isError: false }`). These
- * tools used to return one, so every refusal they reported — a bad URL, a dead
- * endpoint, a hosted tool that never ran — was recorded as a success with an
- * apology in it.
- *
- * Our own ceiling also looks like a cancellation from the outside; say which one
- * it was, or the caller reads "aborted" and cannot tell whether it did that.
- */
+/** Throwing is the only way to report a failed tool call: Pi ignores an
+ *  `isError` field in a returned result (`agent-loop.js`). Our own ceiling
+ *  looks like a cancellation from outside, so say which one it was. */
 function fail(error, until, caller) {
     const message = error instanceof Error ? error.message : String(error);
     const gaveUp = until?.aborted && !caller?.aborted;

package/dist/lock.js

@@ -0,0 +1,98 @@
+// One Pier per instance directory: the ownership claim, taken before anything
+// under PIER_HOME is opened. A pid file, because Node's stdlib has no advisory
+// locking and the pid is what makes a crashed holder's claim reclaimable.
+import { closeSync, fstatSync, linkSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { PIER_LOCK } from "./paths.js";
+/** Unreadable, gone, or not a pid: no holder anyone can name, so the file is
+ *  not evidence of one. */
+function holder(file) {
+    try {
+        const pid = Number(readFileSync(file, "utf8").trim());
+        return Number.isInteger(pid) && pid > 0 ? pid : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** EPERM is a live process owned by someone else; only ESRCH proves it is gone. */
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/** The pid is written to a private file and hard-linked into place: the link
+ *  either creates the lock with the pid already in it or fails EEXIST, so no
+ *  racer can ever read an empty lock. */
+function take(path) {
+    const mine = `${path}.${String(process.pid)}`;
+    writeFileSync(mine, `${String(process.pid)}\n`, { mode: 0o600 });
+    try {
+        linkSync(mine, path);
+    }
+    catch (err) {
+        if (err.code === "EEXIST")
+            return null;
+        throw err;
+    }
+    finally {
+        rmSync(mine, { force: true });
+    }
+    // Only ours: a stale-lock takeover elsewhere may have replaced the file.
+    return {
+        release: () => {
+            if (holder(path) === process.pid)
+                rmSync(path, { force: true });
+        },
+    };
+}
+/** Moves the stale file aside under a name only this pid uses — never an unlink
+ *  in place — then checks it moved the inode it read; a racer's fresh claim that
+ *  landed in between goes straight back. ENOENT is the other reclaimer winning. */
+function reclaim(path, fd) {
+    const aside = `${path}.${String(process.pid)}.stale`;
+    try {
+        renameSync(path, aside);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return;
+        throw err;
+    }
+    if (statSync(aside, { bigint: true }).ino === fstatSync(fd, { bigint: true }).ino)
+        rmSync(aside, { force: true });
+    else
+        renameSync(aside, path);
+}
+export function acquireInstanceLock(path = PIER_LOCK) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const first = take(path);
+    if (first)
+        return first;
+    // Held open across the reclaim: an open inode cannot be reused by a new file,
+    // so the comparison in `reclaim` is exact.
+    let fd;
+    try {
+        fd = openSync(path, "r");
+    }
+    catch {
+        fd = undefined;
+    }
+    if (fd !== undefined) {
+        try {
+            const pid = holder(fd);
+            if (pid !== null && alive(pid))
+                return { heldBy: pid };
+            reclaim(path, fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    // The retry can only lose to another start that claimed the same directory.
+    return take(path) ?? { heldBy: holder(path) };
+}