@code-yeongyu/senpi 2026.9.15 → 2026.9.16-3

package/CHANGELOG.md

@@ -12,6 +12,94 @@
 
 ### Removed
 
+## [2026.9.16-3] - 2026-09-16
+
+### Breaking Changes
+
+### Added
+
+### Changed
+
+- The stream guard now interrupts a message that keeps restating itself in different words, not only one that repeats a paragraph verbatim. A paragraph counts as an echo when its normalized word set overlaps an earlier paragraph of the same message by half, and the guard acts only once at least 8 of the last 12 paragraphs are echoes, so a repeated sentence, a callback, or a closing summary is left alone while a narration loop is cut within a few thousand characters. Paragraphs inside fenced code blocks are ignored, and the earlier text is kept - only the repeated run is dropped before the retry. Measured against 12,499 real assistant messages, the rule matched nothing except two known runaway generations. ([#1330](https://github.com/code-yeongyu/senpi/issues/1330))
+
+- `--help` no longer boots the engine to print a help screen. The usage text and the flags extensions register are answered from a cache of the last launch's flag set (`<agentDir>/cache/help-flags.json`, validated against the engine version and the mtime/size of every extension, settings and trust input, so an upgrade or an edited extension refreshes it); a cache miss loads extensions for their flags only and skips the model runtime, the session and every other resource class. Measured warm on an Apple M4 Pro: 790ms → 28ms on bun and 959ms → 59ms on node for `--help`; a help screen never prompts for project trust and never runs project-local extension code that is not already trusted. ([oh-my-openagent#8371](https://github.com/code-yeongyu/oh-my-openagent/issues/8371))
+
+### Fixed
+
+- The startup spinner is drawn the moment interactive startup begins instead of after a 120ms grace timer. That timer could not fire while the synchronous extension imports it was meant to cover were running, so on a real terminal the first frame appeared only once the whole load was done (measured: first byte at 2.27s, one frame before the TUI took over) and the load ran on a blank screen. ([oh-my-openagent#8371](https://github.com/code-yeongyu/oh-my-openagent/issues/8371))
+
+### Removed
+
+## [2026.9.16-2] - 2026-09-16
+
+### Breaking Changes
+
+### Added
+
+- Added `/rename [name]` to rename the current session from the TUI: with an argument it sets the name immediately, without one it opens an inline editor prefilled with the current name (Enter commits, Esc cancels, empty names are rejected). `/name` remains as an alias, and the new unbound `app.session.renameCurrent` keybinding action opens the same editor. ([#1738](https://github.com/code-yeongyu/senpi/issues/1738))
+
+### Changed
+
+- Large tool-result strings evicted from the resident store persist to a per-session blob backing and hydrate on read instead of forcing a full session-JSONL reparse. Blob names are the SHA-256 of the text, so a string that is hydrated and externalized again maps to the same file, and two processes sharing a session directory can only ever write identical bytes under one name. Blobs are integrity-checked envelopes: a corrupt file is deleted on read and the entry falls back to JSONL recovery. `--no-session` never writes blobs ([#1746](https://github.com/code-yeongyu/senpi/issues/1746)).
+- Idle sessions release the memoized entry views and tokenize the runtime message state only once the store has evicted something; `session.messages` and the compaction estimators hydrate those tokens before returning, so readers never see resident tokens. The blob directory is removed when the session manager is disposed, when the session is switched or branched, and stale blobs are cleared when a persisted session is reopened ([#1746](https://github.com/code-yeongyu/senpi/issues/1746)).
+- Compaction spills resident strings to the blob backing instead of dropping them, keeping post-compaction reads on the per-string hydration path.
+- Branched sessions materialize entry content before the previous backing is released, so resident tokens can no longer be written into a new branched session file.
+
+### Fixed
+
+- Moving the model selector off a Claude model and back no longer re-sends the whole conversation. Leaving the `claude-sdk-oauth` provider now closes the live SDK session but keeps its continuity binding - the same thing a thinking-level change already did - so returning to the same Claude model re-attaches to the existing session and sends only the messages added while you were away, instead of paying for the full history again. Switching to a different Claude model, a restart with no usable transcript, a diverged conversation and an unacknowledged session id all still start fresh exactly as before. When a binding really was discarded, the transcript notice now names the recorded cause (`model_selected`, `tainted_compaction`, `branch_diverged`, `extensions_removed`, ...) instead of the generic `registry_miss`, which from now on means only "no record was ever found" ([#1747](https://github.com/code-yeongyu/senpi/issues/1747)).
+
+- A provider that accepts a request and never starts streaming no longer ends the turn with the watchdog's own message (`Provider stream start timed out after 180000ms ...`). The stall is still retried on the same model with the configured stream-start bound, and still hands the turn to the next model in a configured `retry.fallbackChains` entry whose answer becomes the turn result. What changed is what you read: the transcript (and `senpi -p`) describes the stall in plain language, and when nothing can take the turn over the final line names the stalled model, the attempts spent and the next step - `/fallback`, resending, or raising `retry.provider.streamStartTimeoutMs` (`0` disables). The wording on the assistant message is unchanged, so retry classification and fallback routing behave exactly as before ([#1740](https://github.com/code-yeongyu/senpi/issues/1740)).
+
+- A session no longer dead-ends when the compaction summarizer is killed by a provider or credential failure. Such a stream used to end required compaction with the raw internal `senpi:no-turn-retry:` marker, which also disabled auto-retry and model fallback; because compaction never applied, the context stayed above the threshold and every following prompt failed identically. Those failures now apply the deterministic compaction checkpoint (retained-suffix safety checks unchanged) and the turn continues, with one plain warning saying a provider summary could not be completed, that a checkpoint was applied and older detail was dropped, and that it is safe to continue. Provider refusals, missing credentials and user aborts still surface loudly instead of reducing context. One compaction is also bounded at 15 minutes total across every attempt and retry regardless of input size (an explicit `compaction.summarizationMaxDurationMs` above that still wins), and the summary stream's final settlement now happens inside the watchdog, so a provider whose stream ends without a terminal event can no longer park compaction with no timer armed ([#1741](https://github.com/code-yeongyu/senpi/issues/1741)).
+
+### Removed
+
+## [2026.9.16] - 2026-09-16
+
+### Breaking Changes
+
+### Added
+
+- Extensions receive a per-handler `signal` on the `session_shutdown` event. The host aborts it when that handler exceeds its budget, so long shutdown work can stop cleanly instead of being left behind ([#1732](https://github.com/code-yeongyu/senpi/issues/1732)).
+
+- Added the optional `ExtensionContext.kernelTools` capability with `describe(names)` and `invoke(request, signal?)`. It is present only while a JavaScript eval cell owns the host-tool context, so an extension tool called from inside that cell can reach the functions the cell registered with `tool(fn)`; on older runtimes and outside such a cell it is `undefined`. The package exports `kernelToolsStorage` and the `ExtensionKernelTools` type for hosts that install the capability ([#1647](https://github.com/code-yeongyu/senpi/issues/1647)).
+
+### Changed
+
+- Default `read` calls on eligible `.json` files now return the agent package's structural view, with the same declaration-safe folding and numeric `offset`/`limit` rereads, so edits after a read still target real lines. TypeScript and JavaScript stay raw because the measured candidate missed their quality thresholds. Prose, explicit ranges and the existing size-limit continuations produce the same output as before. `ReadToolOptions.folder` selects the folder; `createReadToolDefinition`, `createCodingTools` and `createReadOnlyTools` default it to `selectedReadFolder`, and an options object without `folder` keeps reads verbatim. Compiled binaries produce byte-identical read output to the source build, and no parser dependency is added ([#1639](https://github.com/code-yeongyu/senpi/issues/1639)).
+
+### Fixed
+
+- One extension can no longer hold quit, `/reload`, `/new`, `/resume` or a fork hostage: senpi now bounds every `session_shutdown` handler itself. A handler still running after `sessionShutdownHandlerWarnMs` (default 2000) logs one warning naming the extension, and at `sessionShutdownHandlerTimeoutMs` (default 10000) senpi aborts that handler's `event.signal`, reports an extension error naming it, and continues teardown with the remaining handlers. Set either setting to `0` to disable that half. Handlers that finish under the warning threshold are unaffected, and every other extension event keeps its uncapped wait (ask-user and approval dialogs may legitimately block for minutes) ([#1732](https://github.com/code-yeongyu/senpi/issues/1732)).
+
+### Removed
+
+## [2026.9.15-2] - 2026-09-15
+
+### Breaking Changes
+
+### Added
+
+### Changed
+
+- Standalone binaries load codemode from the staged on-disk package instead of embedding a second copy; the sidecar includes its JS parser dependency and retains the bun-1-4 skill ([#1656](https://github.com/code-yeongyu/senpi/issues/1656)).
+
+### Fixed
+
+- RPC `close_session` acknowledgements and `session_closed` events, including worker-failure terminals, are published only after the session registry has removed the entry, so an immediate `list_sessions` never returns the closed session. Filesystem watchers are cancelled atomically with shutdown, every disposer is joined before process exit, reentrant RPC shutdown shares that join and keeps a failure exit code, and nonpersistent RPC probes do not start watchers ([#1656](https://github.com/code-yeongyu/senpi/issues/1656)).
+
+- The RPC host watchdog's ppid fallback no longer spawns `ps -o lstart=` every 250ms while the supervisor is alive: a dead supervisor is reaped by its own parent and the host is then reparented, so the free `kill(pid, 0)` + ppid comparison observes the loss without any child process. Long-lived shared hosts no longer accumulate thousands of `ps` children (zombies on runtimes that fail to reap them) ([#1507](https://github.com/code-yeongyu/senpi/issues/1507)).
+
+- Terminal monitors no longer burn CPU while paused: a paused file watch clears its 250ms poll timer entirely (no stat/SHA-256 digest work) and resume runs one immediate check, so a change made during the pause still fires. Session-output line buffers are now capped at 64KiB, so a newline-less stream can no longer grow a monitor's retained tail without bound ([#1698](https://github.com/code-yeongyu/senpi/issues/1698)).
+
+- Long, compaction-trimmed sessions no longer re-parse the entire session file every time the working/retry status animation cadence is decided (which periodically froze the UI on multi-day sessions): the cadence reads an O(1) maintained entry count, `SessionManager#getEntryCount()`; explicit full-history retrieval is unchanged ([#1699](https://github.com/code-yeongyu/senpi/issues/1699)).
+
+
+- The Cursor CLI OAuth lane no longer spawns `cursor-agent models` on every senpi start. The startup catalog probe runs only when the lane is usable (not disabled, `cursor-agent` installed, at least one account bound), inside that account's HOME, and every `cursor-agent` spawn (turn, `models`, `--version`) now receives the same explicit environment allowlist instead of the inherited `process.env`. Hermetic or SSH-launched senpi processes therefore never trigger the CLI's macOS keychain preflight, which used to surface as a blocking "Keychain Not Found" dialog for `cursor-keychain-probe` on the logged-in console ([#1722](https://github.com/code-yeongyu/senpi/issues/1722)).
+
+### Removed
+
 ## [2026.9.15] - 2026-09-15
 
 ### Breaking Changes
@@ -40,6 +128,7 @@
 
 - Compiled Bun binaries load TypeScript extensions through native runtime modules instead of embedding jiti, preserving host-module identity and fresh dependency graphs on reload. Computed imports and requires share their generation, unused graphs can be reclaimed, native data imports keep Bun's loaders, and parser errors retain source locations. Node runtimes retain their existing jiti options and load only their own importer when needed ([#1656](https://github.com/code-yeongyu/senpi/issues/1656)).
 
+
 ### Fixed
 
 - Fixed background processes surviving shutdown when the shell that started them exited first: the bash tool now keeps owning a command's process group until its last descendant is gone, so `sleep 30 &` or `nohup server &` is killed by shutdown cleanup instead of being orphaned. Tracked groups that have drained are pruned, and a group whose leader already exited is never re-signalled by bare pid ([#1697](https://github.com/code-yeongyu/senpi/issues/1697)).

package/README.md

@@ -194,7 +194,7 @@ Type `/` in the editor to trigger commands. [Extensions](#extensions) can regist
 | `/settings` | Theme, message delivery, transport, and other preferences |
 | `/resume` | Pick from previous sessions |
 | `/new` | Start a new session |
-| `/name <name>` | Set session display name |
+| `/rename [name]` | Rename the current session (`/name` is an alias) |
 | `/session` | Show session info (file, ID, messages, tokens, cost) |
 | `/tree` | Jump to any point in the session and continue from there |
 | `/trust` | Save project trust decision for future sessions (restart required) |

package/dist/cli/help-extension-flags.d.ts

@@ -0,0 +1,22 @@
+import type { ExtensionFlag, InlineExtension } from "../core/extensions/types.ts";
+import type { SettingsManager } from "../core/settings-manager.ts";
+export interface HelpExtensionFlagsResult {
+    readonly flags: ExtensionFlag[];
+    readonly extensionPaths: string[];
+}
+/**
+ * Load extensions for their CLI flags and nothing else.
+ *
+ * Help renders flag descriptors, so this deliberately skips every other resource class and the
+ * whole model/session stack that `createAgentSessionServices` would build: skills, prompt
+ * templates, themes and context files cannot register a flag.
+ */
+export declare function resolveHelpExtensionFlags(options: {
+    readonly cwd: string;
+    readonly agentDir: string;
+    readonly settingsManager: SettingsManager;
+    readonly additionalExtensionPaths: readonly string[];
+    readonly noExtensions: boolean;
+    readonly extensionFactories?: readonly InlineExtension[];
+}): Promise<HelpExtensionFlagsResult>;
+//# sourceMappingURL=help-extension-flags.d.ts.map

package/dist/cli/help-extension-flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-extension-flags.d.ts","sourceRoot":"","sources":["../../src/cli/help-extension-flags.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAElF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAEnE,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,KAAK,EAAE,aAAa,EAAE,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,CAAC;CAClC;AAED;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAAC,OAAO,EAAE;IACxD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,QAAQ,CAAC,wBAAwB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrD,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;CACzD,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAoBpC"}

package/dist/cli/help-extension-flags.js

@@ -0,0 +1,30 @@
+import { DefaultResourceLoader } from "../core/resource-loader.js";
+/**
+ * Load extensions for their CLI flags and nothing else.
+ *
+ * Help renders flag descriptors, so this deliberately skips every other resource class and the
+ * whole model/session stack that `createAgentSessionServices` would build: skills, prompt
+ * templates, themes and context files cannot register a flag.
+ */
+export async function resolveHelpExtensionFlags(options) {
+    const resourceLoader = new DefaultResourceLoader({
+        cwd: options.cwd,
+        agentDir: options.agentDir,
+        settingsManager: options.settingsManager,
+        sharedHostEnabled: false,
+        additionalExtensionPaths: [...options.additionalExtensionPaths],
+        noExtensions: options.noExtensions,
+        noSkills: true,
+        noPromptTemplates: true,
+        noThemes: true,
+        noContextFiles: true,
+        ...(options.extensionFactories ? { extensionFactories: [...options.extensionFactories] } : {}),
+    });
+    await resourceLoader.reload();
+    const { extensions } = resourceLoader.getExtensions();
+    return {
+        flags: extensions.flatMap((extension) => [...extension.flags.values()]),
+        extensionPaths: extensions.map((extension) => extension.resolvedPath),
+    };
+}
+//# sourceMappingURL=help-extension-flags.js.map

package/dist/cli/help-extension-flags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-extension-flags.js","sourceRoot":"","sources":["../../src/cli/help-extension-flags.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAQnE;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,OAO/C;IACA,MAAM,cAAc,GAAG,IAAI,qBAAqB,CAAC;QAChD,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,eAAe,EAAE,OAAO,CAAC,eAAe;QACxC,iBAAiB,EAAE,KAAK;QACxB,wBAAwB,EAAE,CAAC,GAAG,OAAO,CAAC,wBAAwB,CAAC;QAC/D,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,QAAQ,EAAE,IAAI;QACd,iBAAiB,EAAE,IAAI;QACvB,QAAQ,EAAE,IAAI;QACd,cAAc,EAAE,IAAI;QACpB,GAAG,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,CAAC,GAAG,OAAO,CAAC,kBAAkB,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9F,CAAC,CAAC;IACH,MAAM,cAAc,CAAC,MAAM,EAAE,CAAC;IAC9B,MAAM,EAAE,UAAU,EAAE,GAAG,cAAc,CAAC,aAAa,EAAE,CAAC;IACtD,OAAO;QACN,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QACvE,cAAc,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,YAAY,CAAC;KACrE,CAAC;AACH,CAAC","sourcesContent":["import type { ExtensionFlag, InlineExtension } from \"../core/extensions/types.ts\";\nimport { DefaultResourceLoader } from \"../core/resource-loader.ts\";\nimport type { SettingsManager } from \"../core/settings-manager.ts\";\n\nexport interface HelpExtensionFlagsResult {\n\treadonly flags: ExtensionFlag[];\n\treadonly extensionPaths: string[];\n}\n\n/**\n * Load extensions for their CLI flags and nothing else.\n *\n * Help renders flag descriptors, so this deliberately skips every other resource class and the\n * whole model/session stack that `createAgentSessionServices` would build: skills, prompt\n * templates, themes and context files cannot register a flag.\n */\nexport async function resolveHelpExtensionFlags(options: {\n\treadonly cwd: string;\n\treadonly agentDir: string;\n\treadonly settingsManager: SettingsManager;\n\treadonly additionalExtensionPaths: readonly string[];\n\treadonly noExtensions: boolean;\n\treadonly extensionFactories?: readonly InlineExtension[];\n}): Promise<HelpExtensionFlagsResult> {\n\tconst resourceLoader = new DefaultResourceLoader({\n\t\tcwd: options.cwd,\n\t\tagentDir: options.agentDir,\n\t\tsettingsManager: options.settingsManager,\n\t\tsharedHostEnabled: false,\n\t\tadditionalExtensionPaths: [...options.additionalExtensionPaths],\n\t\tnoExtensions: options.noExtensions,\n\t\tnoSkills: true,\n\t\tnoPromptTemplates: true,\n\t\tnoThemes: true,\n\t\tnoContextFiles: true,\n\t\t...(options.extensionFactories ? { extensionFactories: [...options.extensionFactories] } : {}),\n\t});\n\tawait resourceLoader.reload();\n\tconst { extensions } = resourceLoader.getExtensions();\n\treturn {\n\t\tflags: extensions.flatMap((extension) => [...extension.flags.values()]),\n\t\textensionPaths: extensions.map((extension) => extension.resolvedPath),\n\t};\n}\n"]}

package/dist/cli/help-fast-path.d.ts

@@ -0,0 +1,19 @@
+import { type Args } from "./args.ts";
+import { type HelpFlagsScope } from "./help-flags-cache.ts";
+export declare function isPlainHelpRequest(parsed: Args): boolean;
+/**
+ * A help screen never prompts for project trust and never runs project-local extension code
+ * the user has not already trusted: only a recorded decision, or an explicit override, lets
+ * project resources in.
+ */
+export declare function resolveHelpProjectTrust(parsed: Args, cwd: string, agentDir: string): boolean;
+export declare function helpFlagsScope(parsed: Args, cwd: string, agentDir: string, projectTrusted: boolean): HelpFlagsScope;
+/**
+ * Answer `--help` before the engine module graph is imported.
+ *
+ * Returns false for every launch it cannot answer from what is already known - a non-plain help
+ * request, or a scope whose cached flags are missing or stale - and the normal startup path then
+ * resolves the flags and refills the cache.
+ */
+export declare function tryPrintHelpWithoutEngine(argv: readonly string[]): boolean;
+//# sourceMappingURL=help-fast-path.d.ts.map

package/dist/cli/help-fast-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-fast-path.d.ts","sourceRoot":"","sources":["../../src/cli/help-fast-path.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,IAAI,EAAwB,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,KAAK,cAAc,EAAsB,MAAM,uBAAuB,CAAC;AAEhF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,IAAI,GAAG,OAAO,CAExD;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAI5F;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAG,cAAc,CAQnH;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAuB1E"}

package/dist/cli/help-fast-path.js

@@ -0,0 +1,64 @@
+import { getAgentDir } from "../config.js";
+import { hasTrustRequiringProjectResources, ProjectTrustStore } from "../core/trust-manager.js";
+import { parseArgs, printHelp } from "./args.js";
+import { readHelpFlagsCache } from "./help-flags-cache.js";
+export function isPlainHelpRequest(parsed) {
+    return parsed.help === true && parsed.print !== true && parsed.mode === undefined;
+}
+/**
+ * A help screen never prompts for project trust and never runs project-local extension code
+ * the user has not already trusted: only a recorded decision, or an explicit override, lets
+ * project resources in.
+ */
+export function resolveHelpProjectTrust(parsed, cwd, agentDir) {
+    if (parsed.projectTrustOverride !== undefined)
+        return parsed.projectTrustOverride;
+    if (!hasTrustRequiringProjectResources(cwd))
+        return true;
+    return new ProjectTrustStore(agentDir).get(cwd) === true;
+}
+export function helpFlagsScope(parsed, cwd, agentDir, projectTrusted) {
+    return {
+        cwd,
+        agentDir,
+        cliExtensionPaths: [...(parsed.extensions ?? [])],
+        noExtensions: parsed.noExtensions === true,
+        projectTrusted,
+    };
+}
+/**
+ * Answer `--help` before the engine module graph is imported.
+ *
+ * Returns false for every launch it cannot answer from what is already known - a non-plain help
+ * request, or a scope whose cached flags are missing or stale - and the normal startup path then
+ * resolves the flags and refills the cache.
+ */
+export function tryPrintHelpWithoutEngine(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs([...argv]);
+    }
+    catch {
+        return false;
+    }
+    if (!isPlainHelpRequest(parsed) || parsed.diagnostics.length > 0)
+        return false;
+    if (parsed.noExtensions === true) {
+        printHelp([]);
+        return true;
+    }
+    let flags;
+    try {
+        const cwd = process.cwd();
+        const agentDir = getAgentDir();
+        flags = readHelpFlagsCache(helpFlagsScope(parsed, cwd, agentDir, resolveHelpProjectTrust(parsed, cwd, agentDir)));
+    }
+    catch {
+        return false;
+    }
+    if (!flags)
+        return false;
+    printHelp(flags);
+    return true;
+}
+//# sourceMappingURL=help-fast-path.js.map

package/dist/cli/help-fast-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-fast-path.js","sourceRoot":"","sources":["../../src/cli/help-fast-path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,EAAE,iCAAiC,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAChG,OAAO,EAAa,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAuB,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhF,MAAM,UAAU,kBAAkB,CAAC,MAAY;IAC9C,OAAO,MAAM,CAAC,IAAI,KAAK,IAAI,IAAI,MAAM,CAAC,KAAK,KAAK,IAAI,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC;AACnF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAY,EAAE,GAAW,EAAE,QAAgB;IAClF,IAAI,MAAM,CAAC,oBAAoB,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,oBAAoB,CAAC;IAClF,IAAI,CAAC,iCAAiC,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACzD,OAAO,IAAI,iBAAiB,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAY,EAAE,GAAW,EAAE,QAAgB,EAAE,cAAuB;IAClG,OAAO;QACN,GAAG;QACH,QAAQ;QACR,iBAAiB,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;QACjD,YAAY,EAAE,MAAM,CAAC,YAAY,KAAK,IAAI;QAC1C,cAAc;KACd,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CAAC,IAAuB;IAChE,IAAI,MAAY,CAAC;IACjB,IAAI,CAAC;QACJ,MAAM,GAAG,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,KAAK,CAAC;IACd,CAAC;IACD,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAC/E,IAAI,MAAM,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;QAClC,SAAS,CAAC,EAAE,CAAC,CAAC;QACd,OAAO,IAAI,CAAC;IACb,CAAC;IACD,IAAI,KAAkC,CAAC;IACvC,IAAI,CAAC;QACJ,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;QAC1B,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;QAC/B,KAAK,GAAG,kBAAkB,CAAC,cAAc,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,uBAAuB,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IACnH,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,KAAK,CAAC;IACd,CAAC;IACD,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,SAAS,CAAC,KAAK,CAAC,CAAC;IACjB,OAAO,IAAI,CAAC;AACb,CAAC","sourcesContent":["import { getAgentDir } from \"../config.ts\";\nimport type { ExtensionFlag } from \"../core/extensions/types.ts\";\nimport { hasTrustRequiringProjectResources, ProjectTrustStore } from \"../core/trust-manager.ts\";\nimport { type Args, parseArgs, printHelp } from \"./args.ts\";\nimport { type HelpFlagsScope, readHelpFlagsCache } from \"./help-flags-cache.ts\";\n\nexport function isPlainHelpRequest(parsed: Args): boolean {\n\treturn parsed.help === true && parsed.print !== true && parsed.mode === undefined;\n}\n\n/**\n * A help screen never prompts for project trust and never runs project-local extension code\n * the user has not already trusted: only a recorded decision, or an explicit override, lets\n * project resources in.\n */\nexport function resolveHelpProjectTrust(parsed: Args, cwd: string, agentDir: string): boolean {\n\tif (parsed.projectTrustOverride !== undefined) return parsed.projectTrustOverride;\n\tif (!hasTrustRequiringProjectResources(cwd)) return true;\n\treturn new ProjectTrustStore(agentDir).get(cwd) === true;\n}\n\nexport function helpFlagsScope(parsed: Args, cwd: string, agentDir: string, projectTrusted: boolean): HelpFlagsScope {\n\treturn {\n\t\tcwd,\n\t\tagentDir,\n\t\tcliExtensionPaths: [...(parsed.extensions ?? [])],\n\t\tnoExtensions: parsed.noExtensions === true,\n\t\tprojectTrusted,\n\t};\n}\n\n/**\n * Answer `--help` before the engine module graph is imported.\n *\n * Returns false for every launch it cannot answer from what is already known - a non-plain help\n * request, or a scope whose cached flags are missing or stale - and the normal startup path then\n * resolves the flags and refills the cache.\n */\nexport function tryPrintHelpWithoutEngine(argv: readonly string[]): boolean {\n\tlet parsed: Args;\n\ttry {\n\t\tparsed = parseArgs([...argv]);\n\t} catch {\n\t\treturn false;\n\t}\n\tif (!isPlainHelpRequest(parsed) || parsed.diagnostics.length > 0) return false;\n\tif (parsed.noExtensions === true) {\n\t\tprintHelp([]);\n\t\treturn true;\n\t}\n\tlet flags: ExtensionFlag[] | undefined;\n\ttry {\n\t\tconst cwd = process.cwd();\n\t\tconst agentDir = getAgentDir();\n\t\tflags = readHelpFlagsCache(helpFlagsScope(parsed, cwd, agentDir, resolveHelpProjectTrust(parsed, cwd, agentDir)));\n\t} catch {\n\t\treturn false;\n\t}\n\tif (!flags) return false;\n\tprintHelp(flags);\n\treturn true;\n}\n"]}

package/dist/cli/help-flags-cache.d.ts

@@ -0,0 +1,23 @@
+import type { ExtensionFlag } from "../core/extensions/types.ts";
+export interface HelpFlagsScope {
+    readonly cwd: string;
+    readonly agentDir: string;
+    readonly cliExtensionPaths: readonly string[];
+    readonly noExtensions: boolean;
+    readonly projectTrusted: boolean;
+}
+/**
+ * Flags a previous run resolved for this exact scope, or `undefined` when anything that feeds
+ * extension discovery changed. Never throws: a help screen must not depend on its own cache.
+ */
+export declare function readHelpFlagsCache(scope: HelpFlagsScope): ExtensionFlag[] | undefined;
+/**
+ * Record the flags a full extension load produced. Failure is silent by contract: this runs on
+ * the startup path, where a cache write must never be the reason a launch fails.
+ */
+export declare function writeHelpFlagsCache(options: {
+    readonly scope: HelpFlagsScope;
+    readonly flags: readonly ExtensionFlag[];
+    readonly extensionPaths: readonly string[];
+}): void;
+//# sourceMappingURL=help-flags-cache.d.ts.map

package/dist/cli/help-flags-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-flags-cache.d.ts","sourceRoot":"","sources":["../../src/cli/help-flags-cache.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAKjE,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;CACjC;AAgFD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,cAAc,GAAG,aAAa,EAAE,GAAG,SAAS,CAOrF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE;IAC5C,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C,GAAG,IAAI,CA4BP"}

package/dist/cli/help-flags-cache.js

@@ -0,0 +1,118 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import { CONFIG_DIR_NAME, DISPLAY_VERSION } from "../config.js";
+const CACHE_FILE_VERSION = 1;
+const MAX_CACHED_SCOPES = 8;
+function cachePath(agentDir) {
+    return join(agentDir, "cache", "help-flags.json");
+}
+function scopeKey(scope) {
+    const material = [
+        scope.cwd,
+        scope.noExtensions ? "no-extensions" : "extensions",
+        scope.projectTrusted ? "trusted" : "untrusted",
+        ...scope.cliExtensionPaths,
+    ].join("\u0000");
+    return createHash("sha256").update(material).digest("hex").slice(0, 32);
+}
+/**
+ * A path's identity for cache validation. Directories carry only their mtime, which is what
+ * changes when an extension file is added or removed inside them; files carry mtime and size,
+ * so an in-place upgrade of a bundled plugin invalidates the entry it produced.
+ */
+function stamp(path) {
+    try {
+        const stats = statSync(path);
+        if (stats.isDirectory())
+            return `d:${stats.mtimeMs}`;
+        return `f:${stats.mtimeMs}:${stats.size}`;
+    }
+    catch {
+        return "absent";
+    }
+}
+function discoveryInputs(scope, extensionPaths) {
+    const paths = new Set([
+        join(scope.agentDir, "settings.json"),
+        join(scope.agentDir, "extensions"),
+        join(scope.agentDir, "trust.json"),
+        join(scope.cwd, CONFIG_DIR_NAME, "settings.json"),
+        join(scope.cwd, CONFIG_DIR_NAME, "extensions"),
+    ]);
+    for (const path of extensionPaths) {
+        if (!isAbsolute(path))
+            continue;
+        paths.add(path);
+        paths.add(dirname(path));
+    }
+    for (const path of scope.cliExtensionPaths) {
+        if (!isAbsolute(path))
+            continue;
+        paths.add(path);
+    }
+    return [...paths].sort();
+}
+function readCacheFile(agentDir) {
+    try {
+        const parsed = JSON.parse(readFileSync(cachePath(agentDir), "utf8"));
+        if (parsed.version !== CACHE_FILE_VERSION || typeof parsed.scopes !== "object" || parsed.scopes === null) {
+            return undefined;
+        }
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Flags a previous run resolved for this exact scope, or `undefined` when anything that feeds
+ * extension discovery changed. Never throws: a help screen must not depend on its own cache.
+ */
+export function readHelpFlagsCache(scope) {
+    const cached = readCacheFile(scope.agentDir)?.scopes[scopeKey(scope)];
+    if (!cached || cached.appVersion !== DISPLAY_VERSION || !Array.isArray(cached.inputs))
+        return undefined;
+    for (const input of cached.inputs) {
+        if (stamp(input.path) !== input.state)
+            return undefined;
+    }
+    return [...cached.flags];
+}
+/**
+ * Record the flags a full extension load produced. Failure is silent by contract: this runs on
+ * the startup path, where a cache write must never be the reason a launch fails.
+ */
+export function writeHelpFlagsCache(options) {
+    const { scope, flags, extensionPaths } = options;
+    try {
+        const existing = readCacheFile(scope.agentDir);
+        const scopes = { ...(existing?.scopes ?? {}) };
+        scopes[scopeKey(scope)] = {
+            writtenAt: Date.now(),
+            appVersion: DISPLAY_VERSION,
+            inputs: discoveryInputs(scope, extensionPaths).map((path) => ({ path, state: stamp(path) })),
+            flags: [...flags],
+        };
+        const keptEntries = Object.entries(scopes)
+            .sort(([, left], [, right]) => right.writtenAt - left.writtenAt)
+            .slice(0, MAX_CACHED_SCOPES);
+        const file = { version: CACHE_FILE_VERSION, scopes: Object.fromEntries(keptEntries) };
+        const target = cachePath(scope.agentDir);
+        mkdirSync(dirname(target), { recursive: true });
+        const temporary = `${target}.${process.pid}.tmp`;
+        writeFileSync(temporary, JSON.stringify(file), { mode: 0o600 });
+        try {
+            renameSync(temporary, target);
+        }
+        catch (error) {
+            if (existsSync(temporary))
+                rmSync(temporary, { force: true });
+            throw error;
+        }
+    }
+    catch {
+        return;
+    }
+}
+//# sourceMappingURL=help-flags-cache.js.map

package/dist/cli/help-flags-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-flags-cache.js","sourceRoot":"","sources":["../../src/cli/help-flags-cache.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from \"node:crypto\";\nimport { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from \"node:fs\";\nimport { dirname, isAbsolute, join } from \"node:path\";\nimport { CONFIG_DIR_NAME, DISPLAY_VERSION } from \"../config.ts\";\nimport type { ExtensionFlag } from \"../core/extensions/types.ts\";\n\nconst CACHE_FILE_VERSION = 1;\nconst MAX_CACHED_SCOPES = 8;\n\nexport interface HelpFlagsScope {\n\treadonly cwd: string;\n\treadonly agentDir: string;\n\treadonly cliExtensionPaths: readonly string[];\n\treadonly noExtensions: boolean;\n\treadonly projectTrusted: boolean;\n}\n\ninterface InputStamp {\n\treadonly path: string;\n\treadonly state: string;\n}\n\ninterface CachedScope {\n\treadonly writtenAt: number;\n\treadonly appVersion: string;\n\treadonly inputs: readonly InputStamp[];\n\treadonly flags: readonly ExtensionFlag[];\n}\n\ninterface CacheFile {\n\treadonly version: number;\n\treadonly scopes: Record<string, CachedScope>;\n}\n\nfunction cachePath(agentDir: string): string {\n\treturn join(agentDir, \"cache\", \"help-flags.json\");\n}\n\nfunction scopeKey(scope: HelpFlagsScope): string {\n\tconst material = [\n\t\tscope.cwd,\n\t\tscope.noExtensions ? \"no-extensions\" : \"extensions\",\n\t\tscope.projectTrusted ? \"trusted\" : \"untrusted\",\n\t\t...scope.cliExtensionPaths,\n\t].join(\"\\u0000\");\n\treturn createHash(\"sha256\").update(material).digest(\"hex\").slice(0, 32);\n}\n\n/**\n * A path's identity for cache validation. Directories carry only their mtime, which is what\n * changes when an extension file is added or removed inside them; files carry mtime and size,\n * so an in-place upgrade of a bundled plugin invalidates the entry it produced.\n */\nfunction stamp(path: string): string {\n\ttry {\n\t\tconst stats = statSync(path);\n\t\tif (stats.isDirectory()) return `d:${stats.mtimeMs}`;\n\t\treturn `f:${stats.mtimeMs}:${stats.size}`;\n\t} catch {\n\t\treturn \"absent\";\n\t}\n}\n\nfunction discoveryInputs(scope: HelpFlagsScope, extensionPaths: readonly string[]): string[] {\n\tconst paths = new Set<string>([\n\t\tjoin(scope.agentDir, \"settings.json\"),\n\t\tjoin(scope.agentDir, \"extensions\"),\n\t\tjoin(scope.agentDir, \"trust.json\"),\n\t\tjoin(scope.cwd, CONFIG_DIR_NAME, \"settings.json\"),\n\t\tjoin(scope.cwd, CONFIG_DIR_NAME, \"extensions\"),\n\t]);\n\tfor (const path of extensionPaths) {\n\t\tif (!isAbsolute(path)) continue;\n\t\tpaths.add(path);\n\t\tpaths.add(dirname(path));\n\t}\n\tfor (const path of scope.cliExtensionPaths) {\n\t\tif (!isAbsolute(path)) continue;\n\t\tpaths.add(path);\n\t}\n\treturn [...paths].sort();\n}\n\nfunction readCacheFile(agentDir: string): CacheFile | undefined {\n\ttry {\n\t\tconst parsed = JSON.parse(readFileSync(cachePath(agentDir), \"utf8\")) as CacheFile;\n\t\tif (parsed.version !== CACHE_FILE_VERSION || typeof parsed.scopes !== \"object\" || parsed.scopes === null) {\n\t\t\treturn undefined;\n\t\t}\n\t\treturn parsed;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\n/**\n * Flags a previous run resolved for this exact scope, or `undefined` when anything that feeds\n * extension discovery changed. Never throws: a help screen must not depend on its own cache.\n */\nexport function readHelpFlagsCache(scope: HelpFlagsScope): ExtensionFlag[] | undefined {\n\tconst cached = readCacheFile(scope.agentDir)?.scopes[scopeKey(scope)];\n\tif (!cached || cached.appVersion !== DISPLAY_VERSION || !Array.isArray(cached.inputs)) return undefined;\n\tfor (const input of cached.inputs) {\n\t\tif (stamp(input.path) !== input.state) return undefined;\n\t}\n\treturn [...cached.flags];\n}\n\n/**\n * Record the flags a full extension load produced. Failure is silent by contract: this runs on\n * the startup path, where a cache write must never be the reason a launch fails.\n */\nexport function writeHelpFlagsCache(options: {\n\treadonly scope: HelpFlagsScope;\n\treadonly flags: readonly ExtensionFlag[];\n\treadonly extensionPaths: readonly string[];\n}): void {\n\tconst { scope, flags, extensionPaths } = options;\n\ttry {\n\t\tconst existing = readCacheFile(scope.agentDir);\n\t\tconst scopes: Record<string, CachedScope> = { ...(existing?.scopes ?? {}) };\n\t\tscopes[scopeKey(scope)] = {\n\t\t\twrittenAt: Date.now(),\n\t\t\tappVersion: DISPLAY_VERSION,\n\t\t\tinputs: discoveryInputs(scope, extensionPaths).map((path) => ({ path, state: stamp(path) })),\n\t\t\tflags: [...flags],\n\t\t};\n\t\tconst keptEntries = Object.entries(scopes)\n\t\t\t.sort(([, left], [, right]) => right.writtenAt - left.writtenAt)\n\t\t\t.slice(0, MAX_CACHED_SCOPES);\n\t\tconst file: CacheFile = { version: CACHE_FILE_VERSION, scopes: Object.fromEntries(keptEntries) };\n\t\tconst target = cachePath(scope.agentDir);\n\t\tmkdirSync(dirname(target), { recursive: true });\n\t\tconst temporary = `${target}.${process.pid}.tmp`;\n\t\twriteFileSync(temporary, JSON.stringify(file), { mode: 0o600 });\n\t\ttry {\n\t\t\trenameSync(temporary, target);\n\t\t} catch (error) {\n\t\t\tif (existsSync(temporary)) rmSync(temporary, { force: true });\n\t\t\tthrow error;\n\t\t}\n\t} catch {\n\t\treturn;\n\t}\n}\n"]}

package/dist/cli/startup-loading-indicator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"startup-loading-indicator.d.ts","sourceRoot":"","sources":["../../src/cli/startup-loading-indicator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAaxD,MAAM,WAAW,8BAA8B;IAC9C,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,uBAAuB;IACvC,KAAK,IAAI,IAAI,CAAC;IACd,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;IAC1C,KAAK,IAAI,IAAI,CAAC;IACd,MAAM,IAAI,IAAI,CAAC;IACf,IAAI,IAAI,IAAI,CAAC;IACb,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC1B;AA8HD,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,8BAA8B,GAAG,uBAAuB,CAE9G;AAED,wBAAgB,iCAAiC,CAAC,KAAK,EAAE;IACxD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CAChC,GAAG,OAAO,CAEV;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAC1C,OAAO,EAAE,mBAAmB,EAC5B,SAAS,EAAE,IAAI,CAAC,uBAAuB,EAAE,OAAO,GAAG,QAAQ,CAAC,GAC1D,mBAAmB,CAsBrB"}
+{"version":3,"file":"startup-loading-indicator.d.ts","sourceRoot":"","sources":["../../src/cli/startup-loading-indicator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAaxD,MAAM,WAAW,8BAA8B;IAC9C,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,uBAAuB;IACvC,KAAK,IAAI,IAAI,CAAC;IACd,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;IAC1C,KAAK,IAAI,IAAI,CAAC;IACd,MAAM,IAAI,IAAI,CAAC;IACf,IAAI,IAAI,IAAI,CAAC;IACb,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC1B;AAmID,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,8BAA8B,GAAG,uBAAuB,CAE9G;AAED,wBAAgB,iCAAiC,CAAC,KAAK,EAAE;IACxD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CAChC,GAAG,OAAO,CAEV;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAC1C,OAAO,EAAE,mBAAmB,EAC5B,SAAS,EAAE,IAAI,CAAC,uBAAuB,EAAE,OAAO,GAAG,QAAQ,CAAC,GAC1D,mBAAmB,CAsBrB"}

package/dist/cli/startup-loading-indicator.js

@@ -10,9 +10,12 @@ const DEFAULT_INTERVAL_MS = 80;
 /**
  * Single-line ANSI loading indicator for the pre-TUI startup window, borrowed
  * from codex's UI-first startup design (codex-rs/tui keeps a dim placeholder
- * header until the session is configured). The grace delay keeps fast startups
- * flash-free; stop() must run before any other stdout writer (TUI, prompts,
- * help) takes over the terminal.
+ * header until the session is configured). The first frame is written in
+ * start() itself: the work it covers is synchronous module loading, which
+ * starves every timer until it is done, so a timer-driven first frame lands
+ * only after that work (measured: 2.27s to the first byte on a real pty). The
+ * grace delay now gates the animation only; stop() must run before any other
+ * stdout writer (TUI, prompts, help) takes over the terminal.
  */
 class AnsiStartupLoadingIndicator {
     constructor(options) {
@@ -45,6 +48,7 @@ class AnsiStartupLoadingIndicator {
                 this.writer(CLEAR_LINE + SHOW_CURSOR);
         };
         process.on("exit", this.exitListener);
+        this.draw(true);
         this.startGraceTimer();
     }
     setPhase(phase) {
@@ -68,6 +72,7 @@ class AnsiStartupLoadingIndicator {
             this.beginAnimation();
         }
         else {
+            this.draw(true);
             this.startGraceTimer();
         }
     }
@@ -89,7 +94,8 @@ class AnsiStartupLoadingIndicator {
         }, this.graceMs);
     }
     beginAnimation() {
-        this.draw(true);
+        if (!this.drawn)
+            this.draw(true);
         this.frameTimer = setInterval(() => {
             this.frameIndex = (this.frameIndex + 1) % this.frames.length;
             this.draw(false);

package/dist/cli/startup-loading-indicator.js.map

@@ -1 +1 @@
-{"version":3,"file":"startup-loading-indicator.js","sourceRoot":"","sources":["../../src/cli/startup-loading-indicator.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ProjectTrustContext } from \"../core/extensions/types.ts\";\nimport type { AppMode } from \"../core/project-trust.ts\";\n\nconst HIDE_CURSOR = \"\\u001b[?25l\";\nconst SHOW_CURSOR = \"\\u001b[?25h\";\nconst CLEAR_LINE = \"\\r\\u001b[2K\";\nconst DIM = \"\\u001b[2m\";\nconst RESET = \"\\u001b[0m\";\n\nconst DEFAULT_FRAMES = [\"⠋\", \"⠙\", \"⠹\", \"⠸\", \"⠼\", \"⠴\", \"⠦\", \"⠧\", \"⠇\", \"⠏\"] as const;\nconst DEFAULT_LABEL = \"Loading\";\nconst DEFAULT_GRACE_MS = 120;\nconst DEFAULT_INTERVAL_MS = 80;\n\nexport interface StartupLoadingIndicatorOptions {\n\treadonly writer: (chunk: string) => void;\n\treadonly isTTY: boolean;\n\treadonly label?: string;\n\treadonly graceMs?: number;\n\treadonly intervalMs?: number;\n\treadonly frames?: readonly string[];\n}\n\nexport interface StartupLoadingIndicator {\n\tstart(): void;\n\tsetPhase(phase: string | undefined): void;\n\tpause(): void;\n\tresume(): void;\n\tstop(): void;\n\treadonly running: boolean;\n}\n\n/**\n * Single-line ANSI loading indicator for the pre-TUI startup window, borrowed\n * from codex's UI-first startup design (codex-rs/tui keeps a dim placeholder\n * header until the session is configured). The grace delay keeps fast startups\n * flash-free; stop() must run before any other stdout writer (TUI, prompts,\n * help) takes over the terminal.\n */\nclass AnsiStartupLoadingIndicator implements StartupLoadingIndicator {\n\tprivate readonly writer: (chunk: string) => void;\n\tprivate readonly isTTY: boolean;\n\tprivate readonly label: string;\n\tprivate readonly graceMs: number;\n\tprivate readonly intervalMs: number;\n\tprivate readonly frames: readonly string[];\n\tprivate phase: string | undefined = undefined;\n\tprivate frameIndex = 0;\n\tprivate drawn = false;\n\tprivate graceElapsed = false;\n\tprivate started = false;\n\tprivate paused = false;\n\tprivate stopped = false;\n\tprivate graceTimer: NodeJS.Timeout | undefined = undefined;\n\tprivate frameTimer: NodeJS.Timeout | undefined = undefined;\n\tprivate exitListener: (() => void) | undefined = undefined;\n\n\tconstructor(options: StartupLoadingIndicatorOptions) {\n\t\tthis.writer = options.writer;\n\t\tthis.isTTY = options.isTTY;\n\t\tthis.label = options.label ?? DEFAULT_LABEL;\n\t\tthis.graceMs = options.graceMs ?? DEFAULT_GRACE_MS;\n\t\tthis.intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;\n\t\tthis.frames = options.frames && options.frames.length > 0 ? options.frames : DEFAULT_FRAMES;\n\t}\n\n\tget running(): boolean {\n\t\treturn this.started && !this.stopped;\n\t}\n\n\tstart(): void {\n\t\tif (!this.isTTY || this.started || this.stopped) return;\n\t\tthis.started = true;\n\t\tthis.exitListener = () => {\n\t\t\tif (this.drawn) this.writer(CLEAR_LINE + SHOW_CURSOR);\n\t\t};\n\t\tprocess.on(\"exit\", this.exitListener);\n\t\tthis.startGraceTimer();\n\t}\n\n\tsetPhase(phase: string | undefined): void {\n\t\tthis.phase = phase;\n\t\tif (this.drawn && !this.paused && !this.stopped) {\n\t\t\tthis.draw(false);\n\t\t}\n\t}\n\n\tpause(): void {\n\t\tif (!this.started || this.stopped || this.paused) return;\n\t\tthis.paused = true;\n\t\tthis.clearTimers();\n\t\tthis.eraseLine();\n\t}\n\n\tresume(): void {\n\t\tif (!this.started || this.stopped || !this.paused) return;\n\t\tthis.paused = false;\n\t\tif (this.graceElapsed) {\n\t\t\tthis.beginAnimation();\n\t\t} else {\n\t\t\tthis.startGraceTimer();\n\t\t}\n\t}\n\n\tstop(): void {\n\t\tif (this.stopped) return;\n\t\tthis.stopped = true;\n\t\tthis.clearTimers();\n\t\tthis.eraseLine();\n\t\tif (this.exitListener) {\n\t\t\tprocess.removeListener(\"exit\", this.exitListener);\n\t\t\tthis.exitListener = undefined;\n\t\t}\n\t}\n\n\tprivate startGraceTimer(): void {\n\t\tthis.graceTimer = setTimeout(() => {\n\t\t\tthis.graceElapsed = true;\n\t\t\tthis.beginAnimation();\n\t\t}, this.graceMs);\n\t}\n\n\tprivate beginAnimation(): void {\n\t\tthis.draw(true);\n\t\tthis.frameTimer = setInterval(() => {\n\t\t\tthis.frameIndex = (this.frameIndex + 1) % this.frames.length;\n\t\t\tthis.draw(false);\n\t\t}, this.intervalMs);\n\t}\n\n\tprivate draw(hideCursor: boolean): void {\n\t\tconst frame = this.frames[this.frameIndex] ?? \"\";\n\t\tconst phaseSuffix = this.phase ? ` ${this.phase}` : \"\";\n\t\tconst line = `${DIM}${frame} ${this.label}…${phaseSuffix}${RESET}`;\n\t\tthis.writer(`${hideCursor ? HIDE_CURSOR : \"\"}${CLEAR_LINE}${line}`);\n\t\tthis.drawn = true;\n\t}\n\n\tprivate eraseLine(): void {\n\t\tif (!this.drawn) return;\n\t\tthis.writer(CLEAR_LINE + SHOW_CURSOR);\n\t\tthis.drawn = false;\n\t}\n\n\tprivate clearTimers(): void {\n\t\tif (this.graceTimer) {\n\t\t\tclearTimeout(this.graceTimer);\n\t\t\tthis.graceTimer = undefined;\n\t\t}\n\t\tif (this.frameTimer) {\n\t\t\tclearInterval(this.frameTimer);\n\t\t\tthis.frameTimer = undefined;\n\t\t}\n\t}\n}\n\nexport function createStartupLoadingIndicator(options: StartupLoadingIndicatorOptions): StartupLoadingIndicator {\n\treturn new AnsiStartupLoadingIndicator(options);\n}\n\nexport function shouldShowStartupLoadingIndicator(input: {\n\treadonly appMode: AppMode;\n\treadonly stdoutIsTTY: boolean;\n\treadonly helpRequested: boolean;\n}): boolean {\n\treturn input.appMode === \"interactive\" && input.stdoutIsTTY && !input.helpRequested;\n}\n\n/**\n * Project-trust prompts open their own startup TUI mid-load; pausing the\n * indicator around each prompt keeps the two from fighting over the terminal.\n */\nexport function pauseIndicatorDuringPrompts(\n\tcontext: ProjectTrustContext,\n\tindicator: Pick<StartupLoadingIndicator, \"pause\" | \"resume\">,\n): ProjectTrustContext {\n\tconst wrapPrompt =\n\t\t<Args extends readonly unknown[], Result>(\n\t\t\tprompt: (...args: Args) => Promise<Result>,\n\t\t): ((...args: Args) => Promise<Result>) =>\n\t\tasync (...args: Args): Promise<Result> => {\n\t\t\tindicator.pause();\n\t\t\ttry {\n\t\t\t\treturn await prompt(...args);\n\t\t\t} finally {\n\t\t\t\tindicator.resume();\n\t\t\t}\n\t\t};\n\treturn {\n\t\t...context,\n\t\tui: {\n\t\t\tselect: wrapPrompt(context.ui.select),\n\t\t\tconfirm: wrapPrompt(context.ui.confirm),\n\t\t\tinput: wrapPrompt(context.ui.input),\n\t\t\tnotify: context.ui.notify,\n\t\t},\n\t};\n}\n"]}
+{"version":3,"file":"startup-loading-indicator.js","sourceRoot":"","sources":["../../src/cli/startup-loading-indicator.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ProjectTrustContext } from \"../core/extensions/types.ts\";\nimport type { AppMode } from \"../core/project-trust.ts\";\n\nconst HIDE_CURSOR = \"\\u001b[?25l\";\nconst SHOW_CURSOR = \"\\u001b[?25h\";\nconst CLEAR_LINE = \"\\r\\u001b[2K\";\nconst DIM = \"\\u001b[2m\";\nconst RESET = \"\\u001b[0m\";\n\nconst DEFAULT_FRAMES = [\"⠋\", \"⠙\", \"⠹\", \"⠸\", \"⠼\", \"⠴\", \"⠦\", \"⠧\", \"⠇\", \"⠏\"] as const;\nconst DEFAULT_LABEL = \"Loading\";\nconst DEFAULT_GRACE_MS = 120;\nconst DEFAULT_INTERVAL_MS = 80;\n\nexport interface StartupLoadingIndicatorOptions {\n\treadonly writer: (chunk: string) => void;\n\treadonly isTTY: boolean;\n\treadonly label?: string;\n\treadonly graceMs?: number;\n\treadonly intervalMs?: number;\n\treadonly frames?: readonly string[];\n}\n\nexport interface StartupLoadingIndicator {\n\tstart(): void;\n\tsetPhase(phase: string | undefined): void;\n\tpause(): void;\n\tresume(): void;\n\tstop(): void;\n\treadonly running: boolean;\n}\n\n/**\n * Single-line ANSI loading indicator for the pre-TUI startup window, borrowed\n * from codex's UI-first startup design (codex-rs/tui keeps a dim placeholder\n * header until the session is configured). The first frame is written in\n * start() itself: the work it covers is synchronous module loading, which\n * starves every timer until it is done, so a timer-driven first frame lands\n * only after that work (measured: 2.27s to the first byte on a real pty). The\n * grace delay now gates the animation only; stop() must run before any other\n * stdout writer (TUI, prompts, help) takes over the terminal.\n */\nclass AnsiStartupLoadingIndicator implements StartupLoadingIndicator {\n\tprivate readonly writer: (chunk: string) => void;\n\tprivate readonly isTTY: boolean;\n\tprivate readonly label: string;\n\tprivate readonly graceMs: number;\n\tprivate readonly intervalMs: number;\n\tprivate readonly frames: readonly string[];\n\tprivate phase: string | undefined = undefined;\n\tprivate frameIndex = 0;\n\tprivate drawn = false;\n\tprivate graceElapsed = false;\n\tprivate started = false;\n\tprivate paused = false;\n\tprivate stopped = false;\n\tprivate graceTimer: NodeJS.Timeout | undefined = undefined;\n\tprivate frameTimer: NodeJS.Timeout | undefined = undefined;\n\tprivate exitListener: (() => void) | undefined = undefined;\n\n\tconstructor(options: StartupLoadingIndicatorOptions) {\n\t\tthis.writer = options.writer;\n\t\tthis.isTTY = options.isTTY;\n\t\tthis.label = options.label ?? DEFAULT_LABEL;\n\t\tthis.graceMs = options.graceMs ?? DEFAULT_GRACE_MS;\n\t\tthis.intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;\n\t\tthis.frames = options.frames && options.frames.length > 0 ? options.frames : DEFAULT_FRAMES;\n\t}\n\n\tget running(): boolean {\n\t\treturn this.started && !this.stopped;\n\t}\n\n\tstart(): void {\n\t\tif (!this.isTTY || this.started || this.stopped) return;\n\t\tthis.started = true;\n\t\tthis.exitListener = () => {\n\t\t\tif (this.drawn) this.writer(CLEAR_LINE + SHOW_CURSOR);\n\t\t};\n\t\tprocess.on(\"exit\", this.exitListener);\n\t\tthis.draw(true);\n\t\tthis.startGraceTimer();\n\t}\n\n\tsetPhase(phase: string | undefined): void {\n\t\tthis.phase = phase;\n\t\tif (this.drawn && !this.paused && !this.stopped) {\n\t\t\tthis.draw(false);\n\t\t}\n\t}\n\n\tpause(): void {\n\t\tif (!this.started || this.stopped || this.paused) return;\n\t\tthis.paused = true;\n\t\tthis.clearTimers();\n\t\tthis.eraseLine();\n\t}\n\n\tresume(): void {\n\t\tif (!this.started || this.stopped || !this.paused) return;\n\t\tthis.paused = false;\n\t\tif (this.graceElapsed) {\n\t\t\tthis.beginAnimation();\n\t\t} else {\n\t\t\tthis.draw(true);\n\t\t\tthis.startGraceTimer();\n\t\t}\n\t}\n\n\tstop(): void {\n\t\tif (this.stopped) return;\n\t\tthis.stopped = true;\n\t\tthis.clearTimers();\n\t\tthis.eraseLine();\n\t\tif (this.exitListener) {\n\t\t\tprocess.removeListener(\"exit\", this.exitListener);\n\t\t\tthis.exitListener = undefined;\n\t\t}\n\t}\n\n\tprivate startGraceTimer(): void {\n\t\tthis.graceTimer = setTimeout(() => {\n\t\t\tthis.graceElapsed = true;\n\t\t\tthis.beginAnimation();\n\t\t}, this.graceMs);\n\t}\n\n\tprivate beginAnimation(): void {\n\t\tif (!this.drawn) this.draw(true);\n\t\tthis.frameTimer = setInterval(() => {\n\t\t\tthis.frameIndex = (this.frameIndex + 1) % this.frames.length;\n\t\t\tthis.draw(false);\n\t\t}, this.intervalMs);\n\t}\n\n\tprivate draw(hideCursor: boolean): void {\n\t\tconst frame = this.frames[this.frameIndex] ?? \"\";\n\t\tconst phaseSuffix = this.phase ? ` ${this.phase}` : \"\";\n\t\tconst line = `${DIM}${frame} ${this.label}…${phaseSuffix}${RESET}`;\n\t\tthis.writer(`${hideCursor ? HIDE_CURSOR : \"\"}${CLEAR_LINE}${line}`);\n\t\tthis.drawn = true;\n\t}\n\n\tprivate eraseLine(): void {\n\t\tif (!this.drawn) return;\n\t\tthis.writer(CLEAR_LINE + SHOW_CURSOR);\n\t\tthis.drawn = false;\n\t}\n\n\tprivate clearTimers(): void {\n\t\tif (this.graceTimer) {\n\t\t\tclearTimeout(this.graceTimer);\n\t\t\tthis.graceTimer = undefined;\n\t\t}\n\t\tif (this.frameTimer) {\n\t\t\tclearInterval(this.frameTimer);\n\t\t\tthis.frameTimer = undefined;\n\t\t}\n\t}\n}\n\nexport function createStartupLoadingIndicator(options: StartupLoadingIndicatorOptions): StartupLoadingIndicator {\n\treturn new AnsiStartupLoadingIndicator(options);\n}\n\nexport function shouldShowStartupLoadingIndicator(input: {\n\treadonly appMode: AppMode;\n\treadonly stdoutIsTTY: boolean;\n\treadonly helpRequested: boolean;\n}): boolean {\n\treturn input.appMode === \"interactive\" && input.stdoutIsTTY && !input.helpRequested;\n}\n\n/**\n * Project-trust prompts open their own startup TUI mid-load; pausing the\n * indicator around each prompt keeps the two from fighting over the terminal.\n */\nexport function pauseIndicatorDuringPrompts(\n\tcontext: ProjectTrustContext,\n\tindicator: Pick<StartupLoadingIndicator, \"pause\" | \"resume\">,\n): ProjectTrustContext {\n\tconst wrapPrompt =\n\t\t<Args extends readonly unknown[], Result>(\n\t\t\tprompt: (...args: Args) => Promise<Result>,\n\t\t): ((...args: Args) => Promise<Result>) =>\n\t\tasync (...args: Args): Promise<Result> => {\n\t\t\tindicator.pause();\n\t\t\ttry {\n\t\t\t\treturn await prompt(...args);\n\t\t\t} finally {\n\t\t\t\tindicator.resume();\n\t\t\t}\n\t\t};\n\treturn {\n\t\t...context,\n\t\tui: {\n\t\t\tselect: wrapPrompt(context.ui.select),\n\t\t\tconfirm: wrapPrompt(context.ui.confirm),\n\t\t\tinput: wrapPrompt(context.ui.input),\n\t\t\tnotify: context.ui.notify,\n\t\t},\n\t};\n}\n"]}

package/dist/cli.js

@@ -120,6 +120,15 @@ if (isRootCommand(args) && (args.includes("--version") || args.includes("-v")))
     console.log(DISPLAY_VERSION);
     process.exit();
 }
+// Help is static text plus the flags extensions registered, so a launch that already knows those
+// flags must not import the engine graph to print them. The import stays dynamic for the same
+// reason `cli-main` is: a static one would evaluate that graph before this answer.
+if (isRootCommand(args) && args.some((arg) => arg === "--help" || arg === "-h")) {
+    const { tryPrintHelpWithoutEngine } = await import("./cli/help-fast-path.js");
+    if (tryPrintHelpWithoutEngine(args)) {
+        process.exit();
+    }
+}
 if (isMissingBundledWorkspaceDependencies(getPackageDir())) {
     if (await handleBootstrapSelfUpdate(args)) {
         process.exit();