aiden-runtime 4.1.5 → 4.6.0

package/dist/cli/v4/callbacks.js

@@ -19,6 +19,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CliCallbacks = void 0;
+exports.mapBlockerToCard = mapBlockerToCard;
 exports.renderApprovalBox = renderApprovalBox;
 const box_1 = require("./box");
 async function defaultPrompts() {
@@ -45,6 +46,68 @@ const DECISION_CHOICES = [
     { name: 'Deny', value: 'deny' },
 ];
 const KNOWN_TIERS = new Set(['safe', 'caution', 'dangerous']);
+// ── v4.3 Phase 3 — manual-blocker card mapping ────────────────────────────
+/** Best-effort hostname extraction; falls back to the raw URL. */
+function blockerHostname(url) {
+    try {
+        return new URL(url).hostname || url;
+    }
+    catch {
+        return url;
+    }
+}
+/**
+ * Map a BlockerSurface to the existing CapabilityCardData chrome.
+ * Pure helper — same shape per `BlockerKind`, parameterised by the
+ * blocker's URL + optional subtype for the body text. The renderer
+ * (`display.capabilityCard`) handles all rendering chrome; this
+ * function only fills the slots semantically.
+ *
+ * Public for unit tests; chatSession + callbacks consume via the
+ * `renderBlockerCardIfPresent` method below.
+ */
+function mapBlockerToCard(blocker) {
+    const host = blockerHostname(blocker.url);
+    const labels = {
+        captcha: {
+            title: `CAPTCHA challenge at ${host}`,
+            canStill: ['Solve the challenge in the browser tab', 'Cancel this task'],
+            cannot: ['Continue automatically without your action'],
+            fix: `I'll wait — solve the ${blocker.subtype ?? 'CAPTCHA'} challenge and tell me when ready.`,
+        },
+        login: {
+            title: `Sign-in required at ${host}`,
+            canStill: ['Sign in via the browser tab', 'Cancel this task'],
+            cannot: ['Continue without authentication'],
+            fix: `I'll wait — sign in and let me know when done.`,
+        },
+        '2fa': {
+            title: `Two-factor code required at ${host}`,
+            canStill: ['Enter the 2FA code in the browser tab', 'Cancel this task'],
+            cannot: ['Continue without the verification code'],
+            fix: `I'll wait — enter your code and tell me when complete.`,
+        },
+        verification: {
+            title: `Identity verification at ${host}`,
+            canStill: ['Complete the verification in the browser', 'Cancel this task'],
+            cannot: ['Continue without verification'],
+            fix: `I'll wait — finish the verification and tell me when done.`,
+        },
+        consent: {
+            title: `Consent banner at ${host}`,
+            canStill: ['Dismiss the banner in the browser', 'Continue if banner is dismissable'],
+            cannot: ['Reliably interact with content while the banner blocks it'],
+            fix: `Dismiss the cookie or privacy banner and I'll retry.`,
+        },
+    };
+    const t = labels[blocker.kind];
+    return {
+        title: `🛑 ${t.title}`,
+        canStill: t.canStill,
+        cannotReliably: t.cannot,
+        fix: t.fix,
+    };
+}
 function parseRiskTier(content) {
     const head = content.trim().toLowerCase().split(/\s+/)[0] ?? '';
     // Strip punctuation that might bleed in from JSON: "safe.", "caution,"...
@@ -161,6 +224,17 @@ class CliCallbacks {
                 catch { /* defensive */ }
                 return;
             }
+            // v4.3 Phase 3 — render a structured "agent needs human help"
+            // card when the browser observer detected a manual blocker
+            // (CAPTCHA / login / 2FA / verification / consent). Renders for
+            // ALL trail-row outcomes below — the blocker is independent of
+            // the tool's own success/fail signal. Inline placement gives
+            // the user immediate awareness; the model's next reply will
+            // explain in prose. Defensive: missing fields silently skip.
+            try {
+                this.renderBlockerCardIfPresent(result);
+            }
+            catch { /* defensive */ }
             // v4.1.4 reply-quality polish — Part 1.6. Helper used by ALL
             // outcome branches below so the activity indicator gets re-armed
             // for the gap that follows this tool (next tool, or final reply).
@@ -353,12 +427,84 @@ Reply with ONE word: safe, caution, or dangerous.`;
             const label = files.length > 0 ? files.join(', ') : 'none';
             this.display.dim(`[memory] refreshed system prompt (${label})`);
         };
+        /**
+         * v4.1.6 Polish 2 — post-turn skill-proposal handler.
+         *
+         * chatSession calls this AFTER `agentTurn` has rendered the agent's
+         * reply on screen. Internally:
+         *   1. Reuses `promptSkillProposal` (the existing inquirer modal)
+         *      to ask the user "Save this as a reusable skill? Yes/No".
+         *   2. If accepted AND a SkillTeacher reference is wired, calls
+         *      `skillTeacher.handleProposal({...skipPrompt})` to build
+         *      the markdown + persist via skillManager.
+         *   3. Returns the result so chatSession can surface a confirmation
+         *      line if needed.
+         *
+         * Decoupled from the agent's `runConversation` so the inquirer no
+         * longer fires mid-turn (the v4.1.5 visual-smoke regression).
+         *
+         * Defensive — exceptions in any step return `{created: false,
+         * reason: 'error'}` so a misbehaving prompt or save can't break
+         * the chat loop. The inquirer modal itself catches input-stream
+         * exceptions via the existing try/catch in promptSkillProposal.
+         */
+        this.handleSkillProposal = async (proposal) => {
+            // Step 1: ask the user (reuses existing modal).
+            let accept;
+            try {
+                accept = await this.promptSkillProposal(proposal);
+            }
+            catch {
+                return { created: false, reason: 'prompt_error' };
+            }
+            if (!accept) {
+                return { created: false, reason: 'declined' };
+            }
+            // Step 2: persist via SkillTeacher when available. Test harnesses
+            // that don't wire a teacher just get the prompt without the save.
+            if (!this.skillTeacher) {
+                return { created: false, reason: 'no_skill_teacher_wired' };
+            }
+            try {
+                // Pass `promptUser: undefined` to bypass the modal in
+                // `handleProposal` (we already showed it above). The teacher
+                // sees tier === 'tier_3_propose' WITHOUT a prompt callback,
+                // which it interprets as `no_prompt_callback` and skips the
+                // save — so we need to call the create branch directly.
+                //
+                // SkillTeacher's tier-4 (auto) branch creates without
+                // prompting; we reuse that path by passing a stub that always
+                // returns true (user already accepted above).
+                const result = await this.skillTeacher.handleProposal(proposal, {
+                    promptUser: async () => true,
+                });
+                return result;
+            }
+            catch (err) {
+                return {
+                    created: false,
+                    reason: `create_failed: ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+        };
         this.display = opts.display;
         this.auxiliaryClient = opts.auxiliaryClient;
         this.verboseMode = opts.verboseMode ?? 'normal';
         this.promptsPromise = opts.promptModule
             ? Promise.resolve(opts.promptModule)
             : defaultPrompts();
+        this.skillTeacher = opts.skillTeacher;
+    }
+    /**
+     * v4.1.6 Polish 2 — late-wire the SkillTeacher reference. aidenCLI
+     * constructs CliCallbacks early (the approval engine needs it
+     * stitched in), but SkillTeacher is built later in the boot
+     * sequence after skillLoader / skillManager are ready. Call this
+     * once after both exist so `handleSkillProposal` can persist
+     * accepted proposals.
+     */
+    setSkillTeacher(teacher) {
+        this.skillTeacher = teacher;
     }
     /** Update verbose mode at runtime (wired to /verbose). */
     setVerboseMode(mode) {
@@ -415,6 +561,30 @@ Reply with ONE word: safe, caution, or dangerous.`;
         this.toolTraceBeforeHook = opts.before;
         this.toolTraceAfterHook = opts.after;
     }
+    /**
+     * v4.3 Phase 3 — render a manual-blocker card when the browser
+     * observer detected a CAPTCHA / login / 2FA / verification /
+     * consent surface on the page. Reuses the existing capabilityCard
+     * chrome via a `mapBlockerToCard` semantic mapping — no new layout
+     * code, no new dedicated card component.
+     *
+     * Defensive: silently skips when the field shape doesn't match
+     * (no browserState, no blocker, unrecognised kind). Never throws
+     * — caller wraps in try/catch defensively.
+     *
+     * The blocker info is structural data emitted by the observer
+     * HOC (`tools/v4/browser/_observer.ts`); the renderer reads it
+     * from `result.result.browserState.blocker` after every browser
+     * tool call. Inline placement gives users immediate awareness
+     * before the model's next reply lands.
+     */
+    renderBlockerCardIfPresent(result) {
+        const inner = (result?.result ?? null);
+        const blocker = inner?.browserState?.blocker;
+        if (!blocker)
+            return;
+        this.display.capabilityCard(mapBlockerToCard(blocker));
+    }
 }
 exports.CliCallbacks = CliCallbacks;
 // Tier-3.1 (v4.1-tier3.1): replaced 🟢/🟡/🔴 emoji badges with

package/dist/cli/v4/chatSession.js

@@ -872,6 +872,21 @@ class ChatSession {
         }
     }
     async runAgentTurn(userInput) {
+        // v4.5 Phase 8b — daemon-scheduling intent check on the user's
+        // initial message. Classifies regex hits like "every day at",
+        // "watch this folder", "when an email arrives" — and queues a
+        // tip to render at the END of the agent's response (so it
+        // doesn't crowd the agent's actual reply). Engine handles
+        // budget + dismissal.
+        let _deferredTip = null;
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { getSuggestionEngine } = require('../../core/v4/suggestionEngine');
+            const t = getSuggestionEngine().checkInitialMessage(userInput);
+            if (t)
+                _deferredTip = t;
+        }
+        catch { /* defensive — never block a turn on a suggestion */ }
         // Phase 30.2.1 — explore mode: short-circuit BEFORE building the
         // turn-status spinner / agent call. The wizard skipped, so there's
         // no real provider to talk to. Print a friendly redirect to /setup
@@ -907,6 +922,43 @@ class ChatSession {
         const baseHistory = newHistory.length > 0
             ? [...this.history, ...newHistory, userMsg]
             : [...this.history, userMsg];
+        // v4.6 Phase 2Q-B — REPL parent-run row (best-effort).
+        //
+        // Insert a `runs` row tagged with this REPL session BEFORE the
+        // agent loop dispatches. Capture the row id into the shared
+        // `replParentRunRef` so any `spawn_sub_agent` / `subagent_fanout`
+        // child this turn produces can link back via
+        // `spawned_from_run_id`. The ref is cleared in the catch /
+        // success paths below regardless of outcome.
+        //
+        // Defensive: a runStore write failure (locked DB, schema drift,
+        // etc.) must NOT crash the REPL — every persistence call here is
+        // wrapped in try/catch and reduces to a logged warning. The
+        // user-facing turn still runs.
+        let replRunId = null;
+        const replRunStore = this.opts.replRunStore;
+        const replInstanceId = this.opts.replInstanceId;
+        const replParentRunRef = this.opts.replParentRunRef;
+        if (replRunStore && replInstanceId && this.sessionId) {
+            try {
+                replRunId = replRunStore.create({
+                    sessionId: this.sessionId,
+                    instanceId: replInstanceId,
+                    status: 'running',
+                    startedAt: turnStartedAt,
+                });
+                if (replParentRunRef) {
+                    replParentRunRef.runId = replRunId;
+                    replParentRunRef.sessionId = this.sessionId;
+                }
+            }
+            catch (err) {
+                // Logged once per turn; the user's chat is not interrupted.
+                // eslint-disable-next-line no-console
+                console.warn('[runs] failed to write REPL parent-run row:', err instanceof Error ? err.message : String(err));
+                replRunId = null;
+            }
+        }
         // Phase 16c: streaming gated on display.streaming config.
         // v4.1.4 Part 1.6: PRODUCTION DEFAULT FLIPPED FROM FALSE TO TRUE.
         // Streaming delivers the activity indicator, tool-row live tick,
@@ -1164,6 +1216,35 @@ class ChatSession {
             this.history = result.messages;
             this.totalUsage.inputTokens += result.totalUsage.inputTokens;
             this.totalUsage.outputTokens += result.totalUsage.outputTokens;
+            // v4.6 Phase 2Q-B — finalize the REPL parent-run row on success.
+            // `finishReason` from the agent loop maps directly into our DB
+            // status: `stop` → completed; `interrupted` / `tool_loop` →
+            // surface as 'interrupted' so it's visible in `runs list`;
+            // `budget_exhausted` / `error` → failed. Wrapped in try/catch
+            // so even a runStore write failure here can't crash the REPL.
+            if (replRunStore && replRunId !== null) {
+                try {
+                    const dbStatus = result.finishReason === 'stop' ? 'completed' :
+                        result.finishReason === 'interrupted' ? 'interrupted' :
+                            result.finishReason === 'tool_loop' ? 'interrupted' :
+                                'failed';
+                    replRunStore.setStatus(replRunId, dbStatus, {
+                        finishReason: result.finishReason,
+                        completedAt: Date.now(),
+                    });
+                }
+                catch (err) {
+                    // eslint-disable-next-line no-console
+                    console.warn('[runs] failed to finalize REPL parent-run row:', err instanceof Error ? err.message : String(err));
+                }
+            }
+            // Clear the shared ref so a subsequent turn (or stray
+            // spawn/fanout dispatched between turns from a slash command
+            // handler) doesn't see a stale parent id.
+            if (replParentRunRef) {
+                replParentRunRef.runId = null;
+                replParentRunRef.sessionId = null;
+            }
             // Phase 16d: surface inline confirmations for verified memory writes.
             // We MUST gate on verified=true (the post-write read flag from
             // MemoryGuard) — HonestyEnforcement uses the same flag to catch
@@ -1178,9 +1259,25 @@ class ChatSession {
             if (result.toolCallTrace && result.toolCallTrace.length > 0) {
                 this.sessionToolTrace.push(...result.toolCallTrace);
             }
-            // When streaming was active and emitted the final content already,
-            // skip the markdown re-render — we'd otherwise duplicate text.
-            if (result.finalContent && !streamingActive) {
+            // v4.1.6 spike (TCE) — tool-loop terminal surface. When the
+            // agent ended the turn via the recovery controller's surface
+            // stage, render a structured-failure card instead of the
+            // (empty) reply. Same chrome as auth / platform capability
+            // cards — fits the established Aiden UX language for
+            // "the action you wanted didn't happen, here's why and what
+            // you can do." Surface BEFORE the tool→reply separator path
+            // below because there's no agent reply to introduce.
+            if (result.finishReason === 'tool_loop' && result.toolLoopCard) {
+                // Emit the muted rule so the card visually separates from
+                // the tool trail above it.
+                emitToolReplySeparator();
+                this.opts.display.capabilityCard(result.toolLoopCard);
+            }
+            else if (result.finalContent && !streamingActive) {
+                // When streaming was active and emitted the final content
+                // already, skip the markdown re-render — we'd otherwise
+                // duplicate text.
+                //
                 // v4.1.5 Issue O — non-streaming reply path. Emit the muted
                 // rule between the tool trail and the agent header before
                 // the one-shot reply lands. Idempotent + tool-gated by
@@ -1188,6 +1285,30 @@ class ChatSession {
                 emitToolReplySeparator();
                 this.opts.display.write(this.opts.display.agentTurn(result.finalContent));
             }
+            // v4.1.6 Polish 2 — post-render skill-proposal handler.
+            // The agent loop now SKIPS the inquirer prompt when a
+            // prompt callback is wired, surfacing the SkillProposal
+            // here instead. We fire the prompt AFTER the agent reply
+            // has rendered so the user sees the answer before being
+            // asked "save this as a reusable skill?" — fixing the
+            // v4.1.5 visual-smoke regression where the prompt fired
+            // mid-turn and clobbered the reply.
+            //
+            // Wrapped in try/catch so a buggy proposal flow never
+            // breaks the chat loop. A successful save surfaces a
+            // dim confirmation line that fits the established
+            // memory-confirmation chrome.
+            if (result.skillProposal && this.opts.callbacks?.handleSkillProposal) {
+                try {
+                    const saveResult = await this.opts.callbacks.handleSkillProposal(result.skillProposal);
+                    if (saveResult?.created && saveResult.skillName) {
+                        this.opts.display.dim(`  ✓ Saved as skill: ${saveResult.skillName}`);
+                    }
+                }
+                catch {
+                    /* defensive — never let proposal flow break the chat loop */
+                }
+            }
             if (this.sessionId) {
                 // Only persist the new tail of messages — what got added this turn.
                 const newSlice = this.history.slice(turnStart);
@@ -1195,6 +1316,20 @@ class ChatSession {
             }
             this.setStatusState({ kind: 'ready' });
             this.lastTurnElapsedMs = Date.now() - turnStartedAt;
+            // v4.5 Phase 8b — surface a deferred daemon-scheduling tip
+            // queued at turn start. Renders AFTER the agent's response per
+            // Q-P8b-3(b) — the user reads the answer first, then sees the
+            // ambient capability hint.
+            if (_deferredTip) {
+                try {
+                    this.opts.display.dim(_deferredTip.message);
+                    // eslint-disable-next-line @typescript-eslint/no-var-requires
+                    const { getSuggestionEngine } = require('../../core/v4/suggestionEngine');
+                    getSuggestionEngine().recordFired(_deferredTip.slot);
+                }
+                catch { /* defensive */ }
+                _deferredTip = null;
+            }
             // Tier-3.1a: dim full-width rule between the agent reply and the
             // post-turn status footer.
             this.opts.display.write(`  ${this.opts.display.rule()}\n`);
@@ -1220,6 +1355,26 @@ class ChatSession {
             progressBar?.hide();
             if (streamingActive)
                 this.opts.display.streamComplete();
+            // v4.6 Phase 2Q-B — finalize REPL parent-run row on error.
+            // Visible in `aiden runs list` as a failed top-level row so
+            // operators can correlate a chat error with whatever children
+            // it had already kicked off this turn.
+            if (replRunStore && replRunId !== null) {
+                try {
+                    replRunStore.setStatus(replRunId, 'failed', {
+                        finishReason: 'error',
+                        completedAt: Date.now(),
+                    });
+                }
+                catch (e2) {
+                    // eslint-disable-next-line no-console
+                    console.warn('[runs] failed to mark REPL parent-run failed:', e2 instanceof Error ? e2.message : String(e2));
+                }
+            }
+            if (replParentRunRef) {
+                replParentRunRef.runId = null;
+                replParentRunRef.sessionId = null;
+            }
             const msg = err?.message ?? String(err);
             // v4.1.3-prebump: classify the error so the suggestion below
             // points at the actual fix instead of the generic "/model or
@@ -1349,6 +1504,30 @@ class ChatSession {
             providerOk: !this.opts.unconfigured,
             version: version_1.VERSION,
         }) + '\n');
+        // v4.6 Phase 3A — operator kill-switch indicator. Lands ABOVE
+        // the blank-line + provider-source annotation so an operator
+        // who paused in a prior session sees the state immediately on
+        // boot, alongside the standard status pills. Single dim
+        // warning line; no special chrome — the message itself is the
+        // visual signal.
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { getSpawnPause } = require('../../core/v4/subagent/spawnPause');
+            const s = getSpawnPause().status();
+            if (s.paused) {
+                const reasonSuffix = s.reason ? ` · ${s.reason}` : '';
+                const durationSuffix = typeof s.durationMs === 'number'
+                    ? ` · ${formatDuration(s.durationMs)}`
+                    : '';
+                display.warn(`spawn-pause: ON${reasonSuffix}${durationSuffix} — use /spawn-pause off to resume`);
+            }
+        }
+        catch {
+            // Singleton not initialised (test stubs, etc.) — silently skip.
+        }
+        // v4.5 TUI polish — blank line so the status pills row doesn't
+        // crowd the muted source annotation right beneath it.
+        display.write('\n');
         // v4.1.3-prebump: dim source annotation under the pills row so the
         // user can see WHY this provider/model was chosen — closes the
         // information gap that made Case 3 (persisted-config) look like a
@@ -1408,10 +1587,73 @@ class ChatSession {
         }
         // Scroll footer (parchment at ≥80 cols, single-line credits below).
         display.write(display.scrollFooter() + '\n');
+        // v4.5 update system — boxed three-option prompt rendered AFTER
+        // the boot card / status pills (Q-U5b less-intrusive position),
+        // BEFORE the bottomPromptHint. Fires only when:
+        //   - update check came back with `updateAvailable && !skipped`
+        //   - stdin is a TTY (non-interactive boots short-circuit to 'later')
+        // 5-second timeout defaults to 'later' so a user away from
+        // keyboard isn't held up. Skip-on-'n' writes the version to the
+        // .update_check.json cache so subsequent boots stay quiet until
+        // a newer release ships.
+        try {
+            await this.maybeShowBootUpdatePrompt();
+        }
+        catch { /* never let the update prompt crash boot */ }
         // Bottom prompt hint — final line of the boot card.
         display.write('\n');
         display.write(display.bottomPromptHint() + '\n');
     }
+    /**
+     * v4.5 update system — orchestrates the boot prompt. Lazy-imports
+     * the update modules so non-boot code paths (e.g. test harness
+     * sessions constructed without paths wired) don't pay the cost.
+     */
+    async maybeShowBootUpdatePrompt() {
+        if (!this.opts.paths)
+            return;
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const cu = require('../../core/v4/update/checkUpdate');
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const md = require('../../core/v4/update/installMethodDetect');
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const ss = require('../../core/v4/update/skipState');
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const bp = require('./updateBootPrompt');
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const ei = require('../../core/v4/update/executeInstall');
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const ver = require('../../core/version');
+        const status = await cu.checkForUpdate({ paths: this.opts.paths, installedVersion: ver.VERSION });
+        if (!status.updateAvailable || !status.latest || status.skipped)
+            return;
+        const method = md.detectInstallMethod();
+        const choice = await bp.showBootUpdatePrompt({
+            status, method,
+            display: { write: (s) => this.opts.display.write(s), dim: (s) => this.opts.display.dim(s) },
+        });
+        if (choice === 'install') {
+            if (method.inProcessInstallSupported) {
+                this.opts.display.write(`Installing aiden-runtime ${status.latest}…\n`);
+                const result = await ei.executeInstall({ packageSpec: `aiden-runtime@${status.latest}` });
+                if (result.success) {
+                    this.opts.display.write(`  ✓ aiden-runtime ${result.installedVersion ?? status.latest} installed.\n`);
+                    this.opts.display.dim('Restart Aiden to apply: type /quit then re-run `aiden`.');
+                }
+                else {
+                    this.opts.display.warn(result.error ?? 'Install failed (no error message).');
+                }
+            }
+            else {
+                this.opts.display.write(`To update, run:\n  ${method.updateCommand(status.latest)}\n`);
+            }
+        }
+        else if (choice === 'skip') {
+            await cu.updateCacheFile(this.opts.paths, (current) => ss.applySkip(current, status.latest));
+            this.opts.display.dim(`  skipped ${status.latest}. Boot prompt resumes when a newer version ships.`);
+        }
+        // 'later' = no-op; prompt fires again next session.
+    }
     /** Phase 22 Task 4: state transitions for the right-most segment. */
     setStatusState(state) {
         this.statusState = state;

package/dist/cli/v4/commands/_runtimeToggleHelpers.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/commands/_runtimeToggleHelpers.ts — v4.5 Phase 8a.
+ *
+ * Shared `flip` + `printStatus` helpers used by /sandbox, /tce, and
+ * /browser-depth. Each subsystem command is a tiny wrapper over
+ * these — same on/off/status surface, same status format.
+ *
+ * The persist path goes through `ConfigManager.set()` + `save()` so
+ * the runtime_toggles section is written verbatim to config.yaml.
+ * The runtimeToggles singleton's `set()` then fires onChange
+ * callbacks for cached consumers (sandboxConfig's singleton).
+ *
+ * Test seam: `flip` and `printStatus` accept a `ctx` shaped like
+ * SlashCommandContext (just `display`, optionally `config`). Tests
+ * pass a minimal stub.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flip = flip;
+exports.printStatus = printStatus;
+exports.parseSubcommand = parseSubcommand;
+const runtimeToggles_1 = require("../../../core/v4/runtimeToggles");
+const LABEL = {
+    sandbox: 'Sandbox',
+    tce: 'TCE',
+    browser_depth: 'Browser depth',
+    suggestions: 'Suggestions',
+    planner_guard: 'Planner-Guard',
+};
+const CONFIG_DOTTED = {
+    sandbox: 'runtime_toggles.sandbox',
+    tce: 'runtime_toggles.tce',
+    browser_depth: 'runtime_toggles.browser_depth',
+    suggestions: 'runtime_toggles.suggestions',
+    planner_guard: 'runtime_toggles.planner_guard',
+};
+/**
+ * Apply a toggle change. When `ctx.config` is wired, persists to
+ * config.yaml. Otherwise the flip is in-process only (current
+ * session sees the new value; next process boot doesn't).
+ *
+ * Returns nothing — prints status via ctx.display.
+ */
+async function flip(key, value, ctx) {
+    const rt = (0, runtimeToggles_1.getRuntimeToggles)();
+    // Persist when a ConfigManager is wired.
+    if (ctx.config) {
+        try {
+            ctx.config.set(CONFIG_DOTTED[key], value);
+            await ctx.config.save();
+        }
+        catch (e) {
+            ctx.display.warn(`[${key}] config.yaml save failed (${e instanceof Error ? e.message : String(e)}); ` +
+                `flip applies to this session only.`);
+        }
+    }
+    await rt.set(key, value, { persist: false });
+    printStatus(key, ctx);
+}
+/**
+ * Print the current state of one toggle. One-line output per
+ * Q-P8a-2(a):
+ *
+ *   `Sandbox: ON   (source: config)`
+ *
+ * `source` reveals which precedence layer provided the value —
+ * critical for debugging "why is it ON when my .env says 0".
+ */
+function printStatus(key, ctx) {
+    const snap = (0, runtimeToggles_1.getRuntimeToggles)().snapshot()[key];
+    const label = LABEL[key];
+    const state = snap.value ? 'ON' : 'OFF';
+    ctx.display.write(`${label}: ${state}   (source: ${snap.source})\n`);
+}
+/**
+ * Parse the on/off/status subcommand. Returns null when the input
+ * is unrecognised (caller prints usage).
+ */
+function parseSubcommand(raw) {
+    const s = (raw ?? 'status').toLowerCase();
+    if (s === 'on' || s === 'enable' || s === '1' || s === 'true')
+        return 'on';
+    if (s === 'off' || s === 'disable' || s === '0' || s === 'false')
+        return 'off';
+    if (s === 'status' || s === '' || s === undefined)
+        return 'status';
+    return null;
+}

package/dist/cli/v4/commands/browserDepth.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/commands/browserDepth.ts — v4.5 Phase 8a.
+ *
+ * `/browser-depth on|off|status` — flip the v4.3 state-aware
+ * browser observer (URL/DOM/iframe-tree capture, stale-ref retry,
+ * manual-blocker detection) without restart. Persists to
+ * config.yaml. Env var AIDEN_BROWSER_DEPTH always wins.
+ *
+ * Q-P8a-5(a): named `/browser-depth` to mirror the env var
+ * exactly. Reserves `/browser` for future browser-navigation
+ * commands so the namespace stays unambiguous.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.browserDepth = void 0;
+const _runtimeToggleHelpers_1 = require("./_runtimeToggleHelpers");
+exports.browserDepth = {
+    name: 'browser-depth',
+    description: 'Toggle the v4.3 state-aware browser observer.',
+    category: 'system',
+    icon: '🌐',
+    handler: async (ctx) => {
+        const sub = (0, _runtimeToggleHelpers_1.parseSubcommand)(ctx.args[0]);
+        if (sub === 'on') {
+            await (0, _runtimeToggleHelpers_1.flip)('browser_depth', true, ctx);
+            return {};
+        }
+        if (sub === 'off') {
+            await (0, _runtimeToggleHelpers_1.flip)('browser_depth', false, ctx);
+            return {};
+        }
+        if (sub === 'status') {
+            (0, _runtimeToggleHelpers_1.printStatus)('browser_depth', ctx);
+            return {};
+        }
+        ctx.display.printError('Usage: /browser-depth on|off|status');
+        return {};
+    },
+};