zames_pro 2.60.0 → 2.63.0

package/CHANGELOG.md

@@ -5,7 +5,96 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [2.63.0] - 2026-10-06
+
+### Added
+
+- Реальные подтверждения действий (BACKLOG C1): политика approval в
+  `.zames/permissions.json` (`default` + `rules` с regexp по `tool`/`command`/
+  `path` и действием `allow`|`deny`|`ask`). Вызывается в `agent-loop.ts` ПЕРЕД
+  каждым инструментом: `deny` блокирует вызов, `ask` спрашивает оператора через
+  `onAskPermission` (в TTY — интерактивный промпт над инпут-линией, в non-TTY —
+  запрет). Новый чистый модуль `src/permissions.ts` + тесты
+  (test/permissions.test.ts, test/permissions-loop.test.ts).
+
+- Кастомные команды: аргументы и подсказки (BACKLOG B7). Frontmatter
+  `argument-hint:` показывается в списке «/» и в `/help` (не вставляется в
+  строку ввода), а `arguments:` объявляет обязательные позиционные аргументы.
+  В теле команды подставляются `$1 $2`, именованные `$name`, а также прежние
+  `{{args}}`/`$ARGUMENTS`. Если обязательные аргументы не переданы — команда
+  не уходит в чат, печатается подсказка. Новые чистые хелперы
+  `splitCommandArgs()` / `expandCommandArgs()` / `missingCommandArgs()`
+  (src/commands.ts, покрыты тестами).
+
+- Path-scoped правила (BACKLOG B6): вложенные `AGENTS.md`/`MEMORY.md` из
+  подпапок, которых касается задача, подтягиваются автоматически. Текст задачи
+  сканируется на path-токены, для найденных директорий (и их предков ниже
+  рабочей) читаются ближайшие инструкции и рендерятся отдельной секцией
+  `## Scoped instructions (...)` — явно помечены как действующие только для
+  этих файлов. `loadProjectContext(workdir, touchPaths?)` и
+  `renderContextSection()` (src/context.ts, src/system-prompt.ts; покрыто
+  тестами).
+
+- `@file`-ссылки в задаче (BACKLOG B5): `реши задачу @src/browser.ts`
+  подставляет содержимое указанного файла прямо в задачу, экономя отдельный
+  ход агента на чтение. Распознаётся `@path` на границе слова (в начале строки
+  или после пробела/скобки/кавычки), с расширением файла; `user@host` и
+  декораторы (`@Component`) не трогаются. Существующие файлы инлайнятся
+  (лимит 60 КБ на файл, 200 КБ суммарно — сверх этого усечение с пометкой),
+  несуществующие остаются как есть. Хелпер `extractAtFileRefs()` в
+  `src/path-token.ts` (чистый, покрыт тестами).
+
+### Changed
+
+- `AGENTS.md` уменьшен (BACKLOG C2): глубокие root-cause разборы («агент
+  остановился», чтение ответа из DOM, send-хуки, `LineEditor`, вложения) и
+  терминальная механика вынесены в `docs/DESIGN-NOTES.md` (progressive
+  disclosure — не грузится в каждую задачу). В AGENTS.md остались действующие
+  правила и краткая выжимка со ссылкой.
+
+## [2.62.0]
+
+### Added
+
+- Checkpoints / rewind (BACKLOG B3): at the start of every task the working
+  tree is snapshotted into a tarball under `~/.zames/checkpoints/`, and
+  `/rewind [n]` rolls it back in one step (with a confirmation prompt and an
+  automatic `pre-rewind` backup of the current state, so the rewind itself is
+  reversible). `/rewind-list` shows the recent checkpoints. `node_modules`,
+  `.git`, `dist` and `tmp` are never snapshotted or deleted. Unlike a manual
+  git stash, this works in a non-git directory and never touches the
+  operator's index. New module `src/checkpoint.ts` (pure helpers + `CheckpointStore`,
+  unit-tested); configurable via `checkpoint.enabled` / `checkpoint.maxBackups`
+  (default 50) in `/config`.
+
+## [2.61.0]
+
+### Added
+
+- `/backlog <text>` — record an improvement idea in `BACKLOG.md` without
+  implementing it. Deterministic: a fresh `N<n>` id under the matching
+  `P0..P3` section; an optional leading `P0..P3` picks the section, the first
+  line is the title, the rest the body. `/backlog collapse` prunes the
+  archived blocks.
+- BACKLOG.md maintenance (`src/backlog.ts`, pure/tested): `/improve` now
+  auto-prunes a finished item's archived `<details>` copy after a successful
+  run (the `### X. [x] ... done` summary line is kept), and a startup warning
+  fires when BACKLOG.md exceeds 500 lines / 60 KB. The collapser tolerates an
+  UNCLOSED `<details>` (a real file had one).
+- Dev-mode self-improvement note: in `--dev` the system prompt tells the model
+  it may append ONE short BACKLOG.md bullet when it spots an improvement
+  outside the current task (off in a normal run).
+
+### Changed
+
+- Self-development commands (`/improve`, `/backlog`, `/self-review`,
+  `/self-fix`, `/self-done`, `/self-list`, `/self-diff`, `/self-apply`) are now
+  DEV-ONLY: they are hidden from `/help` and the «/» hints, and rejected by the
+  main loop, unless the operator runs in dev mode (`--dev` or
+  `config.hotReload`). A regular package install no longer advertises them, and
+  a hand-typed `/improve` can no longer edit an unrelated project's
+  BACKLOG.md. The list is `DEV_ONLY_COMMANDS` / `isDevOnlyCommand()` in
+  `src/commands.ts` (pure, tested).
 
 ## [2.60.0]
 
@@ -220,7 +309,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Session banner warns when no saved DeepSeek session exists.
 - `--no-color` flag (explicit `NO_COLOR`).
 
-[Unreleased]: https://github.com/Viqto0r/zames_pro/compare/v2.60.0...HEAD
+[Unreleased]: https://github.com/Viqto0r/zames_pro/compare/v2.63.0...HEAD
+[2.63.0]: https://github.com/Viqto0r/zames_pro/compare/v2.61.0...v2.63.0
+[2.61.0]: https://github.com/Viqto0r/zames_pro/compare/v2.60.0...v2.61.0
 [2.60.0]: https://github.com/Viqto0r/zames_pro/compare/v2.59.0...v2.60.0
 [2.59.0]: https://github.com/Viqto0r/zames_pro/compare/v2.58.0...v2.59.0
 [2.58.0]: https://github.com/Viqto0r/zames_pro/compare/v2.57.1...v2.58.0

package/README.md

@@ -1,13 +1,20 @@
-# zames_pro
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Viqto0r/zames_pro/master/logo-small.jpg" alt="zames logo" width="180">
+</p>
 
-[![npm version](https://img.shields.io/npm/v/zames_pro.svg)](https://www.npmjs.com/package/zames_pro)
-[![npm downloads](https://img.shields.io/npm/dm/zames_pro.svg)](https://www.npmjs.com/package/zames_pro)
-[![tests](https://github.com/Viqto0r/zames_pro/actions/workflows/test.yml/badge.svg)](https://github.com/Viqto0r/zames_pro/actions/workflows/test.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](package.json)
-[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+<h1 align="center">zames_pro</h1>
 
-![zames logo](https://raw.githubusercontent.com/Viqto0r/zames_pro/master/logo.jpg)
+<p align="center">
+  <strong>A terminal coding agent that drives chat.deepseek.com through Playwright — no API key required.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/zames_pro"><img src="https://img.shields.io/npm/v/zames_pro.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/zames_pro"><img src="https://img.shields.io/npm/dm/zames_pro.svg" alt="npm downloads"></a>
+  <a href="https://github.com/Viqto0r/zames_pro/actions/workflows/test.yml"><img src="https://github.com/Viqto0r/zames_pro/actions/workflows/test.yml/badge.svg" alt="tests"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="package.json"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg" alt="Node.js"></a>
+</p>
 
 A terminal coding agent that works on top of [chat.deepseek.com](https://chat.deepseek.com/) through Playwright.
 In spirit it is similar to Claude Code / Codex CLI: it starts in the current
@@ -16,6 +23,44 @@ directory, reads and edits files, runs commands, and commits to git.
 > No API key required — it drives the DeepSeek web chat like a regular user
 > through a real (headless) browser.
 
+## How it works
+
+zames does not call the model API. It launches a headless Chromium with a
+persistent profile, signs in to `chat.deepseek.com` like a human, types the task
+into the chat box, and reads the answer back.
+
+```
+ terminal (you)                 zames                          chat.deepseek.com
+ ───────────────                ─────                          ─────────────────
+   task ──────────────────────▶ system prompt + task ────────▶  browser types it
+                                       ▲                              │
+                                       │                        model answers
+                                       │                              │
+   answer  ◀──── render ◀─────  parse tool-call  ◀──── raw answer ◀────┘
+                                       │
+                                       ▼
+                         run tool (Read/Edit/Bash/…) → feed result back
+```
+
+Key pieces:
+
+- **The answer is read from the raw network stream** (SSE), not the rendered
+  DOM, so tool-call JSON with template strings and escapes survives intact.
+- **A persistent profile** (`~/.zames/profile`) keeps you signed in; the
+  headless User-Agent is patched so DeepSeek's CDN does not 403 the login.
+- **A send throttle** (15 s by default) keeps the web chat's rate limit happy
+  during long tool-heavy runs.
+- **The agent is sandboxed** to the directory it was started in — no tool can
+  read or write above it.
+
+## Table of contents
+
+- [Features](#features) · [Why zames?](#why-zames) · [Requirements](#requirements)
+- [How it works](#how-it-works) · [Installation](#installation) · [Signing in](#signing-in) · [Usage](#usage)
+- [Tools](#tools) · [Slash commands](#slash-commands)
+- [Project context, skills and memory](#project-context-skills-and-memory) · [MCP (external tools)](#mcp-external-tools) · [Configuration](#configuration)
+- [FAQ](#faq) · [Links](#links) · [License](#license)
+
 ## Features
 
 - **Tools like Claude Code / Codex** — `Read`, `Write`, `Edit`, `Bash`,
@@ -29,8 +74,6 @@ directory, reads and edits files, runs commands, and commits to git.
   custom commands from the repo and `~/.zames`, the same idea as Codex / Claude
   Code.
 - **MCP support** — plug in external tool servers (e.g. `@playwright/mcp`).
-- **Self-review** — `/self-review` snapshots `src/` so the agent can review and
-  fix itself in a sandbox (`/self-fix`, `/self-apply`).
 - **Scheduling** — `/loop`, `/cron` and `/jobs` repeat tasks on a timer.
 - **Bilingual UI** — Russian / English (`/config lang`).
 
@@ -47,7 +90,7 @@ directory, reads and edits files, runs commands, and commits to git.
 
 ## Requirements
 
-- Node.js >= 20 (CI and development use Node 24; see `.nvmrc`)
+- Node.js >= 20
 - A DeepSeek account. On first launch zames asks for your DeepSeek
   login/password in the terminal (and stores them in `~/.zames/config.json`
   after a successful sign-in, so a later logout is handled automatically
@@ -85,13 +128,6 @@ version). You do not need `--headed` just to log in.
 Credentials and toggles can also be edited from `/config`
 (`browser.auth.username`, `browser.auth.password`, `browser.auth.saveSession`).
 
-## Links
-
-- npm: <https://www.npmjs.com/package/zames_pro>
-- Changelog: [`CHANGELOG.md`](CHANGELOG.md)
-- Contributing: [`CONTRIBUTING.md`](CONTRIBUTING.md)
-- Security policy: [`SECURITY.md`](SECURITY.md)
-
 ## Installation
 
 ```bash
@@ -247,10 +283,6 @@ Codex CLI:
   instead of the whole list.
 - /review [focus] [--staged] — ask the agent to review uncommitted changes
   and report findings (no code changes).
-- /improve [id] — self-improvement loop: take the next open item from
-  `BACKLOG.md` (or a specific id, e.g. `/improve B3`), implement it, run the
-  typecheck/lint/tests, mark it done and add a CHANGELOG entry. Nothing is
-  committed — the changes stay in the working tree for review.
 - /plan [on|off] — plan (read-only) mode. While it is on, the mutating tools
   (Write/Edit/MultiEdit/ApplyPatch/Bash, GitAdd/GitCommit/GitPush) are removed
   from the tool set, so the agent can investigate without touching the tree.
@@ -384,7 +416,7 @@ Changes are written to the project `.zamesrc.json` and applied right away
 (help, messages, spinner) and the language the agent answers you in. The
 locale lives in `ui.locale` in the config file.
 
-Agent data is stored in `~/.zames`: browser profile, logs, undo history, self-review snapshots.
+Agent data is stored in `~/.zames`: browser profile, logs, undo history, sessions.
 
 ## FAQ
 
@@ -414,6 +446,15 @@ Same shape (tools, `AGENTS.md`, skills, MCP, slash commands) but it runs on your
 DeepSeek account instead of an API, as a browser automation rather than a
 first-party API client.
 
+## Links
+
+- **npm:** <https://www.npmjs.com/package/zames_pro>
+- **GitHub:** <https://github.com/Viqto0r/zames_pro>
+- **Changelog:** [`CHANGELOG.md`](CHANGELOG.md)
+- **Contributing:** [`CONTRIBUTING.md`](CONTRIBUTING.md)
+- **Security policy:** [`SECURITY.md`](SECURITY.md)
+- **Code of conduct:** [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)
+
 ## License
 
 MIT

package/dist/agent-loop.js

@@ -6,12 +6,15 @@ import { translate } from './i18n.js';
 import { substituteAttachmentMarkers } from './commands.js';
 import { normText } from './browser.js';
 import { loadHooks, runPreToolUse, runPostToolUse, } from './hooks.js';
-export async function runAgentLoop({ browser, tools, task, workdir, maxIterations = 0, freshChat = false, sendSystemPrompt = false, transcript = null, attachments = [], onThinking = () => { }, onSendPause = () => { }, onSendState = () => { }, onNotice = () => { }, onAssistantThought = () => { }, onToolCall = () => { }, onToolResult = () => { }, onAssistantMessage = () => { }, onChatReady = () => { }, onWarning = () => { }, debugLog = false, locale = 'ru', askDeadlineMs = 240_000, maxAfterToolRetries = 6, onAutoCompact = null, autoCompactPct = 95, contextLimit = 1_000_000, getTokenUsage = null, hooks = undefined, }) {
+import { loadPermissions, decidePermission, } from './permissions.js';
+export async function runAgentLoop({ browser, tools, task, workdir, maxIterations = 0, freshChat = false, sendSystemPrompt = false, transcript = null, attachments = [], onThinking = () => { }, onSendPause = () => { }, onSendState = () => { }, onNotice = () => { }, onAssistantThought = () => { }, onToolCall = () => { }, onToolResult = () => { }, onAssistantMessage = () => { }, onChatReady = () => { }, onWarning = () => { }, debugLog = false, locale = 'ru', askDeadlineMs = 240_000, maxAfterToolRetries = 6, onAutoCompact = null, autoCompactPct = 95, contextLimit = 1_000_000, getTokenUsage = null, hooks = undefined, permissions = undefined, onAskPermission = undefined, selfImprovement = false, }) {
     // Resolve the hook config ONCE per task: a read per tool call would be
     // wasteful, and a mid-task edit of hooks.json is not something to chase.
     // `undefined` means "read .zames/hooks.json"; an explicit null disables
     // hooks entirely.
     const hookConfig = hooks === undefined ? loadHooks(workdir) : (hooks ?? {});
+    // Same for the approval policy (C1): read `.zames/permissions.json` once.
+    const permissionPolicy = permissions === undefined ? loadPermissions(workdir) : permissions;
     // UI callbacks must NEVER break the agent loop. A rendering error (a huge
     // tool result, a broken markdown frame, a closed terminal) used to throw
     // out of the loop right after a tool call — the session looked "stopped
@@ -91,7 +94,9 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
         }
         let context;
         try {
-            context = await loadProjectContext(workdir);
+            // Pass the task text so nested AGENTS.md/MEMORY.md for the directories
+            // this task actually touches are pulled in (B6, path-scoped rules).
+            context = await loadProjectContext(workdir, [task]);
         }
         catch {
             context = null;
@@ -102,11 +107,13 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
             gitContext: gitText,
             locale,
             context,
+            selfImprovement,
         });
         transcript?.log('system_prompt', {
             length: systemPrompt.length,
             gitContext: gitText,
             agents: context?.agents.map((f) => f.path) ?? [],
+            scopedAgents: context?.scopedAgents?.map((f) => f.path) ?? [],
             memory: context?.memory.map((f) => f.path) ?? [],
             skills: context?.skills.map((s) => s.name) ?? [],
             commands: context?.commands.map((c) => c.name) ?? [],
@@ -726,6 +733,47 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
                 results.push({ tool: call.tool, result: blocked });
                 continue;
             }
+            // Approval policy (C1): a `deny` rule blocks the call (like a PreToolUse
+            // denial); an `ask` rule prompts the operator. Hooks stay authoritative
+            // for programmatic guards — this is the human-in-the-loop layer.
+            const decision = decidePermission(permissionPolicy, call.tool, call.args);
+            if (decision.action === 'deny') {
+                const blocked = `Blocked by permission policy: ${decision.reason}`;
+                transcript?.log('permission_deny', {
+                    tool: call.tool,
+                    reason: decision.reason,
+                });
+                safeToolResult(blocked);
+                transcript?.log('tool_result', {
+                    tool: call.tool,
+                    result: blocked,
+                });
+                results.push({ tool: call.tool, result: blocked });
+                continue;
+            }
+            if (decision.action === 'ask' && onAskPermission) {
+                let allowed;
+                try {
+                    allowed = await onAskPermission({ ...decision, tool: call.tool });
+                }
+                catch {
+                    allowed = false;
+                }
+                if (!allowed) {
+                    const blocked = `Denied by operator: ${decision.reason}`;
+                    transcript?.log('permission_denied', {
+                        tool: call.tool,
+                        reason: decision.reason,
+                    });
+                    safeToolResult(blocked);
+                    transcript?.log('tool_result', {
+                        tool: call.tool,
+                        result: blocked,
+                    });
+                    results.push({ tool: call.tool, result: blocked });
+                    continue;
+                }
+            }
             let result;
             // While the tool runs, poll for an Esc/Ctrl+C: the abort flag is a plain
             // boolean set by stopGeneration(), so the only way to turn it into a
@@ -734,6 +782,9 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
             const poll = setInterval(syncToolAbort, 100);
             if (typeof poll.unref === 'function')
                 poll.unref();
+            // Time the tool (T-D3): the transcript carries durationMs so /cost can
+            // show where the time goes (frequent Read→Edit cycles vs slow Bash).
+            const toolStart = Date.now();
             try {
                 result = await tool.fn(call.args, { signal: toolAbort.signal });
             }
@@ -743,6 +794,7 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
             finally {
                 clearInterval(poll);
             }
+            const toolMs = Date.now() - toolStart;
             // PostToolUse hooks run AFTER the tool; their stdout is appended to the
             // result (e.g. `prettier` output) before it is fed back to the model.
             // Best-effort: a hook failure is ignored, the tool result still stands.
@@ -758,6 +810,7 @@ ${post}`;
             transcript?.log('tool_result', {
                 tool: call.tool,
                 result: String(result),
+                durationMs: toolMs,
             });
             results.push({ tool: call.tool, result });
             // The operator pressed Esc/Ctrl+C while the tool was running. The tool

package/dist/backlog.js

@@ -0,0 +1,166 @@
+import { parseBacklogItems } from './commands.js';
+// BACKLOG.md maintenance — the pure half of /backlog and the automatic pruning
+// that runs after /improve. BACKLOG.md is the agent's own improvement-notes
+// file (gitignored); it is READ by /improve, so keeping it small matters —
+// every finished item used to keep a full copy of its original text inside a
+// <details> block, and the file grew without bound.
+//
+// Everything here is pure and unit-tested; index.ts only reads/writes the file.
+const NL = String.fromCharCode(10);
+// Agent-appended items use this id prefix. A distinct letter keeps them apart
+// from the hand-numbered A/B/C/D/E entries, so it is obvious which notes the
+// agent added on its own.
+const NEW_ITEM_PREFIX = 'N';
+// Past these thresholds BACKLOG.md costs more tokens (on /improve) than it is
+// worth, so the operator is nudged to collapse it.
+export const BACKLOG_WARN_LINES = 500;
+export const BACKLOG_WARN_CHARS = 60_000;
+function squashBlankLines(lines) {
+    const out = [];
+    let blanks = 0;
+    for (const line of lines) {
+        if (line.trim() === '') {
+            blanks++;
+            if (blanks > 2)
+                continue;
+        }
+        else {
+            blanks = 0;
+        }
+        out.push(line);
+    }
+    return out;
+}
+// A real, kept heading: a `## P<n>` section or a `### X<n>.` item heading that
+// is NOT the archived copy (archived copies carry `~~` right after the id).
+function isRealBoundary(line) {
+    const t = line.trim();
+    if (/^##\s/.test(t))
+        return true;
+    return /^###\s+[A-Z]\d+[.]/.test(t) && !/^###\s+[A-Z]\d+[.]\s+~~/.test(t);
+}
+function isDetailsOpen(line) {
+    return line.trim().startsWith('<details');
+}
+function isArchivedHeading(line) {
+    return /^###\s+[A-Z]\d+[.]\s+~~/.test(line.trim());
+}
+/**
+ * Remove archived copies of finished items. A finished item keeps its
+ * `### X. [x] ... done` summary line; the `### X. ~~original~~` copy and its
+ * body (normally wrapped in a <details> block) are dropped.
+ *
+ * Deliberately tolerant of an UNCLOSED <details>: a real backlog item was
+ * written as `### A1. [x] ...` then `<details>...` with no `</details>`, so the
+ * whole file became one nested block. Keying the end of a block on the next
+ * REAL heading (a `### X.` without `~~`, or a `## ` section) — not only on
+ * `</details>` — keeps the summary lines and the open items even then. Pure and
+ * unit-tested; a heading that looks like an item INSIDE an archive is skipped
+ * because it carries `~~`.
+ */
+export function collapseBacklog(text) {
+    const src = String(text ?? '');
+    const lines = src.split(NL);
+    const out = [];
+    let collapsed = 0;
+    let i = 0;
+    while (i < lines.length) {
+        if (isDetailsOpen(lines[i]) || isArchivedHeading(lines[i])) {
+            // Skip to the end of the archive: the first `</details>` OR the first
+            // real heading, whichever comes first (see the note above).
+            let j = i + 1;
+            while (j < lines.length) {
+                const t = lines[j].trim();
+                if (t.startsWith('</details>')) {
+                    j++;
+                    break;
+                }
+                if (isRealBoundary(t))
+                    break;
+                j++;
+            }
+            collapsed++;
+            i = j;
+            continue;
+        }
+        out.push(lines[i]);
+        i++;
+    }
+    const next = squashBlankLines(out).join(NL);
+    return { text: next, changed: next !== src, collapsed };
+}
+export function backlogStats(text) {
+    const src = String(text ?? '');
+    const items = parseBacklogItems(src);
+    let archived = 0;
+    for (const line of src.split(NL)) {
+        if (line.trim().startsWith('<details'))
+            archived++;
+    }
+    return {
+        lines: src.split(NL).length,
+        chars: src.length,
+        open: items.filter((i) => i.status === 'open').length,
+        done: items.filter((i) => i.status === 'done').length,
+        archived,
+    };
+}
+/** True when the file is big enough to deserve a collapse nudge. */
+export function backlogNeedsPruning(stats) {
+    return stats.lines > BACKLOG_WARN_LINES || stats.chars > BACKLOG_WARN_CHARS;
+}
+/** The next free N<n> id not yet used in the file. */
+export function nextBacklogId(text) {
+    let max = 0;
+    const re = /^###[ ]+([A-Z])([0-9]+)[.]/gm;
+    let m;
+    while ((m = re.exec(String(text ?? '')))) {
+        if (m[1] === NEW_ITEM_PREFIX)
+            max = Math.max(max, Number(m[2]));
+    }
+    return NEW_ITEM_PREFIX + (max + 1);
+}
+/**
+ * Insert a new OPEN item under the matching `## P<n>` section (or append a new
+ * section at the end). Returns the new file text and the generated id. Pure;
+ * the caller writes the file.
+ */
+export function appendBacklogItem(text, item) {
+    const src = String(text ?? '');
+    const title = String(item.title ?? '')
+        .trim()
+        .replace(/ {2,}/g, ' ');
+    const prio = /^P[0-3]$/i.test(String(item.priority ?? '').trim())
+        ? String(item.priority).trim().toUpperCase()
+        : 'P2';
+    const note = String(item.note ?? '').trim();
+    const id = nextBacklogId(src);
+    const entry = ['### ' + id + '. ' + title, ''];
+    if (note) {
+        for (const l of note.split(NL))
+            entry.push(l);
+        entry.push('');
+    }
+    const lines = src.split(NL);
+    const headerRe = new RegExp('^##[ ]+' + prio + '(?![0-9])');
+    let at = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (headerRe.test(lines[i])) {
+            // Insert right after the header and any blank lines that follow it, so
+            // the newest note sits at the top of its priority block.
+            let j = i + 1;
+            while (j < lines.length && lines[j].trim() === '')
+                j++;
+            at = j;
+            break;
+        }
+    }
+    if (at === -1) {
+        while (lines.length && lines[lines.length - 1].trim() === '')
+            lines.pop();
+        const out = lines.concat(['', '## ' + prio, '', ...entry]).join(NL);
+        return { text: out, id };
+    }
+    const out = lines.slice(0, at).concat(entry, lines.slice(at)).join(NL);
+    return { text: out, id };
+}