@rol1n/pi-kit 0.1.1 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RoL1n_SrP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,45 +1,78 @@
 # pi-kit
 
-Pi extensions and prompt templates distributed together as **`@rol1n/pi-kit`** and individually as **`@rol1n/<extension>`**. Each extension directory contains its own `index.ts` and `README.md`.
+> Modular extensions and prompt templates for the [Pi Coding Agent](https://pi.dev), published as the **`@rol1n/pi-kit`** bundle and as standalone **`@rol1n/<extension>`** packages.
+
+<p align="left">
+  <b>English</b> •
+  <a href="README_zh.md"><b>中文说明</b></a>
+</p>
+
+[![npm version](https://img.shields.io/npm/v/@rol1n/pi-kit?style=flat-square&logo=npm)](https://www.npmjs.com/package/@rol1n/pi-kit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
+
+---
 
 ## Install
 
+Install the default bundle:
+
 ```sh
 pi install npm:@rol1n/pi-kit
 ```
 
-Install from GitHub or a local checkout:
+Or install any standalone extension individually:
+
+```sh
+pi install npm:@rol1n/memory-log
+pi install npm:@rol1n/subagent
+pi install npm:@rol1n/multi-harness
+```
+
+Install from GitHub or a local checkout during development:
 
 ```sh
 pi install https://github.com/RolinShmily/pi-kit
 pi install /absolute/path/to/pi-kit
 ```
 
-Update with `pi update npm:@rol1n/pi-kit` or `pi update --extensions`.
+Update installed packages:
+
+```sh
+pi update npm:@rol1n/pi-kit
+pi update --extensions
+```
+
+---
 
 ## Extensions
 
-| Extension | Purpose | Default in kit | Standalone npm |
-|---|---|---|---|
-| [ask-u-questions](ask-u-questions/README.md) | Interactive single/multi-choice and text dialogs | Yes | `@rol1n/ask-u-questions` |
-| [continue-signal](continue-signal/README.md) | Resume an idle agent via `/continue` or Alt+C | Yes | `@rol1n/continue-signal` |
+Each top-level directory is a self-contained extension (`<name>/index.ts` + `README.md`). Detailed commands, parameters, and settings are documented in each extension's README:
+
+| Extension | Description | In `@rol1n/pi-kit` | Standalone Package |
+| :--- | :--- | :---: | :--- |
+| [ask-u-questions](ask-u-questions/README.md) | Interactive single-choice, multi-choice, and text dialogs | Yes | `@rol1n/ask-u-questions` |
+| [continue-signal](continue-signal/README.md) | Resume an idle agent via `/continue` or `Alt+C` | Yes | `@rol1n/continue-signal` |
 | [custom-providers](custom-providers/README.md) | Additional model providers and gateway registration | Yes | `@rol1n/custom-providers` |
-| [image-generate](image-generate/README.md) | Image generation tool and `/image-generate` selector | Yes | `@rol1n/image-generate` |
-| [memory-log](memory-log/README.md) | Background observational memory and compaction | Yes | `@rol1n/memory-log` |
-| [model-vision](model-vision/README.md) | Image understanding and OCR tool | No | `@rol1n/model-vision` |
-| [multi-harness](multi-harness/README.md) | Delegate to Pi, Codex, Claude, and OpenCode | Yes | `@rol1n/multi-harness` |
-| [oai-subquota](oai-subquota/README.md) | OpenAI Codex subscription quota monitor | Yes | `@rol1n/oai-subquota` |
-| [prompt-snipaste](prompt-snipaste/README.md) | Select prompt snippets for the next user message (bundles 7 built-in prompts) | Yes | `@rol1n/prompt-snipaste` |
-| [screenshot](screenshot/README.md) | Insert the latest Windows/WSL screenshot path | No | `@rol1n/screenshot` |
-| [srp-theme](srp-theme/README.md) | Prompt preview footer and streaming TPS meter | Yes | `@rol1n/srp-theme` |
-| [subagent](subagent/README.md) | Delegate to asynchronous Pi workers | Yes | `@rol1n/subagent` |
-| [tui-asr](tui-asr/README.md) | Streaming voice dictation via DashScope ASR | Yes | `@rol1n/tui-asr` |
-| [web-reach](web-reach/README.md) | Keyless Exa web search and multi-tier page extraction | Yes | `@rol1n/web-reach` |
-| [windows-wheel-fix](windows-wheel-fix/README.md) | Windows ConPTY/Zellij mouse-wheel reporting fix | Yes (Windows only) | `@rol1n/windows-wheel-fix` |
-
-## Resource selection
-
-The kit exposes 13 extension entrypoints and the 7 prompt templates bundled in [prompt-snipaste/prompts](prompt-snipaste/prompts/). Narrow loaded resources with `pi config` or in `settings.json`:
+| [image-generate](image-generate/README.md) | Image generation tool and `/image-generate` model selector | Yes | `@rol1n/image-generate` |
+| [memory-log](memory-log/README.md) | Tiered asynchronous observational memory and instant compaction | Yes | `@rol1n/memory-log` |
+| [model-vision](model-vision/README.md) | Image understanding and OCR tool (`model_vision`) | No | `@rol1n/model-vision` |
+| [multi-harness](multi-harness/README.md) | Delegate tasks across `pi`, `codex`, `claude`, and `opencode` | Yes | `@rol1n/multi-harness` |
+| [oai-subquota](oai-subquota/README.md) | OpenAI Codex subscription quota monitor and statusline | Yes | `@rol1n/oai-subquota` |
+| [prompt-snipaste](prompt-snipaste/README.md) | Prompt snippet selector (`/snipaste`, `Alt+S`) with 7 built-in prompts | Yes | `@rol1n/prompt-snipaste` |
+| [screenshot](screenshot/README.md) | Insert the latest Windows/WSL screenshot path (`/screenshot`) | No | `@rol1n/screenshot` |
+| [srp-theme](srp-theme/README.md) | Last-prompt preview widget and real-time streaming TPS meter | Yes | `@rol1n/srp-theme` |
+| [subagent](subagent/README.md) | Delegate tasks to parallel Pi workers in tmux/Zellij or background processes | Yes | `@rol1n/subagent` |
+| [tui-asr](tui-asr/README.md) | Streaming voice dictation via Aliyun DashScope ASR (`/asr`, `Alt+M`) | Yes | `@rol1n/tui-asr` |
+| [web-reach](web-reach/README.md) | Keyless Exa MCP web search and multi-tier page extraction | No | `@rol1n/web-reach` |
+| [windows-wheel-fix](windows-wheel-fix/README.md) | Windows ConPTY / Zellij mouse-wheel reporting fix | Yes (Windows) | `@rol1n/windows-wheel-fix` |
+
+> Standalone packages with cross-extension dependencies (`tui-asr` / `image-generate` -> `@rol1n/custom-providers`, `multi-harness` -> `@rol1n/subagent`) declare standard npm `dependencies` and resolve them automatically on install.
+
+---
+
+## Resource Selection
+
+`@rol1n/pi-kit` exposes 12 extension entrypoints and the 7 prompt templates bundled in [prompt-snipaste/prompts](prompt-snipaste/prompts/). Use `pi config` or filter loaded resources in `settings.json`:
 
 ```json
 {
@@ -53,22 +86,51 @@ The kit exposes 13 extension entrypoints and the 7 prompt templates bundled in [
 }
 ```
 
-## Build and publish
+---
 
-[kit.config.json](kit.config.json) controls which extensions are bundled into `@rol1n/pi-kit` (`bundle: true`) and inter-extension npm dependencies (`deps`).
+## Development & Publishing
+
+[kit.config.json](kit.config.json) controls bundle selection (`bundle`), inter-extension dependencies (`deps`), and release versions. The top-level `version` belongs to `@rol1n/pi-kit`; each extension can set its own `version`, otherwise it inherits the top-level version. Set explicit extension versions to release the kit and standalone packages independently.
+
+### Automated releases
+
+1. Update the code and bump the relevant version(s) in `kit.config.json`.
+2. Push to `main` with changes to `kit.config.json` or `package.json`, or manually run **Publish to npm** in GitHub Actions. Changes to the packaging script or workflow also trigger a release run.
+3. CI runs the same pipeline for both triggers:
+
+```sh
+npm run manifest
+npm run check
+npm run publish:ci -- all
+```
+
+The workflow in [`.github/workflows/publish.yml`](.github/workflows/publish.yml) generates `package.json`, validates the layout, then publishes all standalone extensions in dependency order, followed by the kit. Already-published versions are skipped; versions are never bumped automatically. `bundle: false` excludes an extension from the kit, not from standalone publishing. Publishing runs do not overlap, and a new run does not cancel an active release. Code-only pushes do not trigger publishing.
+
+You do not need to run `manifest` or publish locally for an npm release. CI generates the manifest only in its checkout and does not commit it back. For local or Git installs, run `npm run manifest` and commit the generated `package.json` when changing bundle selection or versions so the repository manifest stays in sync.
+
+### Local development and manual publishing
 
 ```sh
-# Sync package.json from kit.config.json and validate
+# Sync the local manifest and validate all extensions
 npm run manifest
 npm run check
 
-# Stage any extension into dist/<id>
-npm run prepare:extension -- subagent
+# Stage a standalone package into dist/<id>
+npm run prepare:extension -- memory-log
 
-# Publish all standalone extensions, or the kit, or one extension
-npm run publish:ci -- extensions
-npm run publish:ci -- kit
-npm run publish:ci -- tui-asr
+# Optional local release; also accepts extensions, kit, or a single extension ID
+npm run publish:ci -- all
 ```
 
-GitHub Actions OIDC Trusted Publishing is configured in [`.github/workflows/publish.yml`](.github/workflows/publish.yml).
+---
+
+## Acknowledgements
+
+- [elpapi42/pi-observational-memory](https://github.com/elpapi42/pi-observational-memory) — Observational memory architecture and inspiration for [`memory-log`](memory-log/README.md).
+- [earendil-works/pi](https://github.com/earendil-works/pi) — The Pi coding agent harness and SDK.
+
+---
+
+## License
+
+[MIT](LICENSE) © RoL1n_SrP

package/README_zh.md

@@ -0,0 +1,136 @@
+# pi-kit
+
+> 面向 [Pi Coding Agent](https://pi.dev) 的模块化扩展与提示词模板套件，支持作为 **`@rol1n/pi-kit`** 聚合包或 **`@rol1n/<extension>`** 独立包安装。
+
+<p align="left">
+  <a href="README.md"><b>English</b></a> •
+  <b>中文说明</b>
+</p>
+
+[![npm version](https://img.shields.io/npm/v/@rol1n/pi-kit?style=flat-square&logo=npm)](https://www.npmjs.com/package/@rol1n/pi-kit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
+
+---
+
+## 安装
+
+安装默认聚合包：
+
+```sh
+pi install npm:@rol1n/pi-kit
+```
+
+或按需安装任意独立扩展包：
+
+```sh
+pi install npm:@rol1n/memory-log
+pi install npm:@rol1n/subagent
+pi install npm:@rol1n/multi-harness
+```
+
+开发期间也可直接从 GitHub 或本地目录安装：
+
+```sh
+pi install https://github.com/RolinShmily/pi-kit
+pi install /absolute/path/to/pi-kit
+```
+
+更新已安装的包：
+
+```sh
+pi update npm:@rol1n/pi-kit
+pi update --extensions
+```
+
+---
+
+## 扩展列表
+
+仓库根目录下每个文件夹均为自包含扩展（`<name>/index.ts` + `README.md`）。各扩展的详细命令、参数与配置说明请参阅对应目录的 README：
+
+| 扩展目录 | 功能简介 | 默认纳入 `pi-kit` | 独立 npm 包名 |
+| :--- | :--- | :---: | :--- |
+| [ask-u-questions](ask-u-questions/README.md) | 交互式单选、多选与自由文本提问弹窗（共享 UI 锁） | Yes | `@rol1n/ask-u-questions` |
+| [continue-signal](continue-signal/README.md) | 通过 `/continue` 或 `Alt+C` 唤醒空闲智能体继续未完成任务 | Yes | `@rol1n/continue-signal` |
+| [custom-providers](custom-providers/README.md) | 自定义模型服务商与网关（Magpie、智谱、阿里百炼等）注册 | Yes | `@rol1n/custom-providers` |
+| [image-generate](image-generate/README.md) | OpenRouter / 百炼文生图与参考图生图工具及 `/image-generate` 模型选择器 | Yes | `@rol1n/image-generate` |
+| [memory-log](memory-log/README.md) | 分层异步观察记忆系统与零模型阻塞的确定性秒级压缩 | Yes | `@rol1n/memory-log` |
+| [model-vision](model-vision/README.md) | 本地与远程图片视觉理解、OCR 与 UI 诊断工具（`model_vision`） | No | `@rol1n/model-vision` |
+| [multi-harness](multi-harness/README.md) | 跨 `pi`、`codex`、`claude`、`opencode` 的多 CLI 协同委派运行时 | Yes | `@rol1n/multi-harness` |
+| [oai-subquota](oai-subquota/README.md) | OpenAI Codex 订阅额度（5h / 7d 窗口与重置时间）状态栏监控 | Yes | `@rol1n/oai-subquota` |
+| [prompt-snipaste](prompt-snipaste/README.md) | 提示词片段选择器（`/snipaste`、`Alt+S`），内置 7 个常用提示词模板 | Yes | `@rol1n/prompt-snipaste` |
+| [screenshot](screenshot/README.md) | 一键将最新 Windows / WSL 系统截图路径插入编辑器（`/screenshot`） | No | `@rol1n/screenshot` |
+| [srp-theme](srp-theme/README.md) | 编辑器下方最近提问预览组件与实时流式 TPS 速率仪表 | Yes | `@rol1n/srp-theme` |
+| [subagent](subagent/README.md) | 基于 tmux / Zellij 分屏或后台进程的并发 Pi 子智能体工具 | Yes | `@rol1n/subagent` |
+| [tui-asr](tui-asr/README.md) | 基于阿里百炼 Paraformer 的终端实时流式语音听写（`/asr`、`Alt+M`） | Yes | `@rol1n/tui-asr` |
+| [web-reach](web-reach/README.md) | 免 Key Exa MCP 网页搜索与多级网页正文提取（RSC / HTML / PDF / Jina） | No | `@rol1n/web-reach` |
+| [windows-wheel-fix](windows-wheel-fix/README.md) | 修复 Windows ConPTY / Zellij 下鼠标滚轮被误转为上下方向键的问题 | Yes (仅 Windows) | `@rol1n/windows-wheel-fix` |
+
+> 带有跨扩展依赖的独立包（`tui-asr` / `image-generate` 依赖 `@rol1n/custom-providers`，`multi-harness` 依赖 `@rol1n/subagent`）已声明标准 npm `dependencies`，单独安装时会自动拉取补全并激活所需依赖。
+
+---
+
+## 资源按需筛选
+
+`@rol1n/pi-kit` 默认导出 12 个扩展入口与 [prompt-snipaste/prompts](prompt-snipaste/prompts/) 下的 7 个提示词模板。可通过 `pi config` 或在 `settings.json` 中按需过滤：
+
+```json
+{
+  "packages": [
+    {
+      "source": "npm:@rol1n/pi-kit",
+      "extensions": ["**/*.ts", "!tui-asr/**"],
+      "prompts": ["prompt-snipaste/prompts/diagnose-report.md"]
+    }
+  ]
+}
+```
+
+---
+
+## 构建与发布
+
+[kit.config.json](kit.config.json) 统一管理聚合包选择（`bundle`）、扩展间的依赖关系（`deps`）与发布版本。顶层 `version` 属于 `@rol1n/pi-kit`；各扩展可以单独设置 `version`，未设置时继承顶层版本。为每个扩展显式设置版本即可让聚合包与独立包分别升级。
+
+### 自动发布
+
+1. 修改代码，并在 `kit.config.json` 中提升需要发布的包的版本。
+2. 将包含 `kit.config.json` 或 `package.json` 变更的提交推送到 `main`，或在 GitHub Actions 手动运行 **Publish to npm**。修改打包脚本或工作流本身也会触发发布流程。
+3. 自动和手动触发均执行同一条流水线：
+
+```sh
+npm run manifest
+npm run check
+npm run publish:ci -- all
+```
+
+[`.github/workflows/publish.yml`](.github/workflows/publish.yml) 会生成 `package.json`、校验扩展布局，再按依赖顺序发布所有独立扩展，最后发布聚合包。已存在的版本自动跳过，不会自动提升版本号。`bundle: false` 只表示不纳入聚合包，不影响独立发布。发布流程不会并行执行，新触发的流程也不会取消正在进行的发布。仅修改扩展代码不会触发发布。
+
+发布 npm 包无需本地运行 `manifest` 或 `publish`。CI 只在运行目录中生成清单，不会自动提交回仓库。若使用本地或 Git 安装，调整聚合包选择或版本后仍应运行 `npm run manifest` 并提交生成的 `package.json`，保持仓库清单同步。
+
+### 本地开发与手动发布
+
+```sh
+# 同步本地清单并校验所有扩展
+npm run manifest
+npm run check
+
+# 将单个扩展构建到 dist/<id>
+npm run prepare:extension -- memory-log
+
+# 可选的本地发布，也支持 extensions、kit 或单个扩展 ID
+npm run publish:ci -- all
+```
+
+---
+
+## 致谢
+
+- [elpapi42/pi-observational-memory](https://github.com/elpapi42/pi-observational-memory) — [`memory-log`](memory-log/README.md) 的观察记忆架构灵感与上游基础。
+- [earendil-works/pi](https://github.com/earendil-works/pi) — Pi Coding Agent 运行时与 SDK。
+
+---
+
+## 许可证
+
+[MIT](LICENSE) © RoL1n_SrP

package/memory-log/README.md

@@ -1,6 +1,8 @@
 # memory-log
 
-Observational memory for long Pi sessions: background observers distill conversation chunks, a ledger records observations, and a consolidator writes durable project memory. Compaction rebuilds context from the recorded memory and recent conversation.
+> Tiered asynchronous observational memory for long-running Pi sessions.
+
+`memory-log` keeps multi-day coding sessions coherent across compactions without blocking your workflow. Based on the observational memory paradigm from [elpapi42/pi-observational-memory](https://github.com/elpapi42/pi-observational-memory), it moves memory distillation into background subprocesses while you work, making compaction a model-free rendering step when sufficient observations are available. If a safe cutoff or usable memory summary is unavailable, Pi's native summarizer takes over instead.
 
 ## Install
 
@@ -8,20 +10,60 @@ Observational memory for long Pi sessions: background observers distill conversa
 pi install npm:@rol1n/memory-log
 ```
 
-Also included in `@rol1n/pi-kit`. The extension loads with new-session memory disabled by default.
+Also included in `@rol1n/pi-kit`. The extension loads with new-session memory disabled by default (`/mem-log on` to enable for the current session, or `"defaultEnabled": true` in settings).
+
+---
+
+## Why it exists
+
+Long AI coding sessions typically hit two walls:
+
+1. **The Compression Wall (Summary of a Summary)**: Traditional compaction summarizes the conversation when the context window fills up. Over multiple cycles, the agent carries a compressed summary of a previous summary, gradually losing concrete architectural rationale, rejected approaches, and subtle constraints.
+2. **Compaction Stalls**: Waiting for a model to rewrite a massive transcript right when the context window overflows interrupts flow.
+
+`memory-log` solves both by doing the heavy lifting **asynchronously in the background** as the session progresses:
+
+- **Background Observers**: Whenever raw conversation history accumulates a full chunk (`chunkTokens`), a background Pi worker distills that chunk into timestamped, priority-tagged (`🔴` / `🟡` / `🟢`) atomic observations stored in the session branch ledger.
+- **Consolidator & Durable Topic Files**: When the active observation pool reaches `consolidateAtPoolTokens`, a background consolidator archives older observations into durable Markdown topic files under `.memory/<sessionId>/` (`INDEX.md`, `<topic>.md`) and appends project milestones to `.memory/<sessionId>/JOURNEY.md`, draining the active pool back toward `poolTargetTokens`.
+- **Safe Deterministic Compaction**: After `agent_settled` (all retries and queued continuations have finished), context pressure can trigger compaction. The cutoff snaps to a completed observation boundary near `tailTokens`, never crossing an unobserved gap in newly recorded chunks or splitting a tool call from its results. The entire unobserved tail stays verbatim, even if larger than the target. The summary is rendered from `JOURNEY.md` + the **Memory Map** + active observations, without an LLM call. Missing boundaries or empty memory delegate to Pi's native summarizer, which may make an LLM call.
+- **Source Recall**: `memory_recall` retrieves the original conversation chunk behind an observation by timestamp, including history hidden by compaction and observations archived to topic files.
+- **TUI Observability**: Displays live footer gauges (`Next` chunk progress, `Pool` capacity, `Ctx` window usage), active worker spinners, and session memory cost.
+
+---
 
 ## Commands
 
 | Command | Action |
 |---|---|
-| `/mem-log on` / `/mem-log off` | Set the current session's memory gate |
-| `/mem-log status` or `/mem-log:status` | Inspect observation progress, workers, memory, and costs |
-| `/mem-log compact` or `/mem-log:compact` | Request compaction |
-| `/mem-log consolidate` or `/mem-log:consolidate` | Consolidate the observation pool |
+| `/mem-log` | Enable memory log (if off) or display status & timeline (if on) |
+| `/mem-log on` / `/mem-log off` | Enable or disable observational memory for the current session |
+| `/mem-log status` or `/mem-log:status` | View gauges, worker states, cost summary, and observation timeline |
+| `/mem-log compact` or `/mem-log:compact` | Request immediate compaction (native summarization if no safe memory cutoff exists) |
+| `/mem-log consolidate` or `/mem-log:consolidate` | Consolidate the active observation pool into durable topic files immediately |
+
+---
 
-## Settings
+## Source recall
 
-Add `memoryLog` to personal or project Pi settings. Project values override personal values:
+The agent can call `memory_recall` with an observation's full timestamp-id (including a `.NN` suffix, if present), or an unambiguous prefix:
+
+```json
+{ "timestamp": "2026-10-23T14:30:00" }
+```
+
+- New observations persist exact `sourceEntryIds`; provenance covers the **whole chunk**, not a per-fact citation.
+- Older records remain readable: ranges are inferred from coverage anchors in source order, not worker completion order. Inferred ranges are explicitly labeled and may include extra conversation; old records cannot prove gaps caused by failed workers. Legacy compaction coverage retains its existing watermark interpretation.
+- Recall searches only the **current branch**. Missing sources are reported as unavailable or partial, never borrowed from another branch. Archived observations remain traceable in the ledger.
+- Output is paged at 12,000 source characters. Use the returned `nextOffset` as `offset` to continue; `limit` can request a smaller page. Images/non-text blocks use placeholders.
+- Recall is read-only and remains available when background memory processing is disabled.
+
+Automatic compaction requires a Pi version that exposes `agent_settled`. Aborted runs do not trigger it; there is no retry-error guessing or idle polling. Pi's own compaction mechanism remains independent.
+
+---
+
+## Configuration
+
+Add a `memoryLog` section to `~/.pi/agent/settings.json` (global) or `.pi/settings.json` (project-level override):
 
 ```json
 {
@@ -34,7 +76,6 @@ Add `memoryLog` to personal or project Pi settings. Project values override pers
     "tailTokens": 20000,
     "journeyTargetTokens": 1000,
     "observerConcurrency": 4,
-    "resumeAfterMidRunCompaction": true,
     "passive": false,
     "debugLog": false,
     "models": {
@@ -45,10 +86,36 @@ Add `memoryLog` to personal or project Pi settings. Project values override pers
 }
 ```
 
-Observer and consolidator model objects accept `provider`, `id`, and `thinking`. An explicitly configured model takes priority over the session model, followed by Pi's configured default model. `chunkOverlapTokens` defaults to zero.
+`resumeAfterMidRunCompaction` is retained for configuration compatibility but has no effect: this extension's automatic trigger now runs only after settlement and never starts a synthetic continuation.
+
+### Model resolution
+
+`models.observer` and `models.consolidator` accept `{ "provider": "...", "id": "...", "thinking": "off|minimal|low|medium|high|xhigh" }`.
+Resolution priority: **explicit `memoryLog.models` -> current session model -> Pi default model (`defaultProvider` / `defaultModel`)**.
+
+### Environment overrides
+
+| Variable | Purpose |
+|---|---|
+| `PI_OM_PASSIVE=1` | Disable automatic observer/consolidator/compaction triggers while keeping manual commands |
+| `PI_OM_OBSERVER_PROVIDER` / `PI_OM_OBSERVER_MODEL` / `PI_OM_OBSERVER_THINKING` | Override observer worker model |
+| `PI_OM_CONSOLIDATOR_PROVIDER` / `PI_OM_CONSOLIDATOR_MODEL` / `PI_OM_CONSOLIDATOR_THINKING` | Override consolidator worker model |
+
+---
+
+## Storage layout
+
+```text
+<project-root>/.memory/<session-id>/
+├── INDEX.md          # Orchestrator-rendered index of durable topics (injected as the Memory Map)
+├── JOURNEY.md        # Chronological project history maintained by the consolidator
+└── <topic-slug>.md   # Durable topic notes read on demand by the agent
+```
+
+Short-term observations and enable/disable gates are stored directly in the Pi session JSONL ledger so they branch and fork naturally with your session tree.
 
-Environment overrides are `PI_OM_PASSIVE`, `PI_OM_OBSERVER_PROVIDER`, `PI_OM_OBSERVER_MODEL`, `PI_OM_OBSERVER_THINKING`, and the corresponding `PI_OM_CONSOLIDATOR_*` values. Passive mode disables automatic triggers separately from the session gate.
+---
 
-## Storage and requirements
+## Credits
 
-Durable files live under `.memory/<session-id>/` in the working project, including topic files and `JOURNEY.md`. Gate changes and observation history are recorded in the Pi session ledger. Observer and consolidator workers require the `pi` executable and model credentials; they make additional model requests. Disabling memory aborts active background workers.
+Adapted from and inspired by [elpapi42/pi-observational-memory](https://github.com/elpapi42/pi-observational-memory) (MIT License), extended with file-backed durable topic consolidation (`.memory/<sessionId>/`), `JOURNEY.md` tracking, and TUI progress gauges.

package/memory-log/config.ts

@@ -42,7 +42,7 @@ export interface Config {
    * used as the last-resort fallback when no session model is available.
    */
   settingsDefaultModel?: { provider?: string; id?: string };
-  /** Resume the agent automatically after a mid-run compaction. */
+  /** @deprecated Compatibility only; automatic compaction now runs after agent_settled. */
   resumeAfterMidRunCompaction: boolean;
   /** Power-user setting: disable all triggers (distinct from the on/off gate). */
   passive: boolean;

package/memory-log/hooks/compaction-hook.ts

@@ -14,16 +14,50 @@ import {
   type Entry,
 } from "../ledger/index.ts";
 
-/** Distinct, branch-resolved coversUpToId indices of committed observation chunks, ascending. */
+/**
+ * Completed boundaries behind the contiguous observation frontier. A later worker
+ * finishing first must not authorize discarding an earlier failed/in-flight chunk.
+ * Legacy records only have a cumulative watermark; retain that older contract.
+ */
 function chunkBoundaryIndices(branch: Entry[]): number[] {
   const indexes = entryIndexById(branch);
-  const set = new Set<number>();
-  for (const entry of branch) {
+  const boundaries = new Set<number>();
+  const coveredAt = new Map<string, number>();
+  let legacyFrontier = -1;
+  for (let i = 0; i < branch.length; i++) {
+    const entry = branch[i];
     if (!isObservationsRecordedEntry(entry)) continue;
     const idx = indexes.get(entry.data.coversUpToId);
-    if (idx !== undefined) set.add(idx);
+    if (idx === undefined || idx >= i || !isSourceEntry(branch[idx])) continue;
+    if (entry.data.sourceEntryIds === undefined) {
+      legacyFrontier = Math.max(legacyFrontier, idx);
+    } else {
+      const ids = entry.data.sourceEntryIds;
+      // Reject unresolved, out-of-order, or non-source anchors.
+      let previous = -1;
+      const valid = ids.length > 0 && ids.at(-1) === entry.data.coversUpToId && ids.every((id) => {
+        const index = indexes.get(id);
+        if (index === undefined || index <= previous || index > idx || !isSourceEntry(branch[index])) return false;
+        previous = index;
+        return true;
+      });
+      if (!valid) continue;
+      for (const id of ids) coveredAt.set(id, Math.min(coveredAt.get(id) ?? Infinity, idx));
+    }
+    boundaries.add(idx);
+  }
+  const safeBoundaries: number[] = [];
+  let requiredCoverageEnd = -1;
+  for (let i = 0; i < branch.length; i++) {
+    if (isSourceEntry(branch[i])) {
+      const coveredEnd = i <= legacyFrontier ? i : (coveredAt.get(branch[i].id) ?? Infinity);
+      requiredCoverageEnd = Math.max(requiredCoverageEnd, coveredEnd);
+    }
+    // The projection must include the records that authorize this cut, not just
+    // records for overlapping chunks whose watermarks lie beyond it.
+    if (boundaries.has(i) && requiredCoverageEnd <= i) safeBoundaries.push(i);
   }
-  return Array.from(set).sort((a, b) => a - b);
+  return safeBoundaries;
 }
 
 /** First source entry after `boundaryIndex` that is a valid cut point, or undefined. */
@@ -37,9 +71,9 @@ function firstKeptAfterBoundary(branch: Entry[], boundaryIndex: number): Entry |
 
 export function snapCutoff(
   branch: Entry[],
-  proposedFirstKeptId: string,
+  _proposedFirstKeptId: string,
   tailTokens: number,
-): { firstKeptId: string; tail: number | undefined } {
+): { firstKeptId: string | undefined; tail: number | undefined } {
   const indexes = entryIndexById(branch);
   const lastCompactionIdx = findLastCompactionIndex(branch);
   const boundaries = chunkBoundaryIndices(branch);
@@ -80,26 +114,21 @@ export function snapCutoff(
     }
   }
 
-  if (!finalFirstKeptId) {
-    finalFirstKeptId = proposedFirstKeptId;
-    finalTail = undefined;
-  }
-
   return { firstKeptId: finalFirstKeptId, tail: finalTail };
 }
 
-export function snapFirstKeptEntryId(branch: Entry[], proposedFirstKeptId: string, tailTokens: number): string {
+export function snapFirstKeptEntryId(branch: Entry[], proposedFirstKeptId: string, tailTokens: number): string | undefined {
   return snapCutoff(branch, proposedFirstKeptId, tailTokens).firstKeptId;
 }
 
 export function canSkipObserverWait(
   branch: Entry[],
-  snappedFirstKeptId: string,
+  snappedFirstKeptId: string | undefined,
   snappedTail: number | undefined,
   tailTokens: number,
   observersInFlight: Iterable<{ coversUpToId: string }>,
 ): boolean {
-  if (snappedTail === undefined || snappedTail > tailTokens) return false;
+  if (!snappedFirstKeptId || snappedTail === undefined || snappedTail > tailTokens) return false;
 
   const indexes = entryIndexById(branch);
   const cutoffIndex = indexes.get(snappedFirstKeptId);
@@ -115,6 +144,7 @@ export function canSkipObserverWait(
 export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void {
   pi.on("session_before_compact", async (event: any, ctx: any) => {
     if (!runtime.enabled || runtime.config.passive) return undefined;
+    if (event.signal?.aborted) return { cancel: true };
 
     const hasUI = ctx.hasUI;
     if (runtime.compactHookInFlight) {
@@ -140,11 +170,24 @@ export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void
         snap = snapCutoff(branch, firstKeptEntryId, tailTokens);
       }
 
+      if (event.signal?.aborted) return { cancel: true };
+      if (!runtime.enabled) return undefined;
+
+      // No proven observed cut: let Pi summarize the raw history, never stamp an
+      // empty deterministic summary over unobserved messages (including old tails).
       const snapped = snap.firstKeptId;
+      if (!snapped || snap.tail === undefined) {
+        if (hasUI) ctx.ui.notify("memory-log: no safe observed cutoff — using Pi's native summarizer", "info");
+        return undefined;
+      }
       const projection = buildCompactionProjection(branch, snapped);
       const journey = readJourney(runtime.memoryRoot);
       const map = renderMemoryMap(listTopics(runtime.memoryRoot));
       const summary = renderSummary(journey, map, projection.observations);
+      if (!summary.trim()) {
+        if (hasUI) ctx.ui.notify("memory-log: memory summary is empty — using Pi's native summarizer", "info");
+        return undefined;
+      }
 
       return {
         compaction: {