ipinb 0.1.0__tar.gz

ipinb-0.1.0/BREAKING_CHANGES.md

@@ -0,0 +1,1844 @@
+# Breaking Changes
+
+## 2026-10-03: PyPI distribution is `ipinb`
+
+IPi is published to PyPI as `ipinb` starting with version 0.1.0. Python imports, the `ipi` command, configuration keys, plugin entry-point groups, and notebook metadata stay unchanged. The PyPI project named `ipi` belongs to unrelated software.
+
+**Migration:** Replace package requirements such as `ipi[mcp] @ git+...` with `ipinb[mcp]` or a pinned `ipinb[mcp]==0.1.0`. Git installations use the new requirement name with the same repository URL. Reinstall native integrations with `uvx --isolated --from 'ipinb[mcp]' ipi install --provider codex --replace` after reviewing the existing configuration. Kernel overlays, version reporting, remote wheel staging, and notebook publisher wheels now resolve `ipinb`.
+
+## 2026-10-03: Optional asynchronous Codex startup
+
+`install-hooks --async-startup` is an opt-in Codex path for hosts that accept messages while IPi prepares. SessionStart and SubagentStart forwarding runs in the background with a positive 300-second bridge readiness wait. Existing synchronous installation remains the default. Requires typed-agent-hooks 0.2.4 or newer. No migration is needed unless choosing asynchronous startup.
+
+## 2026-09-25: Portable native host installation
+
+`ipi install` now configures MCP startup and forwarding hooks together for
+Codex and Claude Code. Project scope is the default; `--scope user` selects
+personal configuration. Existing `install-hooks` remains available when MCP
+startup is managed separately. No running server or kernel is restarted.
+
+The installer refuses to overwrite a different `ipi` MCP entry unless
+`--replace` is explicit. Review that entry before replacing it. Local/editable
+IPi installations require an explicit portable `--requirement`; Git and index
+installs derive a pinned requirement from installed metadata.
+
+## 2026-09-24: Concise Markdown submission receipts
+
+- `markdown` now returns only `{"kind":"markdown","cell_id":"..."}` for new submissions and identical retries. It no longer repeats the submitted `source` or its metadata in the write response.
+- Call `read_cell(cell_id)` when the retained Markdown source, origin, creation time, request ID, or revision is needed. Large sources remain available through the resource URI returned by `read_cell`.
+
+## 2026-09-24: Native Claude provenance and narration
+
+- Claude MCP calls now use the exact `claudecode/toolUseId` metadata and native hook `prompt_id` to retain their originating session and prompt. Prompt groups are explicitly named `prompt:<id>`; Claude's distinct display turn UUID is not substituted for its prompt ID. Subagent origins remain separate from the parent's trace.
+- Kernel environments expose `AGENT_SESSION_PROVIDER` and `AGENT_SESSION_ID` for either harness. Codex retains `CODEX_THREAD_ID`; Claude clears inherited Codex attribution. Use the neutral pair in shared tooling.
+- Claude `MessageDisplay` batches become notebook narration, with retry-safe assembly and no duplicate Stop final message. Retained execution cells now have a stable prompt parent, including the first cell before a prompt hook could be mirrored. No tool-call migration is required.
+- Requires `typed-agent-hooks==0.2.2`. The redundant root `CLAUDE.md` link is removed; Claude Code 2.1.277 or newer reads `AGENTS.md` natively.
+
+## 2026-09-21: Lean Python cell reads
+
+- Remove `include_source` from every `read_cell` call. The argument is no longer accepted. Python replies always contain state and output without `source`, `origin`, `created_at`, or `request_id`, matching the former `include_source=False` behavior.
+- These fields remain stored internally. Retrieve retained Python source through the MCP resource `ipi://cells/{cell_id}/source` when needed. Markdown reads still include source and metadata. Observation windows, caller-owned cursors, cancellation, and output artifact metadata are unchanged.
+
+## Per-cell replay exports
+
+- Completed Python cells expose `files` when `read_cell(..., include_artifact_metadata=True)` is requested: raw `input.py` and dependency-selected PEP 723 `replay.py`. These are additive; the existing `source` JSON resource and lean polling are unchanged.
+- File resource bodies are Python text. Clients may read their MCP URIs or request host paths with `include_artifact_metadata=True`. The replay's diagnostics describe limitations; export failures never turn a successful cell into a failed execution. No migration is required.
+
+## Per-execution debugger (feature/per-cell-debugger)
+
+- Adds `ipdb(kernel_id, command, cell_id=None, yield_time_ms=1000, request_id=None)`. Kernel identity is always required; cell identity additionally targets a particular pause or failed execution. This does not restore the retired `pdb` tool or its implicit active target.
+- Unhandled Python exceptions finish as before, with an optional debugger inspection hint. `breakpoint()` and configured source breakpoints can now pause a live execution for stepping. `exceptions raised` opts into stops before exception handling; `exceptions off` restores normal handling.
+- A new ordinary execution to the same kernel discards existing postmortem inspection and aborts existing live pauses, allowing cleanup before admitting the new work. Already-running siblings are unaffected. Deliberately configured breakpoints persist until cleared or the kernel closes.
+- Debugger commands may yield with a durable `result_uri`. Read that resource or the cell transcript to recover completion; do not repeat a yielded command. Notebook debugger transcripts remain attached to their original cells.
+
+## 2026-09-15: Consolidated notebook tools and one execution runtime
+
+- Replace `wait(cell_id, ...)` with `read_cell(cell_id, yield_time_ms=10000, ...)`. `read_cell` defaults to an immediate read (`yield_time_ms=0`); Markdown never waits. The original source-inclusion switch was removed on 2026-09-21 as described above. Cursor and immutable artifact semantics are unchanged.
+- Replace `show(cell_id, caption)` and `publish_notebook(kernel_id)` with `publish(kernel_id, cells={cell_id: caption})`. The optional map highlights terminal Python cells in the full live notebook; it does not filter or rerun cells. All selected cells must belong to that kernel. Null captions highlight without text; omitted cells retain their existing highlights. Publishing without a map leaves highlights unchanged and supports empty notebooks. Publication creates or repairs the live URL and retains the kernel until close or owner exit.
+- Bash remains available but is disabled by default. Set `IPI_MCP_ENABLE_BASH_TOOL=1` before server startup to expose it. Remove `tools.bash` from configuration; the environment variable is the only opt-in. Remove the obsolete `tools.auto_create_kernel_for_python` field; use explicit kernel IDs and `server.prewarm_kernel` for optional startup provisioning.
+- Remove `request_id` from `list_kernels` and `list_cells`; those arguments were ignored. Retry keys remain supported on creation, execution, and Markdown submission.
+- The old `RuntimeManager`, `ToolRuntime`, implicit-kernel dispatchers, kernel-pool/worker lifecycle, logical-session registry, and skill-reading tool helpers are removed. Internal consumers and hook routing use the explicit `ExecutionRuntime`/`Registry` path. Direct importers of those internal modules must migrate. The current kernel implementation, transports, archival records, publication, and plugin APIs remain supported.
+
+
+This document records user-visible breaking changes made during the MCP-first
+redesign. Entries describe the old contract, the replacement, the reason, and
+the required migration.
+
+## Unreleased MCP-First Redesign
+
+### Compact cell IDs, cursors, and artifact references
+
+New cell IDs use one persisted registry-wide counter: `c1`, `c2`, ..., shared by Python, Bash, markdown, and browser executions across all kernels. Allocation never reuses a handle after close, expiry, failed acceptance, or reopening the same registry. Retained IDs are not renamed. Like kernel IDs, cell IDs are scoped to their originating registry; an independent registry can issue the same IDs. Cell lookup tools still take `cell_id` alone.
+
+Output cursors now have the form `c1:17`; kernel-list cursors use `k:50`, and cell-list cursors use `k0:50`. They remain bound to their resource and page type. Treat cursors as opaque: pass the returned `next_cursor` unchanged. Previously retained cursors using `output:`, `kernels:`, or `cells:` prefixes must be discarded; omit the cursor to replay from the beginning and obtain a new one.
+
+Large source and event references now contain only `uri` and `bytes` by default. Read the URI through MCP resources to retrieve the full JSON body. Call `read_cell(cell_id=..., include_artifact_metadata=True)` when filesystem paths, full SHA-256 checksums, and MIME types are needed. Consumers that previously accessed `artifact`, `sha256`, or `mime_type` directly must opt into metadata or use the resource URI. Full content hashes and immutable artifact files remain intact internally; authentication and upstream protocol IDs are unchanged.
+
+### Compact ordered output blocks
+
+Execution results expose `output.blocks` instead of `output.events`. Adjacent stdout or stderr writes become one `{"type":"stdout","text":"..."}` or `{"type":"stderr","text":"..."}` block. Stream blocks omit transport sequence numbers and the nested content wrapper. Rich outputs, control events, and large-event artifact references retain their event identity and content. Update programmatic consumers to the block schema; the MCP output schema describes both variants.
+
+The immutable event log and caller-owned cursors are unchanged. A page cursor advances over the original events consumed, independently of the number of blocks returned. Response limits apply to compact blocks; stream ordering, exact text, replay, and image delivery are preserved.
+
+### Structured-only execution results, compact kernel IDs, and FastMCP 4
+
+Execution tools return their JSON payload once in `structuredContent`. The duplicate JSON text block is removed; `content` is empty unless it carries images. The MCP output schema describes the result, and the host's standard MCP handling applies. Image MIME payloads are retained as artifacts instead of also embedding their bytes in structured output.
+
+Kernel IDs are unpadded registry-local counters: `k0`, `k1`, ..., `k11`. Allocation persists in the registry database and does not recycle IDs after close, expiry, or owner restart. An independent registry begins at `k0`; IDs are not globally unique and must be used with their originating registry. Existing retained IDs are not renamed. The subsequent cell-ID change is described above.
+
+The MCP extra now pins FastMCP 4.0.3 and MCP SDK 2.2.0. Reinstall the extra to upgrade the environment. Python protocol-model attributes now use snake_case, and request metadata is a dictionary; JSON wire aliases remain governed by MCP. Codex itself requires no changes.
+
+### Explicit kernels and concurrent retained executions
+
+The stdio and HTTP MCP APIs now share one explicit resource contract. `ipython`, `markdown`, publication, Bash, and plugin tools require `kernel_id`; observation and interruption require `cell_id`. Replace `switch_kernel` and `list_active_kernels` with explicit IDs and `list_kernels`. Replace `kill_session` with `close_kernel` for each kernel whose state you intend to discard. HTTP no longer accepts a logical `session_id`.
+
+Independent submissions to one kernel overlap by default and share globals. Observe terminal success before submitting dependent code. `yield_time_ms=0` always returns a handle. Observation cancellation leaves accepted work running; use explicit best-effort interruption for cancellation. Output cursors belong to each reader and can replay retained output. Optional `request_id` deduplicates identical accepted create, Python, Bash, and markdown operations; reuse with another payload is rejected.
+
+Live notebook publication remains executable and receives later updates. Closing its kernel or exiting the server ends the endpoint. Published kernels are exempt from idle expiry. Retained records and retry keys survive under the registry policy, while process restart truthfully marks unfinished work and live state lost.
+
+The old global PDB MCP plugin is not exposed by this release. Its behavior is incompatible with independent concurrent cells; the optional per-cell debugger validation gate must pass before it is advertised again. Dependency upgrades outside the validated ipykernel/IPython pins fail setup explicitly until the local concurrency repair is revalidated.
+
+
+### Codex Apps and web search move out of IPi
+
+**Status:** Implemented.
+
+**Change:** The `ipi.codex_apps` built-in, `ipi_codex_tools` generated package, authenticated host bridge, connector file staging, and Codex-backed `web_search` helper are removed.
+
+**Why:** Connected services and general web search are independent agent tools, not notebook runtime responsibilities. Keeping their authentication, discovery, transport, code generation, and file handling inside IPi coupled notebook startup and remote-kernel lifecycle to unrelated services.
+
+**Migration:** Install the standalone `codex-apps` and `web-search` toolfuncs. Import them through `import toolfuncs as tools`, then call flat generated operations such as `tools.codex_apps.google_drive_search(...)` or `tools.web_search.search(...)`. Run `codex-apps login` once to authenticate its dedicated ChatGPT account; `web-search` uses the normal active `codex login` profile.
+
+### Script-only path imports are delegated to toolfuncs
+
+**Status:** Implemented.
+
+**Change:** `ipi.import_path` is now the public `toolfuncs.import_path` function. It imports one local `.py` file or extensionless script and derives the module name from the filename. Optional PEP 723 requirements are installed into the running kernel before import; `dependency_installer=` may replace the default pip operation with a callable accepting `list[str]` and returning `None`. IPi's package, project, distribution-artifact, fsspec URL, `module=`, and `storage_options=` import paths are removed.
+
+**Why:** Importing a standalone script and preparing its optional inline dependencies is the reusable operation shared with toolfuncs. Package acquisition and arbitrary project installation made IPi own a second, much broader source loader that no current toolfunc contract requires.
+
+**Migration:** Keep calls that pass one local script path. Remove `module=` and `storage_options=`. Install packages, projects, wheels, and source distributions through the environment manager, then use normal Python imports. Materialize remote scripts locally before calling `import_path`. Pass `dependency_installer=` only when the caller must replace installation into the current kernel environment.
+
+### Native harness sessions replace IPi artifact IDs in model-facing provenance
+
+**Status:** Implemented.
+
+**Change:** Harness grounding now emits the exact native Codex or Claude Code session identity in an `agent-session` block. Stateful runtime output and notebook publication no longer expose the durable IPi artifact-directory ID as a standalone `session` attribute. They expose only the explicitly labeled `IPi artifact root` path. Stateless HTTP-family transports still return their required short-lived routing handle as `logical-session-id` instead of the generic `session` attribute.
+
+**Why:** Durable IPi artifact IDs such as `8212394626483155999-558398bc` identify `.agents/sessions/...` storage, not Codex or Claude history. Advertising that value as a generic session caused agents to record it as native session provenance, which cannot be resolved by harness-history tools.
+
+**Migration:** Use the `agent-session` block's `provider` and `id` attributes for note provenance and harness-history lookup. Use `IPi artifact root` to inspect notebook artifacts; an ID embedded in that path is storage metadata. Stateless clients must read `logical-session-id` from `runtime-state` and continue passing it unchanged as the `session_id` tool argument.
+
+### Notebook frontend dependencies are explicitly shared
+
+**Status:** Implemented.
+
+**Change:** Strict configuration now accepts `publication.shared_dependencies`, a list of PEP 508 requirements installed in both each matching kernel and its lazily created Notebook 7 publisher. A caller-supplied `additional_dependencies` requirement for the same distribution wins on both sides. Plotly is no longer a built-in member of the `publish` extra.
+
+**Why:** Packages such as Plotly and anywidget contain browser-side JupyterLab code as well as kernel-side Python code. Installing them in only one of IPi's isolated environments either cannot create the output or cannot render it. Declaring the shared set once makes that two-environment requirement explicit without inspecting `%pip`, mutating live publishers, or hard-coding optional visualization libraries into IPi.
+
+**Migration:** Move Plotly, anywidget, and any other distribution whose JupyterLab extension is required from `kernel.additional_dependencies` to `publication.shared_dependencies`. Keep packages built on a generic shared provider, such as ipymolstar on anywidget, in `kernel.additional_dependencies`. Recreate the kernel and publication after changing or upgrading a shared provider; ordinary live kernel package installs need no publication restart.
+
+### Runtime-only state uses temporary storage and notebook publication dependencies are lazy
+
+**Status:** Implemented.
+
+**Change:** The generated `ipi_codex_tools` project, Codex Apps bridge staging, connector-file staging, Jupyter configuration, Jupyter runtime data, IPython configuration, collaboration state, and exact-running-IPi publication wheel now live in process-owned operating-system temporary directories. Codex Apps uses one authenticated loopback TCP server for local and remote kernels; it no longer creates request, response, tombstone, heartbeat, or stale-root-sweep files. `generated_package_dir` and `stale_root_ttl_s` are removed and now fail directly when present.
+
+Codex configuration and auth are loaded once per bridge lifetime, outside the event loop. An explicit inventory refresh reloads them. Durable auth updates still use `fsync`, but generated packages, connector staging, and other disposable files do not. Repeated durability requests for the same notebook artifact are coalesced to one pending flush, plus at most one follow-up when a new generation arrives during an active flush.
+
+The base distribution now includes `nbformat`, which core notebook persistence requires. Notebook 7, Jupyter collaboration, YDoc, PyCRDT, and Tornado are in the `publish` extra instead of the MCP host extra. The first `publish_notebook` call builds one process-cached wheel from the exact running `ipi` package and starts the publisher with `uv run --isolated --no-project --no-config --with "ipi[publish] @ file://..."`. Concurrent first publications share that build. The child inherits `UV_CACHE_DIR`, but all Jupyter state directories are redirected into the publication's private temporary root.
+
+The default local-plugin server-dependency cache now uses this precedence: `IPI_SERVER_DEPS_CACHE`, then `$UV_CACHE_DIR/ipi/server-deps`, then `$XDG_CACHE_HOME/ipi/server-deps`, then `~/.cache/ipi/server-deps`. Slow runtime boundaries emit value-free warnings at one second or longer, naming only a fixed operation, fixed phase, and elapsed milliseconds.
+
+Every IPi-managed local or SSH kernel now sets `HistoryManager.hist_file=:memory:`. The IPi notebook and session log remain the durable execution record; kernels no longer create or share `~/.ipython/profile_default/history.sqlite`. A recorded kernel-start failure raises one internal `KernelLaunchError` instead of returning content that can be mistaken for a live kernel. Failed prewarm state is discarded, automatic execution stops after that one failed launch, and cancellation uses an operation-local launch-abort signal that does not poison the next attempt. Cancelled launch ownership is retained until the worker has closed any unpublished child and transport state.
+
+**Why:** Runtime-only metadata was doing small-file creation, polling, sweeping, SQLite locking, and synchronous durability work on user homes and shared filesystems. On Lustre and NFS, metadata latency dominates despite abundant CPU and RAM. Temporary local state, in-memory kernel history, and a single socket remove that filesystem from the request path, while the UV cache remains durable because reusing resolved dependencies is valuable. Treating a failed launch as ordinary content could also make one `ipython` call start a second kernel and wait through the readiness timeout twice.
+
+**Migration:** Delete `generated_package_dir` and `stale_root_ttl_s` from every `ipi.codex_apps` plugin configuration. Set `UV_CACHE_DIR` to node-local storage, or set `IPI_SERVER_DEPS_CACHE` explicitly, when the default home or XDG cache is remote. Keep `uv` available for the first notebook publication; a cold publish cache may require dependency network access. Install `ipi[publish]` explicitly only when a preinstalled publisher environment is useful. After changing Codex config or auth in a running host, call the generated tools refresh or restart IPi to reload it immediately. Code that called IPython's cross-process persistent history must use the IPi notebook or session artifacts instead. Callers must treat a failed `create_kernel` response as a tool error rather than parsing a normal content result.
+
+### Structured turn traces replace narration Markdown cells
+
+**Status:** Implemented.
+
+**Change:** The `ipi.reasoning_forwarding` built-in and `ipi-reasoning` Markdown cells are removed. `ipi.session_trace` records each user prompt in a structured raw `session-turn` anchor and adds chronological `session-activity` children for the associated agent messages and Codex reasoning summaries. Only immediately consecutive reasoning updates share an activity. Portable tools without a richer notebook cell use a stable `tool-activity` child keyed within its turn. Every top-level member receives a notebook-wide `activity_index`; late work is inserted at its turn's tail. Executions, authored Markdown, host-shell records, and suspension transcripts name their exact parent with `metadata.ipi.parent_id`. The Notebook 7 extension presents this flat notebook log as nested turn, user, agent, activity, and execution disclosures, and renders prompt and agent text as untrusted Markdown through Jupyter's rendermime registry. Every raw trace source remains a readable plain-text fallback.
+
+**Why:** One Markdown cell per narration sweep consumed excessive vertical space and made forwarded agent text look like deliberate notebook prose. A turn is the useful reading unit, but a single mutable cell per turn cannot preserve the actual chronology between narration, executions, and tools. A flat cell graph with explicit parent IDs and one total activity order preserves chronology and notebook interoperability while letting the extension render the hierarchy without reparenting Jupyter widgets.
+
+**Migration:** Remove `ipi.reasoning_forwarding` from any built-in plugin overrides and use `ipi.session_trace`. Consumers that inspect notebooks should find raw cells with `metadata.ipi.kind` equal to `session-turn`, `session-activity`, or `tool-activity`; group them by `session_id` and `turn_id`, and resolve `parent_id` by the notebook cell model ID. Prompt, reasoning, and message records retain `metadata.ipi.items` entries with `role`, `kind`, and `text`. The former single-cell `ipi-session-trace` representation is not supported.
+
+### Explicit per-kernel publication replaces the global notebook service
+
+**Status:** Implemented.
+
+**Change:** `publish_notebook` now lazily publishes one existing notebook and
+returns its complete tokenized Cloudflare quick-tunnel URL. Stateful mode takes
+`kernel_id`; stateless mode takes `session_id`. A successful publication starts
+one attached Notebook 7 child and one tunnel, retains the kernel past kernel and
+logical-session idle expiry, and lasts until the kernel is killed or its owning
+IPi process exits. The `ipi notebook-service` command, global dashboard,
+per-user rendezvous, registration client/API, symlink farm, GC and
+re-registration machinery are removed.
+
+The older automatic per-kernel Jupyter sidecar design is also gone. The entire
+`[jupyter]` configuration table is removed and now fails validation; live
+Notebook 7 processes exist only after an explicit publication call.
+
+**Why:** Notebook sharing is sparse and explicit. Kernel ownership already
+provides the necessary lifetime boundary, so a machine-wide discovery and
+registration system made every launch and deployment more complex without
+improving the selected-notebook workflow.
+
+**Migration:** Delete user services and wrappers that launch
+`ipi notebook-service`, including dashboard URL lookup scripts. Remove any
+service runtime-directory configuration and every `[jupyter]` table. Call
+`publish_notebook(kernel_id="kN")` or
+`publish_notebook(session_id="sNNNNNNNNN")` when a notebook must be shared, and
+treat the returned URL as a bearer credential. Install `cloudflared`; the tool
+fails rather than returning a localhost fallback when no public tunnel can be
+created.
+
+### Session termination uses `kill_session` in every transport
+
+**Status:** Implemented.
+
+**Change:** `kill_session` is the terminal session lifecycle tool in every
+transport. In stateful stdio, `kill_session()` cancels active work and prewarm,
+closes every kernel, and permanently ends the implicit notebook session; later
+notebook calls fail. In stateless HTTP-family transports,
+`kill_session(session_id)` removes and closes that logical session and
+invalidates its ID. The stateless-only `close_session` tool is removed.
+
+**Why:** Session termination is destructive and permanent in both ownership
+modes. One explicit verb and one terminal contract avoid a transport-specific
+alias that described the same lifecycle less precisely.
+
+**Migration:** Replace `close_session(session_id=...)` with
+`kill_session(session_id=...)` for stateless clients. Stateful clients may call
+`kill_session()` only as their final notebook operation.
+
+### Harness hook configuration is code-first
+
+**Status:** Implemented.
+
+**Change:** IPi now delegates hook configuration directly to `typed_agent_hooks.fastmcp.ForwardingHooks`. The removed TAH hookset manifests, compiler, loader, and global `typed-agent-hooks` CLI are no longer part of IPi's installation path. Forwarding commands invoke the dedicated `tah-fastmcp-forward` Cyclopts function and carry the stable `--managed-app ipi` ownership marker.
+
+**Why:** The executable TAH application now owns its dependency environment, provider metadata, installation behavior, and Python API in one code-first definition. Keeping IPi's parallel hookset construction would restore the duplicate configuration model that TAH removed.
+
+**Migration:** Remove existing IPi hook handlers containing `--hookset-name ipi`, then run `ipi install-hooks --provider codex --scope <project|user>` and `ipi install-hooks --provider claude_code --scope <project|user>` as applicable. Restart the harness after reinstalling. Existing entries are deliberately not interpreted as the new format.
+
+### Kernel idle reaping defaults to one hour and published kernels are retained
+
+**Status:** Implemented.
+
+**Change:** `server.kernel_idle_timeout_s` defaults to `3600`. An explicitly
+published kernel is exempt from that reaper, and its stateless manager is exempt
+from logical-session TTL expiry, until explicit kill or IPi process exit.
+
+**Why:** Ordinary forgotten kernels should release resources, while a notebook
+that was deliberately shared must remain usable for the publication lifetime.
+
+**Migration:** Set `kernel_idle_timeout_s = 0` under `[server]` to disable idle
+reaping globally. Prefer `publish_notebook` when only a specific shared kernel
+needs retention.
+
+### Flat string results and typed model-facing handles
+
+**Status:** Implemented.
+
+**Change:** Agent-facing tools retain their string return contract, but their text now uses flat, non-nested, product-neutral XML-like delimiters. Compact facts that describe a block, such as its identity, kind, state, source, counts, and flags, live in opening-tag attributes. What the block says or delivers remains in Markdown or verbatim bodies, including explanations, source, logs, errors, and raw output. Small inventories are Markdown tables. The delimiters are not a strict XML contract. Opening and closing tags provide the block boundary without a separate length attribute. IPi reparses only the generated top-level blocks needed for incremental output delivery. Runtime inspection consolidates the former scalar `status`, `session-id`, `kernel-state`, and related blocks into one `runtime-state` block with descriptive attributes and a body for its substantive details.
+
+Model-facing cells retain `cN`; live kernels now use `kN`, including
+`switch_kernel(kernel_id="k1")`; cell-local outputs use `oN`; stateless HTTP
+sessions use `s` plus nine random decimal digits. New session artifacts use the
+same handles in `kernels/kN/outputs/cN/g-<hex>/oN-*`. Durable session directory
+IDs, `g-<hex>` generation IDs, Jupyter IDs, and other external or internal
+protocol IDs are unchanged.
+
+**Why:** Flat semantic boundaries make mixed instructions, Markdown, and raw
+payloads easy for an agent to distinguish without turning prompts into a
+machine data protocol. Short type prefixes disambiguate local handles while
+retaining the measured token behavior of decimal counters and random suffixes.
+
+**Migration:** Treat result tags as descriptive boundaries, not strict XML. Read facts that describe a block from its opening-tag attributes and read what the block says or delivers from its body. Replace tab-record parsing with the corresponding top-level blocks and Markdown fields. Pass returned cell, kernel, and session handles unchanged; replace numeric `switch_kernel` arguments with `kN` strings. Follow returned artifact paths rather than constructing the former padded path components.
+
+### Python execution uses fixed yielding and addressed cell controls
+
+**Status:** Implemented.
+
+**Change:** `ipython` is now `ipython(code)` and uses a fixed 5-second initial observation window. A still-running cell yields with `cell_id=cN` and status `yielded`. `wait` is now `wait(cell_id, yield_time_ms=10_000)`, `interrupt` requires `cell_id`, and `show` is now `show(cell_id, caption=None)`. Stateless forms additionally require `session_id`. `show` promotes a terminal whole cell only; output references and the `last` sentinel are removed. Explicit interruption returns status `interrupted` without a synthetic `TimeoutError`. Execution records expose their count, state, duration, cell handle, exit code, and post-mortem flag as `status` attributes; any changed cwd, `sys.path`, or environment values remain in the body.
+
+**Why:** These names and continuation semantics match the agent harness's cooperative-yield UX. Explicit cell addressing prevents stale continuation calls from controlling the wrong execution, and whole-cell presentation removes an unnecessary output-addressing protocol.
+
+**Migration:** Remove `timeout_s` from every `ipython` call. Read the returned `cell_id`, then call `wait(cell_id=..., yield_time_ms=...)` or `interrupt(cell_id=...)`. Replace `show(target=...)`, `cell_ref`, and `show_ref` handling with `show(cell_id=...)` and `cell_id`. Do not pass `last` or composite values such as `c7/o2`.
+
+### Object-driven Agent Introspection Protocol and auto-context are removed
+
+**Status:** Implemented.
+
+**Change:** The Agent Introspection Protocol object model and the generic automatic context coordinator are deleted. IPi no longer inspects imports, new bindings, displayed values, or exceptions for `__agent_summary__`, `__agent_doc__`, resolver methods, synthesized dataclass or enum guidance, or inspection debt. The AIP tier model, well-known-object policy, suppression API, debugger suppression state, `ipi.auto_context` built-in, and public runtime enable/disable/status functions are removed. Generated Codex Apps modules no longer define `__agent_summary__`, and generated package schema 15 invalidates old stubs.
+
+Structured context blocks remain, under neutral `ContextBlock` and `PersistedContextBlock` names, as the transport for explicitly authored semantic events. The built-in producers are AGENTS file discovery after path or cwd changes, written-image advice, `ModuleNotFoundError` guidance, and pip guidance. Each producer emits directly and owns its recurrence policy. Kernel cwd, `sys.path`, and environment deltas are captured by a separate private tracker. Host-side context providers, harness context, state-specific result notices, and session-history context-block deduplication are unchanged.
+
+**Why:** Object inspection guessed relevance from ordinary Python activity and spent tokens on information already available through normal language knowledge and `help()`. It also coupled unrelated concerns: object metadata, exception scanning, context recurrence, plugin coordination, debugger behavior, and process-state tracking. Explicit semantic producers preserve the passive hints that carry hidden or local information while removing the speculative path and its policy machinery.
+
+**Migration:** There is no compatibility layer or phased migration. Delete uses of the removed AIP dunders, resolver and formatting APIs, inspection registry, trigger scanners, auto-context registration and suppression APIs, and `ipi.auto_context` plugin ID. Use standard `help(...)` for object and generated-tool inspection. A plugin that owns genuinely hidden semantic information should emit a `ContextBlock` directly from the event where that information becomes relevant and should own its own recurrence rule.
+
+### Kernel execution locations are per-kernel local paths or SSH URIs
+
+**Status:** Implemented; pending user acceptance.
+
+**Change:** `create_kernel(cwd=...)` now selects an immutable execution
+location for that kernel. An ordinary absolute path remains local;
+`ssh://[user@]host[:port]/absolute/path` creates a kernel at that absolute path
+through non-interactive system OpenSSH. One server can own local kernels and
+kernels on multiple SSH targets. Each SSH kernel owns its private control
+master, five host-loopback Jupyter forwards, target supervisor, approximately
+60-second owner lease, latest officially released portable `uv` verified with
+its publisher checksum, and an exact staged build of the running IPi. Remote
+projects require no host mirror. Remote kernels run built-in plugins only;
+external project, user, and installed plugins are ignored with one redacted
+warning and are not imported, executed, or staged.
+
+Native Windows and WSL support, the `ipi-windows` and `ipi-remote` Jupyter
+provisioners, path mapping, static command prefixes, Windows harness transport,
+and every process-wide `IPI_KERNEL_*` selector have been removed. IPi now
+supports Linux and macOS only. A removed variable fails startup rather than
+being silently ignored.
+
+**Why:** A process-wide launch prefix cannot represent mixed local/multi-host
+kernels and does not own target Jupyter ports, authentication, staged runtime,
+health, or cleanup. WSL path maps also required a host mirror and allowed host
+plugin execution to be confused with target execution. The resource-owned
+transport boundary makes target identity transactional and gives every acquired
+host and target resource a bounded rollback and cleanup path. It is private but
+is shaped for later native Docker and Kubernetes transports without treating
+those systems as SSH command prefixes.
+
+**Migration:** Remove all `IPI_KERNEL_*` variables and Windows/WSL provisioner
+configuration. Run IPi on Linux or macOS. Keep local calls as
+`create_kernel(cwd="/absolute/local/path")`; replace remote prefixes and path
+maps with `create_kernel(cwd="ssh://user@host/absolute/target/path")`. Configure
+aliases, keys, ports, `ProxyJump`, and host trust in OpenSSH, and verify the
+connection works non-interactively before launch. Move required remote behavior
+into built-ins or ordinary target project code; external IPi plugins do not run
+for SSH kernels. Targets must provide `python3` 3.10 or newer for the isolated
+session owner; the kernel environment itself continues to use the verified
+portable `uv` and exact staged IPi build. The last reviewed pre-change lineage is
+`origin/autopilot/ipi-http-session-ids@ae37c31502eb46c17e4df537f4f74babcccd49a2`.
+
+### HTTP logical session IDs shrink to nine digits behind a session limit
+
+**Status:** Implemented.
+
+**Change:** The logical `session_id` returned by stateless HTTP `create_kernel`
+is now an opaque fixed-width 9-digit decimal string (previously 18 digits).
+Allocation is unique-by-retry: a candidate that collides with a live session or
+a leftover `.agents/sessions/` directory is redrawn, `Session.create` and
+`SessionRegistry.register` raise the new `SessionIdCollisionError` for those
+collisions (`register` previously raised `ValueError`), and the new
+`server.stateless_max_sessions` config (default 256; `0` disables) makes
+`create_kernel` fail with a clear error instead of launching a kernel once that
+many sessions are live.
+
+**Why:** The ID is repeated in every session-bound tool call. Nine decimal
+digits cost three tokens bare and four inside JSON tool arguments under both
+benchmark tokenizers, versus six and seven for 18 digits. The $9 \times
+10^8$-value space is sized for loud failure, not secrecy: at 100 live sessions
+a stale ID hits a live one with probability about $10^{-7}$ per retry, so
+expired or pre-restart IDs keep dying with `UnknownSessionError` instead of
+aliasing another session. Authentication remains the HTTP token, never the ID.
+The cap exists because an authorized client loop could otherwise fork-bomb the
+host with kernel launches.
+
+**Migration:** Treat session IDs as opaque strings of any width and retain the
+exact value returned by `create_kernel`. Logical sessions never survive a
+server restart, so there is no persisted-ID migration. Callers that caught
+`ValueError` from `SessionRegistry.register` must catch
+`SessionIdCollisionError`. Deployments expecting more than 256 concurrent
+sessions must raise `server.stateless_max_sessions`.
+
+### Codex Apps tool results carry file bytes, and kernels name themselves to HTTP
+
+**Status:** Implemented.
+
+**Change:** A Codex Apps tool call that returns a file now performs a host-side
+download during the call. The stored copy lands in a `files` directory beside
+the endpoint's bridge spools, each file reference in the result gains an
+`__ipi_file__` entry, and the kernel receives it as a `CodexAppFile` exposing
+`path`, `read_bytes()`, and `mime_type`. A result holding at least one file is a
+`CodexAppResult` with a `files` tuple, and renders when it holds a single image.
+Both are `dict` subclasses, so every key the connector returned still indexes as
+before. A non-text content block returned alongside `structuredContent` is no
+longer discarded; it appears under `__ipi_content__`. Separately, kernels now
+install a `urllib.request` opener that sends `ipi/<version>` instead of the
+stdlib default User-Agent.
+
+**Why:** Connectors return a file as a credentialed URL that expires in minutes,
+never as bytes, and nothing fetched it. Notebook code had to, but a kernel
+environment carries no HTTP client unless the project depends on one, so code
+fell back to `urllib.request` — whose exact `Python-urllib/<version>`
+User-Agent the bot rules in front of those file hosts reject outright, with a
+403 whose explanation is only in a response body `urlopen` raises away. The
+result read as a permission error on the file. Two adjacent defects made the
+same path worse: `structuredContent` silently dropped any content block beside
+it, and content blocks were dumped in python mode, so a `ResourceLink` or
+`EmbeddedResource` carried an `AnyUrl` that could not be serialized and failed
+the whole call at the bridge with an unrelated-looking error.
+
+**Migration:** None required for reading tool results. Code that downloaded
+`download_url` itself still can — the URL is preserved — but should prefer
+`read_bytes()`, which does not race the expiry. A failed fetch never fails the
+call: `path` is `None` and `error` explains why, including the response body.
+Files over 25 MiB are not stored. Set
+`[plugins.config."ipi.http_user_agent"] user_agent` to choose a different
+User-Agent, `""` to keep urllib's own, or disable `ipi.http_user_agent`
+entirely; an explicit per-request header or a later `install_opener` already
+takes precedence.
+
+### The stdio server shuts down on SIGTERM and Ctrl-C
+
+**Status:** Implemented.
+
+**Change:** The stdio entrypoint now installs its own SIGINT and SIGTERM
+handlers and, once serving has ended, runs `atexit` hooks, flushes, and exits
+the process directly. HTTP transports are untouched, since uvicorn installs its
+own handlers.
+
+**Why:** Two defects met on this path. FastMCP installs no SIGTERM handler, so
+stdio ran under Python's default disposition and the normal end of a Codex or
+Claude Code session killed the process outright, skipping the lifespan
+`finally` and every `atexit` hook. Ctrl-C did reach Python, but `asyncio.Runner`
+claimed SIGINT and cancelled the main task instead, and that cancellation never
+completed, so the server hung until something force-killed it. Together these
+meant no owned cleanup operation ran on either stop path, which is why
+generated package roots accumulated. Even after cleanup was made to run, the
+interpreter still could not exit: anyio's worker threads are not daemons and
+park on an unbounded queue, so `threading._shutdown` waited on them forever.
+
+**Migration:** None required. A stop signal now completes teardown and exits 0.
+Anything embedding IPi that installs its own SIGINT or SIGTERM handler before
+`main()` keeps it; IPi only claims a signal still on its default disposition.
+
+### Generated Codex Apps stubs document their parameters
+
+**Status:** Implemented.
+
+**Change:** Generated tool docstrings gain a Google-style `Args:` section built
+from each JSON Schema property's `description`, declared choices, and `default`.
+Signatures render `Literal[...]` for a declared `enum` or `const` when the value
+list is small enough to stay readable, and fall back to the plain type
+otherwise. Generated modules now begin with `from __future__ import
+annotations`, the `_CodexAppTool` constructor takes `doc=` instead of
+`description=`, and each module's `TOOLS` entry carries a `parameters` tuple.
+`GENERATED_PACKAGE_SCHEMA` is bumped to 11. A failed tool call now appends what
+the named parameter accepts, or a pointer to `help(tools.<app>.<tool>)` when no
+known parameter is named.
+
+**Why:** Codegen kept only the property name, type, and requiredness, so
+everything an agent needed in order to choose a value was discarded. In the real
+inventory 96% of properties carry a description and only 3% declare an `enum`,
+so the values are usually stated in prose rather than machine-readable. Slack's
+`response_format` is the case that motivated this: it advertises no `enum` while
+the server enforces one, and agents that inspected the tool first still had to
+guess. That guess failed 67 times across recorded sessions.
+
+**Migration:** None required. The generated package is rebuilt on every host
+process, schema `default`s are still never sent on the wire, and the rendered
+annotations are display-only and unenforced.
+
+### Stale generated package roots are reclaimed
+
+**Status:** Implemented.
+
+**Superseded:** Generated package roots now use process-owned operating-system temporary storage, so this sweep, its heartbeat, and both related configuration keys have been removed. See “Runtime-only state uses temporary storage and notebook publication dependencies are lazy.”
+
+**Change:** On startup each host process sweeps sibling generated-package roots
+under its cache directory on a background thread, removing those whose owner is
+gone and whose age exceeds `stale_root_ttl_s` (default 24 hours; `0` disables).
+The owning process refreshes a `.alive` heartbeat so a live root is never
+mistaken for an abandoned one. Setting `generated_package_dir` opts out of both
+the sweep and the existing teardown, since the caller owns that directory.
+
+**Why:** Roots are unique per host process and are removed at teardown, but a
+stdio server killed with `SIGTERM` never runs that teardown, so nothing reclaimed
+them. One observed cache had grown to 452 roots and 160 MB, 441 of them owned by
+dead processes, with 409 byte-identical copies of a single module.
+
+**Migration:** None required. To keep the previous behavior, set
+`stale_root_ttl_s = 0` in the `ipi.codex_apps` plugin config.
+
+### Agent work cells collapse by default and `show` promotes
+
+**Status:** Implemented.
+
+**Change:** A new `show(cell_id, caption)` MCP tool promotes a completed cell
+into the human's view. `ipython` results carry `cell_id=c7` on the status record
+as the address `show` accepts. The bundled extension collapses agent work cells
+to a one-line header and renders promoted material expanded.
+
+**Why:** The notebook served the agent's scratch work and the human's reading at
+once, with no way to tell them apart. Promotion is retroactive because a cell
+becomes interesting when its result is surprising, which the agent cannot
+predict before running it.
+
+**Migration:** None required. `[jupyter] collapse_cells` still writes Jupyter's
+own `collapsed` and `source_hidden` keys and remains off by default; the
+frontend now collapses without it, which keeps those keys owned by the reader so
+promotion never reverts a manual collapse.
+
+### `action_description` and `description_display` are removed
+
+**Status:** Implemented.
+
+**Change:** The optional `[tools] action_descriptions` mode, the
+`action_description` argument on `ipython`, `bash`, and `pdb`, and the
+`[jupyter] description_display` renderer choice are all gone. Cell metadata no
+longer carries `description` or `description_display`, the `#### Intent:`
+Markdown cell is no longer emitted, and PDB suspension transcripts no longer
+show an `**Intent:**` line. The bundled Notebook 7 extension now always loads
+rather than being selected by `description_display = "extension"`.
+
+**Why:** The argument asked the agent to pay tokens on every call to restate
+intent the model had already produced. IPi now records the agent's own
+reasoning summaries and preambles in the structured turn trace
+(`ipi.session_trace`), which is both cheaper and more faithful: there is no
+reliable pairing between reasoning and calls, so a per-call field could never
+represent what the agent was actually doing.
+
+**Migration:** Remove `action_descriptions` from `[tools]` and
+`description_display` from `[jupyter]` in `~/.ipi/config.toml` and any
+`.ipi.toml`. Unknown config keys fail validation, so a stale file stops the
+server at startup with the offending key named. Callers passing
+`action_description` to a tool must drop it; extra arguments are rejected.
+Reasoning forwarding requires `model_reasoning_summary` to be set in
+`~/.codex/config.toml`, and is Codex-only.
+
+### Codex Apps startup refresh is a background kernel thread
+
+**Status:** Implemented.
+
+**Change:** The `refresh` bootstrap cell no longer blocks kernel readiness on
+the inventory refresh (a real Codex backend round trip, ~0.5 s). The cell
+imports the generated package, wires the bridge, installs the `tools` alias,
+arms a settle event, and runs the refresh on a daemon thread. First attribute
+access on an app module that is not materialized yet waits (bounded, 10 s)
+for the armed refresh before failing, so `tools.<app>` still behaves as if
+the refresh were synchronous when the inventory is genuinely needed.
+`GENERATED_PACKAGE_SCHEMA` bumped to 10.
+
+**Why:** Kernel creation (and therefore prewarm completion and the cold first
+call) paid the network refresh serially even though the server's own startup
+refresh freshens the same package concurrently.
+
+**Migration:** Code that asserted on the bootstrap cell's source must match
+`arm_startup_refresh` / `run_startup_refresh` instead of a synchronous
+`refresh(silent=True, ...)` call.
+
+### `ipi.runtime.bootstrap(ip)` renamed to `bootstrap_shell(ip)`
+
+**Status:** Implemented.
+
+**Change:** The package-level convenience function `ipi.runtime.bootstrap`
+collided with the `ipi.runtime.bootstrap` submodule: importing the submodule
+rebinds the package attribute to the module object, which silently shadowed
+the function once imports became lazy. The function is now
+`ipi.runtime.bootstrap_shell`; `%load_ext ipi.runtime` is unaffected. The
+heavy `ipi.runtime` members also import lazily now, so host-side code can use
+light leaves such as `ipi.runtime.project` without paying for IPython.
+
+**Migration:** Call `bootstrap_shell(ip)` (or `load_ipython_extension(ip)`).
+
+### On-disk notebook writes are coalesced and asynchronous without collaboration
+
+**Status:** Implemented.
+
+**Change:** Without the collaborative mirror (`jupyter.enabled = false`, or a
+sidecar with `collaboration = false`), `notebook.ipynb` is no longer rewritten
+synchronously on every cell mutation. A background saver persists the latest
+notebook state, debounced to at most one full rewrite per ~200 ms burst, and
+`Kernel.close()` still writes the authoritative final notebook synchronously.
+The new `Kernel.flush_notebook()` is the read-back barrier for anything that
+inspects the file mid-session. Cell artifacts (`input.py`, outputs,
+`manifest.json`) and `session.jsonl` are unchanged: still written before the
+tool result is returned. Relatedly, per-cell artifact fsyncs moved to a
+background durability flusher earlier in this cycle; atomic tmp-write + rename
+still happens on the response path.
+
+**Why:** A full-notebook rewrite per mutation made warm call latency grow
+linearly with session length (~13 ms at cell 25 to ~31 ms at cell 150 on the
+benchmark machine). Collaboration mode already treated the on-disk file as
+eventually consistent (the live room owns the document); this aligns the
+non-collaborative path with the same contract and keeps per-call latency flat.
+
+**Migration:** Tools or tests that read `notebook.ipynb` while the kernel is
+alive must call `flush_notebook()` first (or accept up to ~200 ms of
+staleness). Readers that only look after `close()` are unaffected.
+
+### Exception results are inline errors with an optional armed post-mortem
+
+**Status:** Implemented.
+
+**Change:** An uncaught exception in an `ipython` cell now publishes its
+concise, chain-aware traceback as that cell's own error output at throw time,
+exactly like plain IPython, and the tool result renders the cell as `err` with
+a `post-mortem=armed` status marker plus a one-line optional `pdb` hint. The
+previous shape suppressed the traceback from the cell output ("Traceback
+omitted here"), framed the result as a debugger stop ("Kernel is suspended"
+with `w`/`q`/`c` instructions and a `Location:`/`Exception:` suspension body),
+and appended an internally-run `pdb w` stack section. Dismissal is now silent
+and honest: the next `ipython` or `bash` call no longer prepends
+"automatically aborted the pdb suspension before ...", and the failed cell
+finalizes as `err` carrying the original exception instead of `aborted` (for
+automatic dismissal and for a manual `pdb` `q` alike). `breakpoint()` stops
+are unchanged: they keep the "Kernel is suspended" framing, the automatic
+`pdb w` stack, and the explicit auto-quit prefix with `aborted` status.
+
+**Why:** Agents reflexively answered every exception with `pdb("q")` even
+though ignoring the suspension always worked, and the failing cell's notebook
+record only received its traceback once the suspension resolved on the next
+call. Traceback-in-the-throwing-cell parity removes the ceremony while the
+armed post-mortem keeps live-state inspection one optional call away.
+
+**Migration:** Consumers matching "Traceback omitted", the exception-pause
+"Kernel is suspended" notice, or "automatically aborted the pdb suspension"
+must update their patterns. The exception suspension record is now a bare
+`suspension<TAB>ipi.pdb<TAB>exception<TAB>tool=pdb` line with no body, and the
+inline traceback strips IPython infrastructure frames and elides long middles
+(`... N frame(s) omitted ...`).
+
+### The stateful server prewarms the default kernel at startup
+
+**Status:** Implemented.
+
+**Change:** A stateful server now launches the default kernel in a background
+task as soon as its lifespan starts, so the first `ipython` call usually
+attaches to a warm kernel instead of paying kernel startup. The prewarm
+respects `tools.auto_create_kernel_for_python`, never blocks or fails server
+startup, and a failed prewarm logs a warning and falls back to the existing
+lazy auto-create. The first-result `auto_created_kernel` wrapper now appears
+only when that call actually created the kernel, and the auto-read notebook
+skill rides the first execution result even when the kernel was prewarmed.
+
+**Why:** The redesign makes bare `ipython` the whole default workflow; hiding
+kernel startup behind server startup removes the last visible setup cost, and
+the session-start harness context can advertise a kernel that already exists.
+
+**Migration:** Set `[server] prewarm_kernel = false` to opt out (for example
+on hosts where most sessions never run Python).
+
+### Auto-created kernels reuse the last kernel spec; reap notices target executions
+
+**Status:** Implemented.
+
+**Change:** When `ipython` or `bash` auto-creates a kernel because the previous
+one died or was idle-reaped, the new kernel reuses the most recently created
+or activated kernel's cwd, venv, and `additional_dependencies` instead of the
+server-default cwd with no overlay. The idle-reap "state is gone" notice is
+now delivered only into the next `create_kernel`, `ipython`, or `bash` result;
+`state`, `list_active_kernels`, and `switch_kernel` no longer consume it, so a
+read-only call between the reap and the next execution cannot swallow the
+warning.
+
+**Why:** Auto-create previously used a cwd frozen at first runtime creation
+(often the server working directory), silently moving the session to a
+different directory with no venv or dependency overlay after a reap. The
+notice draining into whichever call arrived first meant the execution that
+actually hit the empty kernel could see no warning at all.
+
+**Migration:** None. To land in a different cwd after a reap, call
+`create_kernel` explicitly, as before.
+
+### Written-image guidance no longer recommends an absent `view_image` tool
+
+**Status:** Implemented.
+
+**Change:** The `ipi.view_image` kernel plugin's post-cell context block
+("Images saved this cell. ...") now depends on whether the public `view_image`
+MCP tool is actually registered. The server resolves the effective
+`tools.view_image` value (transport default or explicit override) and injects
+it into the kernel plugin's spec config at kernel launch. When the tool
+exists, the guidance keeps recommending `view_image` with kernel-cwd-relative
+paths; when it does not (the stdio default), the guidance lists absolute paths
+and points at the client's own file/image reading instead.
+
+**Why:** Stdio agents were told to "Use `view_image`" for a tool their client
+does not have, which taught them to route figures through `savefig` plus
+harness file reading. Relative paths were also only resolvable against the
+kernel cwd, not the client cwd.
+
+**Migration:** None. Anything matching the old guidance string must accept
+both variants; the block's `source` (`path:written-images`) and `reason`
+(`path-written`) are unchanged.
+
+### `%pip` no longer shells out through `$SHELL`
+
+**Status:** Implemented.
+
+**Change:** IPi registers its own `%pip` line magic that executes
+`sys.executable -m pip ...` as a direct argv subprocess with piped output,
+replacing IPython's stock magic, which runs the installer through
+`$SHELL -c`. A failed install now raises `CalledProcessError`, so the cell
+reports `err` instead of quietly printing a nonzero exit; the stock
+"restart the kernel" note is printed only on success.
+
+**Why:** Routing installs through the user's login shell let shell startup
+hooks (fnm, nvm, direnv, ...) interleave their own errors into `%pip` output —
+for example fnm's "Requested version ... is not currently installed" in any
+repo with a `.node-version` — and made install output depend on per-machine
+shell configuration.
+
+**Migration:** None for normal use; `%pip install <pkg>` behaves the same but
+with deterministic output. Anything that relied on shell syntax inside the
+`%pip` line (environment prefixes, `&&` chains) must move to `%%bash` or a
+plain cell.
+
+### Idle kernels are shut down after one hour by default
+
+**Status:** Implemented.
+
+**Change:** A kernel with no agent or browser executions for
+`server.kernel_idle_timeout_s` seconds (default `3600`) is now closed
+automatically; previously kernels lived until server shutdown. Executing,
+suspended, and browser-busy kernels are never culled. The durable notebook and
+output artifacts are saved as usual, the shutdown is recorded as a
+`kernel`/`death` event with reason `idle_timeout`, and the next tool response
+carries a notice. An open JupyterLab tab alone does not keep a kernel alive;
+only executions reset the timer.
+
+**Why:** Each live kernel holds an IPython child process and usually a Jupyter
+sidecar process. Sessions left open for hours accumulated idle kernels that
+wasted memory and CPU indefinitely.
+
+**Migration:** To restore forever-lived kernels, set
+`kernel_idle_timeout_s = 0` under `[server]` in `~/.ipi/config.toml` or
+`<cwd>/.ipi.toml`, or pass `-c server.kernel_idle_timeout_s=0`. Raise or lower
+the value to tune the horizon.
+
+### Action descriptions are opt-in
+
+**Status:** Implemented.
+
+**Change:** `ipython`, the optional `bash` tool, and the built-in `pdb` tool no
+longer expose `action_description` by default. IPi injects an empty internal
+description, does not render an Intent block for it, and otherwise keeps the
+execution and debugger behavior unchanged. Set
+`[tools] action_descriptions = true` before server startup to restore the
+required, nonblank argument and its notebook intent metadata. This is a strict
+boolean startup schema setting.
+
+**Why:** Requiring a prose preamble for every notebook action adds tool-schema
+and call overhead even when the code or debugger command already states the
+operation clearly. Keeping intent opt-in preserves the auditable notebook
+workflow for users who value it without imposing it on every client.
+
+**Migration:** Remove `action_description` from default `ipython`, `bash`, and
+`pdb` calls. To retain the former signatures and nonblank validation, add
+`action_descriptions = true` under `[tools]` and restart the MCP server.
+
+### `view_image` availability follows the MCP transport
+
+**Status:** Implemented.
+
+**Change:** `[tools] view_image` is now a strict `bool | None` startup setting.
+When omitted, `view_image` is absent from every stdio server and present on
+every HTTP-family transport (`http`, `sse`, and `streamable-http`). Explicit
+`true` or `false` overrides that transport default. Filtering removes only the
+server-side MCP tool contribution; the `ipi.view_image` kernel plugin continues
+to report image files written by cells. Stateless plugin schemas now put
+`session_id` first, including `view_image(session_id, path)` and
+`pdb(session_id, command)` with default action-description settings.
+
+**Why:** Stdio clients can inspect local image artifacts through their native
+filesystem/image surface, while HTTP clients need an MCP tool that reads from
+the session kernel's filesystem. Transport-aware defaults avoid a duplicate
+stdio tool without removing runtime image-output context.
+
+**Migration:** Stdio clients that still need IPi's MCP image loader must set
+`view_image = true` under `[tools]`. HTTP clients can omit the setting, or set
+it to `false` to remove the tool. Treat stateless `session_id` as the first
+schema field; MCP invocation remains named-argument based.
+
+### Model-facing MCP tool references use canonical bare names
+
+**Status:** Implemented.
+
+**Change:** Server instructions, runtime hints and errors, harness guidance, and
+the local and HTTP notebook skills now refer to tools by their canonical names,
+such as `ipython`, `create_kernel`, `wait`, and `pdb`. The model-facing alias
+resolver and `IPI_MCP_TOOL_PREFIX` environment variable have been removed. The
+registered FastMCP tool names were already bare and are unchanged.
+
+**Why:** The `mcp__<alias>__<tool>` spelling is a client-specific presentation
+detail. Repeating it in IPi-authored prose added noise, coupled the instructions
+to one host naming convention, and could become incorrect when the configured
+server alias differed from the client-visible alias.
+
+**Migration:** Remove `IPI_MCP_TOOL_PREFIX` from launch environments and refresh
+or reinstall any copied notebook skills. Integrations that inspect IPi-authored
+guidance must expect canonical bare names. MCP clients remain responsible for
+any namespace they add to transport-level tool identifiers.
+
+### Python execution tool renamed to `ipython`
+
+**Status:** Implemented.
+
+**Change:** The stateful and stateless Python/IPython execution MCP tool is now
+registered as `ipython` (previously `python`). Both notebook skills, the
+README, server instructions, and error/collision messages now reference the
+new name. The optional `bash` tool and its `IPI_MCP_ENABLE_BASH_TOOL`/
+`tools.bash` gating are unchanged.
+
+**Why:** `ipython` more accurately reflects that the tool runs a persistent
+IPython kernel, not just plain Python.
+
+**Migration:** Any client-side permission allowlist, config, or automation
+that references the `python` MCP tool name (e.g. `mcp__notebook__python`) must
+be updated to `ipython`. Refresh or reinstall any copied notebook skills.
+
+### Jupyter Cloudflare tunnels are quick-tunnel only
+
+**Status:** Implemented.
+
+**Change:** `jupyter.tunnel = true` now launches only an accountless Cloudflare
+quick tunnel. The `jupyter.tunnel_domain` and
+`jupyter.tunnel_hostname_prefix` fields are removed and rejected. Jupyter waits
+up to 30 seconds for `cloudflared` to publish the quick-tunnel URL so
+`create_kernel` can return it immediately; failure stops the tunnel and falls
+back to the local notebook URL with a diagnostic notice.
+
+**Why:** Named Jupyter tunnels required Cloudflare login state, tunnel and DNS
+provisioning, generated credentials, and custom-hostname configuration. Quick
+tunnels need none of that setup. The previous asynchronous startup also returned
+localhost before the quick-tunnel URL appeared a few seconds later.
+
+**Migration:** Remove `tunnel_domain` and `tunnel_hostname_prefix` from every
+`[jupyter]` table. Keep `jupyter.tunnel = true` to request a quick tunnel. MCP
+HTTP named tunnels and the `--tunnel-domain` CLI option are unchanged.
+
+### HTTP logical session IDs use compact decimal strings
+
+**Status:** Implemented.
+
+**Change:** The logical `session_id` returned by stateless HTTP `create_kernel`
+is now an opaque fixed-width 18-digit decimal string. The prior implementation
+reused the 28-character timestamp-sortable durable-session directory ID.
+
+**Why:** The logical ID is repeated in every later HTTP tool call. Measurements
+over 10,000 samples with `o200k_base` and `cl100k_base` reduced its mean cost
+from 12.56 tokens to exactly 6. The new $9 \times 10^{17}$-value random space
+retains about 59.6 bits of entropy; even one million generated IDs have an
+approximate birthday-collision probability of $5.6 \times 10^{-7}$.
+
+**Migration:** Treat session IDs as opaque strings and retain the exact value
+returned by `create_kernel`. Do not parse timestamps, UUID fragments, or numeric
+meaning from either format. Logical sessions never survive an MCP server
+restart, so there is no persisted-ID migration.
+
+### Parked execution control returns incremental output
+
+**Status:** Implemented.
+
+**Change:** After the initial Python result parks a running cell, each `wait`
+and `interrupt` result now contains current status plus only output not already
+returned. New output records include `update=new`; a growing stream uses
+`update=append from_chars=N` and contains only its suffix. An unchanged poll has
+no output record. Non-append changes emit `notice\tkind=output-reset` followed by
+the complete current snapshot. Artifact paths continue to name complete output,
+and canonical cell records remain full snapshots.
+
+**Why:** Replaying all output accumulated so far on every poll made repeated
+waits consume quadratic model tokens and obscured which output was actually new.
+
+**Migration:** Clients that assemble a live view must retain earlier output,
+add `update=new` records, append untruncated suffixes at the Unicode code-point
+offset `from_chars=N`, and replace the assembled view after
+`kind=output-reset`. A truncated suffix is only a preview; read its complete
+`PATH` and replace that output when lossless assembly is required. Clients that
+need a stateless complete snapshot should likewise read the referenced artifact
+or current manifest instead of expecting every `wait` response to repeat prior
+output.
+
+### AGENTS context hints use absolute paths
+
+**Status:** Implemented.
+
+**Change:** The `source` field emitted by the `ipi.agents_md` built-in now uses
+the resolved absolute `AGENTS.md` path with portable forward slashes. It no
+longer renders the path relative to a detected project or ancestor directory.
+
+**Why:** Relative hints can contain several `..` components when applicable
+instructions live above the nearest project root, making the model-visible path
+hard to identify and resolve correctly.
+
+**Migration:** Treat the text after `agents-md:` as an absolute path and open it
+directly. Consumers must stop joining the hint to the kernel cwd or project
+root.
+
+### Model-facing output no longer contains ANSI controls
+
+**Status:** Implemented.
+
+**Change:** MCP responses, live output callbacks, PDB results, and persisted
+text artifacts remove both terminal control bytes and serialized spellings such
+as `\x1b[31m`. Runtime bootstrap also undoes ipykernel's forced-color child
+process environment. Raw notebook stream/error output retains explicitly
+emitted controls so Jupyter can render them, but ordinary child CLI output is
+no longer forced to use color.
+
+**Why:** ANSI syntax expands further when MCP JSON is encoded, consumes model
+tokens without adding information, and can make captured machine-readable
+output invalid before the agent can parse it.
+
+**Migration:** Do not depend on ANSI syntax in model-facing output or captured
+subprocess data. Emit semantic text or a structured rich display instead. Code
+that intentionally needs colored child-process output must opt in explicitly
+for that subprocess and consume the resulting control sequences itself.
+
+### Execution descriptions become required action intent
+
+**Status:** Implemented.
+
+**Change:** Execution intent is now the first required argument of Python,
+bash, and PDB. The public signatures are
+`python(action_description, code, timeout_s=10)`,
+`bash(action_description, cmd, timeout=None)`, and
+`pdb(action_description, command)`. The former optional Python `description`
+argument, internal Python `source` argument, and bash `command` argument have
+been removed rather than aliased. Blank descriptions are rejected.
+
+**Why:** The old Python description was effectively a no-op after the tool call.
+Putting user-facing intent first makes the agent state what an execution is for
+before composing it, and preserving that intent makes notebook history easier
+to follow and audit.
+
+**Migration:** Rename Python `description` to `action_description` and place it
+before `code`; rename Python `source` payloads to `code`; rename bash `command`
+to `cmd`; and add `action_description` before every bash and PDB command. The raw
+tool-call arguments remain available in session records, while normalized intent
+is stored on execution records and notebook metadata. Notebook 7 uses the
+bundled intent-header extension by default. Set
+`[jupyter] description_display = "markdown"` to stage an intent Markdown cell
+before each agent code cell instead.
+
+### Python execution yields after 10 seconds by default
+
+**Status:** Implemented.
+
+**Change:** Omitting `python.timeout_s` now uses a 10-second cooperative yield
+budget instead of inheriting the kernel's 1,800-second timeout. If the cell is
+still running, IPi returns it as parked with partial output; the cell continues
+until `wait` collects it or `interrupt` stops it. `timeout_s=0` parks
+immediately. The MCP parameter is now a non-null integer greater than or equal
+to zero.
+
+**Why:** The prior default kept the MCP request occupied for up to 30 minutes,
+so an agent that did not predict a slow call could not reach the control tools
+that cooperative timeout was designed to expose.
+
+**Migration:** Omit `timeout_s` for the new responsive default. Pass an explicit
+larger value when one blocking call is intentional; `timeout_s=1800` recreates
+the former wait. Replace explicit `null` with either omission or a non-negative
+integer. Existing MCP processes must be restarted before they advertise and use
+the new schema.
+
+### TUI and embedded LLM harness removal
+
+**Status:** Implemented.
+
+**Change:** The terminal UI and its `ipi.tui` package have been removed. The
+root `ipi` command now starts the MCP server. The embedded agent loop,
+`ipi.agent`, `ipi.client`, `ipi.core`, provider prompt assembly, diagnostics,
+and client transport APIs have also been removed.
+
+**Why:** These layers have no active TUI users, duplicate responsibilities
+already owned by Codex and Claude Code, and force the MCP path through a much
+larger compatibility architecture. Removing them makes the supported product
+boundary explicit and allows the runtime and extension APIs to model only real
+use cases.
+
+**Migration:** Configure IPi as an MCP server through the `ipi` command. The
+`ipi-mcp` command no longer exists. Existing users of the old TUI must remain on
+an older release; there is no replacement embedded agent harness.
+
+### Harness-only configuration removal
+
+**Status:** Implemented.
+
+**Change:** The `[provider]`, `[display]`, and `[tui]` configuration sections
+and their Python model types have been removed. IPi config now describes MCP
+tools, Jupyter behavior, and extensions only. Removed sections are rejected as
+invalid configuration.
+
+**Why:** Provider selection, reasoning effort, display verbosity, and terminal
+keybindings belonged to the deleted embedded harness. Accepting those settings
+would imply behavior the MCP server cannot provide.
+
+**Migration:** Remove those sections from user and project `.ipi.toml` files.
+Configure models, reasoning, display, and keybindings in Codex or Claude Code.
+
+### Provider-era package removal
+
+**Status:** Implemented.
+
+**Change:** Every bundled `ipi-plugin-*` distribution has been removed. The
+following provider-era capabilities were deleted rather than migrated:
+
+- `ipi-plugin-provider-codex`
+- `ipi-plugin-provider-generic`
+- `ipi-plugin-compaction`
+- `ipi-plugin-skills`
+- `ipi-plugin-slash-lifecycle`
+- `ipi-plugin-write-tool`
+- `ipi-plugin-notebook-transcript`
+
+Actively retained behavior, including AGENTS path hints, automatic context,
+autoreload, project imports, dataframe formatting, image output tracking, PDB,
+Codex Apps, and harness context, now ships as in-tree built-in plugins in the
+single `ipi` distribution.
+
+**Why:** Codex and Claude Code already own provider calls, skills, slash
+commands, patch/write tools, conversation transcripts, and context compaction.
+Keeping duplicate implementations in IPi enlarged the dependency and extension
+surface without contributing to the MCP execution product.
+
+**Migration:** Remove these package names from IPi configuration and launch
+requirements. Use the corresponding Codex or Claude Code harness capability.
+AGENTS instructions are discovered by the `ipi.agents_md` built-in, which emits
+file path hints for the harness to read rather than injecting full file
+contents. Executed notebook cells and outputs remain recorded by core;
+conversation messages are no longer mirrored into the notebook.
+
+### Extension API replacement
+
+**Status:** Implemented.
+
+**Change:** The provider/TUI-oriented `HostInitAPI` and its priority registries,
+string event namespace, tool-object/dispatcher pairs, provider registration,
+slash commands, record renderers, and agent control handle were replaced by
+plain plugin callbacks with separate server, per-kernel environment, and
+in-kernel scopes.
+
+First-class MCP tools are registered only by bundled, installed,
+user-level, and startup-project plugins discovered before the MCP server starts.
+Project plugins discovered later through `create_kernel(cwd=...)` may customize
+that kernel and its environment, but cannot add a new MCP tool schema because
+Codex does not currently refresh its model tool registry after
+`tools/list_changed`.
+
+**Why:** The current API combines unrelated process lifetimes and obsolete
+agent-harness concepts. Explicit scopes make ownership, failure behavior, and
+project isolation understandable while preserving the extensibility that is
+the product's central requirement.
+
+**Migration:** Export one direct `plugin` value from each extension entry point
+or local file:
+
+```python
+from ipi.plugins import EnvironmentSetup, Plugin, ServerSetup, ToolContext
+
+
+async def inspect(ctx: ToolContext, name: str) -> str:
+    return f"{ctx.environment}: {name}"
+
+
+def setup_server(setup: ServerSetup) -> None:
+    setup.tool("inspect", inspect)
+
+
+def setup_environment(setup: EnvironmentSetup) -> None:
+    setup.bootstrap("imports", "import ipi_codex_tools as tools")
+    setup.require("example-dependency>=1")
+
+
+plugin = Plugin(server=setup_server, environment=setup_environment)
+```
+
+Installed distributions must expose `module:plugin` in the `ipi.extensions`
+entry-point group and already be present in the host environment. User plugins
+move to `~/.ipi/extensions/`; project plugins move to
+`<cwd>/.ipi/extensions/`. The old `.agents/extensions` loader, PEP 723
+sidecars, split `host.py`/`kernel.py` packages, priority values, and trust
+allowlist are not part of the replacement.
+
+Configuration moves from `[extensions]` to:
+
+```toml
+[plugins]
+installed = ["my-ipi-plugin==1.2.3"]
+disabled = ["ipi.optional_feature"]
+
+[plugins.config."my.plugin"]
+enabled = true
+```
+
+Configuration selects installed entry points but never installs a missing host
+package; add external distributions to the `uvx` launch environment. Tool
+extensions must be discoverable from the server startup project. Kernel-only
+project behavior remains independently discoverable for each
+`create_kernel(cwd)`.
+
+### Strict setup callbacks and threaded synchronous tools
+
+**Status:** Implemented.
+
+**Change:** `Plugin.server`, `Plugin.environment`, and `Plugin.kernel` callbacks
+must be synchronous and return `None`. Coroutine functions, async callable
+objects, decorated callbacks that return an awaitable, and any other non-`None`
+result fail setup with plugin and phase attribution. Synchronous plugin MCP
+tools now execute in a worker thread; async tools continue on the serving loop.
+Tool names must contain 1-128 ASCII letters, digits, underscores, hyphens, or
+dots. A tool must expose an inspectable signature whose first positional
+parameter is named `ctx`; public positional-only, `*args`, and `**kwargs`
+parameters are rejected because they do not define one object-shaped MCP input
+schema.
+
+Every contributed tool invocation now participates in the connection's runtime
+operation owner. It is serialized with kernel control calls and shutdown. A
+cancelled synchronous tool remains owned until its worker exits. Direct calls
+such as `await ctx.session.cell(...)` are reentrant; child tasks spawned by a
+plugin are tracked and drained before that invocation or session shutdown can
+complete.
+
+**Why:** An async setup callback previously produced an unawaited coroutine,
+contributed nothing, and still let startup succeed. A synchronous MCP tool ran
+inside IPi's async wrapper on the shared event loop, so one blocking file or
+remote operation stalled every HTTP session and harness event.
+
+**Migration:** Define setup with ordinary `def` and do all registration before
+returning `None`. Give tools stable valid names and ordinary typed keyword
+parameters after `ctx`; replace variadic or positional-only public APIs with an
+explicit object schema. Put asynchronous behavior inside the registered async
+tool, handler, observer, or provider rather than making setup async. Make
+synchronous MCP tools thread-safe and avoid event-loop-local state, or convert
+them to `async def` and use nonblocking APIs. Do not use a plugin task as a way
+to detach notebook operations beyond the MCP call lifetime.
+
+### Recursively immutable plugin configuration
+
+**Status:** Implemented.
+
+**Change:** `EnvironmentSetup.config` and `KernelSetup.config` are isolated,
+recursively immutable views. Nested mappings are read-only, lists and tuples
+become tuples, sets become frozensets, and bytearrays become bytes.
+
+**Why:** A top-level mapping proxy still allowed a plugin to mutate nested
+configuration shared with later callbacks. Setup is transactional only when its
+inputs cannot be changed behind the loader's back.
+
+**Migration:** Treat configuration as `Mapping` and immutable sequences rather
+than concrete `dict` and `list` values. Make an explicit local copy inside the
+callback when an algorithm genuinely needs mutable working state.
+
+### Explicit HTTP logical sessions and per-kernel project ownership
+
+**Status:** Implemented for the MCP runtime and new plugin system.
+
+**Change:** Session ownership is selected by strict `server.session_mode`
+configuration. Stateful mode remains the stdio default and owns one implicit,
+multi-kernel runtime. Every HTTP transport requires stateless mode and uses
+FastMCP's request-stateless transport. In that mode `create_kernel` creates one
+logical session with one kernel and returns its `session_id`; every later
+session-bound core or plugin tool requires the explicit ID. Stateless mode adds
+`kill_session`, removes `switch_kernel` and `list_active_kernels`, and safely
+expires idle sessions after `server.stateless_session_idle_timeout_s`. Each
+kernel still owns the config and plugins resolved from its exact cwd. The
+optional `read_notebook_skill` tool is session-independent and returns the
+common notebook workflow composed with the stateless lifecycle in this mode.
+
+**Why:** MCP clients may reconnect or create a new protocol session for every
+tool call. Keying notebook ownership by that transport detail silently replaced
+the active runtime, lost Python state, and made `list_active_kernels` appear
+empty. Logical ownership must survive transport churn and remain visible in the
+tool contract.
+
+**Migration:** Remove `--session-isolation` and `--no-session-isolation`. Set
+`[server] session_mode = "stateless"` for HTTP, or pass
+`-c 'server.session_mode="stateless"'`. Call `create_kernel` first, retain its
+logical ID, pass `session_id` to every later tool call, and close it explicitly.
+HTTP transport lifecycle guidance remains in server instructions and
+`ipi/skills/notebook-http/SKILL.md`; `read_notebook_skill` returns it together
+with the common notebook workflow. Local stdio agents continue to use
+`ipi/skills/notebook/SKILL.md`. Plugins must read active state from their
+injected `ToolContext`, not module globals or the server startup cwd.
+
+### Explicit programmatic runtime ownership
+
+**Status:** Implemented.
+
+**Change:** `create_server` now accepts an explicit `session_mode`.
+`shared_manager=` is valid only for stateful mode. `manager_factory=` is valid
+only for stateless mode and receives the newly generated logical session ID.
+Omitting the applicable owner constructs the corresponding default manager or
+registry.
+
+**Why:** The old parameter names did not describe whether state was shared or
+isolated. Injecting a mutable registry also split ownership across the caller
+and server and could cache a manager before server plugin binding succeeded.
+The factory boundary keeps construction, binding, insertion, and shutdown under
+one owner.
+
+**Migration:** Pass `session_mode="stateful"` with `shared_manager=` for the
+implicit multi-kernel server. Pass `session_mode="stateless"` with
+`manager_factory=lambda session_id: CustomRuntimeManager(session_id=...)` for
+explicit one-kernel sessions. Supplying an owner intended for the other mode is
+an error.
+
+### Initial built-in plugin IDs and image result
+
+**Status:** Implemented.
+
+**Change:** The lightweight AGENTS and automatic context behavior now use
+reserved built-in IDs `ipi.agents_md` and `ipi.auto_context`. The image tool is
+the server plugin `ipi.view_image` and returns native MCP `ImageContent` for
+PNG, JPEG, GIF, and WebP rather than a text-only path description. The old
+`%%view_image` magic is not retained.
+
+**Why:** Built-ins should exercise the same small public contract as external
+plugins. Native MCP image content lets capable clients render the actual file
+without provider-specific text or base64 conventions.
+
+**Migration:** Replace old `ipi-plugin-*` config tables with
+`[plugins.config."ipi.<name>"]` tables and disabled IDs with the new reserved
+IDs. Call the `view_image(path=...)` MCP tool directly; remove uses of the cell
+magic or assumptions that its result is plain text.
+
+### Internal extension tool calls
+
+**Status:** Implemented.
+
+**Change:** `ctx.impersonate(...)`, the `impersonated` tool-hook flag, and the
+synthetic tool-call helpers have been replaced by `ctx.run_tool(...)`, the
+`internal` flag, and `run_internal_tool(...)`. Internal calls no longer append
+a synthetic assistant-message record.
+
+**Why:** IPi is no longer an LLM provider or transcript owner. Startup probes
+and debugger automation still need to execute tools through normal hooks, but
+representing those operations as an assistant message is inaccurate and tied
+the execution core to provider wire formats.
+
+**Migration:** Replace `ctx.impersonate(name, ...)` with
+`ctx.run_tool(name, ...)` and `ctx.impersonated` with `ctx.internal`. Consumers
+of session JSONL must no longer expect an assistant-message record before
+host-initiated tool calls; the tool-call and result records remain.
+
+### Canonical MCP tool arguments
+
+**Status:** Implemented.
+
+**Change:** Provider-specific tool normalization, custom/freeform tool metadata,
+Lark grammar declarations, wire serializers, and the public
+`ToolCallRecord.wire_kind` field have been removed. PDB now accepts the normal
+MCP argument object `{"command": "..."}` only. The live-only record schema is
+strict; existing JSONL records with a `wire_kind` key must be migrated before
+IPi reads them.
+
+**Why:** The deleted embedded providers were the only consumers of alternate
+wire shapes. Retaining two representations forced every execution and record
+path to normalize data that already arrives from MCP in canonical form.
+
+**Migration:** Extension tools must define one typed MCP argument schema and
+consume it directly. Remove `freeform`, `grammar`, `normalize_arguments`, and
+`wire_arguments` members. Replace raw PDB custom-tool bodies with the `command`
+field.
+
+### Conversation record removal
+
+**Status:** Implemented.
+
+**Change:** `UserMessageRecord`, `AssistantMessageRecord`, `ProviderMessage`,
+`ContextRecord`, `UnknownRecord`, visibility/render policies, provider-history
+rendering, baked context-text parsing, and user-message rewind helpers have been
+removed. The session log accepts only the current execution record schema;
+unknown and provider-era lines are no longer preserved or interpreted. Output
+summaries affect only the current MCP tool result after durable persistence.
+
+**Why:** Codex and Claude Code own the conversation transcript, compaction, and
+rewind lifecycle. IPi owns notebook execution records and output artifacts.
+Maintaining a second partial transcript created incorrect ownership and coupled
+kernel persistence to provider request formats.
+
+**Migration:** Consumers of session JSONL should use the current cell, bash,
+tool-call, tool-result, and kernel event records only. Read conversation and
+context history from the active agent harness. Migrate any retained legacy log
+before passing it to IPi; the runtime does not provide a compatibility loader.
+
+### Session resume and fork removal
+
+**Status:** Implemented.
+
+**Change:** `Session.open`, `SessionInfo`, `list_sessions`, `resolve_session`,
+`fork_session`, and the associated resolution errors and artifact-copy helpers
+have been removed. A session exists only for its live MCP connection and is not
+reopened after process exit.
+
+**Why:** The agreed product has disposable per-connection kernels and no restart
+resumability. Keeping discovery and fork code implied a durable lifecycle that
+the kernel processes, plugin environments, and HTTP ownership model did not
+support.
+
+**Migration:** Treat `.agents/sessions/<id>` as an append-only execution and
+artifact directory, not a resumable IPi object. Inspect or copy files with
+ordinary filesystem tools when archival workflows need them.
+
+### Embedded provider runtime removal
+
+**Status:** Implemented.
+
+**Change:** The internal `Provider` API, provider stream/response models,
+`LLMSessionInfo`, `ipi.llm`, `ipi.runtime.llm`, `%ipi_set_session`, provider
+debug sinks, credential storage, reasoning models, and agent-side LLM helpers
+have been removed. Kernels no longer receive provider/model metadata in their
+environment or notebook metadata.
+
+**Why:** IPi does not call an LLM in the MCP product. Codex and Claude Code own
+models, credentials, reasoning settings, provider requests, and conversation
+state. Propagating a fake `provider_name="mcp"` session into every kernel added
+state and API surface without representing a real capability.
+
+**Migration:** Remove imports from `ipi.tools.providers`, `ipi.tools.agent`,
+`ipi.auth`, `ipi.reasoning`, `ipi.llm`, and `ipi.runtime.llm`. Extensions that
+need harness event data must use the new typed Codex/Claude harness hook API;
+kernel extensions must not infer the active model.
+
+### Public prompt helper removal
+
+**Status:** Implemented.
+
+**Change:** `ipi.prompts`, `Prompt`, and the public prompt/tag helper package
+have been removed. IPi retains only a private model-output renderer used by its
+own MCP result formatting.
+
+**Why:** IPi no longer assembles system prompts or owns model conversations.
+Keeping a public prompt object after deleting the embedded agent loop preserved
+an API with no supported product consumer.
+
+**Migration:** Build any harness-owned prompt text in Codex or Claude Code.
+Plugins should return typed harness results, context strings, or ordinary MCP
+tool values rather than importing IPi prompt helpers.
+
+### Legacy tool abstraction removal
+
+**Status:** Implemented.
+
+**Change:** The kernel-side `ipi.tools` priority registry, canonical `Tool`
+object classes, provider/TUI tool-name aliases, and IPi's internal
+`apply_patch` parser and dispatcher have been removed. IPi now retains only
+the argument validation used by its fixed notebook-control dispatchers and the
+packaged Notebook Agent Skill helpers. `apply_patch` remains a capability of
+supporting coding harnesses, not an IPi MCP tool.
+
+**Why:** None of these abstractions had an MCP consumer. The legacy
+`apply_patch` dispatcher targeted a `%%apply_patch` kernel magic that no longer
+exists, and the provider-name translation layer described an embedded agent
+runtime that IPi no longer owns.
+
+**Migration:** Register first-class MCP tools through `ServerSetup.tool()` and
+kernel behavior through `EnvironmentSetup` callbacks. Use `ipi.plugins.ToolContext`
+for tool access to the active session and kernel. Remove imports from
+`ipi.tools`, `ipi.tools.names`, and `ipi._patch`; call the coding harness's
+native patch tool when file patching is required.
+
+### Single distribution and MCP extra
+
+**Status:** Implemented.
+
+**Change:** The `ipi-core`, `ipi-runtime`, `ipi-mcp`, `ipi-tui`, and bundled
+`ipi-plugin-*` workspace distributions were replaced by one installable
+`ipi` distribution. Built-in plugins become modules in that distribution. The
+base dependency set supports kernel/shared code; the `mcp` extra supplies host,
+Jupyter, and harness dependencies.
+
+**Why:** The workspace members share one version, repository, release, and
+runtime product. Their manifests and exact cross-pins add resolution and
+maintenance complexity without providing independent ownership or reuse. A
+clean uv experiment verified that a Git-installed `ipi[mcp]` host can launch a
+base `ipi` kernel pinned to the same resolved commit without installing host-only
+dependencies in the kernel.
+
+**Migration:** Replace dependencies on internal IPi distributions with `ipi`.
+Replace `ipi_mcp` imports with `ipi.server`; imports from the shared `ipi.*`
+modules otherwise retain their names. Replace `ipi-mcp` launchers with:
+
+```bash
+uvx --isolated --from "ipi[mcp] @ git+https://github.com/nimashoghi/ipi.git@<ref>" ipi
+```
+
+External plugins remain separate distributions using the `ipi.extensions`
+entry-point group and are added to the host with `uvx --with`. IPi installs its
+base distribution into each child kernel at the exact source checkout, Git
+commit, or released version used by the host; launchers must not add the `mcp`
+extra to child kernels.
+
+### Host pins and kernel compatibility ranges
+
+**Status:** Implemented.
+
+**Change:** IPi now exactly pins its build dependency and every direct host
+dependency in the `mcp` extra to the versions validated for the release. The
+extra repeats exact versions for base packages used by the host. Base
+dependencies retain bounded compatibility ranges so a child-kernel overlay can
+select another supported version. `typed-agent-hooks` remains pinned to an
+immutable Git commit.
+
+**Why:** `uvx` installs from wheel metadata and does not consume the
+repository's `uv.lock`. Broad lower bounds allowed an unchanged Git tag to
+resolve a different FastMCP, MCP, IPython, ipykernel, Notebook, or Plotly release
+depending on installation date. IPi is an application whose host and child
+runtime need a tested compatibility envelope.
+
+**Migration:** Resolve plugin host dependencies against the exact direct host
+versions in the target IPi release. When a plugin genuinely needs a conflicting
+host dependency, release and validate a new IPi dependency set instead of
+relying on the installer to choose an untested combination. Kernel-only
+dependencies may select any version inside the declared base ranges when they
+do not conflict with IPi or another plugin contribution. Do not treat wheel
+metadata as a complete transitive lock; use the committed `uv.lock` for
+development and CI reproduction.
+
+### Server package import boundary
+
+**Status:** Implemented.
+
+**Change:** `ipi.server` no longer eagerly imports or re-exports
+`create_server`. Importing the package now works in a base child-kernel install,
+while executing the `ipi` command without the `mcp` extra reports the missing
+extra directly instead of raising `ModuleNotFoundError: fastmcp`.
+
+**Why:** The base distribution is intentionally usable in child kernels without
+FastMCP or other host-only dependencies. Eager package initialization violated
+that boundary and made even metadata-level imports fail.
+
+**Migration:** Replace:
+
+```python
+from ipi.server import create_server
+```
+
+with:
+
+```python
+from ipi.server.server import create_server
+```
+
+Launch the server from `ipi[mcp]`; the base-only console entry point is not a
+server installation.
+
+### Exact kernel dependency and plugin provenance
+
+**Status:** Implemented.
+
+**Change:** Caller and plugin kernel dependencies are now resolved by canonical
+distribution name before launch. Exact duplicates are deduplicated, but
+different requirements or editable modes for the same distribution are
+rejected. Explicit `pip` and `ipykernel` requirements replace IPi's defaults.
+Versioned and direct requirements are no longer rewritten to an implicit
+workspace editable.
+
+Installed plugin selection validates the configured requirement against the
+host distribution version and PEP 610 `direct_url.json`. The child validates
+its installed version, direct source, owning distribution, and entry-point
+target before loading the callback. Directory distributions prove their owned
+files or bounded editable runtime tree plus resolved import roots. Built-in,
+user, and project runtime trees are hashed at discovery and must have the same
+content when the child imports them.
+
+**Why:** Allowing pip to resolve conflicting plugin contributions made the
+child source depend on argument order and resolver behavior. Rewriting pinned
+requirements to a nearby checkout silently violated the selected source.
+Loading an entry point by name alone could then run a different plugin version,
+Git revision, archive, subdirectory, or mutated local file in the child.
+
+**Migration:** Make every contributor use one identical PEP 508 requirement and
+editable mode for each distribution. Declare an editable local path explicitly
+when live source is intended; relative paths passed through `EnvironmentSetup`
+resolve against that environment's cwd. Ensure selected direct URLs match the
+host installation's VCS source/revision, archive hash, and subdirectory;
+reinstall the host distribution from the intended source when they do not.
+Finish editing local plugin code before creating a kernel, or create a new
+kernel after rediscovery. Restart the IPi process after changing an installed
+directory/editable plugin: once its module is admitted, later source drift is
+rejected rather than executing bytecode from a different revision. A
+kernel-enabled entry-point module is imported in both the host and base-only
+child, so move host-only imports inside host callbacks and declare all
+module-level and kernel imports as child dependencies.
+
+### Credential-safe dependency reporting
+
+**Status:** Implemented.
+
+**Change:** Authenticated PEP 508 URLs remain available only in transient launch
+inputs and private live-kernel state. User information is removed from notebook
+metadata, child plugin payloads, session records, manifests, launch diagnostics,
+logs, kernel inventories, snapshots, MCP-visible runtime state, and validation,
+plugin-setup, or kernel-creation errors.
+
+**Why:** A private Git requirement must remain usable by `uv`, but copying that
+requirement into durable artifacts made it easy to commit a credential by
+accident. Provenance identity and child validation do not require URL user
+information.
+
+**Migration:** Do not read authenticated requirements back from inventory or
+session output. For private Git metadata with redacted credentials, provide the
+matching authenticated source through `IPI_INSTALL_REQUIREMENT` for child
+launches. `IPI_UV_WITH` is deprecated. IPi verifies repository identity and
+never writes these credential-bearing values to its artifacts. Hook forwarding
+now runs from the public `typed-agent-hooks` source and needs no IPi repository
+credential.
+`IPI_INSTALL_REQUIREMENT` authenticates only the IPi overlay itself and is no
+longer reused for unrelated installed plugin distributions. Private plugins
+must supply their own usable direct requirement through their plugin dependency
+declaration or host installation.
+
+### Strict and credential-safe configuration errors
+
+**Status:** Implemented.
+
+**Change:** `load_config()` now converts Pydantic `ValidationError` values into
+an attributed, input-free `ConfigError`. A missing TOML file remains optional,
+but permission errors, directory paths, and other non-missing I/O failures now
+propagate instead of silently loading defaults. `PluginSetupError` no longer
+retains a raw source or callback exception; its safe fields are `source_kind`,
+`source_location`, `error_type`, and `detail`. Runtime operations preserve a
+safe exception unchanged and replace only an exception whose text contains URL
+user information before FastMCP renders or logs it.
+
+Boolean tool/Jupyter fields and integer Jupyter fields are now strict: strings,
+integer booleans, floats, and Python booleans used as ports are not coerced.
+`jupyter.tunnel = true` requires Jupyter itself to be enabled. The named
+Jupyter tunnel fields described by the original change were subsequently
+removed; see "Jupyter Cloudflare tunnels are quick-tunnel only" above.
+
+**Why:** Pydantic's default error text includes the raw input value, and Python
+exception chains retain the original callback exception. Sanitizing only the
+outer message still exposed authenticated requirements through MCP failures,
+logs, or formatted tracebacks. Treating every `OSError` as a missing config also
+made an unreadable project silently run with unrelated defaults.
+
+**Migration:** Catch `ConfigError`, not Pydantic `ValidationError`, around
+`load_config()`. Code inspecting `PluginSetupError.source` or `.error` must use
+the safe fields above. Fix filesystem access errors rather than expecting IPi to
+ignore them. Error consumers must not depend on authenticated URL user
+information being present in an exception string. Replace coercible config
+values with literal TOML booleans and integers, and make tunnel dependencies
+explicit.
+
+### Immutable content-addressed output generations
+
+**Status:** Implemented.
+
+**Change:** Cell inputs and output artifacts now live below
+`outputs/cN/g-<sha256-prefix>/` rather than directly below `outputs/cN/`.
+The usual prefix is eight hexadecimal characters and extends automatically if
+another generation has the same prefix. Each generation stores its full digest
+in `.sha256`, and `manifest.json` records it as `generation_sha256`. Every path
+returned in a tool result or written to a session record names an immutable
+snapshot. Late output, `clear_output`, and cross-cell display updates publish a
+new generation and atomically replace `outputs/manifest.json`; they do not
+rewrite a path already given to an agent. Prior generations remain readable for
+the lifetime of the session.
+
+**Why:** Reusing one filename meant a late update or failed manifest commit
+could change or delete bytes referenced by an earlier tool result or JSONL
+record. Publishing complete immutable generations before swapping one manifest
+keeps old references valid and makes the latest-state commit failure-atomic.
+
+**Migration:** Do not construct artifact paths from handles or assume an
+artifact path will change in place. Use paths recorded in a tool result or
+`session.jsonl` when the exact response-time snapshot is required. Read
+`outputs/manifest.json` and follow its recorded input/artifact paths when the
+latest reduced state is required, including late display updates.
+
+### Compact lossless result protocol and identifiers
+
+**Status:** Implemented.
+
+**Change:** Model-visible MCP text results no longer use XML-shaped tags. They
+use tab-separated line records. Fields escape backslash, tab, carriage return,
+and line feed reversibly. A multiline header ends with an exact
+Unicode-code-point count; its body remains unchanged and the record ends with
+`end<TAB><record-name>`. Alternative
+artifact `part` records follow their exact output preview and carry its ordinal.
+Kernel inventories use counted tables with explicit columns and `\N` for null.
+
+Persisted Python and bash inputs are returned as `input<TAB><language><TAB><path>`
+references instead of echoing source already present in the tool call. The path
+names the exact immutable input artifact. Output bodies, errors, state changes,
+artifact MIME types, alternative parts, and suspension actions remain in the
+result. When the automatic PDB stack repeats a suspension location and exception,
+the live response emits those details once while the durable cell record retains
+its concise summary.
+
+Session directories now use `<inverted-nanoseconds>-<random-hex>` instead of
+also repeating a readable UTC timestamp. The inverted timestamp still preserves
+exact creation time and newest-first lexical ordering. PEP 610 build output
+omits a requested revision only when it is byte-for-byte identical to the full
+commit ID. Shortened hashes remain visible because the metadata cannot
+distinguish one from a hexadecimal branch or tag name.
+
+**Why:** Structural punctuation, repeated source, high-entropy path text, and
+duplicate identity fields consumed model context without adding information.
+The replacement keeps arbitrary bodies exact and makes every omitted repetition
+recoverable from an explicit artifact or durable record.
+
+**Migration:** Replace XML parsing and literal tag assertions with the line
+grammar above. Use the Unicode-code-point count, not a search for the terminator,
+to read multiline bodies. Split ordinary fields on tabs and reverse their
+escapes; treat `\N` as null only in table cells. Resolve input and output paths
+below the printed kernel output directory. Treat session and generation
+directory names as opaque identifiers; read `.sha256` or `manifest.json` when
+the full generation digest is required.
+
+### Bounded MCP output delivery
+
+**Status:** Implemented.
+
+**Change:** Individual text previews are limited to 64,000 characters and the
+aggregate content returned by one MCP tool call is limited to 256,000 UTF-8
+bytes. A bounded response retains its head and tail and includes the session
+artifact directory. Complete retained raw kernel outputs are still written to
+disk.
+
+**Why:** Unbounded MCP results can exceed client or model context limits and can
+make otherwise successful notebook execution unusable. Persistence, rather than
+the model-facing preview, is the authoritative output record.
+
+**Migration:** Consumers that require complete large outputs must read the
+artifact path recorded in the cell output or inspect the session's `kernels/`
+directory. Do not treat an MCP response preview as a lossless transport for
+arbitrarily large stdout, stderr, display data, or result text.
+
+### Typed Codex and Claude hook contract
+
+**Status:** Implemented.
+
+**Change:** Harness plugins now subscribe with `EnvironmentSetup.on_harness()`
+or `observe_harness()` using exact `typed-agent-hooks` shared or provider-native
+event classes. Both callbacks must be declared with `async def`; synchronous
+callbacks are rejected during plugin setup. The old `harness:*` string events
+and mutable `Harness*Ctx` values are no longer dispatched. Hook installation
+forwards every native event for the selected provider. For a recognized harness
+ancestor, failure to attach its expected bridge stops
+stdio startup; an unrecognized ancestor simply runs without forwarding.
+Individual hook callbacks still fail open.
+
+**Why:** Parallel wrapper models drifted from the provider schemas and made event
+composition, correlation, and failure semantics implicit. Direct typed models
+keep Codex and Claude behavior explicit while preserving a small IPi-owned
+runtime snapshot. Async-only callbacks can run on IPi's isolated callback loop;
+arbitrary synchronous Python cannot be stopped at a deadline.
+
+**Migration:** Replace string event registrations with typed event classes and
+return `typed_agent_hooks.shared.outputs` result values rather than mutating a
+context object. Convert every registered handler and observer from `def` to
+`async def`, use async I/O, and allow cancellation to propagate. Re-run
+`ipi install-hooks --provider codex` or
+`ipi install-hooks --provider claude_code` and restart the harness so all native
+events are installed.
+
+### Isolated hook callbacks and hard deadlines
+
+**Status:** Implemented.
+
+**Change:** `EnvironmentSetup.context()` now accepts only providers declared
+with `async def`, matching harness handlers and native observers. The timed hook
+path no longer loads config, discovers or imports plugins, or runs setup
+callbacks. It uses the pre-resolved startup environment for the exact startup
+cwd or the atomically published active environment for its exact cwd. An event
+from any other cwd fails open without plugin output.
+
+Actual handlers, observers, and context providers now run on one IPi-owned
+daemon event-loop thread rather than FastMCP's serving loop. The five-second
+callback and 25-second dispatch limits are hard response deadlines: IPi requests
+cancellation, fails open, and ignores a late result without waiting for a
+callback that suppresses `CancelledError`. Shutdown cancels submitted callback
+futures and boundedly joins the worker; truly stuck user code remains only on a
+daemon thread and cannot keep the MCP process alive.
+
+`HarnessRuntime.manager` has been removed. The callback runtime exposes only
+the immutable `snapshot`, `environment`, and `config` data needed to observe the
+current IPi state.
+
+**Why:** Cancellation-resistant plugin code must not block every HTTP operation,
+prevent the server event loop from closing, or retain direct access to mutable
+manager operations from another event loop. A daemon callback owner makes the
+response and process-lifecycle boundaries enforceable even though Python cannot
+forcibly terminate arbitrary user code.
+
+**Migration:** Convert every context provider to `async def`, use async I/O, and
+propagate `CancelledError`; code that suppresses it may continue running, but its
+result is discarded. Replace `runtime.manager` access with
+`runtime.snapshot`, `runtime.environment`, or `runtime.config`. Do not capture
+FastMCP-loop-bound futures, tasks, transports, locks, or clients in a callback;
+create async resources on the callback loop and use ordinary thread-safe state
+when sharing data with server setup. Create and activate a kernel for a project
+cwd, or restart IPi from that cwd, before expecting its project-specific hooks.
+Do not rely on a hook event to discover a new project environment.
+
+### Harness forwarding uses typed-agent-hooks directly
+
+**Status:** Implemented.
+
+**Change:** `ipi install-hooks` now writes a self-bootstrapping TAH forwarding
+command from the installed TAH Git source.
+IPi no longer installs an `ipi-hook-forward` tool environment or exposes the
+`ipi forward-hook` command. Hook configuration contains no IPi source or
+repository credential. Linux uses the existing Unix-socket rendezvous; macOS
+and stdio processes without a recognized Codex or Claude Code ancestor continue
+as notebook servers with forwarding inactive.
+
+**Why:** The forwarder belongs to TAH and imports no IPi or FastMCP runtime.
+Installing the full private IPi MCP distribution duplicated ownership, created
+a 156-package environment, required private Git authentication, and could place
+that environment on a different filesystem from uv's cache. TAH now emits an
+immutable uvx launcher itself, so its small cached environment survives the
+installer process without a second environment lifecycle.
+
+**Migration:** Re-run `ipi install-hooks` for Codex and Claude Code, then restart
+the harness. Keep `uv` available when hooks run. Remove
+`IPI_HOOK_INSTALL_REQUIREMENT` and `IPI_HOOK_RUNTIME_ROOT`; they are no longer
+read. The old `~/.local/share/ipi/hooks` directory can be deleted after both
+provider configs have been regenerated.
+
+### Authenticated MCP HTTP tunnels
+
+**Status:** Implemented.
+
+**Change:** Non-stdio transports accept `--tunnel` and optional
+`--tunnel-domain`. A public MCP tunnel now requires
+`IPI_MCP_HTTP_AUTH_TOKEN`; setup failure stops the server rather than silently
+advertising a local URL. Stdio rejects tunnel flags.
+
+**Why:** A public endpoint exposes trusted arbitrary code execution. A local
+fallback is acceptable for the Jupyter follow view but is misleading for an
+explicit MCP publication command, and an unauthenticated public tunnel is not a
+reasonable default even under the trusted-local execution model.
+
+**Migration:** Set `IPI_MCP_HTTP_AUTH_TOKEN` and give the remote MCP client the
+same bearer token or `token` query parameter. Use `--tunnel-domain` only with a
+configured named Cloudflare tunnel; omit `--tunnel` for local HTTP.
+
+### Built-in initialization and debugger plugins
+
+**Status:** Implemented.
+
+**Change:** Autoreload, project import, dataframe formatting, PDB, and Codex Apps
+now use reserved IDs `ipi.autoreload`, `ipi.project_import`,
+`ipi.dataframe_display`, `ipi.pdb`, and `ipi.codex_apps`. Startup actions are
+visible bootstrap cells. Bootstrap failure discards the new kernel and restores
+the previous active kernel. PDB is a normal annotated plugin tool, and Codex
+Apps supplies a generated kernel-side `ipi_codex_tools` package instead of
+dynamic MCP tools. The MCP host owns configuration, credentials, keyring access,
+network clients, and web search; the child package uses a private local bridge.
+IPi registers the generated package as top-level `tools` only when that import
+name is not already owned by the project or another dependency.
+
+**Why:** These features should exercise the same scoped plugin contract as
+third-party extensions. Transactional bootstraps prevent a half-initialized
+kernel from becoming active, and a static MCP catalog matches Codex's current
+tool-discovery behavior.
+
+**Migration:** Move configuration to `[plugins.config."ipi.<name>"]`. Import and
+call Codex app wrappers with `import ipi_codex_tools as tools`. Existing
+`import tools` cells still work only when the environment has no real `tools`
+module or package; reusable code must use the canonical name. Do not depend on
+old `ipi-plugin-*` setup hooks, dynamic Codex-app MCP schemas, child-side Codex
+credentials or clients, or provider/model metadata inside the kernel.
+
+### Bounded image reads
+
+**Status:** Implemented.
+
+**Change:** `view_image` rejects local or remote files larger than 25 MiB before
+base64 encoding them into an MCP image result. In remote mode, relative paths
+resolve against the target kernel cwd; unmapped target-native files are read by
+a bounded helper on the target instead of being resolved against the host.
+
+**Why:** Base64 expands the payload and MCP transports generally buffer the
+complete image. An unbounded read can exhaust the host or client before either
+can inspect the result. Target-aware resolution also prevents a WSL path from
+accidentally naming an unrelated host file.
+
+**Migration:** Resize or recompress larger images, or inspect them through the
+saved artifact and Jupyter notebook instead of `view_image`. Remote callers do
+not need a path-map entry for target-native image files.
+
+The old bundled distributions and transition loader have now been deleted. The
+Python subprocess hint and subprocess-pip gate are intentionally not replaced:
+IPi is a trusted local execution environment, and package-install policy belongs
+to the calling harness or project. Existing users that depended on the one-shot
+block must enforce that policy outside IPi.
+
+### Legacy extension runtime removal
+
+**Status:** Implemented.
+
+**Change:** `ipi.extension`, `HostExtensionsState`, `HostInitAPI`,
+`KernelInitAPI`, mutable tool registries, priority overrides, execution hooks,
+PEP 723 extension sidecars, `.agents/extensions`, and the `[extensions]`
+configuration namespace have been removed. The bundled `ipi-plugin-*`
+distributions no longer exist. Core notebook tools use one fixed dispatcher;
+plugin MCP tools register directly with FastMCP.
+
+The replacement `EnvironmentSetup` exposes only behavior that has a live
+consumer: typed harness handlers/observers, context providers, visible
+bootstrap cells, and kernel requirements. The speculative generic `on(...)`
+lifecycle API was removed until concrete, stable core events exist.
+
+**Why:** The legacy system maintained two competing plugin models and carried
+agent-loop concepts through every kernel launch and tool call. Inert parameters
+and compatibility loaders made ownership unclear and allowed extensions to
+replace core state-machine operations. The smaller contract keeps MCP schemas
+static, kernel setup attributable, and project state isolated without a general
+dependency-injection framework.
+
+**Migration:** Use `ipi.plugins.Plugin` and export a direct `plugin` value as
+described above. Move local files to `~/.ipi/extensions/` or
+`<project>/.ipi/extensions/`, and move configuration to `[plugins]`. Register
+model-facing tools with `ServerSetup.tool`; do not attempt to override
+`python`, `create_kernel`, `switch_kernel`, `wait`, or `interrupt`. Replace
+legacy execution hooks with a first-class MCP tool, kernel callback, visible
+bootstrap, context provider, or typed Codex/Claude hook according to the
+behavior being implemented.
+
+### Remote project paths require a shared host view
+
+**Status:** Implemented.
+
+**Change:** In remote kernel mode, `create_kernel(cwd=...)` now treats `cwd` as
+the kernel-side POSIX project path and resolves a separate, host-visible project
+root for `.ipi.toml`, local plugin discovery, MCP callbacks, harness callbacks,
+and context providers. Kernel creation fails when that host view is unavailable.
+Local user and project plugin paths are translated back into the kernel view
+before their kernel callbacks load.
+
+**Why:** Resolving `/home/...` with the host's `pathlib.Path` silently loaded
+defaults and plugins from the wrong filesystem under a Windows-host/WSL setup.
+Host callbacks cannot safely execute project code that exists only on the
+kernel target, so the shared boundary must be explicit rather than best effort.
+
+**Migration:** Configure `IPI_KERNEL_PATH_MAP` with semicolon-separated
+`<host-prefix>=><kernel-prefix>` pairs that make every remote project visible to
+both processes. For example, map a WSL UNC project root on Windows to its WSL
+POSIX root. Windows drive paths under `/mnt/<drive>` continue to use the built-in
+drive mapping. Move host-only project extensions to a shared location or install
+them as selected `ipi.extensions` distributions.
+
+### Portable model-facing paths on Windows
+
+**Status:** Implemented.
+
+**Change:** Artifact paths stored in cell records and AGENTS context identifiers
+now use `/` separators on every host platform. Native filesystem operations
+continue to use `pathlib.Path`; only strings exposed to models, records, and
+context consumers are normalized.
+
+**Why:** These values form a portable protocol between IPi, MCP clients, and
+saved session artifacts. Emitting Windows-only `\\` separators made otherwise
+identical sessions host-dependent and contradicted the documented relative-path
+examples.
+
+**Migration:** Consumers that compare these strings literally must expect `/`
+on Windows. Convert a returned path with `Path(value)` before performing native
+filesystem operations instead of constructing paths by splitting on either
+separator.