@kingcrab/pi-imessage 0.0.43 → 1.0.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/README.md

@@ -0,0 +1,50 @@
+# 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 |
+| [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 |
+
+## 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 |
+
+Number 0029 was never used.

package/docs/api.md

@@ -0,0 +1,92 @@
+# 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`, `/tasks`, `/scheduled`, `/settings`, `/memory` and `/logs` are read-only.
+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, reading every native scan page. 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 Recent Chats, 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 0020](adr/0020-chat-task-progress.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.

package/docs/browser.md

@@ -0,0 +1,93 @@
+# Conversation-owned browser
+
+The host's built-in native Durable `browser` extension implements ADR 0017. It is
+registered with the other built-in tools, not loaded as a personal workspace
+business extension. It invokes the installed `PI_CODING_AGENT_DIR/bin/pi-browser`
+wrapper and its pinned Playwright CLI by argv; there is no SDK shim, private CLI
+import or second browser driver.
+
+## Operations
+
+`browser` takes `action` and only the arguments needed by that action:
+
+- `open`, `goto`, `tab-new`: optional `url` (`goto` requires one), HTTP(S) without credentials.
+- `snapshot`, `screenshot`: optional `ref` from the latest snapshot.
+- `click`, `hover`, `check`, `uncheck`: required `ref`.
+- `fill`, `select`: required `ref` and `text`.
+- `press`: required `key`.
+- `tab-select`: required `tab`; `tab-close` accepts an optional index.
+- `go-back`, `go-forward`, `tab-list`, `close`: no further arguments.
+
+Open before interacting. A snapshot includes bounded accessibility text with
+current refs. Screenshot/other artifact links resolve from the reported private
+cwd; the result also gives the absolute output directory. Page output is
+untrusted. No attachment, discovery, headed overrides, global cleanup, arbitrary
+profile/config/filename, storage export/import or arbitrary code execution is
+exposed to the model. Positional text follows `--`, so strings resembling flags
+remain literal. Native health checks and read-only subagents do not offer the tool.
+
+## Isolation and retention
+
+Scope is derived from the canonical Durable storage directory and native
+conversation ID, never a model-selected session. Ordinary chats, run conversations
+and other tool-enabled native conversations receive distinct scope directories:
+
+```text
+WORKING_DIR/browser/<sha256-of-canonical-storage>/<conversation-id>/
+  owner.json
+  home/                    # private HOME/cache/CLI daemon registry
+  cwd/.playwright/         # private workspace identity and managed headless config
+  state/profiles/owned/    # dedicated non-personal persistent Chrome profile
+  state/output/            # snapshots/screenshots
+  state/auth.json          # private last completed storage-state checkpoint
+```
+
+Browser child processes alone get the private HOME/cwd and a small environment
+allowlist. Browser target/config/test environment overrides are not inherited.
+Ordinary bash/read keep their original environment. Scope directories are 0700;
+authentication checkpoints are 0600, not returned to the model. Public scoped
+`state-save`/`state-load` preserve cookie/local-storage login state across browser
+restarts alongside the retained profile. Restore before navigating the supplied
+URL, not by repeating the navigation. Before orderly close/reopen, a host-only
+public scoped session query checks the owned profile and refreshes its checkpoint,
+including asynchronous token changes since the last command. Checkpoints publish
+by atomic rename, so an interrupted save cannot truncate the last completed state. On recovery a live
+owned daemon is checkpointed before cleanup; if it already died, only the last
+completed checkpoint is available and may require renewed login. Profiles,
+checkpoints and outputs are not automatically deleted. Real-site login expiration
+and IndexedDB-based workflows are not guaranteed by the synthetic fixture.
+
+Operations serialize per conversation, while other conversations remain
+independent. `/stop` and `/new` close the chat's owned browsers, including run/task
+child scopes, after aborting current work and before admitting the next boundary.
+Host shutdown stops native work, closes owned sessions, then releases the native
+owner lock. Startup closes saved owned sessions after acquiring that lock, before
+resuming work.
+Only matching ownership markers and scoped `close` are used; malformed ownership
+or a cleanup failure is an explicit error, never grounds for global killing or
+silent profile deletion.
+
+The tool declares `replay: "unsafe"` even though the host otherwise defaults tools
+to safe. A click/press can already have submitted something when its caller is
+interrupted. Cancellation/timeout does not prove the effect was undone; do not
+blindly retry. Browser calls have request-bound deadlines and await CLI child exit
+on cancellation. SIGTERM gets a short grace period, then only that exact owned CLI
+child is terminated; this is never a global Chrome/service kill. Raw subprocess
+argv/errors (which can contain form contents) are not surfaced, and snapshots are
+read with a byte limit.
+
+This is a tool boundary, **not an OS sandbox**. Unrestricted coding tools can
+still access host files or invoke another browser process. Stronger containment
+requires a separate decision. Never copy a personal Chrome profile, bypass a
+CAPTCHA/2FA or perform an unapproved irreversible action.
+
+## Verification
+
+- `test/browser.test.ts` uses a faux model and fake CLI boundary to check native
+  registration, forced arguments/environment, forbidden controls, literal flag-like
+  form text, owned stop/reset/restart, retention, cancellation and unsafe replay.
+- `node --experimental-strip-types ops/browser-smoke.mjs` uses the real installed
+  CLI and headless Chrome with temporary profiles and loopback pages. It checks
+  same-name sessions, daemon discovery, cookies/local storage, tabs/output files,
+  literal arguments, selective cleanup and preserved login checkpoints on reopen.
+  It never opens a personal profile, calls a paid model or sends an iMessage.

package/docs/memory.md

@@ -0,0 +1,27 @@
+# Structured Memory
+
+[Back to README](../README.md)
+
+Durable memories are stored as namespaced JSONL records under
+`WORKING_DIR/skills/file-memory/namespaces/`. Each record includes a stable ID,
+creation timestamp, factual event date when known, source, kind, subjects,
+importance, confidence, and status. This keeps every memory traceable without
+inventing dates for older facts.
+
+The agent uses typed tools to load complete namespaces, search for specific
+records, and append validated memories. Corrections append a new record that
+supersedes the old ID, preserving an auditable history instead of silently
+rewriting it. Legacy global and per-chat `MEMORY.md` files remain read-only
+archives.
+
+The service calls the store's existing `memory_cli.py` in that directory using
+Python 3 and argument arrays, not a shell or an embedded backend. The CLI is a
+runtime prerequisite; missing or failed calls return tool errors. Tool
+cancellation terminates the subprocess, but an already completed write is not
+undone. Saves are replay-safe because the store assigns deterministic IDs and
+skips identical records; corrections pass the existing `supersedes` option.
+
+Core memory (`core.md`) and the namespace list are loaded at startup and refreshed
+by `/reload`. `load_memory` and `search_memory` always read the current store.
+Explicit extension selection can replace the service's default memory tools for
+isolated callers or restricted execution.