@kingcrab/pi-imessage 0.0.43 → 1.0.0

package/docs/adr/0010-test-budget.md

@@ -0,0 +1,11 @@
+# 0010. About 40 tests, only for our code
+
+Status: accepted (2026-10-04; owner accepted 2026-10-05)
+
+**Context.** #31 reached 404 tests. Many retested Durable's own guarantees, or killed subprocesses to probe crash windows.
+
+**Decision.** At most about 40 tests, each for a distinct behavior of our code. Faux provider, temp directories and a fake sender; never real Messages, models or production data. Durable's guarantees (crash resume, tool replay, request dedupe) are not retested. To add a test over budget, delete a weaker one first. Real model and Messages checks live in a manual `ops/smoke.ts`.
+
+**Consequences.** Some bugs will ship; each gets a regression test when found.
+
+**Rejected.** Subprocess crash tests. A unit test per function.

package/docs/adr/0011-reconcile-unsent-answers.md

@@ -0,0 +1,24 @@
+# 0011. Reconcile unsent answers after intervening input
+
+Status: accepted (2026-10-04; owner chose reconciliation and explicitly included different senders)
+
+**Context.** Native steer places all selected messages after a tool round when configured with `steeringMode: "all"`. At a final-answer boundary, however, Durable first records the answer and settles that run's inputs; selected new messages start another run. The earlier answer remains eligible for delivery even when a newer message corrects its assumptions. An `onYield` continuation does not change this: it is ignored when the boundary selects user input. See [the state ownership decision](0001-durable-owns-state.md) and [at-most-once replies](0003-replies-at-most-once.md).
+
+**Example.** The model is finishing a two-day itinerary when the user says “three days instead.” Sending both itineraries is confusing. Conversely, blindly dropping the first answer when the new message asks an unrelated question can lose useful work.
+
+**Decision.** Reconcile delivery, not execution:
+
+- If newer ordinary input was durably accepted before an answer's transport claim, hold that unattempted answer for reconciliation. Do not abort or replay the completed tools.
+- Give the next generation truthful information about which assistant answers were actually sent and which remain drafts. It must apply corrections, retain valid completed work and answer unrelated questions separately in its final response.
+- Include messages from different senders in that decision. Keep each sender's identity and request distinct; a later sender does not automatically retract or correct another person's request. Reconcile shared tasks where appropriate and ask for clarification when their requirements conflict.
+- Supersede held drafts only when a replacement final answer is durably ready. Preserve all original entries and explicit delivery disposition for inspection.
+- If reconciliation fails or is cancelled, retain the held drafts for inspection; do not automatically release possibly obsolete answers. Operator-facing state must explain why a reply is held. No silent deletion.
+- A reply already claimed as `sending` cannot reliably be retracted. Later input affects future replies. Existing `sent`/`unknown` receipts remain authoritative and are never automatically retried.
+
+This is not permission to change Durable's inbox, introduce a host model loop, add a debounce window, replay a turn or classify topics with a second model call. Slash-command cancellation requires its own command-boundary handling.
+
+**Consequences.** A late unrelated message can delay an otherwise valid answer; the next response must preserve that answer rather than assume it was delivered. Continuous input can extend this delay. Reconciliation failure can leave visible undelivered drafts requiring intervention. The owner accepted these product trade-offs.
+
+**Alternatives.** Always send every completed answer (preserves delivery timing but exposes obsolete answers). Drop all but the latest answer (can silently lose unrelated answers). Guess corrections from keywords (unreliable). Change or wrap Durable's internal finalization logic (violates state ownership).
+
+**Approval.** The owner selected waiting for the next turn and replying together, explicitly including different senders in the decision. This approval covers reconciliation of unattempted replies, not retraction or replay of claimed sends.

package/docs/adr/0012-run-in-owned-conversation.md

@@ -0,0 +1,22 @@
+# 0012. `/run` works in a conversation owned by one task
+
+Status: accepted (2026-10-04; owner accepted 2026-10-05). Replaces the `/run` part of [0008](0008-compaction-and-run.md); its compaction part stays.
+
+**Context.** In 0008, `/run` works inside the chat's own conversation. Stopping it then means telling run work apart from ordinary work: `Conversation.abort()` also withdraws ordinary queued messages, so the draft tracked submission IDs and command receipts by hand. Durable already scopes abort by ownership: aborting a task aborts the conversations and work it owns.
+
+**Example.** The user sends `/run 30m plan a two-day trip`, then "make it three days". The correction must reach the run. A later `/stop` must end the run without touching anything else.
+
+**Decision.**
+
+- `/run <duration> [task]` creates one Durable task that owns a fork of the chat conversation at its newest entry. The fork inherits the context; nothing is copied or summarized. The task text (default: continue the current task) is the fork's first input. One run per chat.
+- `/run` starts only when the chat conversation is idle. Otherwise it replies that the chat is busy and does nothing: no queueing, no moving of running work. A repeated `/run` during a run updates the deadline; a task text in it is sent to the run like an ordinary message.
+- While a run is active, all ordinary messages of the chat go to the run conversation as steers, with the message GUID as request ID. Commands do not.
+- An `onYield` hook continues the run until the model calls `end_run` (done, or the user is needed) or the deadline passes. The deadline only stops continuation: the current turn finishes, so a run can overrun. Ordinary messages do not extend it. Without unfinished work, the model ends the run instead of inventing a task.
+- Final answers of the run conversation are delivered as they are committed, including those between continuations, under [0003](0003-replies-at-most-once.md) and [0011](0011-reconcile-unsent-answers.md).
+- `/stop` aborts the run task. Durable aborts the run's work and withdraws its queued messages; they stay in history, unanswered, and are not resubmitted anywhere. Without an active run, `/stop` replies that nothing is running. There is no `/run-stop`. `/new` also stops the run.
+- A restart does not stop a run. `resume()` continues the run task like any other pending work, with the deadline from our run document; if it passed during the downtime, the current turn finishes and the run ends. Replies interrupted mid-send follow [0003](0003-replies-at-most-once.md).
+- The chat conversation keeps the record: the run's user messages and sent replies are written to it as passive entries, plus how the run ended. Tool calls and results stay in the run conversation, searchable under `durable/` like other history.
+
+**Consequences.** Stopping needs no submission bookkeeping and no command receipts. During a run, the chat has one place where work happens. Messages still queued in the run when `/stop` arrives are dropped, a narrower promise than before. After the run, the chat conversation knows what was said, not how; the model searches the run conversation when it needs details.
+
+**Rejected.** Running in the chat conversation (per-submission abort bookkeeping). A blank run conversation (loses earlier requirements). Queueing `/run` behind ordinary work, or moving running work into the run. Durable's background-subagent example as is (named agents and reporter tasks we don't need). A separate `/run-stop`. Aborting runs at startup (extra code against Durable's resume, and a silent stop the user would wait on).

package/docs/adr/0013-thin-adapters-around-durable.md

@@ -0,0 +1,18 @@
+# 0013. Use Durable directly; keep adapters thin
+
+Status: accepted (2026-10-04; owner accepted 2026-10-05)
+
+**Context.** The drafts grew host state that Durable already keeps (per-command receipts with running/unknown recovery, a reply scan over every settled submission) and copies of other systems (a gzip/base64 Python memory backend inside TypeScript, a vendored 1,000-line scheduler). [0001](0001-durable-owns-state.md) says Durable owns chat state; this records where our code stops.
+
+**Decision.**
+
+- **Commands** call Durable APIs directly (`configure`, `compact`, `reset`, task abort). Each command is first written to the chat conversation as a passive entry with the message GUID as request ID, so a repeated row is skipped by Durable's dedupe. An interrupted command is not replayed. No command receipt state.
+- **`/reload`** rereads settings, models and auth, AGENTS and skills, and reinstalls our extensions under the same names; Durable's registry replaces them in place. Running calls finish on their old code. Nothing is paused or cancelled.
+- **Memory tools** run the store's own CLI, `WORKING_DIR/skills/file-memory/memory_cli.py`, which finds its data next to itself. No embedded or rewritten backend; a missing CLI is a tool error.
+- **Scheduler** keeps the clock: cron expressions, timezones, reminders and their files (`cron/jobs.json`, reminders). When a job fires it submits to Durable with a stable request ID, or sends directly with a receipt. After acceptance, Durable owns execution and recovery; the scheduler never retries model work. Durable 1.0.2 has task `sleep` but no cron or reminder service, so it is not used as one.
+- **Web pages** are read-only: they show Harness state and watches (history, live state, task graph, usage) and have no buttons. They keep no execution log of their own. The endpoints in [the HTTP API](../api.md) stay; endpoints used only by the old page buttons (per-chat reply toggle, PT task actions) are removed. Replies are enabled through the settings allowlist; cron jobs are run or paused through the API.
+- **Our documents** hold only what Durable cannot know: the `chat.db` cursor, the chat-to-conversation map, send receipts and the active run with its deadline.
+
+**Consequences.** Little host recovery code beyond send receipts. Memory needs Python and the store's CLI at runtime (Python is already a prerequisite). The scheduler stays a larger, separate module, isolated behind one submit or send call.
+
+**Rejected.** Command receipts and a command state machine. Pausing work around `/reload`. Embedding or reimplementing the memory backend. Rewriting cron and reminders as Durable tasks. A separate execution log for the UI. Page buttons, including a resend button for `unknown` replies.

package/docs/adr/0014-ephemeral-private-storage.md

@@ -0,0 +1,13 @@
+# 0014. Keep ephemeral transcripts in disposable private storage
+
+Status: superseded by [0018](0018-tasks-without-prompt-api.md) (2026-10-05). Was: proposed (2026-10-04)
+
+**Context.** The retained HTTP `ephemeral:true` contract removes an isolated session after its queued work finishes. Durable 1.0.2 has reset/compaction but no public single-conversation deletion API. Reset hides old context from the model; it does not erase stored prompts, tool results or child conversations.
+
+**Example.** An automated task reads private files. Its final answer may stay in the destination chat, but its private task transcript must not remain searchable in the ordinary conversation store after cleanup.
+
+**Decision proposed for owner acceptance.** Give each active ephemeral `(chatGuid, sessionKey)` its own private JSONL storage and native Harness. Let Durable own that storage's inbox, dedupe, steering, tasks and recovery. The main store keeps only opaque identity/lifecycle metadata needed to locate it and external send receipts, not its private prompt/tool transcript. Admission success follows persisted private admission. On restart, reopen recorded private storage and resume its native work; never replay a whole turn in the host. Deliver completed answers with stable main-store receipts. Once the private Harness is idle and its completed answers have an authoritative sent/unknown disposition, close it and remove its directory with restart-safe cleanup. A later batch with the same key starts a fresh private context. Do not remove an active directory or silently lose queued work.
+
+**Consequences.** Extra storage/lifecycle wiring is necessary for the old privacy promise, but no second model loop or mirrored inbox. Repeated request IDs and uncertain sends need checks across cleanup/restart. HTTP ephemeral admission remains blocked until this design is accepted, implemented and verified. Ordinary API/cron contexts stay in the shared store.
+
+**Rejected.** Calling reset and claiming deletion. Editing shared append-only storage behind Durable. Retaining private transcripts in the main store. Dropping ephemeral behavior without owner approval.

package/docs/adr/0015-ordinary-stop-keeps-native-inbox.md

@@ -0,0 +1,21 @@
+# 0015. Ordinary `/stop` keeps the native inbox
+
+Status: superseded by [0018](0018-tasks-without-prompt-api.md) (2026-10-05). Was: proposed (2026-10-04). Replaces only the no-active-run `/stop` clause of proposed [0012](0012-run-in-owned-conversation.md) if accepted. Does not approve its other behavior changes.
+
+**Problem.** Ordinary `/stop` must cancel current work and foreground children, suppress unclaimed old replies, and preserve later unprocessed ordinary messages. `Conversation.abort()` in Durable 1.0.2 cancels the conversation's foreground scope but withdraws queued inputs. Looking up `LiveDoc.run.taskId` and calling `abortTask()` preserves the parent inbox, but is not equivalent: generation hands over to a new conversation-owned task between turns. The old task can become terminal between lookup and abort; aborting it then does nothing to the new generation.
+
+**Example.** A request reads a file and continues into another model turn. A later ordinary message is queued. `/stop` must cancel the ongoing request, even at that turn boundary, without losing or resubmitting the later message.
+
+**Decision.**
+
+- Preserve this ordinary-chat behavior; do not silently replace it with “nothing is running” or queue withdrawal.
+- Require a supported native conversation-scope cancellation operation that atomically selects current foreground work while retaining the root chat's queued inputs. Cancellation of work owned below that scope must still follow Durable's ownership rules. The operation must define admission during cancellation and behavior across generation handover.
+- Use the native operation directly. After cancellation settles, suppress old unclaimed drafts using existing delivery records; never change `sending`, `sent` or `unknown` receipts or claim that a started send was undone.
+- If preserved inputs require a new boundary, submit one passive cancellation note through the public conversation API. Durable places existing inbox items; the host never copies their content, creates replacement input submissions, or replays the cancelled request.
+- Keep `/run` cancellation and isolated API/cron/background/health sessions separately scoped. This decision does not accept dropping queued run messages or cancelling unrelated sessions.
+
+**API boundary.** Durable 1.0.2 exposes no retain-inbox option on `Conversation.abort()`, and its public transaction API has no atomic task-abort operation. An upstream API change and dependency upgrade are required before this design can be implemented as specified. Do not patch installed package files or write the built-in live/inbox documents to simulate that operation.
+
+**Evidence.** The [inbox example](https://github.com/earendil-works/pi/blob/main/packages/durable/test/examples/20-inbox.ts), installed `harness/generation.js` (`createGeneration`, `handOver`), `harness/scheduler.js` (`abort`, `abortConversation`) and public `Tx` declarations establish the distinction. A bounded faux-provider experiment reproduces generation-ID handover and the stale-ID abort no-op; aborting the current generation preserves the queued input, and a passive write places it without a replacement submission. That experiment does not establish a race-free host cancellation implementation.
+
+**Rejected.** Repeated lookup/abort polling, a host cancellation epoch or mirrored inbox, withdrawing and resubmitting queued inputs, direct edits of Durable internals, and treating a cancelled wait as cancelled work. Also rejected: claiming a single generation-task abort cancels a whole multi-turn request.

package/docs/adr/0016-process-http-transport.md

@@ -0,0 +1,21 @@
+# 0016. Initialize one process-owned HTTP transport
+
+Status: accepted (2026-10-05; owner accepted 2026-10-05)
+
+**Problem.** Pi's global `httpProxy` and `httpIdleTimeoutMs` settings need HTTP transport setup, not just request-option forwarding. Coding-agent's experimental Durable startup calls `applyHttpProxySettings()` and `configureHttpDispatcher()`, but neither is a public export of coding-agent 1.0.2. Merely assigning `HTTP_PROXY` and `HTTPS_PROXY` after Node starts does not reconfigure the dispatcher created by `--use-env-proxy`.
+
+**Example.** An operator sets `httpProxy` in Pi settings without shell proxy variables. The service must use that proxy for authentication and model HTTP requests. Setting the variables at service startup can otherwise leave fetch connecting directly. A provider request timeout also does not replace a socket's inactivity timeout.
+
+**Decision.**
+
+- The host owns one process-wide HTTP setup, initialized before opening model/auth runtime. Individual chats and private Harness instances do not install global dispatchers.
+- Use public Undici APIs, with an exact direct dependency matching the supported SDK implementation, rather than importing private coding-agent files. Supply the global Pi proxy setting only as environment defaults; retain explicit environment proxy values, lowercase precedence and NO_PROXY behavior. Do not accept project-local proxy overrides where Pi accepts only global configuration.
+- Configure native HTTP headers/body idle timeouts from Pi settings, including disabled timeout semantics. Keep transport fetch and dispatcher on the same Undici implementation so compressed responses are decoded consistently. Preserve deliberately supplied fetch implementations. Follow the SDK's connection-family and client-error handling rather than inventing transport retries.
+- `/reload` may replace transport for subsequent requests without cancelling active work. Track transport resources in memory only, let active requests finish on their original clients, and retire old clients safely. During shutdown, stop producers and Harness work before releasing transport; restore globals only if they are still ours. Never close a dispatcher owned by another caller.
+- Durable/provider retry policy and request timeout options remain unchanged. This setup is not a host activity timer, prompt deadline, compaction deadline, inbox or execution loop.
+
+**Consequences.** Process-global HTTP setup belongs to application lifecycle, not per-conversation configuration. Standalone callers with an injected runtime/fetch keep control of their transport. The implementation must verify proxy precedence/bypass, compressed responses, idle timeout enable/disable, reload with active requests, cleanup and custom-fetch preservation against loopback fixtures before claiming compatibility.
+
+**Evidence.** The installed coding-agent `core/http-dispatcher.js` and experimental [harness setup](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/experimental/durable/harness-setup.ts) use Undici EnvHttpProxyAgent and matching fetch globals. A bounded Node 26 loopback experiment confirms late environment defaults leave built-in fetch direct, while public Undici 8.10.2 dispatcher plus matching fetch routes through the configured proxy. This establishes an implementation path, not completed lifecycle/timeout behavior or real-provider connectivity.
+
+**Rejected.** Environment mutation as proof of effective transport, request timeout as proof of socket-idle enforcement, private SDK imports, patching installed packages, a new HTTP retry algorithm, and relying on newer Node-only proxy-reset APIs while retaining Node >=22.22.2 support.

package/docs/adr/0017-browser-cli-owned-scope.md

@@ -0,0 +1,22 @@
+# 0017. Invoke browser CLI in a native conversation-owned scope
+
+Status: accepted (2026-10-05; owner accepted 2026-10-05). Replaces only the browser-through-unrestricted-bash part of proposed [0004](0004-native-extensions.md) if accepted.
+
+**Problem.** `PI_BROWSER_HOME` scopes the pi-browser wrapper's profiles/output, not Playwright CLI's daemon registry. CLI 0.1.19 keeps that registry in the user's cache directory, derives daemon workspace identity from `.playwright` or the installed package, and enumerates other workspaces. All chats currently share the same shell environment and working directory. A named session or separate profile directory alone therefore does not preserve the old browser adapter's private-session rules.
+
+**Example.** Two chats both use `-s=task`. Even with different PI_BROWSER_HOME values, they can resolve the same daemon/session and see other registry entries. Giving the model a suggested name is not enforcement.
+
+**Decision.**
+
+- Offer a thin native Durable browser tool that invokes the installed, pinned pi-browser CLI by argv. Do not load an SDK browser extension, emulate ExtensionAPI, vendor CLI internals or implement another browser driver.
+- Derive browser scope from canonical storage identity plus native conversation identity, not a model-selected name. Ordinary chats, runs and isolated API/cron contexts get distinct scope; disallowed read-only contexts do not get the tool.
+- Give only browser child processes a dedicated HOME, profile/output root and scoped working directory. Leave ordinary coding tools' HOME/cwd unchanged. Use public process/CLI controls rather than PWTEST daemon/socket environment variables. Verify daemon discovery and attachment cannot escape the scope, including environment-inherited external browser targets.
+- Always select the owned session/profile and headless mode. Deny attachment/discovery, global close/kill, arbitrary profile/config paths and headed overrides, retaining the old service's restrictions. Expose the ordinary browsing operations needed by the product through validated arguments; operation results remain untrusted data.
+- Close owned browsers at the agreed stop/shutdown boundaries without touching unrelated sessions. Track only external browser resources and cleanup facts, not a second task state machine. Define restart cleanup and privacy retention before claiming isolation. Do not silently delete saved login profiles or replay uncertain browser mutations.
+- Do not mistake this tool boundary for an OS sandbox: unrestricted bash/read can still access host files and invoke other executables. State that limit explicitly; stronger containment requires a separate decision.
+
+**Consequences.** Native tool registration replaces browser instructions as the enforcement boundary for normal product use. The browser skill can still explain workflows, but cannot be the sole privacy mechanism. Actual Chrome/CLI fixtures must verify same-name sessions in different scopes, registry isolation, profile/config rejection and owned cleanup before release.
+
+**Evidence.** The installed wrapper source separates PI_BROWSER_HOME from Playwright's registry. In a temporary copy installed with the locked manifests (`npm ci --ignore-scripts`), CLI 0.1.19's `cli-client/registry.js` uses OS HOME/cache, scans every workspace and exposes only a PWTEST-specific daemon-root override. A bounded temporary-HOME experiment confirms different PI_BROWSER_HOME values share the daemon directory and registry enumeration sees another synthetic workspace. No browser or personal profile was opened. The experiment describes the pinned implementation; production must not import those private files.
+
+**Rejected.** Profile-directory changes or prompt-only session naming as proof of isolation, private PWTEST controls, changing HOME/cwd for all bash tools, SDK extension adaptation, unscoped global browser cleanup and claiming unrestricted coding tools are sandboxed.

package/docs/adr/0018-tasks-without-prompt-api.md

@@ -0,0 +1,19 @@
+# 0018. Ordinary `/stop`; scheduled tasks without HTTP `/prompt` and `/send`
+
+Status: accepted (2026-10-05; owner accepted 2026-10-05). Supersedes proposed [0014](0014-ephemeral-private-storage.md) and [0015](0015-ordinary-stop-keeps-native-inbox.md). Replaces the HTTP `/prompt` clause of proposed [0012](0012-run-in-owned-conversation.md) and the `/send` resend hint of [0003](0003-replies-at-most-once.md).
+
+**Context.** Every production caller of HTTP `/prompt` and `/send` is a script or cron job on the same machine, plus the agent sending files through curl. The work they start runs in a separate context, but its result never reaches the chat's own conversation: when the user replies to a morning summary, the chat does not know what was sent. 0014 and 0015 wait for storage lifecycle work and an upstream Durable API.
+
+**Example.** At 08:00 a cron job runs a script that builds the newsletter prompt; the agent works in its own conversation and sends five links. The user replies "expand the third one". The chat conversation must already hold the five links, not the prompt or tool calls that produced them.
+
+**Decision.**
+
+- **Ordinary `/stop`** (no active `/run`) aborts the generation task that owns the current inputs (`LiveDoc.run`), not the conversation, so later queued messages stay in the inbox. If generation hands the same inputs to a new task meanwhile, abort that one too. Then write a passive `[/stop]` entry so Durable places the queued messages. `/stop` during a run is unchanged.
+- **Tasks.** Cron `prompt` jobs, `schedule_task` firings and background summaries each run in a fresh ownerless conversation, keyed by request ID. Nothing carries over between runs; continuity lives in the chat conversation and memory. Transcripts are kept, not deleted. The model health check reuses one conversation.
+- **The chat records what was sent.** A delivered task answer, and every service or tool send (reminders, cron `send`, background summaries, Automation, `send_message`), is written to the chat conversation as one passive entry with its delivery status, deduplicated by request ID. No extra model turn; the chat's next turn sees it.
+- **No HTTP `/prompt`, `/send` or `ephemeral`.** Cron `send` and `prompt` actions accept an optional `command` (absolute argv). Its stdout replaces the text or prompt; empty output skips the run. Scripts print instead of POSTing, and are scheduled in `cron/jobs.json`. The agent sends files and extra messages with the native `send_message` tool, using the existing direct-send receipts (tool task ID as request ID). Remaining HTTP: read-only pages, reminders, cron management and model health.
+- **Cutover.** The old service still needs `/prompt` and `/send`, so production scripts, crontab entries and `jobs.json` change in the same step as the cutover ([0009](0009-one-shot-cutover.md)).
+
+**Consequences.** One way to start agent work from outside a chat, and one place (the chat conversation) that knows what the user saw. `/stop` uses a bounded lookup/abort retry instead of an atomic native operation. Old `ephemeral` deletion is dropped; private tool output stays searchable under `durable/`. External callers on other machines can no longer prompt the agent; a future multi-entry design decides that. The shared scheduler's `jobs.json` parser gains the optional `command` field.
+
+**Rejected.** Handing task results to the chat as input (an extra model turn, interrupts current work, rewrites the sent text). Private per-session storage (0014). Waiting for an upstream cancellation API (0015). Keeping `/prompt` and `/send` as thin HTTP entries.

package/docs/adr/0019-remove-scheduled-services.md

@@ -0,0 +1,41 @@
+# 0019. Remove scheduled services from the chat application
+
+Status: proposed
+
+**Problem.** The owner wants scheduling removed from this project and will design
+it separately later. Keeping empty job files or startup switches still leaves
+scheduled effects and their dependencies in the chat application's lifecycle.
+
+**Example.** Starting messaging must not create reminder databases, register cron
+jobs, run PT checks or watch completion files, even when old configuration exists.
+
+**Decision.**
+
+- Remove cron, reminders, delayed/repeating prompts, background completion
+  watchers/summaries and PT Automation from source, tools, routes, pages, startup,
+  preflight and direct dependencies. Do not replace them with disabled stubs.
+- Keep messaging, immediate `send_message`, foreground subagents, `/run`, ordinary
+  `/stop`, native task inspection and explicit tool-less model health checks.
+  Keep the six-hour context compaction required by ADR 0008; it is a chat
+  maintenance timer, not user scheduling.
+- Keep existing settings, memory, history, receipts and offline backup/import
+  data intact. Removal does not authorize deleting stored job data, modifying
+  installed Pi extensions, or changing the operating system's crontab/launchd.
+  This application does not manage or stop independent operating-system jobs.
+- Removed scheduling and Automation endpoints return 404. There is no
+  compatibility adapter or automatic migration to another scheduler.
+- Retain historical isolated-conversation metadata for read-only inspection,
+  but do not deliver answers from retired scheduled conversations.
+
+This proposal supersedes the scheduled-service clauses of ADR 0013 and ADR 0018
+only when accepted. Their ordinary stop, immediate sending and receipt decisions
+remain unchanged. Accepted ADR files are not edited. Scope and implementation
+progress are tracked in GitHub #33, not in this document.
+
+**Consequences.** A future scheduler needs its own design and approval. Startup
+still needs independent old producers to be reviewed, and model/Messages live
+acceptance remains separate from removal of scheduled services.
+
+**Rejected.** Merely clearing job definitions, hiding tools while retaining
+workers, reviving HTTP `/prompt` or `/send`, and deleting production state as
+part of a source-code change.

package/docs/adr/0020-chat-task-progress.md

@@ -0,0 +1,41 @@
+# 0020. Report native task calls in iMessage
+
+Status: accepted (owner approved the format, exclusions, implementation and restart)
+
+**Problem.** Final-only replies leave the owner unable to see tool and task
+progress in iMessage while work is running.
+
+**Example.** A search emits `[tool] web_search · query=上海浦东 私立医院`
+before the final answer. Other custom tasks emit their native task name. A
+foreground subagent's calls use `[subagent/tool]` and go to its parent chat.
+
+**Decision.**
+
+- Observe committed native task admission with Durable's public commit API;
+  do not wrap tools, poll task phases or introduce another execution loop.
+- With `settings.json` setting `progressMessages: true`, send one plain-text
+  notice per new task to its owning, reply-enabled chat, except `pi.generation`
+  which the owner excludes. A `pi.tool` task is one tool notice, not a duplicate
+  task notice. Keep IDs internal for deduplication; do not display them.
+- Include native names, parent names and bounded argument summaries, not tool
+  outputs, thinking, free-form commands, prompts or document contents. Path and
+  search-query previews are screened for known credential indicators; URL
+  previews omit user info, paths, queries and fragments. Arbitrary user-authored
+  secrets cannot be guaranteed detectable.
+- Follow Durable's conversation ownership for child/subagent attribution.
+  Health and unrelated ownerless conversations stay local.
+- Use existing direct-send receipts keyed by task ID. Unknown sends are not
+  retried. Do not replay pre-existing live tasks on startup or generate model
+  context entries for progress notices.
+- Notifications do not gate task execution; drain admitted notices before
+  automatic final replies. Stop observation and join pending sends on shutdown.
+- Missing or false configuration retains final-only delivery. No stored
+  settings or receipt formats are removed.
+
+**Consequences.** iMessage can receive many notices. Progress reflects task
+admission, not confirmed completion. Final answers retain their existing
+reconciliation and at-most-once rules. This expands final-only chat behavior;
+accepted ADR files remain unchanged. Scope and validation belong in GitHub #33.
+
+**Rejected.** Asking the model to narrate every call, forwarding raw outputs,
+replaying old task history, or using unreliable delivery confirmation to retry.

package/docs/adr/0021-readable-progress-without-link-previews.md

@@ -0,0 +1,33 @@
+# 0021. Readable progress without automatic link previews
+
+Status: accepted (owner approved implementation and restart on 2026-10-05)
+
+Supersedes the argument-display details of ADR 0020; routing, admission,
+receipts, exclusions and recovery remain unchanged.
+
+**Problem.** `command=[128 chars]` does not explain the work. Clickable URLs
+in progress and default answers create unwanted iMessage preview cards.
+
+**Example.** `[tool] bash · 搜索上海天气 · timeout=30` reports intent without
+revealing a shell command. `url=weather．com．cn` identifies a source without
+a clickable URL.
+
+**Decision.**
+
+- Add an optional short `description` to the native bash schema. Ask the model
+  for a non-sensitive purpose in the user's language; delegate execution,
+  timeout validation and output handling unchanged to native bash.
+- Show the screened, bounded description instead of the command or its length.
+  Missing or credential-like descriptions use `执行命令`. Raw commands remain
+  private. Descriptions report intent, not verified completion.
+- URL arguments show only hostnames with fullwidth dots, never schemes,
+  user information, paths, queries or fragments. Screened path/query previews
+  omit explicit HTTP(S) URLs.
+- Default answers name sources without URLs. Provide original links when the
+  user asks. This is prompt policy, not a transport-level preview toggle or
+  a prohibition on explicitly requested links.
+- Credential screening is best effort; arbitrary secrets in model-authored
+  labels cannot be guaranteed detectable.
+
+**Rejected.** Raw shell snippets, another model call to summarize commands,
+transport retries, and claiming an unsupported Messages preview-disable option.

package/docs/adr/0022-progress-admission-and-settlement.md

@@ -0,0 +1,35 @@
+# 0022. Arrow and settlement progress notices
+
+Status: accepted (owner requested arrow/checkmark style and omitted timeout on 2026-10-05)
+
+Supersedes the admission-only notification/display decisions of ADR 0020 and
+the displayed timeout example in ADR 0021. Other safety and routing decisions
+remain unchanged.
+
+**Problem.** Character counts and bracketed tool headers are noisy. The owner
+prefers the earlier arrow/checkmark style and does not need timeout parameters
+in chat.
+
+**Example.** `→ bash: 搜索上海天气`, then `✓ bash (0.8s)` on successful settlement.
+An unsuccessful call gets `× bash (0.8s)`, never a success checkmark.
+
+**Decision.**
+
+- Observe native committed task admission and terminal settlement through the
+  existing public commit subscription, without another execution loop.
+- Emit one arrow at admission and one checkmark/cross at settlement for tasks
+  admitted during this process lifetime. Exclude generation tasks and retain
+  native parent/child ownership, allowlist and private-health routing.
+- For native tools, success requires both a completed task outcome and the
+  stored tool-result message having no error flag. Aborted, failed and missing
+  or error tool results are not success.
+- Duration is local elapsed admission-to-settlement time, including queueing;
+  it is not exact subprocess-only runtime or recipient delivery latency.
+- Keep separate direct-send receipt IDs for admission and settlement. Do not
+  replay historical starts/completions or retry uncertain sends after restart.
+- Omit timeout from displayed argument summaries only; native enforcement is
+  unchanged. Keep short screened purpose labels and non-clickable hostnames,
+  never raw commands or outputs.
+- Final replies drain already queued progress notices. Progress remains
+  optional through the existing setting. This intentionally doubles most
+  task progress notices compared with admission-only reporting.

package/docs/adr/0023-retain-progress-type-prefixes.md

@@ -0,0 +1,18 @@
+# 0023. Retain progress type prefixes
+
+Status: accepted (owner explicitly corrected the format on 2026-10-05)
+
+Supersedes the prefix-free display examples of ADR 0022 only. Admission,
+settlement, privacy, elapsed time and receipt/recovery behavior are unchanged.
+
+**Problem.** Arrows and checkmarks replaced useful type labels. The owner wants
+bracketed prefixes retained alongside the new status markers.
+
+**Example.** `[tool] → bash: 搜索上海天气`, followed by `[tool] ✓ bash (0.8s)`.
+Owned child tools use `[subagent/tool] → read: path=…` and
+`[subagent/tool] ✓ read (0.8s)`. Native non-tool tasks retain `[task]` and
+parent-qualified task prefixes. Unsuccessful settlement uses `×`.
+
+**Decision.** Render the native type/parent prefix first, then the status marker,
+then the native tool/task name and short safe summary or elapsed time. Do not
+restore timeout, raw shell commands or clickable URLs.

package/docs/adr/0024-status-marker-before-type-prefix.md

@@ -0,0 +1,13 @@
+# 0024. Status marker before the type prefix
+
+Status: accepted (owner explicitly corrected marker placement on 2026-10-05)
+
+Supersedes the prefix-first display order in ADR 0023 only. Preserve all
+native routing, safe descriptions, settlement verification and receipt rules.
+
+**Example.** `→ [tool] bash: Check the weather`, then `✓ [tool] bash (0.8s)`.
+Child tools use `→ [subagent/tool] read: path=…`. Failure uses `×` first.
+
+**Decision.** Put the status marker at the very beginning, immediately followed
+by the retained bracketed type/parent label. Ask for short everyday action
+wording instead of implementation jargon. Omit timeout and raw commands.

package/docs/adr/0025-reusable-progress-and-command-preview.md

@@ -0,0 +1,49 @@
+# 0025. Reusable progress data and short command previews
+
+Status: accepted (owner approved option 5, then clarified request/response names and app reuse on 2026-10-05)
+
+Supersedes the command-opaque/request-name display rules of ADR 0021 and the
+request display examples of ADR 0024. Native lifecycle, routing, receipt IDs,
+uncertain-effect handling and response formatting are unchanged.
+
+**Problem.** The owner wants readable request purposes, a useful short bash
+preview, no tool names in any request, and reusable rules for a future app.
+
+**Example.**
+
+```text
+→ [tool] Check the weather
+node search.mjs "Shanghai weather" --count 5
+✓ [tool] bash (0.8s)
+```
+
+**Decision.**
+
+- Requests keep the leading arrow and bracketed type/parent label. Tool names
+  do not appear as separate request labels or parenthetical suffixes. Responses
+  keep the deployed format: marker, type/parent label, native name and elapsed
+  time. This latest clarification replaces the earlier proposed hidden-bash
+  response and option-5 parenthetical response examples.
+- Bash requests add a second line with at most 100 Unicode code points,
+  including a trailing ellipsis when truncated. Screen the whole command
+  before truncation. Recognized credential indicators suppress the entire
+  preview; explicit URLs and common bare domains are defanged. Native
+  execution and timeout enforcement remain unchanged.
+- Screening is conservative and best effort, not a guarantee against arbitrary
+  unknown secrets. Do not restore raw tool outputs or document-content notices.
+- `src/agent/progress-format.ts` defines a transport-independent structured
+  ProgressEvent and pure summarization, screening and text formatting functions.
+  The native observer creates safe request/response events; iMessage is the
+  current plain-text adapter. Future apps can render event fields and reuse
+  the safety functions without parsing iMessage text or copying its lifecycle.
+- The event retains the native name internally, allowing app rendering and
+  response formatting, even though request text omits it. Raw command strings
+  do not belong in exported progress events; only screened previews do.
+- No app transport, new scheduler, listener, database or delivery replay is
+  introduced in this change. A future app connection must wire its own
+  delivery/receipt policy explicitly.
+
+**Verification.** Isolated regressions cover the request/response event format,
+all-request name omission, native command execution/failure, preview length and
+Unicode, screening before truncation, credential suppression, URL defanging,
+child attribution, unknown receipts and no restart replay.

package/docs/adr/0026-inline-command-only-requests.md

@@ -0,0 +1,16 @@
+# 0026. Inline command-only requests
+
+Status: accepted (owner specified `bash: <command>` and a 50-character limit on 2026-10-05)
+
+Supersedes the request-name omission, second-line preview and 100-character
+limit in ADR 0025. Preserve shared ProgressEvent data, screening, native
+execution, ownership, response formatting and receipt/recovery rules.
+
+**Example.** `→ [tool] bash: printf hi`, then `✓ [tool] bash (0.8s)`.
+Other tools retain the screenshot format, e.g. `→ [tool] read: path=/tmp/a.jpg`.
+
+**Decision.** Requests show native name and safe arguments inline. Bash uses
+only its screened command preview, not purpose/description text. The preview
+is at most 50 Unicode code points including an ellipsis when truncated.
+Screen the entire original command before truncation. No actual execution
+limit or output handling changes. Response notices remain unchanged.

package/docs/adr/0027-command-preview-width.md

@@ -0,0 +1,10 @@
+# 0027. Modest command preview width
+
+Status: accepted (owner delegated a slightly longer preview on 2026-10-05)
+
+Supersedes only ADR 0026's fixed 50-character width. The current default is
+80 Unicode code points, including a trailing ellipsis when truncated. This
+balances useful context with phone readability. Keep the same inline
+`→ [tool] bash: <screened command>` format and unchanged response notices.
+Whole-command screening still occurs before truncation; no purpose text,
+raw output, tool execution or channel architecture changes.

package/docs/adr/0028-command-preview-120.md

@@ -0,0 +1,8 @@
+# 0028. Use 120 characters for command previews
+
+Status: accepted (owner selected120 after viewing80/120/150/180 examples on 2026-10-05)
+
+Supersedes only ADR 0027's80-character default. Show at most120 Unicode code
+points in the command portion, including a trailing ellipsis when truncated.
+Retain the inline command-only request, existing response, whole-command
+screening before truncation and transport-independent event/formatter.

package/docs/adr/0030-shared-web-read-cache.md

@@ -0,0 +1,33 @@
+# 0030. Share a versioned web read cache
+
+Status: rejected (owner decided on 2026-10-06: a cold read takes about 40 ms, and every commit invalidated the cache anyway; the cache was removed)
+
+**Context.** The chat overview requests each conversation separately and repeats
+reads on refresh and navigation. Large native payloads include model-only data
+that the page never renders. Time-based caching would hide recent changes.
+
+**Decision.** Keep one bounded, process-local cache in `web/`, shared by pages
+and read-only APIs. Read through the owning Harness, never its storage files.
+Every non-empty Durable commit changes the native cache version. File-backed
+views validate inode, size and nanosecond modification/change timestamps on
+each access; enumerate memory namespaces on each request to detect additions
+and removals. Coalesce concurrent reads and recheck the version after loading;
+retry if it changed. Do not retain rejected reads or oversized results.
+
+Limit the cache to 128 entries and a 16 MiB serialized-size budget using
+least-recently-used eviction. This budget is not an exact JavaScript heap limit.
+Do not cache model health requests or resolved registry-dependent agent choices.
+
+Embed display-only chat data in the initial HTML and batch overview refreshes.
+Keep existing native data response shapes. SSE readiness includes a process and
+revision marker so the client can detect changes between HTML loading and stream
+attachment, without always fetching the initial view twice. Refreshes already
+in flight do not discard subsequent change notices.
+
+**Consequences.** Restart discards the cache. There is no second durable state,
+execution log, writer or model call. A response reflects versions checked while
+it is read; changes during network transit still require a later refresh. File
+freshness relies on filesystem metadata, not a fixed stale-data interval.
+
+**Rejected.** Browser-local copies as the shared cache, fixed cache TTLs,
+persistent materialized views, and rebuilding all page data on every commit.

package/docs/adr/0031-quiet-compaction-progress.md

@@ -0,0 +1,32 @@
+# 0031. Hide only six-hour compaction progress
+
+Status: proposed (owner clarified trigger-specific visibility on 2026-10-06)
+
+Narrows ADR 0020's compaction notices only for six-hour maintenance ticks.
+
+**Problem.** The six-hour timer emits `pi.compaction` progress into chat. The
+owner wants that timer quiet, but wants progress for manual `/compact` and
+automatic context-threshold/overflow compaction.
+
+**Example.** A timer tick sends neither a start nor completion notice. Manual
+`/compact` shows both notices and its command result. A native context-triggered
+compaction shows both notices.
+
+**Decision.** Track exact task IDs admitted by `compactChats` using process-local
+Harness-scoped state. Before a compaction admission notice, wait for in-flight
+timer admissions to resolve so the observer can classify the committed task
+before `compact()` has returned its ID. Suppress only a matching timer task's
+notice; without an admission notice its settlement also remains quiet. Consume
+the classification after observation. Do not mute an entire conversation or
+filter by native reason: both the timer and `/compact` use reason `manual`.
+
+Native manual, threshold and overflow task progress keeps its existing routing,
+receipts and settlement formatting. Timer execution, logs, six-hour cadence,
+manual command results and other progress are unchanged. Classification is not
+persisted because pre-start task progress is never replayed.
+
+**Verification.** An existing isolated faux-provider messaging regression with
+progress enabled checks timer admission/settlement create no notices or progress
+receipts, manual `/compact` shows progress and its result, and native tasks with
+threshold/overflow reasons retain both progress receipts. Existing tool and
+child-task progress regressions remain enabled.

package/docs/adr/0032-native-background-schedules.md

@@ -0,0 +1,58 @@
+# 0032. Native background schedules and read-only execution history
+
+Status: proposed (owner requested native scheduling, compact migration and Web history)
+
+**Problem.** The retired scheduler called HTTP `/prompt`, which no longer exists.
+The six-hour maintenance `setInterval` also loses its next deadline on restart.
+
+**Example.** Restart at 07:40 must retain tomorrow's English deadline and the
+maintenance deadline, without starting another message pipeline or recreating
+uncertain sends. A Web refresh must show both jobs without invoking a model.
+
+**Decision.**
+
+- Register one Durable scheduling extension in the agent layer. Each configured
+  job has a dedicated ownerless conversation and a conversation-owned task with
+  `background: true`. Its saved `sleep` checkpoint contains the absolute next
+  deadline. `runtime.sleep()` is an invocation-local wait, not a persisted timer.
+- An occurrence is a child task admitted atomically with the scheduler's waiting
+  checkpoint. Join with `allSettled`, then compute the next deadline, including
+  after generation failure. Native task records are the execution history; there
+  is no separate host worker database or UI execution log.
+- Support exactly six-hour chat compaction and the explicitly configured daily
+  English card. Keep native compaction, its quiet maintenance progress routing,
+  and automatic/manual compaction behavior. No arbitrary cron parser or LLM
+  scheduling tools. Do not revive legacy job files, HTTP prompt/send, reminders,
+  background completion watchers or PT Automation.
+- Daily English uses Asia/Shanghai calendar deadlines. A late start processes
+  only the current day after its scheduled time; missed days are not backfilled.
+  Compaction processes one overdue tick and skips missed interval slots. Long
+  executions never overlap themselves. Configuration is read at startup; existing
+  saved deadlines remain, with changed cadence applied to the following slot.
+- Import the configured English `used.json` once, read-only, preserving unknown
+  fields. Durable owns subsequent learning progress. Code selects due reviews
+  and enforces the existing three-expression daily limit and new-learning quota;
+  a tool-less, isolated model conversation provides wording, never updates files
+  or sends. Commit learning changes, the actual card and its outbox together.
+  Per-date card records and stable submission/request IDs prevent regeneration.
+- Deliver the outbox using existing direct-send receipts and passive chat records.
+  Sending is not transactional with Messages.app. `sending` becomes `unknown` on
+  restart; uncertain or previously accepted sends are not automatically replayed.
+  Stored learning progress means generated/displayed content, not proof of delivery.
+- `/scheduled` and `/scheduled/data` show all native configured schedules, their
+  task state/deadline, per-job latest ten occurrence tasks, and the latest ten
+  across all jobs. Show generation result separately from delivery receipt. These
+  are read-only routes; viewing them never resumes tasks or starts inference.
+
+This proposal supersedes ADR 0013's rejection of native recurring task adapters
+and ADR 0019's removal of these two scheduling features only. Other retired
+features and at-most-once transport safeguards remain unchanged.
+
+**Consequences.** The service must be running to act at a deadline. Stored
+checkpoints recover execution but cannot wake a stopped machine or process.
+Schedules remain independent of chat abort/reset. Explicitly aborting their task
+pauses them; startup does not silently recreate a terminal scheduler.
+
+**Rejected.** An external cron daemon, a second message pipeline, restoring
+`/prompt`, a timer that reschedules from each process startup, asking the model
+to remember to schedule tomorrow, and claiming exactly-once external delivery.