@aragon-agent/cli 0.6.3 → 0.6.4

package/dist/compaction/compactor.js

@@ -26,6 +26,15 @@ export class Compactor {
     lastCompactionTurn = -Infinity;
     // --- Per-session state ---
     compactions = 0;
+    /**
+     * How many `compact()` calls returned WITHOUT announcing (quiet-noop D-9).
+     *
+     * A SESSION TOTAL, LIKE `compactions`, and reset by neither `onRunStart()` nor
+     * `clearSelfDisable()`: `/compact on` overrides a guard, it does not rewrite
+     * history. `/compact status` is its only reader, and it is the whole of what
+     * keeps a decline reportable once the transcript stops carrying one.
+     */
+    declined = 0;
     tokensReclaimed = 0;
     sessionUsage = { inputTokens: 0, outputTokens: 0 };
     pricingUnknown = false;
@@ -218,22 +227,19 @@ export class Compactor {
         const uiTrigger = manual ? 'manual' : ctx.trigger;
         const config = this.deps.getConfig().compaction;
         const summarizer = this.resolveSummarizer();
+        // GUARDS 1 AND 2 COUNT *ATTEMPTS*, NOT ANNOUNCEMENTS, and they stay here
+        // (quiet-noop §3.3). A decline still consumed a checkpoint: it still has to
+        // serve the cooldown and it still has to be charged to the per-run cap, or a
+        // history that can never be compacted would re-attempt on every turn for the
+        // whole run. `inFlight` stays for the same reason - the chip reports what the
+        // compactor is DOING, not what it has decided to say.
         this.compactionsThisRun += 1;
         this.lastCompactionTurn = ctx.turnIndex;
-        this.compactions += 1;
         this.inFlight = true;
-        const index = this.compactions;
-        this.deps.emit({
-            type: 'compaction_start',
-            index,
-            trigger: uiTrigger,
-            model: summarizer?.ref.modelId ?? '',
-        });
         const started = Date.now();
         try {
             return await this.runCompaction({
                 ctx,
-                index,
                 uiTrigger,
                 config,
                 summarizer,
@@ -250,8 +256,56 @@ export class Compactor {
     // =========================================================================
     // Internals
     // =========================================================================
+    /**
+     * Open the card (quiet-noop §3.2).
+     *
+     * THE ONLY EMITTER OF `compaction_start`, AND THE ONLY PLACE `this.compactions`
+     * ADVANCES. A compaction that never reaches an announce point is a DECLINE: it
+     * changed nothing, called nothing and spent nothing, and it is deliberately
+     * indistinguishable - on every human surface except `/compact status`'s
+     * `declined` count (D-9) - from a turn at which `shouldCompact` returned false.
+     * `finish` is the other half of that rule.
+     *
+     * IT RETURNS THE ANNOUNCEMENT RATHER THAN STORING IT (P1-1), and the caller
+     * keeps it in a LOCAL for the lifetime of one `runCompaction` call - the same
+     * slot `index` occupied before this change. An instance field would have needed
+     * a no-re-entrancy argument, and the obvious one is WRONG: guard 1 lives in
+     * `shouldCompact`, while the idle `/compact` path calls `compact()` straight
+     * through `wiring.compactNow()` without consulting it. What actually keeps two
+     * compactions apart is that `command.ts` QUEUES instead of calling `compactNow`
+     * while the loop runs - a property of a different file, which is exactly why
+     * this one must not depend on it. A clobbered field would leave `finish` unable
+     * to settle the card it opened, and a card that never settles pins
+     * `Transcript`'s monotonic boundary for the rest of the session.
+     */
+    announce(trigger, summarizer) {
+        this.compactions += 1;
+        this.deps.emit({
+            type: 'compaction_start',
+            index: this.compactions,
+            trigger,
+            model: summarizer?.ref.modelId ?? '',
+        });
+        return { index: this.compactions };
+    }
     async runCompaction(args) {
         const { ctx, config, summarizer } = args;
+        // THE ANNOUNCEMENT IS A LOCAL, NEVER A FIELD (quiet-noop §3.2 / P1-1), and
+        // `??=` is what makes the eager path and the two commit points idempotent
+        // with respect to each other.
+        let announced = null;
+        const announce = (model) => {
+            announced ??= this.announce(args.uiTrigger, model);
+        };
+        // A REQUESTED compaction and a REACTIVE one announce BEFORE they know the
+        // answer, for two different reasons. `manual` is a user instruction, and its
+        // QUEUED form (`/compact` typed mid-run) has NO other reporting surface - a
+        // silent decline there would be a command that did nothing and said nothing.
+        // `overflow` runs after the provider has ALREADY refused the request; if it
+        // cannot recover, the card is the only place that says why the run is about
+        // to die. Both paths stay byte-identical to the round before this one.
+        if (args.uiTrigger !== 'pressure')
+            announce(summarizer);
         const before = ctx.messages;
         const protectedPrefix = countProtectedPrefix(before);
         // THE ONE LEVER THE GUARDS DO NOT HAVE (D-24). A tail that alone exceeds the
@@ -271,6 +325,12 @@ export class Compactor {
             // `plan === null` branch tries it before conceding.
             const reliefOnly = this.relieveInPlace(before, protectedPrefix, ctx.systemPrompt);
             if (reliefOnly) {
+                // COMMIT POINT A (quiet-noop §3.4). Relief changes the history the run
+                // continues from - a bounded, announced data loss - so it is announced
+                // even though no model was called. `null` summarizer for the same reason
+                // `finish` writes `model: ''` on a relief-only record: naming a model here
+                // would claim a call that never ran.
+                announce(null);
                 this.checkProgress(ctx, args.uiTrigger, reliefOnly.messages);
                 return this.finish({ ...args, tailRelief: reliefSummary(reliefOnly) }, {
                     action: 'replace',
@@ -282,17 +342,51 @@ export class Compactor {
                     mode: 'truncated',
                     messages: reliefOnly.messages,
                     reason: 'tail_relief_only',
-                }, { droppedMessages: 0 }, keepRecentTurns);
+                }, { droppedMessages: 0 }, keepRecentTurns, announced);
             }
             this.noteNoProgress(args.uiTrigger, 'nothing_to_drop');
-            return this.finish(args, { action: 'keep', reason: 'nothing_to_drop' }, null, keepRecentTurns);
+            return this.finish(args, { action: 'keep', reason: 'nothing_to_drop' }, null, keepRecentTurns, announced);
         }
         const anchor = buildAnchor(before);
         if (!anchor) {
             // A history with no `user` message at all cannot have a goal anchor, and
             // D-6 makes the anchor non-negotiable. Refusing is the honest outcome.
-            return this.finish(args, { action: 'keep', reason: 'no_anchor' }, null, keepRecentTurns);
+            //
+            // STRUCTURALLY UNREACHABLE, AND KEPT ANYWAY (quiet-noop E-23 / §3.4). This
+            // is reached only after `plan !== null`, and `planCompaction` returns a plan
+            // only when some cut leaves `countTurns >= keep` behind it - `countTurns`
+            // counts `user`-role messages and `keep` is at least 1, so a plan PROVES the
+            // one thing `buildAnchor` looks for. A provably dead guard is worth strictly
+            // more than the non-null assertion that would replace it. It stays ABOVE the
+            // commit point on purpose: if the plan/anchor relationship ever changes, the
+            // reason that appears is one decided before any work began, and silence is
+            // what it should get - but any new PRE-COMMIT decline must then either
+            // charge guard 4 (as `nothing_to_drop` does) or be proven unreachable in
+            // turn, because guard 4 is what bounds how long a silent decline can repeat.
+            return this.finish(args, { action: 'keep', reason: 'no_anchor' }, null, keepRecentTurns, announced);
         }
+        // COMMIT POINT B (quiet-noop §3.4). Everything below this line either spends
+        // money (`runLadder`), rewrites the history, or faults - and all three are the
+        // user's business.
+        //
+        // BEFORE `buildDigest`, NOT AFTER. A throw inside the digest renderer reaches
+        // the engine as `manager_threw`, and the engine settles the card from the
+        // verdict alone; with no card open, that fault would be invisible on every
+        // human surface. Announcing first costs one event on a path that is about to
+        // spend seconds and dollars.
+        //
+        // WHAT IT STILL DOES NOT COVER (recorded, not closed - quiet-noop §12 / IF-2).
+        // A throw in the SYNCHRONOUS region ABOVE this line - `countProtectedPrefix`,
+        // `planCompaction`, `relieveInPlace`, `buildAnchor` - also reaches the engine
+        // as `manager_threw`, and on `pressure` that fault now has no card, charges no
+        // guard (`noteNoProgress` is never reached) and does not advance `declined`
+        // (`finish` is never called) - so a host bug there would repeat at every
+        // checkpoint for a whole run in silence. `manager_timeout` cannot land there:
+        // that region holds no `await`, which is the property AC-Q12 pins. Closing it
+        // means hoisting the announcement out of this function, which is precisely
+        // what P1-1 decided against - so it is written down rather than fixed under
+        // another change's name.
+        announce(summarizer);
         const head = before.slice(protectedPrefix, plan.cutIndex);
         const priorBlock = before.slice(0, protectedPrefix).find((m) => isPriorSummaryBlock(m));
         // The prior block is carried into the DIGEST rather than the tail, so the
@@ -312,14 +406,14 @@ export class Compactor {
             ...(args.instructions ? { instructions: args.instructions } : {}),
         });
         if (ladder.kind === 'aborted') {
-            return this.finish(args, { action: 'keep', reason: 'aborted' }, null, keepRecentTurns);
+            return this.finish(args, { action: 'keep', reason: 'aborted' }, null, keepRecentTurns, announced);
         }
         if (ladder.kind === 'failed' && config.onFailure === 'stop') {
             // Rung 4. The run proceeds and will probably hit `context_overflow`, which
             // is what the user asked for by setting this.
             this.deps.notify('error', `Context compaction failed (${ladder.reason}) and compaction.onFailure is "stop". ` +
                 'The next request may exceed the context window. Try /compact again, or /clear, or /reset.');
-            return this.finish(args, { action: 'keep', reason: `summarize_failed: ${ladder.reason}` }, null, keepRecentTurns);
+            return this.finish(args, { action: 'keep', reason: `summarize_failed: ${ladder.reason}` }, null, keepRecentTurns, announced);
         }
         const truncated = ladder.kind === 'failed';
         const mode = truncated ? 'truncated' : 'summarized';
@@ -365,7 +459,7 @@ export class Compactor {
             messages,
             ...(truncated ? {} : { summary: ladder.text }),
             ...(truncated ? { reason: `truncated: ${ladder.reason}` } : {}),
-        }, { droppedMessages: plan.droppedMessages, summary: truncated ? undefined : ladder.text }, keepRecentTurns);
+        }, { droppedMessages: plan.droppedMessages, summary: truncated ? undefined : ladder.text }, keepRecentTurns, announced);
     }
     /** Tail relief against this session's window (hardening §3.3.3 / W2). */
     relieveInPlace(messages, from, systemPrompt) {
@@ -522,19 +616,57 @@ export class Compactor {
             `${this.deps.getConfig().compaction.keepRecentTurns} turns alone exceed the threshold. ` +
             'Lower compaction.keepRecentTurns, or use /clear or /reset.');
     }
-    finish(args, outcome, applied, keepRecentTurnsUsed) {
+    finish(args, outcome, applied, keepRecentTurnsUsed, announced) {
         const before = args.ctx.messages.length;
         const after = outcome.action === 'replace' ? outcome.messages.length : before;
         const tokensBefore = this.lastPressure?.occupied ?? 0;
+        // `'relieved'` IS A CLI-ONLY WORD (RV-5 / DH-20). The port reports
+        // `'truncated'` for a relief-only compaction, which is accurate for the
+        // engine's narrower question; the card's `summarized N messages with
+        // <model>` line would otherwise render "summarized 0 messages with
+        // claude-haiku-4-5" for a compaction in which no model was called.
+        const mode = reliefOnly(outcome)
+            ? 'relieved'
+            : outcome.action === 'replace'
+                ? outcome.mode
+                : 'none';
+        // NO MODEL ON A RELIEF-ONLY RECORD, because no model was called. The card
+        // names the summarizer from this field, and naming one here would be the
+        // same claim `mode: 'relieved'` exists to stop making.
+        const model = reliefOnly(outcome) ? '' : args.summarizer?.ref.modelId ?? '';
+        const durationMs = Date.now() - args.started;
+        // THE ON-DISK RECORD OF EVERY ATTEMPT IS UNCHANGED (quiet-noop §9). This
+        // feature makes the TRANSCRIPT quiet, not the logs: a declined compaction is
+        // still one `compaction` line here, still one `compaction_start` /
+        // `compaction_end` pair from CORE in the JSONL sink, and still reflected in
+        // `/compact status`.
+        this.log.info('compaction', {
+            trigger: args.uiTrigger,
+            announced: announced !== null,
+            before,
+            after,
+            droppedMessages: applied?.droppedMessages ?? 0,
+            mode,
+            model,
+            durationMs,
+        });
+        // A SILENT DECLINE (quiet-noop §3.1). No card was opened, so there is nothing
+        // to settle and nothing to say IN THE TRANSCRIPT. Returning here is what makes
+        // a declined checkpoint indistinguishable from one at which `shouldCompact`
+        // said no.
+        //
+        // `declined` IS THE ONE THING THAT STILL SPEAKS (D-9). Quiet is the goal;
+        // invisible is not, and `/compact status` is a published guaranteed surface
+        // (`context-auto-compaction` §6.5). One integer here is what keeps that
+        // promise true while the card goes away.
+        if (!announced) {
+            this.declined += 1;
+            return outcome;
+        }
         const record = {
-            index: args.index,
+            index: announced.index,
             trigger: args.uiTrigger,
-            // `'relieved'` IS A CLI-ONLY WORD (RV-5 / DH-20). The port reports
-            // `'truncated'` for a relief-only compaction, which is accurate for the
-            // engine's narrower question; the card's `summarized N messages with
-            // <model>` line would otherwise render "summarized 0 messages with
-            // claude-haiku-4-5" for a compaction in which no model was called.
-            mode: reliefOnly(outcome) ? 'relieved' : outcome.action === 'replace' ? outcome.mode : 'none',
+            mode,
             // OPTIMISTIC AND CORRECTED BY THE WIRING (§3.2.1). Only the ENGINE knows
             // whether the splice passed the structural gate, and it says so on
             // `compaction_end`; the wiring rewrites this before the card settles.
@@ -546,23 +678,11 @@ export class Compactor {
             tokensBefore,
             tokensAfter: 0, // filled by the wiring from the engine's own estimator
             ...(applied?.summary ? { summary: applied.summary } : {}),
-            // NO MODEL ON A RELIEF-ONLY RECORD, because no model was called. The card
-            // names the summarizer from this field, and naming one here would be the
-            // same claim `mode: 'relieved'` exists to stop making.
-            model: reliefOnly(outcome) ? '' : args.summarizer?.ref.modelId ?? '',
-            durationMs: Date.now() - args.started,
+            model,
+            durationMs,
             ...(args.ctx.trigger === 'overflow' ? { keepRecentTurnsUsed } : {}),
             ...(args.tailRelief ? { tailRelief: args.tailRelief } : {}),
         };
-        this.log.info('compaction', {
-            trigger: args.uiTrigger,
-            before,
-            after,
-            droppedMessages: applied?.droppedMessages ?? 0,
-            mode: record.mode,
-            model: record.model,
-            durationMs: record.durationMs,
-        });
         this.deps.emit({ type: 'compaction_end', record });
         return outcome;
     }
@@ -605,6 +725,7 @@ export class Compactor {
     sessionTotals() {
         return {
             compactions: this.compactions,
+            declined: this.declined,
             tokensReclaimed: this.tokensReclaimed,
             usage: this.sessionUsage,
             pricingUnknown: this.pricingUnknown,

package/dist/compaction/types.d.ts

@@ -143,7 +143,26 @@ export interface CompactionSnapshot {
     live: boolean;
     /** The summarizer's model id, or `''`. */
     model: string;
+    /**
+     * How many compactions ANNOUNCED themselves (quiet-noop §6.2 / D-5).
+     *
+     * COMPACTIONS THAT RAN, NOT CHECKPOINTS THAT FIRED. A `pressure` compaction
+     * that declines before calling a model or changing the history never advances
+     * this, which is what keeps the card's `#N` contiguous. `declined` below is
+     * the other half of the same total.
+     */
     compactions: number;
+    /**
+     * How many `pressure` checkpoints declined BEFORE committing to any work
+     * (quiet-noop D-9 / P1-2).
+     *
+     * OPTIONAL SO EVERY EXISTING CONSTRUCTION SITE STAYS UNTOUCHED, and rendered
+     * by `/compact status` only when non-zero — a healthy session must not read
+     * `(0 checkpoints declined)`. This is the one human surface that still speaks
+     * about a decline after the transcript went quiet, which is what keeps
+     * `context-auto-compaction` §6.5's "guaranteed reporting surface" promise true.
+     */
+    declined?: number;
     /** Sum of `(tokensBefore - tokensAfter)` over applied compactions. */
     tokensReclaimed: number;
     /** What compaction itself has spent this session. */
@@ -161,6 +180,23 @@ export interface CompactionSnapshot {
     generation: number;
     pressure: Pressure;
 }
+/**
+ * THE COMPACTION EVENT STREAM.
+ *
+ * `compaction_start` and `compaction_end` are emitted ONLY for compactions that
+ * COMMITTED TO WORK (quiet-noop §3.1): a `pressure` compaction that declines
+ * before calling a model or changing the history emits NEITHER, and is
+ * deliberately indistinguishable from a turn at which `shouldCompact` returned
+ * false. `manual` and `overflow` always emit both.
+ *
+ * The pair is still BALANCED: every `compaction_start` is followed by exactly
+ * one `compaction_end` (a `finally` in the engine guarantees the verdict, and
+ * `settlePending` synthesizes a skeleton record when the compactor's own has not
+ * arrived). Consumers that count PAIRS are unaffected; consumers that counted
+ * ATTEMPTS must read `/compact status` or the JSONL diagnostic log instead -
+ * CORE's own `compaction_start` / `compaction_end` pair still fires for every
+ * attempt, declined or not, and that is the stream the log subscribes to.
+ */
 export type CompactionEvent = {
     type: 'compaction_start';
     index: number;

package/dist/compaction/wiring.d.ts

@@ -25,6 +25,15 @@
  * methods delegate to a compactor that reads config LIVE - which is what lets
  * `/compact off`, `/compact threshold 0.8` and a settings-screen save take effect
  * mid-session without touching the `Agent`.
+ *
+ * DECLINED COMPACTIONS PRODUCE NO CLI EVENTS (quiet-noop §3.6). A `pressure`
+ * compaction that changed nothing, called nothing and spent nothing never emits
+ * `compaction_start`, so `onCompactorEvent` never opens a card and `settlePending`
+ * finds neither a held record nor a skeleton to synthesize. CORE still emits its
+ * own pair for every attempt, which is why `settlePending` still runs - it just
+ * refreshes the snapshot and returns. `onCompactorEvent`'s `if (!this.open)`
+ * guard is now unreachable for declines and stays for the abort race it was
+ * written for.
  */
 import { type AgentEvent, type ContextManager, type Message, type ModelInfo, type ModelRef, type ProviderRegistry, type ProviderRegistryOptions, type TokenUsage } from '@aragon-agent/core';
 import type { CliConfig } from '../config/schema.js';

package/dist/compaction/wiring.js

@@ -25,6 +25,15 @@
  * methods delegate to a compactor that reads config LIVE - which is what lets
  * `/compact off`, `/compact threshold 0.8` and a settings-screen save take effect
  * mid-session without touching the `Agent`.
+ *
+ * DECLINED COMPACTIONS PRODUCE NO CLI EVENTS (quiet-noop §3.6). A `pressure`
+ * compaction that changed nothing, called nothing and spent nothing never emits
+ * `compaction_start`, so `onCompactorEvent` never opens a card and `settlePending`
+ * finds neither a held record nor a skeleton to synthesize. CORE still emits its
+ * own pair for every attempt, which is why `settlePending` still runs - it just
+ * refreshes the snapshot and returns. `onCompactorEvent`'s `if (!this.open)`
+ * guard is now unreachable for declines and stays for the abort race it was
+ * written for.
  */
 import { DEFAULT_RETRY_POLICY, estimatePromptTokens, initProviders, validateHistory, } from '@aragon-agent/core';
 import { getLogger } from '../logging/logger.js';
@@ -328,6 +337,10 @@ export class CompactionWiring {
             live: this.enabled && summarizer !== null,
             model: summarizer?.ref.modelId ?? '',
             compactions: totals.compactions,
+            // OMITTED WHEN ZERO (quiet-noop D-9), so a healthy session's snapshot is
+            // shaped exactly as it was before this feature and `/compact status` has
+            // nothing extra to render.
+            ...(totals.declined > 0 ? { declined: totals.declined } : {}),
             tokensReclaimed: totals.tokensReclaimed,
             usage: totals.usage,
             pricingUnknown: totals.pricingUnknown,
@@ -445,8 +458,16 @@ export class CompactionWiring {
         // compaction no matter which branch the verdict took - including the early
         // `return` below.
         const dropped = this.compactor.takeLastDropped();
-        if (!record)
+        if (!record) {
+            // A SILENT DECLINE (quiet-noop §3.6). No card - but the gauge and the chip
+            // are still refreshed: `inFlight` has just gone false and `/compact status`
+            // reads this same snapshot, which is where the `declined` count surfaces.
+            // `snapshot()` uses the CACHED pressure (`compactor.lastMeasured()`), so
+            // this costs no re-measurement, and guard 4 caps the number of declines per
+            // session at `stuckLimit`.
+            this.emit({ type: 'snapshot', snapshot: this.snapshot() });
             return;
+        }
         const settled = {
             ...record,
             applied: verdict.applied,

package/dist/config/env.d.ts

@@ -7,7 +7,7 @@
  *   - Overrides: ARAGON_PROVIDER, ARAGON_MODEL, ARAGON_BASE_URL, ARAGON_THINKING,
  *     ARAGON_SHOW_THINKING,
  *     ARAGON_MAX_TOKENS (a number, or `auto` / `0` for the per-model ceiling),
- *     ARAGON_THEME, ARAGON_MOUSE, ARAGON_PLAN, ARAGON_TEAM,
+ *     ARAGON_THEME, ARAGON_MOUSE, ARAGON_PASTE, ARAGON_PLAN, ARAGON_TEAM,
  *     ARAGON_TEAM_MAX, ARAGON_RETRY, ARAGON_RETRY_MAX, ARAGON_FAST,
  *     ARAGON_FAST_PROVIDER, ARAGON_FAST_MODEL, ARAGON_FAST_BASE_URL,
  *     ARAGON_LOG_LEVEL,

package/dist/config/env.js

@@ -7,7 +7,7 @@
  *   - Overrides: ARAGON_PROVIDER, ARAGON_MODEL, ARAGON_BASE_URL, ARAGON_THINKING,
  *     ARAGON_SHOW_THINKING,
  *     ARAGON_MAX_TOKENS (a number, or `auto` / `0` for the per-model ceiling),
- *     ARAGON_THEME, ARAGON_MOUSE, ARAGON_PLAN, ARAGON_TEAM,
+ *     ARAGON_THEME, ARAGON_MOUSE, ARAGON_PASTE, ARAGON_PLAN, ARAGON_TEAM,
  *     ARAGON_TEAM_MAX, ARAGON_RETRY, ARAGON_RETRY_MAX, ARAGON_FAST,
  *     ARAGON_FAST_PROVIDER, ARAGON_FAST_MODEL, ARAGON_FAST_BASE_URL,
  *     ARAGON_LOG_LEVEL,
@@ -141,6 +141,13 @@ export function readEnvConfig() {
                 mouseSelect === 'on' ||
                 mouseSelect === 'yes';
     }
+    // ARAGON_PASTE=0 turns paste recognition off, which is the documented one-env
+    // revert to v0.6.3 input handling (tui-paste-handling section 7.2). Parsed by
+    // the POSITIVE list, exactly as its two neighbours above are.
+    const paste = process.env.ARAGON_PASTE?.trim().toLowerCase();
+    if (paste !== undefined && paste.length > 0) {
+        partial.paste = paste === '1' || paste === 'true' || paste === 'on' || paste === 'yes';
+    }
     // ARAGON_SCROLL_RESUME_MS=<n> — idle delay before a paused viewport returns to
     // the newest line; `0` disables auto-resume. THE ONLY CHANNEL BESIDES THE
     // CONFIG FILE, because §6.1 gives this key no CLI flag on purpose. `load.ts`
@@ -239,6 +246,46 @@ export function readEnvConfig() {
         if (Object.keys(section).length > 0)
             partial.todo = section;
     }
+    // ARAGON_BASH_BACKGROUND=0 turns background services off entirely (no
+    // `background` param, no `bash_output`/`bash_kill`, no prompt block, no chip);
+    // ARAGON_BASH_AUTO_BACKGROUND=0 keeps them but stops the classifier firing on
+    // an unset `background`. Parsed by the POSITIVE list, exactly as
+    // ARAGON_FULLSCREEN / ARAGON_MOUSE / ARAGON_PLAN / ARAGON_TEAM / ARAGON_TODO
+    // are - NOT by `envBool` below, which uses a negative list.
+    //
+    // Both pass the test every env var in this file has to pass: an unattended run
+    // in a container with a fixed entrypoint can reach neither a flag nor a config
+    // file, and "do not leave a dev server running in my CI job" is exactly the
+    // kind of decision that channel needs to make.
+    //
+    // ONE ACCUMULATED SECTION, ASSIGNED ONCE - the shape the `team` and `todo`
+    // branches above already use, and NOT two `if` blocks each assigning
+    // `partial.bash` (the `todo` P1-4 trap). THE CAST IS WHAT WOULD MAKE THAT
+    // MISTAKE SILENT: a second assignment compiles clean and drops the first key,
+    // so `ARAGON_BASH_BACKGROUND=0 ARAGON_BASH_AUTO_BACKGROUND=0` would quietly
+    // re-register the tools the user turned off.
+    const bashBackground = process.env.ARAGON_BASH_BACKGROUND?.trim().toLowerCase();
+    const bashAuto = process.env.ARAGON_BASH_AUTO_BACKGROUND?.trim().toLowerCase();
+    if ((bashBackground !== undefined && bashBackground.length > 0) ||
+        (bashAuto !== undefined && bashAuto.length > 0)) {
+        const section = {};
+        if (bashBackground !== undefined && bashBackground.length > 0) {
+            section.background =
+                bashBackground === '1' ||
+                    bashBackground === 'true' ||
+                    bashBackground === 'on' ||
+                    bashBackground === 'yes';
+        }
+        if (bashAuto !== undefined && bashAuto.length > 0) {
+            section.autoBackground =
+                bashAuto === '1' || bashAuto === 'true' || bashAuto === 'on' || bashAuto === 'yes';
+        }
+        // A PARTIAL section, safe only because every consumer deep-merges it - the
+        // same contract `partial.skills`, `partial.log`, `partial.team` and
+        // `partial.todo` rely on.
+        if (Object.keys(section).length > 0)
+            partial.bash = section;
+    }
     // ARAGON_RETRY=0 is the kill switch for API retry; ARAGON_RETRY_MAX=<n>
     // overrides the count. Parsed by the POSITIVE list, exactly as
     // ARAGON_FULLSCREEN / ARAGON_MOUSE / ARAGON_PLAN / ARAGON_TEAM / ARAGON_TODO

package/dist/config/load.d.ts

@@ -49,6 +49,17 @@ export interface CliFlags {
      * `false` on every run (the `--todo-panel` trap).
      */
     mouseSelect?: boolean;
+    /**
+     * `--paste` ⇒ true, `--no-paste` ⇒ false, absent ⇒ undefined
+     * (tui-paste-handling section 7.1).
+     *
+     * DECLARED AS A PAIR, and carried through `toFlags`, for the reason the two
+     * notes above record. `paste` is additionally PERSISTED and defaults to
+     * `true`, so a lone `--no-paste` would make commander default `opts.paste` to
+     * `true` -- indistinguishable from silence, and silently overriding a stored
+     * `false` on every run that passed no flag at all.
+     */
+    paste?: boolean;
     /** `--no-skills` ⇒ false. Turns the whole skill subsystem off (§7.5). */
     skills?: boolean;
     /** `--skill <name>` ×N — force Level 2 injection for this run. */

package/dist/config/load.js

@@ -6,7 +6,7 @@
  * legitimately long single tool run can never be watchdog-killed.
  */
 import process from 'node:process';
-import { DEFAULT_CONFIG, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampCompactionConfig, clampLogConfig, clampFastConfig, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampUpdateConfig, clampTheme, clampThinkingLevel, clampMaxTokens, clampMaxRenderInterval, clampScrollResumeMs, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAutoToken, isSkillsToolPolicyMode, parseThresholdInput, } from './schema.js';
+import { DEFAULT_CONFIG, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampCompactionConfig, clampLogConfig, clampFastConfig, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampBashConfig, clampUpdateConfig, clampTheme, clampThinkingLevel, clampMaxTokens, clampMaxRenderInterval, clampScrollResumeMs, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAutoToken, isSkillsToolPolicyMode, parseThresholdInput, } from './schema.js';
 import { loadDotenv, readEnvConfig, readEnvDisabledSkills } from './env.js';
 import { readConfigFile } from './store.js';
 import { getConfigPath } from './app-paths.js';
@@ -80,6 +80,24 @@ function resolveMouseSelect(flags, env, file) {
         return file.mouseSelect;
     return DEFAULT_CONFIG.mouseSelect;
 }
+/**
+ * Paste handling: flag > env > file > default `true` (tui-paste-handling
+ * section 7.4).
+ *
+ * SHAPED EXACTLY LIKE `resolveMouse` above, for the reason its own note gives:
+ * reaching for the `hints` shape -- `flags.x !== undefined ? ... : file.x ??
+ * DEFAULT`, which reads NO ENV AT ALL -- would ship `ARAGON_PASTE` as
+ * documented-but-dead.
+ */
+function resolvePaste(flags, env, file) {
+    if (flags.paste !== undefined)
+        return flags.paste;
+    if (env.paste !== undefined)
+        return env.paste;
+    if (file.paste !== undefined)
+        return file.paste;
+    return DEFAULT_CONFIG.paste;
+}
 /**
  * Idle scroll-resume delay: env › file › default 5000, clamped to [0, 120000].
  *
@@ -153,6 +171,24 @@ function resolveTodoConfig(flags, env, file) {
         ...(flags.todoFollow !== undefined ? { followThrough: flags.todoFollow } : {}),
     });
 }
+/**
+ * Merge the `bash` section across the three layers that supply it
+ * (defaults > file > env), background-service-supervision §5.4.
+ *
+ * THREE LAYERS, NOT FOUR, AND THAT IS NOT AN OVERSIGHT. There is deliberately no
+ * `--no-background` flag: the two switches this section carries are already
+ * reachable from `config.json` (a per-machine preference) and from the
+ * environment (the channel a container entrypoint has), which is the two-part
+ * test every knob in this file is held to. A third spelling would be a third
+ * place for the answer to differ.
+ */
+function resolveBashConfig(env, file) {
+    return clampBashConfig({
+        ...DEFAULT_CONFIG.bash,
+        ...(file.bash ?? {}),
+        ...(env.bash ?? {}),
+    });
+}
 /**
  * Merge the `retry` section across all four layers (defaults › file › env ›
  * flags), llm-api-retry-backoff §6.2.
@@ -520,6 +556,7 @@ export function loadConfig(flags = {}) {
         hints,
         mouse: resolveMouse(flags, env.partial, file),
         mouseSelect: resolveMouseSelect(flags, env.partial, file),
+        paste: resolvePaste(flags, env.partial, file),
         scrollResumeMs: resolveScrollResumeMs(env.partial, file),
         // From `<home>/state.json`, not the config file — see `ui-state.ts`.
         submitCount: readSubmitCount(),
@@ -545,6 +582,7 @@ export function loadConfig(flags = {}) {
         fast: resolveFastConfig(flags, env.partial, file),
         update: resolveUpdateConfig(flags, env.partial, file),
         compaction: resolveCompactionConfig(flags, env.partial, file),
+        bash: resolveBashConfig(env.partial, file),
         cwd,
         color,
         colorLevel,