changes.md

## 2026-10-25 - Host-owned MCP presenter deployment options (#4197)

### What changed

- `main.ts`: pass the deployment switch to the RPC host and interactive terminal, and the reserved bootstrap descriptor to the host without copying the descriptor into session-worker runtime configuration.

### Why

- Presenter enrollment belongs to the launch owner, not a project setting, ordinary RPC role, or worker launch specification.

### Key decisions

- Enforcement is explicitly enabled with `--mcp-presenter-enforcement`. Without it, existing RPC and terminal MCP UI behavior remains unchanged.

### Why an extension could not handle it

- The entry point owns process descriptors and the configuration handed to workers.

### Expected merge conflict zones

- LOW: RPC-host construction in `main.ts`.

## 2026-10-24 - Fresh standalone CLI sessions accept task ancestry (oh-my-openagent#10782)

### What changed

- `packages/coding-agent/src/main.ts`: passes ancestry to fresh session creation and warns when session selection ignores it, preserving existing headers and ordinary fork identity.

### Why

- `packages/coding-agent/src/main.ts`: lifecycle role is derived from the header before the first prompt.

### Why an extension could not handle it

- `packages/coding-agent/src/main.ts`: the session header is created before runtime construction.

### Expected merge conflict zones

- `packages/coding-agent/src/main.ts`: `createSessionManager`.

## 2026-10-24 - Host commands select endpoint credentials without changing the profile (senpi#3815)

### What changed

- `packages/coding-agent/src/cli/host-command.ts` and `packages/coding-agent/src/cli/host-session-command.ts`: accept `--rpc-key-root <dir>` and run the host request inside that credential root, so nested probes and ensures authenticate against it. `SENPI_RPC_KEY_ROOT` is the environment default, then the agent dir. Settings, skills, MCP configuration and every other profile input stay the caller's.
- `packages/coding-agent/src/cli/host-command-args.ts` (new, fork-only): the host argument parser, moved out of `host-command.ts` (which re-exports `parseHostArgs`), with the new flag.

### Why

- `packages/coding-agent/src/cli/host-command.ts`, `packages/coding-agent/src/cli/host-session-command.ts`: a client running under a separate profile must still prove the key of the endpoint it dials.

### Why an extension could not handle it

- `packages/coding-agent/src/cli/host-command.ts`, `packages/coding-agent/src/cli/host-session-command.ts`: host CLI parsing and endpoint startup run before any session extension loads.

### Expected merge conflict zones

- LOW: option parsing, usage text and the runner call in `packages/coding-agent/src/cli/host-command.ts` and `packages/coding-agent/src/cli/host-session-command.ts`.

## 2026-10-23 - Print formats share the final failure exit status (senpi#4061)

### What changed

- `packages/coding-agent/src/modes/print-mode.ts`: after settlement, select the last assistant once and use one `error`/`aborted` decision for both formats' exit status and text diagnostics. This supersedes the JSON compaction-only exception recorded below.

### Why

- JSON output reported provider failures but returned success to scripts. Only the final settled response decides the status, so a recovered retry remains successful.

### Why an extension could not handle it

- Print mode owns the process exit status after extensions and retries finish.

### Expected merge conflict zones

- `packages/coding-agent/src/modes/print-mode.ts`: the block after `waitForSettledSessionWork()` and the text diagnostic branch.

## 2026-10-22 - Export the reserved custody key error (senpi#3986)

### What changed

- `packages/coding-agent/src/index.ts`: exports `ReservedCustodyKey`, the error `pi.lifecycle.obligations` throws for a key under an engine prefix.

### Why

- `packages/coding-agent/src/index.ts`: extensions need the class to catch the refusal by type.

### Why an extension could not handle it

- `packages/coding-agent/src/index.ts`: an extension can only import what the package exports.

### Expected merge conflict zones

- `packages/coding-agent/src/index.ts`: the export line after the `session-lifecycle-types.ts` export block.

## 2026-10-20 - Internal RPC stdin bootstrap precedes the CLI graph (senpi#3795)

### What changed

- `packages/coding-agent/src/cli-main.ts`: imports the POSIX internal-host bootstrap before any CLI module can touch stdin.
- `packages/coding-agent/src/bun/cli.ts`: imports the same bootstrap after sandbox env restoration and before runtime setup.

### Why

- `packages/coding-agent/src/cli-main.ts` and `packages/coding-agent/src/bun/cli.ts`: the internal key must be consumed synchronously before the runtime instantiates `process.stdin`, then fd 0 must become `/dev/null` for descendants. Launchers keep forwarding stdin unchanged.

### Why an extension could not handle it

- `packages/coding-agent/src/cli-main.ts` and `packages/coding-agent/src/bun/cli.ts`: extensions load after the CLI graph and cannot own the first stdin read.

### Expected merge conflict zones

- LOW: the initial side-effect import order in `packages/coding-agent/src/cli-main.ts` and `packages/coding-agent/src/bun/cli.ts`.

## 2026-10-22 - `--rebind` reads the session's recorded cwd asynchronously (senpi#3676)

### What changed

- `packages/coding-agent/src/main.ts`: `sessionCwdOrUndefined` is now `async` and awaits `readSessionCwd` (`src/core/session-rebind.ts`), which reads the session header with `node:fs/promises`; the `--rebind` branch of `createSessionManager` awaits it. Errors still map to `undefined` exactly as before.

### Why

- The `move_session` RPC commands export a session through `readSessionCwd`, so its header read sits on the shared RPC host's session path, where `test/suite/no-sync-in-session-path.test.ts` forbids new synchronous filesystem calls. Making the one reader async keeps the CLI and the RPC host on a single implementation.

### Why an extension could not handle it

- `--rebind` resolution runs in core before any extension is loaded, and the header reader is shared core code.

### Expected merge conflict zones

- `main.ts`: `sessionCwdOrUndefined` and its `--rebind` call site.

## 2026-10-22 - Replace Biome with oxlint and oxfmt (senpi#3976)

### What changed

- `packages/coding-agent/src/experimental/services/connection.ts`: `oxlint-disable-next-line eslint/prefer-const` comments on the two `let binding!` declarations that a closure reads; `const` would hit the temporal dead zone if that closure ran before the assignment.

### Why

- The repository moved lint and format from Biome to oxlint 1.89.0 and oxfmt 0.74.0 (senpi#3976). oxlint reports this site where Biome did not; the change keeps behaviour identical.

### Why an extension could not handle it

- Lint configuration and source comments are read by the linter before any agent code runs.

### Expected merge conflict zones

- The two `binding` declarations in `connection.ts`.


## 2026-10-21 - llama.cpp declares its API key optional (senpi#3869)

### What changed

- `packages/coding-agent/src/extensions/llama/provider.ts`: the llama.cpp `apiKey` auth sets `keyOptional: true`, so `Models.login` keeps a login whose optional key prompt was left blank.

### Why

- senpi#3867 made `Models.login` refuse blank keys; a keyless local llama-server is a valid setup. Regression: `test/llama-extension.test.ts` ("logs in through Models.login with no API key").

### Why an extension could not handle it

- This is the in-tree llama extension declaring its own auth metadata.

### Expected merge conflict zones

- LOW: the `apiKey` object in `createLlamaProvider`.

## 2026-10-21 - Test runs refuse the real agent directory (senpi#3867)

### What changed

- `packages/coding-agent/src/config.ts`: `getAgentDir()` passes the resolved directory to the new `assertAgentDirAllowedInTests` in the same file; it lives here rather than in a new module so the RPC supervisor's import graph stays at its 55-module ceiling. In a senpi test run (`SENPI_TEST_AGENT_DIR_GUARD=1`, set only by senpi's own test harness and never inferred from `VITEST` or `NODE_ENV`, so a user's own test suite that runs the CLI is unaffected), a directory inside the real account home's `.senpi`, `.omo`, `.pi` or active brand config dir throws `RealAgentDirInTestError`. The real home comes from the account database, not `$HOME`. `SENPI_TEST_USE_REAL_AGENT_DIR=1` opts out, as it already does for the quarantine.

### Why

- senpi#3867: a test run without the Vitest quarantine setup (for example `bun test <file>` from inside an agent session that exports `OMO_CODING_AGENT_DIR`) resolved the user's real agent dir and left faux pool state in `credential-pool-state.json`. Regressions: `test/suite/regressions/issue-3867-real-agent-dir-guard.test.ts` and `issue-3867-built-cli-user-test-env.test.ts` (the built CLI starts under `NODE_ENV=test`/`VITEST` with no senpi marker).

### Why an extension could not handle it

- `getAgentDir()` is the core path resolver every store reads; the guard has to sit where the path is produced.

### Expected merge conflict zones

- LOW: the body of `getAgentDir()` and the import block in `packages/coding-agent/src/config.ts`.

## 2026-10-20 - The host holder type is exported (omo-desktop-app#3561)

### What changed

- `packages/coding-agent/src/modes/index.ts`: exports `describeHostHolder` and `type HostHolder` from `./rpc/host-holder.ts`.
- `packages/coding-agent/src/index.ts`: re-exports `type HostHolder` next to `HostEnsureRefusedError`.

### Why

- `HostEnsureRefusedError.holder` is part of the public refusal; embedders (the omo runner, the desktop) read it with the same type.

### Why an extension could not handle it

- These are the package's public barrels.

### Expected merge conflict zones

- LOW: one export line in each barrel's host block.

## 2026-10-21 - Micro context reads the request measurement (omo#10792)

### What changed

- `packages/coding-agent/src/experimental/micro/runtime.ts`: the micro status context count prefers `Usage.contextUsage` while cumulative usage totals retain their existing fields.

### Why

- `packages/coding-agent/src/experimental/micro/runtime.ts`: the same SDK message must not display cumulative billing as context on this independent surface.

### Why an extension could not handle it

- `packages/coding-agent/src/experimental/micro/runtime.ts`: this runtime owns its own context projection.

### Expected merge conflict zones

- LOW: `packages/coding-agent/src/experimental/micro/runtime.ts`, `contextTokenCount`.

## 2026-10-22 - Export the session lifecycle contract (senpi#3864)

### What changed

- `packages/coding-agent/src/index.ts`: exports lifecycle snapshots, events, child reports, `SpawnedBy`, self-settle results and obligation/ticket interfaces.

### Why

- `packages/coding-agent/src/index.ts`: RPC clients and the desktop type against them.

### Why an extension could not handle it

- `packages/coding-agent/src/index.ts`: the package entry point is core.

### Expected merge conflict zones

- `packages/coding-agent/src/index.ts`: type export list.

## 2026-10-21 - Export the shared session lifecycle contract (senpi#3864)

### What changed

`packages/coding-agent/src/index.ts` exports lifecycle snapshots, events, child reports, spawned-session identity, self-settle results and obligation/ticket interfaces.

### Why

`packages/coding-agent/src/index.ts`: RPC clients and extension producers need the engine's named contract rather than separate copies.

### Why an extension could not handle it

`packages/coding-agent/src/index.ts`: the package's public entry point and its declarations belong to the engine.

### Expected merge conflict zones

`packages/coding-agent/src/index.ts`: core session type exports.

## 2026-10-18 - A session is found by the id its file name carries (oh-my-openagent#7471)

### What changed

- `packages/coding-agent/src/main.ts`: `resolveSessionPath` matches the header id first, then the id the file name carries, then an id prefix, for both the project and the global listing. `findLocalSessionByExactId` (`--session-id`) also matches the id the file name carries, so it opens that session instead of creating a second file under the same id.

### Why

A session file named `<timestamp>_<id>.jsonl` whose header carried a different id could not be opened with `--session <id>`, though the file name (and the resume hint printed from it) named that id; `--session-id <id>` then created a second session under the same id.

### Why an extension could not handle it

Session creation and `--session` resolution run in core before any extension is loaded.

### Expected merge conflict zones

- `main.ts`: `resolveSessionPath`, `findLocalSessionByExactId` and the import line.

## 2026-10-19 - Print mode stops waiting for a silent stdin pipe (senpi#3715)

### What changed

- `packages/coding-agent/src/main.ts`: the inline `readPipedStdin` (which resolved only on stdin `end` for any non-TTY stdin) is replaced by the fork-only `src/utils/piped-stdin.ts`, called with `hasPromptArgument` (positional messages or `@file` arguments) and `forceRead` (a bare `-`). With a prompt argument, a pipe or socket that delivers no data within `PIPED_STDIN_GRACE_MS` (2000 ms) is paused, unref'd and skipped; data inside the window, a regular file, no prompt argument, and `-` keep the read-to-EOF behavior. A skipped stdin prints one stderr line (`PIPED_STDIN_SKIP_HINT`, built with the options in the fork-only `src/cli/piped-stdin-options.ts`) naming `-` as the way to read it.

### Why

- ssh, CI runners and agent harnesses give children a stdin that is open but never written or closed, so `senpi -p "prompt"` blocked before startup forever at 0% CPU. Regression: `test/suite/regressions/issue-3715-print-stdin-open-pipe.test.ts`.

### Why an extension could not handle it

- stdin is read in `main` before the initial message is built and before print mode starts; no extension hook runs earlier.

### Expected merge conflict zones

- LOW: the `readPipedStdin` call site before `prepareInitialMessage` and the utils import block.

## 2026-10-19 - Print mode marks its quit as a process exit (senpi#3711)

### What changed

- `packages/coding-agent/src/modes/print-mode.ts`: `disposeRuntime` calls `runtimeHost.dispose({ processExit: true })`.

### Why

- The total quit budget (senpi#3711) must only cut handlers when the process really exits right after; an RPC host closing one session keeps running, so there a detached handler would keep running while its extension's handles and provider scope are closed.

### Why an extension could not handle it

- Print mode's shutdown is host code, not an extension surface.

### Expected merge conflict zones

- LOW: `print-mode.ts` `disposeRuntime`.

## 2026-10-19 - Never signal a child whose spawn failed (senpi#3706)

### What changed

- `packages/coding-agent/src/experimental/session-worker-manager.ts`: its stop/timeout/abort path calls `signalSpawnedChild` (`packages/coding-agent/src/utils/child-signal.ts`), which sends nothing to a child without a pid, instead of calling `kill()` on it directly.

### Why

On Node before 24.22.0 / 26.10.0 (nodejs/node#65052), `kill()` on a child whose spawn failed (no pid) becomes `kill(0, signal)` and signals the caller's own process group, killing senpi and the rest of the terminal's foreground job.

### Why an extension could not handle it

The affected calls are inside core stop paths; nothing outside them owns those child processes.

### Expected merge conflict zones

The single `kill()` call on each listed path's stop/timeout/abort branch.

## 2026-10-19 - Subscription limits are polled before the first turn (senpi#3684)

### What changed

- `packages/coding-agent/src/main.ts`: interactive and RPC startup (single-session and the multi-session host) call `startSubscriptionUsagePolling({ agentDir, report })` unless `--offline` is set; print mode never polls. The poller (`src/core/subscription-limits/usage-poller.ts`, fork-only) reads each signed-in Claude and ChatGPT subscription account's usage endpoint into the process's `SubscriptionLimitStore`, sharing one `subscription-usage.json` cache across processes. The newest report wins: a cached poll older than a turn's report never replaces it. A refresh the token endpoint rejects marks the Claude slot `auth_error` (as a turn would), so polling stops asking for that account until `/login`.

### Why

Limits reached hosts only from a turn's response, so a fresh desktop session showed none, while the OmO TUI polled the same endpoints separately: two implementations of one thing.

### Why an extension could not handle it

The store is process-wide and served by the RPC host itself (`get_subscription_limits`); the poll must start with the host process, before any session or extension exists.

### Expected merge conflict zones

- `packages/coding-agent/src/main.ts`: LOW, the import block, the multi-session branch after `initTheme`, and the lines before the `appMode === "rpc"` dispatch.

## 2026-10-18 - The runtime factory threads --tool-runtime into every session it creates (senpi#3566)

### What changed

- `packages/coding-agent/src/main.ts`: `createCliRuntimeFactory` destructures `toolRuntime` from its `CliRuntimeConfiguration` and forwards it to `createAgentSessionFromServices`, so the single-session, interactive, and multi-session paths (which all build sessions through this factory, worker isolates included via their replayed configuration) hand each `AgentSession` its tool runtime instead of re-reading the env.

### Why

The tool dispatcher is per-session state constructed from the once-per-process resolution todo 1 added; a session or worker must never re-derive it.

### Why an extension could not handle it

The runtime factory and the session constructor run before extensions load.

### Expected merge conflict zones

- `packages/coding-agent/src/main.ts`: the `createCliRuntimeFactory` destructure and the `createAgentSessionFromServices` call.

## 2026-10-18 - Every CLI entry becomes the tool-child role first (senpi#3566)

### What changed

- `packages/coding-agent/src/cli.ts` and `packages/coding-agent/src/cli-main.ts`: `import "./internal-role.ts"` directly after the existing `./valid-cwd.ts` guard (which stays the first import).
- `packages/coding-agent/src/rpc-entry.ts`: the same import as its first statement.
- `internal-role.ts` (fork-only) does nothing unless `SENPI_INTERNAL_ROLE` is set. With `tool-child` it runs the tool child and never returns; without its channel environment it exits 70 with `tool-child: channel unavailable` before argument parsing.

### Why

A tool child is started by re-entering the engine binary with a role in its environment (DESIGN PART 1). The role has to be decided before version dispatch, argument parsing or the CLI graph, on every published entry.

### Why an extension could not handle it

Extensions load long after argument parsing; the role must win before any of it.

### Expected merge conflict zones

- `packages/coding-agent/src/cli.ts`, `packages/coding-agent/src/cli-main.ts`, `packages/coding-agent/src/rpc-entry.ts`: the first import lines.

## 2026-10-17 - /share redacts the session, previews it and asks before uploading (senpi#3524)

### What changed

- `packages/coding-agent/src/config.ts`: `getShareViewerUrl` and the `https://pi.dev/session/` default are replaced by `getShareViewerBase()` (the `SHARE_VIEWER_URL` value or undefined) and `isShareDisabledByEnvironment()` (`<PREFIX>_DISABLE_SHARE`).

### Why

- `/share` uploaded the whole session unredacted, with no confirmation, to a secret (unlisted) gist, after writing it to a fixed `os.tmpdir()/session.html`, and pointed users at the third-party `pi.dev` viewer by default. Any key, token, home path or email in a prompt or tool result left the machine in clear text. Regressions: `test/suite/regressions/3524-share-redaction.test.ts`, `test/suite/regressions/3524-share-consent.test.ts`.

### Why an extension could not handle it

- `/share` is a built-in interactive command and the HTML export is core; an extension cannot intercept either before the upload.

### Expected merge conflict zones

- LOW: the share viewer block in `config.ts`.

## 2026-10-18 - The host resolves and advertises its tool runtime (senpi#3566)

### What changed

- `packages/coding-agent/src/main.ts`: right after argument parsing, `resolveToolRuntime(parsed)` (flag, then `SENPI_TOOL_RUNTIME`, then `in-process`) runs once; an invalid env value prints `Error: ...` and exits 1, like an invalid flag, except for `--version` and `--help`, which run no tool. `CliRuntimeConfiguration` gains an optional `toolRuntime` (absent means `in-process`), set on both the multi-session and the single-session configuration, `runMultiSessionHost` receives `toolRuntime`, which the router advertises as `tool_runtime:<value>` in `get_protocol_info`, and `runRpcMode(runtime, toolRuntime)` does the same for a single-session RPC process.

### Why

Clients must be able to see which tool runtime a host they attach to uses, and a worker isolate must not re-read the env to learn it.

### Why an extension could not handle it

The host's startup configuration and its protocol answer are assembled in core before extensions load.

### Expected merge conflict zones

- `packages/coding-agent/src/main.ts`: the parse-diagnostics block in `main`, `CliRuntimeConfiguration`, and the `runMultiSessionHost` call.

## 2026-10-16 - Non-interactive startup reports context size warnings once (senpi#3460)

### What changed

- `main.ts`: print, JSON, and RPC startup report only the loader warnings tagged `category: "size-limit"` through `reportDiagnostics`, retaining a diagnostic's path as a prefix. Pre-existing skill validation warnings stay silent on stderr. The size checks themselves no longer print, and interactive startup leaves their warnings to the TUI resource notices.

### Why

Returning diagnostics lets the owning mode display them without duplicate stderr output.

### Why an extension could not handle it

Core resources load before mode startup.

### Expected merge conflict zones

- `main.ts`: the non-interactive diagnostics block after runtime creation.

## 2026-10-16 - A full-access session trusts its project without asking (senpi#3414)

### What changed

- `main.ts` `createServices` (inside `createCliRuntimeFactory`, which builds every interactive and RPC host session): an explicit `full-access` preset (`presetTrustsProject` in `core/project-trust.ts`) skips the "Trust project folder?" prompt and trusts the project for that session only, with no cache and no trust-store write. A saved "do not trust", `--no-trust` and an answer already given in this host still win. Details: `core/changes.md`.

### Why

Full access means no prompt anywhere (sisyphuslabs/omo-desktop-app#2465); the trust prompt never read the preset.

### Why an extension could not handle it

Project trust is decided before extensions load and decides whether project extensions load at all.

### Expected merge conflict zones

`main.ts` `createServices`, the trust block before `createAgentSessionServices`.

## 2026-10-15 - The package exports the abort cause type (senpi#3357)

### What changed

- `packages/coding-agent/src/index.ts`: exports the `AgentAbortCause` type, so RPC and SDK callers can read `agent_end.abortCause` (set when a turn stops because its session was replaced) with its type.

### Why

- A caller reacting to a replaced session needs the cause's shape; the runtime change is tracked in `core/changes.md`.

### Why an extension could not handle it

- The package's public type surface is defined only by its entry point.

### Expected merge conflict zones

- LOW: the type export list in `src/index.ts`.

## 2026-10-15 - Print and RPC processes contain a retired extension ctx too (senpi#3389)

### What changed

- `packages/coding-agent/src/cli-main.ts`: installs `installStaleExtensionContainment()` (fork-only `core/stale-extension-containment.ts`) right after the early inspector seam. It adds one process `uncaughtException` listener that logs and contains only the stale-ctx guard (`StaleExtensionContextError`) and keeps every other uncaught throw fatal (`console.error` + exit 1), unless interactive mode has registered its own handler (`markModeCrashHandler`). It adds no `unhandledRejection` listener: that would change the default routing of every rejection, including the Inspector rejection the early seam recovers. So under Bun an async stale throw in print or RPC mode still exits, as before; the TUI already logs rejections and keeps running.
- `packages/coding-agent/src/inspector-policy.ts`: the early inspector listener defers only to a handler interactive mode registered with `markModeCrashHandler` (fork-only `core/bootstrap-crash-listeners.ts`), never to another bootstrap or library listener; it leaves a stale-ctx error to the containment seam, and the containment seam leaves the recoverable Inspector rejection to it. Before this, with `SENPI_RECOVER_INSPECTOR_VM_IMPORT=1`, the two bootstrap listeners each deferred to the other and a real crash kept the process running.

### Why

- Print mode and the RPC host have no crash handler of their own, so the same stale-ctx throw from a timer ended a headless run or every session on a host (senpi#3389, oh-my-openagent#7114).

### Why an extension could not handle it

- The listener has to exist before any extension loads, and process-wide; the entry point is the only place that covers every mode.

### Expected merge conflict zones

- LOW: the bootstrap block in `cli-main.ts` beside `installEarlyInspectorVmImportRecovery()`; the listener registration and `otherHandlerActive` check in `inspector-policy.ts`.

## 2026-10-14 - A model that cannot start is reported, not crashed on (senpi#3333)

### What changed

- `packages/coding-agent/src/main.ts`: a `ModelUsabilityBudgetError` from `createAgentSessionRuntime` prints its one-line message in red and exits 1, instead of escaping as an uncaught error with a stack and minified bundle source.

### Why

The startup refusal is the user's to fix; a stack trace hid the reason and the fix.

### Why an extension could not handle it

The error is thrown while the runtime is created, before extensions are bound.

### Expected merge conflict zones

- `packages/coding-agent/src/main.ts`: the `createAgentSessionRuntime` call.

## 2026-10-12 - Retire Codex app-server compatibility (senpi#3167)

### What changed

Remove app-server dispatch and its mode/trust special cases from CLI startup. The parser refuses the retired command rather than treating it as a prompt.

- `packages/coding-agent/src/main.ts`

### Why

The executable Codex compatibility layer is being removed. Shared Native runtime behavior and historical records must remain independent of that layer.

### Why an extension could not handle it

These host contracts, import paths and build or verification targets belong to the repository; an extension cannot retire them.

### Expected merge conflict zones

The listed paths, especially command dispatch, mode unions and process identity imports. Keep the supported runtime branches and the shared utility behavior.

## 2026-10-12 - Print-then-exit commands skip startup compile caching (senpi#3166)

### What changed

- `packages/coding-agent/src/compile-cache.ts`: `enableStartupCompileCache` checks command arguments before enabling or publishing the cache. Package and host routing reuse `cli/deferred-commands.ts`; schedule commands skip caching except `run --watch`. Root `--version`/`-v` uses the same parser-free check as `cli.ts`. Other candidate help/list/export flags lazily use the existing argument parser so prompt and option values do not disable session caching. Parse/import failures fall through to the previous cache enablement behavior, leaving errors to the CLI. Multi-session RPC hosts retain caching even with `--help`. Ordinary sessions still enable the cache before loading the parser.
- `packages/coding-agent/src/cli.ts` and `packages/coding-agent/src/cli-main.ts` await the shared decision before continuing startup, including help's fast path and isolated child entries.
- `packages/coding-agent/test/compile-cache-invocation.test.ts` observes the enable call and inherited environment without timing thresholds, including legacy provider IDs, deferred commands, schedule watchers and multi-session RPC hosts. `packages/coding-agent/test/compile-cache.test.ts` observes parser module resolution to protect the parser-free version path; its cache subprocess drivers await the decision. Node-bundle smoke tests are unchanged.

### Why

Bun 1.4.3 writes a cold compile cache at process exit more slowly than 1.4.2. Metadata-only invocations paid this shutdown cost despite never opening a session. Real sessions retain compile caching for later launches.

An externally supplied `NODE_COMPILE_CACHE` remains untouched: the runtime may enable that cache before CLI startup, so skipping senpi's programmatic enablement does not disable the external cache.

### Why an extension could not handle it

Cache enablement happens in the CLI bootstrap before extension loading and before the help fast path.

### Expected merge conflict zones

- LOW: the shared startup compile-cache helper and its two entry-point calls. Preserve the pre-import ordering for sessions and await the command decision.

## 2026-10-12 - Remove the /llama llama.cpp integration (senpi#3202)

### What changed

- `packages/coding-agent/src/extensions/llama/index.ts`: deleted. This was the built-in `/llama` extension entry point.
- `packages/coding-agent/src/extensions/llama/client.ts`: deleted. The llama-server client.
- `packages/coding-agent/src/extensions/llama/provider.ts`: deleted. The llama.cpp provider and slash command wiring.
- `packages/coding-agent/src/extensions/llama/ui.ts`: deleted. The `/llama` model-management UI.
- `packages/coding-agent/src/extensions/llama/huggingface.ts`: deleted. The Hugging Face download helper used only by `/llama`.
- `packages/coding-agent/src/extensions/index.ts`: `builtInExtensions` becomes an empty array; the llama.cpp extension was its only entry.

### Why

- `packages/coding-agent/src/extensions/llama/index.ts`: Q ordered removal of the `/llama` entry point.
- `packages/coding-agent/src/extensions/llama/client.ts`: the removed integration was this client's only consumer.
- `packages/coding-agent/src/extensions/llama/provider.ts`: the removed integration owned this provider.
- `packages/coding-agent/src/extensions/llama/ui.ts`: the removed command owned this management UI.
- `packages/coding-agent/src/extensions/llama/huggingface.ts`: the removed command owned this download helper.
- `packages/coding-agent/src/extensions/index.ts`: the host must no longer register the deleted extension.

### Why an extension could not handle it

- `packages/coding-agent/src/extensions/llama/index.ts`: an extension cannot delete a shipped entry point.
- `packages/coding-agent/src/extensions/llama/client.ts`: an extension cannot delete the shipped client.
- `packages/coding-agent/src/extensions/llama/provider.ts`: an extension cannot delete the shipped provider.
- `packages/coding-agent/src/extensions/llama/ui.ts`: an extension cannot delete the shipped management UI.
- `packages/coding-agent/src/extensions/llama/huggingface.ts`: an extension cannot delete the shipped download helper.
- `packages/coding-agent/src/extensions/index.ts`: only the host can remove its built-in registration.

### Expected merge conflict zones

- `packages/coding-agent/src/extensions/llama/index.ts`: deleted; upstream edits will conflict.
- `packages/coding-agent/src/extensions/llama/client.ts`: deleted; upstream edits will conflict.
- `packages/coding-agent/src/extensions/llama/provider.ts`: deleted; upstream edits will conflict.
- `packages/coding-agent/src/extensions/llama/ui.ts`: deleted; upstream edits will conflict.
- `packages/coding-agent/src/extensions/llama/huggingface.ts`: deleted; upstream edits will conflict.
- `packages/coding-agent/src/extensions/index.ts`: the `builtInExtensions` list.

## 2026-10-11 - Export eval cell RPC contracts (senpi#3072)

### What changed

- `packages/coding-agent/src/index.ts` and `packages/coding-agent/src/modes/index.ts` export `RpcEvalCell` and `RpcEvalCellSnapshot` beside the established RPC types.

### Why

Typed downstream clients need the new session-owned cell control results through the public coding-agent entry point.

### Why an extension could not handle it

Extensions cannot add exports to the host's public package entry point.

### Expected merge conflict zones

- Additive RPC type export lists in the two barrels; no runtime initialization changes.

## 2026-10-10 - Runtime dependency snapshots omit development payload (#3083 part B)

### What changed

- `packages/coding-agent/src/runtime-snapshot/layout.ts` (fork-only) keeps the full nested/hoisted dependency closure, applying `packages/coding-agent/src/runtime-snapshot/dependency-files.ts` to each dependency's payload. Development trees, root Markdown and extensionless README/changelog/history files are omitted unless a manifest entry names them; license files remain. Redundant TypeScript under `src` is omitted only for packages with an existing built JavaScript entry; source-only extensions, source assets, skills, native binaries and wasm remain.
- `packages/coding-agent/src/runtime-snapshot/tree.ts` and `packages/coding-agent/src/runtime-snapshot/package-files.ts` extract tree planning and the existing shipped-package policy from layout, without changing the package-root selection. The real CLI inventory regression observes Node resolution hooks, Bun loads/resolution and transpiler reads across help, external TypeScript/typebox loading, a faux turn, Claude executable resolution, photon, grep and codemode bootstrap. Glob-only shipping is now tested at the snapshot boundary.

### Why

Copying dependency tests, documentation and duplicate TypeScript sources increases file-system work on every new snapshot. A representative run cannot prove an unvisited provider or dynamic extension will never load a package, so it must not become a package allowlist. Both runtimes resolve the Claude platform binary inside the snapshot; it stays eagerly copied with the existing clone/link/copy mechanism, independent of install updates.

### Why an extension could not handle it

Snapshot materialization precedes extension loading. An extension cannot reduce this first-launch copy or safely repair a missing dependency after an update deletes the original install.

### Expected merge conflict zones

- None upstream: `runtime-snapshot/` is fork-only. Part A's package selection moved from layout into package-files; preserve it when merging other snapshot changes.

## 2026-10-10 - The runtime snapshot copies the shipped package files only (#3083)

### What changed

- `packages/coding-agent/src/runtime-snapshot/layout.ts` (fork-only): `materializeRuntimeSnapshot` plans the package root with `planPackageRoot`, which copies the entries of the package's `files` field (honouring its `!` exclusions, including nested ones such as `!dist/experimental`) plus the files npm always ships (`package.json`, `README*`, `LICENSE*`). A package without `files` is still copied whole. The dependency closure is unchanged.

### Why

From a repository checkout the snapshot copied the package's sources, tests and scripts too: 11,080 files and 508 MB for `packages/coding-agent`. That made the bundle smoke tests' cold start take 2.9 s on CI with Bun 1.4.2 and exceed the 5 s test timeout with Bun 1.4.3 (#3078). A published install already holds only the `files` entries, so it is unaffected.

### Why an extension could not handle it

The snapshot is built before any extension loads, by the launcher that decides where the session runs from.

### Expected merge conflict zones

- None upstream: `runtime-snapshot/` is fork-only.

## 2026-10-09 - `--session <id>` opens a session recorded under a folder the OmO desktop moved here (senpi#2990)

### What changed

- `packages/coding-agent/src/main.ts`: in `createSessionManager`, a `--session <id>` match found in another project (the `global` branch) whose non-empty recorded cwd `resolveMovedPath` maps to the current cwd opens directly instead of offering or printing the cross-project rebind/fork choice. `--continue` without a session dir first asks `movedHereSessionToContinue` (`core/moved-sessions.ts`) for a session the OmO desktop moved here that is newer, by file mtime, than the folder's own newest, so the session used last wins as it already does with a shared session dir. That lookup reads no git identity and lists only dirs whose recorded path moved here. The moved-repository rebind offer, which does both, still runs only when the folder has neither. `SessionManager.open` then maps the cwd; the file is not rewritten.

### Why

After the desktop moves its data home, a session recorded in the old folder sits in that folder's default session dir, so `--session <id>` from the new folder only finds it in the global search. It is the same folder's session, and rebinding or forking it would rewrite or copy a file the desktop expects to stay as it is.

### Why an extension could not handle it

Session selection runs in `main.ts` before any extension loads.

### Expected merge conflict zones

- LOW: the start of the `case "global"` block under `if (parsed.session)` and the `if (parsed.continue)` block in `createSessionManager`.

## 2026-10-08 - Interactive startup warns about live session holders (senpi#2951)

### What changed

- `packages/coding-agent/src/main.ts`: prints the interactive holder warning after runtime creation publishes the CLI's own hold. Existing `--name` validation and persistence stay at their original post-selection location.

### Why

Opening the same JSONL in a CLI and a host silently admitted two writers.

### Why an extension could not handle it

The warning belongs to CLI startup and must work with extensions disabled.

### Expected merge conflict zones

- `packages/coding-agent/src/main.ts`: imports and the block after runtime creation.

## 2026-10-08 - JSON print mode exits non-zero when the run ran out of context (senpi#2925)

### What changed

- `packages/coding-agent/src/modes/print-mode.ts`: in `--mode json`, a run whose last assistant message stopped with `REQUIRED_COMPACTION_ERROR_MESSAGE` returns exit code 1. Text mode already exited 1 on any error stop. JSON mode keeps exit 0 for other error stops, because a JSON consumer reads them from the event stream.

### Why

A parent agent that delegates through `-p --mode json` and only checks the exit code took a run that could not fit its context for an empty success.

### Why an extension could not handle it

The exit code is decided by print mode itself after the session settles.

### Expected merge conflict zones

- LOW: the block after `waitForSettledSessionWork()` in `runPrintMode`.

## 2026-10-08 - An unresolvable session model is a tagged diagnostic (senpi#2906)

### What changed

- `packages/coding-agent/src/main.ts`: `buildSessionOptions` tags the error diagnostic it records when `--model` (or an `open_session` `creationModel`) cannot be resolved with `code: "model_unresolved"`. Message, severity and the standalone CLI's exit are unchanged.

### Why

An RPC host `open_session` whose requested model did not resolve opened anyway on the default model and reported success, because the host never read the diagnostics. The host now fails that open; it needs to tell this one diagnostic apart from every other startup error (extension load failures, auth notes) without matching message text.

### Why an extension could not handle it

Session options are built before any extension loads, and the RPC host's open path is core.

### Expected merge conflict zones

- LOW: the `resolved.error` push in `buildSessionOptions`'s `--model` branch.

## 2026-10-08 - Print-then-exit CLI paths deliver all of their output before exiting (senpi#2937)

### What changed

- `packages/coding-agent/src/cli/print-then-exit.ts` (new): `printThenExit(print, code)` runs the printing function with stdout collected (`console.log` and `process.stdout.write`), writes the collected text as one chunk, waits for that write's own callback and for stderr, then exits. `exitAfterOutput(output, code)` is the same wait for a command that already printed. The wait is bounded (`OUTPUT_DELIVERY_LIMIT_MS`, 30 s, unref'd timer) and an EPIPE from a reader that closed the pipe ends it at once. Output that is already redirected (json mode routes `console.log` to stderr) is not collected.
- `packages/coding-agent/src/main.ts`: `--list-models`, `--version`, `--export`, `--list-tips` and both `--help` branches (plain and the one reached with `--mode`/`-p`) use `printThenExit`; the package, host and schedule commands, which stream their own output, end with `exitAfterOutput`. `host` writes its one line with `writeSync`, so it is complete on both runtimes; package and `schedule` output still streams through `process.stdout`, so under Bun output past the pipe buffer can still be dropped for a reader that falls behind (senpi#2947).
- `packages/coding-agent/src/cli.ts`: the `--version` and help fast paths use the same helper.

### Why

- Under Node a write to a pipe is asynchronous: `process.exit()` right after printing dropped what a slow reader had not taken (0 of 20,000 lines to a reader 1.5 s late) and still exited 0; a consumer of `--list-models` received 541 of 1,843 rows.
- Under Bun `console.log` output queued behind an earlier `process.stdout` write is discarded at exit, and neither a write callback, `Bun.stdout` flush, nor a natural exit recovers it: `senpi --list-models` delivered 0 to 138 KB of 224,697 bytes, exit 0. A single write whose callback is awaited is the shape both runtimes deliver in full (senpi#2937).
- A `drain`-based wait would hang when the queued tail never crossed the high-water mark; the write callback does not depend on it.

### Why an extension could not handle it

- These are CLI entry paths that run before or without any extension.

### Expected merge conflict zones

- LOW: `main.ts` and `cli.ts` at each early-exit branch named above, and their import blocks.

## 2026-10-08 - Brand-dir copy-forward reserved-entry match folds case on darwin and win32 (senpi#2898 review L6)

### What changed

- `packages/coding-agent/src/brand-dir-migration.ts`: `isDesktopReserved` lower-cases the entry on darwin and win32 before matching `desktop` / `desktop.init-*`.

### Why

Those volumes fold case, so `Desktop` is the desktop's own folder there.

### Why an extension could not handle it

The copy-forward runs at startup, before any extension loads.

### Expected merge conflict zones

- Fork-only file. `isDesktopReserved`.

## 2026-10-08 - Brand-dir copy-forward skips the OmO desktop's reserved entries (oh-my-openagent#9727)

### What changed

- `packages/coding-agent/src/brand-dir-migration.ts`: `isSkipped` also skips `desktop` and every `desktop.init-*` entry, so the copy-forward never creates or writes into them in the brand dir.

### Why

The OmO desktop app owns `~/.omo/desktop*` (omo-desktop-app#1829); an engine copy-forward must not create its data home or a half-initialized one.

### Why an extension could not handle it

The copy-forward runs at startup, before any extension loads.

### Expected merge conflict zones

- Fork-only file. `isSkipped`.

## 2026-10-06 - visibleWidth export for extensions that lay out their own rows (senpi#2831)

### What changed

- `packages/coding-agent/src/index.ts`: `visibleWidth` is exported from `@earendil-works/pi-tui` beside `sanitizeTerminalLabel`.

### Why

The eval extension's live row cuts its headline to the terminal width. Counting code points let a wide-character summary (Korean, Chinese, Japanese, emoji) wrap a narrow terminal. Measuring in screen cells needs the TUI's own width function, and extensions reach the TUI only through this package.

### Why an extension could not handle it

Extensions import `@code-yeongyu/senpi`, not `@earendil-works/pi-tui`, and a second copy of the width tables in an extension would drift from the renderer's.

### Expected merge conflict zones

- LOW: the `sanitizeTerminalLabel` export line at the top of `src/index.ts`.

## 2026-10-05 - A single-session rpc process takes its fallback chain over the wire (omo#9582)

### What changed

- `packages/coding-agent/src/main.ts`: `createServices` applies a launch profile's `retryFallback` through the shared `applyRetryFallbackProfile` helper (`core/agent-session-runtime.ts`) instead of an inline `applyOverrides` block, so `open_session` and `set_retry_fallback` apply the policy the same way.

### Why

- omo task children that run as their own `--mode rpc` process (every Windows child) had no way to receive their category's fallback chain, so a usage limit after a tool call ended the child even with `fallback_models` configured. `set_retry_fallback` gives that process the same in-memory policy `open_session.retryFallback` gives a host session; the runtime factory has to apply it identically for later sessions of the process.

### Why an extension could not handle it

- The runtime factory builds each session's `SettingsManager` before any extension loads. An extension cannot reach a later replacement session's settings before its first turn.

### Expected merge conflict zones

- `main.ts`: the `createServices` block directly after `SettingsManager.create(cwd, agentDir, { projectTrusted })`.

## 2026-10-03 - EvalHandleHost capability exports (codemode plan node 10)

### What changed

- `packages/coding-agent/src/index.ts`: re-exports the `EvalHandleHost` capability surface from `core/extensions/eval-handle-host.ts` (`EvalHandleHost`, `HandleRef`, `HandlePhase`, `HandleSnapshot`, `HandleOutcome`, `HandleWatch`, `HandleCallContext`, `HandleError`, `HandleKind`, `CancelReceipt`, `OutputRequest`, `OutputSnapshot`, `EVAL_HANDLE_ERROR_CODES`, `EvalHandleErrorCode`, `EvalHandleError`) beside the kernel-tools context exports.

### Why

- The task owner (an extension) implements the capability and codemode (another extension) consumes it; both import the contract from the package root, never from each other.

### Why an extension could not handle it

- The package root is the only import path published to extensions; an extension cannot add exports to it.

### Expected merge conflict zones

- `index.ts`: the export block directly before the `kernel-tools-context.ts` re-exports.

## 2026-10-03 - A session's own fallback policy reaches its settings in memory only (omo#9512)

### What changed

- `packages/coding-agent/src/main.ts`: `createCliRuntimeFactory` applies a launch profile's `retryFallback` (`open_session.retryFallback`) to that session's own `SettingsManager` through `applyOverrides`, the session-only layer that `save()` never writes.

### Why

- `packages/coding-agent/src/main.ts`: each host session builds its own `SettingsManager`, so the override reaches only that session, and the user's `settings.json` stays byte-identical (`test/suite/rpc-open-session-retry-fallback.test.ts`).

### Why an extension could not handle it

- `packages/coding-agent/src/main.ts`: the settings manager is created before the session's extensions load, and `ctx.sessionSettings` setters persist to the global settings file.

### Expected merge conflict zones

- LOW: the `runtimeSettingsManager` construction in `createCliRuntimeFactory`.

## 2026-10-02 - Memory report trigger at startup (senpi#2561)

### What changed

- `packages/coding-agent/src/main.ts`: calls `installMemoryReportSignal()` before the multi-session branch and the mode dispatch, so TUI, print, RPC and multi-session hosts all install the `SIGUSR2` memory report when `SENPI_MEMORY_REPORT=1`; without the flag it installs nothing.

### Why

- The on-demand memory report must be reachable from every mode of a running session process.

### Why an extension could not handle it

- Extensions load per session, after mode selection; a multi-session host has none until a session opens, and the signal handler is process-wide.

### Expected merge conflict zones

- `main.ts`: the line before `if (appMode === "rpc" && parsed.multiSession)` and the import block.

## 2026-10-01 - Package directory lookup is resolved once (senpi#2508)

### What changed

- `packages/coding-agent/src/config.ts`: `getPackageDir()` resolves the source/dist package root once per process instead of walking parent directories with `existsSync` on every call.

### Why

Read-card classification calls `getReadmePath()`; the walk ran for every read card on every frame.

### Why an extension could not handle it

Core path resolution.

### Expected merge conflict zones

- `packages/coding-agent/src/config.ts`: `getPackageDir`.

## 2026-10-01 - Experimental picker preserves optional command arguments (senpi#2479)

### What changed

- `packages/coding-agent/src/experimental/services/slash-commands.ts`: command contributions expose `requiresArguments`.
- `packages/coding-agent/src/experimental/services/slash-commands-provider.ts`: model, thinking and compact explicitly allow bare invocation.
- `packages/coding-agent/src/experimental/client-tui.ts`: forward the explicit requirement to the shared autocomplete provider.

### Why

The experimental client uses the same picker as the classic TUI; optional selectors and compaction must submit on first Enter there too.

### Why an extension could not handle it

The service contract and client mapping own the metadata before dispatch.

### Expected merge conflict zones

- `packages/coding-agent/src/experimental/services/slash-commands.ts`: command contribution interface.
- `packages/coding-agent/src/experimental/services/slash-commands-provider.ts`: builtin command metadata.
- `packages/coding-agent/src/experimental/client-tui.ts`: updateAutocomplete mapping.

## 2026-10-01 - GPT-6 Astra high-reasoning warning shows above high again (senpi#2496)

### What changed

- `packages/coding-agent/src/core/high-reasoning-warning.ts`: GPT-6 Astra warns at `xhigh` and `max` again, like every other sensitive model, and stays quiet at `high` and below. This reverses the 2026-09-10 "Restrict GPT-6 Astra high-reasoning warning to max" entry below. The full record, with tests, is the 2026-10-01 entry in `src/core/changes.md`.

### Why

- The owner wants the Astra warning shown for any effort above high.

### Why an extension could not handle it

- The warning predicate is core session policy evaluated before the warning event is emitted.

### Expected merge conflict zones

- `packages/coding-agent/src/core/high-reasoning-warning.ts`: fork-only file.

## 2026-10-01 - Export the bundled-bun PATH helper for eval kernels (omo#9362)

### What changed

- `packages/coding-agent/src/index.ts`: exports `withBundledBunCommands` from `utils/bundled-bun.ts`, next to the shell utilities.

### Why

- The eval extension (`senpi-codemode`) gives its kernels the same `bun`/`bunx` directory that `getShellEnv()` puts on the bash tool's `PATH`, so a cell's `bun test` in a compiled executable runs Bun instead of the engine. The extension reaches it only through the package's public exports.

### Why an extension could not handle it

- The helper lives in the core package; an extension can only import what `index.ts` exports.

### Expected merge conflict zones

- LOW: the shell-utilities export block in `index.ts`.
## 2026-09-30 - Legacy tool warnings require a legacy tool entry point (senpi#2451)

### What changed

- `packages/coding-agent/src/extension-system-migration.ts`: project and global `tools/` warnings now require the legacy `tools/<name>/index.ts` layout instead of treating every non-binary entry as a custom tool.
- `packages/coding-agent/test/extension-system-migration.test.ts`: the OmO-branded migration covers both a plain helper file and a legacy custom tool directory.

### Why

- OmO keeps its own helper files and artifacts in `.omo/tools`; those files were never legacy custom tools, but their presence triggered the migration warning.

### Why an extension could not handle it

- The warning is produced by the startup migration before extensions load.

### Expected merge conflict zones

- LOW: the custom-tool filter in `extension-system-migration.ts`.

## 2026-09-30 - Host sessions apply the permission preset their client opened them with (#2461)

### What changed

- `packages/coding-agent/src/main.ts`: `createCliRuntimeFactory`'s `createServices` passes `sessionExtensionFlagValues(parsed.unknownFlags, launchProfile)` as the session's extension flag values instead of the host's own flags alone.
- `packages/coding-agent/src/core/session-extension-flags.ts` (fork-only): copies the host flags and sets `permission-preset` from `launchProfile.permissionPreset` when the client sent one.

### Why

- `open_session.permissionPreset` was stored in the launch profile and never read, so every host-opened session ran with the host's startup preset (normally `full-access`). The builtin permission extension reads its preset from the `--permission-preset` flag, so the per-session value has to reach it through that flag. Settings still apply below it, as for a CLI preset.

### Why an extension could not handle it

- Extension flag values are fixed when the session's services are created; an extension cannot see the launch profile.

### Expected merge conflict zones

- LOW: the `extensionFlagValues` argument of `createAgentSessionServices` in `main.ts` (one line) and the import block.

## 2026-09-30 - Sync with upstream v0.99.1 (6a4af07d6): experimental micro default model uses the fork provider id

### What changed

- `packages/coding-agent/src/experimental/micro/runtime.ts`: the upstream-new micro runtime's `DEFAULT_MODEL` names the provider `chatgpt-subscription` instead of the upstream `openai-codex`; its README says the same.

### Why

The fork renamed the ChatGPT subscription provider to `chatgpt-subscription` (sync decision D-4; `openai-codex` survives only as the legacy alias in `legacy-provider-ids.ts`), and `test/suite/anthropic-subscription-naming.test.ts` rejects any shipped string literal carrying the legacy id. The upstream file arrived with the old id, so a new micro session looked up a provider name the fork no longer ships.

### Why an extension could not handle it

The default is a module constant the experimental micro entry reads before any extension loads.

### Expected merge conflict zones

- LOW: the `DEFAULT_MODEL` line in `experimental/micro/runtime.ts` whenever upstream changes the micro default model; keep the `chatgpt-subscription` provider id.

## 2026-09-30 - Sync with upstream v0.99.1 (6a4af07d6): paths divergent from the new pin

### What changed

- `packages/coding-agent/src/experimental/radius-auth.ts`: kept the fork version. It defines `ENV_RADIUS_GATEWAY` itself and defaults the gateway from that variable or `DEFAULT_RADIUS_GATEWAY` (`@earendil-works/pi-ai/providers/radius-config`); the pinned upstream file imports both from `../core/radius.ts`.

### Why

The fork deleted `packages/coding-agent/src/core/radius.ts` (the Radius share/upload service is not used; sync decision D-6 keeps it deleted), so the relay auth resolver cannot import from it. The gateway resolution is the same: environment variable first, then the default gateway.

### Why an extension could not handle it

The experimental relay client imports this module directly at startup; there is no extension hook in front of it.

### Expected merge conflict zones

- MEDIUM: the import block and the `RadiusRelayAuthResolver` constructor default whenever upstream changes `core/radius.ts` exports; keep the local `ENV_RADIUS_GATEWAY` and the `DEFAULT_RADIUS_GATEWAY` fallback.

## 2026-09-30 - Sync with upstream v0.99.1 (6a4af07d6): settings, entrypoints and resource loading

### What changed

- `packages/coding-agent/src/bun/runtime-setup.ts`: `packages/coding-agent/src/bun/runtime-setup.ts`: = OURS (`registerBunRuntimeModules`); upstream QuickJS wasm embedding not adopted (only the excluded upstream codemode reads it). No compile-cache work on the Bun path (fork compile cache stays in the Node entry).
- `packages/coding-agent/src/config.ts`: `packages/coding-agent/src/config.ts`: = OURS (upstream `setEmbeddedQuickJSWasmPath`/`getQuickJSWasmPath`/`getCodemodeWorkerUrl` are codemode-only, D-2).
- `packages/coding-agent/src/experimental/client.ts`: `packages/coding-agent/src/experimental/client.ts`: = OURS (the fork already waits for the run's terminal event, bounded by `RUN_TAIL_TIMEOUT_MS`; upstream's unbounded duplicate waiter dropped).
- `packages/coding-agent/src/index.ts`: `packages/coding-agent/src/index.ts`: fork export superset kept (`OAuthCredential`, `McpServerDeclaration`, `ToolPermissionRequest`, `UnknownCommandError`, `connectWebViewService`, `export *` session-control types); adopted upstream `ToolLoadout`, `ToolLoadoutChanges`, `ToolNamespace`, boundary/virtual-model/session-projection/theme type exports and `core/virtual-models.ts` exports (C-EX-10). Dropped: `CacheWarmingDecision/Status`, `CacheWarmingDecisionEvent(Result)`, `CacheWarmingMode` (D-5), `McpServersChangeEvent`, `RegisteredMcpServer`, upstream codemode/mcp/tool-search extension exports (D-2). Upstream core/index.ts additions (all types) are re-exported from here; core/index.ts is not resurrected.
- `packages/coding-agent/src/main.ts`: `packages/coding-agent/src/main.ts`: = OURS + extension-package warnings mapped into runtime diagnostics in `createCliRuntimeFactory`. No `/bug`, no crash-report hints, no upstream `mcp` subcommand (D-2/D-6); fork startup paths kept (loading indicator, from-source guard, legacy .pi notice, app-server/host/schedule dispatch, moved-session loaders, index-backed exact-id lookup, CLI-side image resize, initialTitlePrompt).
- `packages/coding-agent/src/experimental/process.ts`: Silent rows read and accepted as merged: `cli/startup-ui.ts` (system theme startup, D-14), `core/keybindings.ts` (descriptions), `core/prompt-templates.ts` (diagnostics result), `core/trust-manager.ts` (adds `mcp.json`; the fork MCP reads project `.senpi/mcp.json`; the `.pi` legacy-trust fix is untouched), `experimental/process.ts` (`--import` URL), `package-manager-cli.ts` (builtin names into config), tests `args`, `package-manager`, `stdout-cleanliness`, `5943-session-start-notify`.
- `packages/coding-agent/src/package-manager-cli.ts`: Silent rows read and accepted as merged: `cli/startup-ui.ts` (system theme startup, D-14), `core/keybindings.ts` (descriptions), `core/prompt-templates.ts` (diagnostics result), `core/trust-manager.ts` (adds `mcp.json`; the fork MCP reads project `.senpi/mcp.json`; the `.pi` legacy-trust fix is untouched), `experimental/process.ts` (`--import` URL), `package-manager-cli.ts` (builtin names into config), tests `args`, `package-manager`, `stdout-cleanliness`, `5943-session-start-notify`.

### Why

Upstream v0.99.1 settings/resource-loading features are adopted where they carry no excluded subsystem; D-2/D-5/D-6 exclusions remove codemode, MCP, tool-search, cache-warming and /bug surfaces; fork runtime contracts (tool defaults, loader ordering, global-default shims, session profiles) win on conflict.

### Why an extension could not handle it

Settings layering, resource/extension resolution, the package barrel and CLI entrypoints are core loader/bootstrap code that runs before any extension loads.

### Expected merge conflict zones

`settings-manager.ts` Settings interface + deepMergeSettings + getDefaultTools; `resource-loader.ts` constructor, loadCurrentExtensionSet, loadExtensionPaths, loadFinalExtensionSet; `index.ts` extension type export block; `main.ts` createCliRuntimeFactory diagnostics; upstream re-adding cacheWarming/codemode/mcp settings or exports.

## 2026-09-30 - Sync with upstream v0.99.1 (6a4af07d6): upstream features excluded on record

### What changed

Upstream paths below are not added (or stay deleted) in this sync; `.github/agent/upstream-exclusions.txt` lists them for mechanical re-exclusion after every upstream merge.

- `packages/coding-agent/src/extensions/codemode/execute.lazy.ts` (not added / kept deleted)
- `packages/coding-agent/src/extensions/codemode/execute.ts` (not added / kept deleted)
- `packages/coding-agent/src/extensions/codemode/index.ts` (not added / kept deleted)
- `packages/coding-agent/src/extensions/codemode/renderer.ts` (not added / kept deleted)
- `packages/coding-agent/src/extensions/codemode/tool.ts` (not added / kept deleted)
- `packages/coding-agent/src/extensions/codemode/worker.ts` (not added / kept deleted)
- `packages/coding-agent/src/extensions/mcp/cli.lazy.ts` (not added / kept deleted)
- `packages/coding-agent/src/extensions/mcp/cli.ts` (not added / kept deleted)
- `packages/coding-agent/src/extensions/mcp/config.ts` (not added / kept deleted)
- `packages/coding-agent/src/extensions/mcp/index.ts` (not added / kept deleted)
- `packages/coding-agent/src/extensions/mcp/log.ts` (not added / kept deleted)
- `packages/coding-agent/src/extensions/mcp/oauth.ts` (not added / kept deleted)
- `packages/coding-agent/src/extensions/mcp/resources.ts` (not added / kept deleted)
- `packages/coding-agent/src/extensions/mcp/runtime.lazy.ts` (not added / kept deleted)
- `packages/coding-agent/src/extensions/mcp/runtime.ts` (not added / kept deleted)
- `packages/coding-agent/src/extensions/mcp/tools.ts` (not added / kept deleted)
- `packages/coding-agent/src/extensions/mcp/ui.ts` (not added / kept deleted)
- `packages/coding-agent/src/extensions/tool-search/index.ts` (not added / kept deleted)
- `packages/coding-agent/src/extensions/tool-search/tool.ts` (not added / kept deleted)
- `packages/coding-agent/src/extensions/index.ts`: upstream's built-in list reduced to its llama.cpp entry; the codemode, tool-search and MCP entries are excluded with their directories.

### Why

The fork keeps one implementation per capability: its own builtin mcp, tool-search and senpi-codemode instead of upstream's codemode/MCP/tool-search built-ins and packages (plan D-2, owner default Q1); builtin cache-keepalive instead of upstream cache warming, whose default spends paid refreshes (D-5, Q3); report-bug skills instead of `/bug` uploads to Radius (D-6, Q4); no `packages/durable`, which nothing in the fork imports (D-7). Paths the fork had already deleted (core/index.ts, core/radius.ts, session-share.ts, tui latex.ts, providers/openai-codex.ts, npm-shrinkwrap.json) stay deleted.

### Why an extension could not handle it

Exclusion is a repository-level decision about which upstream files exist at all; an extension can add behavior but cannot remove files an upstream merge adds.

### Expected merge conflict zones

Every upstream release that touches these paths re-adds or modifies them: re-run `git rm -rqf --ignore-unmatch $(cat .github/agent/upstream-exclusions.txt)` after the merge and extend the list (with a dated block here) when upstream adds a new file to an excluded feature.
## 2026-09-30 - Print mode selects its answer after deferred turns settle (#1431)

### What changed

- `packages/coding-agent/src/modes/print-mode.ts`: await the existing session-work settlement before selecting the final assistant answer and exit status.

### Why

- An extension command can start a deferred turn and return before its provider response arrives. Text mode previously selected its answer before waiting, so the command produced empty or stale output even though the deferred turn completed before process exit. This extracts the remaining print-output slice of #1431; ordinary prompt settlement and JSON event streaming retain their existing behavior.

### Why an extension could not handle it

- The final stdout selection and exit status belong to the core print-mode runner, after extension commands return.

### Expected merge conflict zones

- LOW: the settlement call immediately before final text selection in `packages/coding-agent/src/modes/print-mode.ts`.

## 2026-09-30 - Print, JSON, and RPC runs warn once about a clamped explicit thinking level (senpi#2395)

### What changed

- `packages/coding-agent/src/main.ts`: after runtime creation, non-interactive modes report `session.startupThinkingClamp` as one stderr warning. The CLI thinking re-apply passes the requested level from a clamped selection, so it keeps the clamp record instead of replacing it with the applied level.

### Why

- `--thinking high` on a model not marked `reasoning: true` silently ran with thinking off (senpi#2395). Spawned RPC children are one common way this level is set.

### Why an extension could not handle it

- The warning belongs to CLI startup before extensions see the session, and the re-apply is part of `main.ts` session creation.

### Expected merge conflict zones

- `main.ts`: the `cliThinkingOverride` re-apply in the session factory and the diagnostics block after `reportDiagnostics(runtime.diagnostics)`.

## 2026-09-30 - A runtime snapshot holds its own dependencies, and shared hosts run from it (#2408, #2409)

### What changed

- `packages/coding-agent/src/cli.ts`: the bundled launch awaits `prepareRuntimeSnapshot()`, which is async now because the snapshot's files are copied with a bounded number of copies in flight.
- `packages/coding-agent/src/runtime-snapshot/` (fork-only): `layout.ts` copies the whole package (except `node_modules`) and every package the install's dependency graph reaches into the snapshot instead of linking back to the install. Each name goes where the package itself resolves it (nested or hoisted); a package that resolves another copy of a name gets that copy nested under itself. Type declarations and source maps are left out. `file-copier.ts` (new) copies each file as a copy-on-write clone, then a hardlink where the filesystem cannot clone, then a plain copy, eight at a time. `registry.ts` gains `withBuildLock()`: one builder per snapshot, a dead builder's lock and staging directories are taken over, and launches of snapshots that already exist never wait on a build. `enter.ts` claims an existing snapshot under the runtime lock, and builds a missing one under the build lock before claiming it.

### Why

- An update that changes the package layout (`bundledDependencies` on or off) deletes the directories the snapshot's links named, so a running session's PTY tools and `eval` failed with `ENOENT` (#2408). Measured on the published releases: 223 of 232 links dangled after 2026.9.29-3 was replaced by 2026.9.29-4.
- A clone never shares the install's file, so an in-place rewrite of the install cannot reach the snapshot; a hardlink does share it and is only taken where no clone is possible (package managers replace files rather than rewriting them).
- Cost, measured on macOS with the 2026.9.29-4 dependency closure (14.4k files, 382 MiB logical, all clones): the first launch after an update builds the snapshot once; later launches are unchanged.

### Why an extension could not handle it

- The snapshot is built by the CLI entry before the engine graph loads.

### Expected merge conflict zones

- LOW: the `prepareRuntimeSnapshot` call in `cli.ts` (one added `await`).

## 2026-09-29 - Carry model tier decorators into session startup (senpi#2399)

### What changed

- `packages/coding-agent/src/main.ts`: retain the service tier from --model and --models through buildSessionOptions and the CLI runtime factory.

### Why

- `packages/coding-agent/src/main.ts`: the real CLI discarded the parsed tier even though model resolution preserved it, so an Astra Ultrafast command silently ran without that tier.

### Why an extension could not handle it

- `packages/coding-agent/src/main.ts`: this host startup boundary discarded the selection before extension contexts were created.

### Expected merge conflict zones

- `packages/coding-agent/src/main.ts`: initial session options and construction/forwarding calls.

## 2026-09-29 - The CLI runtime factory passes the launch profile's prompt surface (senpi#2377)

### What changed

- `packages/coding-agent/src/main.ts`: `createCliRuntimeFactory`'s `createRuntime` passes `promptSurface: launchProfile?.promptSurface` to `createAgentSessionFromServices`.

### Why

- `open_session.promptSurface` reaches the session through the launch profile, the same path `kind`, `context` and `auto_title` take.

### Why an extension could not handle it

- The runtime factory builds the session before extensions bind.

### Expected merge conflict zones

- LOW: the `createAgentSessionFromServices` call in `createRuntime`.

## 2026-09-29 - Print mode names why a fallback returned early (senpi#2376)

### What changed

- `packages/coding-agent/src/modes/print-mode.ts`: the `Model fallback reverted` stderr line appends `(<from> cannot serve right now)` when `retry_fallback_reverted` carries `cause: "fallback-unusable"`.

### Why

- The session now returns from a billing-dead fallback before the original's cooldown lapses; the line must not read like an ordinary cooldown revert.

### Why an extension could not handle it

- Print mode's event-to-stderr writer is core output, not an extension surface.

### Expected merge conflict zones

- LOW: the `retry_fallback_reverted` branch in `packages/coding-agent/src/modes/print-mode.ts`.

## 2026-09-29 - A running session keeps its own build when the install is replaced (#2358)

### What changed

- `packages/coding-agent/src/cli.ts`: after the `--version`, help and bootstrap-repair paths, a bundled launch calls `prepareRuntimeSnapshot()` (`src/runtime-snapshot/`, new) and, on a hand-off, imports the snapshot's own `dist/bundle/cli.js` instead of `./cli-main`. That copy of `cli.ts` sees it already runs from a snapshot, claims it and imports its own `cli-main`. The bootstrap-repair check reads `getInstallPackageDir()`.
- `packages/coding-agent/src/config.ts`: new `getInstallPackageDir()`, which equals `getPackageDir()` except inside a runtime snapshot, where it returns the install the snapshot was taken from (`runtime-snapshot.json`). `detectInstallMethod()` classifies the install path mapped through `resolveInstallPath(__dirname, ...)`, and `getInferredNpmInstall`, both pnpm global-root regexes, `isSelfUpdatePathWritable` and `isManagedByGlobalPackageManager` read `getInstallPackageDir()`.
- `packages/coding-agent/src/main.ts` and `packages/coding-agent/src/package-manager-cli.ts`: the Windows self-update quarantine cleanup and the managed-install release check read `getInstallPackageDir()`.
- `packages/coding-agent/src/runtime-snapshot/` (new, fork-only): `enter.ts` decides the hand-off, `layout.ts` builds `<agentDir>/runtime/<buildId>-<installHash>/` (copies `dist/bundle` and `package.json`, links every other package and `dist` entry, and builds a `node_modules` that is the union of the install's resolution path, so nested and hoisted dependencies resolve to the install's own copies, verified against the manifest's externals), `registry.ts` owns the directory lock, per-pid claims and pruning (a snapshot with no live claim and no use for 10 minutes is removed), and `marker.ts` reads the marker.

### Why

- `bun install -g` and `npm i -g` delete and rewrite the package directory. A session started before that died at its next lazy chunk import (`Cannot find module './anthropic-messages-<hash>.js'`, or `ENOENT reading` under Bun), and every later request failed the same way until restart (#2358). Bun rewrites every global package on any `bun install -g`, so each omo update hit every open session. Preloading the lazy chunks instead measured +53 to +66 MB RSS and 114 to 566 ms per process and still missed the 16 name-stable lazy files, workers and disk assets. The snapshot costs a one-time 32 to 144 ms copy of 158 files per build and about nothing per launch.
- Any snapshot failure (read-only agent dir, unknown layout, lock busy for 5 s) runs in place, exactly as before: the snapshot only adds upgrade resilience and must never be why startup fails.

### Why an extension could not handle it

- The decision has to happen in the entry before the engine graph loads, and install-method detection is core config.

### Expected merge conflict zones

- MEDIUM: the final `cli-main` import in `cli.ts`; LOW: `getPackageDir()` call sites in `config.ts` near `detectInstallMethod`, `getInferredNpmInstall`, the pnpm global-root regexes and the self-update checks; the Windows quarantine call in `main.ts`; `getActiveManagedInstallRoot` and `prepareWindowsNpmSelfUpdate` in `package-manager-cli.ts`.

## 2026-09-29 - The session control types are public (session gateway)

### What changed

- `packages/coding-agent/src/index.ts`: `export * from "./core/extensions/session-control-types.ts"` - `SessionControlActions`, `RegisterControlEndpointOptions`, `SessionControlRegistration`, `SessionControlWakeEvent`, the admission input/result/gate/ledger types and `SESSION_CONTROL_DELIVERY_TYPE`. See `src/core/extensions/changes.md` (2026-09-29).

### Why

- omo's thread component registers the endpoint and drains its inbox through `pi.session`, typed from the package root.

### Why an extension could not handle it

- Package exports are the package's own surface.

### Expected merge conflict zones

- LOW: the line after the `./core/extensions/index.ts` export block in `src/index.ts`.

## 2026-09-29 - The endpoint registry helpers are public (session gateway)

### What changed

- `packages/coding-agent/src/modes/index.ts` and `packages/coding-agent/src/index.ts`: export `classifyEndpointLiveness`, `EndpointLiveness`, `endpointProbeTimeoutMs`, `TUI_PROBE_TIMEOUT_MS`, `ENDPOINT_REGISTRY_VERSION`, `EndpointKind`, `listHostEndpoints`, `HostEndpointEntry`, `HostEndpointIdentitySource`, `gcHostEndpoints`, `HostGcOptions`, `HostGcResult`, `readAllHostStatus` and `HostEndpointStatus`. See `src/modes/rpc/changes.md` (2026-09-29).

### Why

- omo and the Desktop read the one endpoint registry (`endpoint_kind`, liveness verdict, `tui`-only gc) through the library as well as through `senpi host status --all`.

### Why an extension could not handle it

- Package exports are the package's own surface.

### Expected merge conflict zones

- LOW: the `./modes/index.ts` export block in `src/index.ts` and the rpc export block in `src/modes/index.ts`.

## 2026-09-29 - Edits made in ~/.pi/agent after its copy are reported and importable (omo#9173)

### What changed

- `packages/coding-agent/src/migrations-state.ts`: the state file keeps fields it does not own on every write, and carries `legacyPiAgentDir: { copiedAt, noticedMtimes }` through `readLegacyPiAgentDirRecord`, `writeLegacyPiAgentDirRecord` and `recordLegacyPiAgentDirCopy`. Schema version stays 1; older readers ignore the new field.
- `packages/coding-agent/src/legacy-senpi-dir-migration.ts`: copying the global `~/.pi/agent` records the copy time and prints where config lives from now on instead of the generic "original directory is untouched" line.
- `packages/coding-agent/src/pi-dir-restore.ts`: `restoreDir` reports whether it copied anything, and a restored `~/.pi/agent` records the copy time too.
- `packages/coding-agent/src/legacy-pi-edits.ts` (new): finds `auth.json`, `keybindings.json`, `models.json` and `settings.json` in `~/.pi/agent` changed after the copy (a copy made before the time was recorded compares against the agent copy's preserved mtime) whose content differs from the agent dir's copy; `takeLegacyPiEditNotice` returns only changes not reported yet and records their mtimes; `importLegacyPiConfig` copies named or all edited files into the agent dir after a `.bak-<time>` backup. `~/.pi/agent` is only ever read.
- `packages/coding-agent/src/main.ts`: interactive startup passes `legacyPiEditStartupNotice()` to `InteractiveMode` as `legacyPiEditNotice`.
- `packages/coding-agent/src/package-manager-cli.ts`: `config import-pi [files]` routes to `runConfigImportPi` (`src/cli/config-import-pi.ts`, new), and `config --help` documents it.

### Why

- After the one-time copy (#8039) both directories hold plausible config, and edits to `~/.pi/agent` silently had no effect (omo#9173). `~/.pi/agent` belongs to upstream pi, so nothing may be written there; the product says what it reads instead.

### Why an extension could not handle it

- The copy, its state file and the startup options all run before any extension loads, and `config` is a CLI route.

### Expected merge conflict zones

- LOW: the `InteractiveMode` options object in `main.ts`; the top of `handleConfigCommand` and `printConfigCommandHelp` in `package-manager-cli.ts`.

## 2026-09-29 - Interactive launches never join a shared RPC host (senpi#2328)

### What changed

- `packages/coding-agent/src/main.ts`: the interactive runtime is always the local `createAgentSessionRuntime` result. Removed: the `shouldJoinSharedHost` decision, the `experimental.sharedHost` setting and brand-prefixed `ENABLE_SHARED_HOST` opt-in, the obsolete `DISABLE_SHARED_HOST` stderr notice, the dynamic import of `createInteractiveHostRuntime` and the `selectedRuntime` swap, and the `sharedHostEnabled` value the runtime factory passed in `resourceLoaderOptions`. The env names are no longer read anywhere and print nothing. This supersedes the 2026-09-09 "Forward shared-host policy to extension loading" entry below and every earlier entry that routed an interactive launch through the shared host.

### Why

- One host event loop serving every interactive session let one session's work stall all the others (senpi#2328). An interactive session is isolated by running in its own process; the multi-session RPC host keeps serving its own clients.

### Why an extension could not handle it

- Runtime selection happens in `main()` before any extension loads.

### Expected merge conflict zones

- LOW: the `resourceLoaderOptions` literal in `createCliRuntimeFactory` and the lines between `createAgentSessionRuntime` and the `services` destructuring in `main()`.

## 2026-09-29 - Print mode names the usage limit behind a model fallback (omo#8296)

### What changed

- `packages/coding-agent/src/modes/print-mode.ts`: the stderr line for `retry_fallback_applied` prints `usageLimitCause(from, limit)` in place of the bare reason when a usage limit caused the switch, e.g. `Model fallback: a/x -> b/y (a/x hit its usage limit)`. Other switches print the reason as before.

### Why

- Headless runs and task children log this line; "(transient)" hid that the model had run out of its usage limit (omo#8296).

### Why an extension could not handle it

- The line is written by print mode's own session subscription.

### Expected merge conflict zones

- LOW: the `retry_fallback_applied` branch in `print-mode.ts`.

## 2026-09-28 - `createCliRuntimeFactory` can build a session's services alone (senpi#2314)

### What changed

- `packages/coding-agent/src/main.ts`: the services half of `createCliRuntimeFactory` (project trust, settings, resource loader with the launch profile's kind and context, extension factories) is a `createServices` closure the runtime factory calls first. The returned factory also carries `prepare(options)`, which builds those services for a host open (no start event) and drops them. The return type is `PreparableRuntimeFactory`.

### Why

A multi-session host's `warm` command (senpi#2314) must load exactly what the next `open_session` loads - the same resource paths, trust decision and extension factories - without creating an `AgentSession` or firing `session_start`. Only the factory knows those inputs, so it builds them for both paths.

### Why an extension could not handle it

Extensions are what gets loaded; the loading itself is the CLI runtime factory's.

### Expected merge conflict zones

- The body of `createCliRuntimeFactory` between its setup and `createAgentSessionFromServices`, and its return.

## 2026-09-27 - `senpi schedule` route for durable scheduled prompts

### What changed

- `packages/coding-agent/src/main.ts`: `dispatchScheduleCommand(args)` runs beside the `host` route, BEFORE `parseArgs`, and exits with the code it returns, so `senpi schedule list|cancel|run` never falls through into argument parsing or a session. The implementation is `src/cli/schedule-command.ts` behind an `await import(...)` in `src/cli/deferred-commands.ts`.

### Why

- A prompt scheduled by the `schedule_prompt` tool (builtin `schedule`) must fire after the scheduling process exits, which a `--print` run always does. The firing half therefore runs as its own long-lived or cron-driven process, and that process is a CLI command.

### Why an extension could not handle it

- Command routing and process exit codes run before any extension is loaded, and an extension only lives as long as the session process that loaded it.

### Expected merge conflict zones

- LOW: one import name and one dispatch branch next to the `host` dispatch in `main.ts`.

## 2026-09-28 - Single-session modes arm the child reaper; orphaned-child collection is exported (senpi#1962)

### What changed

- `packages/coding-agent/src/main.ts`: interactive, print, JSON and single-session RPC modes start `startHostChildReaper` (the multi-session host already did) before the mode runs; interactive mode passes a silent log sink because the TUI owns stderr, print mode stops it before returning.
- `packages/coding-agent/src/index.ts`: exports `collectOrphanedChildren` from `src/modes/rpc/child-reaper.ts`.

### Why

- Every mode hosts the eval kernel, and a terminated worker thread takes its children's exit watchers with it; outside the multi-session host nothing ever collected them, so interactive sessions accumulated zombies for days (#1962).

### Why an extension could not handle it

- Arming a process-wide reaper and exporting the collector belong to the host process entry point and the package's public surface.

### Expected merge conflict zones

- LOW: the mode dispatch at the end of `main()` in `main.ts`; the export list in `index.ts`.

## 2026-09-28 - The process footprint reader is exported (senpi#2261)

### What changed

- `packages/coding-agent/src/index.ts`: exports `readOwnFootprint`, `readProcessFootprint` and the `ProcessFootprint` / `ProcessFootprintMeasure` types from the fork-only `src/core/process-footprint.ts`, which reads a process's memory footprint from the kernel (`phys_footprint` / `RssAnon` / `PrivateUsage`, RSS as the labelled fallback) synchronously, without spawning anything and without throwing.

### Why

- RSS stays high after memory is returned, so it cannot tell whether the host or an eval kernel still holds memory (senpi#2261). The RPC host sampler uses the reader, and exporting it lets `senpi-codemode` measure its kernel processes through `@code-yeongyu/senpi`.

### Why an extension could not handle it

- `src/index.ts` is the package's public surface; extensions cannot add exports to it.

### Expected merge conflict zones

- `packages/coding-agent/src/index.ts`: the export block after `./core/package-manager.ts`.

## 2026-09-28 - A main-thread Bun.WebView service is exported for eval kernels (senpi#2248)

### What changed

- `packages/coding-agent/src/index.ts`: exports `connectWebViewService` and the `WebViewServiceConnection` type from the fork-only `src/core/webview/webview-broker.ts`.
- Fork-only `src/core/webview/`: `WebViewService` serves Chrome-backed `Bun.WebView`s on the process main thread to eval kernels in worker threads. Each kernel gets its own client (a private `MessagePort` and the views created through it); only the owner that connected a client can release it, a closed port releases it too, and Bun's Chrome is retired once no proxied view is left (`closeAll()` off macOS, a kill of Bun's own Chrome child on macOS, where `closeAll()` would also kill the shared WebKit host of native worker views).
- Fork-only `src/core/webview/webview-readiness.ts` (senpi#2353): the service answers a `create` only after the new view's readiness navigation to `about:blank` settled. A launch still pending at the bound (`cdp-target-attach`) is closed, its Chrome retired unless another view holds it, and relaunched once (not for a released client) before the create fails with `ERR_WEBVIEW_NOT_READY`.

### Why

- Bun constructs the `"chrome"` WebView backend only on the main thread, so `new Bun.WebView()` failed in every eval cell on Windows and Linux (Chrome is their default backend) and in every macOS cell that asked for `backend: "chrome"`.

### Why an extension could not handle it

- In RPC worker hosts the codemode extension itself runs in a session worker; only the process that owns the main thread can serve the views, and `src/index.ts` is the package's public surface.

### Expected merge conflict zones

- `packages/coding-agent/src/index.ts`: the trailing utility export block (after the shell utilities).

## 2026-09-28 - The shard naming helpers are exported from the package entry

### What changed

- `packages/coding-agent/src/modes/index.ts`: re-exports `shardKey`, `shardSocketPath`, `shardSocketPathForKey`, `daemonDirectoryName` and the `ShardKind` type from `modes/rpc/host-daemon-paths.ts`.
- `packages/coding-agent/src/index.ts`: adds the same names to the run-mode export list, so `import { shardKey } from "@code-yeongyu/senpi"` resolves.
- Tests: `test/rpc-host-shard-naming.test.ts` checks that the package entry exports the same functions and that they produce the fixed vectors.

### Why

omo imports senpi only through the package root (its `senpi-barrel.ts` resolves host symbols there, and `package.json` `exports` exposes no deeper path), so a helper exported only from `host-daemon-paths.ts` is unreachable to it and its shard naming would have to go through the `senpi host shard-path` CLI (senpi#2245 review M2).

### Why an extension could not handle it

`src/index.ts` is the package's public surface; extensions cannot add exports to it.

### Expected merge conflict zones

- `packages/coding-agent/src/index.ts`: the run-mode export list from `./modes/index.ts`.
- `packages/coding-agent/src/modes/index.ts`: the export block above the host-decision exports.

## 2026-09-28 - Export UnknownCommandError (omo #9042)

### What changed

- `packages/coding-agent/src/index.ts` exports `UnknownCommandError` and `UnknownCommandReason` from `./core/unknown-command.ts`.

### Why

- SDK callers of `AgentSession.prompt()` need to recognize the typed refusal of unknown commands.

### Why an extension could not handle it

- The package entry point is the only public export surface.

### Expected merge conflict zones

- `packages/coding-agent/src/index.ts`: the line after the `./core/trust-manager.ts` export.

## 2026-09-27 - `senpi models discover <provider>` dispatch (senpi#2196)

### What changed

- `packages/coding-agent/src/main.ts`: `models discover ...` is routed to the fork-only `src/cli/models-command.ts` right after the auth commands and exits with its code. Any other `models` argument is still a prompt.

### Why

- Custom OpenAI-compatible providers had no model discovery; the command fetches `/models` once and records the listed models, with the reasoning efforts the endpoint advertises, in models.json (prior art: gajae-code #5979).

### Why an extension could not handle it

- Top-level subcommands are dispatched in `main()` before settings, extensions, or a session exist, like `auth`.

### Expected merge conflict zones

- `packages/coding-agent/src/main.ts`: the import block (`./cli/list-models.ts`) and the dispatch after `runAuthCommand`.

## 2026-09-27 - Branded starts copy an upstream pi install instead of moving it, and restore one they drained (oh-my-openagent#8039)

### What changed

- `packages/coding-agent/src/migrations.ts`: `runMigrations()` runs the new one-time scan migration `restoreDrainedPiDirs` (`src/pi-dir-restore.ts`) before `migrateLegacySenpiDirs`, passing the completed set it already read. When `~/.pi` exists, its `agent` (or `mom`) directory holds no user state (missing, empty, or only the `{}` `auth.json`/`models-store.json` stubs pi writes itself), the agent dir lives under `~/<configDir>` (compared by canonical path), and the migrations state records the old moving `migrateLegacySenpiDirs` (or a pre-state-file build left engine state), it copies the upstream pi entries (`auth.json`, `settings.json`, `models.json`, `sessions/`, `extensions/`, `skills/`, ...) back into `~/.pi/agent` and `~/<configDir>/mom` into `~/.pi/mom`. Real files are never overwritten; a `{}` stub is replaced only when the agent dir has that entry. `SCAN_MIGRATIONS` (`src/migrations-state.ts`) gains its name, so it runs once per agent dir; the schema version is unchanged so the move-era record stays readable as evidence.
- `migrateLegacySenpiDirs` (`src/legacy-senpi-dir-migration.ts`, fork-only) now copies the official `~/.pi/agent`, `~/.pi/mom` and `<cwd>/.pi` (missing top-level entries only, modes and timestamps kept, copy-on-write where supported, `src/legacy-dir-copy.ts`) and keeps the move only for `.pi` leftovers nested inside the fork's own config dir.

### Why

- The first start of a branded engine (omo: `~/.omo/agent`) renamed a real upstream pi install into its own directory, leaving pi empty (oh-my-openagent#8039, #8370). `brand-dir-migration.ts` already copies `~/.senpi` for exactly this reason. Users already drained get their pi state back on the next start.

### Why an extension could not handle it

- Migrations run in `runMigrations()` before any extension loads, and the damage happens there.

### Expected merge conflict zones

- `packages/coding-agent/src/migrations.ts`: the three lines before `migrateLegacySenpiDirs(cwd)` in `runMigrations()` and one import.

## 2026-09-27 - Unsupervised processes leave a record when they crash natively (senpi#2194)

### What changed

- `packages/coding-agent/src/main.ts`: once the app mode is final (after `readPipedStdin`), `recordProcessLifetime(agentDir, appMode, { supervised: appMode === "rpc" })` (`src/core/process-crash-record.ts`) turns the lifetime marker of every dead senpi process into one record in `<agentDir>/process-crashes/crashes.jsonl` (`detection: "unclean_exit"`, kind, uptime to the last heartbeat, Bun and senpi versions), then writes this process's own marker unless it runs in RPC mode, whose parent already watches its exit. The marker is removed on every exit JavaScript can observe, through the `signal-exit` hook `proper-lockfile` already installs in every process, so signal behaviour is unchanged.

### Why

- An interactive or print process has no supervising parent (the omo launcher `execve`s into it), so a native crash such as the JSC heap corruption in senpi#1949 left nothing countable behind; only the supervised RPC host recorded its deaths (senpi#1950).

### Why an extension could not handle it

- The marker has to exist before extensions load and must cover processes whose extension set is not known, and the sweep has to run on every launch whatever extensions are installed.

### Expected merge conflict zones

- `packages/coding-agent/src/main.ts`: the two lines after `time("readPipedStdin")` and one import.

## 2026-09-27 - --continue and --resume reach a moved repository's sessions (senpi#2184)

### What changed

- `packages/coding-agent/src/main.ts`: `rebindSessionOrExit` awaits the now lock-protected `rebindSessionFile`. `--resume` lists the moved sessions of this repository in the current-folder scope (`withMovedSessions`) and marks them in the all scope (`markMovedSessions`, `src/core/moved-sessions.ts`), and routes the pick through `resolveResumeTarget` (`src/core/resume-target.ts`), which offers the #2181 rebind and reports the process still holding the session. `--continue` in a project with no session file of its own asks `movedSessionToContinue` (`src/cli/continue-moved.ts`): interactive runs get the rebind prompt for the newest moved session, other runs get the `--rebind` command on stderr and a new session as before.

### Why

- After `mv repo`, `--continue` silently started an empty session and the `--resume` current-folder view was empty, so the moved sessions were only reachable by id (senpi#2184, oh-my-openagent#8914).

### Why an extension could not handle it

- `--continue` / `--resume` resolution runs in the CLI before any extension or session exists.

### Expected merge conflict zones

- `packages/coding-agent/src/main.ts`: the `--resume` branch after `selectSession`, the `--continue` branch, `rebindSessionOrExit`, and three imports.

## 2026-09-27 - Rebind a moved repository's session instead of only forking it (senpi#2181)

### What changed

- `packages/coding-agent/src/main.ts`: `createSessionManager` classifies a cross-project `--session` hit with `classifySessionRepository` and hands the decision to `chooseCrossProjectAction` (`src/cli/cross-project-session.ts`): the same git repository gets a rebind prompt showing both paths (`rebindSessionFile`, `src/core/session-rebind.ts`), a different or unrecognised one keeps the fork prompt, and a non-interactive run prints the exact `--rebind` / `--fork` commands and exits 1. A new `--rebind <path|id>` branch (`validateRebindFlags`) rebinds without asking and refuses a provably different repository. `--resume` offers the same rebind when the picked session belongs to this repository at another path.

### Why

- Sessions are filed by absolute path, so moving a repository stranded its sessions: they could only be forked into copies, and the originals never listed under the moved project again (senpi#2181, oh-my-openagent#8914).

### Why an extension could not handle it

- `--session` / `--resume` resolution runs in the CLI before any extension or session exists; the recording half (`repository-identity` builtin) is an extension.

### Expected merge conflict zones

- `packages/coding-agent/src/main.ts`: the `case "global"` branch of `--session`, the `--resume` branch after `selectSession`, the new `--rebind` branch after `--fork`, `validateRebindFlags` / `rebindSessionOrExit` / `sessionCwdOrUndefined` beside `validateForkFlags` / `forkSessionOrExit`, and two imports.

## 2026-09-27 - Preserve interactive cross-project session confirmations (senpi#2180)

### What changed

- `packages/coding-agent/src/main.ts`: prevent the readline `close` fallback from overriding an answer already received by `promptConfirm()`, and trim the answer before matching `y`/`yes`.
- `packages/coding-agent/test/suite/regressions/issue-2180-interactive-session-confirmation.test.ts`: cover `y`, `yes`, padded/uppercase answers, `n`, empty input, and EOF.

### Why

- Calling `rl.close()` from the question callback emits `close` before the callback's result can settle the promise, so `y` and `yes` were incorrectly treated as `false`.

### Why an extension could not handle it

- Cross-project session confirmation runs in the core CLI session-resolution path before an extension can take over.

### Expected merge conflict zones

- `packages/coding-agent/src/main.ts` `promptConfirm` (now exported for the regression test)
- `packages/coding-agent/test/suite/regressions/issue-2180-interactive-session-confirmation.test.ts`

## 2026-09-26 - Run on Bun when installed and tell Node.js users once how to switch (senpi#2157)

### What changed

- `packages/coding-agent/src/bun-runtime.ts`: `resolveBunReexec` gains a rule between the Bun-global rule and the fallback: a script under a `node_modules` directory (`isInstalledPackageScript`: npm, pnpm, Yarn, npx, project-local installs) re-execs under a discovered Bun when `<bun> --version` is at least `MIN_BUN_VERSION` (1.4.0), and otherwise stays with the new `bun-too-old` reason. `BunRuntimeOptions` gains the injected `bunVersion` probe (`readBunVersion`, a 5 s `spawnSync` of `<bun> --version`, in `processBunRuntimeOptions`). A `SENPI_RUNTIME=bun` pin and Bun-global installs keep trusting their Bun without the probe; source checkouts keep `not-bun-install`.

### Why

- npm installs stayed on Node.js even on machines with a current Bun, so users silently lost Bun-only behavior (e.g. #2032). The OmO Native launcher already applies the same rule (oh-my-openagent #7680); the engine now matches it for standalone installs.

### Why an extension could not handle it

- Runtime selection happens in the launcher before any extension, session, or engine module loads.

### Expected merge conflict zones

- None upstream: `bun-runtime.ts` is fork-only and `cli.ts` is unchanged.

## 2026-09-27 - Export the tool hook types

### What changed

- `packages/coding-agent/src/index.ts`: re-exports `KernelPreludeContribution` and `ToolPermissionRequest` for extension packages.

### Why

- Extension packages type their tool definitions against the package entry.

### Why an extension could not handle it

- Package entry exports.

### Expected merge conflict zones

- LOW: the extension type export list.

## 2026-09-24 - Profile /resume session switches under TIMING (senpi#2087)

### What changed

- `packages/coding-agent/src/main.ts`: the CLI runtime factory marks `services`, `sessionOptions`, and `createSession` in the `switch` timing namespace when it builds a runtime for a `session_start` event whose reason is `resume`. No-op unless `TIMING=1`.

### Why

- The switch profile needed the factory's own phases (service recreation, option resolution, session construction) separated from teardown and extension binding; on a 42.5 MB session each costs ~0.1-0.3 s and none dominates.

### Why an extension could not handle it

- The factory runs before the new session's extensions exist.

### Expected merge conflict zones

- LOW: three one-line marks inside the factory closure in `createCliRuntimeFactory`.

## 2026-09-23 - `resolvedToolName` on toolcall_start/toolcall_end JSON and RPC records (senpi#2068)

### What changed

- `packages/coding-agent/src/modes/json-event.ts`: `toJsonEvent` copies the session event's `resolvedToolName` into the delta-only `message_update` record written by stdout RPC and `--mode json`. Socket-host records already carry it, since `demoteToDeltaOnly` only rewrites `*_delta` records and spreads the rest.
- `docs/rpc.md`, `docs/json.md`: document the field. `test/suite/regressions/issue-2068-rpc-resolved-tool-name.test.ts` (new); `7925-toolcall-start-metadata.test.ts` pins it on the exact `toolcall_start` wire shape.

### Why

- Clients title a streaming call by the tool it will run from its first frame (code-yeongyu/omo-desktop-app#1079); without the copy the field existed on the in-process event but never reached the wire.

### Why an extension could not handle it

- The JSON wire projection is built by the mode, after every extension hook; an extension cannot add fields to the records `toJsonEvent` writes.

### Expected merge conflict zones

- LOW: the returned object in `toJsonEvent`.

# changes

## 2026-09-23 - Export EntryRendererOptions from the package entry (senpi#2051)

### What changed

- `packages/coding-agent/src/index.ts`: re-exports the new `EntryRendererOptions` type next to `EntryRenderer` and `EntryRenderOptions`.

### Why

- `pi.registerEntryRenderer()` gained an optional third argument (`replaces`) so an entry can update the card before it; extension authors importing from the package need its type.

### Why an extension could not handle it

- `packages/coding-agent/src/index.ts` is the package's public type surface; extensions cannot add exports to it.

### Expected merge conflict zones

- `packages/coding-agent/src/index.ts`: the extension-rendering type export list.

## 2026-09-21 - Print mode explains transport drops and never prints the replay marker (senpi#1628)

### What changed

- `packages/coding-agent/src/modes/print-mode.ts`: the text-mode error line goes through pi-ai's `describeProviderFailureForUser` (stall wording delegated, WebSocket interruptions worded for a person) and the raw fallback is passed through `stripTurnRetrySuppressionPrefix`.

### Why

- `packages/coding-agent/src/modes/print-mode.ts` printed the assistant's `errorMessage` verbatim, so a Codex WebSocket drop ended a `-p` run with `senpi:no-turn-retry:WebSocket error` on stderr - an internal classifier token in front of a transport verdict.

### Why an extension could not handle it

- `packages/coding-agent/src/modes/print-mode.ts` owns the one-shot exit path; no extension event runs between the final assistant message and the stderr write.

### Expected merge conflict zones

- `packages/coding-agent/src/modes/print-mode.ts`: the pi-ai import line and the text-mode error branch.

## 2026-09-21 - Announce supersession and park attached RPC sessions (#1933)

### What changed

- The socket host serializes `host_superseded` through its event writer before draining, then parks attached as well as unattached sessions with `session_closed { reason: "handoff_parked", sessionPath }` and closes connections after their last attached session parks.
- Handoff activity protects turns and in-flight requests but excludes durable wake-source holds; ordinary idle eviction is unchanged. Both in-process and worker runtimes publish the handoff predicate.
- The supervisor owns the 600000 ms `SENPI_RPC_HANDOFF_GRACE_MS` soft deadline. Expiry requests another drain pass, never aborts active work, and child exit ends the generation regardless of attached clients.

### Why

- Attached idle sessions pinned superseded hosts forever, without telling clients to reopen their files on the successor. Late commands on a parked handle now terminate through the close rather than `unknown_session`.

### Why an extension could not handle it

- Supervisor signals, JSONL ordering, shared connection ownership, request accounting and file reservations belong to the host transport and session registry.

### Expected merge conflict zones

- `modes/rpc/host-lifecycle.ts`, `multi-session-host.ts`, `session-command-router.ts`, `session-event-writer.ts`, and worker activity snapshots. Socket regression tests exercise real supervisors and held model turns.

## 2026-09-21 - Preserve host MCP registry injection in CLI runtime creation (#1915)

### What changed

- `packages/coding-agent/src/main.ts` forwards the runtime factory's optional MCP registry to session services.

### Why

- `packages/coding-agent/src/main.ts` recreates services during session replacement; the host registry must follow the runtime factory rather than a single initial session.

### Why an extension could not handle it

- `packages/coding-agent/src/main.ts` owns CLI runtime construction before extension loading.

### Expected merge conflict zones

- `packages/coding-agent/src/main.ts`: `createCliRuntimeFactory` arguments and `createAgentSessionServices` options. Sharing remains disabled.

## 2026-09-21 - Export retained-session attachment events (#1902)

### What changed

- `index.ts` exports `SessionParkedEvent` and `SessionResumedEvent` alongside the other public session event types.

### Why

- Extensions need to name the types of the additive retained-session attachment hooks.

### Why an extension could not handle it

- The package entry point owns its exported type surface.

### Expected merge conflict zones

- The session event type export list in `index.ts`.

## 2026-09-21 - Per-provider streaming concurrency cap (senpi#1909)

### What changed

- `core/provider-concurrency.ts` (new): `createProviderSemaphores(getLimit)` hands out one FIFO, abort-aware semaphore per provider id and exposes `bracket(providerId, signal, run)` plus `resize(providerId, limit)`. `bracket` acquires a slot, calls `run()`, and releases exactly once when the returned stream's `result()` settles - fulfil, reject, or abort - never at stream construction. A provider with no cap returns `run()` untouched, so the unconfigured path adds no bookkeeping.
- `core/model-runtime.ts`: all four provider stream call sites (`stream` and `streamSimple`, each in its credential-rotation attempt and its plain path) now go through the bracket, keyed by `prepared.model.provider`. `complete`/`completeSimple` inherit it. `setSettingsManager()` (also accepted as `CreateModelRuntimeOptions.settingsManager`) supplies the limits and subscribes for changes.
- `core/settings-manager.ts`: `Settings.providers?: Record<string, ProviderConcurrencySettings>`, `getProviderConcurrencyLimit()`, `getProviderSettings()`, and `subscribeToProviderSettings()`. Every merged-settings assignment now routes through one `updateSettings()` helper so trust changes, reloads, overrides and saves all notify subscribers.
- `core/settings-diagnostics.ts`: a negative or fractional `providers.<id>.maxConcurrency` becomes a startup warning instead of silently doing nothing. One private `providerSettingsWarnings()` feeds both the plain collector and the new context-labelled `collectSettingsDiagnosticsWithContext()`.
- `main.ts`: the CLI's own private settings-diagnostic collector is gone. Startup session lookup, runtime creation and model listing now call `collectSettingsDiagnosticsWithContext()`, so a malformed cap reaches the CLI surface too - the duplicate collector had silently skipped every diagnostic this module adds.
- `core/sdk.ts`, `core/agent-session-services.ts`: both session entry points hand their settings manager to the runtime.
- Behaviour is unchanged until a cap is configured; no provider ships a default.

### Why

- A provider that rate-limits on concurrent connections (or a local runtime with a small worker pool) turns burst fan-out into 429s and refused sockets, and senpi had no way to express "at most N at once" for one provider.
- The bracket is deliberately narrow. Holding a slot for a whole agent turn deadlocks any spawn tree wider than the cap, because parents wait on children that wait for slots the parents still hold. Releasing when the provider's stream finishes producing keeps the slot tied to the HTTP request and nothing else.

### Why an extension could not handle it

- The request is issued inside `ModelRuntime`, after credential resolution and rotation slot selection; no extension hook sits between provider selection and the outgoing stream, and the cap must also cover rotation retries.

### Expected merge conflict zones on next upstream sync

- MEDIUM: the four `prepared.provider.stream(...)` / `streamSimple(...)` call sites in `model-runtime.ts` are now wrapped, so upstream edits to those argument lists conflict textually.
- LOW: additive `Settings` field, additive settings-manager methods, and the `this.settings = ...` assignments rerouted through `updateSettings()`.
- LOW: `main.ts` loses a nine-line local function and gains one import; its three diagnostic call sites are renamed.

## 2026-09-21 - The in-process daemon host initializes the theme before serving sessions (senpi#1894)

### What changed

- `main.ts`: the `appMode === "rpc" && parsed.multiSession` branch calls `initTheme(startupSettingsManager.getTheme(), false)` again, immediately before `runMultiSessionHost(...)`. The worker split (75572fc90d) had removed this call and kept the theme bootstrap only inside each session worker, so the in-process runtime (the default for a `--listen` socket host) lost it: the host never returns, the `initTheme()` further down `main()` stays unreachable, and every theme-touching extension load failed with "Theme not initialized. Call initTheme() first.".
- Regression: `test/suite/regressions/issue-1894-inprocess-theme-init.test.ts` spawns the real CLI as a `--listen unix://` socket host pinned to `--session-runtime in-process`, opens a session over the socket with a global extension that touches `theme` at load time, and asserts the probe marker appears with no "Theme not initialized" text in the host transcript or any delivered record. Its teardown goes through `helpers/spawned-host-reaper.ts` (`reapProcessesUnder` on the mkdtemp sandbox, and NOT `killAndWait` first): the socket host runs as a grandchild of the tsx wrapper the test spawned and renames its own argv (`process.title`), so killing the wrapper first makes the host unreachable to any later argv match - it survives holding the socket and writes into the sandbox mid-removal (measured: one orphaned host per run, `ENOTEMPTY` on the temp dir). Reaping by the sandbox path walks the wrapper's descendants and kills the host with it. `0000-multi-session-theme-init.test.ts` keeps covering the worker runtime.

### Why

- Extensions load per `open_session` and read the process-global `theme` proxy. The worker runtime initializes the theme inside each isolate (`session-worker.ts`); the in-process runtime shares the host process, so the host bootstrap must initialize the theme before the first session opens. The original multi-session fix (db1cfefc54) put this call in `main.ts`; the worker split dropped it from the branch that needed it.

### Why an extension could not handle it

- The theme proxy is process-global state owned by the host bootstrap; extension code runs after the ordering it needs has already been decided.

### Expected merge conflict zones on next upstream sync

- LOW: one additive call (plus comment) inside the multi-session dispatch branch in `main.ts`.

## 2026-09-21 - Print extension user edits and guarded tree navigation

### What changed

- `packages/coding-agent/src/modes/print-mode.ts`: binds `editUserMessage` beside assistant editing and forwards `expectedLeafId` for navigation without re-reading or defaulting the caller's token.

### Why

- `packages/coding-agent/src/modes/print-mode.ts`: print/JSON extension command contexts must expose the same edit capability and typed core errors as RPC and interactive mode.

### Why an extension could not handle it

- `packages/coding-agent/src/modes/print-mode.ts` constructs the host actions before invoking extension commands.

### Expected merge conflict zones

- `packages/coding-agent/src/modes/print-mode.ts`: navigation and assistant-edit neighbours inside `commandContextActions`.

## 2026-09-20 - Name what the startup timing table measures before the stdin read (senpi#1868 follow-up)

### What changed

- `packages/coding-agent/src/main.ts`: two `time()` marks around `writeHelpFlagsCache`, so the startup table reports `extensionFlags` and `helpFlagsCache` instead of folding both into the row labelled `readPipedStdin`.

### Why

- `readPipedStdin` returns immediately when stdin is a TTY, yet its row carried 76-172 ms in two profiled interactive launches. The interval belonged to the help-flags cache write, which stats every loaded extension file: a reader chasing that row looked at stdin handling and found nothing. With the marks in place the same launches report `helpFlagsCache` at a 3 ms median (tail 27-118 ms under load) and `readPipedStdin` at 0 ms.

### Why an extension could not handle it

- The marks sit in `main()` between resource loading and the interactive branch, before any extension host exists.

### Expected merge conflict zones

- LOW: the statements around `writeHelpFlagsCache` in `main.ts`.

## 2026-09-20 - Forward initial CLI model provenance (#1560)

### What changed

- `packages/coding-agent/src/main.ts` forwards the resolved `initialModelProvenance` to session creation.

### Why

- `packages/coding-agent/src/main.ts` resolved explicit and scoped models but discarded their provenance before extensions received `session_start`.

### Why an extension could not handle it

- The metadata is lost in `packages/coding-agent/src/main.ts` before an extension can observe the startup event.

### Expected merge conflict zones

- LOW: the `createAgentSessionFromServices` options in `packages/coding-agent/src/main.ts`.

## 2026-09-19 - The in-process daemon shares one model runtime across its sessions (senpi#1844)

### What changed

- `main.ts` `createCliRuntimeFactory` accepts `modelRuntime` in its local options and passes it
  to `createAgentSessionServices`, which already honoured an injected runtime but was never
  handed one on the daemon path.
- `main.ts` multi-session entry builds one `ModelRuntime` for the host's agent dir and gives it to
  the factory - in-process only. Worker sessions build their own inside the isolate; an object
  cannot cross that boundary, so the shared one is not offered there.

### Why

Measured on `main` from source (44 extensions, sandbox agent dir): an open is ~92%
`createAgentSessionServices`, and inside it `ModelRuntime.create` (~110 ms) runs in parallel with
`resourceLoader.reload` (~105 ms), so an open costs the slower branch. Under concurrency the
opens interleave as synchronous CPU on one loop: 8 concurrent opens on a warm cache took 1013 ms
wall with min 1008 - every open waited for all eight. That is the 32-open / 10.5 s minimum on
#1844 to the millisecond. A shared host's sessions all live in one agent dir, so every one of
those runtimes was identical.

Sharing it alone did NOT move the daemon: the unconditional per-open `modelRuntime.refresh()`
recomposed every provider the shared instance had accumulated, serialized on that one instance,
and cost more than the parallel `create` it replaced (measured 29-118 ms vs ~5 ms). So a shared
runtime refreshes only the providers this open registered, and nothing when it registered none.

Measured on the built daemon over its socket, 9 rounds each, alternating: single warm open
277 -> 162 ms median (~40%); 8 concurrent opens 507 -> 439 ms wall median (~15%), the two
distributions separating. Not the ~50% a source-level probe had promised - that probe's faux
extensions registered no providers, which hid the refresh cost. `reload` is now the sole
critical path (tracked on #1844).

### Why an extension could not handle it

The runtime is built before any extension of the session exists, by the services layer that
extensions are loaded into. An extension sees the runtime only through `ctx`; it cannot supply
one.

### Expected merge conflict zones

- `main.ts` - the `createCliRuntimeFactory` options type and the `runMultiSessionHost` call.
  Upstream changes to either the factory's local options or the daemon entry meet this.
- `core/agent-session-services.ts` - the provider replay loop now records what it registered and
  the trailing refresh is scoped when the runtime was injected. Upstream changes to the replay or
  to the refresh call meet this.

## 2026-09-18 - Every daemon surface this fork added is documented where its client reads (senpi#1782)

### What changed

- `packages/coding-agent/docs/rpc.md`: the in-process session runtime with its measured per-session cost, the occupancy section rewritten so nothing implies the daemon caps sessions, invariants I3/I4 beside I1/I2, the no-sync rule, the `session_opened`/`session_closed`/`session_parked`/`session_replaced` event rows, and the two live QA drivers that verify a daemon build.
- `packages/coding-agent/docs/extensions.md`: `pi.sessionKind` / `pi.sessionContext` / `pi.sharedHostEnabled` with a gating example, and the measured per-session cost of the `config-reload` watcher (senpi#1794).
- `packages/coding-agent/src/modes/rpc/AGENTS.md`: host-lifecycle and daemon-state modules in the structure block, the I1-I4 and no-sync sections, daemon suites, the fixture-reaper receipt and the QA drivers.

### Why

- The daemon work of this plan (in-process runtime, session kind/context, retention, generation handoff, `senpi host`, the stall guard) landed across four increments; each documented its own slice, and the result described a host with a session cap it no longer has. One pass makes the public reference match the shipped behaviour, including the cost it is honest about.

### Why an extension could not handle it

- Documentation of engine process lifecycle, wire protocol and the extension contract itself.

### Expected merge conflict zones

- LOW: docs prose in sections upstream rarely edits, plus this fork's own `AGENTS.md`.

## 2026-09-17 - `senpi host` is routed before argument parsing and exported for launchers (senpi#1782)

### What changed

- `packages/coding-agent/src/main.ts`: `dispatchHostCommand(args)` runs beside the app-server route, BEFORE `parseArgs`, and exits with the code it returns. The route is one argv[0] comparison in `cli/deferred-commands.ts` with the implementation behind an `await import(...)`, so `dist/main.js` still does not statically reach the RPC host graph - and `senpi host ...` never falls through into argument parsing, the print path or the interactive TUI.
- `packages/coding-agent/src/modes/index.ts`: re-exports the new host surface - `runHostRequest` with `HostRequest`/`HostOutcome`/`HostTarget` and the `HOST_EXIT_*` codes, `readHostStatus` with its report types, and `loadHostLaunchSpec`/`parseHostLaunchSpec`/`HostLaunchSpecError` with `HostLaunchSpec`/`ResolvedHostLaunchSpec`.
- `packages/coding-agent/src/index.ts`: the package barrel adds `runHostCommand` (from `cli/host-command.ts`) plus everything `modes/index.ts` now publishes, so the omo launcher and the desktop drive the same command without a shell.

### Why

- Every client of the machine-wide daemon needs one answer to "is there a host, may I use it, may I replace it", and the invariants behind it (never signal a host you did not start; compatibility is protocol plus capabilities) must not be re-derived per client. The command is that one answer, so it has to be reachable both as a process and as a function.
- The dispatch sits before `parseArgs` because `host` is a command, not a prompt: reaching argument parsing would make a stray `senpi host status` open a session instead of answering.

### Why an extension could not handle it

- Command routing, process exit codes and the package barrel all run before any extension is loaded.

### Expected merge conflict zones

- LOW: one import block and one dispatch branch in `main.ts`, and the additive export lists in `modes/index.ts` and `index.ts`.


## 2026-09-17 - The host-daemon surface is what the modes barrel re-exports (#1782)

### What changed

- `index.ts` and `modes/index.ts`: re-export the host-daemon surface a client needs - `ensureHost`, `probeHost`, `stopHost`, `handoffHost`, `decideHostAction`, `engineBuildIdentity` and the host identity/decision types - beside the existing `RpcClient` surface, so nothing outside `modes/rpc/` reaches into that directory.

### Why

A client - omo's task runner, the desktop server, a terminal attach - has to decide what to do with a host it finds on a socket. That decision belongs to the engine (protocol version, capabilities, build ordinal, launch profile), not to each client's guesswork, so the engine must export it. One barrel is also what lets a client duck-type these symbols and fail closed against an older engine that lacks them.

### Why an extension could not handle it

An extension runs inside a session; both of these are process-level surfaces that exist before any session does - the module barrel a client imports to decide what to do with a host it found, and the compile step that stamps the binary. Neither is reachable from extension code.

### Expected merge conflict zones

Upstream edits to the same export list, and upstream edits to the `bun build --compile` argument list in the release script.



### What changed

`src/modes/index.ts` now re-exports the pieces a client needs to talk to a machine-wide host, so nothing outside `src/modes/rpc/` has to reach into that directory: `ensureHost`, `probeHost`, `stopHost`, `handoffHost`, `decideHostAction` and the host identity/decision types, alongside the `RpcClient` surface that was already there.

### Why

A client - omo's task runner, the desktop server, a terminal attach - decides what to do with a host it found on a socket. That decision belongs to the engine (protocol version, capabilities, build ordinal, launch profile), not to each client's own guesswork, so the engine has to export it. Keeping the export list in one barrel is also what lets a client duck-type the symbols and fail closed when it is running against an older engine that does not have them.

## 2026-09-17 - Per-session kind and context reach the session's resources only (senpi#1782)

### What changed

- `packages/coding-agent/src/main.ts`: the runtime factory forwards `launchProfile.sessionKind` and `launchProfile.sessionContext` into `resourceLoaderOptions`, beside `sharedHostEnabled`. The `runtimeParsed` override block is untouched, so neither value enters `CliRuntimeConfiguration.parsed`.

### Why

- A shared host's `open_session` selects those two per-session values, and the only thing that may observe them is the session's own extension set (`pi.sessionKind` / `pi.sessionContext`). Routing them through `parsed` would let a client's opaque labels reach model, auth and flag resolution, which is exactly what the field must never do.

### Why an extension could not handle it

- The factory runs before any extension of that session exists; it is where the per-session resource loader is configured.

### Expected merge conflict zones

- LOW: the `resourceLoaderOptions` literal inside `createCliRuntimeFactory`.

## 2026-09-17 - Socket RPC hosts stop allocating a worker per session (senpi#1782)

### What changed

- `packages/coding-agent/src/main.ts`: the `appMode === "rpc" && parsed.multiSession` branch resolves `resolveSessionRuntime(parsed)` and passes `workerConfiguration` to `runMultiSessionHost` only for the `worker` runtime; the runtime factory is still built from the same configuration on both paths. `main.ts` is the only producer of that option, and `createHostCore` selects `WorkerSessionRegistry` exactly when it is present, so withholding it selects the uncapped in-process `RpcSessionRegistry`.

### Why

- A `--listen` socket host is the shared daemon every client attaches to; the worker registry caps admission at 20 and answers `too_many_sessions` beyond it, which a daemon may never do. Nothing was removed from the worker path - `--session-runtime worker` still reaches the same code with the same cap.

### Why an extension could not handle it

- Host construction happens before extensions load, and no extension surface selects the session registry.

### Expected merge conflict zones

- LOW: the ~10 lines of the multi-session host launch block.

## 2026-09-17 - The bundled entry replays exec arguments onto itself (senpi#1781)

### What changed

- `packages/coding-agent/src/cli.ts`: `spawnFullCli()` resolves the respawn target from `isBundledNode` - the bundle re-executes its own `import.meta.url`, an unbundled install keeps spawning the sibling `cli-main`. The bundled child carries `SENPI_CLI_ISOLATED_CHILD=1`, which `requiresIsolatedProcess()` reads first so it loads the agent in process instead of spawning again.

### Why

- The bundle inlines `cli-main`, so no sibling module exists beside it. Once the package build started emitting the bundle and the launcher preferred it, every launch carrying custom exec arguments (a profiler or inspector flag, anything in `NODE_OPTIONS`) failed with `Module not found .../dist/bundle/cli-main.js` before any agent code ran.

### Why an extension could not handle it

- Process structure is decided by the entry module before the extension host exists.

### Expected merge conflict zones

- LOW: `requiresIsolatedProcess()` and `spawnFullCli()` in `cli.ts`.

## 2026-09-17 - Defer command and mode graphs out of main()'s import block (senpi#1781)

### What changed

- `packages/coding-agent/src/main.ts`: the app-server command tree, the RPC host cluster (rpc-mode, multi-session-host, host-lifecycle, interactive-host-runtime), the package-manager CLI, the `--list-tips` registry and the `--resume` session picker are `await import(...)`ed at the branch that owns them instead of at module load; the one-shot command dispatch and the supervisor launch moved into `src/cli/deferred-commands.ts` and `src/modes/rpc/supervisor-route.ts` so `main.ts` did not grow.
- `main()` records `processStart->main` from `process.uptime()` as the first row of the PI_TIMING main table, and the `PI_STARTUP_BENCHMARK` branch exits 0 after draining stdout/stderr.

### Why

- Those graphs were evaluated before argv was even parsed: 92 of 2,780 resolved modules and about 147ms of import cost for code an interactive run never reaches. The pre-main phase was invisible because the timing table's clock starts inside `main()`, and a benchmark run never exited because interactive mode's terminal handles outlive its `stop()`.

### Why an extension could not handle it

- This is the host's own entry module; its import graph, timing instrumentation and benchmark exit all run before any extension exists.

### Expected merge conflict zones

- MEDIUM: the import block at the top of `main.ts`, the dispatch sequence at the start of `main()`, and the mode dispatch tail.

## 2026-09-17 - Skip completed directory-scan migrations on later boots (senpi#1781)

### What changed

- `packages/coding-agent/src/migrations-state.ts` (new): reads and writes `<agentDir>/migrations-state.json` (schema version 1, completed scan names); the read is fail-open and the write is tmp+rename.
- `packages/coding-agent/src/migrations.ts`: `runMigrations` skips `migrateLegacySenpiDirs` and `migrateSessionsFromAgentRoot` when the marker lists them, then records them once both complete.

### Why

- Those two migrations are idempotent directory scans that cost `readdirSync` work on every boot long after the legacy layouts are gone; the other migrations (auth, tools-to-bin, keybindings, extension system, brand dir) still run every start.

### Why an extension could not handle it

- `runMigrations` runs in `main.ts` before the extension host exists.

### Expected merge conflict zones

- LOW: the body of `runMigrations`.

## 2026-09-16 - Type kernelTools as the shipped invoke-scope surface (senpi#1731)

### What changed

- `packages/coding-agent/src/index.ts` exports `ExtensionKernelTools`, `KernelToolInvokeOptions`, and `KernelToolInvokeScope` as the public shipped kernel-tools surface.

### Why

- `packages/coding-agent/src/index.ts` is the public `@code-yeongyu/senpi` surface; typed consumers of `kernelTools` were still on the pre-#1765 `AbortSignal`-only declaration.

### Why an extension could not handle it

- Package index re-exports are owned by coding-agent; an extension cannot change the published host type.

### Expected merge conflict zones

- `packages/coding-agent/src/index.ts` adjacent to the `kernelToolsStorage` export.

## 2026-09-16 - Order worker output to one client scope (senpi#1676)

### What changed

- `packages/coding-agent/src/experimental/session-worker-manager.ts`: service events and operation responses for one attachment scope now share a single FIFO (`#forwardInScopeOrder`) instead of an async per-subscription delivery chain plus an immediately settled response. A response is handed to the presentation client only after every provider update the worker emitted before it has been forwarded, so the client observes the worker's emission order; buffering stays bounded by the transport's existing pending-byte limit, whose overflow disconnects that peer explicitly.
- `packages/coding-agent/src/experimental/client.ts`: `runClient` keeps its transcript subscription until the prompted run's own terminal event (`run_end`/`run_suspend`) has been delivered, bounded by `RUN_TAIL_TIMEOUT_MS`, instead of unsubscribing the moment the prompt response resolves.

### Why

- senpi#1676: a worker emits a run's transcript updates and that run's response on one control channel in order, but the server forwarded them on two independent paths. Under a client that was slow to drain its socket, the prompt response overtook the queued updates, and the client tore its subscription down on the response - the received event list ended at `entry_added` with `run_end` missing (reproduced with a stalled peer write), and the same race could return an empty answer because the assistant `message_end` had not been delivered either.

### Why an extension could not handle it

- The ordering hazard is inside the host's worker-to-client forwarding and the client command's own subscription lifetime; no extension surface observes either.

### Expected merge conflict zones

- MEDIUM: `#handleOperationResponse` and `#handleServiceEvent` in `session-worker-manager.ts`, plus the removed `deliveryTail` field on `WorkerServiceSubscription`. LOW: the prompt block of `runClient` in `client.ts`.

## 2026-09-16 - Answer `--help` without booting the engine (oh-my-openagent#8371)

### What changed

- `packages/coding-agent/src/cli.ts`: a plain root `--help`/`-h` is answered before `cli-main` is imported when `cli/help-fast-path.ts` finds a valid flags cache for this cwd, agent dir, `--extension` set and project-trust decision; the import stays dynamic for the same reason the `cli-main` import is. `--no-extensions` is answered without any cache.
- `packages/coding-agent/src/main.ts`: a plain `--help` stops right after CLI paths are resolved. It resolves extension flags through `cli/help-extension-flags.ts` (a `DefaultResourceLoader` with skills, prompt templates, themes and context files disabled; no `ModelRuntime`, no `SessionManager`, no `AgentSession`), prints help, writes `<agentDir>/cache/help-flags.json` through `cli/help-flags-cache.ts` and exits. Every full launch also refreshes that cache from the runtime's loaded extensions right after the late `parsed.help` branch, which now only serves `--help --mode json` / `-p --help`.
- Project trust for the help path is `--yolo`/override → recorded `trust.json` decision → trusted when the project carries no trust-requiring resources; it never prompts and never loads untrusted project extension code.

### Why

- oh-my-openagent#8371: `omo --help` measured 47.8s on Windows and 790ms warm / 8.8-13.6s cold on bun here, all spent building a runtime the help screen never uses. Cached help now costs 28ms (bun) / 59ms (node); a cache miss costs the extension load only.

### Why an extension could not handle it

- The help screen is printed by the host before any extension is bound, and the cost being removed is the host's own runtime construction.

### Expected merge conflict zones

- MEDIUM: `main.ts` around the `resolveCliPaths` block and the late `if (parsed.help)` branch; LOW: `cli.ts` next to the `--version` fast path.

## 2026-09-16 - Print mode explains provider stalls (senpi#1740)

### What changed

- `packages/coding-agent/src/modes/print-mode.ts`: the terminal `console.error` for an errored or aborted final assistant message routes `errorMessage` through `describeProviderStallForUser` first, so a headless run reports the stall in plain language and keeps every other error verbatim. The exit code and stdout path are unchanged.

### Why

- senpi#1740: `senpi -p` printed the stream watchdog's interpolated message as the whole failure output, which names no cause and no next step.

### Why an extension could not handle it

- Print mode's final output is written by the host after the session settles.

### Expected merge conflict zones

- LOW: one import line and the `console.error` call in the `mode === "text"` branch.

## 2026-09-16 - Export kernelTools storage (senpi#1647)

### What changed

- packages/coding-agent/src/index.ts exports kernelToolsStorage and ExtensionKernelTools for senpi-codemode.

### Why

- packages/coding-agent/src/index.ts is the public `@code-yeongyu/senpi` surface the originating eval uses to bind kernel tools onto host-tool context.

### Why an extension could not handle it

- Package index re-exports are owned by coding-agent; an extension cannot add a host context capability type.

### Expected merge conflict zones

- packages/coding-agent/src/index.ts adjacent to other extension exports.

## 2026-09-14 - Clickable pending questions and capture controls (#1645)

### What changed

- The interactive host renders clickable pending options and expanded question actions, commits selection feedback before answering, and owns capture leases across renderer replacement and terminal handoffs. Settings expose `terminal.mouse: off | whilePending | always`; default `whilePending` leaves no-question regular sessions uncaptured.
- Public TUI, keybinding and settings guides plus one input tip describe clicks, selection bypass, tmux calibration and the herdr 0.9.0 short-frame limitation tracked by #1688. Exact source ownership is recorded in the interactive and core trackers.

### Why

- Pending questions should be directly answerable without taking over terminal selection outside their lifetime or changing existing keyboard paths.

### Why an extension could not handle it

- The built-in question components, renderer lifecycle and persisted terminal settings are host-owned; the lower-level cursor source belongs to the TUI package.

### Expected merge conflict zones

- Interactive lifecycle and question component wiring, terminal settings accessors, input tips and related public guides. No question wire format or default renderer changes.

## 2026-09-14 - Activate builtin herdr pending-input reporting (senpi#1645)

### What changed

- `packages/coding-agent/src/core/extensions/builtin/index.ts` registers the lifecycle reporter after `ask-user`; `builtin/herdr/index.ts` reads loaded extension paths at session start and bounded managed headers.
- `packages/coding-agent/src/core/extensions/types.ts` and `runner.ts` expose optional read-only resolved extension paths, including event-only user extensions. Detailed API ownership is recorded in `core/extensions/changes.md`.

### Why

- Pending questions and host dialogs need explicit blocked state in herdr without requiring a separately installed user reporter or competing with one already loaded. Managed integration files remain installed and do not suppress the builtin.

### Why an extension could not handle it

- Lifecycle reporting stays in the builtin extension. Only the loaded-path handoff requires host code because factories cannot see other extensions' discovery identities.

### Expected merge conflict zones

- The `ExtensionContext` and `createContext()` getter lists and the builtin registration after `ask-user`. No interactive-mode or question component behavior changes in this increment.

## 2026-09-13 - Centralize standalone provider registration

### What changed

- `packages/coding-agent/src/bun/runtime-modules.ts` synchronously registers Bedrock, Cursor, Devin and bundled OAuth once per isolate, preserving later overrides on repeat calls.
- `packages/coding-agent/src/bun/runtime-setup.ts` delegates registration to that entry.
- `packages/coding-agent/src/bun/cli.ts` retains sandbox -> runtime setup -> CLI order and removes the separate `register-cursor-agent.ts` import; that redundant file is deleted.

### Why

- Variable-specifier imports cannot resolve implementations absent from a relocated compiled binary, and launcher registration does not initialize worker-isolate module state.

### Why an extension could not handle it

- `packages/coding-agent/src/bun/runtime-setup.ts` and `packages/coding-agent/src/bun/cli.ts` establish startup state before extensions run; static bundle membership belongs to the entry graph.

### Expected merge conflict zones

- `packages/coding-agent/src/bun/runtime-setup.ts` registration calls and `packages/coding-agent/src/bun/cli.ts` startup imports.

## 2026-09-12 - Clear the ask-user own-answer editor when advancing to the next question

### What changed

- `packages/coding-agent/src/modes/interactive/components/ask-user-question.ts`: `commitOwnAnswer()` clears `ownAnswerInput` after committing the typed text to the active question. Previously the editor kept the committed value, so the Enter path (commit + `advance()`) left focus in own-answer on the next question with the previous question's text still in the editor, and pressing Enter again committed that stale text as the next question's own answer (it also reached `onProgress` drafts through `emitProgress`).
- Revisiting a tab is unchanged: `openOwnAnswer()` still reloads the question's saved text from `AskUserQuestionState.textFor()`, so committed answers stay editable per question.
- `packages/coding-agent/test/suite/ask-user-question-component.test.ts`: regression coverage for the empty editor on the next question, no stale `onProgress` answer for the next question, and the saved answer reloading when the tab is revisited.

### Why

- With multi-question `ask-user` requests, answering a question with the own-answer editor prefilled the following question with the previous answer's text and submitted it as that question's custom answer when the user pressed Enter again — silently answering a question the user had not answered.

### Why an extension could not handle it

- The editor lifetime is owned by the fork's in-tree question overlay component; `AskUserQuestionState` deliberately stays free of pi-tui input state, so only the component can reset the editor.

### Expected merge conflict zones

- `commitOwnAnswer()` in `packages/coding-agent/src/modes/interactive/components/ask-user-question.ts` if upstream changes the own-answer commit/advance flow.

## 2026-09-12 - Support the Notification hook event and fire it for ask-user settlements

### What changed

- `packages/coding-agent/src/core/extensions/builtin/hooks/types.ts`: `Notification` moves from `UNSUPPORTED_KNOWN_HOOK_EVENTS` to `SUPPORTED_HOOK_EVENTS`, and `HookInputWire` gains a `Notification` variant carrying `message`, `kind`, optional `title`, `notification_source`, `request_id`, `status`, and `transcript_path`.
- `packages/coding-agent/src/core/extensions/builtin/hooks/matcher.ts`, `dispatcher.ts`, `output-parser.ts`, `lifecycle-adapter.ts`: `Notification` dispatches like the other non-blocking lifecycle events (matcher ignored, block-only aggregation, `additionalContext` accepted, decisions rejected with an `unsupported_field` diagnostic). New `buildNotificationHookInput` / `dispatchNotificationHookEvent` / `notificationResultDetails` helpers mirror the SessionStart path.
- `packages/coding-agent/src/core/extensions/builtin/ask-user/notify.ts`, `tool.ts`, and `resume.ts`: live and resumed non-cancelled settlements publish `ask-user:settled`. The active hooks builtin owns Notification execution (`kind` `ask-user-timeout` on timeout, `ask-user-settled` otherwise); disabling or excluding hooks prevents execution. Configuration and atomic trust snapshots are read asynchronously, and no Notification handlers means no trust I/O. Only validated hook `additionalContext` is recorded.
- `packages/coding-agent/test/suite/hooks-notification*.test.ts`: schema/output parsing, real trusted command dispatch with ignored matchers, disabled/excluded builtin activation through the resource loader, registered-tool blocking/async answers and authoritative fake-clock timeouts, late UI responses, cancellation, concurrent IDs, resume/reload exactly-once delivery, gated preparation/command completion, rejected-output recording, and typed persistent/in-memory payload fields.

### Why

- Question timeouts previously arrived only as framed user messages, so there was no hook surface for notifying on them (for example desktop or mobile push on `ask-user-timeout`).

### Why an extension could not handle it

- The supported hook wire event and authoritative ask-user settlement publication are owned by in-tree builtins. Extensions can observe the settlement event, but adding the Notification wire contract requires core changes.

### Expected merge conflict zones

- `SUPPORTED_HOOK_EVENTS` / `UNSUPPORTED_KNOWN_HOOK_EVENTS` in `hooks/types.ts` and any upstream change that adds a `Notification` event with different semantics.

## 2026-09-12 - Remove the client transcript/remote-session island, keep the dist `./client` export

### What changed

- `packages/coding-agent/src/client/transcript.ts`, `src/client/remote-session.ts`, and their tests are deleted (C14); upstream replaced that island with the source-only experimental client under `src/experimental/`.
- `packages/coding-agent/src/client/index.ts` stays a one-line barrel, and `packages/coding-agent/package.json` keeps the fork's dist-based `./client` export instead of upstream's `source`-conditioned entry, so `@code-yeongyu/senpi/client` keeps resolving for installed consumers.
- The 2026-08 block below that cites `src/client/transcript.ts` for an optional-chaining guard describes deleted code and stays as history.

### Why

- The transcript island duplicated what upstream now provides through Chord-routed services; carrying it would fork the RPC surface twice.

### Why an extension could not handle it

- Package exports and the client barrel are packaging contracts outside the extension API.

### Expected merge conflict zones

- `packages/coding-agent/package.json` `exports["./client"]` and `src/client/index.ts` whenever upstream touches the client entry.

## 2026-09-12 - Keep upstream's experimental server, client, and plugin sources source-only

### What changed

- `packages/coding-agent/src/experimental/cli.ts`, `src/experimental/commands.ts`, `src/experimental/server.ts`, `src/experimental/client.ts`, `src/experimental/client-runtime.ts`, `src/experimental/plugin.ts`, and the rest of `src/experimental/` arrive from upstream unchanged and are reachable only through `pi-test.sh` in a checkout (`Q-C=source-only`).
- They are not exported from the published `@code-yeongyu/senpi` package, are not bundled into standalone binaries, and no fork runtime module imports them. `src/experimental/server.ts` still reads `PI_SERVER_DIR`/`PI_SERVER_ID` and defaults to `~/.pi/server`; that upstream naming is intentional for the source-only tree and is not part of the `SENPI_*` environment contract.
- Unlike upstream, `@earendil-works/pi-client` and `@earendil-works/pi-protocol` stay runtime dependencies of `@code-yeongyu/senpi`, and the `./client` entry point stays published.

### Why

- Upstream moved its remote-harness experiment behind a `source` export condition after 0.85.0 shipped it by accident. The fork wants the sources present so future syncs merge cleanly, without widening the supported CLI surface or the tarball.

### Why an extension could not handle it

- Package export conditions, bundle inputs, and CLI entry wiring are build and packaging contracts; an extension cannot decide what the tarball contains.

### Expected merge conflict zones

- `packages/coding-agent/package.json` `exports` (fork keeps `./client`; upstream gates `client` behind `source`), `scripts/build-coding-agent-bundle.mjs` inputs, `pi-test.sh`, and any upstream change that starts importing `src/experimental/` from `src/main.ts` or `src/cli.ts`.

## 2026-09-11 - Support brand-owned changelog sources (senpi#1583)

### What changed

- `packages/coding-agent/src/core/brand.ts`: accepts an optional absolute `changelog.path` and authored `changelog.version` in the brand profile.
- `packages/coding-agent/src/core/settings-manager.ts`: stores changelog-seen versions per source while preserving the legacy engine version fallback.
- `packages/coding-agent/src/core/extensions/builtin/config-reload/routine-settings.ts`: treats `changelogSeen` as routine settings during reload filtering.

### Why

- Branded distributions need to show and acknowledge their own changelog without confusing their release history with the engine's changelog.

### Why an extension could not handle it

- Brand profile parsing, persistent settings, and reload bookkeeping are core startup and configuration contracts that run before extensions can provide equivalent behavior.

### Expected merge conflict zones

- LOW: brand profile parsing, changelog settings accessors, and the config-reload routine settings key list.

## 2026-09-11 - Make file reload detection independent of mtime granularity

### What changed

- `src/core/auth-storage.ts` now compares SHA-256 file-content revisions when deciding whether a shared auth snapshot is current.
- `src/utils/paths.ts` owns the shared SHA-256 file-content revision helper used by the reload and settings caches.
- Cursor CLI OAuth and Claude SDK OAuth settings caches use the same content revision helper instead of `mtimeMs:size`.

### Why

- Linux can retain one mtime for rapid rewrites, so mtime-based cache keys returned stale credentials or provider settings.

### Why an extension could not handle it

- Auth reload state is core-owned; provider settings cache invalidation is owned by the provider loaders.

### Expected merge conflict zones

- LOW: `core/auth-storage.ts`, `utils/paths.ts`, and provider `settings.ts` cache keys.

## 2026-09-10 - Restrict GPT-6 Astra high-reasoning warning to max

### What changed

- `packages/coding-agent/src/core/high-reasoning-warning.ts`: GPT-6 Astra now emits
  the high-reasoning warning only at `max`; GPT-5.6 Sol retains its `xhigh`/`max`
  warning behavior.
- `packages/coding-agent/test/high-reasoning-warning.test.ts`: added coverage for
  Astra variants at both reasoning levels.

### Why

- Astra's warning policy is specific to its highest reasoning level, so showing it
  at `xhigh` was overly broad.

### Why an extension could not handle it

- The warning predicate is core session policy evaluated before warning events are
  emitted.

### Expected merge conflict zones

- LOW: the high-reasoning warning predicate and its focused test.

## 2026-09-10 - Print mode binds editAssistantMessage for extensions

### What changed

- `packages/coding-agent/src/modes/print-mode.ts`: the extension `commandContextActions` gain `editAssistantMessage`, delegating to `session.editAssistantMessage` with `summarize` / `customInstructions` / `expectedLeafId`, beside the existing `navigateTree` binding.

### Why

- `ExtensionCommandContextActions.editAssistantMessage` is required, so every mode that binds command actions must provide it; print mode is one of the three binding sites.

### Why an extension could not handle it

- The actions object is built by the mode before extensions run.

### Expected merge conflict zones

- LOW: the `navigateTree` neighbour inside `commandContextActions` in `print-mode.ts`.

## 2026-09-10 - Render Anthropic tool_search results instead of raw JSON

### What changed

- `packages/coding-agent/src/modes/provider-native-rendering.ts` formats the `tool_search_tool_result` provider-native
  block: the summary reads `<provider> tool_search results` and the body lists the discovered `tool_name` values
  (capped at ten when collapsed), or the `error_code`/`error_message` of a `tool_search_tool_result_error`.

### Why

- Native Anthropic tool search is injected by the shared tool-search builtin, so its result block reaches every user
  whose catalog has inactive extension tools. Without a formatter the block fell through to the generic provider-native
  fallback and printed the whole payload as pretty JSON in the transcript.

### Why an extension could not handle it

- Provider-native block rendering happens in the assistant-message renderer that the interactive mode and print mode
  share; extensions cannot supply a formatter for a native block subtype.

### Expected merge conflict zones

- LOW: `packages/coding-agent/src/modes/provider-native-rendering.ts` if upstream adds its own provider-native
  formatter next to the existing web-search cases.

## 2026-09-10 - Fall back to the running install when PACKAGE_DIR ships no assets

### What changed

- `packages/coding-agent/src/config.ts` resolves `getThemesDir()` and `getExportTemplateDir()` through one
  layout-aware helper that probes the preferred root for a marker file (`dark.json` / `template.html`) and falls back
  to the running install's own asset tree when the `PACKAGE_DIR`-derived root does not ship it. A valid relocation
  still wins, and a genuinely broken install still returns the preferred path so the resulting error names it.

### Why

- `PACKAGE_DIR` is consumed by `getPackageDir()` before any layout decision, so an inherited root belonging to a
  DIFFERENT install silently produced an asset path that cannot exist. A Bun binary that embeds this CLI pins the
  variable to its own root and ships themes in a flat `theme/`; a Node install inheriting that root resolved
  `<root>/dist/modes/interactive/theme/dark.json` and died in `initTheme()` before the session started.

### Why an extension could not handle it

- Asset-root resolution runs inside `config.ts` during startup, before extensions load, and `theme.ts` reads the
  returned directory synchronously while building the builtin theme table.

### Expected merge conflict zones

- MEDIUM: `packages/coding-agent/src/config.ts` around `getThemesDir()` / `getExportTemplateDir()` if upstream edits
  either resolver; the shared `ShippedAsset` descriptors and `resolveShippedAssetDir()` are fork-owned.

## 2026-09-09 - Forward shared-host policy to extension loading

### What changed

- `packages/coding-agent/src/main.ts` supplies the shared-host policy when constructing CLI runtime resources.

### Why

- `packages/coding-agent/src/main.ts` knows the application mode and branded environment used by the shared-host decision.

### Why an extension could not handle it

- `packages/coding-agent/src/main.ts` owns CLI mode selection and runtime service creation before extension factories execute.

### Expected merge conflict zones

- `packages/coding-agent/src/main.ts`: `createCliRuntimeFactory` resource-loader configuration.

## 2026-09-09 - Upgrade generate_image to GPT Image 2.5

### What changed

- `packages/coding-agent/src/core/extensions/builtin/imagegen/tool.ts` now defaults to GPT Image 2.5 Sunburst, offers Flare and legacy GPT Image 2, accepts xhigh/max quality and validated custom sizes, and forwards local reference images to the existing pi-ai edits route.
- Schema/results and reference-file validation move into focused `imagegen/params.ts` and `imagegen/reference-images.ts` modules. The bundled skill documents model/tier choices, size constraints, and reference-image editing while retaining prompt-crafting guidance.

### Why

- The fixed GPT Image 2 text-only surface could not expose the newly released GPT Image 2.5 capabilities.

### Why an extension could not handle it

- The change is implemented entirely in the owning imagegen builtin extension and its guide, not session core. Its credential gate, native-tool arbitration, and PNG output behavior remain intact.

### Expected merge conflict zones

- MEDIUM: `packages/coding-agent/src/core/extensions/builtin/imagegen/tool.ts` execution and schema extraction; see the imagegen-local tracker for details.
- LOW: the two new imagegen modules, skill guide, and focused tool regression tests.

## 2026-09-09 - Export the compact read classifier API

### What changed

- `packages/coding-agent/src/index.ts`: re-exports `CompactReadClassification`, `ReadClassifier`, `registerReadClassifier`, and `classifyRead` from the shared read-classifier module alongside the core tool exports.

### Why

- `packages/coding-agent/src/index.ts` makes the classifier contract available to extensions and SDK consumers through the public package entry point, sharing the same registry used by the read renderer.

### Why an extension could not handle it

- `packages/coding-agent/src/index.ts` is the package's public export surface. An extension cannot expose host-owned types and functions from that entry point without a core export change.

### Expected merge conflict zones

- LOW: the core tool export block in `packages/coding-agent/src/index.ts`, immediately after the exports from `core/tools/index.ts`.

## 2026-09-08 - Construct shared RPC runtimes inside session workers

### What changed

- `packages/coding-agent/src/main.ts` extracts `createCliRuntimeFactory` with cloneable CLI configuration and isolate-local extension/UI construction. Shared mode dispatches before creating any default SessionManager and passes worker configuration to the host. Inline extension factories are rejected in shared mode rather than crossing IPC.

### Why

- The shared host must remain responsive while a session's filesystem access or JavaScript execution blocks its worker; eagerly constructing a default session or closing over main-thread runtime objects defeats that boundary.

### Why an extension could not handle it

- CLI dispatch and runtime construction in `packages/coding-agent/src/main.ts` precede extension execution and own the shared-host boundary.

### Expected merge conflict zones

- MEDIUM: `packages/coding-agent/src/main.ts` runtime resolver and mode dispatch. Classic runtime selection uses the extracted resolver unchanged.

## 2026-09-07 - Add the memory Aha-moment tip

### What changed

- `packages/coding-agent/src/modes/interactive/tips/catalog/memory-tips.ts` gains `memory.aha-moment`, gated on the `memory` command like its siblings: memory can surface a stored fact on its own as an `Aha moment!` line when it would change the next step, and silence means nothing relevant was found.

### Why

- The memorian recall notice (omo-senpi `memorian-notice.ts`, oh-my-openagent #7906) had no tip in the rotation, so the one memory feature that acts without a command was the only one never explained.

### Why an extension could not handle it

- The tip catalog is a core interactive-mode registry with no extension registration surface.

### Expected merge conflict zones

- LOW: the tail of `MEMORY_TIPS` in `memory-tips.ts` and `test/suite/list-tips.test.ts`.

## 2026-09-06 - Preserve inline skill anchors in composed prompts

### What changed

- `packages/coding-agent/src/core/agent-session.ts` preserves known inline `$skill:name` references as readable `[skill: name]` anchors when composing the expanded user request.

### Why

- Inline skill expansion previously removed the token entirely, leaving a sentence hole and losing the user's explicit reference in the composed prompt.

### Why an extension could not handle it

- Skill invocation token removal and prompt composition are core `AgentSession` behavior below the extension API.

### Expected merge conflict zones

- LOW: `removeSkillInvocationTokens` in `packages/coding-agent/src/core/agent-session.ts`.

## 2026-09-05 - Ctrl+P skips favorites without context room

### What changed

- `packages/coding-agent/src/core/agent-session.ts` uses the existing model
  usability projection before favorite cycling, emits `model_change_skipped`
  events for rejected candidates, and reports all-skipped cycles explicitly.

### Why

- Ctrl+P is an explicit switch request. A model that cannot admit the current
  context must be skipped instead of reaching the later usability assertion and
  surfacing a failed switch.

### Why an extension could not handle it

- Favorite cycling and the session event stream are core runtime seams below the
  extension API.

### Expected merge conflict zones

- LOW: `packages/coding-agent/src/core/agent-session.ts` model event types and
  favorite cycling.

## 2026-09-04 - Export the UI prompt events and apply terminal overrides in main

### What changed

- `packages/coding-agent/src/index.ts`: re-exports `UIPromptStartEvent`, `UIPromptEndEvent`, and `UIPromptKind` so embedders can subscribe to the new extension prompt lifecycle events.
- `packages/coding-agent/src/main.ts`: `main()` applies the settings manager's terminal capability overrides before HTTP proxy and dispatcher configuration, so non-interactive and RPC launches honor explicit capability settings too.

### Why

- Both are public surface wiring from the v0.84.4 sync: the prompt events are unusable by embedders unless exported from the package root, and capability overrides must be in place before any rendering or transport setup reads detected capabilities.

### Why an extension could not handle it

- Package export lists are compile-time surface, and `main()`'s startup ordering runs before extensions load.

### Expected merge conflict zones

- LOW: `packages/coding-agent/src/index.ts` export list; MEDIUM: `packages/coding-agent/src/main.ts` startup ordering around services initialization.

## Branded build labels render verbatim in startup UI (2026-09-04)

### What changed

- `packages/coding-agent/src/modes/interactive/version-label.ts` (new): `formatDisplayVersion` prefixes `v` only when the version string starts with a digit, so release semver/CalVer keep the `v` while branded build labels pass through verbatim.
- `packages/coding-agent/src/modes/interactive/grok/welcome-card.ts`: both welcome card render sites use the same helper.
- `packages/coding-agent/src/utils/version-check.ts`: `isNewerPackageVersion` returns `false` for version pairs it cannot order instead of falling back to string inequality.

### Why

- Branded distributions inject free-form `SENPI_BRAND.displayVersion` labels such as `omo@c6e7dd7 2026-09-04 10:17 +09:00`. The hardcoded `v` prefix rendered `OmO vomo@c6e7dd7 …`, and the string-inequality fallback advertised a bogus engine update on every branded startup.

### Why an extension could not handle it

- These are the engine's own startup chrome and update comparison. A branded repackage only injects the label string; it cannot alter render sites or comparison semantics inside the engine.

### Expected merge conflict zones

- LOW: the logo line in `packages/coding-agent/src/modes/interactive/interactive-mode.ts` and the two template literals in `packages/coding-agent/src/modes/interactive/grok/welcome-card.ts`.

## 2026-09-03 - Announce print-mode model fallback on stderr

### What changed

- `packages/coding-agent/src/modes/print-mode.ts` writes one stderr line when `retry_fallback_applied`, `retry_fallback_exhausted`, or `retry_fallback_reverted` fires, in both text and json print modes, without changing JSON stdout.

### Why

- `senpi -p` answered on a fallback model with no human-visible notice, so users could treat the wrong model's output as the requested model's. JSON mode already streamed `retry_fallback_applied` on stdout; stderr is the channel that does not corrupt that stream.

### Why an extension could not handle it

- Print mode owns the `-p` / `--mode json` I/O path and is the only subscriber that can write stderr without going through the interactive TUI. Retry fallback already emits session events; the hole is print-mode rendering, not the controller.

### Expected merge conflict zones

- LOW: the `session.subscribe` callback in `packages/coding-agent/src/modes/print-mode.ts`.

## 2026-09-02 - Export the RPC open-in-flight client error

### What changed

- `packages/coding-agent/src/index.ts` and `packages/coding-agent/src/modes/index.ts` re-export `RpcClientOpenInFlightError` beside `RpcClient` and `RpcTransportGoneError` so embedders can classify a rejected concurrent `open_session`.

### Why

- `RpcClient` now holds exactly one lease and rejects a second `openSession()` while one is in flight (`code: "open_session_in_flight"`); the public client surface needs the typed error to distinguish that programming error from transport loss.

### Why an extension could not handle it

- The client lease and its pending-open buffering live in the RPC transport layer below the extension API.

### Expected merge conflict zones

- LOW: the export lists in `index.ts` and `modes/index.ts`.

## 2026-09-01 - Negotiate RPC session auto-titling

### What changed

- `packages/coding-agent/src/main.ts` enables RPC session auto-titling when the client advertises `auto_title_sessions`, while preserving the context-message guard and default behavior for clients without the capability.
- `packages/coding-agent/src/modes/rpc/connection-handler.ts`, `packages/coding-agent/src/modes/rpc/custom-capability.ts`, and `packages/coding-agent/src/modes/rpc/session-command-router.ts` define and advertise the capability in both RPC protocol surfaces.

### Why

- RPC clients that support native session titles need the engine to generate titles and forward the existing `session_info_changed` event without changing the default wire contract.

### Why an extension could not handle it

- The auto-title decision is made while the entrypoint constructs each `AgentSession`, before extension code loads.

### Expected merge conflict zones

- LOW: the `resolveAutoTitleSessions` helper and `autoTitleSessions` option in `main.ts`, plus RPC capability declarations and protocol responses.

## 2026-08-30 - Export the RPC transport-gone classifier

### What changed

- `index.ts` and `modes/index.ts` re-export `RpcTransportGoneError` and `isTransportGoneError` beside `RpcClient` so embedders can classify shared-host transport loss.

### Why

- The reconnect-or-fallback orchestration rejects sends with the typed error; consumers of the public client surface need the classifier to distinguish transport loss from real failures.

### Why an extension could not handle it

- Package export surfaces are compile-time module structure; extensions cannot add public exports.

### Expected merge conflict zones

- LOW: export lists in `index.ts` and `modes/index.ts`.

## 2026-08-30 - Dispatch the internal RPC host route through wrapper-injected argv

### What changed

- `packages/coding-agent/src/main.ts` matches the hidden `--internal-rpc-host-supervisor` route through `findInternalSupervisorArgs()` instead of a strict `args[0]` comparison, and still fails closed with `exit(2)` when the payload does not parse.

### Why

- A rebranded wrapper re-dispatches this binary through its own entry and prepends `--extension <dir>` for every non-early command, which pushed the sentinel off `args[0]`. The internal route then never fired and the spawned helper died on `--socket`, so compiled wrapper builds could never start the shared host.

### Why an extension could not handle it

- The dispatch happens in the CLI entry before argument parsing and before any extension host exists, so no extension hook can observe or rewrite it.

### Expected merge conflict zones

- LOW: the internal-route dispatch block near the top of `main()`.


## Measure Cursor tool-result history at the wire representation (2026-08-29)

### What changed

- `packages/coding-agent/src/core/agent-session.ts` admits Cursor context using the actual serialized history bytes, accounting for tool names, call IDs, MIME types, arguments, and framing instead of a fixed envelope estimate. Oldest result bodies are emptied first, with complete oldest turns removed only when metadata alone exceeds the bound.
- `packages/ai/src/api/cursor-agent.ts` exposes the shared serialized-history measurement used by the admission transform.

### Why

- Cursor history must stay at or below 50,000 serialized bytes without evicting results from histories that genuinely fit.

### Why an extension could not handle it

- Admission occurs in the core Cursor context transform before provider execution.

### Expected merge conflict zones

- LOW: Cursor admission constants and `truncateToolResultBodies()` in `agent-session.ts`.

## 2026-08-29 - Propagate shared-host bash callback failures

### What changed

- `packages/coding-agent/src/core/agent-session.ts` observes asynchronous bash output callbacks and preserves callback failures through cleanup.
- `packages/coding-agent/src/modes/interactive/interactive-host-runtime.ts` aborts shared-host commands when callbacks reject and rethrows the original value.

### Why

- Public shared-host bash execution could resolve successfully after an asynchronous callback rejection and leave large-output spill files behind.

### Why an extension could not handle it

- Core session and RPC proxy callback dispatch occurs before extension code can finalize execution cleanup.

### Expected merge conflict zones

- LOW: bash callback dispatch in the core session and interactive host runtime.

## Honor --auto-title-sessions outside interactive mode (2026-08-28)

### What changed

- `packages/coding-agent/src/main.ts` resolves session auto-titling through the exported `resolveAutoTitleSessions(appMode, parsed, hasContextMessages)` helper: interactive launches keep titling by default, any app mode opts in with `--auto-title-sessions`, and sessions resumed with context messages are still never retitled. Because the shared `createRuntime` closure is also what the multi-session RPC host calls through `RpcSessionRegistry.openSession`, both the classic and multi-session RPC paths honor the flag without extra plumbing.

### Why

- RPC clients (the desktop app spawns `--mode rpc --multi-session`) never received generated session titles even though `setSessionName()` already emits `session_info_changed` and the RPC connection handler already forwards it.

### Why an extension could not handle it

- The auto-title decision is made while the entrypoint constructs the first `AgentSession`, before extensions load.

### Expected merge conflict zones

- LOW: the `autoTitleSessions` argument in the `createAgentSessionFromServices` call and the helper beside `toProjectTrustMode`.

## Credential accounts in auth check --json (2026-08-27)

### What changed

- `packages/coding-agent/src/main.ts`: `auth check --json` output gains a non-secret `accounts` array (name/source/blocked/pinned) for the checked provider, sourced from `core/credential-accounts.ts`; enrichment failures never turn a readable auth state into an error, and non-JSON output is unchanged.

### Why

- Scripts consuming `auth check --json` need visibility into a provider's credential pool without parsing auth.json themselves.

### Why an extension could not handle it

- The auth-check CLI output is composed in the entrypoint's command handling, which extensions cannot alter.

### Expected merge conflict zones

- LOW: one enrichment block in the auth-check branch.

## 2026-08-25 - Keep JSON startup logging off stdout

### What changed

- `packages/coding-agent/src/main.ts` takes over stdout for JSON `--help` and redirects `console.log` to stderr for the lifetime of JSON-mode execution, restoring the original logger on process exit.

### Why

- Machine-readable JSON output must remain clean while startup diagnostics and trusted chatter continue to be visible on stderr.

### Why an extension could not handle it

- CLI mode selection and stdout ownership happen before extensions load and are process-wide runtime behavior.

### Expected merge conflict zones

- LOW: JSON-mode startup setup around `resolveAppMode()` and stdout takeover.

## Coding-agent entry surfaces re-diverge from upstream dcd4619 (2026-08-25)

### What changed

- `packages/coding-agent/src/config.ts` keeps the bun global-launcher repair command, brand-profile
  and `envValue` plumbing, nearest-parent config discovery, and multi-step self-update commands.
- `packages/coding-agent/src/index.ts` keeps the fork public surface: `sanitizeTerminalLabel`,
  `OAuthCredential`, `CacheFriendlySummaryOptions`, the filesystem-policy and extension-RPC contract types, and notice primitives.
- `packages/coding-agent/src/migrations.ts` keeps the fork migration chain (brand-dir,
  extension-system, legacy-senpi dirs) in place of upstream's commands-to-prompts migration.
- `packages/coding-agent/src/package-manager-cli.ts` keeps senpi-branded update help text and the
  removable `omo-local-update` beta hook.
- `packages/coding-agent/src/main.ts` keeps the fork stdout contract for JSON mode: stdout takeover
  also applies to `--help` in JSON mode, and `console.log` is redirected to stderr for the process
  lifetime so machine-readable stdout stays clean of stray logging.

### Why

These are fork-owned product surfaces (senpi branding, provider wire behavior, fork runtime features) that the new upstream tree does not carry; the sync must re-assert them on top of upstream's tree.

### Why this lives in the fork

The divergence lives in core wiring, package identity, or build plumbing that executes before any extension loads, so no extension hook can express it.

### Expected merge conflict zones

- Export lists in `packages/coding-agent/src/index.ts`, the migration registry in
  `packages/coding-agent/src/migrations.ts`, and update-help templates in
  `packages/coding-agent/src/package-manager-cli.ts`.

## Preserve zero-usage context estimation for auto-compaction (2026-08-25)

### What changed

- `packages/coding-agent/src/core/agent-session.ts`: allow the fork-owned estimated context size to drive threshold compaction even when no prior assistant usage index exists.

### Why

- The fork's zero-usage regression guard depends on message estimation; upstream's no-usage early return silently disables compaction for malformed or provider-zero usage responses.

### Why an extension could not handle it

- Automatic compaction admission is internal session state evaluated before extension compaction hooks run.

### Expected merge conflict zones

- HIGH: `_checkCompaction` threshold accounting and fork compaction safeguards.

## Restore fork settings paths and interactive startup seams after upstream merge (2026-08-25)

### What changed

- `packages/coding-agent/src/core/settings-manager.ts`: preserve fork `.senpi` settings discovery while adopting upstream BOM-tolerant parsing and path-bearing diagnostics.
- `packages/coding-agent/src/modes/interactive/interactive-mode.ts`: retain the fork's testable tmux-keyboard startup seam while adopting the upstream startup warning flow.

### Why

- The fork's branded config directory and interactive startup contracts are production behavior; allowing upstream `.pi` assumptions or an unmocked method call breaks settings persistence and startup diagnostics.

### Why an extension could not handle it

- Settings source selection and interactive startup dispatch run before extensions are loaded.

### Expected merge conflict zones

- HIGH: settings source resolution, error reporting, and interactive startup checks.

## Preserve highlight.js package export compatibility after upstream merge (2026-08-25)

### What changed

- `packages/coding-agent/src/utils/syntax-highlight.ts`: use highlight.js package-export subpaths compatible with the fork's pinned 11.12.0 release, including the root package for lazy grammar loading.

### Why

- Upstream's source import suffixes are not exported by highlight.js 11.12.0 under Node and Vite, preventing child-process startup and causing the test prerequisite to fail.

### Why an extension could not handle it

- Syntax-highlighter module resolution happens during CLI and TUI module loading, before extensions are initialized.

### Expected merge conflict zones

- MEDIUM: highlight.js imports and deferred grammar loading in the syntax-highlighting utility.

## 2026-08-25 - brand executable name for shell-command contexts

### What changed

- `packages/coding-agent/src/config.ts`: exports `APP_COMMAND` from `BRAND?.command`, falling back to `APP_NAME`, so shell-command strings can use the real binary when it differs from the display name.

### Why

- A brand can present as `OmO` while the installed executable is `omo`. Resume hints and other copy-paste commands must name the binary the shell can run.

### Why an extension could not handle it

- Brand identity constants are resolved at module load, before the extension loader exists; every later command-line interpolation reads these exports.

### Expected merge conflict zones

- LOW: `packages/coding-agent/src/config.ts` identity constants next to `APP_NAME`.

## 2026-08-25 - Lazy-load the interactive mode at the CLI mode seam

### What changed

- `packages/coding-agent/src/main.ts`: RPC and print mode imports remain eager, while `InteractiveMode` is loaded dynamically only after the final mode is known to be interactive.

### Why

- RPC children are headless and never construct the interactive TUI. Keeping the interactive mode import in the shared static mode barrel made the full component tree parse during RPC startup. The dynamic boundary removes that interactive-only work from the RPC boot path while preserving the same interactive import immediately before its first use.

### Why an extension could not handle it

- Mode selection and entry-module loading happen before extensions are loaded; only the CLI coordinator can keep an unused mode graph out of the RPC child entry.

### Expected merge conflict zones

- LOW: `packages/coding-agent/src/main.ts` mode imports and the final interactive dispatch branch.
## Export client-side RPC socket host ensuring (2026-08-24)

### What changed

- `packages/coding-agent/src/index.ts` and `packages/coding-agent/src/modes/index.ts` export `ensureHost`, its state-path helper, result/options types, and the pinned shared-host capability profile.

### Why

- Desktop and other package consumers need to auto-start or reuse the compatible shared RPC socket host through a supported library API.

### Why an extension could not handle it

- The package entry point owns the supported programmatic API before any session or extension runtime exists.

### Expected merge conflict zones

- LOW: additive RPC exports in the two index modules.

## Route RPC listen addresses into the shared multi-session host (2026-08-23)

### What changed

- `packages/coding-agent/src/main.ts` forwards the parsed RPC `--listen` address to `runMultiSessionHost` while preserving the existing no-default-runtime startup branch.

### Why

- The Unix-socket transport must own one process-global multi-session host rather than constructing the classic single-session runtime before binding.

### Why an extension could not handle it

- Main-mode dispatch and pre-runtime host selection happen before session extensions exist.

### Expected merge conflict zones

- LOW: the existing multi-session dispatch object in `main.ts`.


## 2026-08-22 - emit agent_idle after settlement-deferred turns resolve

### What changed

- `packages/coding-agent/src/core/agent-settled-delivery.ts`: added `DeferredTurnClaim` / `DeferredTurnDisposition` (`started` / `delegated` / `finished-without-start`) and `deferTriggerTurn`, so a settlement-deferred `sendMessage(..., { triggerTurn: true })` declares whether it actually started a run. Claims resolve at the `_promptAgent` admission boundary.
- `packages/coding-agent/src/core/agent-session.ts`: after the deferred-action loop in `_emitAgentSettled`, an out-of-band check waits for all deferred turn dispositions, skips emission when any turn `started`, waits for delegated session work to drain, verifies the settlement epoch is still current, and emits `{ type: "agent_idle" }` only when no agent run or session work is active. Both settlement-deferred turn APIs register a claim: `sendMessage(..., { triggerTurn: true })` via `deferTriggerTurn`, and `sendUserMessage` (which always triggers a turn) via a claim resolved from its prompt disposition. `agent_settled` ordering is unchanged for existing subscribers.

### Why

- The TUI cleared its working-status dock on the public `agent_settled`, but settlement-deferred continuations (TTSR, loop-guard, goal recovery) start a turn *after* that event, so the dock was removed and immediately remounted - the same vertical bounce the jitter fix exists to eliminate. `_isAgentRunActive` alone cannot decide this at the deferred-action loop because a deferred `sendCustomMessage` can be suspended at compaction/provider admission before reaching `_promptAgent`. `agent_idle` is the single race-free boundary for final cleanup.

### Why an extension could not handle it

- Settlement-deferred turn admission and the settlement epoch are private `AgentSession` / `AgentSettledDelivery` state.

### Expected merge conflict zones

- `packages/coding-agent/src/core/agent-session.ts` `_emitAgentSettled`, `_promptAgent`, and the `AgentEvent` union.
- `packages/coding-agent/src/core/agent-settled-delivery.ts`.

## 2026-08-22 - Bun-installed CLIs re-exec onto the Bun runtime

### What changed

- `packages/coding-agent/src/cli.ts` now runs a runtime check as its first statement, before `enableStartupCompileCache()`: it realpaths `process.argv[1]`, asks the fork-only `packages/coding-agent/src/bun-runtime.ts` decision function whether this process should run under Bun, and on a positive decision `spawnSync`s the installed `bun` binary with the same script and arguments, propagates the child's signal or exit status, and exits without loading the rest of the entry flow.

### Why

- `bun install -g` links the CLI into `~/.bun/bin`, but the shebang still selects Node, so users who installed with Bun silently ran on the Node runtime. The check has to precede compile-cache setup so a re-exec never pays for Node-only startup work, and it honors `SENPI_RUNTIME=node`/`bun`, keeps debugger runs on Node, and never re-execs when `process.versions.bun` is already set.

### Why an extension could not handle it

- Runtime selection happens before any extension, session, or engine module is loaded; by the time an extension could run, the process is already committed to its interpreter.

### Expected merge conflict zones

- LOW: the import block and the first statements of `packages/coding-agent/src/cli.ts`, immediately above the existing `enableStartupCompileCache()` call.

## 2026-08-20 - Cursor 0-token RE stays on the same model and shrinks

### What changed

- `packages/coding-agent/src/core/agent-session.ts`: 0-token Cursor `resource_exhausted` retries with `sameModelRemint` instead of 429/k3 fallback; overflow compact uses Cursor keep-recent-0 settings; too-small compact truncates to the last user turn.

### Why

- `resource.?exhausted` was classified as a 429 transient fallback, and overflow compact that saved <1% still retried the same Cursor payload.

### Why an extension could not handle it

- Retry fallback and pre-prompt compaction are core AgentSession admission paths.

### Expected merge conflict zones

- `packages/coding-agent/src/core/agent-session.ts` `_handleRetryableError`, `_executeCompaction`, `_isHardErrorFallbackEligible`.

## Public notice renderer primitives (2026-08-20)

### What changed

- `packages/coding-agent/src/index.ts` now exports `buildNoticeBox`, `noticeMessageRenderer`, `noticeEntryRenderer`, and the `NoticeSpec`, `NoticeLine`, and `NoticeTone` types.

### Why

- Extensions and package consumers need the same notice-card contract as built-in transcript surfaces instead of recreating its background, title, and detail styling.

### Why an extension could not handle it

- The package entry point owns the supported public API; an extension cannot export additional symbols from it.

### Expected merge conflict zones

- LOW: the notice export block in `packages/coding-agent/src/index.ts`.

## 2026-08-19 - Session title uses session-model auth

### What changed

- `_generateSessionTitle` now calls `_getSummarizationRequestAuth(model)` instead of `_getCompactionRequestAuth(model)`.

### Why

- Compaction auth can be remapped to another provider (see #974). Title generation still streams with the **session** model, so a remapped key produces `session_title_generation` `unauthenticated` on Cursor while the main turn works.

### Why an extension could not handle it

- Title generation is private session lifecycle. There is no extension hook for the title complete auth.

### Conflict zone

- `packages/coding-agent/src/core/agent-session.ts` `_generateSessionTitle`.

## 2026-08-19 - Skip Cursor compaction while a Run is live

### What changed

- `compactBeforeNextAdmission` no-ops for `cursor` / `cursor-cli-oauth`.
- Blocking and generated compaction refuse those providers while `!ctx.isIdle()`.

### Why

- Cursor rebuilds full conversation state each hop. Mid-turn compact desyncs `conversationId` and the next hop returns 0-token `resource_exhausted` (session 01a01879).

### Conflict zone

- `packages/coding-agent/src/core/agent-session.ts` `compactBeforeNextAdmission`
- `packages/coding-agent/src/core/extensions/builtin/compaction/index.ts` `applyBlockingCompaction`
- `packages/coding-agent/src/core/extensions/builtin/compaction/speculative.ts` `applyGeneratedCompaction`

## 2026-08-19 - Ignore implausible Cursor usage for compaction threshold

### What changed

- `_resolveThresholdContextTokens` uses `resolveThresholdContextTokens`: if the local estimate is at least 50k and billed usage is more than 8× that estimate, compact against the estimate.

### Why

- Complements the billed-cacheRead guard. When no checkpoint arrived, a 4M `cacheRead` still must not beat a 149k transcript estimate.

### Conflict zone

- `packages/coding-agent/src/core/compaction/compaction.ts`
- `packages/coding-agent/src/core/agent-session.ts` `_resolveThresholdContextTokens`

## In-process CLI fast path when no isolation is required (2026-08-20)

### What changed

- `packages/coding-agent/src/cli.ts` no longer always re-spawns Node to run the agent. It now decides
  with `requiresIsolatedProcess()` — `process.execArgv.length > 0 || hasInheritedInspectorOption()`.
  When false (the overwhelmingly common launch), it loads the agent with a dynamic
  `await import("./cli-main.ts")` in the launcher process itself. When true, the previous child spawn
  is kept byte-for-byte, including `releaseInheritedInspectorForChild()`, `process.execArgv`
  forwarding, `stdio: "inherit"`, exit-code forwarding, and signal re-raise via
  `process.kill(process.pid, signal)`.
- The former `runFullCli()` is renamed `spawnFullCli()` and is now reached only on the isolation path;
  the fast path has no result to forward, because `cli-main` runs `main()` at module scope and already
  owns `process.exitCode` and any `process.exit()` of its own.
- `packages/coding-agent/src/inspector-policy.ts` exports the previously private
  `hasInheritedInspectorOption()` (unchanged logic: `--inspect*` in `process.execArgv`, or `--inspect`
  inside `NODE_OPTIONS`) so `cli.ts` decides with exactly the predicate that governs the existing
  Inspector handoff, rather than a second, drifting copy of it.
- Ordering with the compile cache (merged separately, same day) is preserved and is load-bearing:
  `enableStartupCompileCache()` still runs as the first statement, BEFORE the dynamic import, so on the
  fast path the dynamically imported engine graph is itself compile-cached in-process, and on the
  isolation path `NODE_COMPILE_CACHE` is still published for the child to inherit. The comment on that
  call now states both roles.
- The two documented reasons for the respawn were re-verified. Inspector socket handoff still requires
  a separate process and is preserved. Brand env isolation does NOT: `cli-main.ts` calls
  `scrubBrandFromEnvironment()` itself (`src/core/brand.ts`), so an in-process load scrubs this
  process's environment before anything the agent later spawns can inherit it.

### Why

- The respawn cost a full Node process launch plus a duplicated entry-module graph on every single
  launch, for isolation that almost no launch needs. Measured on this fork's built dist (Apple M4 Pro,
  node v26.7.0, hyperfine 15 runs, 3 warmup): `node dist/cli.js --help` 1.206 s ± 0.049 -> 1.131 s ±
  0.036 (-75 ms, -6.2%). The untouched control `dist/cli-main.js --help` is unchanged across the same
  pair of builds, and after the change `cli.js` is faster than `cli-main.js` itself — the launcher no
  longer pays for a second process. System CPU per launch drops 0.513 s -> 0.397 s (12-run
  `/usr/bin/time` means), which is where an eliminated spawn is expected to show up.

### Why an extension could not handle it

- This is the process structure of the entrypoint itself: the decision happens in `cli.ts` before any
  session, extension loader, or extension API exists, and it determines which process the extension
  loader will eventually run in.

### Expected merge conflict zones

- MEDIUM: `runFullCli()`/`spawnFullCli()` and the trailing dispatch in `packages/coding-agent/src/cli.ts`.
  Upstream owns this entrypoint and reshapes it periodically; a conflict here should be resolved by
  re-applying the `requiresIsolatedProcess()` branch around whatever spawn body upstream ends up with,
  keeping the spawn path unchanged.
- LOW: the `hasInheritedInspectorOption` export in `packages/coding-agent/src/inspector-policy.ts`
  (export keyword only; the function body is untouched).
- LOW: the `enableStartupCompileCache()` call comment in `cli.ts`, shared with the compile-cache entry
  below.

## Node module compile cache for CLI startup (2026-08-20)

### What changed

- `packages/coding-agent/src/compile-cache.ts` (new, fork-only): `enableStartupCompileCache()` enables
  Node's on-disk V8 module compile cache and publishes the resolved BASE cache directory into
  `process.env.NODE_COMPILE_CACHE` so child processes inherit the same cache. Node's programmatic
  `enableCompileCache()` does not export that variable itself, and the value published must be the base
  directory (not `getCompileCacheDir()`, which already contains Node's versioned segment — handing it
  back double-nests the child's cache and it misses every parent entry). The API is read off the
  `node:module` namespace rather than imported by name: a named import of a missing export is a
  link-time `SyntaxError` no runtime guard can catch, and the bun-compiled binary runs this file.
- `packages/coding-agent/src/cli.ts` calls it as the first statement after imports (after the existing
  `valid-cwd.ts` first-import guard): `cli.ts` spawns `cli-main` as a child, and that child loads the
  full engine graph, so inheritance is what makes the cache reach the process that pays the compile cost.
- `packages/coding-agent/src/cli-main.ts` calls it first as well, so direct `cli-main` invocations (the
  bun binary, tests) benefit when no launcher published a directory; when one did, the call keeps the
  existing value.
- Guards: never overrides a pre-set `NODE_COMPILE_CACHE`; `NODE_DISABLE_COMPILE_CACHE=1` stays honored
  (the call is skipped or Node reports failure and nothing is published); any failure degrades to plain
  compilation instead of failing startup.

### Why

- Cold profiling attributes roughly a quarter of CLI boot CPU to V8 compiling the ~800ms module graph;
- with the cache warm, repeated launches skip that compilation. Measured on this fork's built dist
  (Apple M4 Pro, node v26.7.0): `cli-main --help` user CPU -11% to -14%, net user+sys -3% (the cache
  read IO eats part of the compile saving; wall-clock gains appear on an otherwise idle machine).
- The first launch after enabling still compiles and writes the cache (cache population), so this is a
  warm-start optimization only.

### Why an extension could not handle it

- The cache must be enabled before the engine's module graph starts loading, and `NODE_COMPILE_CACHE`
  must be in the environment before `cli.ts` spawns the `cli-main` child — both happen in the
  entrypoints, before the extension loader exists.

### Expected merge conflict zones

- LOW: the first-statement call and its import in `cli.ts` and `cli-main.ts` (upstream may reshuffle
  entrypoint imports; the `valid-cwd.ts` first-import ordering is pinned by test and must stay first).
  `compile-cache.ts` is fork-only with no upstream counterpart.

## Entry surface and CLI coordinator re-diverge from upstream 59a71b23 (2026-08-19)

### What changed

- `packages/coding-agent/src/index.ts` keeps the fork's wider public surface after the sync to upstream
  `59a71b235dadb4ad0d67557a8abb0aaa093e68b4`: it re-exports `sanitizeTerminalLabel` from
  `@earendil-works/pi-tui`, the `OAuthCredential` type from `core/auth-storage.ts`, and the fork-only extension
  contracts `ExtensionRpcRequestHandler`, `FilesystemOperation`/`FilesystemPolicy`/`FilesystemPolicyChecker`/
  `FilesystemPolicyDecision`/`FilesystemPolicyRequest`, `InputDispositionEvent`, and `McpServerDeclaration`, plus
  the RPC client event types `RpcClientEvent` and `RpcExtensionEvent`.
- `packages/coding-agent/src/main.ts` keeps the fork startup coordinator on top of upstream's version: the
  `app-server` app mode and `handleAppServerCommand()` dispatch (with `toProjectTrustMode()` mapping it to the
  `print` trust mode), the `--multi-session` plain-RPC host (which pre-calls `initTheme()` because
  `runMultiSessionHost()` never returns), `--list-tips`, the codex-style startup loading indicator paused around
  project-trust prompts, `--grok-neo` chrome selection with the non-persistent `grok-night` theme fallback,
  branded `envValue("OFFLINE")`/`envValue("STARTUP_BENCHMARK")` reads and `DISPLAY_VERSION`, `--list-models`
  resolved from services before the runtime is built, auth-storage diagnostics drained per phase,
  `initialTitlePrompt`/auto-title wiring, `initialModelProvenance`/`thinkingSelection` propagation, the
  `promptConfirm()` stdin-EOF close handler, and the non-interactive fail-fast for cross-project session forks.

### Why

- These are fork product surfaces (app-server transport, multi-session RPC host, senpi branding and version
  display, grok chrome, tips, model provenance) that upstream does not ship; the merge with the new pin restores
  upstream's leaner entry point around them, so the files remain divergent by design after the pin advance.

### Why an extension could not handle it

- Both files run before any extension exists: `index.ts` is the module surface extensions import, and `main.ts`
  parses argv, resolves trust, and constructs the runtime that later loads extensions.

### Expected merge conflict zones

- MEDIUM: `main.ts` `main()` startup ordering (list-models/list-tips early exits, loading indicator, runtime
  factory) and `resolveAppMode()`/`createSessionManager()`; LOW: the alphabetized export blocks in `index.ts`.

## 2026-08-18 - Cursor reasoning-level startup wiring

### What changed

- `packages/coding-agent/src/main.ts`: startup carries the resolved thinking selection (CLI `--thinking`,
  `:suffix` model patterns, favorites, legacy cursor variant ids) into session state so the first turn's
  provider request encodes the user's actual choice.

### Why

- Cursor models encode reasoning on the wire; a defaulted level must not be mistaken for an explicit one.

### Why an extension could not handle it

- CLI argument resolution and initial session construction are core startup surfaces.

### Expected merge conflict zones

- `main.ts` model/thinking option resolution block.

## Repository audit baseline for the src tracker (2026-08-17)

### What changed

- This entry is the canonical inventory for the repository-wide changes.md audit (`scripts/audit-changes-md.mjs`, pin
  `914cf1472e715297caa30db4b9535d534a9eb718`, tag v0.84.2). It assigns every audited production path whose exact
  nearest tracker is this file, so the audit gate resolves each divergence even where the per-feature history below
  predates the gate. `packages/coding-agent/src/cli.ts` and `packages/coding-agent/src/main.ts` are already covered by
  dated entries below.
- Entrypoints: `packages/coding-agent/src/bun/cli.ts` (Bun-binary entry now loads the full bootstrap and registers the
  cursor-agent module), `packages/coding-agent/src/rpc-entry.ts` (RPC entry scrubs the brand environment and exports
  the branded `AI_AGENT` identity).
- Brand and config resolution: `packages/coding-agent/src/config.ts` — brand-profile consumption for identity constants,
  flat-layout agent-directory resolution with nearest-parent discovery, brand-scoped environment reads, and the Bun
  self-update launcher-repair step (own entry below).
- Startup migrations: `packages/coding-agent/src/migrations.ts` — brand engine-state copy-forward plus the fork
  extension-system and legacy-directory migrations replacing upstream's inline commands-to-prompts path (own entry
  below).
- Public surface: `packages/coding-agent/src/index.ts` re-exports the extension RPC handler, filesystem-policy,
  input-disposition, MCP-declaration, and RPC-client event types; `packages/coding-agent/src/modes/index.ts`
  re-exports `RpcClientEvent` and `RpcExtensionEvent`.
- Mode and client deltas: `packages/coding-agent/src/modes/print-mode.ts` (one-shot prompts pass
  `sessionTitlePrompt: false`, the final assistant message is selected with `findLast` so trailing non-assistant
  entries cannot mask it, provider-native content renders in text mode, and the run waits for settled session work
  before exiting), `packages/coding-agent/src/client/transcript.ts` (equivalent optional-chaining guard on transcript
  progress application), `packages/coding-agent/src/package-manager-cli.ts` (branded `update`/`list`/`config` help
  surface, brand update-channel redirect that defers to the parent package, and the removable omo-local-update beta
  worker flag).
- Local provider: `packages/coding-agent/src/extensions/llama/provider.ts` keeps sleeping llama.cpp runners
  discoverable (own entry below).

### Why

- The pre-backfill audit reported these paths uncovered: the entries that described them either predate the canonical
  four-section format or never named the exact path. This inventory closes that gap without rewriting the accurate
  per-feature history below.

### Why an extension could not handle it

- Tracker coverage is repository and release policy, not runtime behavior; it is enforced by repository scripts before
  any extension loader exists.

### Expected merge conflict zones

- NONE: this tracker file merges to `ours` on upstream sync; the inventory intentionally names pin-relative paths so
  it stays valid as entries below change.

## Brand profile, config-directory resolution, and engine-state migration (2026-08-17)

### What changed

- `packages/coding-agent/src/config.ts`: consumes a `BrandProfile` injected once per process — `APP_NAME`, `APP_TITLE`,
  and `CONFIG_DIR_NAME` resolve the brand ahead of the package's `piConfig` metadata, `DISPLAY_VERSION` separates the
  brand-facing version from the engine `VERSION` used for update comparisons, `CONFIG_FLAT_LAYOUT` marks brands that
  keep agent state directly under the config directory, and `ENV_PREFIX` builds `ENV_AGENT_DIR`/`ENV_SESSION_DIR`
  while legacy prefixes stay readable.
- `packages/coding-agent/src/config.ts`: environment reads go through brand-scoped `envValue()` (`PACKAGE_DIR`,
  `SHARE_VIEWER_URL`, `CODING_AGENT_DIR`) instead of raw `PI_*` literals; `resolveAgentDir()` adds nearest-parent
  config discovery with a flat-layout `settings.json` sentinel; Bun self-update composes a launcher-repair step and
  binary-download guidance points at the senpi releases page.
- `packages/coding-agent/src/migrations.ts`: `runMigrations()` runs `migrateEngineStateForBrand()` first — a
  copy-forward (never a move) of the engine's `~/.senpi/agent` state into a flat-layout brand directory, guarded by
  the `.migrated-from-senpi` marker and skipping regenerable entries — then the fork's `migrateLegacySenpiDirs()` and
  `migrateExtensionSystem()`, replacing upstream's inline commands-to-prompts and deprecated-directory checks that
  now live in `extension-system-migration.ts`.

### Why

- A rebranded distribution reads different config and state locations than the engine install it replaces; resolving
  them once keeps every downstream consumer brand-correct, and copying (not moving) engine state keeps a standalone
  engine install on the same machine intact.
- Environment prefixes and display versions are brand identity, not feature behavior, so they must not be hardcoded
  per call site.

### Why an extension could not handle it

- Config-path, brand, and environment resolution happen at module load and bootstrap, before the extension loader
  exists; startup migrations run once over directories extensions never see.

### Expected merge conflict zones

- HIGH: `packages/coding-agent/src/config.ts` identity constants and `resolveAgentDir()`.
- MEDIUM: `packages/coding-agent/src/migrations.ts` `runMigrations()` ordering; upstream may reshape its own
  command/prompt migrations.

## Split CLI bootstrap: thin launcher, full engine child, branded entries (2026-08-17)

### What changed

- `packages/coding-agent/src/cli.ts` is now a thin bootstrap: it imports the deleted-cwd guard first, answers
  `--version`/`-v` directly from `DISPLAY_VERSION` without loading the engine, detects package-manager subcommands,
  and when a package-manager install is missing its bundled workspace dependencies routes through the bootstrap
  self-update handler before spawning the full CLI as a child process with the parent's `execArgv`, propagating the
  child's exit signal.
- `packages/coding-agent/src/cli-main.ts` is the relocated full bootstrap (early inspector-import recovery, brand
  scrubbing, `PI_CODING_AGENT` marker, HTTP dispatcher configuration) that awaits `main()`.
- `packages/coding-agent/src/bun/cli.ts` registers Bun OAuth flows, restores the sandbox environment, registers the
  Bedrock and cursor-agent modules, then loads the full bootstrap instead of the thin launcher.
- `packages/coding-agent/src/rpc-entry.ts` keeps its dedicated RPC dispatch but now scrubs the brand environment and
  sets `AI_AGENT` to `APP_NAME` instead of the hardcoded engine name.

### Why

- A broken or half-updated global install must offer a self-repair path instead of dying on module resolution, and
  version or package-manager queries should not pay full engine startup. RPC host processes need their own process
  identity and a clean brand environment so nested engine runs keep the engine's identity.

### Why an extension could not handle it

- These are pre-runtime entrypoints: extensions load only after `main()` has bootstrapped settings and the resource
  loader, so no extension can restructure process spawning, environment scrubbing, or self-repair.

### Expected merge conflict zones

- HIGH: `packages/coding-agent/src/cli.ts` was substantially rewritten relative to upstream's direct `main()` call.
- MEDIUM: `packages/coding-agent/src/cli-main.ts` bootstrap ordering.
- LOW: the registration lines in `packages/coding-agent/src/bun/cli.ts` and the identity lines in
  `packages/coding-agent/src/rpc-entry.ts`.

## Deleted-cwd bootstrap guard (2026-08-17)

### What changed

- New fork-only first-import guard `packages/coding-agent/src/valid-cwd.ts`: when the shell's working directory no
  longer exists (a removed worktree or checkout), it changes to the home directory with a stderr notice before any
  other module loads. `packages/coding-agent/src/cli.ts` and `packages/coding-agent/src/cli-main.ts` import it as
  their first statement.

### Why

- Node boots with a stale cwd handle and only throws `uv_cwd` when something evaluates `process.cwd()`; the bundled
  agent SDK does that during module evaluation, before user code could recover, so a deleted cwd crashed the CLI at
  import time with no guidance.

### Why an extension could not handle it

- The guard must run before every other import, including the SDK's module evaluation; the extension loader does not
  exist yet.

### Expected merge conflict zones

- LOW: `packages/coding-agent/src/valid-cwd.ts` is fork-only; the first-import lines in the entrypoints may conflict
  with upstream import reshuffles.

## llama.cpp local provider keeps sleeping runners discoverable (2026-08-17)

### What changed

- `packages/coding-agent/src/extensions/llama/provider.ts`: the router-fed `setCatalog()` keeps models whose runner
  status is `loaded` OR `sleeping`, because the llama.cpp router wakes sleeping runners on demand; the persisted
  `refreshModels()` snapshot still filters to `loaded` only. Credential resolution accepts a stored server URL, the
  `LLAMA_BASE_URL` environment, or the default local server, with an optional API key.

### Why

- A model whose runner was asleep but wakeable disappeared from the model list, so users could not select exactly
  the local models the router exists to wake on demand.

### Why an extension could not handle it

- The provider is a builtin registered with the model runtime; catalog filtering happens inside the provider's own
  model snapshot, which the runtime reads before any extension can post-process it.

### Expected merge conflict zones

- LOW: the status filter in `setCatalog()` and the credential-resolution chain.

## APP_NAME process identity and first-prompt session titles (2026-08-17)

### What changed

- Process identity is derived from the resolved brand: `process.title` is `APP_NAME` in `packages/coding-agent/src/cli.ts`,
  `packages/coding-agent/src/cli-main.ts`, and `packages/coding-agent/src/bun/cli.ts`, and `${APP_NAME}-rpc` in
  `packages/coding-agent/src/rpc-entry.ts`; `AI_AGENT` and inherited brand environment variables are set or scrubbed
  per entrypoint so nested engine runs keep the engine's own identity.
- Session titles: `buildInitialMessage()` in `packages/coding-agent/src/cli/initial-message.ts` returns the first CLI
  message as `initialTitlePrompt` when the initial prompt carries no private context (no piped stdin, no `@file` text,
  no attached images); `main.ts` threads it into interactive mode, which passes it as `sessionTitlePrompt` so the
  session is titled from the user's actual prompt. One-shot print mode passes `sessionTitlePrompt: false` instead.

### Why

- Process lists, logs, and RPC host spawns must distinguish branded runs (and RPC hosts) from the upstream engine,
  and an auto-generated title that ignored a plain first prompt produced generic titles for the most common launch
  shape.

### Why an extension could not handle it

- `process.title`, brand scrubbing, and argv-to-options wiring all execute in the entrypoints before the extension
  loader exists; the title prompt must be captured before the session consumes the initial message.

### Expected merge conflict zones

- LOW: per-entrypoint title and environment lines; the `sessionTitlePrompt` threading in `main.ts` and interactive
  mode.

## Retry-exhausted provider timeouts release retained steering (2026-08-17)

### What changed

- `core/agent-session.ts`: when a managed provider-timeout retry exhausts its retry/fallback budget, the retry owner
  now hands steering or follow-up input that was deliberately deferred from the retry request to the existing
  scheduled-continuation path. Successful retries keep their current queue behavior, and generic terminal
  provider errors or aborts still park queued work.
- Queue ownership follows the retry continuation that actually deferred the queue (recorded when the
  provider-timeout retry plan schedules its continuation), not the class of the final error: a timeout retry that
  ends in a different retryable failure still releases its deferred queue, while late steering queued during an
  ordinary non-deferring retry stays parked. User aborts — in flight or during the retry backoff sleep — keep
  retained input parked; a cancelled backoff reports a distinct outcome from budget exhaustion.
- Coverage: `test/suite/regressions/provider-idle-steering.test.ts` proves a provider timeout, one failed managed
  retry, and a steer queued during `auto_retry_start` produce an automatic third request without another prompt.
  `.agents/skills/senpi-qa/scripts/mock-loop-stream-start-timeout-steering.mjs` drives the same sequence through the
  real RPC CLI and actual stream-start watchdogs.

### Why

- Provider-timeout retries use `deferQueuedMessages: true` so steering cannot be consumed by another retry request
  that has not demonstrated responsiveness. If that retry also failed and no fallback remained, the generic Agent
  terminal-error policy correctly parked the queue, but the coding-agent retry owner had already finished and no
  lifecycle owner remained to admit it. The queued message therefore ran only after an unrelated later prompt.

### Why an extension could not do this

- Retry attempt accounting, provider-timeout continuation options, terminal `agent_end` admission, compaction
  revalidation, and queued-message ownership are coordinated inside `AgentSession` before extension callbacks can
  safely claim or release the queue.

### Expected merge conflict zones

- HIGH: `core/agent-session.ts` around `_processAgentEvent()` retry/compaction continuation admission.
- LOW: additive coverage in `test/suite/regressions/provider-idle-steering.test.ts` and the Senpi QA scenario.

## Custom-editor submit callbacks preserve the authoritative value (2026-08-16)

### What changed

- `modes/interactive/interactive-mode.ts` now routes custom-editor submissions through `expandSubmittedText()`.
- The submit helper preserves a non-empty `getExpandedText()` result from editors that submit before clearing, but uses the callback text when the live editor has already been cleared by pi-tui.
- The real host bridge is covered in `test/suite/regressions/0000-editor-paste-submit.test.ts` for clear-before-callback, retained paste-state expansion, and uncleared custom-editor compatibility.

### Why

- pi-tui computes the submitted value, clears editor and paste state, then invokes `onSubmit`. Re-reading the cleared editor returned `""`, so Enter cleared the prompt without sending a message.

### Why an extension could not do this

- The host owns the callback bridge between extension-provided editors and the default submission handler.

### Expected merge conflict zones

- LOW: `modes/interactive/editor-paste-transfer.ts`, the `setCustomEditorComponent()` submit callback, and its focused regression suite.

## CLI system-prompt overrides rewired into the runtime resource loader (2026-08-17)

### What changed

- `main.ts`: the runtime `resourceLoaderOptions` again forwards `parsed.systemPrompt` / `parsed.appendSystemPrompt` to `DefaultResourceLoader`, re-enabling the documented `--system-prompt` / `--append-system-prompt` flags on the CLI path (the SDK path already honored loader overrides).

### Why

- Commit `0ce8ac312` (2026-07-19, "preserve dynamic prompt policy") disconnected the flags because the prompt-preset extension clobbered user overrides on preset-matching models. The preset extension now yields to a user custom prompt and reapplies user appends (see `core/extensions/builtin/prompt-preset/changes.md`), so the flags can compose with the dynamic prompt policy instead of fighting it.

### Why extension system couldn't handle this

- CLI argv-to-loader wiring is host bootstrap code; extensions load after the resource loader exists.

### Expected merge conflict zones

- LOW: `main.ts` runtime `resourceLoaderOptions` block — keep both fields when upstream reshapes the options.

## JSONC settings selection and source events (2026-08-16)

### What changed

- Settings loading now accepts dependency-free JSONC syntax (line/block comments outside strings and trailing commas) in both `settings.jsonc` and existing settings content.
- Each global/project config directory prefers `settings.jsonc` over `settings.json`; the selected path remains the write target until the next explicit reload selection.
- `AgentSessionEvent` gained `settings_source_selected` with `{ path, format, reason, scope }`. Current selections replay once to newly attached host listeners, and reload selections publish through the normal session emitter.
- The config-reload builtin watches and validates both settings filenames with the same parser.

### Why

- Users need commented settings without losing plain-JSON compatibility, deterministic precedence, or having a UI write silently create the other file flavor.
- RPC and interactive hosts need an authoritative source decision instead of inferring it from filesystem state.

### Why an extension could not do this

- Settings path selection, parse-before-runtime, merge-before-write, and session listener attachment all occur in core before an extension can replace them. The built-in config watcher also owns reload admission and validation.

### Expected merge conflict zones

- HIGH: `core/settings-manager.ts` around path resolution, storage locking, load/reload, and merge-before-write parsing.
- MEDIUM: `core/agent-session.ts` event union, subscription replay, and disposal.
- LOW: additive host handling under `modes/rpc/` and `modes/interactive/`, plus config-reload filename allowlists/validation.

## Unified lockfile staleness policy across auth and settings storage (2026-08-16)

### What changed

- `core/lockfile-policy.ts` exports `FILE_STORAGE_LOCK_OPTIONS` (`stale: 30_000`, `update: 10_000`, `realpath: false`)
  and both file-backed stores acquire proper-lockfile locks with it: `FileAuthStorageBackend` sync and async paths in
  `core/auth-storage.ts` and `FileSettingsStorage` in `core/settings-manager.ts`. Lock file locations and read/write
  semantics are unchanged.
- Coverage: `test/lockfile-policy.test.ts` captures the options each backend passes to `lockSync`/`lock` and asserts
  all three acquisitions report the identical policy.

### Why

- Proper-lockfile defaults to `stale: 10_000` and refreshes a held lock's mtime every `stale / 2` ms. The async auth
  path used `stale: 30_000` (15s refresh) while both sync paths kept the 10s default, so a sync contender could
  classify a still-live async lock as stale in the 10-15s window and steal it mid-update.

### Why an extension could not do this

- Lock acquisition options are hardcoded inside core storage backends; an extension cannot intercept or reconfigure
  the proper-lockfile calls used by credential and settings persistence.

### Expected merge conflict zones on next upstream sync

- `core/auth-storage.ts` and `core/settings-manager.ts`, around the lock acquisition helpers.

## Non-interactive auth reads degrade on storage lock failures (2026-08-16)

### What changed

- `core/auth-storage.ts`: asynchronous credential reads now preserve the last valid in-memory snapshot when acquiring
  or reading the auth storage lock fails, regardless of whether the caller supplied an operation signal. The failure is
  retained in `AuthStorage.drainErrors()`; an actual caller abort still rejects instead of being converted into stale data.
- `main.ts`: non-interactive startup/model-listing and completed print runs drain auth-storage failures through the
  existing warning diagnostic renderer. Interactive-mode reporting is unchanged.
- OAuth refresh persistence remains fail-closed because `modify` and `delete` still propagate every lock, parse, and
  write failure without fallback.

### Why

- Model-runtime credential reads always carry a normalized signal. The previous signal-gated branch therefore skipped
  its intended last-good fallback, so a sandbox-denied `auth.json.lock` mkdir escaped top-level `senpi -p` startup as an
  uncaught `EPERM` instead of a warning.
- Corrupt auth data must remain visible even when the last-good snapshot keeps a non-interactive run alive, so degraded
  reads record the original failure for the CLI diagnostic surface.

### Why an extension could not do this

- Credential storage locking and the non-interactive bootstrap diagnostic boundary run inside core before an extension
  can intercept model authentication or recover a rejected credential-store read.

### Expected merge conflict zones on next upstream sync

- `core/auth-storage.ts`, around `readLatestData` reload coalescing and abort handling.
- `main.ts`, around startup diagnostics and print-mode dispatch.


## Idempotent ambient OAuth auth composition (2026-08-14)

### What changed

- `core/provider-api-key-auth.ts` now accepts an ambient OAuth resolver's own synthetic key when resolved auth is replayed as an explicit request key by title, compaction, and branch-summary calls.
- The compatibility adapter identifies itself as ambient-only, so a replayed marker or unrelated explicit key cannot bypass a valid stored OAuth account.
- The ambient adapter now resolves configured metadata headers and `authHeader` through the same composition used by stored OAuth.
- Replay-only credential environment participates in configured header resolution while unrelated explicit keys remain rejected.
- Present-but-empty Claude token slots survive synthetic-marker replay, preventing auxiliary calls from falling back to a host token.
- When any request Claude token slot is present, ambient resolution treats that request token set as the complete namespace and cannot import a different host slot during replay.
- Request-backed `config-dir` authentication uses the non-persisting OAuth environment lane for that request, so request credentials are never written below the stable agent directory.
- Coverage compares ambient and stored OAuth auth shapes, drives replay through real title generation, and pins stored-account precedence.

### Why

- Auxiliary calls copy resolved request auth into their own options. Rejecting the provider's marker made the second auth pass report unconfigured, while allowing the ambient adapter to outrank stored OAuth broke managed-account replay and an early ambient return dropped configured headers and synthesized authorization.

### Why an extension could not do this

- Provider auth composition runs before request hooks and is the mechanism that makes extension-registered providers callable. An extension cannot repair auth that the host composer rejected or omitted.

### Expected merge conflict zones on next upstream sync

- LOW: `core/provider-api-key-auth.ts` around the ambient-only OAuth adapter and its precedence metadata.


The historical-image transport entry moved to `core/changes.md`, beside the
other provider-bound image transport behavior that owns the same payload path.

## GLM 5.3 full support: preset + catalog + wire (2026-08-16)

### What changed

- `core/extensions/builtin/prompt-preset/`: new `glm-5-3.ts` preset (clone of `glm-5-2.ts`), `presets.ts` matcher + dispatch, `settings.ts` union entry. The preset carries "running on GLM 5.3" tuning; every behavioral directive is identical to 5.2.
- `packages/ai`: `openai-completions.ts` generalized `isGlm52`→`isGlm5x` (5.3 inherits 5.2's thinkingLevelMap branches) and forces zai `{type:"enabled"}` for 5.3 even without reasoning effort. 25 glm-5.3 catalog entries cloned across 18 provider data files. `generate-models.ts` updated so regeneration preserves 5.3.
- Tests: `test/suite/prompt-presets-glm-5-3.test.ts` (preset resolution + catalog sweep), `packages/ai/test/glm-5.3-thinking.test.ts` (reasoning effort map + zai always-enabled).

### Why

- GLM 5.3 shipped in upstream catalogs (oh-my-pi's `zai` provider defaults to `glm-5.3`) but senpi had zero 5.3 support: no preset, no catalog entries, no wire-level reasoning effort handling. Users selecting GLM 5.3 got the untuned fallback prompt and unmapped reasoning effort.

### Expected merge conflict zones

- `prompt-preset/presets.ts`/`settings.ts`: shared lists — trivial adjacent-line conflicts if upstream adds presets.
- `openai-completions.ts`: the `isGlm52`→`isGlm5x` rename and zai handler guard sit in fork-modified sections.
- Provider data files: fork-only; upstream has no counterpart.

## Explicit `/skill:` invocations retain user authority (2026-08-16)

### What changed

- `core/agent-session.ts`: each known leading `/skill:<name>` expansion now states that the user explicitly invoked that
  skill, places its binding workflow in a `<skill-instruction>` section, and isolates trailing free text in a
  `<user-request>` section. Chained skills retain written order; unknown-skill fallthrough, duplicate suppression, and
  the five-skill expansion cap are unchanged. `parseSkillBlock` recognizes that current format first and retains its
  legacy `<skill>` fallback so resumed and imported sessions still collapse correctly.
- `core/export-html/template.js`: the intentionally standalone parser mirrors the runtime parser, preserving collapsed
  skill rendering in exported transcripts for both current and legacy session payloads.
- Coverage: `test/suite/agent-session-prompt.test.ts` pins invocation shape with and without trailing arguments and for
  chained skills; `test/suite/regressions/308-skill-composition.test.ts` keeps unknown-skill, cap, deduplication, steer,
  and follow-up behavior pinned to the new shape; `test/export-html-skill-block.test.ts` executes both parsers against
  payloads from the production formatter and covers chained and legacy messages; the real-expansion hook test confirms
  `UserPromptSubmit` context injection preserves the new wrapper and request.

### Why

- The previous expansion flattened passive `<skill>` content and trailing arguments into one ordinary user message.
  That erased the user's explicit command authority, allowing the Intent Gate to route only on the trailing prose and
  ignore the selected skill's rules or workflow (issue #890).

### Why an extension could not do this

- Skill-command expansion happens in the private `AgentSession` prompt, steering, and follow-up dispatch paths before
  the provider sees the user message. Extensions cannot replace that text transformation consistently across all three
  paths.

### Expected merge conflict zones on next upstream sync

- `core/agent-session.ts` around skill invocation formatting, parsing, and `_expandSkillCommand`.
- `core/export-html/template.js` around the standalone `parseSkillBlock` copy.
- `test/export-html-skill-block.test.ts`, `test/suite/agent-session-prompt.test.ts`, and
  `test/suite/regressions/308-skill-composition.test.ts` where parsing and the exact expanded payload are pinned.

## Shipped Fable fallback chain reaches Kimi K3 served as `kimi-k3` (2026-08-13)

### What changed

- `core/retry-fallback/settings.ts`: `DEFAULT_FALLBACK_CHAINS["claude-fable-5"]` gains a bare `kimi-k3:max` entry after
  `k3:max`, so providers that expose Kimi K3 under the vendor-prefixed id `kimi-k3` (OpenCode Go) join the shipped
  Fable -> K3 fallback route. `matchesFamily` is untouched: the conservative exact/dash-suffix matcher still cannot
  capture `kimi-k3` via `k3`, which is why the alias is an explicit entry rather than a matcher change (issue #793).
- Coverage: `test/suite/retry-fallback-expansion.test.ts` (new alias expansion case + shipped-default pin),
  `test/settings-manager-retry-fallback.test.ts` and `test/suite/retry-fallback-chains.test.ts` (shipped-default pins),
  and the real-CLI scenario `.agents/skills/senpi-qa/scripts/scenarios/fallback-chains-kimi-k3-qa.mjs`.

### Why

- On registries serving `opencode-go/kimi-k3`, `/fallback` expanded the shipped Fable chain to Claude entries only:
  `k3` matches `k3`/`k3-*` but never `kimi-k3`, so OpenCode Go users lost the intended Fable -> K3 route.

### Why an extension could not do this

- The shipped defaults are core policy consumed by `canonicalizeFallbackChains`; an extension can replace a chain per
  key but cannot amend the shipped default's entries without owning the whole key.

### Expected merge conflict zones on next upstream sync

- `core/retry-fallback/settings.ts` (`DEFAULT_FALLBACK_CHAINS` literal).
- The three test files pinning the shipped chain contents/length.

## Provider stream stalls share the bounded retry policy (2026-08-13)

### What changed

- `core/agent-session.ts`: provider-stream stalls (`isProviderStreamStallError`, covering both the idle-timeout and
  stream-start-timeout watchdog wordings) are no longer special-cased. They consume the same bounded same-model retry
  budget (`settings.retry.maxRetries`) as every other transient class and escalate to the fallback chain only when that
  budget is exhausted. The `_consecutiveProviderStreamStalls` streak counter and its escalation branch are removed.
- `core/provider-timeout-retry.ts`: the retry request keeps the configured `timeoutMs`/`streamStartTimeoutMs` instead of
  clamping both to `retry.provider.streamRetryTimeoutMs`. That setting still bounds the retry *continuation*
  (`runBoundedRetryContinuation`), so a wedged retry is still cancelled without shortening the provider's own guards.
  Disabled guards are still never re-enabled.
- Coverage: `test/suite/retry-fallback-stall-shared-budget.test.ts` (replaces
  `test/suite/retry-fallback-stall-escalation.test.ts`), `test/provider-timeout-retry.test.ts`, and updated
  `test/suite/regressions/provider-idle-{recovery,steering}.test.ts`.

### Why

- This reverses the 2026-07-29 stall-escalation and retry-cap entries below. In practice the two combined to end turns
  early: the second consecutive stall skipped the remaining same-model budget, so a session with no configured fallback
  chain surfaced `Retry failed after 1 attempts: Provider stream start timed out after 30000ms` while `maxRetries` was 3.
- The cap also shrank a configured 90s stream-start guard to 30s on the retry, so the retry was judged dead on a deadline
  the operator never configured - visible as a 90000ms stall immediately followed by a 30000ms one. A slow-but-alive
  provider now gets the budget it was configured with, and the transient class it already belongs to
  (`isRetryableErrorMessage` matches both wordings) decides the number of attempts.

### Why an extension could not do this

- Retry classification, the same-model budget, and the fallback-chain handoff all live in the private auto-retry branch of
  `AgentSession`. No extension hook observes or replaces that decision.

### Expected merge conflict zones on next upstream sync

- `core/agent-session.ts` in the transient retry branch (`_autoRetry`) around the budget/fallback gate.
- `core/provider-timeout-retry.ts` in `createProviderTimeoutRetryPlan`.

## Model-aware `/btw` side-query context budgeting (2026-08-12)

### What changed

- `/btw` side queries now budget the complete ephemeral prompt against the selected model's context window. Oversized
  snapshots reuse the deterministic context reducer, repair orphaned tool results, and prune oldest context while
  preserving the final question and newest usable messages.
- Mandatory prompt content that still cannot fit now fails locally with an actionable `/compact` suggestion instead of
  sending a provider request that is guaranteed to be rejected.

### Why

- The builtin `/btw` path bypassed the main-turn context pipeline and replayed the captured session snapshot directly to
  the provider. Large sessions could therefore fail with a context-window overflow even while the main turn continued.

### Why an extension could not do this

- The oversized payload is assembled inside the builtin command's private snapshot-to-provider path. An external
  extension cannot intercept and structurally budget that ephemeral request without replacing the builtin.

### Expected merge conflict zones on next upstream sync

- `core/extensions/builtin/btw/index.ts` around snapshot construction and side-query dispatch.
- `core/extensions/builtin/btw/side-query.ts` around context assembly and model runtime options.
- `test/suite/btw-side-query.test.ts` around context-builder and command regression coverage.

## Control protocol exposes loaded extensions and MCP inventory (2026-08-11)

### What changed

- RPC gained the session-scoped `get_loaded_surfaces` request. Extension rows come from
  `resourceLoader.getExtensions().extensions`, so commandless extensions remain visible and multi-command extensions
  appear once; skills remain one-row-per-skill through `get_commands`.
- MCP rows come from the live session-owned MCP service and report server name, tool count, connection/config status,
  and non-secret auth status. A session-local event-bus bridge preserves multi-session isolation instead of consulting
  the classic process singleton.
- RPC emits `loaded_surfaces_changed` when the loaded skill, extension, or MCP snapshot changes. The event is an
  invalidation notice with no payload, matching the app-server `skills/changed` read-after-notify model.

### Why this cannot be expressed externally

- The control host owns session routing and response/event ordering, while the loaded extension inventory and scoped
  MCP service are private runtime state. An extension cannot add a correlated control request or safely address another
  session's service.

### Expected merge conflict zones

- MEDIUM: additive request/event handling in `modes/rpc/rpc-types.ts` and `connection-handler.ts`.
- LOW: the MCP control-inventory bridge and wire-status refresh hooks under `core/extensions/builtin/mcp/`.

## Fallback responses with errors no longer emit success (2026-08-11)

### What changed

- `core/agent-session.ts` now requires an assistant response to have no `errorMessage` before it emits
  `retry_fallback_succeeded` and `auto_retry_end { success: true }`.
- A fallback provider response such as `Not logged in · Please run /login` can no longer produce the green
  `Fallback model responded` notice merely because its stop reason was not normalized to `error`.
- A terminal errored fallback response also closes the active retry attempt with `auto_retry_end { success: false }`,
  so a later successful user turn cannot emit a delayed success notice for the earlier failed fallback.

### Why this cannot be expressed externally

- Retry-attempt settlement and `retry_fallback_succeeded` emission occur inside private `AgentSession` lifecycle
  state before extensions or interactive renderers can correct the classification.

### Expected merge conflict zones

- LOW: the assistant `message_end` success gate in `core/agent-session.ts`.
- LOW: the focused hard-error fallback cases in `test/suite/retry-fallback-hard-error.test.ts`.

## Public filesystem policy exports (2026-08-09)

### What changed

- The package root now exports the filesystem policy request, operation, decision, policy, and composed-checker types
  used by `pi.registerFilesystemPolicy()` consumers.

### Why this cannot be expressed externally

- Extension source compiles against the package's public type surface; an extension cannot export missing host API
  declarations for itself.

### Expected merge conflict zones

- LOW: the extension type export lists in `src/index.ts` and `core/extensions/index.ts`.

## `--session` cross-project resume fails fast instead of hanging on non-interactive stdin (2026-08-07)

### What changed

- `src/main.ts`: when `--session <id>` resolves to a session owned by a different project, the CLI previously always asked `Fork this session into current directory?` via readline. With piped, detached, or closed stdin (scripts, app-server spawns) the question never settles — readline does not answer on EOF — so the process hung forever with no output. `createSessionManager()` now receives the resolved `AppMode` and exits 1 with an actionable message (`--fork '<id>'` or re-run interactively from the owning project) for every non-interactive mode. Gating on `process.stdin.isTTY` alone was not enough: a `-p` one-shot launched from an ordinary terminal has TTY stdin, so it still reached the prompt and blocked.
- `promptConfirm()` additionally resolves `false` on readline `close` (Ctrl+D / stdin EOF) so interactive sessions can no longer wedge on an ended input stream.
- Coverage: `test/suite/regressions/756-session-cross-project-resume.test.ts` spawns the real CLI against a cross-project session fixture for both shapes — non-terminal stdin, and a `-p` run booted with the TTY flags a terminal sets — and asserts the fast, guided failure with bounded child teardown.

### Expected merge conflict zones on next upstream sync

- LOW: additive branch and close-handler only, both inside fork-owned `main.ts` session wiring.

## Joined user aborts override system provenance (2026-08-05)

### What changed

- `AgentSession` now promotes an in-flight system-owned abort to user-owned when
  an explicit user abort joins the same operation.
- Joining an existing abort awaits the shared promise without issuing a second
  `agent.abort()` call, and a later system abort cannot downgrade user provenance.
- A later recovery generation with no active provenance issues its own
  `agent.abort()` and records a fresh source instead of incorrectly joining the
  prior generation's completed abort.
- User intent that arrives while `agent_end` handlers are dispatching promotes
  the shared event in place. A late join that occurs after an earlier handler
  already observed system provenance emits one `session_abort` before
  `agent_settled`, so TTSR corrective follow-ups and provider retries admitted
  before dispatch cannot outrun the user cancellation.
- The same cancellation boundary remains open through the public `agent_end`
  notification, covering Escape handlers that run after extension dispatch but
  before retry and settlement processing.
- The boundary now remains mutable through `agent_settled` dispatch as well.
  Extension messages requested from that event are held by
  `agent-settled-delivery.ts` until every handler and public listener completes;
  a user abort drops the held actions before one can become a corrective
  provider turn, without disturbing user-owned steering or follow-up queues.
- System-owned aborts no longer set the user-only queued-continuation suppression
  latch; a user join still sets it before awaiting the shared abort.

### Why

- TTSR can begin a corrective system abort immediately before the user presses
  Escape. The old early-return path kept `"system"` provenance and invoked the
  underlying abort twice, so Goal could ignore the user's durable stop intent.

### Why this cannot be expressed externally

- Abort provenance, shared-promise ownership, and queued-continuation suppression
  are private `AgentSession` lifecycle state.

### Expected merge conflict zones

- `core/agent-abort-provenance.ts`, `core/agent-settled-delivery.ts`, and
  `core/agent-session.ts` around `_emitExtensionEvent`, `_emitAgentSettled`,
  `abort`, and `_abortActiveAgentAndRetry`.

## Required-recovery admission supersession and bounded fallback sizing (2026-08-03)

### What changed

- An accepted required-compaction recovery now clears the stored admission rejection when its queued
  continuation is scheduled, so the originating `prompt()` resolves after the queued steer/follow-up
  completes instead of throwing the superseded `RequiredCompactionError`.
- Deterministic recovery sizing no longer materializes `JSON.stringify` for every retained message
  without a bound: the estimator fails closed on accessor-bearing, non-plain, cyclic, or callable
  values and exits early once the remaining `contextWindow - reserveTokens` budget is exceeded.
- Regression coverage pins the turn-end soft-cap reset across degradation-recovery early returns,
  accepted-recovery queued-steer supersession, accessor-safe fallback rejection, and the three-call
  continuation flow (previously ending in an unasserted faux queue-exhaustion error).

### Why

- Review of #679 reproduced a contradiction: queued continuation completed and both queues drained,
  yet the originating prompt still rejected with the stale required-compaction error.
- The same review measured ~207 MiB peak amplification from a 32 MiB retained message and observed
  property getters executing on persisted tool-call arguments during recovery sizing.

### Why this cannot be expressed externally

- Supersession lives in `AgentSession`'s internal compaction admission/continuation ownership; the
  sizing guard is a fail-closed property of the builtin deterministic-fallback estimator.

### Expected merge conflict zones

- `core/agent-session.ts` retry/continuation scheduling around `_checkCompaction` and `agent_end`.
- `core/extensions/builtin/compaction/deterministic-fallback.ts` estimator and projection call site.

## Keep long-running compaction recovery progressing (2026-08-03)

### What changed

- The automatic-compaction soft cap now resets after each provider turn instead of lasting for the
  whole multi-tool agent run. The completed turn's zero-yield recovery still observes its original cap
  before the reset, while the absolute session cap remains authoritative for every route.
- Required-compaction failures now resume queued work after an accepted recovery compaction without a
  synthetic `continue`, while rejected recovery remains terminal.
- Provenance-confirmed required recovery uses the persisted byte-derived estimate when no valid
  provider usage sample exists.
- Deterministic recovery measures the reconstructed suffix instead of stale cumulative assistant usage.
  It keeps the prepared boundary when safe and otherwise advances to the latest complete persisted user
  turn, including expanded skill text and its chronological suffix, with strict retained-message schemas.

### Why

- Long `ulw` runs could complete three valid compactions and then reject every later threshold
  compaction as if the whole agent run were one provider turn.
- When summarization then failed, a fitting skill-bearing suffix could be rejected because provider
  usage still described the discarded pre-compaction prefix. Repeated continuations surfaced the same
  threshold error instead of recovering.

### Why this cannot be expressed externally

- The fix depends on internal provider-turn lifecycle state, exact session entry boundaries, compaction
  admission, and continuation ownership.

### Expected merge conflict zones

- `src/core/agent-session.ts` compaction retry/continuation ownership and upstream telemetry lifecycle.
- `src/core/extensions/builtin/compaction/` admission, fallback, and provider-turn accounting.

## Compact completed apply_patch result details (2026-08-02)

### What changed

- Completed `apply_patch` previews retain the TUI's bounded diff and retain a complete unified patch only when it is at most 16 KiB per file; larger patch bodies are omitted rather than persisted or emitted as malformed truncated diffs.
- Nested applied-operation previews are rebuilt as lightweight metadata without full diff or patch bodies, including the fail-fast `ApplyPatchError` recovery result.
- App-server file-change projection keeps its complete unified-diff contract for retained patches within the 16 KiB budget; oversized patches do not produce a file-change diff from persisted result details.

### Why

- Full old/new file contents in unified patches dominated completed tool-result details after diff compaction, so large add, delete, and update operations still scaled with source size in session files and resident memory.
- App-server projection and session persistence consume the same completed result object with no extension-scoped post-projection persistence seam. A fixed budget is therefore required to bound retention without storing a second live-only copy; omitting oversized patches avoids sending invalid partial unified diffs.

### Why this cannot be expressed externally

- The payload and its source-backed unified patches are constructed inside the builtin `apply_patch` tool before app-server projection and session persistence.

### Expected merge conflict zones

- LOW: `core/extensions/builtin/gpt-apply-patch/apply.ts` and `tool.ts` completed-result construction.

## App-server extension RPC delivery (2026-08-12)

### What changed

- `modes/app-server/runtime.ts` subscribes to each bound session's opt-in extension RPC events before extension binding,
  preserves binding-time events until the thread is registered, and routes live events only to that thread's subscribers.
- `modes/app-server/rpc/registry.ts` registers `extension_request` and dispatches `{threadId,name,data}` to the loaded
  session's `extensionRunner.requestRpc`, preserving its exactly-one-handler semantics as JSON-RPC errors.
- `modes/app-server/threads/registry.ts` seeds a new thread's notification queue with binding-time extension records so
  the connection that started, resumed, or forked the thread receives them after subscription.

### Why

- App-server mode binds and owns separate sessions, so classic RPC's connection-bound extension delivery never reaches
  app-server clients in either direction.
- App-server initialize capabilities have no `extension_events` field. Event delivery is therefore unconditional for
  initialized subscribers, while thread subscriptions provide the required audience boundary.

### Why this cannot be expressed externally

- Both directions cross the app-server's internal thread/session registry and notification router. An extension can opt
  into delivery with `pi.rpc`, but cannot register an app-server JSON-RPC method or address the owning thread's clients.
- Ordinary `pi.events` channels remain extension-local; this change forwards only explicit `pi.rpc.emit` records at the
  connection boundary.

### Expected merge conflict zones

- MEDIUM: `modes/app-server/runtime.ts` session binding and registry wiring.
- LOW: `modes/app-server/rpc/registry.ts` method registration and `threads/registry.ts` initial notification storage.

## Backfill: injected app-server turns (2026-08-01)

### What changed

- App-server clients can inject turns through the runtime and thread handlers while preserving the normal turn lifecycle.

### Why

- Remote session controllers need a first-class path that behaves like an ordinary user turn.

### Why this cannot be expressed externally

- Injection crosses app-server runtime, thread state, turn scheduling, and session event emission.

### Expected merge conflict zones

- `modes/app-server/runtime.ts`, `threads/handlers.ts`, and `threads/turn-runtime.ts`.

## Supersede level-scoped high-reasoning warning deduplication (2026-07-31)

### What changed

- High-reasoning warnings are now deduplicated once per provider/model identity
  for the lifetime of an `AgentSession`, rather than once per
  provider/model/reasoning-level tuple.
- Moving between `xhigh`, `max`, lower reasoning levels, or another model and
  back does not append the same warning again.
- A different sensitive provider/model identity still receives its own first
  warning.

### Why

- The released provider/model/level behavior caused the large warning box to
  reappear while the user was only changing reasoning effort. This follow-up
  intentionally supersedes that earlier contract.

### Why extension system couldn't handle this

- Warning deduplication is session-owned state inside `AgentSession` and must
  apply consistently before TUI and RPC consumers receive the event.

### Expected merge conflict zones

- LOW: `core/agent-session.ts` high-reasoning warning state and emission.

## Required-compaction recovery and queue chronology (2026-07-31)

- Targeted required-compaction summarization failures can recover from a deterministic, suffix-safe local checkpoint without a second provider request; unfit recovery remains fail-closed and preserves the latest request.
- Truncation recovery requires structured transient `SummaryRequestError` provenance; generic error text cannot authorize fallback.
- Recovery retains task intent and UTF-8-safe bounded text while todo/checkpoint snapshots remain only in their separately persisted canonical entries, not duplicated in compaction details.
- Terminal queue restoration now follows global submission chronology across native and compaction-owned input through a non-enumerable compatibility side channel, without changing native steer priority or abort-state semantics.

## Refusal fallback exhaustion resets retry state (2026-07-31)

### What changed

- `core/agent-session.ts`: terminal classifier-refusal fallback exits now emit the matching failed `auto_retry_end` event and reset the retry attempt counter when a retry actually started.
- The zero-attempt refusal path remains event-free, so `auto_retry_end` still pairs only with a prior `auto_retry_start`.
- Regression coverage drives every configured fallback to refusal, then proves the session is idle and the interactive double-Escape history action works again.

### Why

- Refusal exhaustion previously resolved the retry promise without clearing `_retryAttempt`. The TUI therefore kept treating an idle session as retrying, so every Escape re-entered abort cleanup instead of arming the double-Escape session-history shortcut.

### Expected merge conflict zones

- LOW: `agent-session.ts` in `_handleRetryableError()`'s classifier-refusal terminal branches.

## Claude SDK OAuth provider identity (2026-07-31)

### What changed

- Renamed the SDK-backed Claude Pro/Max builtin provider, extension directory, runtime/model ID, OAuth storage sentinels, settings key, account directory, imports, tests, QA scenarios, and public commands from `claude-agent-sdk` to `claude-sdk-oauth`.
- Renamed the provider-local TypeScript symbols to the same identity while preserving the upstream npm dependency and executable packages under `@anthropic-ai/claude-agent-sdk`.
- Split the oversized stream test into prompt-bridge and stream-event suites without changing its five pinned behaviors.

### Why

- `claude-agent-sdk` conflated Senpi's provider identity with Anthropic's upstream package name and obscured that this lane is specifically the subscription OAuth surface.
- There was no separate `claude-oauth` implementation to retain; the renamed provider is the sole SDK-backed OAuth implementation.

### Why extension system couldn't handle this alone

- The extension owns the provider implementation, but host registration order, RPC/app-server account imports, persisted auth keys, settings, and QA surfaces all reference its identity outside the extension directory.

### Expected merge conflict zones

- HIGH: the renamed builtin extension directory and provider-focused tests.
- MEDIUM: builtin registration, RPC/app-server account imports, provider docs, and QA scenario names.

## Breaker-cancelled opportunistic compaction no longer blocks admission (2026-07-31)

### What changed

- `core/agent-session.ts`: prompt, final-payload, scheduled-continuation, and retry admission now proceed without opportunistic compaction when the latest compaction rejection is `circuit-breaker`.
- Final-payload admission still fails closed when the provider payload is actually oversized, and overflow-triggered compaction remains fail-closed.
- Regression and real-CLI coverage prove breaker cooldown does not permanently reject prompts while non-breaker cancellation remains blocking.

### Why

- The circuit breaker stops repeated summarization spend during provider outages. Converting its cooldown rejection into `RequiredCompactionError` permanently bricked sessions above the soft threshold instead of allowing the provider or existing overflow recovery to make the real admission decision.

### Why extension system couldn't handle this alone

- Extensions report the rejection cause, but core owns every provider-admission site and decides whether a failed opportunistic compaction blocks the turn.

### Expected merge conflict zones

- MEDIUM: `agent-session.ts` compaction admission and retry-continuation paths.

## Failed pre-prompt compaction reports terminal recovery (2026-07-30)

### What changed

- `core/agent-session.ts`: `_runPrePromptCompaction()` now emits failed `compaction_end` events with `willRetry: false`. Its caller throws `RequiredCompactionError` when compaction fails, so no retry can follow that terminal event.
- Coverage drives a real pre-prompt overflow compaction through a failing faux provider and pins both the truthful event and restoration of queued TUI input through the real interactive helper.

### Why

- Emitting `willRetry: true` deferred queued input to native session queues even though failed compaction blocks provider admission, leaving that input parked indefinitely.

### Why extension system couldn't handle this alone

- `willRetry` is authored inside the core pre-prompt compaction lifecycle before extensions consume the event; only the session can truthfully report whether its caller will retry.

### Expected merge conflict zones

- LOW: `agent-session.ts` in `_runPrePromptCompaction()`'s terminal catch emission.

## high_reasoning_warning narrowed to gpt-5.6-sol only (2026-07-30)

### What changed

- `high-reasoning-warning.ts`: `isSensitiveHighReasoningModel` now matches ONLY gpt-5.x "sol" variants via a dedicated regex (`/gpt-5(?:\.\d+)?-sol(?![a-z])/i`), fully decoupled from `supportsXhigh`/`supportsMax`. The prior implementation reused those capability gates, so the scary warning wrongly fired for every frontier model that merely supports xhigh/max (claude-fable-5, opus, sonnet-5, deepseek-v4).

### Why

- The warning is about a specific risky model family (gpt-5.6-sol-like), not about xhigh/max capability. Conflating the two surfaced the warning on anthropic/claude-fable-5 @ xhigh, which was not intended. The negative lookahead keeps unrelated ids such as `upstage/solar-pro-3` from matching.

### Why extension system couldn't handle this alone

- The detection is consumed by the in-session emit path (`agent-session.ts`); it is core risk logic, not an extension concern.

### Expected merge conflict zones

- LOW: `high-reasoning-warning.ts` `isSensitiveHighReasoningModel`. `thinking-levels.ts` is deliberately unchanged so capability gating (fable-5 still supports xhigh/max) is preserved.

## Kimi XTML thinking recovery runs without tools (2026-07-30)

- `ModelRuntime.stream()` and `streamSimple()` now compose model recovery through the AI package's shared
  `wrapStreamWithModelRecovery()` boundary.
- Kimi structural response-channel recovery therefore runs on final-answer requests with an empty tool list, while
  Claude/Kimi leaked tool-call recovery still activates only when tools are available.
- Real CLI QA adds `--scenario kimi-xtml-thinking-recover`, proving a malformed thinking-only first response is
  discarded, the second response is visible exactly once, XTML markers never leak, real auth is unchanged, and
  the sandbox is cleaned.

## Runtime API keys propagate to session titles (2026-07-30)

- Background session-title generation now reuses the active agent request API key before resolving provider
  headers and compatibility options.
- This prevents a turn launched with `--api-key` from succeeding under one credential and then sending its
  `x-apitopia-session` title request with a different configured credential, which Apitopia rejects with 401.
- Coverage: `test/agent-session-auto-title-routing.test.ts`.

## high_reasoning_warning for sensitive frontier models at xhigh/max (2026-07-30)

### What changed

- New `core/high-reasoning-warning.ts`: provider-agnostic, model-name-based detection (`isSensitiveHighReasoningModel`, reusing `supportsXhigh`/`supportsMax`) plus `shouldWarnHighReasoning` and `buildHighReasoningWarning`.
- `agent-session.ts`: emits a new `high_reasoning_warning` `AgentSessionEvent` when a sensitive model is driven at xhigh/max, deduped by provider/model/level, wired into `_switchActiveModel` and `_setThinkingLevel`.

### Why

- Frontier reasoning models (gpt-5.x, deepseek-v4-pro/flash, opus-4-6..5, sonnet-5, fable-5) at xhigh/max are acutely prompt-sensitive: human-prompted runs risk non-stopping, unrequested actions, or risky behavior. The warning urges use via the ultrabrain subagent and states direct-use responsibility.

### Why extension system couldn't handle this alone

- The event must fire from session model/thinking-level transitions inside `AgentSession`, which extensions can only observe after the fact; the dedupe + emit belongs in the session lifecycle.

### Expected merge conflict zones

- LOW: `agent-session.ts` `_switchActiveModel`/`_setThinkingLevel` and the `AgentSessionEvent` union.

## Ollama Cloud keeps its provider-owned dynamic catalog (2026-07-30)

### What changed

- `ModelRuntime` leaves builtins that already implement `refreshModels` unwrapped instead of replacing their
  refresh path with the static `pi.dev` catalog overlay. This preserves both Radius and the new Ollama Cloud
  `/api/tags` + `/api/show` discovery path.
- An `ollama` provider with an explicit models.json catalog does not run the Cloud builtin refresh first and replaces
  rather than augments any in-memory Cloud catalog. Hot reload therefore removes stale Cloud tags instead of rebinding
  them to the local base URL, without affecting dynamic discovery for Radius or other providers.
- The CLI recognizes `ollama` as `Ollama Cloud`, documents `OLLAMA_API_KEY`, and uses
  `qwen3.5:397b` as the current default when it is present in the refreshed catalog.
- `test/ollama-provider.test.ts` drives `ModelRuntime.create()` with a mocked Ollama host and proves the
  provider-owned catalog reaches the runtime and persisted model store.

### Why this belongs in core

- Builtin catalog wrapping happens before extensions and models.json overlays are composed. A provider factory
  cannot preserve its own refresh implementation after the runtime has replaced it.

### Expected merge conflict zones

- LOW: builtin wrapping predicates in the async and sync `ModelRuntime` constructors.
- LOW: additive provider display/default/help entries.

## Bun self-updates preserve the Bun launcher (2026-07-30)

- Bun-managed global self-updates now replace Bun's generated Node-shebang symlink with a small launcher that
  executes the updated `dist/cli.js` through the Bun runtime that performed the repair.
- The repair uses the Bun runtime's own `process.execPath`, supports Bun binaries installed outside the global bin
  directory, and is skipped on Windows where Bun uses platform-specific shims.
- If `bun pm bin -g` does not return a global bin directory, self-update is now rejected instead of installing
  without a launcher repair.
- Coverage: `test/suite/regressions/496-bun-launcher-self-update.test.ts`.

## Shell-command credential resolution retries before giving up (2026-07-29)

### What changed

- `core/resolve-config-value.ts`: `executeCommandUncached` now runs up to 3 attempts (250ms then 1000ms backoff
  via a blocking `Atomics.wait` sleep — the call sites are synchronous `execSync`/`spawnSync` already) before
  returning `undefined`. Previously a single failed spawn, non-zero exit, or timeout of a credential helper
  propagated through `resolveConfigValueOrThrow` as `Failed to resolve API key … from shell command`, which
  `agent-session` classifies as hard-error eligible and ejects the active model without a single retry.
- Coverage: `test/resolve-config-value.test.ts` — new: transient-fail-then-success resolves on attempt 3;
  persistent failure bounded at exactly 3 attempts. Updated: cache-failure arithmetic (one failing resolve now
  costs 3 executions before the `undefined` is cached).

### Why

- Incident session `019faccb-3e7c-7307-8b19-2c7fb9e77b5c` (2026-07-29), five fallback cascades in one day:
  every cascade opened with `API key auth failed for provider kimi-code: Failed to resolve API key … from shell
  command: omp token kimi-code`, hard-error ejecting `kimi-code/k3`; the same flake hit `omp token anthropic`
  mid-chain. Measured `omp token` cold-start latency is 1.5–4.0s per invocation (bun startup + SQLite auth
  store); under load the subprocess intermittently fails while the credential itself is healthy — re-running it
  seconds later succeeds. A hard-error ejection on a transient resolver blip converts a one-second hiccup into
  a full provider-switch cascade (primary → exhausted fallbacks → last-resort model).

### Expected merge conflict zones on next upstream sync

- MEDIUM: `core/resolve-config-value.ts` also exists upstream in badlogic/pi-mono (same
  `executeCommandUncached`), so the retry wrapper (`executeCommandOnce` keeps the original body) can collide
  with upstream edits to that function; constants and `sleepBlocking` are additive. The same fix belongs
  upstream as well.

## Kimi XTML recovery preserves protocol identity (2026-07-29)

### What changed

- `core/model-runtime.ts` passes both `createXtmlRecoveryStreamParser` and `protocol: "kimi-xtml"` to the shared
  invoke-recovery wrapper for Kimi models.
- Successful recovered tool calls and terminal recovery failures now expose Kimi-specific diagnostics and
  `recovered-kimi-xtml-*` IDs instead of misleading ANTML metadata.
- `test/kimi-xtml-recovery-runtime-boundary.test.ts` pins the user-visible runtime result while the default ANTML
  path remains covered in the AI package.

### Expected merge conflict zones

- LOW: the two invoke-recovery call sites in `core/model-runtime.ts`.

## Static credential headers participate in real provider auth resolution (2026-07-29)

### What changed

- `core/provider-header-auth.ts` classifies only credential-like provider headers, preserves case-insensitive
  override semantics, and derives distinct models.json versus extension status sources.
- `core/provider-api-key-auth.ts` resolves credential-bearing provider headers into a genuine header-only
  `AuthResult`, exposes the same result through `checkAuth()`, and leaves metadata-only or empty header maps
  unconfigured. Header-only auth does not fabricate an API-key login method, and OAuth providers remain logged out
  when their only configured headers are request metadata.
- `configuredRequestAuthStatus()` uses the same credential-header contract, keeping synchronous registry reads,
  asynchronous availability snapshots, TUI/RPC status, and request execution aligned.

### Why this belongs in core

- Auth resolution, registry availability, and status projection are package-owned provider-composition seams. An
  extension can supply headers but cannot make the shared model runtime interpret them consistently.

### Coverage

- `test/provider-composer-headers-auth.test.ts` exercises models.json and extension header auth through registry
  availability, `checkAuth()`, `getAuth()`, and runtime streaming, while locking metadata, empty-header, OAuth, API
  key, and `authHeader` behavior.
- `packages/ai/test/auth-headers.test.ts` and `packages/ai/test/openai-header-auth.test.ts` cover the shared
  classification and OpenAI-compatible request path.

### Expected merge conflict zones

- LOW: additive `core/provider-header-auth.ts`, `core/provider-api-key-auth.ts`, and focused regression coverage.
- MEDIUM: `core/provider-composer.ts` auth composition and status projection.

## Provider-agnostic default fallback chain via bare model-id families (2026-08-09)

### What changed

- `core/retry-fallback/expansion.ts` (new): conservative model-family matching (`id === bare ||
  id.startsWith(bare + "-")` after stripping a `.`/`/` namespace, never a substring `includes`), per-provider
  variant selection (exact id > shortest > alphabetical), and provider ranking for bare selectors: providers
  holding an OAuth credential first, then the fixed table `[claude-sdk-oauth, anthropic, kimi-coding]`, then
  alphabetical. `openrouter` / `openrouter-images` are excluded from bare expansion.
- `core/retry-fallback/settings.ts`: the shipped default is now declared with bare model ids -
  `{"claude-fable-5": ["k3:max", "claude-opus-5:xhigh", "claude-opus-4-8:xhigh"]}`. The previous literal
  `anthropic/claude-fable-5 -> apitopia/kimi-k3-unlocked:max, ...` is gone, including the `apitopia` gateway id.
  An empty entry list is no longer deleted at resolve time; it is preserved as a tombstone.
- `core/retry-fallback/chains.ts`: `canonicalizeFallbackChains` expands bare keys into one canonical
  `<provider>/<id>` key per serving provider and bare entries into a ranked, model-major candidate list.
  Explicit provider-qualified keys are applied after expansion so they override it, and tombstones are honored
  at both bare-family and canonical-provider granularity.
- `core/retry-fallback/controller.ts`: the registry dep accepts an optional `isUsingOAuth(model)` so runtime
  candidate selection ranks the same way the `/fallback` display does.
- `core/retry-fallback/validate.ts`: a bare key naming a registered family is valid configuration; a bare key
  matching nothing keeps the original "roles are unsupported" guidance.
- Bare candidates fan out to at most `MAX_PROVIDERS_PER_FAMILY` (2) providers, ranked by auth tier
  (OAuth credential, then any configured credential, then the rest). Auth ranks candidates and never filters
  them: the runtime already skips unauthenticated candidates, and filtering during canonicalization erased the
  chain whenever an availability snapshot was not populated yet.
- `core/extensions/builtin/model-fallback/settings.ts`: `/fallback` renders chains canonicalized against
  `modelRegistry.getAvailable()` so the menu lists only models the user can select, while the runtime keeps
  resolving against the full registry.

### Why

- The default chain was keyed on the literal provider id `anthropic`. Fable 5 attached through any other
  provider - the builtin `claude-sdk-oauth` extension (which mirrors the whole Anthropic catalog via
  `getModels("anthropic")`), a gateway, or Bedrock's namespaced ids - never matched the key, so
  `canonicalizeFallbackChains` dropped the chain, `hasConfiguredChain()` went false, and the default
  `abortServerSideFallback: true` left the session with provider-side fallback blocked and no client chain:
  the exact dead end the 2026-07-29 default was introduced to remove.
- Ranking by auth tier also fixes same-account thrash: when both `claude-sdk-oauth` and `anthropic` serve
  `claude-opus-5`, both now appear as candidates, so a dead account is skipped by cooldown and the live one
  is used instead of exhausting the chain inside one account.
- `apitopia/kimi-k3-unlocked` is a personal gateway id that should never have shipped as a product default.

### QA

- Real-CLI QA (senpi-qa Channel 2, TUI in a pty, isolated sandbox, `PI_OFFLINE=1`): with Fable 5 served only by
  `claude-sdk-oauth` and no `retry.fallbackChains` configured, `/fallback` renders
  `anthropic-subscription/claude-fable-5 -> kimi-coding/k3:max, anthropic-subscription/claude-opus-5:xhigh,
  anthropic-subscription/claude-opus-4-8:xhigh` where the previous default produced no chain at all. That QA run is
  what surfaced both the fan-out cap and the display scoping above; neither was visible to unit fixtures.

### Expected merge conflict zones on next upstream sync

- LOW: `core/retry-fallback/expansion.ts` is additive and fork-local with no upstream counterpart.
- LOW: the default chain literal in `core/retry-fallback/settings.ts`.
- MEDIUM: `canonicalizeFallbackChains` in `core/retry-fallback/chains.ts` was restructured (two passes plus
  tombstones) rather than edited in place.
- LOW: the optional `isUsingOAuth` member on the controller registry dep.
- LOW: the display-scoping helper in `core/extensions/builtin/model-fallback/settings.ts`.

## Anthropic credits_required 429 pins the billing fallback (2026-07-29)

### What changed

- `core/retry-fallback/billing.ts`: `BILLING_ERROR_PATTERN` now matches Anthropic Console credit exhaustion —
  the 429 `rate_limit_error` whose details carry `error_code: credits_required` ("Usage credits are required
  for this model."). The hard-error fallback branch classifies the shape as `billing` instead of `hard-error`.
- `core/retry-fallback/cooldown.ts`: the 30-minute billing suppression bucket covers the same wording instead
  of the 30-second rate-limit bucket that let cooldown-expiry resurrect the dead model.
- Coverage: `test/suite/retry-fallback-billing-swap.test.ts` (pinned swap + classifier rows),
  `test/suite/retry-fallback-cooldown.test.ts` (duration rows); channel-3 real-CLI proof
  `.agents/skills/senpi-qa/scripts/mock-loop-credits-fallback.mjs` (one primary request, `reason: "billing"`
  in fallback.log, final marker streamed by the fallback model).

### Why

- Incident session `019fac55-3531-7d35-92f1-2d740b659c3c` (2026-07-29): `anthropic/claude-fable-5` answered
  429 credits_required. The switch to `apitopia/kimi-k3-unlocked` fired as `transient`, the 30-second cooldown
  expired, and cooldown-expiry reverted the session into the billing-dead fable-5; the chain then thrashed
  fable-5 → kimi-k3 → opus-5 → opus-4-8 → fable-5 until the session was abandoned. Billing-class failures
  never recover on the same account, so the fallback for one must pin from the first failure.

### Expected merge conflict zones on next upstream sync

- LOW: one regex each in `core/retry-fallback/billing.ts` and `core/retry-fallback/cooldown.ts`; both modules
  are fork-local.

## From-source real-config warning (2026-07-29)

### What changed

- New `from-source-config-guard.ts`: pure predicates detecting a run from TypeScript sources (module URL extension, never a bun binary) whose resolved agent dir is the real `~/.senpi/agent` with no `SENPI_CODING_AGENT_DIR` override.
- `main.ts` prints one yellow stderr warning right after agent-dir resolution when that combination holds, advising an isolated agent dir for dev/QA runs. No change to `resolveAgentDir` precedence or any default.

### Why

- Ad-hoc from-source runs inside the repo (which has `.senpi/` without `agent/`) silently target the real user config; that exact setup has previously leaked writes into the user's `settings.json`. Detection is separated from policy: the warning makes the footgun visible without breaking legitimate real-config runs.

## Interactive startup loading indicator (2026-07-29)

### What changed

- New `cli/startup-loading-indicator.ts`: single-line dim ANSI spinner (`⠋ Loading senpi… <phase>`) with a
  120ms grace delay (fast startups stay flash-free), phase updates, pause/resume, and an idempotent `stop()`
  that clears the line and restores the cursor (also via a `process` exit hook). It engages only when
  `appMode === "interactive"`, stdout is a TTY, and `--help` was not requested.
- `main.ts` starts the indicator before `createAgentSessionRuntime` — the extensions/models/trust window that
  previously rendered nothing — switches the phase to `opening session` before the initial session is created,
  and stops it in a `.finally` before any other stdout writer (TUI, help, diagnostics) takes over.
- Mid-load project-trust prompts (`createProjectTrustContext` `ui.select`/`confirm`/`input`) are wrapped by
  `pauseIndicatorDuringPrompts`, so the trust selector TUI never fights the spinner for the terminal.
- Coverage: `test/startup-loading-indicator.test.ts` (grace delay, frame animation, phase updates,
  pause/resume, stop idempotency, TTY/help gating, prompt-pause wrapping).

### Why

- Interactive startup completed the entire heavy runtime creation before the TUI existed, leaving the terminal
  blank and apparently stuck (QA repro: ~23s of empty screen with a slow-loading extension). Codex's TUI
  addresses the same window by rendering a dim placeholder header until the session is configured
  (`codex-rs/tui` chatwidget); this is the minimal-conflict equivalent for senpi's pre-TUI bootstrap window.

### Expected merge conflict zones on next upstream sync

- LOW: the import block and indicator wiring around `createAgentSessionRuntime` in `main.ts`; the module itself
  has no upstream counterpart.
- LOW: the `projectTrustContext` fallback wrap inside `createRuntime`.

## Repeated provider-stream stalls escalate to the fallback chain (2026-07-29)

### What changed

- `core/agent-session.ts`: the transient retry branch tracks consecutive provider-stream stalls
  (`isProviderStreamStallError` from pi-ai, covering both the idle-timeout and stream-start-timeout wordings). The second consecutive stall escalates to the fallback chain
  immediately (same `tryFallback("transient")` path as budget exhaustion); without a chain the retry loop ends
  instead of replaying the identical payload for the remaining same-model budget. Non-stall failures reset the
  streak, fallback switches and fresh retry loops start at zero.
- Coverage: `test/suite/retry-fallback-stall-escalation.test.ts` (escalation with chain, surrender without chain,
  streak reset for non-consecutive stalls).

### Why

- A stall means the provider accepted the request and delivered zero events for the entire idle budget
  (`httpIdleTimeoutMs`, default 300s). Each retry replays an identical payload, so a hung provider/gateway
  previously cost (1 + maxRetries) * 300s (~20 minutes) of opaque dead air per turn before the chain was
  consulted - experienced as a permanently wedged session (Discord report 2026-07-29, donated session
  019fa8da-43ad-70b7-b01b-8f34f4d907f2 records 1906/1919: reopening a 5h session hit the 300s idle timeout on
  every goal-continuation while new sessions worked).

### Expected merge conflict zones on next upstream sync

- MEDIUM: `_handleRetryableError` transient branch and the `switchedFallback` reset in `core/agent-session.ts`.

## Availability-aware default Fable fallback chain (2026-07-29)

### What changed

- `core/retry-fallback/settings.ts` now owns retry setting types and normalization, including the shipped default
  `anthropic/claude-fable-5` chain:
  `apitopia/kimi-k3-unlocked:max` -> `anthropic/claude-opus-5:xhigh` ->
  `anthropic/claude-opus-4-8:xhigh`.
- The default applies only when `retry.fallbackChains` is absent or malformed. Explicit chain maps, including
  an explicitly empty map, remain authoritative.
- `core/retry-fallback/chains.ts` and the model-fallback builtin omit unavailable models and remove chains with
  no usable candidates, so runtime selection and `/fallback` display agree.
- Existing defaults remain enabled: model fallback on, server-side fallback abort on, and cooldown-expiry revert.
- Coverage: `test/settings-manager-retry-fallback.test.ts`,
  `test/suite/model-fallback-command.test.ts`, and `test/suite/model-fallback-host-wiring.test.ts`.

### Why

- A fresh Senpi install previously aborted provider-side fallback by default but had no client chain, producing a
  dead-end warning. Shipping the preferred chain makes that default policy actionable while keeping optional model
  providers safe: missing models are skipped rather than warned about or selected.

### Expected merge conflict zones on next upstream sync

- LOW: retry settings imports and delegation in `core/settings-manager.ts`; the new retry settings module has no
  upstream counterpart.
- LOW: canonical chain construction in `core/retry-fallback/chains.ts`.
- LOW: registry-aware loading in `core/extensions/builtin/model-fallback/`.

## Stream-start timeout wiring and unregistered-api error context (2026-07-29)

### What changed

- `core/settings-manager.ts`: new `retry.provider.streamStartTimeoutMs` setting and
  `getAgentStreamStartTimeoutMs()` (default 90000ms; 0 disables; the default is clamped to a
  shorter idle timeout and disabled together with a disabled idle guard). `core/sdk.ts` and the
  interactive settings handler wire it into `Agent.streamStartTimeoutMs`.
- `core/provider-composer.ts`: the stream-time `No API provider registered for api: <api>` error
  now names the model (`provider/id`) and points at the models.json provider entry or the missing
  provider extension.
- Coverage: `test/settings-manager.test.ts` (retry describe), `test/provider-composer-unknown-api.test.ts`,
  `packages/ai/test/retry.test.ts` (stream timeout wordings stay retryable).

### Why

- Incident (donated session log): a dead upstream accepted requests but never sent a first byte.
  With only the 300s idle bound, each turn attempt froze the session for 5 minutes with `usage: 0`
  and nothing persisted; retries repeated the same 300s wait, making the session practically
  unrecoverable while new sessions worked. A 90s first-event bound with the retryable wording lets
  the retry/fallback ladder engage quickly. Related incident error `No API provider registered for
  api: kiro-api` carried no context about which model or config produced it.

### Expected merge conflict zones on next upstream sync

- LOW: one settings getter + one field in `ProviderRetrySettings`; one error message in
  `composeModelProvider`; one option in the `Agent` construction in `core/sdk.ts`.

## Provider idle retries preserve user input and use a bounded retry budget (2026-07-29)

### What changed

- `core/agent-session.ts`: retries triggered by the shared anchored provider-timeout classifier defer queued steering
  and follow-up input from the retry's first provider request. This covers the two agent-loop stream watchdog messages
  and exact transport-level `Request timed out` variants without matching incidental command, MCP, or extension text.
- `core/settings-manager.ts`: `retry.provider.streamRetryTimeoutMs` configures the first-request retry liveness cap
  (default 30 seconds; `0` disables). The retry clamps only enabled idle/start guards, so it never re-enables an
  explicitly disabled guard. Both timeout bounds return to their configured values for later provider requests.
- The retry start bound is capped as well as the provider request option, while the configured idle timeout resumes
  after the first event so healthy reasoning gaps are not limited to 30 seconds.
- Consecutive transport timeouts reported with `stopReason: "aborted"` keep consuming the same retry counter. Only a
  genuinely successful assistant response resets the budget or emits `auto_retry_end { success: true }`.
- Retry continuations use the session-work barrier and revalidate atomically with the scheduled-continuation path.
  Accepted recompaction stays queue-first while retaining timeout options; reconstructed failed assistant tails are
  retired before continuation. A concurrent low-level `Agent.prompt()` is treated as a benign takeover, and session
  settlement is never emitted while Agent core is still streaming.
- Coverage: `test/suite/regressions/provider-idle-recovery.test.ts` pins exact request text/order, configurable timeout
  sequences, disabled guards, negative classifier shapes, and a real no-first-event stream expiry at the cap;
  `test/settings-manager.test.ts` pins setting defaults and `0` semantics.

### Why

- A silent provider stream previously consumed user steering into another full-length retry. Repeated 300-second
  retries made the session look stuck and could leave the user's `continue` adjacent to an error instead of a real
  answer.

### Expected merge conflict zones on next upstream sync

- MEDIUM: `core/agent-session.ts` retry-controller continuation options and scheduled-continuation admission.
- LOW: `core/settings-manager.ts` provider retry settings and timeout getters.

## Absent fallback chains no longer produce a startup warning (2026-07-28)

### What changed

- `core/retry-fallback/validate.ts`: `validateFallbackChains(undefined, registry)` now returns no warnings. Explicit malformed values such as `null` and arrays still produce `Fallback chains must be a plain object.`
- Coverage: `test/suite/retry-fallback-validate.test.ts` pins the absent-setting case.

### Why

- `retry.fallbackChains` is optional. A fresh configuration without the setting previously emitted a misleading startup warning even though the user had not configured a malformed chain.

### Expected merge conflict zones on next upstream sync

- LOW: one early return in `validateFallbackChains`.

## Footer shows (OmO Native) when the local omo-senpi + senpi-task stack is installed (2026-07-28)

### What changed

- `core/omo-native-detect.ts` (new): `detectOmoNativeInstall(packages, agentDir)` — sync, dependency-free detection of the "OMO Native" local install. A settings `packages` entry that is a local path resolving to a dir whose package.json name is `@code-yeongyu/omo-senpi`, whose derived repo root (`pluginPath/../../..`) contains both workspace packages `@oh-my-opencode/omo-senpi` and `@oh-my-opencode/senpi-task`. Mirrors gates 1 and 2 of the beta `detectOmoLocalInstall` (beta/omo-local-update.ts), dropping gate 3 (the `git rev-parse --show-toplevel` integrity check) so it stays sync and cheap for footer rendering; the beta module's export policy forbids importing its helpers into production core.
- `core/footer-data-provider.ts`: `FooterDataProvider` gains `setOmoNative(boolean)` / `isOmoNative()` (field-backed, matching the existing `availableProviderCount` injection pattern) and `isOmoNative` is exposed on `ReadonlyFooterDataProvider`.
- `modes/interactive/interactive-mode.ts`: after constructing the provider, calls `setOmoNative(detectOmoNativeInstall(this.settingsManager.getPackages(), getAgentDir()))`.
- Coverage: `test/omo-native-detect.test.ts` pins happy + edge cases; `test/omo-native-footer.test.ts` pins the rendered segment; `test/footer-width.test.ts`, `test/grok/footer.test.ts`, `test/grok/classic-chrome-characterization.test.ts` updated for the new `isOmoNative` Pick member.

### Why

- A senpi session backed by the local OMO source checkout (omo-senpi + senpi-task workspace packages installed as a local-path package) is the "OMO Native" configuration; surfacing it in the footer makes the active stack visible at a glance, mirroring the detection already used by the beta `senpi update` local-update flow.

### Expected merge conflict zones on next upstream sync

- LOW: `core/footer-data-provider.ts` around the `availableProviderCount` field and the `ReadonlyFooterDataProvider` Pick (additive).
- LOW: `modes/interactive/interactive-mode.ts` around the `FooterDataProvider` construction site.
- NEW file `core/omo-native-detect.ts` — no upstream counterpart, no conflict.

## Provider-qualified fallback selectors resolve inside their own provider (2026-07-28)

### What changed

- `core/retry-fallback/chains.ts`: `parseFallbackSelector` now filters the lookup list to the explicitly requested provider before calling `parseModelPattern`. Previously the id pattern was resolved globally, so a foreign id containing the pattern won over the requested provider's exact id: `anthropic/claude-opus-5:xhigh` fuzzy-matched Bedrock's `us.anthropic.claude-opus-5`, failed the provider check, and produced the spurious startup warning `Fallback chain entry ... is not a valid or known model selector.` (The ambiguity arises whenever two configured providers carry the same bare id, e.g. `anthropic` + `anthropic-api`, which makes the bare-id exact match ambiguous and drops resolution into partial matching.)
- Coverage: `test/suite/retry-fallback-chains.test.ts` pins in-provider resolution when `anthropic`, `anthropic-api`, and `amazon-bedrock` all carry colliding `claude-opus-5` ids, with and without a thinking-level suffix.

### Why

- A selector with an explicit provider can only ever resolve inside that provider (the post-check rejected cross-provider results), so global resolution could only turn valid selectors into spurious warnings; scoping converts those failures into the correct in-provider match.

### Expected merge conflict zones on next upstream sync

- LOW: one scoped-lookup block inside `parseFallbackSelector` in `chains.ts`; upstream edits to selector parsing will conflict trivially.


## Paste markers survive editor hand-off and setText round-trips (2026-07-28)

- `modes/interactive/interactive-mode.ts` `setCustomEditorComponent()` now transfers editor content safely when switching between the default and a custom editor: if both editors support the paste-state API (`getPasteState`/`setPasteState` from pi-tui), the raw text plus the registry snapshot are transferred so `[paste #N ...]` markers stay collapsed; otherwise it falls back to the expanded text — `getExpandedText?.()`, or expansion from the paste snapshot via the exported `expandPasteMarkers()` when the source implements `getPasteState` without `getExpandedText`, or the raw text when neither capability exists. Previously the raw text alone was copied into a fresh editor with no registry, turning live markers into dead literals and silently dropping the pasted body from the submitted prompt.
- The companion tui change (`packages/tui/src/changes.md`, same date) makes `Editor.setText()` prune (exact canonical-marker match) instead of clear the paste registry, which fixes the remaining same-instance round-trips: `showExtensionCustom()` save/restore and `restoreQueuedMessagesToEditor()` / `abortAndFireQueuedMessages()` draft restoration. Those call sites are unchanged.
- Symptom fixed: transcript/session showed only the `[paste #1 +18 lines]` placeholder as the user message after pasting, opening a dialog (or aborting with queued messages), and submitting.
- `setCustomEditorComponent(undefined)` is now a draft no-op when the default editor is already active (e.g. `resetExtensionUI()` calls it unconditionally during extension resets): no hand-off happens, so no setText round-trip touches the user's draft.
- Details for the interactive hand-off live in `src/modes/interactive/changes.md` (same date).
- Coverage: `test/suite/regressions/0000-editor-paste-marker-transfer.test.ts` drives the real `setCustomEditorComponent` (prototype + fakeThis pattern) with real tui editors: registry transfer to a paste-aware editor, expanded-text fallback for a plain `EditorComponent`, restore to the default editor, full plain-editor round-trip, and the same-instance no-op.

## Prompt-cache-aware foreground tool budgets (2026-07-28)

### What changed

- `core/settings-manager.ts`: new `PromptCacheSettings` (`cacheAwareTimeouts?: boolean` default true,
  `safetyBufferSeconds?: number` default 30) exposed as `Settings.promptCache`.
- `core/prompt-cache-budget.ts` (new): `resolvePromptCacheSafeWaitSeconds(model, settings, env)` =
  pi-ai's resolved cache TTL minus the safety buffer, or `undefined` when the feature is disabled, no model
  is active, the TTL is unknown, or the buffer swallows the whole TTL. Also exports
  `PROMPT_CACHE_SAFE_WAIT_ENV` and `DEFAULT_PROMPT_CACHE_SAFETY_BUFFER_SECONDS`.
- `core/agent-session.ts`: `resolvePromptCacheSafeWaitSeconds()` recomputes from the LIVE current model, and
  `syncPromptCacheSafeWaitEnv()` mirrors it into the advisory `PI_PROMPT_CACHE_SAFE_WAIT_SECONDS` env var
  (deleted when no budget applies) on session start, reload, and every model select — so out-of-process
  readers such as the omo `task` tool can size their own foreground waits.
- The typed `ExtensionContext.getPromptCacheSafeWaitSeconds()` getter is documented in
  `core/extensions/changes.md`.

### Why

- Blocking a foreground tool past the model's prompt-cache lifetime expires the cache and forces a full
  re-read on the next request. Sizing the ceiling by the cache TTL keeps the cache warm, and the still-running
  work is handed to a background session alive instead of being killed.

### Behavior when no budget applies

- Byte-identical to previous behavior: the injected bash default and recommended maximum keep their existing
  values, the policy prompt is unchanged under strict string equality, and the env var is absent.

## Catalog `-fast` variants resolve serviceTier/upstreamModelId without models.json entries (2026-07-28)

### What changed

- `core/provider-composer.ts` `resolveCompatibilityRequestConfig()`: `upstreamModelId` and
  `serviceTier` now fall back to the catalog `Model`'s own optional fields
  (`extensionModel ?? modelDefinition ?? model`), so generated catalog variants such as
  `openai/gpt-5.5-fast` (upstreamModelId `gpt-5.5`, serviceTier `priority`) request the priority
  tier and the upstream wire id with zero models.json configuration. Config and extension model
  definitions keep precedence over catalog defaults.
- Coverage: `test/model-runtime-catalog-service-tier.test.ts` pins the catalog fallback, the
  models.json override path, and end-to-end resolution through `ModelRuntime` (offline).

### Why

- `-fast` pseudo-models previously worked only when hand-declared in models.json; the generated
  OpenAI priority-tier variants (pi-ai `Model.upstreamModelId`/`serviceTier`) were inert without
  this fallback, since the main request path reads both values exclusively through
  `resolveCompatibilityRequestConfig()`.

### Expected merge conflict zones on next upstream sync

- LOW: two-line `??` fallback change in `resolveCompatibilityRequestConfig()`.

## Cancellable `session_before_reload` veto blocks reload while extensions protect live work (2026-07-28)
## Nearest-parent configuration discovery (2026-07-28)

### What changed

- `config.ts`: `getAgentDir()` now honors `SENPI_CODING_AGENT_DIR` first, otherwise finds the nearest ancestor with a real `.senpi/agent` directory before falling back to `~/.senpi/agent`. The exported `resolveAgentDir(cwd, homeDir, envDir)` makes the precedence contract deterministic for callers and tests.
- `nearest-parent-config.ts`: centralizes the bounded upward walk for config directories. It excludes `$HOME` so global configuration remains the fallback layer and refuses symlinked `.senpi` directories.

### Why

- Starting senpi from a nested project directory previously ignored that project's config and always selected the home agent directory.

### Expected merge conflict zones on next upstream sync

- LOW: `config.ts` around `getAgentDir()`; the discovery helper is a focused fork-owned module.


### What changed

- New cancellable extension event `session_before_reload` (`core/extensions/types.ts`, routed through the
  existing session-before machinery in `core/extensions/runner.ts`). `AgentSession.reload()`
  (`core/agent-session.ts`) now returns `{ cancelled: boolean; reason?: string }` and consults the new
  `checkReloadVeto()` BEFORE emitting `session_shutdown`, so a cancelling extension prevents the entire
  teardown on every reload path (`/reload`, `ctx.reload()`, config hot-reload, direct SDK/rpc/print calls).
- Interactive `/reload` pre-checks the veto and surfaces the extension's `reason` as a warning
  (`modes/interactive/interactive-mode.ts`). Docs: `docs/extensions.md` event flow + `#session_before_reload`.
- Coverage: `test/suite/session-before-reload.test.ts` pins veto-aborts-before-shutdown, normal reload
  passthrough, and the side-effect-free `checkReloadVeto()` probe.

### Why

- A reload tears down the extension runtime; extensions running background subagents (omo-senpi task
  runtime) had their children killed mid-flight by `/reload` or a config hot-reload. Only the session owns
  the teardown ordering, so the veto checkpoint must live in core, mirroring `session_before_switch`.

### Expected merge conflict zones on next upstream sync

- LOW: additive event plumbing in `extensions/types.ts` / `extensions/runner.ts`; MEDIUM: head of
  `reload()` in `agent-session.ts` (early-return veto + return-type change).

## Multi-session RPC host initializes the theme before serving sessions (2026-07-28)

### What changed

- `main.ts`: the `--mode rpc --multi-session` branch now calls `initTheme(startupSettingsManager.getTheme(), false)` immediately before `runMultiSessionHost(...)`. The host returns `Promise<never>`, so the pre-existing `initTheme()` call further down `main()` is unreachable on this path and the theme proxy stayed uninitialized for the whole host lifetime.
- Regression: `test/suite/regressions/0000-multi-session-theme-init.test.ts` spawns the real CLI in multi-session mode with a global extension that touches `theme` at load time and opens a session; pre-fix the extension load crashes with "Theme not initialized. Call initTheme() first." (surfaced by embedders such as T3 Code as transcript errors), post-fix the probe loads and the transcript stays clean.

### Why

- Extensions load per `open_session` inside the multi-session host, and any extension (or render helper) that reads the `theme` proxy crashed the session with "Theme not initialized". An extension cannot fix this ordering itself: the theme must be initialized by the host bootstrap before extension code runs, so this is a core `main.ts` fix.

### Expected merge conflict zones on next upstream sync

- LOW: one additive call (plus comment) inside the multi-session dispatch branch in `main.ts`; upstream edits to that branch will conflict trivially.

## Experimental `--grok-neo` mode: env-gated grok chrome for the interactive loop (2026-07-26)

### What changed

- New opt-in flag `--grok-neo` (`src/cli/args.ts`, gate `src/cli/grok-neo-gate.ts`): `SENPI_ENABLE_GROK_NEO` accepts `1`/`true`/`yes`, default OFF. When the gate is off the flag is absent from `--help` and parses as an unknown extension flag, exactly as if the feature did not exist. When on, it runs the ordinary interactive mode with the grok chrome (`chrome: "grok"` dispatch in `main.ts`) — same senpi process, no separate binary or daemon.
- New built-in themes `grok-night` and `grok-day` (`src/modes/interactive/theme/grok-night.json` / `grok-day.json`, registered in `getBuiltinThemes()` in `src/modes/interactive/theme/theme.ts`). Precedence: an existing settings theme always wins; `grok-night` is only an in-memory fallback when no theme was ever chosen (`applyGrokNeoThemeFallback` in `main.ts`) and is never written to `settings.json`. `--theme` registers theme resources; it does not select one.
- Chrome components under `src/modes/interactive/grok/`: rounded input card, compact footer (model + cwd only), welcome card, single-line tool rows with a `┃`/`◆` guide column, braille working indicator, and a palette/chrome-token layer that resolves colour through the active theme.
- User docs: `docs/grok-neo.md` (mode, gate, themes, in-process architecture, experimental status, independent-reimplementation and non-affiliation statement) plus a `docs/docs.json` navigation entry.

### Why

- Replaces the removed out-of-process Go TUI with an in-process presentation layer: one process and one deployable directory for the Bun binary (native addons ship as sidecars), with the classic TUI unchanged as the default.

### Expected merge conflict zones on next upstream sync

- LOW: additive seams only — the gate module, one conditional branch each in `args.ts` parse/help, the theme-fallback and `chrome` dispatch lines in `main.ts`, and the `grok-night`/`grok-day` registration in `theme.ts`.

## Extension user-message injections are retained when the prompt path rejects (2026-07-26)

- `core/agent-session.ts`: `sendUserMessage()` now tracks the prompt disposition. When `prompt()` rejects before the message reaches a queue or a turn (e.g. a required compaction that cannot complete, auth/model validation, or provider admission), the message is queued for later delivery (`deliverAs: "steer"` goes to the steering queue, otherwise the followUp queue) instead of being silently dropped. The rejection still propagates, so fire-and-forget extension bindings keep emitting their `send_user_message` error event.
- Root cause of the omo `team_wait` starvation forensics: member self-poller injections via `pi.sendUserMessage(..., { deliverAs: "followUp" })` vanished without a trace when the fresh-prompt path threw, leaving no record in the session JSONL while RPC-path `steer`/`follow_up` commands (which bypass `prompt()`) landed normally.
- Interactive `prompt()` behavior is unchanged: a rejected interactive prompt still drops the input and surfaces the error to the user (pinned by `test/suite/regressions/pre-prompt-compaction-no-continue.test.ts`).
- Coverage: `test/suite/agent-session-extension-injection.test.ts` pins retention for followUp and steer injections, exact-once delivery after recovery through the post-run drain, and no double-queueing on the streaming accept path.

## Reload-safe MCP preservation and extension-removal lifecycle event (2026-07-26)

- `session_extensions_removed` is emitted on the old extension runner when a `/reload` or a session replacement (`/new`, `/resume`, `/fork`, import) rebuilds the extension set. Its payload is `{ type: "session_extensions_removed", reason: SessionShutdownEvent["reason"], removed: Array<{ path, resolvedPath }> }`, allowing an extension that did not survive the rebuild to release resources after the new settings and active builtin set are known.
- Unchanged MCP servers now survive a classic `/reload`: the shared service reattaches and reconciles by config hash, preserving live connections while replacing changed servers and disposing removed ones. Provider-scoped MCP services still dispose on reload because their factory creates a replacement instance.
- If the MCP builtin itself is disabled during a reload or replacement, its removal event disposes the preserved classic service so stdio children cannot leak. For an otherwise wedged server, use `/mcp reconnect <name>` to force a fresh connection.

## Same-model-first transient retries and capped server waits (2026-07-26)

### What changed

- Supersedes the 2026-07-20 entry's sentence "retryable transient failures now switch to a configured fallback ...": transient retryable failures (timeouts, overload, 429, 5xx, transport drops) now retry the same model on the existing exponential backoff until `retry.maxRetries` is spent; only then does the configured `retry.fallbackChains` chain engage, and each fallback candidate starts with a fresh retry budget.
- `core/agent-session.ts`: `retry.provider.maxRetryDelayMs` (default 60000) now bounds the server-requested wait honored on the same model. Beyond the cap the fallback chain engages and the primary is suppressed for the requested duration; the turn fails with an informative error only when no chain candidate is available. Waits at or below the cap are honored as before.
- `core/retry-fallback/cooldown.ts`: timeout and connection/transport errors now carry a 60-second selector cooldown instead of the five-minute unmatched default, so revert-to-primary is no longer blocked for five minutes after one network blip. Existing tiers keep precedence: quota/billing 30 minutes, rate-limit 30 seconds, capacity 45 seconds plus jitter, 5xx 20 seconds, and a provider retry-after hint always wins.
- Unchanged: classifier-refusal fallback (immediate, pinned), hard-error fallback (quota/auth/model-not-found, immediate), and `retry.abortServerSideFallback` (default true) routing provider-side model substitution onto the configured chain.
- Cost/latency: with `retry.maxRetries >= 1` a fully failing chain now costs up to `1 + (chainLength + 1) * maxRetries` provider calls plus per-rung backoff before the turn fails; with `maxRetries: 0` every failure switches immediately, costing `1 + chainLength` calls.
## OMO local plugin remote-diff updater beta on bare `senpi update` (2026-07-26)

- A bare `senpi update` now triggers the beta OMO local-update hook (`src/beta/omo-local-update.ts`, reachable only through the two BETA-marked touch points in `package-manager-cli.ts`) before any self-update work. The hook compares the state of the two packages (`omo-senpi` + `senpi-task`) on `origin/dev` of the OMO source checkout against the locally installed modules, and updates the local install ONLY when they differ.
- The user's checkout receives ZERO git mutations: the hook performs one read-only `git fetch origin dev`, builds in a feature-owned persistent worktree under the agent directory, and atomically swaps the installed plugin directory by rename. No checkout/branch/commit/merge/reset/clean/stash/push ever touches the user's tree.
- `SENPI_OMO_LOCAL_UPDATE=0` is a kill-switch that disables the hook entirely. All failures are non-fatal: the hook never throws and never sets `process.exitCode`; any error downgrades to a warning plus a manual-update hint so the `senpi` self-update proceeds untouched.
- Fast path (2026-07-29): the skip decision now compares a build-input fingerprint of `origin/dev` (`src/beta/omo-local-update-fingerprint.ts`: sha256 over root tree entries minus documentation/agent-config paths) instead of the bare commit sha, so docs/CI-only churn in the omo monorepo no longer triggers the ~30s rebuild. When a rebuild IS needed, the bare-update foreground now only fetches and compares (~1s) and hands the build to a detached worker (`src/beta/omo-local-update-worker.ts`, hidden `senpi update --omo-local-update-worker` flag, output to `<agentDir>/omo-local-update/worker.log`); the worker serializes through the existing pid lock and swaps/stamps exactly like the former inline path. `SENPI_OMO_LOCAL_UPDATE_SYNC=1` restores the old blocking foreground behavior.
- The fast skip also checks the updater's current required-artifact contract independently of the historical stamp inventory. A legacy, stale, or externally damaged stamp can no longer hide a missing packaged LSP daemon CLI; the next update rebuilds and atomically repairs the plugin.
- Removal is exactly three steps: delete all `src/beta/omo-local-update*.ts` files; delete all `test/omo-local-update*` files; delete the BETA-marked touch points (the import, the hook calls, and the `--omo-local-update-worker` flag) in `package-manager-cli.ts`.
- CodeGraph cleanup (2026-09-02): `src/beta/omo-local-update-fingerprint.ts` drops `.codegraph` from `EXCLUDED_ROOT_PATHS`. The omo product removed its CodeGraph integration, so that directory is never created and excluding it from the fingerprint no longer skips anything.

## App-server daemon launch diagnostics and hermetic lifecycle coverage (2026-07-24)

- The daemon launcher now classifies websocket listener occupancy before spawn: a compatible app-server answers `initialize` and attaches, while any other TCP listener fails immediately with an `EADDRINUSE` diagnostic instead of consuming the child readiness budget. Child-process startup stderr still accompanies actual post-spawn failures, and each launch replaces stale diagnostics.
- The real-CLI daemon lifecycle test isolates home/XDG state, verifies the pre-spawn occupied-port diagnostic and that it does not create a child stderr log, retries the bounded QA port pool, and awaits lock/process events rather than polling sleeps.

## Manual compaction keeps agent lifecycle subscription through abort (2026-07-24)

- `core/agent-session.ts`: manual or extension-initiated compaction claims its synchronous admission/barrier first,
  then aborts and waits for the active agent run while still subscribed. The abort's `agent_end` now clears the
  active-run and retry state before compaction disconnects for summary generation; all disconnected exits reconnect.
- Regression: `test/suite/compaction-race.test.ts` covers compaction during a live provider stream and asserts the
  aborted `agent_end` precedes compaction startup without deadlocking future prompts.

## Removed the legacy `--neo` Go TUI surface (2026-07-26)

### What changed

- Removed the Go TUI launcher, daemon dispatch, CLI flags, settings, documentation, build gate, and the retired Go package. The classic interactive and `--mode rpc` paths remain unchanged.
- Migrated generic RPC authentication and connection-handler framing coverage into `test/suite/rpc-auth-and-connection-handler.test.ts` before deleting the legacy-specific suites.

### Why

- The legacy out-of-process TUI and its daemon are no longer part of the supported CLI surface.

### Expected merge conflict zones on next upstream sync

- LOW: removal-only changes across fork-owned legacy surfaces.

## Inspector handoff and VM-import crash isolation (2026-07-24)

### What changed

- The launcher closes an inherited startup Inspector endpoint immediately before spawning `cli-main`, allowing the
  child process to bind the same configured endpoint instead of failing with `address already in use`.
- With `SENPI_RECOVER_INSPECTOR_VM_IMPORT=1` set at process start, interactive mode recovers only the exact unhandled
  Inspector-eval rejection produced when `import()` runs without a VM dynamic-import callback. Recovery is fail-closed
  by default; application-owned VM failures and unrelated uncaught exceptions remain fatal.

### Why

- The launcher and child previously inherited one fixed Inspector port, so developers attached to the wrapper rather
  than the TUI process. Running asynchronous `import()` in Node's Inspector VM then terminated the attached process.
  Node exposes no non-spoofable Inspector provenance on the global exception, so continuing requires an explicit
  developer opt-in rather than weakening the default fatal boundary.

### Why extension system couldn't handle this

- Inspector ownership is decided before extensions load, and process-wide uncaught-exception handling belongs to the
  host's terminal-restoration boundary.

### Expected merge conflict zones

- LOW: `cli.ts` immediately before the `cli-main` spawn.
- LOW: `modes/interactive/interactive-mode.ts` uncaught-exception handler.

## Reload measurement and redundant-work removal (2026-07-26)

- `/reload` records a `reload` timing namespace with one marker per phase
  (`shutdown`, `settings`, `models`, `resources`, `runtime`, `chatRebuild`,
  `lifecycle`). With `PI_TIMING=1` the breakdown is appended to the reload
  status line; with it unset nothing is recorded.
- Settings are read once per reload instead of twice.
  `ResourceLoaderReloadOptions.settingsAlreadyReloadedFor` takes the
  `SettingsManager` the caller just reloaded, and the loader skips its own
  reload only when that is the very manager it owns AND project trust is not
  being resolved, so trust-scoped values can never go stale.
- `ModelRuntime.reloadConfig()` delegates to `refresh()` instead of repeating
  the config load and provider rebuild that `refresh()` performs immediately
  afterwards.
- Both model-scope resolutions read the snapshot the reload refresh just
  produced rather than each triggering another availability scan (3 scans -> 1).
  The snapshot is trusted only via `hasFreshAvailabilitySnapshot()`; a failed
  refresh falls back to the runtime so scan errors still surface.
- `scripts/bench-reload.mjs` measures `DefaultResourceLoader.reload()` from
  source through a subprocess probe (real jiti path), reporting cold-first and
  warm p50/p95 across fresh processes.
## Multi-session RPC mode, session-owned MCP/config-reload state, and back-compat guarantee (2026-07-23)

### What changed

- `src/modes/rpc/`: new `--multi-session` startup flag. `senpi --mode rpc --multi-session`
  constructs NO default session (no default `AgentSessionRuntime`, no default extension/watcher load).
  Mode is fixed at process start; there is no runtime transition. New modules: `session-registry.ts`,
  `session-command-router.ts`, `session-binding.ts`, `multi-session-host.ts` (each ≤250 pure LOC).
- Multi-session wire protocol per the D1 normative table (see `docs/rpc.md` → Multi-session mode, and
  the `rpc-mode.ts` header doc block for the verbatim table): `get_protocol_info` (answered in BOTH
  modes; side-effect-free; THE capability probe), `open_session` / `close_session` / `list_sessions`,
  mandatory `sessionId` routing on session-scoped commands, `sessionId` tagging on all session-owned
  output, stable error codes (`unknown_session`, `session_closing`, `session_path_in_use`,
  `missing_session_id`, `multi_session_disabled`, `invalid_path`, `open_failed: <detail>`), identities
  (D6: response-level `sessionId` = opaque routing handle, ephemeral per process epoch;
  `state.sessionId` = durable JSONL identity), and the D9 ordering guarantee (strict FIFO per session,
  one total stdout order, fair round-robin between sessions' queued complete records, NO cross-session
  batch coalescing, starvation freedom NOT promised).
- `src/core/extensions/builtin/mcp/` and `src/core/extensions/builtin/config-reload/`: in multi-session
  mode each session OWNS its MCP service instance (extension factory closes over it; helpers take the
  instance, never call the `getMcpService()` global getter), its elicitation/instructions/prompts state,
  and its `reloadHandoff` keyed by the session handle. Classic single-session mode keeps the globals
  (no behavior change).
- Session-owned config-reload state: the fs-watcher reload chain
  (`config-reload/index.ts` → `agent-session.ts:3807` `resetApiProviders()`) is scoped per session via
  the pi-ai provider scope, so reloading session A cannot reset session B's providers.

### Why

- A single shared `senpi --mode rpc --multi-session` process serves all of a provider instance's
  threads concurrently. Cross-session turns run concurrently; per-session turn serialization comes
  from `AgentSession`. Session-scoped state (provider registry, MCP, config-reload) must be owned by
  the session so one conversation can never corrupt another.

### Back-compat guarantee

- Classic single-session mode (`senpi --mode rpc`, no flag) is byte-identical to today. The ONLY
  additive classic-mode behavior is that `get_protocol_info` is answered (side-effect-free). Existing
  RPC tests, the classic-compat characterization pin suite, and the neo-daemon suites stay green
  unchanged.

### Explicit non-goal

- Per-session AuthStorage / multi-tenant key isolation is NOT added inside the shared process. The
  process is single-tenant; tenancy isolation remains the neo daemon's job (per-connection worker
  model). The neo daemon's behavior and its header distrust rationale are unchanged.

### Why extension system couldn't handle this

- Session lifecycle, the multi-session host/router/registry, MCP service ownership, and config-reload
  handoff are protocol and core-runtime infrastructure below the extension boundary.

### Expected merge conflict zones on next upstream sync

- HIGH: `src/modes/rpc/` (new multi-session modules + `rpc-mode.ts`/`connection-handler.ts` seams).
- MEDIUM: `src/core/extensions/builtin/mcp/service.ts` global getter removal on the multi-session path.
- LOW: `src/core/extensions/builtin/config-reload/index.ts` reloadHandoff keying.

## App-server web-search projection and cumulative turn diffs (2026-07-21)

### What changed

- `modes/app-server/threads/`: projects only OpenAI `web_search_call` metadata into the structured Codex `webSearch`
  shape, preserves readable generic provider-native items for other subtypes, and emits subscriber-only
  `turn/diff/updated` notifications rebuilt from per-tool patches in file-change source order.
- `core/tools/` and `core/extensions/builtin/gpt-apply-patch/`: preserve source-backed unified patches for real edit,
  write, multi-file, partial-success, repeated same-path, dependent sequential, and move-only results.
- Non-empty app-server `fileChange` changes use the generated v2 tagged kind shape; moves retain the source path,
  expose the destination in `move_path`, and carry an applicable delete/add-or-update representation.
- `test/suite/` and `test/qa/app-server/`: cover final web-search payload fidelity, concurrent completion ordering, real
  mutation result shapes, per-turn reset, notification envelopes, subscriber routing, and a zero-token source-CLI run.

### Why

- Codex app-server clients render native web-search activity and live file-change previews from these item and
  notification contracts; synthesized fields and missing diffs break that client experience.

### Why extension system couldn't handle this

- Provider-native item projection, turn-scoped diff state, and subscriber notification routing are app-server protocol
  infrastructure below the extension boundary; source patches must be captured by each mutation tool before apply.

### Expected merge conflict zones on next upstream sync

- LOW: the fork-only `modes/app-server/threads/projection*.ts` implementation and its app-server QA fixtures.
- MEDIUM: write/apply_patch result details where source baselines are captured.

## Fuzzy file search one-shot and sessions (2026-07-21)

### What changed

- `modes/app-server/search/`: added bounded deterministic file traversal, subsequence scoring, same-token one-shot
  cancellation, and replaceable query sessions with latest-query update and completion notifications.
- `modes/app-server/runtime.ts` and `server/notifications.ts`: registered the stable one-shot method plus the three
  experimental session methods, routed the two stable session notifications globally, and cancelled outstanding work on
  runtime teardown.
- `test/suite/` and `test/qa/app-server/`: pinned traversal/scoring limits, cancellation and session races, request
  gates, ungated notification fanout, manifest status, and a zero-token source-CLI fixture-tree scenario.

### Why

- Codex clients use fuzzy file search for path completion and rely on cancellation tokens and long-lived sessions to
  avoid stale results while a query changes rapidly.

### Why extension system couldn't handle this

- File-search requests and global app-server notifications are transport-level JSON-RPC behavior below the extension
  boundary.

### Expected merge conflict zones on next upstream sync

- LOW: the fork-only `modes/app-server/search/` implementation and app-server registration/router allowlists.

## Wave 2 app-server parity verifier corrections (2026-07-20)

### What changed

- `modes/app-server/protocol/`: corrected fuzzy-search result keys to Codex's snake-case wire names and completed the
  handwritten thread-item/history facade so runtime modules no longer import generated protocol files directly.
- `modes/app-server/threads/`: made source-kind parsing strict, applied Codex's interactive-session default when search
  source filters are omitted or empty, rejected malformed search `u32`/boolean fields, separated user-activity recency
  from general updates, persisted unarchive timestamp bumps, rejected non-`u32` history limits, preserved every
  projected history-item variant plus completed-turn lifecycle data, read cold history without loading the thread,
  deferred compact work and `item/started` until after the RPC acknowledgement, and recorded rejected compactions as
  failed without fabricating a completed item.
- `modes/app-server/server/models.ts`: validates `remoteControl/client/list` parameters before returning the honest
  no-remote-control internal error.
- `test/qa/app-server/`: extended the Todo 8–12 drivers for the rejected edge cases and made the compaction fixture
  exercise explicit manual compaction without being preempted by automatic compaction.

### Why

- Independent parity verification found boundary-validation, persistence, timestamp, import-layer, and failure-path
  mismatches that the first wave's happy-path tests did not distinguish from Codex HEAD behavior.

### Why extension system couldn't handle this

- These contracts are JSON-RPC parsing, thread persistence/projection, and app-server lifecycle behavior below the
  extension boundary.

### Expected merge conflict zones on next upstream sync

- LOW: the fork-only `modes/app-server/` and app-server QA surfaces. Preserve Codex wire names and re-run the focused
  verifier drivers if upstream session timestamp or compaction behavior changes.

## Codex HEAD app-server catalogs, facade, and terminal envelopes (2026-07-20)

### What changed

- `modes/app-server/protocol/`: aligned method catalogs with the pinned Codex HEAD source, added complete experimental
  notification metadata, and added handwritten facade types for the catalog, config, account, collaboration-mode,
  fuzzy-search, thread-parity, terminal-error, and notification-envelope surfaces selected by the parity plan.
- `modes/app-server/server/connection.ts`, `server/notifications.ts`, `rpc/envelope.ts`, `rpc/ndjson.ts`: gate
  experimental notifications from the shared catalog and populate one `emittedAtMs` timestamp per notification before
  fanout, preserving it through final transport serialization while leaving server requests untouched.
- `modes/app-server/server/server-core.ts`: added post-response deferred actions so later thread handlers can guarantee
  response-before-notification ordering.
- `modes/app-server/threads/turns.ts`, `turn-adapter.ts`, `threads/projection.ts`: replaced the fork-only terminal
  `turn/failed` wire event with Codex HEAD's ordered `error` plus failed `turn/completed` pair, sharing one `TurnError`.
- `modes/app-server/server/models.ts`: moved model catalog runtime typing onto the handwritten facade while retaining the
  existing remote-control behavior for its dedicated follow-up task.

### Why

- Codex's generated TypeScript exporter omits experimental request roots and cannot by itself describe the live HEAD
  catalog. Senpi needs a stable, Node-compatible facade derived from both the pinned source inventory and generated
  evidence.
- Current Codex clients expect populated notification timestamps, capability-aware experimental delivery, and terminal
  failures expressed through the canonical error/completion pair.

### Why extension system couldn't handle this

- Method catalogs, transport envelopes, response-frame ordering, and terminal event projection are app-server protocol
  infrastructure that runs outside the coding-agent extension surface.

### Expected merge conflict zones on next upstream sync

- LOW: the fork-only `modes/app-server/` tree. Re-derive catalogs and facade shapes from the new Codex source before
  resolving conflicts; never hand-edit `protocol/generated/**`.

## Parallel side questions via `/btw` (2026-07-21)

### What changed

- New builtin extension `core/extensions/builtin/btw/` adds `/btw <question>`: a read-only side LLM query against a synchronously captured snapshot of the current conversation, running in parallel with any in-flight main turn without writing to session history. Details in `core/extensions/builtin/btw/changes.md`.
- TUI: the answer streams into a dismissable widget above the editor; Escape dismisses the side panel without touching main-turn Escape behavior. Non-TUI modes deliver the answer via `ctx.ui.notify`.
- `core/extensions/builtin/index.ts` registers the extension between `goal` and `mcp`.

### Why

- Asking a question about the ongoing session previously required waiting for the main turn and polluting its context. `/btw` answers immediately, in parallel, and leaves the main session untouched.

## Claude text tool-call recovery (2026-07-20)

### What changed

- `core/model-runtime.ts`: both streaming entry points conditionally wrap prepared provider streams through the side-effect-free AI recovery API, using the original selected model and non-empty tools while keeping provider retries/auth/request preparation underneath a single wrapper.
- `core/model-config.ts` and `core/provider-composer.ts`: custom definitions, built-in overrides, and extension models accept the top-level tri-state `recoverTextToolCalls` boolean without using `compat`.
- Session and agent-loop integration tests prove complete and truncated raw Anthropic/OpenAI SSE recovery, safe non-execution, persisted native history, provider-native next-turn replay, original historical XML preservation, and retry-attempt isolation.
- The isolated senpi-qa mock loop now exposes complete/truncated leak modes for both supported APIs, hashes real auth before/after, and captures cleanup/evidence receipts.

### Why

- Provider-specific middleware cannot enforce the cross-provider persistence, retry, abort, ordering, and execution boundaries required after a model leaks XML as assistant text.

- `core/agent-session.ts` and `core/retry-fallback/controller.ts`: non-retryable provider errors now advance immediately through an eligible fallback chain without replaying the failed model or waiting for backoff. Hard-failing selectors receive the normal session-local cooldown; overflows, aborted responses, refusals, and error responses containing tool calls continue to settle through their existing paths.

- `core/agent-session.ts`: typed classifier refusals now bypass same-model retries and immediately advance through a pinned fallback chain without cooldowns. Switched refusal messages are removed from active context while retained in session history; exhausted chains leave only the final refusal visible.

- `ExtensionContext.sessionSettings` now gives the model-fallback builtin the live session-owned retry settings and retry status; `/fallback` writes are immediately visible to the retry controller, while `--no-model-fallback` and `SENPI_NO_FALLBACK=1` apply a non-persistent session override.

- `core/agent-session.ts` now centralizes active-model switching, preserving manual selection behavior while supporting non-persistent, non-notifying ephemeral fallback switches.
- `core/session-manager.ts` records optional fallback model-change metadata and restores the primary model rather than a fallback-period assistant model after restart.

- `core/retry-fallback/validate.ts`: validate fallback-chain configuration with deterministic warnings.

- `core/retry-fallback/log.ts`: add a bounded, sanitized 0600 NDJSON fallback debug logger.

## Retry fallback settings (2026-07-20)

### What changed

- `core/settings-manager.ts` now persists global per-model retry fallback chains, fallback enablement, and the
  fallback revert policy. Reads provide safe defaults when those optional settings are unset or malformed.
- Project `retry` settings retain the established one-level merge behavior: a project `fallbackChains` map replaces
  the global map rather than merging individual chain keys.

### Why

- Model fallback behavior needs a durable, user-configurable chain without adding another settings file or allowing
  fallback controls to write project settings.


- `core/retry-fallback/chains.ts`: adds pure, canonical selector parsing and fallback-chain resolution.

- `core/retry-fallback/cooldown.ts`: adds per-session, lazy-expiry selector cooldowns with provider retry-after and error-derived durations.

## Accepted compaction resumes the waiting prompt (2026-07-20)

### What changed

- `agent-session.ts`: the pre-prompt fail-closed check now recognizes an assistant response retained behind the latest accepted compaction boundary as historical usage. A prompt waiting on compaction therefore dispatches with compacted history, while cancelled or would-overflow compaction remains blocked before any provider request.
- `agent-session-compaction.test.ts`: added a provider-dispatch regression for irreducibly oversized pre-prompt compaction results.

### Why extension system couldn't handle this

- `AgentSession` owns the compaction boundary, stale usage classification, prompt settlement barrier, and the provider-dispatch decision. Extensions can propose or reject summaries but cannot serialize this state transition.

### Expected merge conflict zones on next upstream sync

- MEDIUM: `agent-session.ts` around `prompt()`, `_checkCompaction()`, and compaction-boundary stale-message checks.

## Model-runtime upstream model id and model-config service tier (2026-07-19)

### What changed

- `core/model-runtime.ts`: `prepareRequest()` now swaps the wire model id to the models.json/extension
  `upstreamModelId`. Previously only the compaction and websearch extensions honored it, so main-loop requests sent
  the configured alias id (e.g. `gpt-5.6-terra-fast`) verbatim and upstreams rejected the unknown model.
- `core/agent-session.ts`: `_currentServiceTier` now falls back to the model's configured `serviceTier` from the
  compatibility request config (models.json / extension model definition) when no scoped/favorite tier is set
  (`_resolveServiceTier`). The builtin service-tier extension then injects `service_tier` into OpenAI Responses
  payloads through `before_provider_request`, so client-configured priority tiers reach the wire.

### Why

- models.json `-fast` pseudo-models declare `upstreamModelId` + `serviceTier: priority` so priority-tier requests are
  client-controlled instead of proxy-side per-model overrides; the main request path must honor them.
  (`extraBody.service_tier` is not a viable channel: it is an OpenAI Responses reserved body key.)

### Why extension system couldn't handle this

- `prepareRequest()` is the core chokepoint every stream/complete call funnels through; extensions cannot rewrite the
  wire model id for the main loop, and the builtin service-tier extension only sees the session tier, which never
  reflected model-level configuration.

### Expected merge conflict zones on next upstream sync

- LOW: `model-runtime.ts` `prepareRequest()` body; `agent-session.ts` service-tier assignment sites.

## Paced streaming tool argument previews (2026-07-20)

### What changed

- `modes/interactive/tool-args-reveal.ts` paces append-only partial JSON independently per tool call, reusing the smooth
  streaming FPS and catch-up policy while batching parser work and preserving UTF-16 surrogate boundaries.
- `modes/interactive/interactive-mode.ts` flushes exact arguments before completion or execution and tears down reveal
  state anywhere pending tool components are cleared.

### Why

- Provider bursts should not make large tool-call previews jump or force a full partial-JSON parse for every timer tick.

### Why extension system couldn't handle this

- Pending tool components and their streaming/execution transition state are private to the built-in interactive mode.

### Expected merge conflict zones on next upstream sync

- MEDIUM: interactive tool-call event handling and smooth-streaming settings callbacks.
- LOW: the fork-only reveal controller.

- MEDIUM: interactive tool-call event handling and smooth-streaming settings callbacks.
- LOW: the fork-only reveal controller.

## Smooth streaming reveal (2026-07-20)

### What changed

- `modes/interactive/streaming-reveal.ts`: adds a grapheme-safe, time-based controller that reveals streamed assistant
  text at a stable perceived rate from 30–120fps, catches up bounded backlogs, and flushes immediately at tool-call and
  lifecycle boundaries.
- `core/settings-manager.ts` and the interactive settings selector persist smooth-streaming enablement and FPS.
- `modes/interactive/interactive-mode.ts` routes assistant deltas through the controller and tears it down on final,
  abort, session-switch, and shutdown paths.

### Why

- Provider chunks often arrive in bursts; rendering each burst verbatim makes otherwise fast responses visually jumpy.

### Why extension system couldn't handle this

- The controller owns private in-flight assistant component updates, TUI render scheduling, and session lifecycle state.

### Expected merge conflict zones on next upstream sync

- MEDIUM: interactive assistant event handling and settings-selector plumbing.
- LOW: the fork-only reveal controller and settings accessors.

## Incremental assistant message re-render (2026-07-19)

### What changed

- `modes/interactive/components/assistant-message.ts`: assistant content is now planned as flat render descriptors
  and reconciled against the previous child list. Unchanged children stay mounted, growing text/thinking Markdown
  updates through `Markdown.setText()`, and structural changes rebuild only the divergent suffix.
- `../test/assistant-message-incremental-render.test.ts`: exact raw-render parity covers text, thinking,
  provider-native blocks, error tails, hidden thinking, expansion, and output padding; identity assertions pin the
  incremental reuse contract.

### Why

- Streaming updates previously cleared the entire content container, so every delta recreated all Markdown children
  and discarded their instance render caches even when only the final block grew.

### Why extension system couldn't handle this

- The built-in assistant component owns transcript child identity, disposal, render caching, and OSC marker behavior;
  extensions cannot reconcile its private render tree.

### Expected merge conflict zones on next upstream sync

- MEDIUM: `modes/interactive/components/assistant-message.ts` around content construction and streaming cache reuse.

## Neo launch handoff and daemon dispatch (2026-07-06)

### What changed

- `main.ts`: `--neo` / `--neo-isolated` (+ hidden `--neo-bin`) dispatch to the neo Go TUI launcher (`cli/neo/`),
  spawning the per-platform binary with inherited stdio, forwarded signals, and propagated exit code/signal. Dispatch
  sits after the version/export fast-paths and first-time setup, before any `AgentSessionRuntime` construction or
  extension loading, so the launcher stays thin.
- `main.ts`: `--listen <path>` dispatches to the neo daemon supervisor (see `modes/rpc/changes.md` 2026-07-06). The
  `NeoRuntimeOptions` field list is gated by a generated extraction test over `main.ts` `parsed.*` reads, so new
  runtime-relevant flags fail the test until threaded through.

### Why

- The neo TUI is a separate Go binary; senpi remains the single user-facing entrypoint and must hand off cleanly.

### Why extension system couldn't handle this

- Mode dispatch happens in `main()` before extensions load.

### Expected merge conflict zones on next upstream sync

- MEDIUM: `main.ts` mode-dispatch ordering around startup fast-paths.

## App-server mode dispatch (2026-07-02)

### What changed

- `main.ts`: added dispatch for the fork's `senpi app-server` subcommand into `modes/app-server/` (transports,
  daemon supervision, thread lifecycle), hardened on 2026-07-03 with review fixes (entrypoint split, archive-state
  handling). Arg plumbing is in `cli/changes.md`; the mode directory itself does not exist upstream.

### Why

- Codex-compatible app-server clients need a first-class mode entrypoint next to interactive/print/rpc.

### Why extension system couldn't handle this

- Modes are dispatched from `main()` before extension loading; a wire-protocol server cannot be an extension.

### Expected merge conflict zones on next upstream sync

- MEDIUM: `main.ts` around mode selection and subcommand routing.

## Public model resolution SDK exports (2026-07-02)

### What changed

- `index.ts`: accepted upstream exports for CLI-equivalent model and scoped-model resolution helpers.
- Documentation and examples were updated to describe extension entry renderers and the public SDK surface.

### Why

- External integrations need the same model-resolution behavior the CLI uses without duplicating internal resolver logic.

### Why extension system couldn't handle this

- Public package exports and SDK documentation are package API surfaces. Extensions can consume the exported helpers after
  load, but they cannot publish or document the root module exports themselves.

### Expected merge conflict zones on next upstream sync

- LOW: `index.ts` export list if upstream changes public SDK exports.
- LOW: docs/examples around extension entry renderer examples and model-resolution helper documentation.

## Nested legacy config migration (2026-07-01)

### What changed

- `migrations.ts`: split legacy directory and extension-system migrations into focused modules.
- `legacy-senpi-dir-migration.ts`: migrates missing files from nested legacy `~/.senpi/.pi/agent` and `~/.senpi/.pi/mom` directories into the current senpi config layout without overwriting existing files.

### Why

- Some pre-rename local configs ended up under nested `~/.senpi/.pi/agent`, so a fresh `~/.senpi/agent` could strand custom `models.json` entries such as ccapi-routed Anthropic models.

### Expected merge conflict zones on next upstream sync

- LOW: startup migration orchestration in `migrations.ts`.

## shared provider-native rendering in text output (2026-05-14)

### What changed

- `modes/provider-native-rendering.ts`: added shared provider-native formatting for Anthropic, OpenAI, and Google native web-search metadata, with a generic JSON fallback for unknown provider-native blocks.
- `modes/print-mode.ts`: text print mode now emits provider-native summaries and bodies through the shared formatter instead of silently skipping provider-native content.

### Why

- Native web-search metadata should be readable outside the interactive TUI as well, and the compact rendering rules should stay consistent between interactive and print surfaces.

### Why extension system couldn't handle this

- Print mode emits assistant content directly after the session finishes; extension tool renderers do not own provider-native assistant content.

### Expected merge conflict zones on next upstream sync

- LOW: `modes/print-mode.ts` final assistant-content emission and `modes/provider-native-rendering.ts` if upstream adds its own provider-native formatter.

## CLI export tilde expansion (2026-05-13)

### What changed

- `main.ts`: `senpi --export ~/session.jsonl ~/out.html` expands leading `~` for both the input session path and optional output path before exporting.

### Why

- The interactive `/export` bug also affected the non-interactive export path because Node's path resolution treats `~` as a literal directory name.

### Why extension system couldn't handle this

- `--export` exits before interactive mode and extension command handlers run, so CLI path normalization must happen in `main.ts`.

### Expected merge conflict zones on next upstream sync

- LOW: `main.ts` around the early `parsed.export` branch.

## Senpi self-update release source (2026-05-02)

### What changed

- `config.ts`: Bun-binary self-update fallback now points to `code-yeongyu/senpi` releases.
- `package-manager-cli.ts`: `senpi update senpi` is accepted as the branded self-update target and help text uses senpi wording.
- `package.json`: Repository metadata now points to the senpi fork.

### Why

- Self-update messaging and release metadata should direct users to senpi, not upstream pi-mono.

### Why extension system couldn't handle this

- These are core package metadata and built-in package-command parsing paths that run before extensions participate.

### Expected merge conflict zones on next upstream sync

- LOW: self-update command parsing/help and package metadata.

## Per-model transient retry fallback engine (2026-07-20)

### What changed

- `core/retry-fallback/controller.ts`: added the session-local fallback-chain controller. It canonicalizes configured selectors, suppresses transiently failing models, skips unavailable candidates with scoped logging, applies ephemeral thinking levels, and emits fallback lifecycle events.
- `core/agent-session.ts`: retryable transient failures now switch to a configured fallback without persisting the selected model, emitting a zero-delay retry and retaining the existing failed-assistant removal behavior. A fallback success event is emitted after the next successful response.

### Why extension system couldn't handle this

The retry budget, abortable retry sleep, provider continuation, and active model state all belong to `AgentSession`; an extension cannot safely replace a model inside that lifecycle without persisting it or rebuilding context.
- Retry fallback revert-to-primary at turn boundaries: unpinned fallback state under the `cooldown-expiry` policy restores the original model once its selector cooldown lapses (checked at prompt entry and between the retry sleep and continuation), emits `retry_fallback_reverted`, preserves user thinking-level overrides, and is abandoned on manual `setModel`/`cycleModel` (which also abort a pending fallback retry sleep).
- Server-side fallback aborts (2026-07-25): `retry.abortServerSideFallback` (default true) forwards `abortServerSideFallback` into provider stream options via a new `Agent` field and `createLoopConfig`. `AgentSession` translates the provider's `server_fallback_aborted` diagnostic into a session event of the same name carrying `from`/`to`/`chainConfigured`, emitted synchronously from `message_end` so it precedes refusal retry handling, and the existing refusal path then routes the turn onto the configured chain. `RetryFallbackController.hasConfiguredChain()` distinguishes "no chain configured" from "chain spent", because the no-chain refusal path emits no `retry_fallback_exhausted`. Interactive mode renders the abort and names `/fallback` when no chain exists.

## Session lifecycle stuck-route logging (2026-07-30)

### What changed

- `core/session-log.ts`: new rotating content-free JSONL logger writing `<agentDir>/logs/session.log` (5MB rotate, allow-listed scalar fields, secret redaction, `SENPI_SESSION_DEBUG=1` stderr mirror), following the existing `retry-fallback/log.ts` pattern.
- `core/agent-session.ts`: mirrors stuck-prone lifecycle transitions into `session.log`: `compaction_decision` on every terminal `compaction_end` (reason/accepted/aborted/willRetry/rejectionCause/error), `provider_error` on assistant `message_end` errors classified as stall/timeout/error, `queue_enqueue` on native steer/followUp queueing, and `prompt_rejected` when a `RequiredCompactionError` rejects prompt admission.
- Compaction lifecycle records now correlate start/terminal events with propagated UUID request IDs; classify committed/rejected/failed/skipped/aborted/superseded outcomes; record content-free before/after token estimates; preserve retry exhaustion as a skipped no-attempt action; and ignore stale ends from superseded same-reason attempts instead of attributing them to a newer compaction.
- `test/session-log-routes.test.ts` and the compaction lifecycle suites cover unmatched accepted ends, retry exhaustion, rollback snapshots, extension feedback failures, supersession, same-reason stale ends, consecutive compactions, and start/end request-ID parity without real provider calls.
- `modes/interactive/interactive-mode.ts`: logs `compaction_queue_enqueue` when input is parked during compaction, `compaction_queue_deferred` when a failed compaction defers queued input to the native queues, and `clipboard_error` on clipboard paste failures.

### Why extension system couldn't handle this

The instrumented transitions (`_emit`, queue internals, `RequiredCompactionError` admission, the TUI compaction queue, clipboard catch) are private `AgentSession`/`InteractiveMode` state with no extension-visible hook carrying the needed fields; field debugging of "stuck forever" sessions (Discord report 2026-07-30) requires a single post-hoc timeline in the logs directory.

## 2026-08-25 - Upstream public runtime surface sync coverage

### What changed

- `packages/coding-agent/src/core/agent-session.ts`, `packages/coding-agent/src/index.ts`, `packages/coding-agent/src/modes/rpc/rpc-client.ts`, and `packages/coding-agent/src/modes/rpc/rpc-types.ts` preserve the fork session behavior and public exports while adopting upstream RPC queue clearing and event additions.

### Why

- These runtime and public API paths are directly changed by the upstream sync and require exact nearest-tracker coverage.

### Why this lives in the fork

- Session orchestration and public API exports execute before extension code can compensate for divergence.

### Expected merge conflict zones

- Agent-session event handling, coding-agent barrel exports, and RPC command/client/response unions.

## Upstream sync (upstream/main@71dca871) integration repairs (2026-09-12)

### What changed

- `packages/coding-agent/src/bun/cli.ts`: the Bun entry keeps the fork order: upstream sandbox env setup, then `runtime-setup.ts` (sole Bedrock registration owner, Bun OAuth, process title), then the fork `register-cursor-agent.ts`, then `../cli-main.ts`; upstream's `bun/register-bedrock.ts` deletion was accepted.
- `packages/coding-agent/src/cli.ts`: the fork launcher (Bun re-exec, package-manager command routing, `--version` fast path, bootstrap self-update, startup compile cache, isolated-process decision, inspector policy, dynamic `./cli-main.ts` import); upstream's `cli/setup.ts` is not imported here because `cli-main.ts` performs the same setup for both entry paths.
- `packages/coding-agent/src/config.ts`: fork brand profile (`BRAND`, `APP_COMMAND`, `CONFIG_FLAT_LAYOUT`, `DISPLAY_VERSION`, `ENV_PREFIX`, `resolveAgentDir` with nearest-parent config discovery and flat-layout sentinel), shipped-asset resolution, Bun launcher repair command and the `code-yeongyu/senpi` self-update instruction.
- `packages/coding-agent/src/index.ts`: keeps every fork barrel export (filesystem policy types, `InputDispositionEvent`, MCP declarations, notice primitives, read classifiers, RPC host/daemon helpers and errors, `sanitizeTerminalLabel`, `OAuthCredential`) and drops the PowerShell tool exports upstream still lists; upstream's `CompactionModelOverride` and `CustomEditorOptions` types were added.
- `packages/coding-agent/src/migrations.ts`: the fork migration chain (`migrateEngineStateForBrand` first, `migrateLegacySenpiDirs`, `migrateExtensionSystem`) replaces upstream's in-file commands/prompts and deprecated-dir helpers; upstream's live `earendil-works/pi` doc URLs were taken.

### Why

- Startup ordering, runtime selection, brand/config-dir resolution and the public barrel are where the senpi product identity and its Bun/Node dual runtime live.

### Why an extension could not handle it

- These run before extensions load or define the module surface extensions import from.

### Expected merge conflict zones

- HIGH: `packages/coding-agent/src/cli.ts` top-level flow; `packages/coding-agent/src/index.ts` export list.
- MEDIUM: `packages/coding-agent/src/config.ts` constants block and `getAgentDir`; `packages/coding-agent/src/bun/cli.ts` import order.
- LOW: `packages/coding-agent/src/migrations.ts` migration order.

## 2026-09-12 - Sync CI repair: experimental runtime honors explicit agent dir and spawn context

### What changed

- `packages/coding-agent/src/experimental/server.ts`: `resolveSessionDirectory()` now honors an explicit `PI_CODING_AGENT_DIR` ahead of the branded `getAgentDir()` (SENPI_/OMO_ lanes), so the durable experimental server lists and attaches sessions from the directory its process was actually started with instead of the brand-quarantine default. The ask-user widget's minimal borrowed receiver also stays a prototype call target.
- `packages/coding-agent/src/experimental/process.ts`: spawned internal processes carry the same explicit-dir resolution through their cwd/env instead of inheriting the brand default, so a server child sees its parent's session directory.
- `packages/coding-agent/src/experimental/source-resolver.ts`: the experimental source resolver prefers the explicit `PI_CODING_AGENT_DIR` lane over the branded lane for the same reason; behavior on the plain `senpi` brand is unchanged when the variable is unset.
- `packages/coding-agent/src/experimental/plugins/bundled.ts`: bundled plugin registration carries the explicit agent directory so cold server composition finds its own sessions (upstream CI arbiter: `test/experimental-remote-runtime.test.ts`, 26/26).

### Why

- The upstream durable-server composition contract treats an explicit `PI_CODING_AGENT_DIR` as THE agent-directory override; the fork's branded `envValue` lanes (SENPI_/OMO_ before PI_) shadowed it, so the server listed sessions from an empty quarantine dir and rejected every attach with `Unknown session`.

### Why an extension could not handle it

- The resolution lives inside the experimental server's process bootstrap and spawn plumbing, before any extension runs.

### Expected merge conflict zones

- LOW: `resolveSessionDirectory` and the spawn context construction in `experimental/{server,process,source-resolver}.ts`; upstream only touches these for new composition features.

## OpenAI usage_limit_reached 429 pins the billing fallback (2026-09-22)

### What changed

- `core/retry-fallback/billing.ts`: `BILLING_ERROR_PATTERN` also matches the OpenAI hard-quota exhaustion family — `usage_limit_reached`, `usage_not_included`, "usage limit has been reached" — so the hard-error fallback branch classifies that 429 as `billing` and pins the fallback for the rest of the session instead of leaving it revertable. The family is inlined to keep the module import-free; its single source of truth is `USAGE_LIMIT_EXHAUSTION` in `@earendil-works/pi-ai`'s `utils/retry.ts` (senpi#1969).

### Why

- The account is out of quota, so neither a retry nor a cooldown-expiry revert into the same account can recover it; the session model must not thrash back into the dead primary after the billing cooldown. A configured fallback chain still takes over on the FIRST failure (the senpi-default profile's terminal policy is `immediate-if-eligible`, and the assistant message keeps `stopReason: "error"`), so the switch is pinned as billing-class and survives cooldown expiry; with no chain configured the turn fails on the first attempt.

### Expected merge conflict zones on next upstream sync

- LOW: the single pattern list in `core/retry-fallback/billing.ts`; the module is fork-local.

## 2026-10-02 - Experimental surface stays on the fork harness (upstream v1.0.0 sync)

### What changed

- `packages/coding-agent/src/experimental/client-tui-chat.ts`
- `packages/coding-agent/src/experimental/commands.ts`
- `packages/coding-agent/src/experimental/plugin.ts`
- `packages/coding-agent/src/experimental/services/agent-controller-provider.ts`
- `packages/coding-agent/src/experimental/services/agent-controller.ts`
- `packages/coding-agent/src/experimental/services/models-provider.ts`
- `packages/coding-agent/src/experimental/services/transcript-provider.ts`
- `packages/coding-agent/src/experimental/services/transcript.ts`
- `packages/coding-agent/src/experimental/services/worker.ts`
- `packages/coding-agent/src/experimental/session-worker.ts`
- `packages/coding-agent/src/experimental/durable/harness-setup.ts`
- `packages/coding-agent/src/experimental/durable/main.ts`
- `packages/coding-agent/src/experimental/durable/prompt.ts`
- `packages/coding-agent/src/experimental/durable/runtime.ts`
- `packages/coding-agent/src/experimental/durable/sessions.ts`
- `packages/coding-agent/src/experimental/durable/subagent.ts`
- `packages/coding-agent/src/experimental/durable/tui.ts`
- `packages/coding-agent/src/experimental/vacation/harness-setup.ts`
- `packages/coding-agent/src/experimental/vacation/main.ts`
- `packages/coding-agent/src/experimental/vacation/runtime.ts`
- `packages/coding-agent/src/experimental/vacation/sessions.ts`
- `packages/coding-agent/src/experimental/vacation/tui.ts`
- `packages/coding-agent/src/experimental/vacation/vacation.ts`

The first ten paths stay exactly as in the fork; upstream rewrote them onto its durable package (48dd1e2f0). The `experimental/durable/**` and `experimental/vacation/**` paths are upstream additions built on that package and are not taken.

### Why

The fork's experimental client, worker and transcript services run on the fork harness; the upstream rewrite would import a package the fork does not ship.

### Why an extension could not handle it

These are the experimental client and worker entry points themselves, which sit below the extension API.

### Expected merge conflict zones

Upstream edits to `src/experimental/**`: keep ours for the listed files and keep the durable/vacation trees absent.

## 2026-10-02 - Adopted upstream session, settings and runtime changes (upstream v1.0.0 sync)

### What changed

- `packages/coding-agent/src/cli/args.ts`
- `packages/coding-agent/src/core/agent-session.ts`
- `packages/coding-agent/src/core/extensions/loader.ts`
- `packages/coding-agent/src/core/model-runtime.ts`
- `packages/coding-agent/src/core/remote-catalog-provider.ts`
- `packages/coding-agent/src/core/sdk.ts`
- `packages/coding-agent/src/core/settings-manager.ts`
- `packages/coding-agent/src/index.ts`
- `packages/coding-agent/src/main.ts`
- `packages/coding-agent/src/modes/interactive/components/settings-selector.ts`
- `packages/coding-agent/src/modes/interactive/components/user-message.ts`
- `packages/coding-agent/src/modes/interactive/interactive-mode.ts`
- `packages/coding-agent/src/modes/interactive/theme/system-theme.ts`

The upstream changes are kept with fork behaviour preserved: `--provider` requires `--model` (D-7), `quietStartup: "header"` (D-6), `/reload` enables tools newly added to defaultTools, one copy of each rendered user-message line, pastel system-theme chroma, and the absorbed main's runtime catalog work.

### Why

Each is an upstream improvement that does not break a fork behaviour; the fork alternatives (tuiMode regular, fork header, eval-only policy) are preserved and tested.

### Why an extension could not handle it

Session runtime, settings and interactive mode own these paths below the extension API.

### Expected merge conflict zones

Upstream edits to session/settings/runtime paths at the next sync.

## The CLI runtime factory forwards the browser engine (2026-10-03)

### What changed

- `packages/coding-agent/src/main.ts`: `createCliRuntimeFactory` passes `launchProfile.browserEngine` to session creation next to `promptSurface`.

### Why

A session opened with `open_session.browserEngine` must be created with it (senpi#2611).

### Why an extension could not handle it

The runtime factory builds the session before any extension is loaded.

### Expected merge conflict zones

The `promptSurface: launchProfile?.promptSurface` line in the session creation call.
## 2026-10-11 - Print account limits through the shared formatter (senpi#3131)

### What changed

- `packages/coding-agent/src/modes/print-mode.ts`: supplies provider/model identity and classified usage-limit scope to the existing provider-failure formatter.

### Why

Print mode reads internal messages, where the raw provider detail remains for retry classification.

### Why an extension could not handle it

Print mode owns the final stderr error.

### Expected merge conflict zones

The provider-error branch and usage-limit import in `packages/coding-agent/src/modes/print-mode.ts`.

## 2026-10-12 - Export the reserved-keyword matcher (senpi#3160)

### What changed

- `packages/coding-agent/src/index.ts`

Exports `findReservedKeywordSpans`, `findReservedKeywordRuns` and their types from the fork-only `core/reserved-keywords.ts`, which follows the omo-senpi engine's arming rules (identifier/path guards plus quote, URL, relay-header and negation masks), so it marks only text that actually arms.

### Why

One matcher drives both the TUI rainbow and any SDK consumer that needs the engine's keyword detection.

### Why an extension could not handle it

The package barrel is the only public entry point; an extension cannot add exports to it.

### Expected merge conflict zones

- LOW: the `core/skills.ts` export block in `packages/coding-agent/src/index.ts`.
## 2026-10-16 - Offline prompt size CLI route (senpi#3483)

### What changed

- `packages/coding-agent/src/main.ts`: `--print-prompt-sizes` forces offline print startup, opens the normal runtime and exits through the diagnostic before stdin, model streaming or catalog refresh.

### Why

The size breakdown must describe the loaded current project, including extensions, while making no provider request.

### Why an extension could not handle it

The flag changes core startup and dispatch before extensions can handle a turn.

### Expected merge conflict zones

- `packages/coding-agent/src/main.ts`: offline selection, app mode selection and the post-runtime-creation diagnostic branch.

## 2026-10-16 - Auth notices reach the TUI at startup, once per change (#3448)

### What changed

- `packages/coding-agent/src/main.ts`: `collectAuthDiagnostics` also reports the store's pending credential notices for non-interactive runs; the interactive branch passes `authNotices` (auth errors plus pending notices, with `markSeen`) to `InteractiveMode`.

### Why

- `packages/coding-agent/src/main.ts`: the credential and billing notices reached only model listing, print mode and RPC; the TUI, the main surface, never showed them (#3486 review).

### Why an extension could not handle it

- `packages/coding-agent/src/main.ts` builds the startup options every mode receives.

### Expected merge conflict zones

- `packages/coding-agent/src/main.ts`: `collectAuthDiagnostics`, `interactiveAuthNotices`, and the `InteractiveMode` options in the interactive branch.

## 2026-10-17 - Auth diagnostics show each credential notice once (#3486)

### What changed

- `packages/coding-agent/src/main.ts`: `collectAuthDiagnostics(storage, context, { persistSeen })` and `interactiveAuthNotices` are exported and take notices through `takePendingNotices`; model listing and print mode record them as seen, RPC runs do not.

### Why

- `packages/coding-agent/src/main.ts`: print mode showed the notice twice per run, and model listing showed it on every run (#3486 review).

### Why an extension could not handle it

- `packages/coding-agent/src/main.ts` owns the startup diagnostics of every mode.

### Expected merge conflict zones

- `packages/coding-agent/src/main.ts`: `collectAuthDiagnostics`, `interactiveAuthNotices` and their four call sites.

## 2026-10-22 - Async file locks never crash the process on a late heartbeat report (oh-my-openagent#10878)

### What changed

- `packages/coding-agent/src/experimental/server.ts`: the launcher and activation locks acquire through `lockWithLossHandling` (`core/file-lock.ts`). `ServerProfile` gains `assertHeld()` and `acquireServerActivation` returns `{ release, assertHeld }`; startup, cold activation (before the spawn and on every connect poll) and foreground start abort with `FileLockLostError` once their lock is lost.
- `packages/coding-agent/src/experimental/session-worker.ts`: the session ownership lock acquires through `lockWithLossHandling` with `onLost: stopWorkerOnLostOwnership(...)` (`experimental/session-worker-ownership.ts`): a worker that loses its session lock reports `worker_failed` (bounded by 1 s) and exits without closing, so it never writes the session another owner now holds.
- `packages/coding-agent/src/package-manager-cli.ts`: the managed self-update lock acquires through `lockWithLossHandling` and the update aborts with `FileLockLostError` before the release rename and before each activation once the lock is lost; the `lockSync` path is unchanged.

### Why

- `packages/coding-agent/src/experimental/server.ts`, `packages/coding-agent/src/experimental/session-worker.ts`, `packages/coding-agent/src/package-manager-cli.ts`: proper-lockfile 4.1.2's heartbeat `stat` callback has no `lock.released` check, so an unlock while that stat is in flight reaches the default `onCompromised`, which throws from a timer and kills the process. Reported and diagnosed by @ayalcoh in oh-my-openagent#10878.

### Why an extension could not handle it

- `packages/coding-agent/src/experimental/server.ts`, `packages/coding-agent/src/experimental/session-worker.ts` and `packages/coding-agent/src/package-manager-cli.ts` own these process-level locks before any extension loads.

### Expected merge conflict zones

- `packages/coding-agent/src/experimental/server.ts`: `acquireServerProfile`'s launcher lock, `acquireServerActivation`, and the import block.
- `packages/coding-agent/src/experimental/session-worker.ts`: the `releaseOwnership` acquisition in `run` and the import block.
- `packages/coding-agent/src/package-manager-cli.ts`: the lock in `runManagedSelfUpdate` and the import block.