@alphacoder-v0/pi-loops 0.24.1 → 0.24.2

package/CHANGELOG.md

@@ -5,6 +5,89 @@ All notable changes to pi-loops are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.24.2] - 2026-11-11
+
+Fixes from the 0.24.2 milestone and a review of what merged since 0.24.1: a path rule that never
+fired, faster `pi-loops` commands, page edges that showed what nobody could use, and fewer tools
+offered to a sub-agent that could only fail.
+
+### Fixed
+
+- **A path rule with an aside in parentheses is checked by the model.** The path precheck dropped
+  a trailing parenthetical, so `/tmp/a exists (or /tmp/b exists)` waited on `/tmp/a` alone and never
+  fired when only `/tmp/b` appeared. No word list can tell such an aside from a harmless one, so a
+  condition with one is model-checked again, and `new_trigger` asks the model to keep the person's
+  words with nothing added.
+- **Every `pi-loops` command answers in a fraction of a second.** The command line loaded pi's SDK
+  on every call, about a second of each `status`, `stop` and `--help`; it now loads it only for
+  `import`, the one command that needs it. `pi-loops --version` went from about 1.2 s to 0.17 s here
+  (#168).
+- **The page's inbox matches each project once per request.** `GET /inbox` resolved a finding's
+  directory on disk for every finding, in three passes; 2000 findings took about 24 ms a pass.
+  Each distinct directory is now resolved once per request (#169).
+- **Logs name a conversation the way every screen does.** pi-loops' log lines cut a session id to
+  8 characters while the page, the terminal and the CLI show 13, so an id copied from the page was
+  not found in the log (#177).
+- **Starting or resuming a conversation in the page says why, once.** The new session's events
+  arrived before the page moved to its id, so the page read the old id's history (which the server
+  opened in a pi of its own) and reloaded again on each event after, ending on "the session
+  restarted". The page now waits for the answer, moves to the id it names, and reloads once (#198).
+- **A stopped MCP connection pushes nothing more.** A push read from the server just before the
+  connection stopped could still reach the host after it, and its trust check then read a project
+  directory that might be gone (#188).
+- **An upgrade no longer holds a quit, or the page opening, in silence.** `pi-loops` opening the
+  page during an upgrade waited up to 180 s for the older process with nothing said; it now prints
+  `waiting up to 2 min for a turn in the browser page to finish…` when the wait passes 2 s. A pi
+  window that is quitting asks for the upgrade and leaves at once (#165).
+- **Two page edges no longer show something nobody can use.** An unknown conversation address
+  answers with a page and a link back, not JSON. On a page only this machine can reach, Add a
+  device no longer shows a pairing code: it says how to make the page reachable, and retires the
+  code the server made (#157).
+- **A conversation opened in the page loads pi-loops when the launch named its entry file.** A new
+  conversation in a project with no arguments of its own takes the `-e` that loads pi-loops from
+  another page pi. `-e <package>/src/extension-entry.ts` and `--extension=<path>` were not
+  recognised, so that conversation started without pi-loops (#167).
+- **The page token is made once, even by two first starts at once.** Two windows that started
+  pi-loops together could each write a token, and one then exited. The token and its marker are
+  now written under a lock. A `web-token.v024` that is a symlink is refused before the token is
+  touched; before, it changed the token on every start and then failed (#144).
+- **A loop's finding can no longer pass for an undelivered prompt.** A prompt that never reached its
+  conversation was told from a loop's finding by its text alone, so a loop that wrote
+  `could not be delivered (…): <text>` had its text carried out on Yes. The engine now marks a dead
+  letter with `"undelivered": true`, and only that field changes what a claim asks (#143).
+- **A `$HOME` reached through a symlink is never one project.** Before, a session started in such a
+  `$HOME` lent its trust to loop runs in every project under it, and the create tools accepted any
+  directory under it as the session's own (#142).
+- **Watch for… knows more time words.** "review deps quarterly", "check CI this afternoon",
+  "at nine", "in a few minutes", "next week", "biweekly" and "今晚" were told they read like
+  something to do now, and nothing was set up. They are now watches. A word that only starts like a
+  weekday or a time word ("montage", "sunset", "everyone") no longer reads as one (#146).
+- **`pi-loops --tui --loops-dir <dir>` uses that directory.** The terminal's extension now gets it
+  as `PI_LOOPS_DIR`; before, it used the default. `--open` goes to pi like any flag pi-loops does
+  not read, and `--port`, `--host` and `--allow-host` with `--tui` are dropped, not passed to pi as
+  the 0.24.0 notes said (#145).
+- **`pi-loops --version` prints the pi-loops version,** not pi's. `pi-loops --tui -- --version` asks pi
+  (#148).
+
+### Changed
+
+- **The Loops pane says each thing once.** A named loop shows no prompt peek (the body has the
+  prompt), a failing loop no `quiet ×N` under its error, and the open row no id or cwd. Common cron
+  schedules read in words (`daily 09:00`, `weekdays 18:30`, `weekly Mon 09:00`, `every hour`). A
+  rule row is titled by its condition. The activity strip's "in chat" follows where a run's card
+  went: the conversation that asked for the run, not the one that made its loop (#154).
+- **The page header and composer say less.** The header's clear button did what + New does in
+  this project, so it is gone (`/clear` and `/new` still work). The page says "conversation" where
+  it said "session". The cost badge appears once there is a cost. The composer says "Message pi".
+  The theme button's name is its visible state (#156).
+- **`cron_remove` asks once.** It had a `confirm` parameter: the model asked the person in chat,
+  then the dialog asked again. The parameter is gone, and one call asks through the dialog.
+- **A sub-agent is not offered `new_trigger`, `remove_trigger` or `cron_remove`.** Every call of
+  each was denied at hop 1, so the tools only invited a failed first try (#159, #212).
+- **The agent is told more of what it can use.** `cron_create`'s schedule names `hourly`, `daily`
+  (09:00), `weekly` (Monday 09:00) and that `@daily` is midnight. SKILL.md names the inbox
+  commands a shell can run. The `catch_up` and `spec` descriptions are shorter (#160).
+
 ## [0.24.1] - 2026-11-10
 
 Two first-run fixes: the `pi-loops` command exists after the first pi session with no question, and

package/README.md

@@ -345,9 +345,8 @@ unambiguous prefix of it, or the `--name` you gave it — and `/crontab` and `/l
 
 Tools for the model: `cron_create`, `cron_list`, `cron_remove`, `set_cron_job_state`,
 `new_trigger`, `list_triggers`, `remove_trigger`, `set_trigger_state`, plus every tool of every
-configured MCP server. Five of them stop and ask you: creating or removing a trigger, removing a
-cron job — `cron_remove` twice over, a preview the model must show you before the approval itself —
-and any state change that turns automation *on*, or touches another project's. They are the
+configured MCP server. Five of them stop and ask you, once each: creating or removing a trigger,
+removing a cron job, and any state change that turns automation *on*, or touches another project's. They are the
 operations that decide what runs while nobody is watching.
 
 ## Documentation

package/docs/cli.md

@@ -355,7 +355,7 @@ The rest of the command line does not need a pi session and has no build step; i
 packages the way pi-loops does. `PI_LOOPS_DIR` selects the loops directory, as everywhere.
 
 ```
-pi-loops sessions [--all] [--limit <n>]
+pi-loops sessions [--all] [--limit <n>] [--cwd <dir>]
 pi-loops inspect <file>
 pi-loops export [--session <id>] [--cwd <dir>] [--output <file>] [--exclude-triggers]
 pi-loops import <file> [--cwd <dir>] [--activate-triggers=off|ask|on]
@@ -365,7 +365,9 @@ pi-loops inbox list [--all] [--cwd <dir>] | claim <id> | dismiss <id> [--reason
 ```
 
 `-h` or `--help` anywhere in a subcommand's arguments before a `--` prints that subcommand's usage
-and exits 0 without doing anything else; `pi-loops -h` is `pi-loops --help`. After `--` they are pi's.
+and exits 0 without doing anything else; `pi-loops -h`, `pi-loops help` and `pi-loops --help` are the same. After `--` they are pi's.
+`pi-loops --version` (or `-v`) alone prints the pi-loops version, such as `pi-loops v0.24.2`;
+`pi-loops --tui -- --version` prints pi's.
 A command typed wrong, such as a missing archive path, a flag the command does not read
 (`status does not take --json`) or a word it does not read (`export: unexpected argument "out.pisession"`),
 prints `pi-loops: <what is wrong>` and that command's usage, and exits 2. Any other error prints only its line and exits 1. An unknown command
@@ -378,7 +380,7 @@ in the session's control-plane audit.
 
 ## sessions, inspect
 
-`sessions` lists this project's sessions newest first, one line each: the first sixteen
+`sessions` lists this project's sessions (`--cwd <dir>` names another project) newest first, one line each: the first sixteen
 characters of the id, when the session started, the automation it
 has (`[2 cron, 1 trigger]`, or `[automation off]` when all of it is disabled), and what was first
 said in it — the session's name if it was given one, otherwise the first message, cut at eighty
@@ -422,7 +424,7 @@ spellings `pi-loops host status|abort|stop|start` and `/cron host` still work.
 $ pi-loops status
 pi-loops
   pid 2949521 on box, started 2026-09-09 13:33, model openai-codex/gpt-5.5
-  pi-loops 0.24.1 · 1/1 loops, 0/0 rules enabled · inbox: 0 new
+  pi-loops 0.24.2 · 1/1 loops, 0/0 rules enabled · inbox: 0 new
   started by the shell that ran pi-loops
   conversation 424aba43-0c1f "fix the flaky login test" open in pid 939915 (tui)
   running nightly (run-97ffb250) since 2026-09-09 13:34: check the repo issues
@@ -447,7 +449,9 @@ start` starts it now, even with nothing to run yet. `pi-loops restart` stops it,
 process has exited (SIGKILL after 180 seconds), and starts it. A restart, and an upgrade that a pi
 window with a newer pi-loops asks for, first wait up to two minutes for a turn in the browser page to
 finish, so a conversation open there is not cut off mid-answer; a restart first prints `waiting up
-to 2 min for a turn in the browser page to finish…`. A plain `pi-loops stop` ends it at once, and one
+to 2 min for a turn in the browser page to finish…`, and `pi-loops` opening the page prints the same
+line when the older process has not left after 2 seconds. A pi window that is quitting asks for the
+upgrade and does not wait: the next window or `pi-loops` starts the new version. A plain `pi-loops stop` ends it at once, and one
 run during that wait ends the wait. A restart or an upgrade asked for while it already waits is
 answered `already leaving` and does not start the wait again. With `--help`, each of these prints its
 usage and does nothing else.

package/docs/configuration.md

@@ -30,7 +30,7 @@ Everything lives under `~/.pi/agent/loops/` (override: `PI_LOOPS_DIR`).
 | `*.lock` | short-lived locks around writes |
 | `polls.json` | last dynamic check per project (shared with 0.22 windows during an upgrade, so a project is not checked twice in one interval) |
 | `dedup.json` | machine-wide trigger dedup window (5 minutes) |
-| `web-token` | the browser page's token, mode 0600. It lives in a file rather than being made per start so the address stays the same one and a signed-in device stays signed in across restarts and upgrades. Delete it and run `pi-loops restart` to sign every device out. The first 0.24 start replaces a token from an earlier version once, and writes `web-token.v024` beside it to record that; a token you write into `web-token` after that is kept |
+| `web-token` | the browser page's token, mode 0600. It lives in a file rather than being made per start so the address stays the same one and a signed-in device stays signed in across restarts and upgrades. Delete it and run `pi-loops restart` to sign every device out. The first 0.24 start replaces a token from an earlier version once, and writes `web-token.v024` beside it to record that; a token you write into `web-token` after that is kept. A `web-token.v024` that is not a regular file (a symlink, even a dangling one) stops pi-loops from starting, as a `web-token` symlink does |
 
 Project-level: `<project>/.pi/mcp.toml` (trusted projects only) and `<project>/.pi/hooks.toml`
 (when allowed).

package/docs/design.md

@@ -153,8 +153,9 @@ machine. Everything here follows from that, and each one has a price.
     three is recorded in the control-plane audit, the self-removals included.
 
 12. **Cycle suppression by hop count.** Sub-agents run at hop 1 and keep the cron and trigger tools
-    (`cron_create`, `cron_remove`, listing, disabling), so a loop can manage automation; the
-    operations that would need a human's yes are denied there, and sub-sessions never run the
+    (`cron_create`, listing, disabling), so a loop can manage automation; the tools whose every
+    call needs a human's yes are not offered there, the other operations that need one are
+    denied, and sub-sessions never run the
     trigger runtime, so nothing nests.
 
 13. **Stdio MCP servers reconnect** with backoff (20 attempts by default), each distinct error

package/docs/triggers.md

@@ -54,6 +54,8 @@ noun only when a space sets it apart from the path: `~/备份文件 存在` wait
 `once`, `当`, `如果` or `一旦` and an optional trailing `的时候`, `时` or `后`. `~` and `$HOME` are
 resolved in the process that creates the rule, so they are your home even when pi-loops in the
 background was started with another one; a relative path is resolved against the rule's project.
+An aside in parentheses is a second clause: `/tmp/a exists (or /tmp/b exists)` is true while
+`/tmp/a` is absent, so a condition with one is checked by the model.
 
 Anything else is refused as path-only and checked by the model, as before: a glob, a second clause
 (`~/x appears and it contains ERROR`, `~/a exists or ~/b exists`), another verb, a bare word with no
@@ -138,7 +140,7 @@ that instant (someone wrote it in the last two minutes), the row waits and pi-lo
 later tick. A row whose delivery fails waits a minute, then five, and blocks nothing behind it; at
 the third failure, or when the conversation's file is gone, it is a dead letter: a finding in the
 inbox marked for the conversation, then a `request` audit row (`dead`), then the row is removed, in
-that order so a crash in between loses nothing. A rule's result has its finding already (every match is one), so its dead letter files no second one; any other row's finding reads `could not be delivered (<why>): <prompt>`. A rule with no
+that order so a crash in between loses nothing. A rule's result has its finding already (every match is one), so its dead letter files no second one; any other row's finding reads `could not be delivered (<why>): <prompt>` and carries `"undelivered": true`. Only that field makes a claim carry the prompt out; a loop's finding in the same words is claimed as a finding. A rule with no
 creating conversation (made from a shell, imported, or made by a loop's run) sends results to the
 project's open window as above, and to the inbox (`redirected`, which finds the match's finding and adds nothing) when none is open. One check evaluates every
 rule of the project at once, so it runs under **one** model: the first rule that has one recorded
@@ -207,12 +209,14 @@ poll interval is unaffected: the next scheduled check happens when it would have
 
 ## Cycle safety
 
-Cycles are bounded by a hop count: sub-agents run at hop 1 and still have the
-cron/trigger tools, so a trigger action can schedule a job; they never run the trigger runtime, so
-nothing nests. Prompt-class operations — creating or removing a trigger,
-re-enabling a trigger or a cron job — are denied fail-closed in sub-agents (no control-plane
-prompt channel there). `cron_create` works there, and so does disabling a job of the sub-agent's own
-project; the control-plane audit records `actor: sub-agent`. `cron_remove`, re-enabling a job and
+Cycles are bounded by a hop count: sub-agents run at hop 1 and still have
+`cron_create`, `cron_list`, `set_cron_job_state`, `list_triggers` and `set_trigger_state`, so a
+trigger action can schedule a job; they never run the trigger runtime, so nothing nests.
+`new_trigger`, `remove_trigger` and `cron_remove` are not offered at hop 1: every call of each
+needs a person, and a sub-agent has nobody to ask. The other
+prompt-class operations — re-enabling a trigger or a cron job — are denied fail-closed in
+sub-agents (no control-plane prompt channel there). `cron_create` works there, and so does disabling a job of the sub-agent's own
+project; the control-plane audit records `actor: sub-agent`. Re-enabling a job and
 touching another project's job are denied there like the other prompt-class operations. Sub-agents never handle triggers themselves: they ignore MCP pushes, and the
 runtime audits anything reaching hop ≥ 1 as `cycle_suppressed` (hops are counted per trace, but the
 bound that matters is structural: a sub-agent session never acts on a trigger at all).

package/docs/web-ui-parity.md

@@ -327,7 +327,8 @@ weaker, and worth converting whenever one of them breaks.
       **Waiting on** and **If you don't** when the loop said them, then news. A card names its loop
       only when the list holds more than one loop's findings, and says where a claim runs only when
       that is not the conversation on screen (another conversation's or project's finding, or a
-      terminal that takes no messages). **See the run** is there only when the finding has a run.
+      terminal that takes no messages). **See the run** is there only when the finding has a run this page can read
+      (`test/page-server.test.ts`: *See the run is offered only for a transcript the server would read*).
       Every card carries its finding's whole id; no button names a position. `test/web-page.test.ts`:
       *the inbox shows decisions before news, each row only with a value, and where a claim runs
       only when that is not here*. `test/page-server.test.ts`: *GET /inbox: one project's cards, decisions first,
@@ -502,10 +503,10 @@ weaker, and worth converting whenever one of them breaks.
       open this on a phone. Wide, it is a column beside the conversation, which the rail's Loops
       button gives back to the conversation, remembered; up to 1100 px it is a drawer from that
       button; on a phone (760 px and less) it is the Loops tab.
-- [x] Thirteen controls do not fit across a narrow conversation. Below 1000 px of conversation,
+- [x] Twelve controls do not fit across a narrow conversation. Below 1000 px of conversation,
       whatever is beside it, the ones you reach for mid-conversation (undo, find, compact and resume)
       stay in the header on one row with ⋯, and the header stays two rows at a 1280 or 1440 px
-      window; reload, save, share, clear, add device, theme and notifications go behind ⋯. The
+      window; reload, save, share, add device, theme and notifications go behind ⋯. The
       sheet lists all of them, moved — not copied — into it. On a phone (760 px and less) every one is behind ⋯.
       `test/web-page.test.ts`: *the header's secondary actions move into a sheet and back*, *below
       1000 px of conversation, undo, find, compact and resume stay in the header and the rest go
@@ -591,8 +592,8 @@ weaker, and worth converting whenever one of them breaks.
       first; it replaces `new_trigger`'s confirm, so there is one question, never two. A scheduled
       turn, a sub-agent and pi-loops in the background ask nobody. `test/scoping.test.ts`: *the answer
       is promote_to_chat and fire_once for a rule, and stateful and verify for a schedule*, *a
-      sub-agent, a scheduled turn and a pi with no dialog keep today's gate: new_trigger asks the
-      host's confirm once and cron_create creates*; J8 in `test/journey/journeys/j08-watch.mjs`
+      sub-agent has no new_trigger; a scheduled turn and a pi with no dialog keep today's gate:
+      new_trigger asks the host's confirm once and cron_create creates*; J8 in `test/journey/journeys/j08-watch.mjs`
       drives the selector in tmux.
 - [x] At 390 px the box and the card fit: nothing scrolls sideways, the chips and buttons wrap, and
       every button is at least 32 px tall (J8 in `test/journey/journeys/j08-watch.mjs`).
@@ -742,7 +743,7 @@ weaker, and worth converting whenever one of them breaks.
       whether pi-loops runs*.
 - [x] **Starting over does not mean going back to a terminal.** The context is finished with far
       more often than the window is: a new session and going back to an earlier one are both here,
-      by button (the list's + New is the header's clear) and by `/clear`, `/new` and `/resume` typed
+      by button (the list's + New in this project) and by `/clear`, `/new` and `/resume` typed
       in the composer — the habit comes from a
       terminal and the muscle memory arrives with it. Neither deletes anything: the session being
       left is a file that `resume` lists, labelled by what was said in it rather than by a filename.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alphacoder-v0/pi-loops",
-  "version": "0.24.1",
+  "version": "0.24.2",
   "description": "An automation layer for pi: cron + stateful loops with a triage inbox, maker/checker verification, dynamic triggers, MCP notifications and tools, lifecycle hooks, session archives. A non-invasive pi extension.",
   "type": "module",
   "license": "MIT",

package/skills/pi-loops/SKILL.md

@@ -46,6 +46,8 @@ reported in your notes; report only new or newly closed issues". Findings should
 (a reason is shown to the loop's next run, so a finding the user calls noise can say why).
 `/cron` lists jobs, `/cron runs`, `/cron trace <job> [k]` shows what a run did. `/triggers rules`,
 `/triggers audit` for dynamic triggers.
+From a shell: `pi-loops inbox list --json`, `pi-loops inbox claim <id> --json`,
+`pi-loops inbox dismiss <id> --reason <text> --json`.
 
 ## Confirmations
 

package/src/activity.ts

@@ -8,7 +8,7 @@ import type { InboxEntry } from "./inbox.ts";
 import { ruleResultText, splitFinding } from "./inbox-card.ts";
 import { failingJobs } from "./job-health.ts";
 import { redact } from "./redact.ts";
-import { runCardFor } from "./run-card.ts";
+import { runCardFor, runCardsHere } from "./run-card.ts";
 import type { LoopJob, RunRecord } from "./store.ts";
 import type { AuditRecord } from "./triggers.ts";
 
@@ -45,7 +45,7 @@ export interface ActivityItem {
 	carded: boolean;
 	/** A rule check: its findings, so a row can point at the card. */
 	inboxIds: string[];
-	/** A rule check: the result also went to a conversation (`promote_to_chat`). */
+	/** A rule check: the result also went to a conversation (`promote_to_chat`). A run: its card is in this conversation. */
 	inChat: boolean;
 	/** The run's loop or the rule was made in the conversation asking. */
 	fromThisConversation: boolean;
@@ -123,7 +123,8 @@ export function activityFrom(input: ActivityInput): { items: ActivityItem[]; mor
 			...(!r.ok && r.error ? { error: clip(r.error) } : {}),
 			carded: runCardFor(r) === "card",
 			inboxIds: [],
-			inChat: false,
+			// Where its card is: a run someone asked for cards where they asked, not where its loop was made.
+			inChat: runCardFor(r) === "card" && runCardsHere([r], { sessionId: input.sessionId, inProject: here }).length > 0,
 			fromThisConversation: !!input.sessionId && r.forSession === input.sessionId,
 		});
 	}

package/src/cli.ts

@@ -9,14 +9,13 @@
  *   pi-loops import <file> [--cwd <dir>] [--activate-triggers=off|ask|on]
  */
 import { execFileSync, spawn, spawnSync } from "node:child_process";
-import { plural } from "./job-lines.ts";
+import { plural } from "./plural.ts";
 import * as fs from "node:fs";
 import * as net from "node:net";
 import * as os from "node:os";
 import * as path from "node:path";
 import * as readline from "node:readline";
 import { fileURLToPath } from "node:url";
-import { SessionManager, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { isRemoteTty, openFileTarget, openUrl, thisMachine } from "./browser-open.ts";
 import { applyImport, automationOf, exportSession, defaultExportPath, importSession, inspectArchive, offerToEnable, parseActivateMode } from "./archive.ts";
 import { API_KEY_REFUSAL, CONTROL_TIMEOUT_MS, COPY_KEY_MS, askHost, hostSocketPath, openConversations, renderHostSnapshot, requestLines, requestQueues, ringHost } from "./host-control-channel.ts";
@@ -31,13 +30,13 @@ import { crashPaused, crashPauseText, ensureHost, HOST_LOG, hostCommand, hostSer
 import { loadConfig, pageBindPort } from "./config.ts";
 import { writeUiPref } from "./ui-prefs.ts";
 import { type UiPrefs, clearUiPref, readUiPrefs } from "./ui-prefs.ts";
-import { JobStore, defaultLoopsDir, homeLoopsDir } from "./store.ts";
+import { JobStore, defaultLoopsDir, homeLoopsDir, piAgentDir } from "./store.ts";
 import { automationBadge, previewText, readSessionHead, shortSessionId } from "./session-head.ts";
 import { AUTONOMY_LEVELS, type AutonomyLevel, INSTALL_ROOT, TRACKER_FILE, addLineFor, ensureExcluded, installDirFor, installFiles, installedRecipes, listRecipes, loadRecipe, planInstall, playbookFiles, readRecord, resolveRecipeRef } from "./recipe.ts";
 import { TriggerStore } from "./triggers.ts";
 import { PI_LOOPS_VERSION } from "./version.ts";
 import { formatLocal, stamp } from "./schedule.ts";
-import { canonicalDir } from "./trust.ts";
+import { canonicalDir } from "./paths.ts";
 
 /**
  * Which front end `pi-loops` opens when you do not say. A browser is the better window when one is
@@ -73,7 +72,7 @@ export function noTerminalRefusal(input: { web: boolean; tui: boolean; interacti
  * `allow-host` and `no-auth` are claimed only to be refused: the page outlives the command now, so
  * its address lives in config.toml.
  */
-const LAUNCH_FLAGS = new Set(["web", "tui", "port", "host", "allow-host", "open", "no-open", "no-auth", "loops-dir", "help"]);
+const LAUNCH_FLAGS = new Set(["web", "tui", "port", "host", "allow-host", "no-open", "no-auth", "loops-dir", "help"]);
 /** The ones that take the next argument as their value. */
 const LAUNCH_FLAGS_WITH_VALUE = new Set(["port", "host", "allow-host", "loops-dir"]);
 
@@ -128,7 +127,7 @@ const CLI_USAGE = [
 	"pi-loops import <file> [--cwd <dir>] [--activate-triggers=off|ask|on]",
 	"    Restore an archive into a project.",
 	"",
-	"pi-loops sessions [--all] [--limit <n>]",
+	"pi-loops sessions [--all] [--limit <n>] [--cwd <dir>]",
 	"    List sessions, newest first.",
 	"",
 	"pi-loops inspect <file>",
@@ -287,6 +286,10 @@ function runChild(command: string, args: string[], env?: NodeJS.ProcessEnv): Pro
 export async function runCli(argv: string[], out: (line: string) => void = console.log): Promise<number> {
 	const route = cliRoute(argv);
 	if (route === "launch") return launch(argv, out);
+	if (route === "version") {
+		out(`pi-loops v${PI_LOOPS_VERSION}`);
+		return 0;
+	}
 	if (route === "help") {
 		out(usageFor(argv[0]));
 		return 0;
@@ -299,7 +302,7 @@ export async function runCli(argv: string[], out: (line: string) => void = conso
 		const v = flags.get(name);
 		return typeof v === "string" ? v : undefined;
 	};
-	const agentDir = getAgentDir();
+	const agentDir = piAgentDir();
 	const loopsDir = process.env.PI_LOOPS_DIR || defaultLoopsDir(agentDir);
 	const cwd = path.resolve(str("cwd") ?? process.cwd());
 
@@ -383,6 +386,8 @@ export async function runCli(argv: string[], out: (line: string) => void = conso
 		const triggerStore = new TriggerStore(loopsDir);
 		// pi encodes a project as `--home-u-proj--` and `SessionManager.list()` reads only that one
 		// directory, with no fallback — a hand-rolled name here would restore a session pi never sees.
+		// Loaded here, not at the top: pi's SDK takes about a second, and only this verb needs it.
+		const { SessionManager } = await import("@earendil-works/pi-coding-agent");
 		const sessionDir = SessionManager.create(cwd).getSessionDir();
 		const existingJobs = jobStore.load();
 		const existingRules = triggerStore.load();
@@ -751,7 +756,7 @@ async function upgrade(checkOnly: boolean, out: (line: string) => void): Promise
 		out("already up to date");
 		return 0;
 	}
-	const spec = upgradeSpec(packageRoot(), name ?? "", getAgentDir(), latest, configuredNpmSource(packageRoot(), name ?? ""));
+	const spec = upgradeSpec(packageRoot(), name ?? "", piAgentDir(), latest, configuredNpmSource(packageRoot(), name ?? ""));
 	if (!spec) {
 		// Nothing failed, so this is not an error: the newest release is out and the way to it is a
 		// pull, not an install that would leave a second copy beside the checkout.
@@ -779,11 +784,14 @@ async function upgrade(checkOnly: boolean, out: (line: string) => void): Promise
  * `-h` or `--help` anywhere before a `--` asks how a subcommand works, and asking must not run it:
  * `install-launcher --help` wrote the launcher and `upgrade --help` ran the upgrade. After `--`
  * they are pi's.
+ *
+ * `--version` alone names this pi-loops; `pi-loops --tui -- --version` still asks pi.
  */
-export function cliRoute(argv: string[]): "launch" | "subcommand" | "help" {
+export function cliRoute(argv: string[]): "launch" | "subcommand" | "help" | "version" {
 	const first = argv[0];
 	if (first === undefined) return "launch";
 	if (first === "--help" || first === "-h" || first === "help") return "help";
+	if (argv.length === 1 && (first === "--version" || first === "-v")) return "version";
 	if (first.startsWith("-")) return "launch";
 	const dashdash = argv.indexOf("--");
 	const before = dashdash === -1 ? argv.slice(1) : argv.slice(1, dashdash);
@@ -898,7 +906,7 @@ function launcherDirFlag(flags: ReadonlyMap<string, string | true>): string | un
  * says whose it is. With nothing there, the state asked for is already the state on disk.
  */
 export function uninstallLauncher(dir: string | undefined, out: (line: string) => void): number {
-	writeUiPref(defaultLoopsDir(getAgentDir()), "launcher", "declined");
+	writeUiPref(defaultLoopsDir(piAgentDir()), "launcher", "declined");
 	const target = launcherTarget(dir);
 	const again = "no pi session writes it again; `/pi-loops install-launcher` in pi puts it back";
 	if (!target) {
@@ -980,8 +988,8 @@ export async function installLauncher(dir: string | undefined, out: (line: strin
 	}
 	// Whatever a session start was told once, this is the answer now: a launcher exists because
 	// someone asked for it, so the offer is live again if the file ever goes.
-	clearUiPref(defaultLoopsDir(getAgentDir()), "launcher");
-	clearUiPref(defaultLoopsDir(getAgentDir()), "launcherFailedIn");
+	clearUiPref(defaultLoopsDir(piAgentDir()), "launcher");
+	clearUiPref(defaultLoopsDir(piAgentDir()), "launcherFailedIn");
 	out(`wrote ${file}`);
 	out(`  it runs ${path.join(entryDir, "cli-entry.mjs")}`);
 	out("  `pi-loops` now starts a session; `pi-loops --tui` opens the terminal one instead");
@@ -1026,7 +1034,7 @@ export function launcherScript(entryDir: string, node: string, agentDir: string)
 
 /** What a launcher for *this* copy is written from, so a caller needs to know none of the three. */
 export function launcherSource(): { entryDir: string; node: string; agentDir: string } {
-	return { entryDir: path.dirname(fileURLToPath(import.meta.url)), node: process.execPath, agentDir: getAgentDir() };
+	return { entryDir: path.dirname(fileURLToPath(import.meta.url)), node: process.execPath, agentDir: piAgentDir() };
 }
 
 /**
@@ -1036,7 +1044,7 @@ export function launcherSource(): { entryDir: string; node: string; agentDir: st
  * for a command that was never put on their PATH.
  */
 export function installedByPi(): boolean {
-	return upgradeSpec(packageRoot(), manifest().name ?? "", getAgentDir(), "v0.0.0") !== undefined;
+	return upgradeSpec(packageRoot(), manifest().name ?? "", piAgentDir(), "v0.0.0") !== undefined;
 }
 
 export type LauncherState = "absent" | "current" | "stale" | "other" | "foreign";
@@ -1214,7 +1222,8 @@ async function launch(argv: string[], out: (line: string) => void, cwd = process
 	const mode = resolveUiMode({ ...asked, remoteTty: isRemoteTty() });
 	const dir = loopsDir(ours);
 	const withDefaults = applyRememberedModel(pi, readUiPrefs(dir));
-	if (mode === "terminal") return runChild(process.env.PI_BIN || "pi", withDefaults);
+	// The extension in that terminal reads its directory from the environment, not from our flags.
+	if (mode === "terminal") return runChild(process.env.PI_BIN || "pi", withDefaults, has("loops-dir") ? { ...process.env, PI_LOOPS_DIR: dir } : undefined);
 
 	const refused = pageFlagRefusal(ours);
 	if (refused) {
@@ -1267,7 +1276,7 @@ export async function openPage(
 	// pi-loops is up; if it does not come up, the stop stays as it was.
 	const liftedStop = readUiPrefs(dir).host === "stopped";
 	if (liftedStop) clearUiPref(dir, "host");
-	const ensured = await ensureHost(how.host);
+	const ensured = await ensureHost({ ...how.host, onLeaveWait: () => process.stderr.write(`${RESTART_WAIT_LINE}\n`) });
 	// Running, started, or being started by a window right now: each of these has a page coming.
 	const why = ensured.error ?? (ensured.action.kind === "none" && ensured.action.reason !== "running" && ensured.action.reason !== IN_PROGRESS ? ensured.action.reason : undefined);
 	const rec = await waitForSocket(dir, why ? 0 : PAGE_WAIT_MS);
@@ -1383,7 +1392,7 @@ function socketOpen(socketPath: string): Promise<boolean> {
  */
 export function pageAddress(dir: string): string {
 	const config = loadConfig(dir);
-	const port = pageBindPort(config, { defaultDir: path.resolve(dir) === path.resolve(homeLoopsDir(getAgentDir())), env: process.env.PI_LOOPS_PAGE_PORT });
+	const port = pageBindPort(config, { defaultDir: path.resolve(dir) === path.resolve(homeLoopsDir(piAgentDir())), env: process.env.PI_LOOPS_PAGE_PORT });
 	return port ? `${config.pageHost}:${port}` : `${config.pageHost} (on a free port; pi-loops status names it)`;
 }
 
@@ -1427,7 +1436,7 @@ export function pageFlagRefusal(ours: string[]): string[] | undefined {
  * already has, found the way `pi-loops export` finds it and taken out of pi's arguments; without
  * either, a new one in `cwd` with the arguments as they are.
  */
-export function pageTarget(piArgs: string[], cwd: string, sessionsRoot = path.join(getAgentDir(), "sessions")): { sessionId?: string; sessionFile?: string; piArgs: string[] } | { error: string } {
+export function pageTarget(piArgs: string[], cwd: string, sessionsRoot = path.join(piAgentDir(), "sessions")): { sessionId?: string; sessionFile?: string; piArgs: string[] } | { error: string } {
 	const rest: string[] = [];
 	let id: string | undefined;
 	let latest = false;
@@ -1538,7 +1547,7 @@ export function loopsDir(ours: string[]): string {
 	if (at !== -1 && ours[at + 1]) return ours[at + 1];
 	const eq = ours.find((a) => a.startsWith("--loops-dir="));
 	if (eq) return eq.slice("--loops-dir=".length);
-	return process.env.PI_LOOPS_DIR || defaultLoopsDir(getAgentDir());
+	return process.env.PI_LOOPS_DIR || defaultLoopsDir(piAgentDir());
 }
 
 /**

package/src/engine.ts

@@ -1079,8 +1079,9 @@ export function deadLetterText(why: string, prompt: string): string {
 	return `could not be delivered (${why}): ${prompt}`;
 }
 
-/** The parts of a finding `deadLetterText` wrote, or undefined for any other finding. */
-export function deadLetterParts(text: string): { why: string; prompt: string } | undefined {
+/** The parts of a dead letter's text, or undefined for any other finding: the engine's mark decides, never the text. */
+export function deadLetterParts(entry: { text: string; undelivered?: true }, text = entry.text): { why: string; prompt: string } | undefined {
+	if (!entry.undelivered) return undefined;
 	const m = /^could not be delivered \((.*?)\): ([\s\S]*)$/.exec(text);
 	return m ? { why: m[1], prompt: m[2] } : undefined;
 }
@@ -1098,7 +1099,7 @@ async function deadLetter(store: RequestStore, sinks: EngineSinks, sessionId: st
 	if (rule !== undefined) {
 		if (!checkDecidedFinding(sinks.audit, row.id)) await sinks.inbox.appendOnce({ source: `trigger:${rule}`, run_id: row.id, job_id: rule, cwd, text: text || `rule result ${row.id}`, session_id: sessionId }, { run_id: row.id, source: `trigger:${rule}` });
 	}
-	else await sinks.inbox.append({ source: row.source, run_id: row.id, cwd, text: deadLetterText(why, text.slice(0, DEAD_LETTER_CHARS) || `${row.kind} request ${row.id}`), session_id: sessionId });
+	else await sinks.inbox.append({ source: row.source, run_id: row.id, cwd, text: deadLetterText(why, text.slice(0, DEAD_LETTER_CHARS) || `${row.kind} request ${row.id}`), session_id: sessionId, undelivered: true });
 	sinks.audit.appendAudit({ cwd, type: "request", traceId: row.id, state: "dead", sourceLabel: row.source, eventLabel: row.session_id, summary: text, details: { session_id: row.session_id, kind: row.kind, attempts: row.attempts, last_error: row.last_error, reason: why } });
 	store.remove(sessionId, [row.id]);
 }

package/src/host-control-channel.ts

@@ -16,6 +16,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { DEAD_AFTER_ATTEMPTS, formatWait, heldTurnFor, stopRow } from "./engine.ts";
 import { snapshotLoopLabel } from "./job-lines.ts";
+import { plural } from "./plural.ts";
 import { type LeaseStore, type ProcessProbe, holderAlive, sessionFileName } from "./lease.ts";
 import { conversationLabel, shortSessionId } from "./session-head.ts";
 import { previewRedacted, redact } from "./redact.ts";
@@ -205,7 +206,7 @@ export function requestLines(queues: readonly RequestQueue[], now: number, opts:
 	const dead = queues.reduce((n, q) => n + q.dead, 0);
 	const undelivered = (n: number) => `${n} could not be delivered`;
 	const where = (q: RequestQueue) => (q.holder.kind === "terminal" ? `open in pid ${line(q.holder.pid)}` : q.holder.kind === "host" ? "in the background" : "closed");
-	const head = `  ${total} message${total === 1 ? "" : "s"} waiting for ${queues.length} conversation${queues.length === 1 ? "" : "s"}${dead ? `, ${undelivered(dead)}` : ""}`;
+	const head = `  ${plural(total, "message")} waiting for ${plural(queues.length, "conversation")}${dead ? `, ${undelivered(dead)}` : ""}`;
 	return [head, ...queues.map((q) => `    ${shortSessionId(line(q.sessionId))}: ${line(q.count)} waiting · oldest ${formatWait(now - Date.parse(q.oldest))}${q.dead ? ` · ${undelivered(q.dead)}` : ""}${opts.where === false ? "" : ` · ${where(q)}`}`)];
 }
 

package/src/host-control.ts

@@ -604,6 +604,12 @@ export interface EnsureHostOptions extends SpawnHostOptions {
 	page?: true;
 	/** How long an upgrade waits for the old process to leave; `LEAVE_WAIT_MS` unless a test says. */
 	leaveWaitMs?: number;
+	/**
+	 * Called once when an upgrade is still waiting for the old process after `leaveNoticeMs` (2 s):
+	 * it is letting a turn in the page finish, and a person waiting on this call is told why.
+	 */
+	onLeaveWait?: () => void;
+	leaveNoticeMs?: number;
 	/**
 	 * Whether a start waits for the process to record itself (up to 10 s). Every caller waits but a
 	 * window that is quitting: it has nothing to do with the answer, and waiting made quitting slow.
@@ -645,13 +651,22 @@ export async function ensureHost(opts: EnsureHostOptions): Promise<{ action: Ens
 	if (action.kind === "upgrade") {
 		recordUpgrader(opts.dir, { pid: process.pid, version: opts.myVersion, procStart: procStart(process.pid) });
 		await askHost(opts.dir, { op: "upgrade" });
+		// A quitting window asks and goes. The claim above holds older windows back; the next window,
+		// or the next `pi-loops`, starts this version once the old process has left.
+		if (opts.wait === false) return { action };
 		// Wait for it to go and start this version at once: the gap until the next tick is where an
 		// older window used to start the old code again. It may first let a turn in the page finish.
 		const old = rec!.pid;
-		const deadline = Date.now() + (opts.leaveWaitMs ?? LEAVE_WAIT_MS);
+		const began = Date.now();
+		const deadline = began + (opts.leaveWaitMs ?? LEAVE_WAIT_MS);
+		let told = false;
 		while (Date.now() < deadline) {
 			const now = readHostService(opts.dir);
 			if (!now || now.pid !== old || !hostServiceAlive(now)) break;
+			if (!told && Date.now() - began >= (opts.leaveNoticeMs ?? 2_000)) {
+				told = true;
+				opts.onLeaveWait?.();
+			}
 			await new Promise((r) => setTimeout(r, 100));
 		}
 		const still = readHostService(opts.dir);