@tt-a1i/openpi 0.1.0

package/SETUP.md

@@ -0,0 +1,74 @@
+# Setup
+
+Use Node.js 22.19.0 or newer. Install the public Pi package:
+
+```sh
+pi install npm:@tt-a1i/openpi
+```
+
+To inspect the current source before loading it, install directly from GitHub instead:
+
+```sh
+pi install git:github.com/tt-a1i/my-pi-setup
+```
+
+Pi installs the package dependencies automatically. Restart Pi or run `/reload` after installation.
+
+## fd and rg tools
+
+The `file-search` extension registers `fd` and `rg` as model tools. No setup is normally needed: at startup it silently uses a system-installed `fd` (or `fdfind` on Debian/Ubuntu) and `rg` when available, or an existing fallback binary in `~/.pi/agent/bin/`. Only when neither exists does it download an official release binary (macOS/Linux, arm64/x64, over HTTPS) into `~/.pi/agent/bin/` and show a one-time notification. If your platform is unsupported, install `fd` and `rg` with your package manager and restart pi.
+
+## Theme
+
+Add the included theme to `~/.pi/agent/settings.json` while keeping your existing settings:
+
+```json
+{
+  "theme": "github-dark-default"
+}
+```
+
+Pi will load the extensions, skills, and theme from their directories the next time it starts.
+
+## Configure this package
+
+Use the single package-owned command. With no arguments, the current model explains the configurable areas and their impact, then uses `ask_user`: first run initializes them; later runs explain the saved state and ask whether to keep it, change one area, or review everything. With arguments, it treats the rest as a targeted natural-language request:
+
+```text
+/my-pi-setup
+/my-pi-setup 开启下一步预测，使用 seal/deepseek-v4-flash，关闭推理
+/my-pi-setup 关闭下一步预测
+/my-pi-setup workflow 同时跑 16 个 agent，总任务最多 256 个
+/my-pi-setup 显示大标题
+/my-pi-setup 切换 Footer 为 powerline
+/my-pi-setup 用 mono powerline Footer
+/my-pi-setup Footer 用 compact
+/my-pi-setup Footer 两行：cwd flex model / context cost flex git
+/my-pi-setup Footer 只显示 model、thinking、context、cache 和 git
+/my-pi-setup 关闭自定义状态栏
+/my-pi-setup 编辑后自动跑 npm run format
+/my-pi-setup 关闭 post-edit 命令
+/my-pi-setup 给 explorer 指定当前 Registry 中可用的模型
+/my-pi-setup 清除 explorer 的模型，让它继承父模型
+```
+
+Next-action suggestions default to off. Run `/my-pi-setup` to explicitly choose an available model and reasoning level. After a fully settled main-agent run, one suggestion may appear as dim inline text on the first row of an empty editor; reserved cells at the row end keep CJK IME preedit from overwriting it. `Right` accepts it into the editor without submitting, while any other editor input dismisses it. Suggestions are ephemeral and never enter session history or model context. Workflows default to 8 concurrent agents and 128 total agent calls per run; configurable hard maxima are 64 and 1024. The large decorative header defaults off and the custom dashboard footer defaults on with a one-line Powerline layout (`cwd model thinking context cache cost throughput |flex| git pr`). Footer presets are `powerline`, `powerline-mono`, and `compact`; style can also be set independently to `plain`, `powerline`, or `powerline-mono`. Custom layouts use a 2D `footerLines` array with at most one `flex` per row for left/right alignment. Nerd Font only affects powerline separator glyphs (``); metric text stays readable without it. Footer changes apply immediately in the active TUI session. Subagent results default to the existing full display; users who do not usually inspect implementation detail can select compact previews. Bash defaults to a folded one-line command with bounded output and a hidden-line count. Write/Edit defaults to an extra-short folded preview capped at three rendered lines including the operation header; its hidden-line hint remains inside the operation's status background. Select full independently for any category to keep it expanded. Compact views temporarily expand with `app.tools.expand` (`Ctrl+O` by default). An optional post-edit command is off by default: set one (for example `npm run format`, maximum 500 characters) and it runs once in the background after each interactive-TUI turn with successful Write/Edit operations, with failures reported as a notification. It deliberately does not guess whether arbitrary Bash commands changed files. Built-in Agent roles `explorer`, `implementer`, `reviewer`, and `advisor` are shared by `subagent_spawn.agent_type` and Workflow `agent(..., { agent_type })`; all inherit the parent model by default. `/my-pi-setup` may assign a currently available Registry model to any subset; clearing one returns it to inheritance and omitted roles stay unchanged. Model precedence is explicit call > selected role-file model > setup assignment > parent inheritance; effort is explicit call > selected role > parent. A trusted project `.pi/agents/<role>.md` overrides global `~/.pi/agent/agents/<role>.md`, which overrides the complete built-in role definition; overrides are diagnosed. Role-model changes apply to the next spawn or Workflow agent call without reload. Configuration is stored privately at `~/.pi/agent/my-pi-setup.json`.
+
+## Session Goal and Tasks
+
+`/goal`, `/goal <objective>`, `/goal edit`, `/goal pause`, `/goal resume`, and `/goal clear` implement a branch-scoped persistent objective with the current OpenAI Codex Goal semantics. `/goal <objective>` starts immediately with no second success-condition prompt or admission judge; the objective can contain up to 4000 characters. `/goal` shows status, objective, elapsed time, consumed tokens, optional token budget, and status-specific command hints. Replacing unfinished work requires `Replace current goal` confirmation, while a complete goal is replaced silently. Editing preserves usage and the optional budget; it reactivates complete or budget-limited goals only when the preserved budget is not already exhausted.
+
+Model callers use `get_goal`, `create_goal`, and `update_goal`. `create_goal` is only for an explicitly requested persistent autonomous goal and fails while an unfinished goal exists. `update_goal` can only mark `complete` after a strict requirement-by-requirement evidence audit, or `blocked` after the same genuine blocker repeats for at least three consecutive Goal Turns. User/system operations own pause, resume, clear, usage limits, and budget limits.
+
+There are no normal user-facing Turn, no-progress, or wall-clock caps; a hidden 1000-continuation circuit breaker exists only to stop runaway automation. An optional `token_budget` must only be positive. Goal non-cached Assistant input-plus-output Token and elapsed-time usage are persisted; crossing the budget marks `budget_limited` and queues one wrap-up Turn. Active goals continue after reload/resume. Fork and tree navigation defer inherited active continuation until the first explicit user input; paused, blocked, and usage-limited goals remain stopped and can prompt for Resume. A v1 active/waiting goal migrates once to paused. Assistant aborts pause an active goal and Assistant errors block it. Print/json automation is inert. Footer text mirrors Codex (`Pursuing goal (…)`, resume hints, `Goal unmet`, `Goal achieved`) without showing the objective or legacy Turn counts. An achieved Footer remains visible until the next explicit interactive/RPC input, then a branch-persisted acknowledgement hides only the Footer while `/goal` retains the completed record.
+
+Session Tasks remain advisory multi-item work intent and do not determine Goal completion. They are scoped to the current request batch: once every item is done or dropped, the batch closes and the next `tasks_add` starts again at T1. Active items persist in a polished Claude Code-style panel above the editor; `Ctrl+Shift+T` or `/tasks hide|show|toggle` controls visibility, while `/tasks` opens the full list. No `/my-pi-setup` setting or secondary judge model is required.
+
+## Other commands added by this fork
+
+- `/sessions` searches and previews project sessions before switching.
+- `/tasks` inspects branch-scoped advisory work items.
+- `/goal ...` controls the persistent autonomous session objective.
+- `/context-pivot <next phase>` deliberately compacts a long current session into a next-phase brief. It requires at least 30,000 context tokens and is rejected below that; use the separate `/handoff` skill when work should move to a genuinely new session.
+- `/cron every <5m> <prompt>`, `/cron in <30s> <prompt>`, `/cron list`, and `/cron remove <id>` schedule a prompt for this session. Jobs are in-memory and session-scoped (cleared on shutdown), fire only while the session is idle, and use a duration grammar (`30s`/`5m`/`2h`, minimum 30s) rather than crontab fields, because the scheduler polls about every 30 seconds.
+- `/plan [objective]` explores read-only before changing anything: while armed it blocks `edit`, `write`, mutating Bash, `subagent_send`, `workflow`, and `bg_start`, while read/grep/find/ls/fd/rg and verified read-only Git/GitHub commands stay available. It permits `subagent_spawn`, but the harness narrows every newly spawned planning child to investigation-only tools; agent types can narrow that list further, never widen it. The model must submit the complete plan through parent-only `plan_ready`; the write gate stays closed until `/plan` prepares an editable implementation prompt for the current or a fresh Session. `/plan off` cancels.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,16 @@
+# Third-Party Notices
+
+## Sessions extension
+
+`extensions/sessions/` is adapted from
+[`jayshah5696/pi-agent-extensions`](https://github.com/jayshah5696/pi-agent-extensions),
+version 0.5.2.
+
+The upstream project is distributed under the MIT License. Its notice states
+`Copyright (c) 2026`; the complete license text is included at
+[`extensions/sessions/LICENSE.upstream`](extensions/sessions/LICENSE.upstream).
+
+The remainder of this repository retains its upstream licensing status; no
+project-wide license is asserted here. The npm package therefore declares
+`UNLICENSED`; publication does not grant permission to copy, modify, or
+redistribute code beyond rights supplied by an applicable upstream license.

package/assets/readme-hero-mobile.svg

@@ -0,0 +1,72 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="720" height="900" viewBox="0 0 720 900" role="img" aria-labelledby="title desc">
+  <title id="title">OpenPI</title>
+  <desc id="desc">A mobile-readable overview of the Pi-native multi-agent runtime.</desc>
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop stop-color="#0d1117"/>
+      <stop offset="1" stop-color="#111827"/>
+    </linearGradient>
+    <pattern id="grid" width="48" height="48" patternUnits="userSpaceOnUse">
+      <path d="M48 0H0V48" fill="none" stroke="#30363d" opacity="0.3"/>
+    </pattern>
+  </defs>
+
+  <rect width="720" height="900" rx="28" fill="url(#bg)"/>
+  <rect width="720" height="900" rx="28" fill="url(#grid)"/>
+  <rect x="1" y="1" width="718" height="898" rx="27" fill="none" stroke="#30363d" stroke-width="2"/>
+
+  <g transform="translate(48 48)">
+    <rect width="146" height="42" rx="21" fill="#12233d" stroke="#2f81f7" stroke-width="2"/>
+    <circle cx="22" cy="21" r="7" fill="#3fb950"/>
+    <text x="42" y="28" fill="#a5d6ff" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="18" font-weight="700" letter-spacing="1">PI NATIVE</text>
+
+    <text x="0" y="122" fill="#f0f6fc" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="66" font-weight="760" letter-spacing="-2">OpenPI</text>
+    <text x="0" y="168" fill="#8b949e" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="24">Small harness. Real runtime.</text>
+  </g>
+
+  <g transform="translate(48 250)" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="23" font-weight="600">
+    <rect width="624" height="68" rx="14" fill="#0d1117" stroke="#238636"/>
+    <circle cx="28" cy="34" r="7" fill="#3fb950"/>
+    <text x="52" y="42" fill="#d1f7d6">background execution</text>
+
+    <rect y="82" width="624" height="68" rx="14" fill="#0d1117" stroke="#1f6feb"/>
+    <circle cx="28" cy="116" r="7" fill="#58a6ff"/>
+    <text x="52" y="124" fill="#cae8ff">isolated Pi subagents</text>
+
+    <rect y="164" width="624" height="68" rx="14" fill="#0d1117" stroke="#8957e5"/>
+    <circle cx="28" cy="198" r="7" fill="#bc8cff"/>
+    <text x="52" y="206" fill="#eadcff">dynamic workflows</text>
+
+    <rect y="246" width="624" height="68" rx="14" fill="#0d1117" stroke="#238b8f"/>
+    <circle cx="28" cy="280" r="7" fill="#39c5cf"/>
+    <text x="52" y="288" fill="#c7f5f7">clean, observable context</text>
+  </g>
+
+  <g transform="translate(48 610)" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">
+    <rect width="624" height="226" rx="18" fill="#010409" stroke="#30363d" stroke-width="2"/>
+    <rect x="1" y="1" width="622" height="46" rx="17" fill="#161b22"/>
+    <circle cx="23" cy="23" r="6" fill="#f85149"/>
+    <circle cx="44" cy="23" r="6" fill="#d29922"/>
+    <circle cx="65" cy="23" r="6" fill="#3fb950"/>
+    <text x="312" y="30" text-anchor="middle" fill="#8b949e" font-size="18">pi · main</text>
+
+    <rect x="24" y="66" width="576" height="48" rx="10" fill="#0d1117" stroke="#30363d"/>
+    <circle cx="46" cy="90" r="6" fill="#58a6ff"/>
+    <text x="64" y="98" fill="#f0f6fc" font-size="22" font-weight="700">main agent</text>
+    <text x="450" y="97" fill="#8b949e" font-size="18">orchestrating</text>
+
+    <g transform="translate(24 130)" font-size="18" font-weight="700">
+      <rect width="176" height="48" rx="9" fill="#0d1117" stroke="#238636"/>
+      <text x="20" y="31" fill="#7ee787">terminal</text>
+      <rect x="200" width="176" height="48" rx="9" fill="#0d1117" stroke="#1f6feb"/>
+      <text x="220" y="31" fill="#79c0ff">subagent</text>
+      <rect x="400" width="176" height="48" rx="9" fill="#0d1117" stroke="#8957e5"/>
+      <text x="420" y="31" fill="#d2a8ff">workflow</text>
+    </g>
+
+    <rect x="24" y="190" width="576" height="20" rx="5" fill="#0b1720"/>
+    <text x="36" y="206" fill="#39c5cf" font-size="16">next: run tests and open the PR</text>
+  </g>
+
+  <text x="360" y="872" text-anchor="middle" fill="#7d8590" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="18" font-weight="600">PI-NATIVE · MODEL-NEUTRAL · FAIL-CLOSED</text>
+</svg>

package/assets/readme-hero.svg

@@ -0,0 +1,118 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="500" viewBox="0 0 1200 500" role="img" aria-labelledby="title desc">
+  <title id="title">OpenPI</title>
+  <desc id="desc">A Pi-native runtime layer for background terminals, isolated subagents, dynamic workflows, and clean context.</desc>
+
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#0d1117"/>
+      <stop offset="0.55" stop-color="#0b1119"/>
+      <stop offset="1" stop-color="#111827"/>
+    </linearGradient>
+    <radialGradient id="blueGlow" cx="0" cy="0" r="1" gradientTransform="translate(820 150) rotate(115) scale(380 520)">
+      <stop stop-color="#1f6feb" stop-opacity="0.22"/>
+      <stop offset="1" stop-color="#1f6feb" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="violetGlow" cx="0" cy="0" r="1" gradientTransform="translate(250 480) rotate(-35) scale(420 310)">
+      <stop stop-color="#8957e5" stop-opacity="0.16"/>
+      <stop offset="1" stop-color="#8957e5" stop-opacity="0"/>
+    </radialGradient>
+    <pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
+      <path d="M40 0H0V40" fill="none" stroke="#30363d" stroke-width="1" opacity="0.33"/>
+    </pattern>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="150%">
+      <feDropShadow dx="0" dy="16" stdDeviation="18" flood-color="#000" flood-opacity="0.42"/>
+    </filter>
+  </defs>
+
+  <rect width="1200" height="500" rx="28" fill="url(#bg)"/>
+  <rect width="1200" height="500" rx="28" fill="url(#blueGlow)"/>
+  <rect width="1200" height="500" rx="28" fill="url(#violetGlow)"/>
+  <rect width="1200" height="500" rx="28" fill="url(#grid)"/>
+  <rect x="1" y="1" width="1198" height="498" rx="27" fill="none" stroke="#30363d" stroke-width="2"/>
+
+  <g transform="translate(70 68)">
+    <g>
+      <rect width="112" height="34" rx="17" fill="#12233d" stroke="#2f81f7"/>
+      <circle cx="18" cy="17" r="5" fill="#3fb950"/>
+      <text x="33" y="22" fill="#a5d6ff" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="13" font-weight="700" letter-spacing="1">PI NATIVE</text>
+    </g>
+
+    <text x="0" y="112" fill="#f0f6fc" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="64" font-weight="760" letter-spacing="-2">OpenPI</text>
+    <text x="0" y="155" fill="#8b949e" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="21">Keep the harness small. Give it a real runtime.</text>
+
+    <g transform="translate(0 198)" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16">
+      <path d="M5 9h14M12 2l7 7-7 7" fill="none" stroke="#58a6ff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+      <text x="32" y="14" fill="#c9d1d9">background execution</text>
+
+      <path d="M5 52h14M12 45l7 7-7 7" fill="none" stroke="#3fb950" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+      <text x="32" y="57" fill="#c9d1d9">isolated Pi subagents</text>
+
+      <path d="M5 95h14M12 88l7 7-7 7" fill="none" stroke="#bc8cff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+      <text x="32" y="100" fill="#c9d1d9">dynamic, replay-safe workflows</text>
+
+      <path d="M5 138h14M12 131l7 7-7 7" fill="none" stroke="#39c5cf" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+      <text x="32" y="143" fill="#c9d1d9">clean context + observable state</text>
+    </g>
+  </g>
+
+  <g transform="translate(675 58)" filter="url(#shadow)">
+    <rect width="458" height="350" rx="18" fill="#010409" stroke="#30363d" stroke-width="2"/>
+    <rect x="1" y="1" width="456" height="43" rx="17" fill="#161b22"/>
+    <path d="M1 43H457" stroke="#30363d"/>
+    <circle cx="22" cy="22" r="5" fill="#f85149"/>
+    <circle cx="40" cy="22" r="5" fill="#d29922"/>
+    <circle cx="58" cy="22" r="5" fill="#3fb950"/>
+    <text x="229" y="27" text-anchor="middle" fill="#7d8590" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="13">pi · main</text>
+
+    <g font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="14">
+      <text x="24" y="78" fill="#7d8590">$ pi</text>
+      <rect x="24" y="92" width="410" height="44" rx="9" fill="#0d1117" stroke="#21262d"/>
+      <circle cx="44" cy="114" r="5" fill="#58a6ff"/>
+      <text x="59" y="119" fill="#f0f6fc">main agent</text>
+      <text x="320" y="119" fill="#7d8590">orchestrating</text>
+
+      <path d="M47 136V155M47 155H379" fill="none" stroke="#30363d" stroke-width="2"/>
+      <path d="M90 155V169M229 155V169M379 155V169" stroke="#30363d" stroke-width="2"/>
+
+      <rect x="24" y="169" width="126" height="68" rx="10" fill="#0d1117" stroke="#238636"/>
+      <circle cx="42" cy="190" r="4" fill="#3fb950"/>
+      <text x="54" y="195" fill="#7ee787">terminal</text>
+      <text x="38" y="219" fill="#8b949e">dev server</text>
+
+      <rect x="166" y="169" width="126" height="68" rx="10" fill="#0d1117" stroke="#1f6feb"/>
+      <circle cx="184" cy="190" r="4" fill="#58a6ff"/>
+      <text x="196" y="195" fill="#79c0ff">subagent</text>
+      <text x="180" y="219" fill="#8b949e">audit auth</text>
+
+      <rect x="308" y="169" width="126" height="68" rx="10" fill="#0d1117" stroke="#8957e5"/>
+      <circle cx="326" cy="190" r="4" fill="#bc8cff"/>
+      <text x="338" y="195" fill="#d2a8ff">workflow</text>
+      <text x="322" y="219" fill="#8b949e">scan → verify</text>
+
+      <rect x="24" y="256" width="410" height="34" rx="8" fill="#0d1117" stroke="#21262d"/>
+      <text x="38" y="278" fill="#7d8590">context</text>
+      <rect x="104" y="268" width="166" height="10" rx="5" fill="#21262d"/>
+      <rect x="104" y="268" width="61" height="10" rx="5" fill="#2f81f7"/>
+      <text x="285" y="278" fill="#c9d1d9">37%</text>
+      <text x="338" y="278" fill="#3fb950">settled</text>
+
+      <path d="M24 308H434" stroke="#21262d"/>
+      <rect x="24" y="318" width="410" height="18" rx="4" fill="#0b1720"/>
+      <text x="34" y="332" fill="#39c5cf" font-size="13">run tests and open the PR</text>
+    </g>
+  </g>
+
+  <g transform="translate(70 444)" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="13" font-weight="600" letter-spacing="0.4">
+    <text fill="#58a6ff">BACKGROUND</text>
+    <circle cx="110" cy="-4" r="2" fill="#30363d"/>
+    <text x="126" fill="#3fb950">SUBAGENTS</text>
+    <circle cx="230" cy="-4" r="2" fill="#30363d"/>
+    <text x="246" fill="#bc8cff">WORKFLOWS</text>
+    <circle cx="352" cy="-4" r="2" fill="#30363d"/>
+    <text x="368" fill="#39c5cf">CONTEXT</text>
+    <circle cx="449" cy="-4" r="2" fill="#30363d"/>
+    <text x="465" fill="#d29922">OBSERVABILITY</text>
+    <circle cx="598" cy="-4" r="2" fill="#30363d"/>
+    <text x="614" fill="#f0f6fc">FAIL-CLOSED</text>
+  </g>
+</svg>

package/assets/readme-runtime-mobile.svg

@@ -0,0 +1,91 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="720" height="1100" viewBox="0 0 720 1100" role="img" aria-labelledby="title desc">
+  <title id="title">OpenPI runtime model</title>
+  <desc id="desc">A mobile-readable diagram of parent control, execution paths, continuity, and observability.</desc>
+  <defs>
+    <linearGradient id="panel" x1="0" y1="0" x2="1" y2="1">
+      <stop stop-color="#161b22"/>
+      <stop offset="1" stop-color="#0d1117"/>
+    </linearGradient>
+    <marker id="arrow" markerWidth="9" markerHeight="9" refX="8" refY="4.5" orient="auto">
+      <path d="M0 0L9 4.5 0 9Z" fill="#484f58"/>
+    </marker>
+  </defs>
+
+  <rect width="720" height="1100" rx="28" fill="#0d1117"/>
+  <rect x="1" y="1" width="718" height="1098" rx="27" fill="none" stroke="#30363d" stroke-width="2"/>
+
+  <g font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif">
+    <text x="40" y="58" fill="#f0f6fc" font-size="32" font-weight="750">One parent. Three paths.</text>
+    <text x="40" y="91" fill="#8b949e" font-size="21">One observable lifecycle.</text>
+  </g>
+
+  <g transform="translate(40 126)" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">
+    <rect width="640" height="112" rx="16" fill="url(#panel)" stroke="#58a6ff" stroke-width="2"/>
+    <rect x="20" y="18" width="104" height="30" rx="15" fill="#12233d"/>
+    <text x="38" y="39" fill="#79c0ff" font-size="16" font-weight="700">PARENT</text>
+    <text x="20" y="82" fill="#f0f6fc" font-size="26" font-weight="700">Main Pi Session</text>
+    <text x="382" y="80" fill="#8b949e" font-size="19">plan · decide · synthesize</text>
+
+    <path d="M320 112V154" stroke="#484f58" stroke-width="2" marker-end="url(#arrow)"/>
+
+    <g transform="translate(0 176)">
+      <rect width="640" height="258" rx="16" fill="#090d12" stroke="#30363d"/>
+      <text x="22" y="34" fill="#8b949e" font-size="18" font-weight="700" letter-spacing="1">EXECUTION</text>
+
+      <rect x="22" y="56" width="596" height="54" rx="11" fill="#0d1117" stroke="#238636"/>
+      <circle cx="47" cy="83" r="7" fill="#3fb950"/>
+      <text x="68" y="91" fill="#7ee787" font-size="22" font-weight="700">Background terminal</text>
+
+      <rect x="22" y="124" width="596" height="54" rx="11" fill="#0d1117" stroke="#1f6feb"/>
+      <circle cx="47" cy="151" r="7" fill="#58a6ff"/>
+      <text x="68" y="159" fill="#79c0ff" font-size="22" font-weight="700">Pi subagent</text>
+
+      <rect x="22" y="192" width="596" height="54" rx="11" fill="#0d1117" stroke="#8957e5"/>
+      <circle cx="47" cy="219" r="7" fill="#bc8cff"/>
+      <text x="68" y="227" fill="#d2a8ff" font-size="22" font-weight="700">Dynamic workflow</text>
+    </g>
+
+    <path d="M320 434V474" stroke="#484f58" stroke-width="2" marker-end="url(#arrow)"/>
+
+    <g transform="translate(0 496)">
+      <rect width="640" height="164" rx="16" fill="url(#panel)" stroke="#30363d"/>
+      <text x="22" y="34" fill="#8b949e" font-size="18" font-weight="700" letter-spacing="1">CONTINUITY</text>
+
+      <g transform="translate(22 54)" font-size="20" font-weight="700">
+        <rect width="136" height="44" rx="9" fill="#0d1117" stroke="#30363d"/>
+        <text x="18" y="29" fill="#f0f6fc">Tasks</text>
+        <rect x="150" width="136" height="44" rx="9" fill="#0d1117" stroke="#30363d"/>
+        <text x="168" y="29" fill="#f0f6fc">Goal</text>
+        <rect x="300" width="158" height="44" rx="9" fill="#0d1117" stroke="#30363d"/>
+        <text x="310" y="29" fill="#f0f6fc" font-size="18">Context Pivot</text>
+        <rect x="472" width="124" height="44" rx="9" fill="#0d1117" stroke="#30363d"/>
+        <text x="490" y="29" fill="#f0f6fc">Sessions</text>
+      </g>
+      <text x="22" y="132" fill="#7d8590" font-size="18">work intent · autonomy · phase switch · resume</text>
+    </g>
+
+    <g transform="translate(0 682)">
+      <rect width="640" height="164" rx="16" fill="url(#panel)" stroke="#30363d"/>
+      <text x="22" y="34" fill="#8b949e" font-size="18" font-weight="700" letter-spacing="1">OBSERVE &amp; CONTROL</text>
+
+      <g transform="translate(22 54)" font-size="20" font-weight="700">
+        <rect width="136" height="44" rx="9" fill="#0d1117" stroke="#30363d"/>
+        <text x="18" y="29" fill="#f0f6fc">Footer</text>
+        <rect x="150" width="136" height="44" rx="9" fill="#0d1117" stroke="#30363d"/>
+        <text x="168" y="29" fill="#f0f6fc">Dashboards</text>
+        <rect x="300" width="136" height="44" rx="9" fill="#0d1117" stroke="#30363d"/>
+        <text x="318" y="29" fill="#f0f6fc">Artifacts</text>
+        <rect x="450" width="146" height="44" rx="9" fill="#0d1117" stroke="#30363d"/>
+        <text x="468" y="29" fill="#f0f6fc">Cleanup</text>
+      </g>
+      <text x="22" y="132" fill="#7d8590" font-size="18">inspect · stop · audit · bounded shutdown</text>
+    </g>
+
+    <g transform="translate(0 872)">
+      <rect width="640" height="78" rx="14" fill="#111820" stroke="#30363d"/>
+      <circle cx="28" cy="27" r="7" fill="#3fb950"/>
+      <text x="50" y="35" fill="#f0f6fc" font-size="21" font-weight="700">Fail closed</text>
+      <text x="28" y="62" fill="#8b949e" font-size="17">unknown or unsafe state → denied, never guessed</text>
+    </g>
+  </g>
+</svg>

package/assets/readme-runtime.svg

@@ -0,0 +1,111 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="520" viewBox="0 0 1200 520" role="img" aria-labelledby="title desc">
+  <title id="title">OpenPI runtime model</title>
+  <desc id="desc">The main Pi session delegates execution to background terminals, subagents, and workflows while state, context, and observability stay under parent control.</desc>
+  <defs>
+    <linearGradient id="panel" x1="0" y1="0" x2="1" y2="1">
+      <stop stop-color="#161b22"/>
+      <stop offset="1" stop-color="#0d1117"/>
+    </linearGradient>
+    <marker id="arrow" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto" markerUnits="strokeWidth">
+      <path d="M0 0L8 4 0 8Z" fill="#484f58"/>
+    </marker>
+  </defs>
+
+  <rect width="1200" height="520" rx="24" fill="#0d1117"/>
+  <rect x="1" y="1" width="1198" height="518" rx="23" fill="none" stroke="#30363d" stroke-width="2"/>
+
+  <g font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif">
+    <text x="52" y="56" fill="#f0f6fc" font-size="24" font-weight="700">One parent. Three execution paths. One observable lifecycle.</text>
+    <text x="52" y="84" fill="#8b949e" font-size="15">The parent owns user interaction, configuration, durable state, and cleanup.</text>
+  </g>
+
+  <g transform="translate(52 116)" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">
+    <rect width="250" height="120" rx="14" fill="url(#panel)" stroke="#58a6ff" stroke-width="2"/>
+    <rect x="18" y="18" width="84" height="24" rx="12" fill="#12233d"/>
+    <text x="31" y="35" fill="#79c0ff" font-size="13" font-weight="700">PARENT</text>
+    <text x="18" y="72" fill="#f0f6fc" font-size="17" font-weight="700">Main Pi Session</text>
+    <text x="18" y="98" fill="#8b949e" font-size="14">plan · decide · synthesize</text>
+
+    <path d="M250 60H316" stroke="#484f58" stroke-width="2" marker-end="url(#arrow)"/>
+
+    <g transform="translate(334 0)">
+      <rect width="710" height="120" rx="14" fill="#090d12" stroke="#30363d"/>
+      <text x="20" y="26" fill="#7d8590" font-size="13" font-weight="700" letter-spacing="1">EXECUTION PLANE</text>
+
+      <g transform="translate(20 42)">
+        <rect width="205" height="58" rx="10" fill="#0d1117" stroke="#238636"/>
+        <circle cx="18" cy="20" r="4" fill="#3fb950"/>
+        <text x="31" y="24" fill="#7ee787" font-size="14" font-weight="700">Background terminal</text>
+        <text x="16" y="45" fill="#7d8590" font-size="13">server · watcher · build</text>
+      </g>
+      <g transform="translate(244 42)">
+        <rect width="205" height="58" rx="10" fill="#0d1117" stroke="#1f6feb"/>
+        <circle cx="18" cy="20" r="4" fill="#58a6ff"/>
+        <text x="31" y="24" fill="#79c0ff" font-size="14" font-weight="700">Pi subagent</text>
+        <text x="16" y="45" fill="#7d8590" font-size="13">isolated context</text>
+      </g>
+      <g transform="translate(468 42)">
+        <rect width="222" height="58" rx="10" fill="#0d1117" stroke="#8957e5"/>
+        <circle cx="18" cy="20" r="4" fill="#bc8cff"/>
+        <text x="31" y="24" fill="#d2a8ff" font-size="14" font-weight="700">Dynamic workflow</text>
+        <text x="16" y="45" fill="#7d8590" font-size="13">pipeline · schema · replay</text>
+      </g>
+    </g>
+
+    <path d="M177 120V176" stroke="#484f58" stroke-width="2" marker-end="url(#arrow)"/>
+    <path d="M690 120V176" stroke="#484f58" stroke-width="2" marker-end="url(#arrow)"/>
+
+    <g transform="translate(0 194)">
+      <rect width="514" height="126" rx="14" fill="url(#panel)" stroke="#30363d"/>
+      <text x="20" y="27" fill="#7d8590" font-size="13" font-weight="700" letter-spacing="1">CONTINUITY</text>
+
+      <g transform="translate(20 46)" font-size="14">
+        <rect width="104" height="54" rx="9" fill="#0d1117" stroke="#30363d"/>
+        <text x="16" y="23" fill="#f0f6fc" font-weight="700">Tasks</text>
+        <text x="16" y="41" fill="#7d8590">work intent</text>
+
+        <rect x="118" width="104" height="54" rx="9" fill="#0d1117" stroke="#30363d"/>
+        <text x="134" y="23" fill="#f0f6fc" font-weight="700">Goal</text>
+        <text x="134" y="41" fill="#7d8590">autonomy</text>
+
+        <rect x="236" width="120" height="54" rx="9" fill="#0d1117" stroke="#30363d"/>
+        <text x="252" y="23" fill="#f0f6fc" font-weight="700">Context Pivot</text>
+        <text x="252" y="41" fill="#7d8590">phase switch</text>
+
+        <rect x="370" width="104" height="54" rx="9" fill="#0d1117" stroke="#30363d"/>
+        <text x="386" y="23" fill="#f0f6fc" font-weight="700">Sessions</text>
+        <text x="386" y="41" fill="#7d8590">find · resume</text>
+      </g>
+    </g>
+
+    <g transform="translate(534 194)">
+      <rect width="510" height="126" rx="14" fill="url(#panel)" stroke="#30363d"/>
+      <text x="20" y="27" fill="#7d8590" font-size="13" font-weight="700" letter-spacing="1">OBSERVE &amp; CONTROL</text>
+
+      <g transform="translate(20 46)" font-size="14">
+        <rect width="108" height="54" rx="9" fill="#0d1117" stroke="#30363d"/>
+        <text x="16" y="23" fill="#f0f6fc" font-weight="700">Footer</text>
+        <text x="16" y="41" fill="#7d8590">live signals</text>
+
+        <rect x="122" width="108" height="54" rx="9" fill="#0d1117" stroke="#30363d"/>
+        <text x="138" y="23" fill="#f0f6fc" font-weight="700">Dashboards</text>
+        <text x="138" y="41" fill="#7d8590">inspect · stop</text>
+
+        <rect x="244" width="108" height="54" rx="9" fill="#0d1117" stroke="#30363d"/>
+        <text x="260" y="23" fill="#f0f6fc" font-weight="700">Artifacts</text>
+        <text x="260" y="41" fill="#7d8590">audit · handoff</text>
+
+        <rect x="366" width="104" height="54" rx="9" fill="#0d1117" stroke="#30363d"/>
+        <text x="382" y="23" fill="#f0f6fc" font-weight="700">Cleanup</text>
+        <text x="382" y="41" fill="#7d8590">bounded</text>
+      </g>
+    </g>
+
+    <g transform="translate(0 350)">
+      <rect width="1044" height="52" rx="12" fill="#111820" stroke="#30363d"/>
+      <circle cx="24" cy="26" r="5" fill="#3fb950"/>
+      <text x="40" y="31" fill="#c9d1d9" font-size="13">Fail closed:</text>
+      <text x="132" y="31" fill="#8b949e" font-size="13">unknown tools, unsafe replay, uncertain Git state, and child orchestration are denied — never guessed.</text>
+    </g>
+  </g>
+</svg>