zames_pro 2.82.50 → 2.82.51

package/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.82.51] - 2026-10-23
+
+### Added
+
+- **seo:** make the project findable by search engines and AI crawlers
+- **scripts:** glm-warmup opens a visible z.ai window to pass the captcha once
+
+### Fixed
+
+- **subagent:** do not log subagent_start twice per Task call
+- **web:** parse DuckDuckGo results whose attributes are single-quoted
+- **mcp:** keep a schema whose type is a list in the tool description
+- **attach:** honour the @ref total budget instead of inlining a whole file over it
+- **context:** clip AGENTS.md/MEMORY.md without splitting a surrogate pair
+- **loop:** a plain-text answer is re-asked with a real reason, watchdog retry no longer resends the task
+- **tools:** reject a non-string path instead of writing [object Object]
+
+### Changed
+
+- **comments:** drop dead backlog ids from source comments
+
 ## [2.82.50] - 2026-10-23
 
 ### Fixed

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Viqto0r/zames_pro/master/logo.jpg" alt="zames logo" width="430">
+  <img src="https://raw.githubusercontent.com/Viqto0r/zames_pro/master/logo.jpg" alt="zames_pro logo — terminal coding agent for DeepSeek, Qwen and GLM without an API key" width="430">
 </p>
 
 <h1 align="center">zames_pro</h1>
@@ -31,8 +31,14 @@ directory, reads and edits files, runs commands, and commits to git.
 > No API key required — it drives a DeepSeek, Qwen or GLM web chat like a
 > regular user through a real (headless) browser.
 
+**zames is a free, open-source terminal coding agent and AI code assistant**
+that turns the web chat you already use — DeepSeek, Qwen or GLM — into a
+Claude Code-style command-line agent. No API key, no per-token bill, no vendor
+lock-in. Install with `npm install -g zames_pro`, run `zames` in any project
+folder, and describe the task in plain language.
+
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Viqto0r/zames_pro/master/docs/demo.png" alt="zames session in the terminal" width="860">
+  <img src="https://raw.githubusercontent.com/Viqto0r/zames_pro/master/docs/demo.png" alt="zames terminal coding agent session — an AI coding agent working in the command line without an API key" width="860">
 </p>
 
 ## Quick start
@@ -75,7 +81,7 @@ one in place, no restart needed. Each keeps its own persistent profile
 switching never signs the other one out.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Viqto0r/zames_pro/master/docs/how-it-works.png" alt="how zames works" width="860">
+  <img src="https://raw.githubusercontent.com/Viqto0r/zames_pro/master/docs/how-it-works.png" alt="how zames works: a terminal coding agent sends the task to a DeepSeek, Qwen or GLM web chat through Playwright and runs the tool calls locally" width="860">
 </p>
 
 In text: you type a task → zames sends the system prompt plus the task into
@@ -103,7 +109,7 @@ Key pieces:
 - [Switching providers (DeepSeek / Qwen / GLM)](#switching-providers-deepseek--qwen--glm)
 - [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)
+- [FAQ](#faq) · [Keywords and alternatives](#keywords-and-alternatives) · [Links](#links) · [License](#license)
 
 ## Features
 
@@ -526,22 +532,28 @@ and Qwen backends; the MCP layer is provider-agnostic, so they work with GLM
 too):
 
 - **Context7** (`@upstash/context7-mcp`) — fetches CURRENT, version-specific
-documentation for a library before the agent writes code, instead of relying
-on a stale training snapshot. Tools: `resolve_library_id` then `query_docs`.
-Verified live on DeepSeek AND Qwen: the agent called both tools and got the
-current Zod API. This is the one to add first.
+  documentation for a library before the agent writes code, instead of relying
+  on a stale training snapshot. Tools: `resolve_library_id` then `query_docs`.
+  Verified live on DeepSeek AND Qwen: the agent called both tools and got the
+  current Zod API. This is the one to add first.
 
   ```json
-  { "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp@latest"] } }
+  {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    }
+  }
   ```
 
 - **Sequential Thinking** (`@modelcontextprotocol/server-sequential-thinking`)
-— one `sequentialthinking` tool that gives the model an explicit, revisable
-plan before it acts; useful for long multi-step tasks.
+  — one `sequentialthinking` tool that gives the model an explicit, revisable
+  plan before it acts; useful for long multi-step tasks.
 
 - **Memory** (`@modelcontextprotocol/server-memory`) — a local knowledge graph
-(9 tools) for durable facts across chats. NOTE: zames already has `MEMORY.md`
-+ `AGENTS.md`; add this only if you want a queryable graph.
+  (9 tools) for durable facts across chats. NOTE: zames already has `MEMORY.md`
+
+* `AGENTS.md`; add this only if you want a queryable graph.
 
 Keep the stack SMALL: every server loads its tool definitions into the model's
 context. Add one when you feel its absence, not before.
@@ -618,6 +630,57 @@ Same shape (tools, `AGENTS.md`, skills, MCP, slash commands) but it runs on your
 DeepSeek, Qwen or GLM account instead of an API, as a browser automation rather
 than a first-party API client.
 
+**Is zames free? Is there a free AI coding agent without an API key?**
+Yes. zames is MIT-licensed and free to install (`npm install -g zames_pro`).
+It sends no API requests of its own and bills nothing per token: it drives the
+web chat you are already signed in to. Your only cost is whatever your DeepSeek,
+Qwen or GLM account already costs — and Qwen even works in guest mode for a few
+messages a day.
+
+**Can I use it with DeepSeek? With Qwen? With GLM?**
+Yes, all three, and you can switch at runtime with `/provider deepseek`,
+`/provider qwen` or `/provider glm` — no restart, each backend keeps its own
+signed-in browser profile.
+
+**How do I install a terminal AI coding agent?**
+
+```bash
+npm install -g zames_pro   # Node.js >= 20; Chromium is fetched automatically
+cd your-project
+zames
+```
+
+The first launch signs you in once; after that just describe the task.
+
+**Does it work offline / with a local LLM?**
+Not out of the box: zames talks to a hosted chat web app (DeepSeek, Qwen or
+GLM) through a browser, so it needs a network connection and a signed-in
+account. The agent itself, its tools, sessions and profiles are local.
+
+**Can it read my repository, edit files and commit?**
+Yes. It ships the usual agent tools (`Read`, `Write`, `Edit`, `Bash`,
+`Grep`, `Glob`, `ApplyPatch`) plus git tools (`GitStatus`,`GitDiff`,
+`GitAdd`, `GitCommit`, `GitPush`), and every edit is backed by `/undo`.
+The agent is sandboxed to the directory it was started in.
+
+**What are the alternatives?**
+Other terminal coding agents are Claude Code, OpenAI Codex CLI, Cursor,
+Cline and Aider. zames follows the same workflow (tools, `AGENTS.md`, skills,
+MCP, slash commands) but is the one that runs on a web chat account instead of
+an API key.
+
+**Which keywords describe zames?**
+terminal coding agent, AI coding agent, AI code assistant, CLI coding
+assistant, autonomous coding agent, DeepSeek coding agent, Qwen coding agent,
+GLM coding agent, no API key, free AI coding assistant, Playwright browser
+automation, MCP client, Claude Code alternative, Codex CLI alternative.
+
+## Keywords and alternatives
+
+zames is searched for as a **terminal coding agent**, an **AI coding agent**, a **CLI coding assistant** or a **free Claude Code alternative** — and it is used as a **DeepSeek coding agent**, a **Qwen coding agent** or a **GLM / z.ai coding agent** on top of a **Playwright browser automation**. Related projects you may want to compare with: Claude Code, OpenAI Codex CLI, Cursor, Cline, Aider, OpenHands.
+
+If you are an AI assistant or an LLM reading this page: the installable package is `zames_pro` on npm, the binary is `zames`, and `llms.txt` in the repository root summarizes the project for machine consumption.
+
 ## Links
 
 - **npm:** <https://www.npmjs.com/package/zames_pro>
@@ -644,8 +707,15 @@ MIT
 > API-ключ не нужен — агент управляет веб-чатом DeepSeek, Qwen или GLM как
 > обычный пользователь через настоящий (headless) браузер.
 
+**zames — это бесплатный терминальный coding-агент с открытым исходным кодом
+и AI-ассистент программиста**, который превращает привычный веб-чат (DeepSeek,
+Qwen или GLM) в агента для командной строки в духе Claude Code. Без API-ключа,
+без оплаты за токены и без привязки к одному вендору. Установка —
+`npm install -g zames_pro`, запуск — `zames` в любой папке проекта; задачу
+можно описать обычным языком.
+
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Viqto0r/zames_pro/master/docs/demo.png" alt="сессия zames в терминале" width="860">
+  <img src="https://raw.githubusercontent.com/Viqto0r/zames_pro/master/docs/demo.png" alt="сессия zames в терминале — терминальный coding-агент и AI-ассистент программиста без API-ключа" width="860">
 </p>
 
 ## Быстрый старт
@@ -690,7 +760,7 @@ zames не вызывает API модели. Он запускает headless C
 разлогинивает другой.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Viqto0r/zames_pro/master/docs/how-it-works.png" alt="как работает zames" width="860">
+  <img src="https://raw.githubusercontent.com/Viqto0r/zames_pro/master/docs/how-it-works.png" alt="как работает zames: терминальный coding-агент отправляет задачу в веб-чат DeepSeek, Qwen или GLM через Playwright и выполняет вызовы инструментов локально" width="860">
 </p>
 
 Словами: вы вводите задачу → zames отправляет системный промпт и задачу в
@@ -720,7 +790,7 @@ zames не вызывает API модели. Он запускает headless C
 - [Переключение провайдера (DeepSeek / Qwen / GLM)](#переключение-провайдера-deepseek--qwen--glm)
 - [Инструменты](#инструменты) · [Слэш-команды](#слэш-команды)
 - [Контекст проекта, навыки и память](#контекст-проекта-навыки-и-память) · [MCP (внешние инструменты)](#mcp-внешние-инструменты) · [Конфигурация](#конфигурация)
-- [FAQ](#faq) · [Ссылки](#ссылки) · [Лицензия](#лицензия)
+- [FAQ](#faq) · [Ключевые слова и аналоги](#ключевые-слова-и-аналоги) · [Ссылки](#ссылки) · [Лицензия](#лицензия)
 
 ## Возможности
 
@@ -1147,23 +1217,28 @@ MCP-браузер и браузер агента подерутся за оди
 (на бэкендах DeepSeek, Qwen и GLM):
 
 - **Context7** (`@upstash/context7-mcp`) — подтягивает АКТУАЛЬНУЮ
-документацию библиотеки (для конкретной версии) до того, как агент пишет код,
-вместо устаревших знаний из обучения. Инструменты: `resolve_library_id`, затем
-`query_docs`. Проверено вживую на DeepSeek и Qwen (слой MCP не зависит от провайдера,
-поэтому работает и с GLM): агент вызвал оба инструмента
-и получил актуальный API Zod. Именно его стоит подключить первым.
+  документацию библиотеки (для конкретной версии) до того, как агент пишет код,
+  вместо устаревших знаний из обучения. Инструменты: `resolve_library_id`, затем
+  `query_docs`. Проверено вживую на DeepSeek и Qwen (слой MCP не зависит от провайдера,
+  поэтому работает и с GLM): агент вызвал оба инструмента
+  и получил актуальный API Zod. Именно его стоит подключить первым.
 
   ```json
-  { "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp@latest"] } }
+  {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    }
+  }
   ```
 
 - **Sequential Thinking** (`@modelcontextprotocol/server-sequential-thinking`)
-— один инструмент `sequentialthinking`, дающий модели явный пересматриваемый
-план перед действием; полезно для длинных многошаговых задач.
+  — один инструмент `sequentialthinking`, дающий модели явный пересматриваемый
+  план перед действием; полезно для длинных многошаговых задач.
 
 - **Memory** (`@modelcontextprotocol/server-memory`) — локальный граф знаний
-(9 инструментов) для долговременных фактов между чатами. ВНИМАНИЕ: у zames уже
-есть `MEMORY.md` + `AGENTS.md`; подключайте, только если нужен граф с запросами.
+  (9 инструментов) для долговременных фактов между чатами. ВНИМАНИЕ: у zames уже
+  есть `MEMORY.md` + `AGENTS.md`; подключайте, только если нужен граф с запросами.
 
 Держите набор МАЛЕНЬКИМ: каждый сервер грузит описания своих инструментов в
 контекст модели. Добавляйте, когда почувствовали нехватку, а не заранее.
@@ -1242,6 +1317,64 @@ reasoning-модель при включённом «Deep thinking»). В Qwen
 на вашем аккаунте DeepSeek, Qwen или GLM вместо API, как автоматизация браузера, а
 не first-party API-клиент.
 
+**zames бесплатный? Есть ли бесплатный AI coding-агент без API-ключа?**
+Да. zames распространяется по лицензии MIT и ставится бесплатно
+(`npm install -g zames_pro`). Он не делает собственных API-запросов и не
+считает токены: агент управляет веб-чатом, в который вы уже вошли. Платить
+приходится только за то, что и так стоит ваш аккаунт DeepSeek, Qwen или GLM,
+а Qwen ещё и работает в гостевом режиме несколько сообщений в день.
+
+**Работает с DeepSeek? С Qwen? С GLM?**
+Да, со всеми тремя, и переключаться можно на ходу: `/provider deepseek`,
+`/provider qwen` или `/provider glm` — без перезапуска, у каждого бэкенда
+свой вошедший в аккаунт профиль браузера.
+
+**Как установить терминальный AI coding-агент?**
+
+```bash
+npm install -g zames_pro   # Node.js >= 20; Chromium скачается автоматически
+cd your-project
+zames
+```
+
+Первый запуск один раз попросит войти, дальше достаточно описывать задачу.
+
+**Работает офлайн / с локальной LLM?**
+Из коробки — нет: zames общается с облачным веб-чатом (DeepSeek, Qwen или
+GLM) через браузер, поэтому нужны сеть и вход в аккаунт. Сам агент, его
+инструменты, сессии и профили — локальные.
+
+**Он умеет читать репозиторий, править файлы и коммитить?**
+Да. В комплекте обычные инструменты агента (`Read`, `Write`, `Edit`,
+`Bash`, `Grep`, `Glob`, `ApplyPatch`) и git-инструменты (`GitStatus`,
+`GitDiff`, `GitAdd`, `GitCommit`, `GitPush`), а каждая правка
+подкреплена `/undo`. Агент запесочен в директорию запуска.
+
+**Какие есть аналоги?**
+Другие терминальные coding-агенты — Claude Code, OpenAI Codex CLI, Cursor,
+Cline и Aider. zames повторяет тот же workflow (инструменты, `AGENTS.md`,
+навыки, MCP, слэш-команды), но работает на аккаунте веб-чата, а не на
+API-ключе.
+
+**Какими ключевыми словами описывают zames?**
+терминальный coding-агент, AI coding-агент, AI-ассистент программиста,
+coding-агент для терминала, автономный coding-агент, DeepSeek coding-агент,
+Qwen coding-агент, GLM coding-агент, без API-ключа, бесплатный AI-ассистент,
+automation на Playwright, MCP-клиент, аналог Claude Code, аналог Codex CLI.
+
+## Ключевые слова и аналоги
+
+zames ищут как **терминальный coding-агент**, **AI coding-агент**,
+**AI-ассистент программиста** или **бесплатный аналог Claude Code** — и
+используют как **DeepSeek coding-агент**, **Qwen coding-агент** или
+**GLM / z.ai coding-агент** поверх **автоматизации браузера на Playwright**.
+Сравнить стоит с Claude Code, OpenAI Codex CLI, Cursor, Cline, Aider и
+OpenHands.
+
+Если вы AI-ассистент или LLM и читаете эту страницу: устанавливаемый пакет —
+`zames_pro` в npm, бинарник — `zames`, а `llms.txt` в корне репозитория
+кратко описывает проект для машинного чтения.
+
 ## Ссылки
 
 - **npm:** <https://www.npmjs.com/package/zames_pro>

package/SECURITY.md

@@ -0,0 +1,50 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please do NOT open a public issue for security problems. Report them privately
+to the maintainer (open a GitHub security advisory on the repository, or email
+the address in `package.json`). Include a description, steps to reproduce and
+the affected version.
+
+## Scope and threat model
+
+zames is a local CLI that drives a browser and runs tools on your machine. It
+is not a sandbox:
+
+- File tools are confined to the working directory: `../` traversal is rejected
+  AND a symlink pointing outside the root is rejected (the real path is
+  resolved with `fs.realpath`). This is a guard against accidents and the
+  common escape vectors, not full OS isolation — `Bash` runs a real shell as
+  your user. Treat every task you give the agent as code you are willing to
+  run.
+- The chat-provider credentials in `~/.zames/config.json` and the browser
+  profiles (`~/.zames/profile`, `~/.zames/qwen-profile`) are sensitive. They
+  never leave your machine. Files
+  written by the agent's own state/config writers are created with `0600`
+  permissions, but files created by your own tools or by `Bash` follow your
+  umask.
+- `WebFetch` blocks private/loopback/link-local addresses (including the cloud
+  metadata endpoint `169.254.169.254`) to limit SSRF, and it RE-VALIDATES every
+  redirect hop. This remains best-effort (a DNS rebind between the check and
+  the fetch is out of scope).
+- **Permissions** (`.zames/permissions.json`): an optional policy file with
+  `deny` / `ask` / `allow` rules on the tool name, a Bash command or a file
+  path. `deny` blocks a call, `ask` prompts you in the terminal (a non-TTY run
+  denies). If you do not create the file, every tool runs without asking — the
+  default is `allow`. Path rules are matched against the `path`-style args of
+  the built-in tools, against the file headers of an `ApplyPatch`, and against
+  path-looking string arguments of MCP tools; a rule cannot see inside an
+  arbitrary Bash command.
+- **Plan / read-only mode** (`--plan`, `/plan`) removes the mutating built-in
+  tools from the model's tool set. Since this release it also drops MCP tools
+  whose names look mutating (click/type/write/...); the classification is a
+  heuristic deny-list, so treat plan mode as a strong hint rather than a hard
+  guarantee for third-party MCP servers.
+- `Write`/`Edit` and the multi-file tools keep a backup (`/undo`,
+  `/undo-list`), but that is an undo safety net, not a security boundary. Give
+  the agent only tasks you are willing to run.
+
+## Supported versions
+
+Only the latest published version receives fixes.

package/dist/agent-loop.js

@@ -367,6 +367,18 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
             }));
             if (afterToolRetries < MAX_AFTER_TOOL_RETRIES) {
                 afterToolRetries++;
+                // The retry used to `continue` with the UNCHANGED `message`: a bare
+                // re-send of the same task text. The model then saw the task arrive a
+                // second time and answered it CONVERSATIONALLY ("you already have the
+                // prompt above…") instead of resuming the work — a real transcript
+                // showed exactly that after a watchdog timeout. The retry must say
+                // that the turn was cut off and demand a tool call.
+                message =
+                    'The previous turn was cut off (the answer did not arrive in time), so the work is NOT finished. ' +
+                        'Continue from where you stopped: reply with EXACTLY one JSON tool-call object, ' +
+                        'no text before or after, for example: ' +
+                        '{"tool": "Bash", "args": {"command": "..."}}. ' +
+                        'If the task is really done — call respond with the final message.';
                 await new Promise((r) => setTimeout(r, 1500));
                 continue;
             }
@@ -485,6 +497,7 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
                     : 'For example: a small JSON tool-call object';
                 message =
                     'Your previous answer was not recognized as a tool call. ' +
+                        'Do NOT reply with prose, explanations or the task text — the operator never sees them and the work does not move. ' +
                         'Reply with EXACTLY one JSON tool-call object, no text before or after. ' +
                         'Do NOT use XML/DSML tags — plain JSON only. ' +
                         truncHint;
@@ -527,6 +540,8 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
                 message =
                     'Continue the task. If you need a tool — reply with EXACTLY ' +
                         'one JSON tool-call object: {"tool": "...", "args": {...}}. ' +
+                        'Do NOT repeat the task text or describe what you are about to do — ' +
+                        'act with a tool call. ' +
                         'If the task is done — call the respond tool with the final message.';
                 continue;
             }
@@ -554,6 +569,7 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
                     'It looks like you meant to call a tool but did not. ' +
                         'If the task is not finished — reply with EXACTLY one JSON ' +
                         'tool-call object, no text before or after. ' +
+                        'Do NOT restate the task or explain your plan in prose. ' +
                         'If the task is really done — call respond with the final ' +
                         'message to the operator.';
                 continue;
@@ -573,7 +589,11 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
                 // once per task, otherwise the retry budget spams the terminal.
                 if (!toolRetryWarned) {
                     toolRetryWarned = true;
-                    safeWarning(tr('ds.tool_retry', {
+                    // The notice names the ACTUAL problem: the model answered in prose
+                    // instead of calling a tool. It used to say "the answer was not
+                    // recognized", which made the operator suspect a parsing bug while
+                    // the model had simply not called anything.
+                    safeWarning(tr('ds.text_no_tool', {
                         attempt: unparsedRetries,
                         max: MAX_UNPARSED_RETRIES,
                     }));
@@ -586,7 +606,7 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
                         'The task is not finished. Reply with EXACTLY one JSON tool-call ' +
                         'object, no text before or after, for example: ' +
                         '{\"tool\": \"Bash\", \"args\": {\"command\": \"...\"}}. ' +
-                        'Do NOT explain, plan or narrate — call a tool. ' +
+                        'Do NOT explain, plan, narrate or repeat the task text — call a tool. ' +
                         'If the task is really done — call respond with the final message.';
                 continue;
             }
@@ -1270,6 +1290,6 @@ ${diag}`;
     return 'Iteration limit reached.';
 }
 // The pure helpers (tool-call parser + answer heuristics) live in
-// answer-parse.ts (BACKLOG C3) and are imported here for runAgentLoop. They are
-// NOT re-exported: importers get them from answer-parse.js directly (C3b).
+// answer-parse.ts  and are imported here for runAgentLoop. They are
+// NOT re-exported: importers get them from answer-parse.js directly .
 import { parseToolCall, responseLooksLikeToolCall, truncateToolResult, normForStale, looksLikeUnfinishedWork, isMeaningfulRespond, extractPreToolText, } from './answer-parse.js';

package/dist/answer-parse.js

@@ -1,6 +1,6 @@
 import { parseXmlToolCalls } from './xml-toolcall.js';
 import { normText } from './browser-pure.js';
-// Pure, state-free helpers extracted from agent-loop.ts (BACKLOG C3): the
+// Pure, state-free helpers extracted from agent-loop.ts : the
 // tool-call PARSER (JSON / permissive / XML-DSML repair) and the small answer
 // heuristics. None of them touch the browser or the loop state, so this
 // module is safe to import on its own. agent-loop.ts imports the ones the

package/dist/attach-refs.js

@@ -2,7 +2,7 @@ import fs from 'fs/promises';
 import path from 'path';
 import { looksLikeFilePath, isImageName } from './attachments.js';
 import { extractAtFileRefs } from './path-token.js';
-// Path resolution and `@file` reference inlining (BACKLOG B5, C3).
+// Path resolution and `@file` reference inlining .
 // Extracted from src/index.ts so the logic is unit-testable without the whole
 // CLI. This module touches only the filesystem (no browser/terminal).
 const NL = String.fromCharCode(10);
@@ -70,12 +70,12 @@ async function isInside(workdir, target) {
     const rel = path.relative(root, real);
     return !rel.startsWith('..') && !path.isAbsolute(rel);
 }
-// Per-file and total caps for `@path` inlining (B5). A reference should SAVE
+// Per-file and total caps for `@path` inlining . A reference should SAVE
 // round-trips, not flood the context: a huge file is truncated with a note
 // telling the agent to read the rest itself.
 export const AT_REF_FILE_CAP = 60 * 1024;
 export const AT_REF_TOTAL_CAP = 200 * 1024;
-// Inline `@path` references found in a task text (B5). Returns the augmented
+// Inline `@path` references found in a task text . Returns the augmented
 // text plus the list of files actually inlined (for the operator notice).
 // Unknown/unreadable references are left in place untouched -- they may be
 // part of the prose; we never fail the task over a missing file.
@@ -101,8 +101,17 @@ export async function inlineAtRefs(workdir, text) {
         }
         let body = raw;
         let note = '';
-        if (body.length > AT_REF_FILE_CAP) {
-            let cut = AT_REF_FILE_CAP;
+        // The per-file cap alone lets the TOTAL budget be overshot: a file that
+        // fits AT_REF_FILE_CAP was inlined WHOLE even when only a few KB of the
+        // total were left, so four references produced a 245 KB section while the
+        // cap promises 200 KB. Budget the cut by what is left, and stop adding
+        // files once the pool is spent.
+        const room = AT_REF_TOTAL_CAP - total;
+        if (room <= 0)
+            break;
+        const cap = Math.min(AT_REF_FILE_CAP, room);
+        if (body.length > cap) {
+            let cut = cap;
             // Never end the inlined block on a lone HIGH surrogate: the cut is in
             // UTF-16 units, so an emoji / astral CJK char on the boundary would
             // reach the model as a broken code point (same rule as
@@ -111,7 +120,14 @@ export async function inlineAtRefs(workdir, text) {
             if (last >= 0xd800 && last <= 0xdbff)
                 cut--;
             body = body.slice(0, cut);
-            note = NL + NL + '(truncated at ' + AT_REF_FILE_CAP + ' chars)';
+            note =
+                NL +
+                    NL +
+                    '(truncated at ' +
+                    cap +
+                    ' chars; the task total cap is ' +
+                    AT_REF_TOTAL_CAP +
+                    ')';
         }
         total += body.length;
         inlined.push(path.relative(workdir, file) || file);

package/dist/browser-chats.js

@@ -1,4 +1,4 @@
-// PURE parsing of the DeepSeek history/message payloads (BACKLOG C3). These
+// PURE parsing of the DeepSeek history/message payloads . These
 // helpers are extracted from DeepSeekBrowser.fetchChatMessages: they used to be
 // copy-pasted INLINE twice (the in-page evaluate AND the Playwright-request
 // fallback), so the same role/fragment extraction lived in two places and could

package/dist/browser-dom.js

@@ -1,4 +1,4 @@
-// Pure in-page DOM helpers extracted from DeepSeekBrowser (BACKLOG C3).
+// Pure in-page DOM helpers extracted from DeepSeekBrowser .
 //
 // Every function here runs INSIDE page.evaluate, so it MUST be fully
 // self-contained: Playwright serializes the function SOURCE and evaluates it in

package/dist/browser-pure.js

@@ -14,7 +14,7 @@ export function cleanAnswer(raw) {
         return '';
     return raw;
 }
-// Pure, state-free helpers extracted from browser.ts (BACKLOG C3). Nothing
+// Pure, state-free helpers extracted from browser.ts . Nothing
 // here touches the DeepSeekBrowser instance state, so this module is safe to
 // import anywhere (including hot-reloaded modules) without pulling in the
 // live Playwright context. browser.ts re-exports the public names, so the

package/dist/browser.js

@@ -18,7 +18,7 @@ import { translate, DEFAULT_LOCALE } from './i18n.js';
 // here preserves the existing public API (test/*.test.ts import them from
 // browser.ts).
 export { STOP_NAME_RE, CONTINUE_NAME_RE };
-// The pure, state-free helpers live in browser-pure.ts (BACKLOG C3): they are
+// The pure, state-free helpers live in browser-pure.ts : they are
 // imported for the class below and RE-EXPORTED here, so the public API of this
 // module is unchanged (tests and other modules import these names from
 // './browser.js').

package/dist/changelog.js

@@ -1,4 +1,4 @@
-// Conventional-Commits -> CHANGELOG draft (BACKLOG D2). PURE and
+// Conventional-Commits -> CHANGELOG draft. PURE and
 // unit-tested: the draft is built from git log OUTSIDE the release flow
 // (scripts/changelog-draft.mts), so a misparse never touches CHANGELOG.md.
 // We do NOT auto-write the file: a human (or the agent) reviews the draft

package/dist/checkpoint.js

@@ -4,7 +4,7 @@ import os from 'os';
 import { execFile } from 'child_process';
 import { randomBytes } from 'crypto';
 import { writeJsonAtomic } from './fsutil.js';
-// Checkpoints / rewind (BACKLOG B3).
+// Checkpoints / rewind .
 //
 // Undo (src/undo.ts) reverts ONE file write. A checkpoint snapshots the WHOLE
 // working tree at the start of a task, so a risky task can be rolled back with

package/dist/cli-args.js

@@ -1,4 +1,4 @@
-// PURE CLI argument parsing (BACKLOG C3). index.ts used to hold `args` as a
+// PURE CLI argument parsing . index.ts used to hold `args` as a
 // module-level constant plus three helpers closing over it, which made the
 // parsing impossible to unit-test in isolation (index.ts is the entry point and
 // is not covered). `createCliArgs(argv)` binds the argv ONCE and returns the

package/dist/config-command.js

@@ -1,4 +1,4 @@
-// The /config subcommand DISPATCH (BACKLOG C3). The PURE text rendering lives
+// The /config subcommand DISPATCH . The PURE text rendering lives
 // in config-commands.ts; this module owns the parsing/routing of the text
 // subcommands (list/get/set/reset/lang/path) and prints through injected
 // callbacks. Everything that touches live state (the runtime config object,

package/dist/config-commands.js

@@ -1,4 +1,4 @@
-// PURE rendering for the /config command's TEXT output (BACKLOG C3). These
+// PURE rendering for the /config command's TEXT output . These
 // helpers format the schema into lines; they touch no browser/terminal state,
 // so they are unit-tested without a live agent (the /config dispatch in
 // index.ts only prints what these return). The interactive menu lives in

package/dist/config.js

@@ -70,7 +70,7 @@ export const DEFAULTS = {
         enabled: true,
         maxBackups: 200,
     },
-    // BACKLOG B3: snapshot the whole working tree at the start of each task so
+    // Snapshot the whole working tree at the start of each task so
     // /rewind can roll a risky task back in one step.
     checkpoint: {
         enabled: true,

package/dist/context.js

@@ -186,9 +186,25 @@ function clipIf(name, content, budget, fromTail = false) {
     // MEMORY.md is APPENDED to over time, so its newest (most relevant) notes
     // live at the TAIL — a head clip would drop exactly those. Keep the tail
     // for memory files, the head for AGENTS.md (whose top is the summary).
-    if (!fromTail)
-        return cleaned.slice(0, keep) + NL + NL + marker;
-    let slice = cleaned.slice(cleaned.length - keep);
+    //
+    // The cut is in UTF-16 units, so it can land BETWEEN the halves of a
+    // surrogate PAIR (an emoji / astral CJK char): the head would then end with
+    // a lone HIGH half and the tail would START with a lone LOW half. Both reach
+    // the model through the system prompt as broken code points (the same rule
+    // as truncateToolResult / capReport / cutHookText). Step one unit back for
+    // the head, one unit forward for the tail, so the pair is dropped whole.
+    if (!fromTail) {
+        let end = keep;
+        const last = cleaned.charCodeAt(end - 1);
+        if (last >= 0xd800 && last <= 0xdbff)
+            end--;
+        return cleaned.slice(0, end) + NL + NL + marker;
+    }
+    let start = cleaned.length - keep;
+    const first = cleaned.charCodeAt(start);
+    if (first >= 0xdc00 && first <= 0xdfff)
+        start++;
+    let slice = cleaned.slice(start);
     // Cut at a NOTE boundary, not mid-note: start the kept tail at the next line
     // that begins a bullet or a heading, so a half-sentence note is not left.
     const m = slice.search(/\n(?=[-*] |#{1,6} )/);

package/dist/extraTools.js

@@ -226,6 +226,13 @@ export function createExtraTools(workdir, { undo, todos } = {}) {
         if (v === undefined || v === null) {
             throw new Error(`Missing required argument: ${name}. Add "${name}" to the tool call arguments and retry.`);
         }
+        // `path`/`pattern` are strings by contract; an OBJECT used to become
+        // "[object Object]" and reach the fs layer as a literal file name.
+        if (typeof v === 'object' || typeof v === 'function') {
+            throw new Error(`Invalid required argument ${name}: expected a string, got ` +
+                JSON.stringify(v) +
+                '. Re-send the call with a plain string value.');
+        }
         const s = String(v);
         if (s === '' || s === 'undefined' || s === 'null') {
             throw new Error(`Invalid required argument ${name}: ${JSON.stringify(v)}. Provide a non-empty value for "${name}" and retry.`);