zames_pro 2.61.0 → 2.63.0

package/CHANGELOG.md

@@ -5,7 +5,67 @@ 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]
 
@@ -249,7 +309,8 @@ 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.61.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

package/README.md

@@ -1,12 +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)
+<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
@@ -15,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`,
@@ -82,12 +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)
-- Security policy: [`SECURITY.md`](SECURITY.md)
-
 ## Installation
 
 ```bash
@@ -406,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, selfImprovement = false, }) {
+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;
@@ -108,6 +113,7 @@ export async function runAgentLoop({ browser, tools, task, workdir, maxIteration
             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) ?? [],
@@ -727,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
@@ -735,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 });
             }
@@ -744,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.
@@ -759,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/checkpoint.js

@@ -0,0 +1,197 @@
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import { execFile } from 'child_process';
+import { writeJsonAtomic } from './fsutil.js';
+// Checkpoints / rewind (BACKLOG B3).
+//
+// 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
+// a single `/rewind`. A tarball — not a git stash — is used on purpose: it
+// works in a non-git directory and never touches the operator's index/stash.
+//
+// Machine codes only ('not_found', 'archive_missing', ...): the caller
+// (src/index.ts) localizes them through the i18n catalog, exactly like
+// undo.ts. Keeping prose out of this module is also why no Russian leaks here
+// (see test/agent-facing-english.test.ts).
+const CHECKPOINT_DIR = path.join(os.homedir(), '.zames', 'checkpoints');
+// Never snapshotted and never deleted on restore: dependencies, the git object
+// store (the operator's own safety net), build output and the agent's scratch
+// dir. Everything else is part of the snapshot. Patterns are anchored to the
+// archive root ('./x') so a nested `src/tmp` is NOT accidentally excluded.
+export const CHECKPOINT_EXCLUDES = ['node_modules', '.git', 'dist', 'tmp'];
+// ---------- pure helpers (unit-tested without tar) ----------
+export function tarCreateArgs(archive, _dir) {
+    const args = ['-czf', archive];
+    for (const e of CHECKPOINT_EXCLUDES)
+        args.push('--exclude=./' + e);
+    args.push('-C', _dir, '.');
+    return args;
+}
+export function tarExtractArgs(archive, dir) {
+    return ['-xzf', archive, '-C', dir];
+}
+/** Keep only the newest `max` records (returns a new array; order preserved). */
+export function rotateRecords(records, max) {
+    if (max <= 0)
+        return [];
+    if (records.length <= max)
+        return records.slice();
+    return records.slice(records.length - max);
+}
+/**
+ * Resolve a `/rewind` selector against records sorted NEWEST FIRST.
+ * `1` = most recent; a non-numeric selector is matched as a stamp prefix.
+ */
+export function pickRecord(records, selector) {
+    const sel = String(selector ?? '').trim();
+    if (!sel)
+        return null;
+    if (/^\d+$/.test(sel)) {
+        const n = Number(sel);
+        // A small number is an index (1 = newest). An out-of-range number is
+        // still tried as a stamp prefix below, so `/rewind 1730000` works.
+        if (n >= 1 && n <= records.length)
+            return records[n - 1];
+    }
+    return records.find((r) => String(r.stamp).startsWith(sel)) || null;
+}
+// ---------- tar / fs plumbing ----------
+function runTar(args, cwd, timeout = 60_000) {
+    return new Promise((resolve) => {
+        execFile('tar', args, { cwd, timeout, maxBuffer: 1024 * 1024 * 8, windowsHide: true }, (err, _stdout, stderr) => {
+            if (!err)
+                return resolve({ code: 0, stderr: '' });
+            const raw = err.code;
+            const code = typeof raw === 'number' ? raw : 127;
+            resolve({ code, stderr: String(stderr || err.message || '') });
+        });
+    });
+}
+async function copyTree(from, to) {
+    await fs.mkdir(to, { recursive: true });
+    const entries = await fs.readdir(from, { withFileTypes: true });
+    for (const e of entries) {
+        const src = path.join(from, e.name);
+        const dst = path.join(to, e.name);
+        if (e.isDirectory())
+            await copyTree(src, dst);
+        else if (e.isSymbolicLink()) {
+            const link = await fs.readlink(src).catch(() => null);
+            if (link !== null)
+                await fs.symlink(link, dst).catch(() => { });
+        }
+        else
+            await fs.copyFile(src, dst);
+    }
+}
+// ---------- store ----------
+export class CheckpointStore {
+    enabled;
+    maxBackups;
+    dir;
+    constructor({ enabled = true, maxBackups = 50, dir = CHECKPOINT_DIR, } = {}) {
+        this.enabled = enabled;
+        this.maxBackups = maxBackups;
+        this.dir = dir;
+    }
+    get indexFile() {
+        return path.join(this.dir, 'index.json');
+    }
+    async _ensure() {
+        await fs.mkdir(this.dir, { recursive: true });
+    }
+    async _readIndex() {
+        try {
+            const data = JSON.parse(await fs.readFile(this.indexFile, 'utf-8'));
+            return Array.isArray(data) ? data : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Snapshot `workdir` into a tarball. Best-effort: a missing tar, an
+     * unreadable dir or a timeout yields null, never a thrown error — a failed
+     * checkpoint must not abort the task it was meant to protect.
+     */
+    async create(workdir, label) {
+        if (!this.enabled)
+            return null;
+        await this._ensure();
+        const stamp = Date.now();
+        const file = path.join(this.dir, `${stamp}.tgz`);
+        const res = await runTar(tarCreateArgs(file, workdir), workdir);
+        if (res.code !== 0) {
+            await fs.rm(file, { force: true }).catch(() => { });
+            return null;
+        }
+        const record = { stamp, file, workdir };
+        if (label)
+            record.label = label;
+        const history = await this._readIndex();
+        history.push(record);
+        const kept = rotateRecords(history, this.maxBackups);
+        // Drop the archives that fell out of the retention window.
+        const keptStamps = new Set(kept.map((r) => r.stamp));
+        for (const r of history) {
+            if (!keptStamps.has(r.stamp))
+                await fs.rm(r.file, { force: true }).catch(() => { });
+        }
+        writeJsonAtomic(this.indexFile, kept);
+        return record;
+    }
+    /** Newest-first list, capped at `count`. */
+    async list(count = 10) {
+        const history = await this._readIndex();
+        return history.slice().reverse().slice(0, count);
+    }
+    /**
+     * Restore the working tree to a checkpoint. Backs up the CURRENT tree first
+     * (a 'pre-rewind' checkpoint), so the rewind itself is reversible. Returns
+     * machine codes; the caller localizes them.
+     */
+    async restore(selector) {
+        if (!this.enabled)
+            return { ok: false, reason: 'disabled' };
+        const history = await this._readIndex();
+        const newestFirst = history.slice().reverse();
+        const record = pickRecord(newestFirst, selector);
+        if (!record)
+            return { ok: false, reason: 'not_found' };
+        const exists = await fs
+            .stat(record.file)
+            .then(() => true)
+            .catch(() => false);
+        if (!exists)
+            return { ok: false, reason: 'archive_missing' };
+        // Backup the CURRENT tree before touching it.
+        const backup = await this.create(record.workdir, 'pre-rewind');
+        // Extract to a temp dir FIRST; only a successful extract may touch workdir
+        // (otherwise a bad archive would wipe the tree).
+        const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'zames-rewind-'));
+        try {
+            const res = await runTar(tarExtractArgs(record.file, tmp), tmp);
+            if (res.code !== 0)
+                return { ok: false, reason: 'extract_failed' };
+            // Full restore: drop everything in workdir except the excludes, then
+            // copy the snapshot in. A partial extract would leave behind files the
+            // task created after the checkpoint.
+            const entries = await fs
+                .readdir(record.workdir)
+                .catch(() => []);
+            for (const e of entries) {
+                if (CHECKPOINT_EXCLUDES.includes(e))
+                    continue;
+                await fs
+                    .rm(path.join(record.workdir, e), { recursive: true, force: true })
+                    .catch(() => { });
+            }
+            await copyTree(tmp, record.workdir);
+            return { ok: true, record, backup };
+        }
+        finally {
+            await fs.rm(tmp, { recursive: true, force: true }).catch(() => { });
+        }
+    }
+}

package/dist/commands.js

@@ -82,6 +82,8 @@ export function summarizeTranscript(entries) {
         turns: 0,
         toolCalls: 0,
         toolCounts: {},
+        toolMs: 0,
+        toolTime: {},
         durationMs: 0,
         startedAt: null,
         autoCompacts: 0,
@@ -98,6 +100,14 @@ export function summarizeTranscript(entries) {
             const tool = String(e.tool ?? '?');
             stats.toolCounts[tool] = (stats.toolCounts[tool] || 0) + 1;
         }
+        if (e.type === 'tool_result') {
+            const ms = Number(e.durationMs);
+            if (Number.isFinite(ms) && ms > 0) {
+                stats.toolMs += ms;
+                const tool = String(e.tool ?? '?');
+                stats.toolTime[tool] = (stats.toolTime[tool] || 0) + ms;
+            }
+        }
         if (typeof e.elapsed === 'number' && e.elapsed > stats.durationMs) {
             stats.durationMs = e.elapsed;
         }
@@ -179,6 +189,19 @@ export function renderCost(stats, transcriptFile, tokenUsage = null, t = transla
         for (const [name, n] of top)
             lines.push(' ' + name + ': ' + n);
     }
+    // T-D3: where the time went. Sort by total ms, show the top tools with the
+    // count and a human duration, so Read→Edit cycles and slow Bash calls are
+    // visible at a glance.
+    const byTime = Object.entries(stats.toolTime || {})
+        .filter(([, ms]) => ms > 0)
+        .sort((a, b) => b[1] - a[1]);
+    if (byTime.length) {
+        lines.push(t('cost.by_time', { dur: formatDuration(stats.toolMs) }));
+        for (const [name, ms] of byTime.slice(0, 8)) {
+            const count = stats.toolCounts[name] ?? 0;
+            lines.push(' ' + name + ': ' + formatDuration(ms) + ' ×' + count);
+        }
+    }
     lines.push(t('cost.duration', { dur: formatDuration(stats.durationMs) }));
     if (stats.startedAt)
         lines.push(t('cost.started', { v: stats.startedAt }));
@@ -615,6 +638,118 @@ export function rewriteFailedAttachments(text, failed) {
     }
     return out;
 }
+// Split a custom-command argument string into positional tokens, honoring
+// single/double quotes (so two quoted words stay one token). Pure, so it is
+// unit-tested.
+export function splitCommandArgs(rest) {
+    const out = [];
+    const s = String(rest ?? '');
+    const SQ = String.fromCharCode(39);
+    const DQ = String.fromCharCode(34);
+    let cur = '';
+    let quote = '';
+    for (let i = 0; i < s.length; i++) {
+        const ch = s[i];
+        if (quote) {
+            if (ch === quote) {
+                quote = '';
+                continue;
+            }
+            cur += ch;
+            continue;
+        }
+        if (ch === SQ || ch === DQ) {
+            quote = ch;
+            continue;
+        }
+        if (ch.charCodeAt(0) <= 32) {
+            if (cur) {
+                out.push(cur);
+                cur = '';
+            }
+            continue;
+        }
+        cur += ch;
+    }
+    if (cur)
+        out.push(cur);
+    return out;
+}
+function isAllDigits(tok) {
+    if (!tok)
+        return false;
+    for (let i = 0; i < tok.length; i++) {
+        const c = tok.charCodeAt(i);
+        if (c < 48 || c > 57)
+            return false;
+    }
+    return true;
+}
+function isWordChar(ch) {
+    const c = ch.charCodeAt(0);
+    return ((c >= 48 && c <= 57) ||
+        (c >= 65 && c <= 90) ||
+        (c >= 97 && c <= 122) ||
+        ch === '_');
+}
+// Replace $1..$N and $name tokens in an already-expanded body. A whole word is
+// read after $ so $foobar never matches the name foo. Pure.
+function replaceDollarTokens(s, parts, names) {
+    let res = '';
+    let i = 0;
+    while (i < s.length) {
+        const ch = s[i];
+        if (ch !== '$') {
+            res += ch;
+            i++;
+            continue;
+        }
+        let j = i + 1;
+        let tok = '';
+        while (j < s.length && isWordChar(s[j])) {
+            tok += s[j];
+            j++;
+        }
+        if (!tok) {
+            res += ch;
+            i++;
+            continue;
+        }
+        if (isAllDigits(tok)) {
+            res += parts[Number(tok) - 1] ?? '';
+        }
+        else {
+            const idx = names.indexOf(tok);
+            res += idx >= 0 ? (parts[idx] ?? '') : '$' + tok;
+        }
+        i = j;
+    }
+    return res;
+}
+// Expand a custom-command body: {{args}} / $ARGUMENTS become the whole argument
+// string, $1..$N the positional tokens, $name the declared positions. Pure, so
+// it is unit-tested.
+export function expandCommandArgs(body, rest, names = []) {
+    const parts = splitCommandArgs(rest);
+    let out = String(body ?? '');
+    out = out.split('{{args}}').join(rest);
+    out = out.split('$ARGUMENTS').join(rest);
+    out = replaceDollarTokens(out, parts, names);
+    return out.trim();
+}
+// Names declared in `arguments:` but not supplied on the command line (by
+// position). Pure, so the caller can refuse an incomplete invocation.
+export function missingCommandArgs(names, rest) {
+    if (!names || !names.length)
+        return [];
+    const parts = splitCommandArgs(rest);
+    const missing = [];
+    for (let i = 0; i < names.length; i++) {
+        if (!parts[i])
+            missing.push(names[i]);
+    }
+    return missing;
+}
 // True when a `/config ...` line can be handled LIVE (while the agent is busy):
 // the text subcommands only touch config values, never the chat. The bare
 // `/config` and `/config menu` (which pause the editor and read keys) are NOT