@aragon-agent/cli 0.6.45 → 0.6.47

package/CHANGELOG.md

@@ -8,6 +8,21 @@ were written.
 ## Unreleased
 
 ### Added
+- **Long waits: `job_wait` now waits up to 20 minutes, and the wait looks like it.**
+  `timeoutSeconds` takes any integer from 5 to 1200 (it used to stop at 60, and at 150 with the
+  default `toolTimeoutMs`, because the tool ceiling silently pulled it down). `job_wait` gets its own
+  executor ceiling (1230 s) and pauses the idle watchdog for the whole wait, so `toolTimeoutMs` no
+  longer limits it and `jobs.waitSeconds` accepts 5-1200. **Typing a message ends the wait at once**
+  (result line `[woke] ...`, the job keeps running, no `Esc` needed); reviewer notes and completion
+  notices do not. While waiting, the tool card is replaced by a fixed five-row card - a progress bar
+  (the job's own progress when it prints any, otherwise the wait window), both clocks, the job's
+  newest output with "N s ago", a calm "not a failure" note after `jobs.stallSeconds` of silence, and
+  a hint that a message ends the wait - and the status bar reads `Waiting on t3 4m12s/10m00s`. New:
+  `job: "any"` (return on the first job to end), a `[next]` suggestion with a `timeoutSeconds` (and the
+  job's ETA) so the model prefers one long wait to many short ones, and `[note]` when a request is
+  clamped to the ceiling. No new config keys; `jobs.enabled=false` is byte-identical to before.
+  Honest limit: while a wait runs the idle check is off, so a stuck wait is ended by its own 20-minute
+  bound, the executor backstop, or you.
 - **Governance mode - a multi-agent "legion" collaboration posture.** `Shift+Tab` (and `Ctrl+N`)
   now cycle `BUILD -> PLAN -> GOVERN -> PLAN+GOVERN -> BUILD`; `/gov` goes to any of them
   directly. In `GOVERN` the main agent becomes an **Orchestrator** that cannot write files or run

package/README.md

@@ -2068,13 +2068,60 @@ longer reads "not ready yet, still coming up" for its first minute.
 Two tools manage them:
 
 - `job_wait({ job, timeoutSeconds?, since? })` — block up to a bound (default 30s,
-  at most 60s) and return one status line, one progress line, at most six new
-  output rows and a cursor. It returns immediately if the job already finished.
-  This is the point of the feature: waiting 30 seconds used to cost six
-  `bash_output` calls, six model turns and six 200-row tails; it now costs one
-  call and about 150 tokens.
+  **at most 20 minutes**: `timeoutSeconds` takes any integer from 5 to 1200) and
+  return one status line, one progress line, at most six new output rows and a
+  cursor. It returns immediately if the job already finished, and it also ends
+  the moment **you send a message** (see below). `job` is an id, `"all"` (until
+  every live job ends) or `"any"` (until the first one ends). This is the point
+  of the feature: waiting 30 seconds used to cost six `bash_output` calls, six
+  model turns and six 200-row tails; it now costs one call and about 150 tokens,
+  and a 40-minute training run costs a handful of calls instead of dozens.
 - `job_list()` — one line per job: id, kind, status, elapsed, progress.
 
+### Long waits
+
+A wait can now last up to 20 minutes, so three things keep it safe and visible:
+
+- **You can always interrupt it by typing.** Send a message while the agent is
+  waiting and the wait ends at once; the result says `[woke] you sent a message...`,
+  your message is delivered next, and the job keeps running. You do not need
+  `Esc`, which would stop the whole run. (Automatic notes, such as a reviewer's
+  or a completion notice, do not end a wait. If the agent had queued more tool
+  calls in the same step, the engine skips them when your message arrives, as it
+  does for any message sent mid-step.)
+- **The wait is drawn as a five-row card** instead of a bare "running":
+
+  ```
+  ⠹ Waiting for t3  python train.py --epochs 10                 4m12s of 10m00s
+    │ ████████░░░░░░░░░░░░░░░░░░░░  30%  epoch 3/10  ETA 13m
+    │ job running 42m04s · this wait ends in 5m48s, or sooner if the job finishes
+    │ step 912/1000  loss 0.4098                                           3s ago
+    │ Send a message to end the wait early · Esc x2 stops the whole run
+  ```
+
+  The bar shows the job's own progress when it prints any, and otherwise the
+  wait window itself (the words say which). After `jobs.stallSeconds` of silence
+  the output row becomes a calm
+  `quiet for 6m02s - the job is still alive; this is not a failure`. The status
+  bar and activity line carry the same clock (`Waiting on t3 4m12s/10m00s`).
+  The card is always five rows, uses ASCII glyphs on terminals without Unicode,
+  and keeps its numbers moving under reduced motion. It disappears when the wait
+  ends and leaves the usual one-line history row.
+- **The idle watchdog is paused for the length of the wait**, and `toolTimeoutMs`
+  no longer limits it: `job_wait` gets its own executor ceiling (20 minutes plus
+  30 seconds). The honest cost is that a wait which is itself stuck is only
+  caught by that ceiling and by you (`Esc x2`), not by the 3.5-minute idle check.
+
+Results suggest the next wait: when the job reports an ETA or has been running for
+a while, the `[next]` line carries a `timeoutSeconds` worth using (for example
+`timeoutSeconds: 900 ... (ETA about 13m)`) so the agent prefers one long wait to
+many short ones. It is advice, never enforced. A request over 1200 seconds is
+clamped and says so (`[note] timeoutSeconds 3600 exceeds the 1200s ceiling`).
+
+Cost note: a wait longer than your provider's prompt-cache lifetime (often five
+minutes) means the next request re-reads the context uncached. That is still far
+cheaper than the dozens of model turns short polling would have spent.
+
 Nothing else tells the model a job finished. When one ends while it is busy, a
 `<job_notices>` block appears at the end of the next tool result:
 
@@ -2114,7 +2161,7 @@ to use it — `grep` and `read_file` already exist.
 | Key | Default | Meaning |
 |---|---|---|
 | `jobs.enabled` | `true` | Register `job_wait`/`job_list`, splice the prompt block. `false` restores the pre-feature build byte for byte. |
-| `jobs.waitSeconds` | `30` | Default bound for one wait, 5–60. Also lowered automatically so a wait always fits inside the tool ceiling. |
+| `jobs.waitSeconds` | `30` | Default bound for one wait, 5–1200. No longer lowered by `toolTimeoutMs`. |
 | `jobs.stallSeconds` | `300` | Silence before `[stalled]`, 30–3600. |
 | `jobs.persistLog` | `true` | Mirror each job's output to disk. `false` creates no directory at all. |
 | `jobs.noticeSteer` | `true` | Whether a completion notice may interrupt a running turn. `false` keeps the notice for the next tool result or the next user turn — it is **not** a notification off switch. |
@@ -3013,6 +3060,57 @@ declares no placeholder, the arguments are appended under an `## Arguments`
 heading instead. Where a skill's name collides with a built-in command, the
 **built-in wins** and the skill is reachable as `/skill:<name>`.
 
+### Invocation cards
+
+A command that starts a task by submitting a long prompt on your behalf does not
+print that prompt. `/pdf-forms`, `/skill:<name>`, `/team <brief>`, `/todo continue`
+and `/gov resume` each leave one **card** in the transcript instead: what you
+started, a few facts, and your own words.
+
+```
+> skill . pdf-forms  v1.2.0 . user . 31 KB . 4 files
+  Fill the W-9 form in ./tax/w9.pdf with the values from data.json
+
+> team  4 subagents . read-only
+  Audit the auth module for session fixation and add regression tests
+  Asked for 12; team.maxSubagents is 8.
+
+> todo . continue  3 of 7 steps left
+```
+
+(`.` is `·` on a Unicode terminal.) The first row names the command and its
+facts and is shortened to the width of the window - facts go first, then the name.
+Your own words follow, capped at 8 lines / 480 characters with an honest
+`... +N chars not shown` tail. A line below it appears only when the command
+changed what you asked for (a fan-out above `team.maxSubagents`). `Ctrl+I` shows a
+`ctrl+i` fact and no input row: the sentence it sends the model is not something
+you said.
+
+What changes and what does not:
+
+- **The model receives exactly the bytes it did before.** Only the transcript
+  entry is different; the skill body, the team directive and the continuation text
+  are untouched.
+- The `Command:` echo and the old `Skill "x" loaded (...)` / `Forcing a fan-out...`
+  notices are folded into the card, so one act is stated once.
+- Up-arrow history and the header task label hold the command you typed
+  (`/skill:pdf-forms a.pdf`), not the prompt behind it. Canned turns the commands
+  submit for you (`/team`, `/todo continue`, `/gov resume`) still stay out of
+  history and do not trigger a task label, exactly as before.
+- A skill run now adds one history entry instead of two to the hint-fade counter.
+- Secrets in your arguments are redacted **before** anything is cut, so a key that
+  straddles a cut cannot leave a readable prefix in the transcript, the session
+  file or the exit replay.
+- The exit replay prints the command line plus one `[skill pdf-forms v1.2.0 - ...]`
+  line. A very long brief is capped at 2000 characters there; the full text is in
+  the up-arrow history and in the conversation itself.
+- Sessions written before cards existed load unchanged; a damaged card in a session
+  file degrades to the plain command line instead of failing the load.
+
+`ARAGON_NO_INVOCATION_CARDS=1` restores the previous behaviour completely (echo,
+notices and the full prompt in the transcript). It is an emergency switch, not a
+setting.
+
 ### Where skills come from
 
 Four scopes, later ones overriding earlier ones by name:

package/dist/agent/coalesce.d.ts

@@ -16,6 +16,10 @@
  * concatenating, and a differing id starts a new pending action because merging
  * across ids would paint one command's output onto another's card.
  *
+ * A FOURTH ARRIVED WITH THE LONG WAIT (extended-job-wait RV-6): `waitUpdate`
+ * carries the WHOLE view, so it merges exactly like the tool tail - same
+ * `toolCallId` keeps the last, a different id or any other action flushes first.
+ *
  * ONE PENDING SLOT, DISCRIMINATED, NEVER TWO (P1-5). A second, independent slot
  * for the object-shaped payload would let a chunk overtake a token and reorder
  * the two streams — exactly what I-L4-1 (`ui/render-governor.ts:14-19`) forbids:

package/dist/agent/coalesce.js

@@ -16,6 +16,10 @@
  * concatenating, and a differing id starts a new pending action because merging
  * across ids would paint one command's output onto another's card.
  *
+ * A FOURTH ARRIVED WITH THE LONG WAIT (extended-job-wait RV-6): `waitUpdate`
+ * carries the WHOLE view, so it merges exactly like the tool tail - same
+ * `toolCallId` keeps the last, a different id or any other action flushes first.
+ *
  * ONE PENDING SLOT, DISCRIMINATED, NEVER TWO (P1-5). A second, independent slot
  * for the object-shaped payload would let a chunk overtake a token and reorder
  * the two streams — exactly what I-L4-1 (`ui/render-governor.ts:14-19`) forbids:
@@ -28,6 +32,9 @@ function isTextDelta(action) {
 function isToolOutputDelta(action) {
     return action.type === 'toolOutputDelta';
 }
+function isWaitUpdate(action) {
+    return action.type === 'waitUpdate';
+}
 /** Merge consecutive same-kind deltas; flush on kind change or a non-delta. */
 export function mergeDeltas(actions) {
     const out = [];
@@ -70,6 +77,12 @@ export function mergeDeltas(actions) {
             // increment, so merging means replacing (D-30).
             pending = { kind: 'tool', action };
         }
+        else if (isWaitUpdate(action)) {
+            const merges = prev !== null && prev.kind === 'wait' && prev.action.toolCallId === action.toolCallId;
+            if (!merges)
+                flush();
+            pending = { kind: 'wait', action };
+        }
         else {
             flush();
             out.push(action);

package/dist/agent/controller.d.ts

@@ -28,6 +28,7 @@ import type { SubagentModelResolution } from '../team/model.js';
 import type { ForcedTeamState } from '../team/forced-mode.js';
 import type { TeamEvent, TeamSnapshot } from '../team/types.js';
 import { ProcSupervisor } from '../proc/supervisor.js';
+import type { WaitEvent } from '../proc/wait-view.js';
 import type { ProcEventListener, ServiceSnapshot } from '../proc/types.js';
 import { type FastStatus } from '../fast/wiring.js';
 import type { FastEventListener, FastSnapshot } from '../fast/types.js';
@@ -350,6 +351,10 @@ export declare class AgentController {
      */
     private readonly toolOutputs;
     private readonly outputListeners;
+    /** `job_wait` live-view listeners (extended-job-wait); see `subscribeWait`. */
+    private readonly waitListeners;
+    /** "The user just spoke": ends a running `job_wait` early. */
+    private readonly userAttention;
     private readonly fast;
     private readonly compaction;
     private settingsRevision;
@@ -768,6 +773,12 @@ export declare class AgentController {
      * rather than a counter, so a nested call's `finally` re-arms the watchdog
      * while the outer wait is still going. That is why a child's `--confirm`
      * dialog does NOT route through this (see the constructor's `humanQueue`).
+     *
+     * `job_wait` ALSO DEPENDS ON THAT (extended-job-wait I-3): it holds the pause for
+     * up to 20 minutes and is safe only because the engine runs a batch's tools
+     * one at a time. If tool execution ever becomes parallel, make this a COUNTER
+     * first - otherwise the first tool to finish re-arms the watchdog under a
+     * still-waiting sibling, which then kills the run at the idle timeout.
      */
     withPausedWatchdog<T>(fn: () => Promise<T>): Promise<T>;
     /** @see withPausedWatchdog — the name the plan tools and `--confirm` use. */
@@ -1026,6 +1037,16 @@ export declare class AgentController {
      * `warn` because a listener that throws once throws on every chunk.
      */
     private emitToolOutput;
+    /**
+     * Subscribe to `job_wait`'s live view (`begin` / 1 Hz `update` / `end`).
+     *
+     * NOT GATED ON `liveToolOutput` (extended-job-wait D-9): that switch bounds a
+     * high-frequency byte stream; this channel is capped at 1 Hz, and switching it
+     * off would bring back the 20-minute black box.
+     */
+    subscribeWait(listener: (event: WaitEvent) => void): () => void;
+    /** Fan out one wait event; a throwing listener is logged and skipped (I-6). */
+    private emitWait;
     /**
      * Subscribe to the CLI-local live tool-output stream (§3.1.3).
      *

package/dist/agent/controller.js

@@ -27,7 +27,8 @@ import { buildForcedTeamBlock } from '../team/forced-prompt.js';
 import { buildFastBlock } from '../fast/prompt.js';
 import { ProcSupervisor } from '../proc/supervisor.js';
 import { buildBackgroundJobsBlock, buildBackgroundServicesBlock } from '../proc/prompt.js';
-import { PROC_LIMITS } from '../proc/limits.js';
+import { JOB_WAIT_TOOL_CEILING_MS, PROC_LIMITS } from '../proc/limits.js';
+import { createUserAttention } from './user-attention.js';
 import { JobLogMirror } from '../proc/log-mirror.js';
 import { JobNoticeQueue } from '../proc/notices.js';
 import { makeBashKill, makeBashOutput } from '../tools/proc-tools.js';
@@ -261,6 +262,10 @@ export class AgentController {
      */
     toolOutputs;
     outputListeners = new Set();
+    /** `job_wait` live-view listeners (extended-job-wait); see `subscribeWait`. */
+    waitListeners = new Set();
+    /** "The user just spoke": ends a running `job_wait` early. */
+    userAttention = createUserAttention();
     // -----------------------------------------------------------------------
     // Fast model tier (fast-model-tier §3.1 / §3.3)
     //
@@ -735,15 +740,19 @@ export class AgentController {
                         supervisor: this.procs,
                         waitSeconds: () => this.config.jobs.waitSeconds,
                         stallSeconds: () => this.config.jobs.stallSeconds,
-                        toolTimeoutMs: () => this.config.toolTimeoutMs,
                         maxConsecutiveWaits: PROC_LIMITS.maxConsecutiveWaits,
                         terminalRecord: (id) => this.jobRelay?.terminalRecord(id),
+                        // THE THREE LONG-WAIT PORTS (extended-job-wait). `holdWatchdog` wraps the
+                        // WHOLE wait because tools run one at a time (I-3); `attention` is
+                        // subscribe-only (RV-1); the view listener never throws back (I-6).
+                        onWait: (event) => this.emitWait(event),
+                        holdWatchdog: (fn) => this.withPausedWatchdog(fn),
+                        attention: { subscribe: (listener) => this.userAttention.subscribe(listener) },
                     }),
                     makeJobList({
                         supervisor: this.procs,
                         waitSeconds: () => this.config.jobs.waitSeconds,
                         stallSeconds: () => this.config.jobs.stallSeconds,
-                        toolTimeoutMs: () => this.config.toolTimeoutMs,
                         maxConsecutiveWaits: PROC_LIMITS.maxConsecutiveWaits,
                         terminalRecord: (id) => this.jobRelay?.terminalRecord(id),
                     }),
@@ -961,6 +970,13 @@ export class AgentController {
                     // outlived a mid-session `Settings > Team` switch to the supervisor
                     // and killed the dispatch the supervisor was meant to look after.
                     ...(this.teamRegistered ? { task: 0 } : {}),
+                    // THE EXECUTOR'S OWN CLOCK FOR A LONG WAIT (extended-job-wait I-2 / I-4').
+                    // Without it `job_wait` falls onto `toolTimeoutMs` (180 s) and a 20-minute
+                    // wait dies at three; with `0` the wait would have no independent backstop
+                    // while the watchdog is paused. A finite value derived from the one
+                    // authority, `PROC_LIMITS.waitMaxSeconds`, is both. `jobsRegistered` is
+                    // assigned in the constructor before this table is built.
+                    ...(this.jobsRegistered ? { job_wait: JOB_WAIT_TOOL_CEILING_MS } : {}),
                     // P0 (governance-mode D-21 / RV-0): `gov_dispatch` runs a whole governed stage,
                     // routinely longer than `toolTimeoutMs`, and it listens to `ctx.signal` (it hands
                     // it to `TeamRuntime.dispatch`), which is what makes `0` safe. Registered in the SAME
@@ -1587,6 +1603,10 @@ export class AgentController {
                 this.pendingUserSteering.delete(id);
             throw error;
         }
+        // AFTER a successful steer, and ONLY for user input (I-7): a reviewer or a job
+        // notice must not cut short the wait the user chose.
+        if (user)
+            this.userAttention.notify();
         return id;
     }
     followUp(text) {
@@ -1948,6 +1968,12 @@ export class AgentController {
      * rather than a counter, so a nested call's `finally` re-arms the watchdog
      * while the outer wait is still going. That is why a child's `--confirm`
      * dialog does NOT route through this (see the constructor's `humanQueue`).
+     *
+     * `job_wait` ALSO DEPENDS ON THAT (extended-job-wait I-3): it holds the pause for
+     * up to 20 minutes and is safe only because the engine runs a batch's tools
+     * one at a time. If tool execution ever becomes parallel, make this a COUNTER
+     * first - otherwise the first tool to finish re-arms the watchdog under a
+     * still-waiting sibling, which then kills the run at the idle timeout.
      */
     async withPausedWatchdog(fn) {
         this.agent.pauseIdleWatchdog();
@@ -2501,6 +2527,33 @@ export class AgentController {
             }
         }
     }
+    /**
+     * Subscribe to `job_wait`'s live view (`begin` / 1 Hz `update` / `end`).
+     *
+     * NOT GATED ON `liveToolOutput` (extended-job-wait D-9): that switch bounds a
+     * high-frequency byte stream; this channel is capped at 1 Hz, and switching it
+     * off would bring back the 20-minute black box.
+     */
+    subscribeWait(listener) {
+        this.waitListeners.add(listener);
+        return () => {
+            this.waitListeners.delete(listener);
+        };
+    }
+    /** Fan out one wait event; a throwing listener is logged and skipped (I-6). */
+    emitWait(event) {
+        for (const listener of this.waitListeners) {
+            try {
+                listener(event);
+            }
+            catch (err) {
+                getLogger().debug('tool', 'wait_listener_threw', {
+                    toolCallId: event.toolCallId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+    }
     /**
      * Subscribe to the CLI-local live tool-output stream (§3.1.3).
      *

package/dist/agent/invocation-card.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Invocation cards (tui-invocation-cards): what a transcript shows INSTEAD of the
+ * system prompt a command submitted on the user's behalf.
+ *
+ * Pure and total: no IO, no React, no Ink, nothing but `import type`. ASCII ONLY -
+ * `src/agent/**` new files sit inside the `glyphs.test.ts` scan scope.
+ *
+ * ONE CONSTRUCTOR (I-3). `buildInvocationCard` is the only function that turns raw
+ * command-layer material into a card, `App.submitMessage` is its only caller, and
+ * `sanitizeInvocationCard` (the session-load path) shares its normaliser so a card
+ * written today and a card read back tomorrow cannot drift apart.
+ *
+ * ORDER IS REDACT -> NORMALISE -> LIMIT, and it is the load-bearing part (I-6). Cut
+ * first and a secret that straddles the cut leaves a prefix shorter than the
+ * redaction patterns' minimum length: the half-key sails through into the
+ * transcript, the session file and the exit replay.
+ */
+export type InvocationVariant = 'skill' | 'team' | 'todo' | 'govern';
+/** Everything one card needs; persisted, queued and rendered in this one shape. */
+export interface InvocationCard {
+    readonly variant: InvocationVariant;
+    /** Skill name / 'continue' / 'resume'; '' for team. */
+    readonly name: string;
+    /** What the user typed (or its equivalent), redacted and capped; also `Entry.text`. */
+    readonly commandLine: string;
+    /** The user's own words (args / brief), redacted and trimmed; may be ''. */
+    readonly input: string;
+    /** Characters cut from `input`; 0 when nothing was cut. */
+    readonly inputHidden: number;
+    /** Fact fragments, each at most `factMaxChars`, at most `factsMax` of them. */
+    readonly facts: readonly string[];
+    /** One disclosure sentence. */
+    readonly note?: string;
+}
+/**
+ * The renderer, the height estimate and the loader all read THESE numbers (I-4).
+ * A card's height is a function of its data and these limits, so it is bounded:
+ * header + `inputMaxLines` + hidden tail + note.
+ */
+export declare const INVOCATION_LIMITS: {
+    readonly commandLineMaxChars: 2000;
+    readonly inputMaxChars: 480;
+    readonly inputMaxLines: 8;
+    readonly nameMaxChars: 64;
+    readonly factsMax: 5;
+    readonly factMaxChars: 28;
+    readonly noteMaxChars: 140;
+};
+/**
+ * Raw material from the command layer: NOT redacted, NOT trimmed. Commands must not
+ * cut or scrub it themselves - both happen exactly once, in `buildInvocationCard`.
+ */
+export interface InvocationCardInput {
+    variant: InvocationVariant;
+    name?: string;
+    commandLine: string;
+    input?: string;
+    facts?: readonly string[];
+    note?: string;
+}
+/**
+ * Total, never throws. `redact` is injected (the same closure `Command:` echo uses) so
+ * this module depends on nothing; the default is the identity for tests and the loader.
+ */
+export declare function buildInvocationCard(input: InvocationCardInput, redact?: (text: string) => string): InvocationCard;
+/**
+ * Session-load path: `null` for anything that is not a plausible card, so the caller
+ * drops the field and the entry degrades to a plain user message (I-7). Re-derives
+ * `inputHidden` from nothing - it trusts the stored count only when it is a sane integer.
+ */
+export declare function sanitizeInvocationCard(value: unknown): InvocationCard | null;
+/**
+ * Emergency kill switch (`ARAGON_NO_INVOCATION_CARDS=1`): every command and the App fall
+ * back to the pre-card behaviour. Read at call time, not import time, so a test (or a
+ * wrapper script) that sets the variable after load is honoured.
+ */
+export declare function invocationCardsEnabled(env?: NodeJS.ProcessEnv): boolean;

package/dist/agent/invocation-card.js

@@ -0,0 +1,169 @@
+/**
+ * Invocation cards (tui-invocation-cards): what a transcript shows INSTEAD of the
+ * system prompt a command submitted on the user's behalf.
+ *
+ * Pure and total: no IO, no React, no Ink, nothing but `import type`. ASCII ONLY -
+ * `src/agent/**` new files sit inside the `glyphs.test.ts` scan scope.
+ *
+ * ONE CONSTRUCTOR (I-3). `buildInvocationCard` is the only function that turns raw
+ * command-layer material into a card, `App.submitMessage` is its only caller, and
+ * `sanitizeInvocationCard` (the session-load path) shares its normaliser so a card
+ * written today and a card read back tomorrow cannot drift apart.
+ *
+ * ORDER IS REDACT -> NORMALISE -> LIMIT, and it is the load-bearing part (I-6). Cut
+ * first and a secret that straddles the cut leaves a prefix shorter than the
+ * redaction patterns' minimum length: the half-key sails through into the
+ * transcript, the session file and the exit replay.
+ */
+/**
+ * The renderer, the height estimate and the loader all read THESE numbers (I-4).
+ * A card's height is a function of its data and these limits, so it is bounded:
+ * header + `inputMaxLines` + hidden tail + note.
+ */
+export const INVOCATION_LIMITS = {
+    commandLineMaxChars: 2000,
+    inputMaxChars: 480,
+    inputMaxLines: 8,
+    nameMaxChars: 64,
+    factsMax: 5,
+    factMaxChars: 28,
+    noteMaxChars: 140,
+};
+const VARIANTS = ['skill', 'team', 'todo', 'govern'];
+// C0 except TAB (\x09) and LF (\x0a), then DEL and C1 (which includes the 8-bit CSI
+// \x9b). Matches the range `QueueOverlay` strips, so the card is no more permissive.
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARS = /[\x00-\x08\x0b-\x1f\x7f-\x9f]/g;
+const CAP_MARK = '...';
+/** Cut at a code-point boundary: a surrogate pair is never split. */
+function sliceCodePoints(text, count) {
+    if (count <= 0)
+        return '';
+    if (text.length <= count)
+        return text;
+    let end = count;
+    const last = text.charCodeAt(end - 1);
+    // A high surrogate at the cut would orphan its low half.
+    if (last >= 0xd800 && last <= 0xdbff)
+        end -= 1;
+    return text.slice(0, end);
+}
+function countCodePoints(text) {
+    let count = 0;
+    for (const _ of text)
+        count += 1;
+    return count;
+}
+/** CRLF and bare CR to LF (a bare CR returns Ink's cursor to column 0), then strip controls. */
+function normalizeText(text) {
+    return text.replace(/\r\n?/g, '\n').replace(CONTROL_CHARS, '');
+}
+function capCommandLine(text) {
+    const max = INVOCATION_LIMITS.commandLineMaxChars;
+    if (text.length <= max)
+        return text;
+    return sliceCodePoints(text, max - CAP_MARK.length) + CAP_MARK;
+}
+function capInput(text) {
+    const trimmed = text.trim();
+    if (trimmed === '')
+        return { input: '', hidden: 0 };
+    const lines = trimmed.split('\n');
+    let kept = lines.length > INVOCATION_LIMITS.inputMaxLines
+        ? lines.slice(0, INVOCATION_LIMITS.inputMaxLines).join('\n') : trimmed;
+    kept = sliceCodePoints(kept, INVOCATION_LIMITS.inputMaxChars).trimEnd();
+    return { input: kept, hidden: countCodePoints(trimmed) - countCodePoints(kept) };
+}
+function capSingleLine(text, max) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    if (countCodePoints(flat) <= max)
+        return flat;
+    return sliceCodePoints(flat, max - CAP_MARK.length) + CAP_MARK;
+}
+function capFacts(facts) {
+    return facts
+        .map((fact) => capSingleLine(fact, INVOCATION_LIMITS.factMaxChars))
+        .filter((fact) => fact !== '')
+        .slice(0, INVOCATION_LIMITS.factsMax);
+}
+function capNote(note) {
+    if (note === undefined)
+        return undefined;
+    const capped = capSingleLine(note, INVOCATION_LIMITS.noteMaxChars);
+    return capped === '' ? undefined : capped;
+}
+/** Shared by the write path and the load path so the two cannot diverge. */
+function assemble(parts) {
+    const { input, hidden } = capInput(normalizeText(parts.input));
+    const note = capNote(normalizeText(parts.note ?? ''));
+    return {
+        variant: parts.variant,
+        name: capSingleLine(normalizeText(parts.name), INVOCATION_LIMITS.nameMaxChars),
+        commandLine: capCommandLine(normalizeText(parts.commandLine).trim()),
+        input,
+        inputHidden: hidden,
+        facts: capFacts(parts.facts.map(normalizeText)),
+        ...(note !== undefined ? { note } : {}),
+    };
+}
+/**
+ * Total, never throws. `redact` is injected (the same closure `Command:` echo uses) so
+ * this module depends on nothing; the default is the identity for tests and the loader.
+ */
+export function buildInvocationCard(input, redact = (text) => text) {
+    const scrub = (text) => {
+        if (text === undefined)
+            return '';
+        try {
+            return redact(text);
+        }
+        catch {
+            return '';
+        }
+    };
+    return assemble({
+        variant: input.variant,
+        name: scrub(input.name),
+        commandLine: scrub(input.commandLine),
+        input: scrub(input.input),
+        facts: (input.facts ?? []).map((fact) => scrub(fact)),
+        note: input.note === undefined ? undefined : scrub(input.note),
+    });
+}
+function asString(value) {
+    return typeof value === 'string' ? value : null;
+}
+/**
+ * Session-load path: `null` for anything that is not a plausible card, so the caller
+ * drops the field and the entry degrades to a plain user message (I-7). Re-derives
+ * `inputHidden` from nothing - it trusts the stored count only when it is a sane integer.
+ */
+export function sanitizeInvocationCard(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const raw = value;
+    const variant = VARIANTS.find((candidate) => candidate === raw.variant);
+    const commandLine = asString(raw.commandLine);
+    if (variant === undefined || commandLine === null)
+        return null;
+    const name = asString(raw.name) ?? '';
+    const input = asString(raw.input) ?? '';
+    const facts = Array.isArray(raw.facts)
+        ? raw.facts.filter((fact) => typeof fact === 'string') : [];
+    const note = asString(raw.note) ?? undefined;
+    const card = assemble({ variant, name, commandLine, input, facts, note });
+    // A stored card that was already capped must keep its recorded `inputHidden`; the
+    // re-cap above can only ever add to it.
+    const stored = raw.inputHidden;
+    const storedHidden = typeof stored === 'number' && Number.isInteger(stored) && stored > 0
+        ? Math.min(stored, 10_000_000) : 0;
+    return { ...card, inputHidden: Math.max(card.inputHidden, storedHidden) };
+}
+/**
+ * Emergency kill switch (`ARAGON_NO_INVOCATION_CARDS=1`): every command and the App fall
+ * back to the pre-card behaviour. Read at call time, not import time, so a test (or a
+ * wrapper script) that sets the variable after load is honoured.
+ */
+export function invocationCardsEnabled(env = process.env) {
+    return env.ARAGON_NO_INVOCATION_CARDS !== '1';
+}

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

@@ -1,3 +1,4 @@
+import type { InvocationCardInput } from './invocation-card.js';
 /** Explicit TUI task boundary; omission retains legacy programmatic behavior. */
 export interface PromptOptions {
     todoPolicy?: 'new-task' | 'continue';
@@ -5,6 +6,11 @@ export interface PromptOptions {
 /** History recording is independent of whether this message continues a plan. */
 export interface SubmitMessageOptions extends PromptOptions {
     userInitiated?: boolean;
+    /**
+     * Raw material for the transcript card. `submitMessage` builds the card exactly once
+     * (redact -> normalise -> limit); the payload sent to the model is unaffected.
+     */
+    invocation?: InvocationCardInput;
 }
 /** Startup outcome only; engine events still describe the result of the run. */
 export type PromptOutcome = {

package/dist/agent/queued-messages.d.ts

@@ -1,8 +1,11 @@
 import type { Entry } from './reducer.js';
+import type { InvocationCard } from './invocation-card.js';
 /** Full user text retained until Core acknowledges its opaque ID. */
 export interface PendingSteering {
     readonly queueId: string;
     readonly text: string;
+    /** Carried so the `queued -> user` rewrite keeps the card (tui-invocation-cards). */
+    readonly invocation?: InvocationCard;
 }
 /** Hide only active pending entries, using the same projection for measurement and paint. */
 export declare function selectTranscriptEntries(entries: Entry[], pending: readonly PendingSteering[]): Entry[];

package/dist/agent/queued-messages.js

@@ -13,7 +13,10 @@ export function reconcileSteeringReceipt(options) {
     if (!ids.size)
         return { entries: options.entries, pending: [...options.pending], changed: false };
     const entries = mergePendingEntries(options.entries, options.pending).map((entry) => entry.kind === 'queued' && ids.has(entry.queueId ?? '')
-        ? { id: entry.id, kind: 'user', text: entry.text } : entry);
+        ? {
+            id: entry.id, kind: 'user', text: entry.text,
+            ...(entry.invocation ? { invocation: entry.invocation } : {}),
+        } : entry);
     return { entries, pending: options.pending.filter((item) => !ids.has(item.queueId)), changed: true };
 }
 /** Supplement trimmed/cleared history for save and exit without deduplicating text. */