@aragon-agent/cli 0.6.7 → 0.6.8

package/README.md

@@ -438,8 +438,9 @@ completes, `Up` / `Down` moves the selection, `Esc` closes it.
 | `Alt+Enter` / `Shift+Enter` | Insert a newline |
 | `Shift+Tab` | Toggle **plan mode** (`BUILD` <-> `PLAN`). Equivalent: `/plan`. On Windows this needs a console flag Node < 22.17 does not set; aragon sets it at startup — see [Requirements](#requirements) |
 | `Ctrl+P` | The same toggle, over a channel no Windows console can swallow. Use it if `Shift+Tab` does nothing |
-| `Esc` | Abort the run / close an overlay / close a popup |
-| `Esc` ×2 | **Force-stop** a run that did not abort: kills the shell command it is blocked on and returns the view to `idle`. The second press only does anything while the run is *still* running, so in a healthy run it is a no-op |
+| `Esc` | Close an overlay or popup; otherwise ask for interruption confirmation. While idle, cancel pending auto-continuation |
+| `Esc` ×2 | Interrupt the run when pressed within 1.5 seconds. Other keys or closing a menu cancel the first press |
+| `Esc` again after interruption | **Force-stop** a run that is still stopping, kill foreground shell commands and return to `idle`; background services remain running |
 | `Ctrl+C` | Stop the background **services** the agent started, when there are any. It does not arm exit |
 | `Ctrl+C` ×2 | Exit (first press warns), once no services are running |
 | `Ctrl+L` | Redraw the frame (clear the screen in inline mode) |
@@ -460,8 +461,11 @@ completes, `Up` / `Down` moves the selection, `Esc` closes it.
 In **full-screen mode** the transcript is scrolled by the app itself: `PgUp` /
 `PgDn` and `Shift+↑` / `Shift+↓`. While pinned to the bottom the viewport follows
 new output automatically; once you scroll away the status bar shows `↑N`, a slim
-rail on the right edge shows where you are, and a hint counts the lines below
-you. Submitting a message always re-pins to the newest output. In **inline mode**
+scrollbar occupies the terminal's last column (including 40-column windows). Drag its thumb
+to move through history, or click the track to move one page. Messages, the team panel
+and the input area scroll together; typing or editing returns to the input without
+losing the draft. The fixed status row shows `PgDn down` while reading history.
+`PgDn` moves one page down; editing or submitting returns directly to the end. In **inline mode**
 (`--no-fullscreen`) history lives in your terminal's native scrollback, printed
 once via Ink `<Static>`.
 
@@ -474,9 +478,10 @@ open. It never touches your draft, and it never recalls prompt history: that is
 Two things follow from the app owning the mouse, and they are worth knowing
 before you meet them:
 
-- **Selecting text now needs `Shift`+drag** in most terminals. That is the
-  terminal's convention for "an application is tracking the mouse", not
-  something this CLI can opt out of while still reading wheel events.
+- **Dragging text selects and copies it when mouse selection is enabled.**
+  Dragging the last-column scrollbar scrolls instead. `--no-mouse-select` disables
+  text selection while preserving scrollbar dragging. `Shift`+drag uses the
+  terminal's native selection on hosts that support that convention.
 - **`tmux` with `mouse on` keeps the wheel for itself**, so the app never sees
   it. `set -g mouse off` hands it back.
 - **A Windows console on Node below 22.17.0 cannot report the wheel at all**,
@@ -512,7 +517,7 @@ Density and hints are settable the same three ways: `--compact` / `--no-hints`
 for one run, `aragon config set density compact` / `aragon config set hints false`
 to persist. The composer hint row also shortens to `? help` on its own after a
 few sessions — except while a run is in progress, when it always spells out
-`esc abort` in full.
+`esc ×2 interrupt` in full.
 
 ## What you see while it runs
 
@@ -624,8 +629,9 @@ near-identical added ones.
 
 - Your previous shell output is **covered, not erased**, and returns untouched
   when you exit. Nothing in your scrollback is destroyed.
-- The frame is fixed at `rows - 1` tall, which is what keeps the composer and the
-  status bar at the bottom of the screen even on an empty session.
+- The frame is fixed at `rows - 1` tall. The header, activity row and status bar
+  stay visible. The input belongs to the scrolling document; short sessions fill
+  the space above it, and browsing history moves it out of view.
 
 On exit the session is replayed into the normal buffer as plain text so the
 conversation survives leaving the screen (`--no-exit-transcript` opts out;
@@ -638,10 +644,13 @@ writing screen-control sequences into a pipe or a redirected file is never safe.
 `--no-fullscreen`, `ARAGON_FULLSCREEN=0`, or `aragon config set fullscreen false`
 opt out permanently.
 
-The terminal's native scrollback and mouse wheel do not scroll the transcript in
-this mode, and mouse tracking is deliberately left off because enabling it costs
-text selection and copy in most terminals. If a crash ever strands your terminal
-on the alternate screen, `reset` restores it.
+The alternate screen uses an application scrollbar rather than the terminal's
+native scrollback. Windows Terminal and conhost have different mouse/VT capabilities;
+the PowerShell version alone does not determine dragging support. If the host cannot
+deliver SGR mouse reports, the scrollbar remains visible and keyboard scrolling works.
+`--no-mouse` provides that keyboard-only path; `--no-diff-render` disables output
+differencing without disabling the scrollbar. A mid-session resize below 40 columns
+or 12 rows displays a size hint and preserves the draft for restoration.
 
 ## Render performance
 
@@ -742,8 +751,8 @@ assumptions rather than to retry.
 
 **Dismissing a plan is not how you stop.** `Esc` on a plan card asks for a
 *better* plan — the agent is told to refine it and submit again — so a model that
-keeps submitting keeps getting cards. To stop the run itself, **press `Esc`
-twice**: the first closes the card, the second aborts the run. `Ctrl+C` twice
+keeps submitting keeps getting cards. To stop the run itself, close the card with `Esc`, then **press `Esc`
+twice within 1.5 seconds** to interrupt. Closing the card never counts as the first press. `Ctrl+C` twice
 still exits the session outright.
 
 ### Where the mode is shown
@@ -800,8 +809,8 @@ ask — and the agent writes the finished plan as its final message in markdown.
 For work with three or more distinct steps the agent keeps a **visible plan**:
 it writes a checklist with the `todo_write` tool, marks exactly one item as in
 progress, and ticks it off before starting the next. In full-screen mode that
-list is rendered as a right-hand rail, targeting 15% of the terminal width
-(14–36 columns, including its separator and padding).
+list is rendered as a right-hand rail, targeting 15% of the terminal width
+(14–36 columns, including its separator and padding).
 
 ```
   transcript ...                            | TODO             2/7
@@ -809,7 +818,7 @@ list is rendered as a right-hand rail, targeting 15% of the terminal width
                                             |
                                             | v  1 Read the reducer
                                             | v  2 Design the store
-                                            | >  3 Wiring the rail...
+                                            | >  3 Wiring the rail...
                                             | o  4 Add the panel-rows test
                                             | o  5 Update the README
                                             |      +2 more
@@ -821,8 +830,8 @@ for a question, or for a search with no work attached — and a one-item list
 against an empty plan is refused outright. A session that never plans has
 byte-identical layout to a build without this feature.
 
-**The list is a projection of what the model believes**, so nothing that does
-not also tell the model may change it — except you, saying so:
+**The list shows the current task's plan.** Starting a new task or explicitly
+clearing the list removes this live view while preserving conversation history:
 
 - `/clear` and `/todo clear` take the plan off the screen. Neither touches the
   conversation, so the model still knows what it was doing and its next update
@@ -831,10 +840,14 @@ not also tell the model may change it — except you, saying so:
 - `/save` writes the list and `/resume` restores it. Resuming a session that has
   no list clears the current one, rather than leaving a plan on screen whose
   conversation has just been replaced.
-- A finished plan is dropped at the START of your next message, so you still get
-  to see `7/7 done`. An unfinished one survives "continue" / "now do the rest",
-  and is dropped after three unrelated turns rather than holding part of the
-  screen for the rest of the session.
+- A normal new task clears the previous plan, including unfinished steps, only
+  when it starts successfully. The completed run keeps its final plan visible.
+  `/todo continue` and automatic continuation preserve the plan and its timestamp;
+  ordinary text such as "continue" starts a new task. Steering keeps the current
+  plan. Until a valid new `todo_write`, the rail, inline strip and count stay hidden.
+  Startup failure or cancellation keeps the old plan. History cards remain available.
+- During a live run, interrupt before `/reset` or `/resume`. A conversation switch
+  while startup is waiting cancels that pending request and returns the view to idle.
 
 ### When a run ends with steps left
 
@@ -857,7 +870,7 @@ setting:
 
 `Esc` during the grace window cancels; so does typing anything. A run that ended
 with an **error** never auto-continues in any mode — you get a warning instead.
-A run **you** aborted with `Esc` now says nothing at all, where it used to
+A run **you** interrupted with two `Esc` presses now says nothing at all, where it used to
 report what you had just interrupted.
 
 `/todo follow off` is the third mode: no notice, no continuation, silence.
@@ -889,19 +902,19 @@ planning discipline and hides the column — which is what you want with a scree
 reader, and what `--no-todo-panel` does for a whole session. Under `-p` the plan
 is written to stderr as `[todo] 3/7 <step>` lines, suppressed by `--quiet`.
 
-右栏从 76 列开始显示，正文至少保留 62 列；100 列终端使用 15 列右栏。
-已有任务时，团队面板按实际行数占用空间，补全菜单的边框和提示也计入预算。
-例如 100×20、团队占 8 行时，TODO 仍以 4 行紧凑视图显示。
-
-剩余 3–5 行时保留标题、完成计数、当前任务与合并提示 `-A +B`：
-`-9 +10` 表示上方隐藏 9 项、下方隐藏 10 项。6 行起使用常规视图；
-所有任务各占一行，全文仍可在正文任务卡片中查看。进度条需要至少 20 列、8 行。
-输入增长导致空间不足时团队先折叠为摘要；菜单不足 3 行时隐藏，其候选不会拦截输入。
-
-低于 76 列、共享区域不足 3 行、打开 overlay、显式关闭面板、没有任务或
-inline 模式时不显示右栏。低于 12 行使用原有小终端提示；扩大窗口后自动恢复。
-inline 仍使用上文的单行任务条。`/todo status` 中的 `Panel: on` 仅表示配置开启，
-实际可见性还取决于数据和窗口空间；可以通过该命令区分未生成计划与暂时隐藏。
+右栏从 76 列开始显示，正文至少保留 62 列；100 列终端使用 15 列右栏。
+已有任务时，团队面板按实际行数占用空间，补全菜单的边框和提示也计入预算。
+例如 100×20、团队占 8 行时，TODO 仍以 4 行紧凑视图显示。
+
+剩余 3–5 行时保留标题、完成计数、当前任务与合并提示 `-A +B`：
+`-9 +10` 表示上方隐藏 9 项、下方隐藏 10 项。6 行起使用常规视图；
+所有任务各占一行，全文仍可在正文任务卡片中查看。进度条需要至少 20 列、8 行。
+输入增长导致空间不足时团队先折叠为摘要；菜单不足 3 行时隐藏，其候选不会拦截输入。
+
+低于 76 列、共享区域不足 3 行、打开 overlay、显式关闭面板、没有任务或
+inline 模式时不显示右栏。低于 12 行使用原有小终端提示；扩大窗口后自动恢复。
+inline 仍使用上文的单行任务条。`/todo status` 中的 `Panel: on` 仅表示配置开启，
+实际可见性还取决于数据和窗口空间；可以通过该命令区分未生成计划与暂时隐藏。
 
 ## Built-in tools
 
@@ -1007,7 +1020,8 @@ than features. `bash` now always settles: it returns when the process exits
 rather than when its output stream closes, so a command that detaches a
 grandchild can no longer leave the turn pending forever, and it is handed a
 closed stdin so a command that prompts fails instead of blocking on a read
-nobody will answer. And `Esc` twice always force-stops, whatever the flag says.
+nobody will answer. Two `Esc` presses request interruption; another press force-stops a stuck run,
+whatever the flag says.
 
 ## Team subagents
 
@@ -1079,7 +1093,7 @@ children's tokens are folded into the `[usage]` footer.
   `debug`. A `team_send` subject is recorded, never its body; a subagent's brief
   and summary only at `trace`.
 
-**`Esc`** aborts the whole dispatch — every subagent within a couple of seconds
+**Two `Esc` presses within 1.5 seconds** abort the whole dispatch — every subagent within a couple of seconds
 — and the report comes back marked `ABORTED` with whatever was finished.
 
 ## Fast model tier
@@ -2234,7 +2248,7 @@ node packages/cli/dist/cli.js --version
   shebang; `node packages/cli/dist/cli.js --version` prints the version.
 - `npm pack -w packages/cli --dry-run --json` lists `dist/cli.js` under `files`.
 - With `ANTHROPIC_API_KEY` set: `aragon` streams a reply, a tool card renders,
-  `Esc` aborts mid-run, `/model` switches models, `/settings` saves a key,
+  `Esc` twice interrupts mid-run, `/model` switches models, `/settings` saves a key,
   `Ctrl+C` twice exits.
 - `echo "list files" | node dist/cli.js -p` prints an answer and exits `0`.
 - A missing/invalid key produces a visible, actionable message (never a blank
@@ -2252,7 +2266,7 @@ node packages/cli/dist/cli.js --version
   nothing is truncated to a single line.
 - `--no-hints` on a 20-row terminal in plan mode - the status bar still says
   `PLAN` with no chip on screen.
-- Dismiss a plan card with `Esc`, let the agent resubmit, then press `Esc` twice:
+- Dismiss a plan card with `Esc`, let the agent resubmit, then close the card and press `Esc` twice within 1.5 seconds:
   the run aborts and the session returns to an idle prompt. Do this one BY HAND
   as well as in a test - the point of the check is whether the exit is findable,
   which no assertion can tell you.
@@ -2260,3 +2274,18 @@ node packages/cli/dist/cli.js --version
 ## License
 
 MIT
+
+
+### 输入光标与任务切换验收
+
+输入获得应用内焦点时，光标每 500 ms 明暗切换；编辑、移动和恢复焦点后立即亮起。
+`reducedMotion` 开启时保持常亮，弹层打开时暂停。fullscreen 和 inline 使用相同规则。
+单色终端用等列宽的下划线标记，原文相同时改用 `^`，零宽附加码点保留以兼容 Ink。
+标记不进入草稿、历史或提交文本；屏幕选择复制会包含当时可见的标记。
+UTF-16 编辑和 ZWJ/组合字形仍有既有限制，本次修复保证视觉光标定位及相位布局稳定。
+
+在 Windows Terminal/PowerShell 与 POSIX TTY 分别验证两种模式，窗口覆盖
+120×30、100×20、80×24、60×16：观察空输入、英文、中文、emoji、多行和组合附加符至少三个周期。
+检查流式输出不阻止闪烁；单 ESC 不停止任务，两击中断，卡住时第三击强停；菜单关闭不计入两击。
+任务结束后保留最终计划，下一条普通消息启动时旧计划消失，新有效计划出现才恢复；显式续跑保留计划。
+强停后立即提交，在等待中双 ESC 取消，旧引擎退出后不得自行执行已取消的消息。

package/dist/agent/controller.d.ts

@@ -8,6 +8,7 @@
  * success — that promise resolves even on failure. Success/failure is derived
  * from the event stream by the reducer (TUI) and the headless writer.
  */
+import type { PromptOptions, PromptOutcome } from './prompt-options.js';
 import { ModelRegistry, type AgentEvent, type AgentTool, type Message, type ModelInfo, type ModelRef, type ProviderRegistry, type ThinkingLevel } from '@aragon-agent/core';
 import type { CliConfig, CompactionConfig, FastConfig, RetryConfig, TeamConfig, ThemeName, TodoConfig } from '../config/schema.js';
 import { type ConfirmRequest } from '../tools/index.js';
@@ -207,6 +208,7 @@ export declare class AgentController {
      * abort lands.
      */
     private runGen;
+    private startupSequence;
     /**
      * Set SYNCHRONOUSLY by `abort()` before `agent.abort()` (§3.5.4a guard 1).
      * Cleared at the next `agent_start`.
@@ -264,21 +266,23 @@ export declare class AgentController {
      * underlying promise so headless mode can await completion. `agent.prompt()`
      * never rejects, so callers must not treat resolution as success.
      */
-    prompt(text: string): Promise<void>;
+    prompt(text: string, options?: PromptOptions): Promise<PromptOutcome>;
     /**
      * Wait for the engine to unwind, bounded.
      *
      * BOUNDED BECAUSE THE UNBOUNDED CASE IS THE ONE THIS FEATURE IS ABOUT: a tool
-     * that never settles is exactly why rung two exists, and `Agent.waitForIdle()`
+     * that never settles is exactly why the force-stop rung exists, and `Agent.waitForIdle()`
      * alone would hang here for as long as it hangs there. The budget is the two
      * graces a wedged `bash` can legitimately spend, plus the executor's own.
      */
     private waitForEngineIdle;
-    /** The pre-round body of `prompt`, unchanged apart from being private. */
+    /** Prepare before clearing the plan, then enter the engine without yielding. */
     private startPrompt;
+    /** Cancel pending startup as well as any engine run already in progress. */
     abort(): void;
+    private stopEngine;
     /**
-     * Rung two of the Esc ladder: stop the AGENT, whatever it is blocked on
+     * Final rung of the Esc ladder: stop the AGENT, whatever it is blocked on
      * (§3.6 / G3).
      *
      * FOUR STEPS, AND THE FOURTH IS AN ABSENCE.
@@ -286,7 +290,7 @@ export declare class AgentController {
      *   1. `abort()` - everything it does today, unchanged.
      *   2. `killForeground('force')` - hard-kill every tracked foreground `bash`
      *      child. THIS is what actually unblocks a wedged `await tool.execute`;
-     *      an abort signal a tool ignores is advisory, and rung two exists for
+     *      an abort signal a tool ignores is advisory, and the force-stop rung exists for
      *      precisely the tools that ignore it.
      *   3. `runGen += 1` - so `App` can drop the events the engine will keep
      *      emitting while it unwinds (I-7). Without it the view bounces straight
@@ -295,7 +299,7 @@ export declare class AgentController {
      *      `Ctrl+C` stops the SERVICES. That asymmetry is the user's own two
      *      sentences and it is exactly the kind of thing a later reader will
      *      "fix" by making this kill everything - which would mean a user who
-     *      pressed Esc twice to stop a runaway turn also lost the dev server they
+     *      confirmed a force-stop of a runaway turn also lost the dev server they
      *      had been working against for an hour. It is invariant I-4.
      *
      * UNCONDITIONAL ON `bash.background` (P1-6 / D-9). The supervisor is always

package/dist/agent/controller.js

@@ -45,7 +45,7 @@ import { buildSystemPrompt } from './system-prompt.js';
  *
  * `bash`'s own kill grace is what a wedged foreground command costs; this covers
  * the loop's own unwinding on top of it. Waiting FOREVER is not an option - a
- * tool that never settles is exactly why rung two exists.
+ * tool that never settles is exactly why the force-stop rung exists.
  */
 const ENGINE_UNWIND_GRACE_MS = 3000;
 /** Approval gate used whenever there is provably no human to ask (headless). */
@@ -246,6 +246,7 @@ export class AgentController {
      * abort lands.
      */
     runGen = 0;
+    startupSequence = 0;
     /**
      * Set SYNCHRONOUSLY by `abort()` before `agent.abort()` (§3.5.4a guard 1).
      * Cleared at the next `agent_start`.
@@ -855,43 +856,33 @@ export class AgentController {
      * underlying promise so headless mode can await completion. `agent.prompt()`
      * never rejects, so callers must not treat resolution as success.
      */
-    async prompt(text) {
-        // I-8 - THIS METHOD NEVER REJECTS, AND THAT HAS TO BE A PROPERTY OF THE
-        // METHOD RATHER THAN A COMMENT ABOVE IT (P0-1).
-        //
-        // `App` calls this as `void controller.prompt(...)`, and
-        // `logging/install.ts` routes an `unhandledRejection` into `handleFatal`,
-        // which EXITS THE PROCESS. `Agent.prompt()` throws SYNCHRONOUSLY while
-        // `Agent.running` is true - so before the force-stop ladder existed this was
-        // merely nearly-true (the view was only ever idle when the engine was), and
-        // rung two makes the view idle while the engine is still unwinding. Without
-        // the wait and the guard below, "Esc, Esc, then type" would kill the CLI on
-        // the very screen this feature exists to rescue.
-        //
-        // TWO PARTS, BOTH REQUIRED. First WAIT the engine out, bounded, so the
-        // common case (the engine unwinds in a few hundred ms) starts a real run
-        // rather than reporting a failure. Then swallow anything that still escapes
-        // and surface it through the existing notify channel, because a message that
-        // cannot be started must produce a visible sentence - never a crash, and
-        // never silence.
-        if (this.agent.state.isRunning) {
-            this.abort();
-            await this.waitForEngineIdle();
-        }
+    async prompt(text, options = {}) {
+        // Capture BEFORE stopping: synchronous abort listeners may cancel this request.
+        const request = ++this.startupSequence;
         try {
-            await this.startPrompt(text);
+            if (this.agent.state.isRunning) {
+                this.stopEngine();
+                await this.waitForEngineIdle();
+            }
+            if (request !== this.startupSequence) {
+                return { status: 'not-started', reason: 'cancelled' };
+            }
+            if (this.agent.state.isRunning)
+                throw new Error('The previous run is still stopping.');
+            return await this.startPrompt(text, options, request);
         }
         catch (err) {
             const reason = err instanceof Error ? err.message : String(err);
             getLogger().warn('agent', 'prompt_failed', { reason });
             this.notifyHostFn?.('error', `Could not start the run: ${reason}`);
+            return { status: 'not-started', reason: 'failed' };
         }
     }
     /**
      * Wait for the engine to unwind, bounded.
      *
      * BOUNDED BECAUSE THE UNBOUNDED CASE IS THE ONE THIS FEATURE IS ABOUT: a tool
-     * that never settles is exactly why rung two exists, and `Agent.waitForIdle()`
+     * that never settles is exactly why the force-stop rung exists, and `Agent.waitForIdle()`
      * alone would hang here for as long as it hangs there. The budget is the two
      * graces a wedged `bash` can legitimately spend, plus the executor's own.
      */
@@ -911,31 +902,25 @@ export class AgentController {
             void this.agent.waitForIdle().then(finish, finish);
         });
     }
-    /** The pre-round body of `prompt`, unchanged apart from being private. */
-    startPrompt(text) {
-        // A new user message is a new intent, so the previous turn's tool ceiling
-        // expires here and anything a slash command queued is promoted (D-G1 / D-G2).
-        // This and `steer()` below are the ONLY two places a user message enters the
-        // engine, which is what makes a per-turn scope implementable at all (FG9).
+    /** Prepare before clearing the plan, then enter the engine without yielding. */
+    async startPrompt(text, options, request) {
         if (this.skillsEnabled)
             this.skills.beginUserTurn();
-        // The ask-round budget is per USER TURN and resets here for the same reason
-        // the skill frame does. `steer()` deliberately does NOT reset it: a user
-        // steering "actually, use Postgres" into a running plan is answering the
-        // questions, not buying four more rounds of them.
         this.askRounds = 0;
-        // Same asymmetry, same reason (§3.5): a completed plan is dropped HERE
-        // rather than at `agent_end`, so the user gets their `7/7 done` moment, and
-        // an unfinished one survives "continue" / "now do the rest" but not four
-        // unrelated turns.
-        this.todos?.beginUserTurn();
-        // The fast reviewer is asked whether the run is on track FOR THIS (§3.5.2).
-        // Without it the reviewer judges progress without being told the goal, which
-        // is the one input it cannot reconstruct from the event stream.
         this.fast?.setGoal(text);
-        return this.agent.prompt(text);
+        if (request !== this.startupSequence) {
+            return { status: 'not-started', reason: 'cancelled' };
+        }
+        this.todos?.beginUserTurn(options.todoPolicy);
+        await this.agent.prompt(text);
+        return { status: 'finished' };
     }
+    /** Cancel pending startup as well as any engine run already in progress. */
     abort() {
+        this.startupSequence += 1;
+        this.stopEngine();
+    }
+    stopEngine() {
         // SET BEFORE `agent.abort()`, SYNCHRONOUSLY — guard 1 of §3.5.4a. The loop
         // still emits the batch's final `tool_execution_end` (`agent-loop.ts:249`)
         // after an Esc lands inside the last tool's `await`, and the reviewer's
@@ -959,7 +944,7 @@ export class AgentController {
         this.teamRuntime?.abortAll();
     }
     /**
-     * Rung two of the Esc ladder: stop the AGENT, whatever it is blocked on
+     * Final rung of the Esc ladder: stop the AGENT, whatever it is blocked on
      * (§3.6 / G3).
      *
      * FOUR STEPS, AND THE FOURTH IS AN ABSENCE.
@@ -967,7 +952,7 @@ export class AgentController {
      *   1. `abort()` - everything it does today, unchanged.
      *   2. `killForeground('force')` - hard-kill every tracked foreground `bash`
      *      child. THIS is what actually unblocks a wedged `await tool.execute`;
-     *      an abort signal a tool ignores is advisory, and rung two exists for
+     *      an abort signal a tool ignores is advisory, and the force-stop rung exists for
      *      precisely the tools that ignore it.
      *   3. `runGen += 1` - so `App` can drop the events the engine will keep
      *      emitting while it unwinds (I-7). Without it the view bounces straight
@@ -976,7 +961,7 @@ export class AgentController {
      *      `Ctrl+C` stops the SERVICES. That asymmetry is the user's own two
      *      sentences and it is exactly the kind of thing a later reader will
      *      "fix" by making this kill everything - which would mean a user who
-     *      pressed Esc twice to stop a runaway turn also lost the dev server they
+     *      confirmed a force-stop of a runaway turn also lost the dev server they
      *      had been working against for an hour. It is invariant I-4.
      *
      * UNCONDITIONAL ON `bash.background` (P1-6 / D-9). The supervisor is always
@@ -1492,6 +1477,7 @@ export class AgentController {
     }
     clearMessages() {
         this.agent.clearMessages();
+        this.startupSequence += 1;
         // INVALIDATION SITE 3 (context-auto-compaction-hardening §3.2.3). The history
         // was CLEARED, not appended to, so the prefix length the last measurement
         // covered indexes an array that no longer exists.
@@ -1519,6 +1505,7 @@ export class AgentController {
     }
     replaceMessages(messages) {
         this.agent.replaceMessages(messages);
+        this.startupSequence += 1;
         // INVALIDATION SITE 4 (§3.2.3) - `/resume`, and any future host-side rewrite.
         // `estimateAppendedTokens` bounds-checks as well, so a MISSED site costs
         // accuracy and never correctness; that belt does not make this call optional.

package/dist/agent/headless.d.ts

@@ -4,6 +4,7 @@
  * derived from the event stream (R2), not from the resolved promise:
  *   0 = success, 1 = agent error (incl. a silently-swallowed throw), 2 = config.
  */
+import type { PromptOutcome } from './prompt-options.js';
 import type { AgentEvent, ModelInfo } from '@aragon-agent/core';
 import type { PreflightResult } from './controller.js';
 import type { TeamEvent } from '../team/types.js';
@@ -15,7 +16,7 @@ import { type FollowThroughMode } from '../todo/follow-through.js';
 export interface HeadlessController {
     preflight(): PreflightResult;
     subscribe(listener: (event: AgentEvent) => void): () => void;
-    prompt(text: string): Promise<void>;
+    prompt(text: string): Promise<void | PromptOutcome>;
     getModelInfo(): ModelInfo;
     /**
      * The CLI-local team stream — OPTIONAL, deliberately (team-subagents §3.12 /

package/dist/agent/prompt-options.d.ts

@@ -0,0 +1,15 @@
+/** Explicit TUI task boundary; omission retains legacy programmatic behavior. */
+export interface PromptOptions {
+    todoPolicy?: 'new-task' | 'continue';
+}
+/** History recording is independent of whether this message continues a plan. */
+export interface SubmitMessageOptions extends PromptOptions {
+    userInitiated?: boolean;
+}
+/** Startup outcome only; engine events still describe the result of the run. */
+export type PromptOutcome = {
+    status: 'finished';
+} | {
+    status: 'not-started';
+    reason: 'cancelled' | 'failed';
+};

package/dist/agent/prompt-options.js

@@ -0,0 +1 @@
+export {};