@kingcrab/pi-imessage 0.0.43 → 1.1.0

package/docs/adr/0047-one-scheduling-path.md

@@ -0,0 +1,158 @@
+# 0047. One scheduling path for recurring and one-off work
+
+Status: accepted (owner requested the minimal implementation on 2026-10-06)
+
+## Problem
+
+Recurring workspace jobs currently enter through a native scheduler task, while
+`serve --run-scheduled JOB --request-id ID` calls `runOnce()` and creates an
+occurrence directly. Both use Durable, but admission follows two paths, and a
+manual trial requires a service restart.
+
+Calling all work "scheduled" is not sufficient. The common path must own deadline
+persistence, deduplication and non-overlap. A trial must also retain the original
+job's business state, rather than create an empty English learning history or
+bypass the monthly quota.
+
+## Example
+
+Workplace English has a daily 07:45 trigger. An operator requests one trial now.
+The trial receives its own stable trigger ID, but targets the existing English
+job and business conversation. Reloading twice does not run it twice, and the
+regular 07:45 deadline does not move. Existing per-date card deduplication still
+applies: a trial is not permission to resend today's card.
+
+## Evaluation
+
+- **One common scheduling path:** recommended. Recurrence and an immediate trial
+  differ in their deadlines and repetition, not their executor or delivery path.
+- **One physical configuration file:** unnecessary. Keep trusted business code
+  and configuration in the workspace extensions required by ADR 0042. Their
+  declarations pass through one framework admission function.
+- **Automatic configuration polling:** unnecessary for the first version. The
+  existing `reload_extensions` tool and `/reload` already apply configuration
+  through the owning service without restart. Polling would add partial-write,
+  repeated-load and failure-handling concerns without helping deadline execution.
+- **A local CLI/socket or HTTP run API:** unnecessary here. A trial can be a
+  one-off declaration followed by the existing reload. This trades one explicit
+  reload operation for avoiding another control protocol.
+- **A separate business executor for every cadence:** rejected. Reminder,
+  script and model workflows remain native business tasks; they do not become
+  separate schedulers.
+
+## Decision
+
+### One admission and execution path
+
+```text
+Workspace extension configuration
+                |
+      startup / reload_extensions / /reload
+                |
+       validate and register triggers
+                |
+       native background Scheduler task
+                |
+       sleep(persisted absolute deadline)
+                |
+       native occurrence wrapper
+                |
+       registered native business task
+                |
+       native receipts -> read-only Scheduled Web
+                |
+       optional outbox -> existing send receipts
+```
+
+The reload commands are configuration-loading entry points, not direct execution
+paths. No file edit alone invokes business work. An immediate trial becomes due
+once its declaration has been accepted; it is not a promise of zero latency.
+The service must be running, and publication of validated code/configuration must
+complete before newly due work can execute under that definition.
+
+The framework retains one owning Harness. Do not introduce another daemon,
+operating-system timer, SDK scheduler bridge, database, or polling watcher.
+
+### Job identity and trigger identity
+
+- A **job** names registered business code, input, destination and its existing
+  business conversation/state. It is not an arbitrary command or prompt supplied
+  by a new public execution API.
+- A **trigger** names when that job is eligible to run. Recurring triggers and
+  one-off triggers use the same registration function and scheduler definition.
+- The minimal version preserves elapsed-time intervals and one local daily slot,
+  and adds a one-off absolute deadline or `now`. Multiple daily slots and monthly
+  calendars are deferred, not part of this first change. Do not add a cron parser.
+- Resolve `now` to an absolute timestamp once, in the admission transaction.
+  Persist the stable trigger ID, target job and deadline together. Subsequent
+  reloads/restarts recover that trigger, including a terminal one; they never
+  reevaluate `now`. A new intended trial needs a new trigger ID. Conflicting reuse
+  of a one-off ID fails explicitly.
+- A one-off declaration targets an existing registered job. Do not give it a
+  fresh business conversation, reset learning/checkpoints, or change the regular
+  trigger's deadline. A workspace extension must provide this declarative trial
+  binding; trial requests do not require generating a new extension per run.
+- Enforce non-overlap by target job, not merely by trigger. A due one-off can wait
+  for that job's active occurrence, then admit its own occurrence. Do not report
+  another trigger's work as completion of the new request.
+- Commit occurrence admission and the scheduler checkpoint together. A one-off
+  scheduler becomes terminal after its occurrence; a recurring scheduler saves
+  the next deadline. Failures remain visible in native occurrence records.
+
+### Recovery, reload and delivery
+
+- Preserve ADR 0042's machine-local calendar/DST rules, saved absolute deadlines,
+  daily/interval overdue behavior and lack of historical backfill. A one-off
+  admitted before shutdown runs once when overdue after restart.
+- Load and validate a complete candidate before accepting declarations. A failed
+  reload leaves old definitions and schedules active and must not start a trial.
+  Reload does not interrupt existing business calls. Pausing/removing a declaration
+  prevents future admission, not undoing already admitted effects.
+- Use native task versions/migrations where persisted structures change. Preserve
+  existing job/conversation/task IDs, learning state, checkpoints, execution
+  history and delivery receipts. Do not recreate terminal trials on startup.
+- Business tasks keep their own replay and success policy under ADR 0041. A shared
+  clock does not make a script's external effects transactional or replay-safe.
+  Reflection advances its checkpoint and starts backup only after verified success.
+- Keep the existing outgoing queue and at-most-once transport receipts. An
+  interrupted send becomes `unknown` and is not automatically resent. One-off
+  execution does not override a business quota, per-date dedupe or a send receipt.
+- Reuse the compact Scheduled page and native occurrence history. Show one-off
+  executions under their target job, with links to their Task tree. Viewing the
+  page starts no work; add no execution buttons.
+
+### Entry points removed or deferred
+
+After the unified one-off path is available, remove the operator startup-run
+flags and the direct-occurrence `runOnce()` bypass. Keep their historical request
+and execution records; do not replay them during migration. Do not add a CLI or
+Unix socket replacement.
+
+ADR 0045 remains a separate proposal about chat scheduling tools. This ADR does
+not enable or reject those tools. If accepted, their declarations must use this
+same admission/clock/occurrence path, preserve chat ownership boundaries, and
+must not introduce another scheduler or call a business executor directly.
+
+## Scope and consequences
+
+Framework changes concern the schedule declaration contract, common admission,
+calendar calculation, scheduler lifecycle and removal of the operator bypass.
+Personal messages, weather/news logic, memory updates, photo-date checks and
+Reflection remain workspace extensions, not framework-specific branches.
+
+Restoring the selected legacy jobs uses this path. Stop only their competing old
+cron producers during the authorized cutover; do not disable unrelated system
+jobs. Fixed-message business tasks do not restore the retired reminder service,
+PT workers or HTTP `/prompt` / `/send`. No restoration or migration is performed
+by accepting a file reload alone
+unless those jobs are explicitly declared.
+
+The first version requires an explicit reload after editing configuration. This
+is intentional: it avoids a new watcher and a new management service. Persistence
+cannot wake a stopped process or machine. Exactly-once external delivery is not
+claimed.
+
+This supersedes only ADR 0042's operator-run clause (which
+consolidated ADR 0033), and extends its cadence/declaration contract. Its workspace
+ownership, recovery and delivery rules remain in force. Accepted ADRs stay
+unchanged.

package/docs/adr/0048-quiet-attachment-reads.md

@@ -0,0 +1,11 @@
+# 0048. Quiet attachment reads
+
+Status: proposed (owner-requested behavior in #38, 2026-10-07)
+
+**Problem.** Reading an archived attachment adds noisy tool notices containing long private archive paths.
+
+**Example.** A native `read` of `WORKING_DIR/attachments/<chat>/<file>` produces no request or completion notice. An ordinary file read still shows the existing progress pair.
+
+**Decision.** Add a narrow exception to ADR 0040's all-tool progress rule: suppress both admission and settlement notices for native `read` calls under the active workspace attachment root, including owned child calls and failed reads. Normalize relative, home, @ and file-URL paths and resolve filesystem aliases using metadata only. Match directory boundaries, not a generic attachment substring. Other reads, tools, task progress, manual compaction and final replies remain unchanged.
+
+The existing native observer filters before assigning notice routing or making direct-send receipts. Execution, result/error history, receipt/no-replay rules and the single pipeline are unchanged. No new poller, sender, permission boundary, data removal or credential policy is introduced.

package/docs/adr/0049-per-chat-progress-notices.md

@@ -0,0 +1,21 @@
+# 0049. Per-chat progress notices
+
+Status: proposed (owner-requested implementation, 2026-10-24)
+
+**Problem.** `progressMessages` in `settings.json` turns tool progress notices on or off for every chat at once. A busy group wants only the final messages while an admin chat wants to watch the tools.
+
+**Example.**
+
+```text
+/verbose            -> Verbose: on (default)
+/verbose off        -> Verbose: off (this chat only)
+/verbose default    -> Verbose: on (default)
+```
+
+**Decision.**
+
+- Each chat record in the native `imessage.chats` document gets an optional `progress` boolean. `/verbose on|off` sets it and `/verbose default` removes it; `/verbose` alone reports the effective state. The record version is unchanged; old records have no field.
+- The progress observer (ADR 0040) resolves the owning chat first and then gates both the admission and the settlement notice by `chat.progress ?? settings.progressMessages`. Reply-enabled allowlisting, formatting, screening, receipts and no-replay rules are unchanged.
+- `settings.json` stays the default and is never rewritten by a command; the per-chat choice lives only in Durable.
+
+**Consequences.** A `/verbose off` chat still runs tools and records their results; it only stops seeing the two notice lines. Child notices follow the owning chat's choice. Changing the global default does not touch chats with an explicit choice.

package/docs/adr/0052-host-owned-self-restart.md

@@ -0,0 +1,53 @@
+# 0052. The host owns its own restart
+
+Status: accepted (owner accepted on 2026-10-24)
+
+**Problem.** A chat assistant restarts the service by writing a controller
+script and running it from a `bash` tool call. The host cannot tell that this
+call is about to stop it. When the call is still running at the stop, ADR 0041
+reruns it on the next start, which launches another controller and stops the
+service again (#39: about 70 restarts in eleven minutes). A host-side stop
+heuristic that aborts a tool interrupted twice in a row was tried the same
+day; it limits the damage after the fact, does not remove the cause, and
+aborts any long tool that two deployments happen to interrupt in a row.
+
+**Example.**
+
+```text
+restart_service({ release: "d627232…" })
+-> Restart into /Users/clawbot/pi-imessage-releases/d627232… is scheduled;
+   the service stops after this call settles. Controller directory:
+   /tmp/pi-imessage-restart.Xy12ab. Verify in a later call.
+```
+
+The call settles, the host opens the controller in Terminal, the controller
+stops the old process and becomes the new one. The next turn verifies the
+listener, the log and the running release directory.
+
+**Decision.**
+
+- A built-in `restart_service` tool takes the full commit hash of a prepared
+  release directory, a sibling of the running one. It refuses a hash that is not
+  a directory with `src/cli.ts`, `node_modules` and `ops/restart.command`, and
+  a second request while one is scheduled.
+- The tool writes the private controller directory of ops/README.md step 3
+  itself: `environment.sh` from the process environment, `control.sh` from the
+  process's own PID, start time and command line, and a copy of
+  `ops/restart.command` from the target release. The controller deletes
+  `environment.sh` after sourcing it.
+- The tool returns at once. The host launches the controller only after the
+  tool task has settled, so the stop can never interrupt the call that asked
+  for it.
+- The tool is `replay: "unsafe"`. If it is interrupted anyway, the model gets
+  an interrupted result and checks what is running instead of a rerun
+  launching a second controller.
+- Ordinary tools keep the rerun default of ADR 0041. Operators keep the manual
+  procedure for a cold start when no service is running.
+
+**Consequences.** A self-restart costs one restart and no extra model turn.
+The stop still happens at a tool boundary of the requesting chat, so that chat's
+next model request is repeated after the restart, as ADR 0041 accepts. The
+restart loop of #39 cannot recur through this tool, so the stop heuristic is
+removed and ADR 0041 applies unchanged to every other tool. A chat that writes
+its own controller through `bash` is still subject to the ops rule of ending
+the call right after `open`.

package/docs/adr/README.md

@@ -0,0 +1,54 @@
+# Architecture decision records
+
+Accepted ADR files are never edited; this index records which ones are current.
+"Active" means the decision is in force. A replaced ADR points to its successor.
+
+## Current
+
+| ADR | Decision | Status |
+|---|---|---|
+| [0001](0001-durable-owns-state.md) | Pi Durable owns all chat state | Active |
+| [0002](0002-module-layering.md) | Modules in strict layers | Active |
+| [0003](0003-replies-at-most-once.md) | Replies are sent at most once | Active |
+| [0004](0004-native-extensions.md) | Native Durable extensions, not an SDK adapter | Active; Codex tier clause replaced by 0036 |
+| [0006](0006-jsonl-storage.md) | One JSONL storage, backed up by hand | Active |
+| [0007](0007-images-by-path.md) | Store images as file paths | Active |
+| [0008](0008-compaction-and-run.md) | Six-hour compaction | Active; `/run` clause replaced by 0012 |
+| [0010](0010-test-budget.md) | About 40 tests | Active |
+| [0011](0011-reconcile-unsent-answers.md) | Reconcile unsent answers | Active |
+| [0012](0012-run-in-owned-conversation.md) | `/run` in an owned conversation | Active |
+| [0013](0013-thin-adapters-around-durable.md) | Thin adapters around Durable | Active; scheduler clause replaced by 0042 |
+| [0016](0016-process-http-transport.md) | One process-owned HTTP transport | Active |
+| [0017](0017-browser-cli-owned-scope.md) | Conversation-scoped browser CLI tool | Accepted, to be implemented |
+| [0018](0018-tasks-without-prompt-api.md) | Ordinary `/stop`; no HTTP `/prompt` or `/send` | Active |
+| [0036](0036-workspace-policy-and-neutral-service-id.md) | Workspace policy and neutral service ID | Active |
+| [0040](0040-chat-progress-notices.md) | Chat progress notices | Active; consolidates 0020–0028, 0031 |
+| [0041](0041-restart-and-recovery.md) | Restart and recovery | Active; consolidates 0037–0039; self-restart path added by 0052 |
+| [0042](0042-background-schedules-and-workspace-extensions.md) | Background schedules and workspace extensions | Active; operator-run clause replaced by 0047 |
+| [0043](0043-remove-legacy-migration.md) | Remove the legacy migration code | Active; archived at tag `archive/legacy-migration` |
+| [0044](0044-message-channels.md) | Organize message sources as channels | Proposed |
+| [0045](0045-chat-scheduling-tools.md) | Native chat scheduling tools | Proposed |
+
+| [0046](0046-selective-command-redaction.md) | Selective command-preview redaction | Proposed; owner-requested implementation in #36 |
+| [0047](0047-one-scheduling-path.md) | One scheduling path for recurring and one-off work | Active |
+| [0048](0048-quiet-attachment-reads.md) | Quiet attachment reads | Proposed; owner-requested implementation in #38 |
+| [0049](0049-per-chat-progress-notices.md) | Per-chat progress notices via `/verbose` | Proposed; owner-requested implementation |
+| [0052](0052-host-owned-self-restart.md) | The host owns its own restart (`restart_service`) | Active; owner accepted on 2026-10-24 (#39) |
+
+## Replaced or rejected
+
+| ADR | Decision | Replaced by |
+|---|---|---|
+| [0005](0005-history-migration.md) | Import old history once | 0043 (done) |
+| [0009](0009-one-shot-cutover.md) | Switch over in one step | 0043 (done) |
+| [0014](0014-ephemeral-private-storage.md) | Ephemeral private storage | 0018 |
+| [0015](0015-ordinary-stop-keeps-native-inbox.md) | `/stop` keeps the native inbox | 0018 |
+| [0030](0030-shared-web-read-cache.md) | Shared web read cache | Rejected; removed |
+| [0019](0019-remove-scheduled-services.md) | Remove scheduled services | 0042 |
+| [0020](0020-chat-task-progress.md)–[0028](0028-command-preview-120.md) | Progress notice format | 0040 |
+| [0031](0031-quiet-compaction-progress.md) | Quiet six-hour compaction progress | 0040 |
+| [0032](0032-native-background-schedules.md)–[0035](0035-external-business-task-extensions.md) | Native schedules, operator run, local time, workspace extensions | 0042 |
+| [0037](0037-restart-during-in-flight-work.md)–[0039](0039-rerun-interrupted-tools.md) | Restart and tool rerun | 0041 |
+
+Numbers 0029, 0050 and 0051 are not used: 0050 and 0051 were interim stop
+heuristics for #39 that the owner did not accept; 0052 replaced them.

package/docs/api.md

@@ -0,0 +1,104 @@
+# HTTP API
+
+[Back to README](../README.md)
+
+Default address: `http://localhost:7750` (configured by `WEB_HOST` and `WEB_PORT`).
+The server has no authentication; do not expose it to untrusted networks.
+
+The pages `/`, `/chat`, `/chats`, `/tasks`, `/scheduled`, `/settings`, `/memory` and `/logs` are read-only.
+The Chats tab (`/chats`, `/chats/data`) lists groups and direct chats, one row
+each: reply eligibility, the `/verbose` choice with its effective value, the
+conversation's model and thinking level, and last activity. Chats that do not
+reply are dimmed. It never shows message text. The message history page in the
+navigation is labelled Messages.
+The Tasks tab shows real chat and native schedule ownership trees, including
+subagent child conversations and terminal tasks. Internal-only conversations such as model-health
+are hidden, including when selected by URL; their stored data is not deleted.
+`/tasks/data` retains all conversation records for native diagnostics
+and lightweight task summaries, newest first. It lists every unfinished task,
+every task that owns a conversation, their parent chains and the 20 newest
+tasks per conversation, read with descending scans so the full task history is
+not scanned; a conversation with older tasks is flagged in `more` and shows one
+line. The Scheduled history and the Logs task list use the same descending
+order, so "Older tasks" pages go back in time. Input and payloads
+are fetched only when a task is expanded, through `/tasks/task/data?taskId=ID`.
+`/tasks?conversationId=ID` focuses one conversation and its descendants. The tree
+and expanded tasks update only on manual refresh. Conversation lists and sidebars
+use newest message activity first, with conversation ID as a descending tie-break;
+Tasks uses the same activity clock as Messages, not conversation creation order.
+Conversation windows have a maximum height of `min(560px, 70dvh)` and scroll inside. These are latest task states,
+not checkpoint history: terminal tasks retain input and outcome, but no checkpoint.
+Existing redaction and large-string truncation apply to task details too.
+`/chat/data?conversationId=ID` exposes history/live state; `/events` announces
+committed changes without executing anything. Native history cursors use
+base64url-encoded JSON in `cursor`; long results are paged and large text is
+truncated. HTML, JSON, JavaScript and CSS responses of at least 1 KiB support
+negotiated gzip compression with `Vary: Accept-Encoding`. SSE stays uncompressed
+so notifications are not buffered.
+
+The chat overview embeds at most 15 displayed messages per conversation in its
+initial HTML, ordered by message timestamps (including imported dates). Group
+names are retained even when their source message is outside that window.
+`/chat/data?view=overview` batches the same bounded view for refreshes, without
+system prompts, tool results, image payloads or agent configuration.
+`/chat/data?conversationId=ID&view=display` returns display-only history, chat
+metadata, reply settings and a revision marker without separate index/settings
+requests; detail history and its older-page cursors are not reduced to 15
+messages. Existing `/chat/data` and conversation detail responses without these
+view parameters retain their native state shapes.
+
+Every request reads current state directly; there is no server-side read cache
+(ADR 0030 was rejected).
+
+Pages load once and refresh only through the Refresh button, memory filtering/
+pagination or explicit navigation. There is no browser SSE connection, periodic
+polling or visibility-triggered refresh. Expanded task payloads are still loaded
+on demand. The standalone `/events` API remains compatible for existing clients;
+the web pages do not use it. Cache invalidation still makes manual reads current.
+
+Memory pages use server-side filtering and 20-record pagination. The additive
+`/memory/data?view=records` view accepts `q`, `namespace`, `kind`, `status` and
+`page`; status defaults to `active`, and an empty status selects all records.
+Responses include only the selected page plus counts and filter choices.
+Supersession is resolved across namespaces before filtering. Complete JSONL
+records and long memory text are never character-truncated; invalid source lines
+are counted and reported without modifying source files. The original
+`/memory/data` raw namespace-array shape remains available with complete content.
+Known credential fields/token patterns are redacted, not a guarantee
+that arbitrary user-written secrets can be identified.
+
+The agent sends files and extra messages with its immediate `send_message`
+tool. HTTP `/prompt` and `/send` remain retired. Legacy cron management,
+reminders and PT Automation routes remain removed and return 404 (ADR 0019).
+
+`GET /scheduled` and `GET /scheduled/data` expose configured native background
+jobs (ADR 0032), not the retained legacy cron files. The JSON view contains `jobs`
+with cadence, enabled state, native scheduler task/conversation IDs, phase and
+`nextAt`, and each job's latest ten execution tasks. `recent` contains the latest
+ten executions across all jobs. Results separate native task outcome from the
+message transport receipt (`sent` is not recipient confirmation). These views
+never resume the Harness or invoke a model. POST/DELETE return 404; there are no
+run, pause or resend buttons. Scheduling configuration takes effect at startup.
+Daily slots and learning dates use the service machine's local timezone (or an
+explicit process `TZ`). Each job includes `timezone`; Web deadlines and history
+use it even when the browser is in another timezone. Saved absolute deadlines
+remain unchanged on restart (ADR 0034).
+
+| Endpoint | Description | Example |
+|---|---|---|
+| `GET /health/model` | Make a live request to the configured default AI model; returns HTTP 200 when healthy or 503 on failure | `curl localhost:7750/health/model` |
+
+The model health endpoint can incur model usage. It is not a passive startup
+probe and never sends its answer to an iMessage chat.
+
+Set `progressMessages: true` in `settings.json` to send one short iMessage notice
+for each newly admitted native task/tool in reply-enabled chats, except
+`pi.generation`. Child calls go to their parent chat. Notices use native names
+without IDs, with bounded argument summaries and screened path/search-query
+previews. Raw outputs, commands, prompts and document contents stay local.
+Known credential indicators are redacted; arbitrary user-authored secrets cannot
+be guaranteed detectable. Missing or false keeps final-only delivery. The setting
+is reread for each notice; old tasks and unknown sends are not replayed
+([ADR 0040](adr/0040-chat-progress-notices.md)). `/verbose on|off` in a chat
+overrides this default for that chat only and `/verbose default` removes the
+override ([ADR 0049](adr/0049-per-chat-progress-notices.md)).

package/docs/architecture.md

@@ -0,0 +1,164 @@
+# Architecture
+
+## 1. Packages
+
+```text
+┌────────────────────────────────────────────┐
+│ 1  main.ts · cli.ts                        │
+├────────────────────────────────────────────┤
+│ 2  web/                                    │
+├────────────────────────────────────────────┤
+│ 3  agent/                                  │
+├────────────────────────────────────────────┤
+│ 4  extensions/                             │
+├────────────────────────────────────────────┤
+│ 5  transport/                              │
+├────────────────────────────────────────────┤
+│ 6  config/                                 │
+└────────────────────────────────────────────┘
+         Imports go downward only.
+```
+
+### Notes
+
+These are folders under `src/`, not separate npm packages.
+The root `main.ts` and `cli.ts` files form one host package.
+Lower layer numbers may import higher ones. Different packages in the same layer
+cannot import each other; imports within a package are allowed.
+
+| Layer | Package | Responsibility |
+|---|---|---|
+| 1 | `main.ts`, `cli.ts` | Startup, wiring and installation. |
+| 2 | `web/` | HTTP API; read-only pages for chat history and live state. |
+| 3 | `agent/` | Harness, models, chat mapping, commands, delivery, prompt, `/run`, native background scheduling and maintenance. |
+| 4 | `extensions/` | Built-in native tools and loading of trusted workspace business extensions. |
+| 5 | `transport/` | Poll chat.db, archive attachments, send text and files through Messages.app. No agent logic. |
+| 6 | `config/` | Settings, environment variables and chat allowlist. |
+
+Enforcement: `test/architecture.test.ts`. Rationale: [ADRs](adr/).
+
+Personal tool and task code lives under `WORKING_DIR/extensions/<name>/index.ts` with
+its own `config.json`. Startup and `/reload` scan direct child directories. Native
+CommonJS module factories (`module.exports`) receive the pinned Durable primitives;
+the loader never scans skills or attachments, installs dependencies or adapts SDK
+extensions. Source and configuration reload without interrupting current calls.
+Failed reloads retain old definitions and schedule configuration. Removed task
+code stays in memory for calls that can still admit children; missing required
+code fails explicitly on restart. The assistant's `reload_extensions` tool uses
+the same service owner. See [workspace extensions](workspace-extensions.md),
+ADR 0035 and ADR 0036.
+
+The built-in native `browser` extension wraps the pinned pi-browser CLI with
+host-derived conversation scopes. Browser children get private HOME/cache,
+profile/output and cwd; other coding tools are unchanged. The host owns scoped
+stop/reset/shutdown/restart cleanup, while Durable owns invocation state and
+unsafe replay policy. Read-only contexts do not offer the tool. This is not an
+OS sandbox; see [browser operations and retention](browser.md) and ADR 0017.
+
+
+### Native schedules
+
+`agent/scheduling.ts` registers an extension with native task definitions. A
+job's dedicated conversation owns a background scheduler, whose checkpoint saves
+the next deadline. Each occurrence is a child execution task delegating to an
+extension's native business task; terminal receipts supply Web history, not a
+parallel UI log. The framework owns daily/interval cadence, non-overlap, recovery
+and quiet six-hour native compaction. Workspace tasks own business policy and
+documents, and can commit their state and the generic outgoing item atomically.
+The host delivery poll uses existing direct-send receipts and passive chat records.
+`web/schedules.ts` projects these native records, including latest-ten history.
+Daily slots and learning dates use the service machine's local timezone; the Web
+view uses the same timezone. Saved absolute deadlines survive restart. See
+[ADR 0032](adr/0032-native-background-schedules.md) and
+[ADR 0034](adr/0034-machine-local-schedule-time.md).
+
+## 2. Workflow
+
+### Overall flow
+
+```text
+User (iMessage / SMS)
+        |
+        v
+transport/watch.ts
+  Poll chat.db, filter, save attachments
+        |
+        v
+agent/chats.ts
+  Find conversation; submit with GUID as requestId
+  Save row cursor after acceptance; steer if busy
+        |
+        v
+Pi Durable Harness <--------> durable/ (JSONL)
+        |                          |
+        | final answer             +--> web/ (history and live state)
+        v
+agent/deliver.ts
+  Record sending -> transport/send.ts -> record sent
+                           |
+                           v
+                      Messages.app -> User
+```
+
+### Inside the Harness
+
+These concepts and files are native to Pi Durable's JSONL storage.
+Paths are relative to `WORKING_DIR/durable/`.
+
+| Member | Role | File |
+|---|---|---|
+| Conversation | Conversation scope linking history and tasks. | `main.jsonl` |
+| Generation | Requests the model, waits for tools and advances one model turn. | Active: `task-<id>.jsonl`; terminal: `main.jsonl` |
+| Entry | Immutable history record: user input, model response or tool result. | `main.jsonl` |
+| `pi.live` | Current run state, partial model response and running tool output. | `doc-<id>.jsonl` |
+| `pi.inbox` | Queued submissions received while the conversation is busy. | `doc-<id>.jsonl` |
+
+Example: "Show the current directory.", then a `steer` while the tool runs.
+Based on a verified Durable 1.0.2 run; test timing details are omitted.
+The second Generation is not shown. File mappings are in the table above.
+
+```text
+Conversation / Tasks                                                      Model                 Tool
+|                                                                           |                     |
+| Conversation 1 (main.jsonl) - create                                      |                     |
+|                                                                           |                     |
+|   Generation task (task-9.jsonl)                                          |                     |
+|     ▶ phase=prepare; state=pending                                        |                     |
+|       pi.live - run.taskId=9, inputs=[8]                                  |                     |
+|       Prepare request; Entry 10 (main.jsonl) - pi.system                  |                     |
+|     ▶ phase=request; state=running                                        |                     |
+|       pi.live - generation.attempt=1                                      |                     |
+|       ------------------ request with committed context ------------------>                     |
+|       <------------------ complete response: bash call -------------------|                     |
+|       Entry 11 (main.jsonl) - pi.assistant, byTaskId=9                    |                     |
+|       pi.usage - update model usage                                       |                     |
+|     ▶ phase=tools; state=waiting, on=[12]                                 |                     |
+|       pi.live - clear partial; tool 12 pending                            |                     |
+|                                                                           |                     |
+|     Tool Task T12 (task-12.jsonl), owner=9                                |                     |
+|       ▶ phase=call; state=pending                                         |                     |
+|         Resolve tool; validate arguments                                  |                     |
+|       ▶ phase=execute; state=running                                      |                     |
+|         Save arguments + replay=safe; pi.live tool running                |                     |
+|         -------------------------------- execute command="pwd" --------------------------------->
+|         <----------------------------- result: current directory -------------------------------|
+|         Entry 14 (main.jsonl) - pi.tool-result, byTaskId=12               |                     |
+|                                                                           |                     |
+|       ▶ T12 (main.jsonl): state=terminal, outcome=completed               |                     |
+|         pi.live - tool done, entry=14; clear output                       |                     |
+|                                                                           |                     |
+|     ▶ phase=tools (reused); state=running                                 |                     |
+|       Place steer: Entry 15 (main.jsonl) - pi.user, byTaskId=9            |                     |
+|       Submission 13 (main.jsonl) - status=placed                          |                     |
+|       pi.inbox - remove item 13                                           |                     |
+|                                                                           |                     |
+|     ▶ G9 (main.jsonl): state=terminal, outcome=completed                  |                     |
+|       pi.live - remove tools; run.taskId=16                               |                     |
+|                                                                           |                     |
+| Next generation continues the run; final settlement is not shown.         |                     |
+|                                                                           |                     |
+```
+
+Upstream reference: [Watching a Conversation](https://github.com/earendil-works/pi/blob/main/packages/durable/README.md#watching-a-conversation)
+and [Busy Conversations](https://github.com/earendil-works/pi/blob/main/packages/durable/README.md#busy-conversations).
+Upstream `main` is experimental; the examples here describe the pinned version.