@timqi/pier 0.1.0 → 0.1.1

package/dist/log.js

@@ -1,52 +1,35 @@
-// What Pier writes to its own log, and the one place that decides how it looks.
-//
-// The destination is stdout/stderr and nothing else — no files, no rotation, no
-// log configuration. Under systemd that *is* the log: journald stamps the time,
-// keeps the history, rotates it and lets `journalctl -p warning` filter it
-// (docs/deploy.md), and in a terminal it is the terminal. A logger that opened
-// its own file would duplicate all of that and hide half the output from
-// `journalctl` — the one place an operator actually looks.
-//
-// Like paths.ts, this is a leaf everything may import and that imports nothing:
-// a log line is not a seam crossing, so no area owns it.
+// What Pier writes to its own log. stdout/stderr only: under systemd journald
+// is the log (timestamps, history, rotation, `journalctl -p warning`), and a
+// file of our own would hide half the output from it.
 import { homedir } from "node:os";
 const ORDER = ["debug", "info", "warn", "error"];
 /** `silent` exists for test runs, which drive failure paths on purpose. */
 const THRESHOLDS = [...ORDER, "silent"];
 const isThreshold = (value) => THRESHOLDS.includes(value);
 const RANK = { debug: 0, info: 1, warn: 2, error: 3, silent: 4 };
-/** `PIER_LOG=debug` turns on the per-message tracing; default keeps it out. */
 const raw = (process.env.PIER_LOG ?? "").toLowerCase();
 const threshold = isThreshold(raw) ? raw : "info";
-// systemd sets JOURNAL_STREAM when our output goes to the journal. There the
-// time and the level are journal fields, not text: a `<N>` prefix is how a
-// plain stream tells journald its priority (sd-daemon(3)), so the same line
-// that reads well in a terminal stays greppable *and* filterable by level.
+// systemd sets JOURNAL_STREAM when output goes to the journal; a `<N>` prefix
+// is how a plain stream tells journald its priority (sd-daemon(3)).
 const toJournal = process.env.JOURNAL_STREAM !== undefined;
 const PRIORITY = { debug: "<7>", info: "<6>", warn: "<4>", error: "<3>" };
-/** `$HOME` back to `~`: a log line is read by a human, and paths dominate.
- *  Skipped when `$HOME` is `/` (containers do this), where it would rewrite
- *  every slash in every message. */
+/** Skipped when `$HOME` is `/` (containers), where it would rewrite every slash. */
 const home = homedir();
 const shorten = (text) => home.length > 1 ? text.replaceAll(home, "~") : text;
-/** An Error contributes its stack — the post-mortem is why it was logged. */
 const describe = (cause) => cause instanceof Error ? (cause.stack ?? `${cause.name}: ${cause.message}`) : String(cause);
 function write(level, area, message, cause) {
     if (RANK[level] < RANK[threshold])
         return;
     const text = shorten(cause === undefined ? message : `${message}: ${describe(cause)}`);
-    // Per line, not per message: journald reads a prefix off each line, so a
-    // stack's frames would otherwise land at the default priority — and a
-    // newline in something a browser reported would let it forge a level.
+    // Per line: journald reads a prefix off each line, and a newline in
+    // something a browser reported would otherwise let it forge a level.
     const line = toJournal
         ? text.split("\n").map((part, i) => `${PRIORITY[level]}${i === 0 ? `${area}: ` : ""}${part}`).join("\n")
         : `${new Date().toISOString()} ${level.toUpperCase().padEnd(5)} ${area}: ${text}`;
-    // Warnings and errors on stderr: it is what journald and every wrapper
-    // already treat as the abnormal stream, with or without the prefix above.
     const stream = level === "warn" || level === "error" ? process.stderr : process.stdout;
     stream.write(`${line}\n`);
 }
-/** `logger("slack")` — the area is the grep handle, so keep it stable. */
+/** The area is the grep handle, so keep it stable. */
 export const logger = (area) => ({
     debug: (message, cause) => write("debug", area, message, cause),
     info: (message, cause) => write("info", area, message, cause),

package/dist/main.js

@@ -27,6 +27,7 @@ import { deliverLedger, drainForRestart, RestartLedger } from "./drain.js";
 import { bundledInfo } from "./extensions/index.js";
 import { surfacePrompt } from "./core/reply.js";
 import { Router } from "./core/router.js";
+import { acquireInstanceLock } from "./lock.js";
 import { logger } from "./log.js";
 import { registerTaskRoutes } from "./tasks/routes.js";
 import { TaskService } from "./tasks/service.js";
@@ -45,51 +46,41 @@ import { PushStore, registerPushRoutes } from "./web/push.js";
 import { SessionStateStore } from "./web/session-state.js";
 import { createServer } from "./web/server.js";
 const log = logger("pier");
-// Pier owns the Pi runtime dir. Set before any SDK call resolves a path, so
-// everything Pi derives from its agent dir (auth.json, models.json, sessions,
-// bin) lands under PIER_HOME instead of ~/.pi.
-//
-// An operator override wins — but only a human's. Everything Pier spawns (the
-// agent's own shell, task sessions) inherits this variable, so a second
-// Pier started from inside the first with its own PIER_HOME would adopt the
-// first one's agent dir and write its sessions, SYSTEM.md and models.json
-// there: two instances sharing a directory neither was told to share, and
-// PIER_HOME looking like it did nothing. PIER_AGENT_DIR marks the value as
-// ours, and a value that is ours is not an override, it is a leak — derive it
-// again from this instance's own PIER_HOME.
+// 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
+// Pier spawned from inside the first inherits it, and an inherited value is a
+// leak, not an operator override (paths.ts).
 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 and tasks 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.
+// 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.
+const lock = acquireInstanceLock();
+if ("heldBy" in lock) {
+    log.error(`another Pier (pid ${lock.heldBy === null ? "unknown" : String(lock.heldBy)}) owns ${PIER_HOME} — refusing to start`);
+    process.exit(1);
+}
+// Every exit path at once: the drain and both shutdowns end in `process.exit`,
+// and the crash that skips this is what the stale-claim takeover is for.
+process.on("exit", lock.release);
+// A schema that cannot be migrated must stop the process before a port is open.
 const db = pierDb();
-// Files earlier versions kept beside the database. Their values live in
-// pier.db now, and a setting that silently stops being read is a 5b violation:
-// the operator who wrote it deserves to hear that it no longer applies.
+// A setting that silently stops being read is a §5 violation.
 for (const stale of ["settings.json", "pins.json", "unread.json"]) {
     if (existsSync(pierPath(stale))) {
         log.warn(`${pierPath(stale)} is no longer read — its value lives in pier.db now; re-enter it in the Console and delete the file`);
     }
 }
-// One store, two readers: the Console writes the public URL, and every session
-// opened after that is told the new one.
 const settings = new SettingsStore(db);
-// Layer-1 credential encryption (channel tokens today). Constructed here,
-// unlocked below: file mode is instant, vt mode waits on a human approval, and
-// nothing that needs a token may run before the key arrives.
+// 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();
 let tasks;
 const conversations = new ConversationStore(db);
 let resolveIm;
-// Declared before the store exists because the factory is built first; the tool
-// only ever runs long after wiring is done.
 let channelStore;
-// Shared by the adapter and the tool: a display name is looked up once per
-// process, not once per message and again per transcript.
+// 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();
@@ -102,15 +93,12 @@ const factory = new PiAgentFactory([
     slackToolSpec((params, callerSessionId) => handleSlackTool({
         store: channelStore,
         directory: slackDirectory,
-        // Rebuilt per call: the Console can change the token underneath us,
-        // and a client captured at boot would keep using the old one.
+        // 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;
         },
-        // 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.
+        // Per call: the mapping is durable, the session is not.
         here: (sessionId) => {
             const key = router.conversationOf(sessionId);
             if (key?.channelId !== "slack")
@@ -119,55 +107,33 @@ const factory = new PiAgentFactory([
             return channel && threadTs ? { channel, threadTs } : null;
         },
         log: (m) => logger("slack.tool").warn(m),
-    }, 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)),
+    }, params, callerSessionId), () => slackToolAvailable(channelStore)),
 ], 
-// Called per session open, so a setting changed in the Console reaches the
-// next session without a restart.
+// Getters, read per session open: a Console change reaches the next session
+// without a restart.
 () => surfacePrompt({ boardsDir: defaultBoardsDir(), publicUrl: settings.get().publicUrl }), 
-// Ships with Pier: documents Pier's own tools, so it loads only inside a
-// Pier session — not in a bare Pi session that has no task tool.
-[fileURLToPath(new URL("../skills", import.meta.url))], 
-// Provider credentials live sealed in pier.db; a leftover auth.json is
-// imported on first use and renamed to auth.json.imported.
-new CredentialStore(db, secrets), piConfig, 
-// Operator pins ride ahead of the curated catalog in every model picker.
-() => settings.get().modelMenu, 
-// Bundled extensions the Console switched on; read per session open, so the
-// toggle reaches the next session the same way an edited agent file does.
-() => settings.get().extensions, 
-// The title model, if the operator picked one; read when a first turn ends.
-() => settings.get().titleModel, 
-// The search index reads Pi's transcripts, which carry the speaker header
-// core wrote for the model; this is where the two areas meet.
+// 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, 
+// Transcripts carry the speaker header core wrote for the model.
 new IndexedListing(undefined, undefined, (text) => splitSpeaker(text).text));
 const hub = new EventHub();
 const router = new Router(hub, (key) => {
-    // Web conversation ids ARE session ids; an IM conversation id is a chat or a
-    // topic, so its session is looked up in the durable map (and created in the
-    // cwd the chat is configured for) — a restart must not re-route a group.
+    // Web conversation ids are session ids; an IM id is a chat, resolved through
+    // the durable map so a restart does not re-route a group.
     if (key.channelId === "web" || key.channelId === "task") {
         return factory.resume(key.conversationId);
     }
     return resolveIm(key);
-});
-// An attached session holds a live Pi runtime and its transcript, and nothing
-// else ever lets one go: without this, one per conversation ever answered.
+}, (key) => conversations.get(key));
 const stopEviction = router.startIdleEviction();
 tasks = new TaskService(new TaskStore(db), factory, router, hub, {
     modelMenu: () => settings.get().modelMenu,
     systemActions: { "config-sync": (signal) => configSync.sync(signal) },
 });
 const configurationSync = configSyncTask(tasks, configSync);
-// The managed CLI tools (src/tools.ts), and the daily task that keeps them
-// current (src/tools-task.ts) — an ordinary bash task on an ordinary cron,
-// wired here because tools.ts may not import tasks/.
 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.
+// Before any route exists: two first flips could otherwise both create a task.
 const reconciled = await toolsUpdate.reconcile();
 if ("problem" in reconciled)
     log.error(`tools cannot be managed: ${reconciled.problem}`);
@@ -175,31 +141,25 @@ channelStore = new ChannelStore(db, secrets);
 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));
-// Channels connect only once tokens are readable. A refused unlock (vt denial,
-// corrupt master.key) must not take the web surface down — it is where the
-// operator goes to repair — but it is named loudly, not served as silence.
-// Once they are up, the chats a previous restart cut off are told (drain.ts) —
-// on this path and on a later Console unlock alike, because a note held back
-// by locked secrets must not wait for yet another restart.
+// Channels connect once tokens are readable; a refused unlock must not take
+// down the web surface, which is where the operator repairs it. The chats a
+// previous restart cut off are told as soon as channels are up (drain.ts).
 const restartLedger = new RestartLedger(db);
 const startChannels = async () => {
     await channels.reload();
     await deliverLedger(restartLedger, (entry) => channels.notify(entry.channelId, entry.conversationId, entry.note))
         .catch((err) => log.error("restart-note delivery failed", err));
 };
-/** What "reload" means, in one place: the adapters re-read their configuration
- * and sessions are let go, so the next message re-opens them with the current
- * skills, extensions, prompts and credentials — all applied at attach, none
- * stored in a transcript. SIGHUP (`pier reload`) and the Console's Reload are
- * both this call; `includeWatched` is the only difference, and only because the
- * Console knows a person asked from the session they are looking at. */
+/** Adapters re-read their configuration and sessions are let go, so the next
+ *  message re-opens them with current skills, extensions, prompts and
+ *  credentials. SIGHUP and the Console's Reload are both this call. */
 const reloadInstance = async (includeWatched = false) => {
     await channels.reload();
     return router.evictIdle(0, Date.now(), { includeWatched });
 };
-// Bound the startup check before sessions and scheduled work can start.
 // Remote outages keep the last local configuration available.
 if (configSync.status().enabled) {
+    // sync() already logged the cause; this line says what the boot did about it.
     try {
         await configSync.sync();
     }
@@ -211,28 +171,15 @@ await configurationSync.reconcile();
 tasks.start();
 readyForConfigReload = true;
 void secrets.unlock().then(startChannels, (err) => log.error("secrets locked — channels not started; unlock from Console → Settings → Security, or repair master.key", err));
-// Replacing Pier is systemd's job, not this process's: the oneshot unit
-// snapshots the database, installs, then stops the service and starts it again
-// on the new version — in that order, so only the last two are downtime. Without
-// that unit there is nothing to hand the work to, and the Console says so
-// instead of offering a button that cannot work.
+// Replacing Pier is systemd's job: the oneshot unit snapshots the database,
+// installs, then stops and starts the service. Without that unit the Console
+// says so instead of offering a button that cannot work.
 const updates = new UpdateCheck();
-// Asked once at boot, not lazily on the first page load: a restart is exactly
-// when "am I current?" is worth knowing, and it puts the answer in the journal
-// of a Pier nobody has a browser open on.
+// At boot, not lazily: it puts the answer in the journal of a Pier nobody has
+// a browser open on.
 void updates.refresh();
-/**
- * Hand over, but not onto a running turn. The updater's first act is
- * `systemctl stop`, i.e. a SIGTERM, which is the *fast* teardown — so anything
- * that started since the idle check would be killed with no note anywhere. The
- * gate closes first and the drain waits, exactly as `pier restart` does,
- * ledger included; only then is the install handed over. A handover that never
- * starts reopens the gate, because a Pier that silently refuses every message
- * forever is worse than the race it was avoiding.
- */
-// Shared restart state. The updater's handover, the SIGUSR2 drain (below) and
-// the final teardown must see each other: without this, two paths drain the
-// same Pier at once, and a failure on one reopens the gate the other still
+// The updater's handover, the SIGUSR2 drain and the teardown must see each
+// other, or two paths drain the same Pier and one reopens the gate the other
 // needs shut.
 let handingOver = false;
 let draining = false;
@@ -240,32 +187,23 @@ let shuttingDown = false;
 const takeWorkAgain = (why) => {
     handingOver = false;
     log.error(`${why} — taking work again`);
-    // Not ours to reopen: a SIGUSR2 restart or the teardown owns the gate now,
-    // and reopening it would hand new work to a process that is exiting.
+    // Not ours to reopen: a restart or the teardown owns the gate now.
     if (draining || shuttingDown)
         return;
     router.endDrain();
     tasks.unpause();
-    // The drain may have deadline-aborted turns into the ledger. Without the
-    // restart that was supposed to follow, that debt would wait for one days
-    // away (§5b) — so the chats are told now, by the process that cut them off.
+    // Turns the drain deadline-aborted must not wait for a restart days away (§5).
     void deliverLedger(restartLedger, (entry) => channels.notify(entry.channelId, entry.conversationId, entry.note))
         .catch((err) => log.error("restart-note delivery failed", err));
 };
-/** How long the handover has to actually stop us. `systemctl start --no-block`
- *  returns when the job is *queued*, so "started" is not proof of anything;
- *  the real outcome is a SIGTERM — but only after the updater has snapshotted
- *  the database and installed the new version, which is a registry download on
- *  someone else's network — ten seconds on a good day, minutes on a bad one.
- *  So this waits far longer than the stop itself needs, because reopening the
- *  gate mid-install would take work we are about to be SIGTERM'd out of, and
- *  still short enough that a handover which never happens does not refuse
- *  messages all afternoon. */
+/** `systemctl start --no-block` returns when the job is queued; the real
+ *  outcome is a SIGTERM after a registry download on someone else's network.
+ *  Long enough not to reopen the gate mid-install, short enough that a handover
+ *  that never happens does not refuse messages all afternoon. */
 const HANDOVER_GRACE_MS = 5 * 60_000;
 const handOverToUpdater = async () => {
-    // One handover at a time, and never on top of a restart: the Console button,
-    // the auto-update tick and SIGUSR2 would otherwise drain the same Pier
-    // twice, each believing the gate is its own to reopen on failure.
+    // The updater's first act is `systemctl stop`, the fast teardown: the gate
+    // closes and the drain waits first, as `pier restart` does.
     if (handingOver || draining || shuttingDown)
         return "busy";
     handingOver = true;
@@ -275,11 +213,8 @@ const handOverToUpdater = async () => {
         takeWorkAgain(`update not started (${started})`);
         return started;
     }
-    // The gate is closed and nothing in this process will open it again, so a
-    // handover that queues and then goes nowhere — npm failed, the unit was
-    // masked, the job sat behind another — would leave Pier alive and refusing
-    // every message with no way back. Unref'd: this must not be what keeps the
-    // process up while systemd is trying to stop it.
+    // A handover that queues and goes nowhere would leave Pier refusing every
+    // message with no way back. Unref'd: must not keep the process up under stop.
     setTimeout(() => {
         takeWorkAgain(`still running ${String(HANDOVER_GRACE_MS / 1000)}s after handing over — pier-update.service never stopped Pier` +
             ` (check: journalctl --user -u pier-update.service -e)`);
@@ -289,20 +224,17 @@ const handOverToUpdater = async () => {
 const updater = process.platform === "linux" && existsSync(unitPath())
     ? { apply: handOverToUpdater, problem: () => updaterProblem() }
     : null;
-// Unattended only when the operator asked for it *and* nothing is running.
 if (updater) {
     const problem = updaterProblem();
-    // Loudly, at boot: this is the one moment the operator is looking, and the
-    // alternative is a restart that fails months from now.
+    // At boot, when the operator is looking; the alternative is a restart that
+    // fails months from now.
     if (problem)
         log.warn(`the updater cannot run: ${problem}`);
     startAutoUpdate(updates, {
         enabled: () => settings.get().autoUpdate,
         idle: () => router.busy().length === 0 && tasks.activeRunCount() === 0,
         apply: async () => {
-            // Re-checked here, not only at boot: a version manager can remove the
-            // recorded Node months into an uptime, and draining for a handover that
-            // cannot happen would take the whole instance down with it.
+            // A version manager can remove the recorded Node months into an uptime.
             const now = updaterProblem();
             if (now) {
                 log.error(`auto-update skipped: ${now}`);
@@ -312,18 +244,14 @@ if (updater) {
         },
     });
 }
-// Composition happens here so web/ and tasks/ never import each other.
 const app = new Hono();
-// A route that threw would otherwise answer 500 and leave no trace anywhere:
-// Hono's default handler writes nothing to the log, so the operator sees a
-// failed request in the browser and an empty journal.
+// Hono's default handler writes nothing to the log.
 app.onError((err, c) => {
     log.error(`${c.req.method} ${c.req.path} failed`, err);
     return c.json({ error: String(err) }, 500);
 });
-// Before every route on purpose: Hono runs middleware in registration order,
-// so a surface added later is covered without knowing this exists. Built
-// before the listener: a first run generates and prints its password here.
+// Before every route: Hono runs middleware in registration order, so a surface
+// added later is covered without knowing this exists.
 const auth = new AuthStore(db);
 registerConfigShareRoute(app, configSync);
 app.use("*", requireAuth(auth));
@@ -338,11 +266,8 @@ registerTaskRoutes(app, tasks, { factory, router });
 registerChannelRoutes(app, channelStore, channels);
 registerBoardRoutes(app);
 const sessionState = new SessionStateStore(db);
-// The workbench's notifications to a browser that is not open. Composed here,
-// beside the other surfaces: it consumes the same event stream the web server
-// does, and neither one runs the other.
 registerPushRoutes(app, {
-    store: new PushStore(db),
+    store: new PushStore(db, secrets),
     hub,
     unread: (id) => sessionState.unread(id),
     channelOf: (id) => router.conversationOf(id)?.channelId,
@@ -357,11 +282,8 @@ app.route("/", createServer({
     config: piConfig,
     providers: factory,
     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.
-    // 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.
+    // Assembled here so web/ gets names and summaries, not a module that
+    // imports the Pi SDK; extensions and binaries are one kind of switch.
     catalog: async () => {
         const { extensions, tools, customTools } = settings.get();
         return {
@@ -369,14 +291,10 @@ app.route("/", createServer({
             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.
+    // 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) },
     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 };
@@ -384,7 +302,6 @@ app.route("/", createServer({
     secrets,
     updates,
     updater,
-    // Unlocked from the Console: start the channels boot held back.
     onUnlocked: () => void startChannels(),
     reload: () => reloadInstance(true),
     backgroundRuns: (id) => tasks.backgroundRuns(id),
@@ -394,56 +311,45 @@ app.route("/", createServer({
 }));
 const port = Number(process.env.PORT ?? 3141);
 const hostname = process.env.HOST ?? "127.0.0.1";
-// Read above, and dropped here so nothing else reads them: these three
-// configure *this* process, and every command a turn runs inherits its env.
-// `NODE_ENV=production` makes an agent's `npm install` skip devDependencies and
-// silently changes what half the ecosystem builds; PORT and HOST would aim an
-// agent's own dev server at Pier's socket. Deleted at runtime rather than only
-// dropped from the unit, because an installed unit is rewritten by
-// `pier service install --force` and by nothing else.
+// 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.
 for (const leak of ["NODE_ENV", "PORT", "HOST"])
     delete process.env[leak];
 const server = serve({ fetch: app.fetch, port, hostname }, () => {
     log.info(`workbench on http://${hostname}:${port}`);
     log.info(`pid ${process.pid}, node ${process.version}, home ${PIER_HOME}`);
-    // Only when it is not the derived default: an agent dir outside PIER_HOME is
-    // the one thing about this process's paths that cannot be guessed from it.
+    // The one path that cannot be guessed from PIER_HOME.
     if (process.env.PI_CODING_AGENT_DIR !== pierPath("pi")) {
         log.info(`agent dir ${process.env.PI_CODING_AGENT_DIR} (PI_CODING_AGENT_DIR)`);
     }
 });
-// A crash and a clean stop must be distinguishable after the fact, and both
-// left nothing behind before this.
 process.on("uncaughtException", (err) => {
     log.error("uncaught exception, exiting", err);
     process.exit(1); // Node's own default outcome, with the area named
 });
-// This one *does* change behaviour: Node's default is to crash. A stray
-// rejection in one adapter's background work must not take every session and
-// every scheduled task down with it — so it is logged loudly and Pier serves on.
+// Node's default is to crash; a stray rejection in one adapter's background
+// work must not take every session and scheduled task down with it.
 process.on("unhandledRejection", (reason) => {
     log.error("unhandled rejection", reason);
 });
 const shutdown = (stopTasks = true) => {
-    // Once: SIGTERM can land while a drain is finishing, and two teardowns
-    // racing each other close the same sockets twice.
+    // SIGTERM can land while a drain is finishing.
     if (shuttingDown)
         return;
     shuttingDown = true;
-    // Best-effort, and bounded: a socket an adapter cannot close must not turn
-    // `systemctl restart` into a 90-second wait for SIGKILL.
+    // A socket an adapter cannot close must not turn `systemctl restart` into a
+    // 90-second wait for SIGKILL.
     setTimeout(() => process.exit(0), 3000).unref();
     stopEviction();
-    // The drain path leaves task runs alone: aborting them here would record
-    // them cancelled and race their callbacks against dying channels, when the
-    // boot-time interrupted marking is the recovery that was promised.
+    // The drain path leaves task runs alone: aborting would record them cancelled,
+    // when the boot-time interrupted marking is the recovery that was promised.
     if (stopTasks)
         tasks.stop();
     void channels.stop().finally(() => {
         server.close(() => process.exit(0));
         // Every workbench tab holds an SSE stream open, so `close()` alone would
-        // always wait out the timer above. (`in` because the served type is a
-        // union with HTTP/2, which has no such method — and no such problem.)
+        // wait out the timer above. (`in`: the served type is a union with HTTP/2.)
         if ("closeAllConnections" in server)
             server.closeAllConnections();
     });
@@ -454,10 +360,8 @@ for (const signal of ["SIGTERM", "SIGINT"]) {
         shutdown();
     });
 }
-// The slow restart (`pier restart`): refuse new work, let running turns finish
-// — bounded by the drain deadline — then exit for `Restart=always` to bring the
-// next process up. SIGTERM above stays the fast path systemd expects. `on`,
-// not `once`: a second SIGUSR2 with no handler would fall back to Node's
+// The slow restart (`pier restart`): drain, then exit for `Restart=always`.
+// `on`, not `once`: a second SIGUSR2 with no handler would fall back to Node's
 // default and kill the drain it meant to hurry.
 process.on("SIGUSR2", () => {
     if (draining) {
@@ -470,11 +374,8 @@ process.on("SIGUSR2", () => {
         .catch((err) => log.error("drain failed — shutting down anyway", err))
         .then(() => shutdown(false));
 });
-// Reload without a restart (`pier reload`): reloadInstance above, leaving the
-// sessions someone is watching alone — nobody asked from a browser here.
-// Only under systemd (the CLI signals through systemctl): a foreground `pier
-// serve` keeps SIGHUP's default, dying with its terminal instead of surviving
-// as an orphan that holds the port.
+// Only under systemd: a foreground `pier serve` keeps SIGHUP's default, dying
+// with its terminal instead of surviving as an orphan that holds the port.
 if (process.env.INVOCATION_ID) {
     process.on("SIGHUP", () => {
         log.info("SIGHUP received, reloading channels and recycling idle sessions");

package/dist/paths.js

@@ -1,36 +1,20 @@
-// Where Pier keeps its state, resolved once.
-//
-// This is process configuration, not a per-call decision: the same
-// `PIER_HOME ?? ~/.pier` line had grown six copies, one per module that needed
-// a file, and no area could own the fix — channels/ must not import tasks/,
-// web/ must not import channels/. So it lives in a leaf that everything may
-// depend on and that depends on nothing.
+// Where Pier keeps its state, resolved once, in a leaf every area may import.
 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. */
+/** Empty is unset, not a value: `PIER_HOME=` would otherwise resolve every
+ *  path relative to the working directory. */
 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 = 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
- *  directory so db.ts can lock that directory down to 0700 without touching
+/** In its own directory so db.ts can lock it down to 0700 without touching
  *  the boards PIER_HOME also holds. */
 export const PIER_DB = pierPath("db", "pier.db");
-/**
- * Which Pi agent dir this process should use, given its environment.
- *
- * `PI_CODING_AGENT_DIR` is an operator override and wins — but Pier exports it
- * for the SDK, so everything Pier spawns inherits it, and a Pier started from
- * inside another one would take the parent's agent dir however different its
- * own PIER_HOME is. `PIER_AGENT_DIR` carries the value Pier itself set: when
- * the two match, the variable is a leak rather than an instruction, and this
- * instance derives its own. Pure, because the rule is worth a test and the
- * process only gets to apply it once (main.ts).
- */
+/** 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");
+/** `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. */
 export function resolveAgentDir(env, derived = pierPath("pi")) {
     const given = env.PI_CODING_AGENT_DIR;
     return !given || given === env.PIER_AGENT_DIR ? derived : given;