@pellux/goodvibes-tui 1.19.5 → 1.20.0

package/docs/README.md

@@ -8,10 +8,10 @@ This directory contains the current product documentation for `goodvibes-tui`.
   Installation, first-run setup, provider configuration, common paths, and basic run/build flows.
 
 - [Configuration reference](configuration.md)
-  TUI-owned settings namespaces you add by hand to settings.json: checkpoint root guard, the scriptable statusline, session behavior, and launch-time self-update.
+  The layered settings model, the key-settings table, permission modes and the policy/trust system, plus the TUI-owned namespaces you add by hand to settings.json: checkpoint root guard, the scriptable statusline, session behavior, and launch-time self-update.
 
 - [Deployment and services](deployment-and-services.md)
-  TUI-only mode, compiled binary behavior, in-process daemon/listener hosting, source-run daemon mode, inbound TLS, outbound trust configuration, and control-plane entrypoints.
+  TUI-only mode, compiled binary behavior, in-process daemon/listener hosting, source-run daemon mode, inbound TLS, outbound trust configuration, control-plane entrypoints, the service registry and secret references, profiles and setup transfer, and integration helpers.
 
 - [Remote access: a home server setup](remote-access.md)
   Step-by-step continuity setup: daemon on an always-on box, webui from any browser, TUI over SSH, Tailscale for reachability and TLS, validated by `goodvibes doctor`.
@@ -47,10 +47,10 @@ This directory contains the current product documentation for `goodvibes-tui`.
   Global flags reference: session lifecycle (`--continue`, `--resume`, `--fork`), confirmation bypass (`-y`/`--non-interactive`), output format consolidation, `--host` alias, and all other startup flags.
 
 - [Tools and commands](tools-and-commands.md)
-  Built-in tool families, slash-command families, and the operator/workflow surfaces that tie them together.
+  Built-in tool families and a per-tool reference, slash-command families, the full keyboard-binding reference, the agent/archetype and hook systems, MCP and plugin extensibility, and the operator, diagnostics, and workflow surfaces that tie them together.
 
 - [QEMU sandbox bootstrapping](qemu-sandbox.md)
-  Host prerequisites, generated QEMU setup bundle files, Debian cloud-image bootstrapping, guest runtime installs, validation, and troubleshooting.
+  Sandbox isolation modes, host prerequisites, generated QEMU setup bundle files, Debian cloud-image bootstrapping, guest runtime installs, validation, and troubleshooting.
 
 - [Release and publishing](release-and-publishing.md)
   Release validation, GitHub CD, compiled binary releases, npm distribution, and the GitHub Packages mirror.

package/docs/foundation-artifacts/operator-contract.json

@@ -3,7 +3,7 @@
   "product": {
     "id": "goodvibes",
     "surface": "operator",
-    "version": "1.11.4"
+    "version": "1.12.0"
   },
   "auth": {
     "modes": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-tui",
-  "version": "1.19.5",
+  "version": "1.20.0",
   "description": "Terminal-native GoodVibes product for coding, operations, automation, knowledge, channels, and daemon-backed control-plane workflows.",
   "type": "module",
   "main": "src/main.ts",
@@ -104,8 +104,8 @@
     "@anthropic-ai/vertex-sdk": "^0.16.0",
     "@ast-grep/napi": "^0.42.0",
     "@aws/bedrock-token-generator": "^1.1.0",
-    "@pellux/goodvibes-sdk": "1.11.4",
-    "@pellux/goodvibes-terminal-shell": "1.11.4",
+    "@pellux/goodvibes-sdk": "1.12.0",
+    "@pellux/goodvibes-terminal-shell": "1.12.0",
     "bash-language-server": "^5.6.0",
     "fuse.js": "^7.1.0",
     "graphql": "^16.13.2",
@@ -131,10 +131,10 @@
     "typescript": "^5.9.3"
   },
   "optionalDependencies": {
-    "@pellux/goodvibes-tui-linux-x64": "1.19.5",
-    "@pellux/goodvibes-tui-linux-arm64": "1.19.5",
-    "@pellux/goodvibes-tui-darwin-x64": "1.19.5",
-    "@pellux/goodvibes-tui-darwin-arm64": "1.19.5"
+    "@pellux/goodvibes-tui-linux-x64": "1.20.0",
+    "@pellux/goodvibes-tui-linux-arm64": "1.20.0",
+    "@pellux/goodvibes-tui-darwin-x64": "1.20.0",
+    "@pellux/goodvibes-tui-darwin-arm64": "1.20.0"
   },
   "trustedDependencies": [],
   "overrides": {

package/src/cli/ensure-goodvibes-gitignore.ts

@@ -13,20 +13,32 @@ import { join } from 'node:path';
  */
 const GOODVIBES_IGNORE_PATTERN = /(^|\n)[ \t]*\/?\.goodvibes\/?\*?[ \t]*(\n|$)/;
 
-export function ensureGoodvibesGitignore(projectRoot: string): void {
+/**
+ * Ensures the project's .gitignore excludes .goodvibes/, appending the rule
+ * exactly once if it is verifiably absent.
+ *
+ * @returns true only the FIRST time the rule is actually written this call —
+ * i.e. this specific invocation just appended/created it. Every subsequent
+ * launch (rule already present) and every no-op case (not a git repo, or the
+ * write failed) return false. The caller uses this to print a one-time
+ * notice instead of staying silent about an edit to the user's own project file.
+ */
+export function ensureGoodvibesGitignore(projectRoot: string): boolean {
   try {
-    if (!existsSync(join(projectRoot, '.git'))) return; // only matters for git projects
+    if (!existsSync(join(projectRoot, '.git'))) return false; // only matters for git projects
     const gitignorePath = join(projectRoot, '.gitignore');
     const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf-8') : '';
-    if (GOODVIBES_IGNORE_PATTERN.test(existing)) return; // already excluded
+    if (GOODVIBES_IGNORE_PATTERN.test(existing)) return false; // already excluded
     const rule = '# goodvibes-tui transient state\n.goodvibes/\n';
     if (existing.length === 0) {
       writeFileSync(gitignorePath, rule);
-      return;
+      return true;
     }
     const separator = existing.endsWith('\n') ? '\n' : '\n\n';
     appendFileSync(gitignorePath, separator + rule);
+    return true;
   } catch {
     // Best-effort only — never block startup on a gitignore write failure.
+    return false;
   }
 }

package/src/cli/entrypoint.ts

@@ -104,7 +104,11 @@ export async function prepareShellCliRuntime(
     homeDirectory: bootstrapHomeDirectory,
   } = resolveShellEntrypointOwnership(roots, cli.flags.workingDir ?? (cli.command === 'tui' ? cli.commandArgs[0] : undefined));
   configureActivityLogger(join(bootstrapWorkingDir, '.goodvibes', 'logs'));
-  ensureGoodvibesGitignore(bootstrapWorkingDir);
+  // Only prints the first time the rule is actually appended (not on every
+  // launch) — see ensureGoodvibesGitignore's return-value doc.
+  if (ensureGoodvibesGitignore(bootstrapWorkingDir)) {
+    console.log("[goodvibes] added '.goodvibes/' to .gitignore — this directory holds transient TUI state (logs, session cache, exec output), not project source.");
+  }
   const configManager = new ConfigManager({
     workingDir: bootstrapWorkingDir,
     homeDir: bootstrapHomeDirectory,

package/src/cli/launch-auto-update.ts

@@ -14,6 +14,14 @@
  *   - a successful update restarts into the new binary and the restarted
  *     process prints a receipt naming both versions, so the swap is never
  *     silent.
+ *   - the install gets a budget too, and running out of it is reported for
+ *     what actually happened rather than assumed. The budget cancels the work
+ *     through a real AbortSignal, so a download that is still in flight is
+ *     genuinely stopped and "deferred — will retry next launch" is true. Once
+ *     the swap has begun it is never interrupted, so that outcome says the
+ *     binary WAS replaced and asks for a restart instead. The two are told
+ *     apart by the swap state the install reports back (UpdateSwapProgress),
+ *     never by guessing.
  *   - every swap keeps the outgoing file at `<path>.previous`; rollback is
  *     one command (`/update rollback`).
  *
@@ -29,7 +37,12 @@
  */
 import { spawnSync } from 'node:child_process';
 import { detectInstallKind, normalizeVersion, type UpdateFetchLike } from '../runtime/update-check.ts';
-import { applyUpdate, checkForUpdate, type ApplyUpdateOptions } from '../input/commands/update-runtime.ts';
+import {
+  applyUpdate,
+  checkForUpdate,
+  createUpdateSwapProgress,
+  type ApplyUpdateOptions,
+} from '../input/commands/update-runtime.ts';
 import { readUpdateSettings, type UpdateSettings } from '../config/tui-extension-settings.ts';
 import type { ConfigManager } from '../config/index.ts';
 import { VERSION } from '../version.ts';
@@ -46,10 +59,23 @@ export const LAUNCH_UPDATED_FROM_ENV = 'GOODVIBES_LAUNCH_UPDATED_FROM';
 /** Default budget for the launch-time version check; user-tunable via update.launchCheckTimeoutMs. */
 export const LAUNCH_UPDATE_CHECK_TIMEOUT_MS = 2500;
 
+/** Default budget for the launch-time download+verify+swap; user-tunable via update.applyTimeoutMs. Generous — a binary download over a slow connection genuinely takes a while — but bounded so launch is never held hostage. */
+export const LAUNCH_APPLY_TIMEOUT_MS = 45_000;
+
 export type LaunchAutoUpdateOutcome =
   | {
       readonly action: 'continue';
-      readonly reason: 'just-updated' | 'disabled' | 'not-swappable-install' | 'already-current' | 'check-skipped' | 'update-failed';
+      readonly reason:
+        | 'just-updated'
+        | 'disabled'
+        | 'not-swappable-install'
+        | 'already-current'
+        | 'check-skipped'
+        | 'update-failed'
+        /** The budget ran out before anything was written, and the work was cancelled. */
+        | 'update-deferred'
+        /** The budget ran out after the swap had begun; the swap finished, so a restart picks up the new version. */
+        | 'update-in-background';
     }
   | { readonly action: 'restart'; readonly latestTag: string };
 
@@ -66,6 +92,8 @@ export interface RunLaunchAutoUpdateOptions {
   /** Injectable so tests observe the install step instead of swapping real files. */
   readonly apply?: (options: ApplyUpdateOptions) => Promise<void>;
   readonly timeoutMs?: number;
+  /** Overrides the download+verify+swap budget; defaults to settings.applyTimeoutMs ?? LAUNCH_APPLY_TIMEOUT_MS. */
+  readonly applyTimeoutMs?: number;
 }
 
 /** Resolves to 'timeout' when `promise` does not settle within `ms`; the timer never keeps the process alive. */
@@ -114,16 +142,24 @@ export async function runLaunchAutoUpdate(options: RunLaunchAutoUpdateOptions):
     check = 'timeout';
   }
   if (check === 'timeout') {
-    options.print('update check skipped: offline');
+    // Honest about WHY the check was skipped — a timeout most commonly means
+    // the update server could not be reached in time, not necessarily that
+    // the whole machine is offline (a slow/flaky connection is just as
+    // common), so this no longer overclaims "offline".
+    options.print("couldn't reach the update server — check skipped");
     return { action: 'continue', reason: 'check-skipped' };
   }
   if (check.isCurrent) {
     return { action: 'continue', reason: 'already-current' };
   }
 
+  const applyTimeoutMs = options.applyTimeoutMs ?? options.settings.applyTimeoutMs ?? LAUNCH_APPLY_TIMEOUT_MS;
+  options.print(`downloading ${check.latestTag}…`);
+  const controller = new AbortController();
+  const progress = createUpdateSwapProgress();
   try {
     const apply = options.apply ?? applyUpdate;
-    await apply({
+    const applyPromise = apply({
       fetchImpl: options.fetchImpl,
       execPath: options.execPath,
       platform: options.platform,
@@ -131,7 +167,30 @@ export async function runLaunchAutoUpdate(options: RunLaunchAutoUpdateOptions):
       currentVersion: options.currentVersion,
       print: options.print,
       configManager: options.configManager,
+      signal: controller.signal,
+      progress,
     });
+    // Losing the race abandons this promise, and a cancelled download rejects
+    // shortly after: that rejection is the expected end of the work, not an
+    // unhandled failure, so it is absorbed here. The race below still sees
+    // every rejection that arrives before the budget runs out.
+    applyPromise.catch(() => {});
+    const applyResult = await withTimeout(applyPromise, applyTimeoutMs);
+    if (applyResult === 'timeout') {
+      if (!progress.begun) {
+        // Nothing has been written yet, so the work can genuinely be called
+        // off — cancel the download in flight, then say it was deferred.
+        controller.abort();
+        options.print('update deferred — will retry next launch');
+        return { action: 'continue', reason: 'update-deferred' };
+      }
+      // The swap had already started when the budget ran out. A swap is never
+      // interrupted, so the binary on disk is the new one — cancelling here
+      // would be a lie in the other direction. Report the replacement and the
+      // restart it needs instead of claiming a deferral that did not happen.
+      options.print(`updated in background; restart to use v${normalizeVersion(progress.targetTag ?? check.latestTag)}`);
+      return { action: 'continue', reason: 'update-in-background' };
+    }
     options.print(`auto-update: ${check.latestTag} installed — restarting onto the new version`);
     return { action: 'restart', latestTag: check.latestTag };
   } catch (error) {

package/src/cli/tui-startup.ts

@@ -4,8 +4,12 @@ import type { SelectionItem } from '../input/selection-modal.ts';
 import type { WorkspaceRegistrationManager } from '../runtime/trust/workspace-registration.ts';
 import { hasResumableWizardProgress, readOnboardingCheckMarker, readWizardProgress } from '../runtime/onboarding/index.ts';
 import { startOnboardingFastPath } from '../runtime/onboarding/fast-path.ts';
-import { readLastSessionPointer } from '@/runtime/index.ts';
+import { checkRecoveryForSession, readLastSessionPointer, type SessionSurface } from '@/runtime/index.ts';
 import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import { offerRecoverySnapshot } from '../runtime/recovery-prompt.ts';
+import { buildRecoveryOfferWiring } from '../runtime/recovery-offer-wiring.ts';
+import type { ConversationManager } from '../core/conversation.ts';
+import type { SessionManager } from '@pellux/goodvibes-sdk/platform/sessions';
 import type { GoodVibesCliParseResult } from './types.ts';
 
 export type TuiStartupShellPaths = Parameters<typeof readOnboardingCheckMarker>[0] & {
@@ -15,6 +19,109 @@ export type TuiStartupShellPaths = Parameters<typeof readOnboardingCheckMarker>[
 
 export type FirstOpenTrustLevel = 'trusted' | 'restricted';
 
+/**
+ * What `resumeNamedSessionWithRecoveryCheck` needs to actually APPLY an
+ * accepted crash-recovery snapshot — the same shape `buildRecoveryOfferWiring`
+ * (runtime/recovery-offer-wiring.ts) takes, minus `surface` and
+ * `commandContext` which this module already has in scope. Optional: a caller
+ * that omits it (or a snapshot-free boot) gets exactly today's behavior —
+ * straight resume from the durable store, no modal.
+ */
+export interface TuiStartupRecoveryDeps {
+  readonly sessionManager: Pick<SessionManager, 'save'>;
+  readonly runtime: { sessionId: string; model: string; provider: string };
+  readonly conversation: ConversationManager;
+  readonly writeLastSessionPointer: (sessionId: string) => void;
+  readonly receipt: (line: string) => void;
+}
+
+/**
+ * resumeNamedSessionWithRecoveryCheck — the pre-resume guard for `--continue`
+ * and the bare `--resume` (pointer) path.
+ *
+ * Resuming a named session straight from its durable store is exactly the
+ * post-crash reflex that silently drops an autosave tail: if that session
+ * also has a crash-recovery snapshot NEWER than its store, the snapshot (not
+ * the shorter store copy) is the live state. `checkRecoveryForSession` is the
+ * read-only probe for that; when it finds one, this routes through the same
+ * ask-then-retire modal flow the general boot offer uses
+ * (runtime/recovery-prompt.ts), scoped to this one session via
+ * `targetSessionId` — never auto-applied.
+ *
+ *   - No live snapshot (or `recovery` deps not wired): straight resume, same
+ *     as before this check existed.
+ *   - Resume chosen: the snapshot is applied (via `buildRecoveryOfferWiring`'s
+ *     `applySnapshot`, which rebinds the runtime session id and replays any
+ *     journal tail) and the plain store resume is skipped — the snapshot IS
+ *     the more complete copy.
+ *   - "Not now" (or a dismissal, or a failed load): falls through to the
+ *     plain store resume, after the follow-up Keep/Remove question the
+ *     established flow always asks on decline.
+ *
+ * The modal itself is deferred to the next macrotask, mirroring
+ * `scheduleRecoveryOffer`'s own reasoning: `applyInitialTuiCliState` runs
+ * before the shell's first render, so asking a question here synchronously
+ * would draw it at a blank terminal. The synchronous `checkRecoveryForSession`
+ * probe above needs no such deferral — only opening the modal does.
+ */
+async function resumeNamedSessionWithRecoveryCheck(options: {
+  readonly sessionId: string;
+  readonly surface: SessionSurface;
+  readonly commandRegistry: CommandRegistry;
+  readonly commandContext: CommandContext;
+  readonly render: () => void;
+  readonly recovery: TuiStartupRecoveryDeps | undefined;
+}): Promise<void> {
+  const { sessionId, surface, commandRegistry, commandContext, render, recovery } = options;
+  const plainResume = (): Promise<void> =>
+    commandRegistry.execute('session', ['resume', sessionId], commandContext).then(() => render());
+
+  if (!recovery) {
+    await plainResume();
+    return;
+  }
+
+  const info = checkRecoveryForSession(surface, sessionId);
+  if (!info) {
+    await plainResume();
+    return;
+  }
+
+  await new Promise<void>((resolve) => {
+    const timer = setTimeout(() => {
+      void (async () => {
+        try {
+          const deps = buildRecoveryOfferWiring({
+            surface,
+            sessionManager: recovery.sessionManager,
+            runtime: recovery.runtime,
+            conversation: recovery.conversation,
+            commandContext,
+            writeLastSessionPointer: recovery.writeLastSessionPointer,
+            receipt: recovery.receipt,
+            render,
+          });
+          const outcome = await offerRecoverySnapshot({ ...deps, targetSessionId: sessionId });
+          if (outcome !== 'resumed') {
+            await plainResume();
+          }
+        } catch {
+          // Best-effort by construction (mirrors offerRecoverySnapshot's own
+          // guarantee): a failure here must fall back to the plain resume
+          // rather than leave the boot with nothing resumed at all.
+          await plainResume().catch(() => {
+            // A failing plain resume here is no worse than the pre-existing
+            // behavior when session resume itself fails.
+          });
+        } finally {
+          resolve();
+        }
+      })();
+    }, 0);
+    timer.unref?.();
+  });
+}
+
 /**
  * decodeFirstOpenChoice — pure mapping from a chosen selection-item id (or
  * null on Escape/enter-through) to the trust decision. Kept pure so the
@@ -79,9 +186,24 @@ export function applyInitialTuiCliState(options: {
   readonly commandRegistry: CommandRegistry;
   readonly commandContext: CommandContext;
   readonly shellPaths: TuiStartupShellPaths;
+  /**
+   * The app's declare-once session-storage handle — the SAME one the runtime
+   * writes the last-session pointer through. `--continue` and bare `--resume`
+   * read that pointer below; deriving its path independently here is exactly
+   * how this read used to land on a file nothing ever wrote.
+   */
+  readonly surface: SessionSurface;
   readonly render: () => void;
+  /**
+   * Enables the crash-recovery check ahead of `--continue` / bare `--resume`
+   * (see `resumeNamedSessionWithRecoveryCheck` above). Omitted, the two flags
+   * resume straight from the durable store exactly as before this check
+   * existed — main.ts always wires this; only tests that don't care about
+   * recovery snapshots leave it out.
+   */
+  readonly continueRecovery?: TuiStartupRecoveryDeps;
 }): Promise<void> | undefined {
-  const { cli, input, commandRegistry, commandContext, shellPaths, render } = options;
+  const { cli, input, commandRegistry, commandContext, shellPaths, surface, render, continueRecovery } = options;
   const globalOnboardingMarker = readOnboardingCheckMarker(shellPaths, 'user');
 
   // Registration self-records on every launch of an already-trusted
@@ -109,27 +231,21 @@ export function applyInitialTuiCliState(options: {
       return commandRegistry.execute('session', ['resume', target], commandContext).then(() => render());
     }
   } else if (cli.flags.continueLast) {
-    // --continue: resume the last session tracked by the pointer file
-    const lastId = readLastSessionPointer({
-      workingDirectory: shellPaths.workingDirectory,
-      homeDirectory: shellPaths.homeDirectory,
-      surfaceRoot: 'tui',
-    });
+    // --continue: resume the last session tracked by the pointer file. Checked
+    // for a live crash-recovery snapshot first — see
+    // resumeNamedSessionWithRecoveryCheck's doc comment.
+    const lastId = readLastSessionPointer({ surface });
     if (lastId) {
-      return commandRegistry.execute('session', ['resume', lastId], commandContext).then(() => render());
+      return resumeNamedSessionWithRecoveryCheck({ sessionId: lastId, surface, commandRegistry, commandContext, render, recovery: continueRecovery });
     }
   } else if (cli.flags.resume !== undefined) {
     // --resume [id]: explicit id dispatches directly; bare form (sentinel 'latest') resolves via pointer
     if (cli.flags.resume !== 'latest') {
       return commandRegistry.execute('session', ['resume', cli.flags.resume], commandContext).then(() => render());
     } else {
-      const lastId = readLastSessionPointer({
-        workingDirectory: shellPaths.workingDirectory,
-        homeDirectory: shellPaths.homeDirectory,
-        surfaceRoot: 'tui',
-      });
+      const lastId = readLastSessionPointer({ surface });
       if (lastId) {
-        return commandRegistry.execute('session', ['resume', lastId], commandContext).then(() => render());
+        return resumeNamedSessionWithRecoveryCheck({ sessionId: lastId, surface, commandRegistry, commandContext, render, recovery: continueRecovery });
       }
     }
   } else if (cli.flags.fork !== undefined) {

package/src/config/surface.ts

@@ -0,0 +1,21 @@
+/**
+ * surface.ts — the TUI's single surface-root identifier.
+ *
+ * Every piece of the TUI's own on-disk state (sessions, the last-session
+ * pointer, recovery snapshots, checkpoints, the transcript journal, the
+ * multi-instance liveness markers) lives under `.goodvibes/tui/`. That scope
+ * segment used to be spelled as a bare `'tui'` string literal at each call
+ * site, which is how a writer and a reader ended up disagreeing about where
+ * the last-session pointer lives: one call passed the scope, another omitted
+ * it and silently resolved to the shared, unscoped `.goodvibes/` directory,
+ * so `--continue` looked at an empty file forever.
+ *
+ * The constant below is the one place that name is written for the session /
+ * recovery / checkpoint domain. It feeds `createSessionSurface` in
+ * runtime/services.ts, which resolves every path once at startup into the
+ * `SessionSurface` handle threaded through the rest of the runtime. Other
+ * subsystems (config storage, sandbox scaffolding, keybindings, and so on)
+ * still write their own `'tui'` surface-root segment at their own call
+ * sites; this constant is not (yet) the single source for all of them.
+ */
+export const GOODVIBES_TUI_SURFACE_ROOT = 'tui';

package/src/config/tui-extension-settings.ts

@@ -113,22 +113,30 @@ export interface UpdateSettings {
   readonly autoUpdateAtLaunch?: boolean;
   /** How long the launch-time version check may take before it is skipped. Defaults to 2500; clamped to [250, 30000]. */
   readonly launchCheckTimeoutMs?: number;
+  /** How long the launch-time download+verify+swap may take before it is deferred to the next launch. Defaults to 45000; clamped to [5000, 300000]. */
+  readonly applyTimeoutMs?: number;
 }
 
 const LAUNCH_CHECK_MIN_TIMEOUT_MS = 250;
 const LAUNCH_CHECK_MAX_TIMEOUT_MS = 30_000;
+const LAUNCH_APPLY_MIN_TIMEOUT_MS = 5_000;
+const LAUNCH_APPLY_MAX_TIMEOUT_MS = 300_000;
 
 /** Read `update.*` from settings.json, validating and clamping the timeout. */
 export function readUpdateSettings(configManager: Pick<ConfigManager, 'getRaw'>): UpdateSettings {
   const src = readNamespace(configManager, 'update');
   if (!src) return {};
-  const out: { autoUpdateAtLaunch?: boolean; launchCheckTimeoutMs?: number } = {};
+  const out: { autoUpdateAtLaunch?: boolean; launchCheckTimeoutMs?: number; applyTimeoutMs?: number } = {};
   const autoUpdateAtLaunch = readBoolean(src, 'autoUpdateAtLaunch');
   if (autoUpdateAtLaunch !== undefined) out.autoUpdateAtLaunch = autoUpdateAtLaunch;
   const launchCheckTimeoutMs = readPositiveInt(src, 'launchCheckTimeoutMs');
   if (launchCheckTimeoutMs !== undefined) {
     out.launchCheckTimeoutMs = Math.min(LAUNCH_CHECK_MAX_TIMEOUT_MS, Math.max(LAUNCH_CHECK_MIN_TIMEOUT_MS, launchCheckTimeoutMs));
   }
+  const applyTimeoutMs = readPositiveInt(src, 'applyTimeoutMs');
+  if (applyTimeoutMs !== undefined) {
+    out.applyTimeoutMs = Math.min(LAUNCH_APPLY_MAX_TIMEOUT_MS, Math.max(LAUNCH_APPLY_MIN_TIMEOUT_MS, applyTimeoutMs));
+  }
   return out;
 }
 

package/src/core/bookmark-navigation.ts

@@ -0,0 +1,44 @@
+/**
+ * bookmark-navigation.ts — fallback resolution for a bookmark whose direct
+ * BlockMeta lookup misses.
+ *
+ * A bookmark stores a block's collapseKey at the time it was set (see
+ * handler-content-actions.ts's handleBookmark). A tool-result message that is
+ * a non-owning member of a folded tool-result group (see
+ * conversation-tool-groups.ts) pushes no BlockMeta of its own while the group
+ * stays collapsed — its own collapseKey (`msg_<absoluteIdx>`) never appears
+ * in getBlockRegistry() until the group is expanded. A direct
+ * find(entry => entry.collapseKey === key) then reports "not found", even
+ * though the message is still present in the transcript, just folded under
+ * its group's header.
+ *
+ * Resolution: parse the message's absolute index out of the `msg_<idx>` key
+ * and resolve it through ConversationManager.getMessageLine(idx) instead of
+ * the block registry. That registry is keyed by absolute message index and,
+ * for a folded group member, already resolves to the group's own header line
+ * rather than the position of whatever renders next (see getMessageLine's
+ * doc and conversation-rendering.ts / conversation-line-cache.ts, which
+ * anchor a folded member's registered line at its group's header) — landing
+ * on the header is an honest, reachable result rather than a false
+ * "not found".
+ */
+
+import type { ConversationManager } from './conversation.ts';
+
+const MESSAGE_BOOKMARK_KEY = /^msg_(\d+)$/;
+
+/**
+ * Resolve a bookmark key that missed a direct BlockMeta lookup. Returns the
+ * line to scroll to, or null when the key isn't a message-scoped bookmark
+ * (`msg_<idx>`) or that message index has never been rendered.
+ */
+export function resolveFoldedBookmarkLine(
+  conversation: Pick<ConversationManager, 'getMessageLine'>,
+  key: string,
+): number | null {
+  const match = MESSAGE_BOOKMARK_KEY.exec(key);
+  if (!match) return null;
+  const absoluteIdx = Number(match[1]);
+  const line = conversation.getMessageLine(absoluteIdx);
+  return line === undefined ? null : line;
+}