Technical Documentation: XiaomiMiMo/MiMo-Code

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

MiMoCode

MiMoCode is a terminal-native AI coding assistant. It can read and write code, run commands, manage Git, and use a persistent memory system to keep a deep understanding of your project across sessions while continuously improving itself.

Xiaomi MiMo Desktop Copy Chapter

Xiaomi MiMo Desktop is built for real-world work: one conversation can handle office work, design, coding, and multimodal creation, while multiple conversations can divide work and collaborate. The desktop app is powered by MiMo Code as its core engine, bringing its terminal-native intelligence to desktop workflows.

• Smart orchestration: evaluates task type and cost, then dynamically selects models, frameworks, and tools; complex tasks can run across multiple agents in parallel.
• Continuous iteration: drag in files in multiple formats, create PPTs, webpages, 3D assets, and apps, preview and operate on results in-session, edit selected regions precisely, and roll back versions.
• Controlled long-task cost: routes between standard and flagship models, edits only the required regions, and supports up to 99% same-session and 95% cross-session cache hit rates.
• Browser control: opens webpages, retrieves information, fills forms, and checks key interactions after generating webpages.
• Computer control (international version only): reads the screen and operates mouse and keyboard across apps; Record & Replay lets you reuse recorded workflows with natural language.

Powered by the new MiMo-V2.6-Pro and MiMo-V2.6-Flash models.

MiMoCode supports connecting to any mainstream LLM provider API.

Quick Start Copy Chapter

# One-line install (macOS / Linux)
curl -fsSL https://mimo.xiaomi.com/install | bash

# One-line install (Windows PowerShell)
powershell -ep Bypass -c "irm https://mimo.xiaomi.com/install.ps1 | iex"

# Run
mimo

The first launch guides you through configuration automatically. Supported options:

• Xiaomi MiMo Platform — OAuth login
• Codex (ChatGPT Pro/Plus) — OpenAI OAuth login
• Import from Claude Code — migrate existing authentication in one step
• Provider list — connect catalog providers by API key, or OAuth where supported (e.g. xAI/Grok)
• Custom Provider — add any OpenAI-compatible API in the TUI

WSL: clipboard issues

If you encounter garbled text when copying on WSL, install xsel:

sudo apt install xsel

macOS: rendering issues in the default terminal

MiMoCode does not support the built-in macOS Terminal (Terminal.app). If the interface is misaligned, flickers, or has other rendering issues, use iTerm2 or the VS Code integrated terminal instead:

brew install --cask iterm2

TUI lag and visual animation issues

If the TUI lags when run directly over SSH, render it locally and run only the MiMoCode server on the remote host. Start the server from the remote project directory:

# Remote host
mimo serve --port 4096

# Local host: create the SSH port forward
ssh -N -L 4096:127.0.0.1:4096 user@remote-host

# Local host: connect from another terminal
mimo attach http://127.0.0.1:4096

If decorative animation is causing the lag, run /vivid, or configure Vivid visuals in the ctrl+p command palette, to switch between Vivid and Minimal visuals as needed.

Windows: garbled CJK (Chinese/Japanese/Korean) output in the shell

On Windows with a non-UTF-8 system locale (e.g. zh-CN, whose active code page is 936/GBK),
command output containing CJK characters may appear garbled (mojibake). MiMoCode forces
UTF-8 output for spawned PowerShell/cmd subprocesses. If you still encounter garbled output
in cases this does not yet cover, enable Windows' system-wide UTF-8 support:

Settings → Time & language → Language & region → Administrative language settings →
Change system locale → check "Beta: Use Unicode UTF-8 for worldwide language support" →
reboot.

This switches the active code page (ACP) to UTF-8 (65001) for all programs, so subprocesses
no longer inherit the legacy code page. Note it is a system-wide Beta toggle and may cause
some older non-Unicode programs to display incorrectly, so treat it as a workaround.

MiMo Ecosystem Copy Chapter

Beyond MiMoCode, Xiaomi MiMo models also work in other agents and coding tools like Cursor, Cline, and Zed.

awesome-mimo-agent collects setup guides for using MiMo in those tools — worth a look if you want to try MiMo elsewhere. Contributions welcome: open a PR to add your own setup.

Core Features Copy Chapter

Multiple Agents Copy Section

Press Tab to switch between primary agents. Build and Plan can switch at any time; other custom or special modes lock once the first message is sent.

Persistent Memory Copy Section

Cross-session memory powered by SQLite FTS5 full-text search:

• Project memory (MEMORY.md) — persistent project knowledge, rules, and architecture decisions
• Session checkpoint (checkpoint.md) — structured state snapshots maintained automatically by the checkpoint-writer subagent
• Scratch notes (notes.md) — temporary note area for agents
• Task progress (tasks//progress.md) — per-task logs

Memory is injected automatically when a session resumes, so the agent does not need to relearn project context.

Intelligent Context Management Copy Section

• Automatic checkpoints — decides when to save session state based on the model context window
• Context reconstruction — when context approaches the limit, rebuilds it from the latest checkpoint, project memory, task progress, and retained recent messages so the agent can continue the current task
• Budgeted injection — uses a token budget to control how much checkpoint, memory, and notes content enters context, with importance ranking
• Adjustable compaction point — /context-limit (or compaction.max_context) makes a model compact earlier than its own window, per model

Compacting earlier than the model window (/context-limit)

Compaction normally fires just below the model's context window. Run /context-limit to
pick a smaller working budget for the current model — 200K / 300K / 500K / 1M or a
custom value — stored per model as compaction.max_context:

{
  "compaction": {
    "max_context": {
      "openai/gpt-5.6": "272K", // token count, "300K", "1M", or "50%" of the window
      "anthropic/*": "300K" // wildcards allowed, longest pattern wins
    }
  }
}

The value is always clamped to what the provider actually accepts, so it can only lower the
compaction point, never raise it. 0 restores the model's own window.

Why you might want it:

• Cost tiers. OpenAI prices GPT-5.6 prompts above 272K input at 2x input and 1.5x output
  for the whole request.
• The advertised window is not always what you get. The same model can have a different
  usable window depending on how you reach it — a ChatGPT/Codex subscription, a direct API
  key, or a reseller such as OpenRouter — so a catalog figure of 1M does not mean your route
  serves 1M.
• Quality and latency. Very long contexts are slower and, past a point, not better.

mimo models prints, per model, the window MiMoCode resolved and the token count
where it will compact. The prompt footer uses that same number as its denominator
(33.0K/260K↓ (13%) — the ↓ means a budget is in force), and /status breaks it down.

Task Tracking Copy Section

A tree-shaped task system (T1, T1.1, T1.2, …) that integrates automatically with the checkpoint system, so task progress is preserved when sessions resume.

Subagent System Copy Section

The primary agent can create subagents on demand. Subagents share the current session context and can work in parallel, with lifecycle tracking, cancellation, and background execution.

Goal / Stop Condition Copy Section

The /goal command sets a stopping condition for a session. When the agent tries to stop, an independent judge model evaluates the conversation to decide whether the condition is truly satisfied — preventing premature "optimistic stops" during autonomous work.

Compose Mode Copy Section

Use the /compose-next skill to run an end-to-end feature delivery loop: a single self-contained contract covering grill → workspace → spec → implement → verify → review → finalize → finish, with feature documents at docs/compose/spec/<feature>.md under the workspace root. Do not combine it with plan mode.

Workflows Copy Section

Workflows are deterministic JavaScript scripts that orchestrate multiple agents in a sandboxed runtime. Unlike agent conversations, workflows encode fixed phase sequences with bounded retries and automatic parallelization — fire-and-forget execution with no user interaction required.

MiMoCode ships with three built-in workflows:

Custom workflows: Place a .js file in .mimocode/workflows/ or .claude/workflows/ to define your own, or override a built-in by using the same name.

Builtin Skills Copy Section

Skills are reusable instruction sets that teach agents how to handle specific tasks (e.g. generating PDFs, writing academic papers, searching arXiv). For a new task, MiMoCode searches available skills by exact name, localized alias, and BM25 relevance. High-confidence matches are loaded automatically; uncertain matches are ranked for the agent to assess. In the TUI, type / to browse the autocomplete list or invoke a skill directly with /<skill-name> — mentioning two or more skills in a single message auto-loads them and injects a multi-skill orchestration plan.

MiMoCode bundles the following builtin skills:

claude-code and codex are exposed only when the claude and codex executables, respectively, are installed. Other skills may still require task-specific tools described in their instructions.

Overriding a builtin skill: Create a skill with the same name under the project (.mimocode/skills/<name>/SKILL.md) or personal (for example ~/.config/mimocode/skills/<name>/SKILL.md) MiMoCode skills directory. Open-standard .agents/skills/ in the project and ~/.agents/skills/ are compatible discovery roots. User skills discovered later in the scan order override builtins with the same name.

Configuring skills via environment variables

External skill roots (default surface is .mimocode + open-standard .agents):

External scans never match dotted path segments under skills/.

MIMOCODE_DISABLE_BUILTIN_SKILLS and MIMOCODE_DISABLE_OFFICIAL_SKILLS remove the corresponding skills from the agent's available skill list entirely — they will not appear in context and cannot be invoked. MIMOCODE_DISABLE_SLASH_SKILLS affects only TUI autocomplete; the skills remain available to agents.

Voice Input Copy Section

Real-time streaming voice input powered by TenVAD and MiMo ASR. Activate with /voice, then speak — audio is segmented by pauses and transcribed incrementally into the input. Available for MiMo logged-in users. Requires sox (brew install sox on macOS, other platforms similar).

WSLg audio setup

sudo apt install -y sox pulseaudio libasound2-plugins
export PULSE_SERVER=unix:/mnt/wslg/PulseServer

SSH remote audio (Mac → remote host)

# Mac (local)
brew install pulseaudio
pulseaudio --load="module-native-protocol-tcp auth-ip-acl=127.0.0.1" --exit-idle-time=-1 --daemonize
# Add to ~/.ssh/config: RemoteForward 4713 127.0.0.1:4713

# Remote host
apt install -y pulseaudio pulseaudio-utils sox
export PULSE_SERVER=tcp:127.0.0.1:4713
# Verify: pactl info

Non-MiMo voice providers (OpenRouter, internal API, etc.)

Voice input can route through other OpenAI-compatible providers via the voice config field. The ASR model (mimo-v2.5-asr) is only available on MiMo's platform; voice control mode (mimo-v2.6-flash) is available on OpenRouter and compatible relay platforms.

OpenRouter (voice control only):

Use /connect to sign in to OpenRouter, then add to your config:

{
  "voice": {
    "control_model": "openrouter/xiaomi/mimo-v2.6-flash"
  }
}

Internal / self-hosted relay (both ASR and voice control):

{
  "provider": {
    "internal": {
      "options": {
        "baseURL": "https://your-api-gateway.example.com/v1",
        "apiKey": "sk-..."
      },
      "models": {
        "xiaomi/mimo-v2.5-asr": { "name": "MiMo-V2.5-ASR" },
        "xiaomi/mimo-v2.6-flash": { "name": "MiMo-V2.6-Flash" }
      }
    }
  },
  "voice": {
    "asr_model": "internal/xiaomi/mimo-v2.5-asr",
    "control_model": "internal/xiaomi/mimo-v2.6-flash"
  }
}

Custom providers must register at least one model in their models field to be recognized. The model names in voice.*_model are sent directly to the API — they don't need to match the registered model keys exactly.

Note: Models registered under a custom provider will appear in the model selection list. Don't use ASR-only models (e.g. mimo-v2.5-asr) as your primary coding model.

Dream & Distill Copy Section

• /dream — scans recent session traces, extracts persistent knowledge into project memory, and removes outdated entries
• /distill — discovers repeated manual workflows in recent work and packages high-confidence candidates into reusable skills, subagents, or commands

Configuration Copy Chapter

MiMoCode uses JSON/JSONC config files with published JSON Schemas for autocompletion and validation.

File Locations Copy Section

On Windows, XDG paths fall under %LOCALAPPDATA%\mimocode\. You can override all paths with MIMOCODE_HOME.

JSON Schemas Copy Section

MiMoCode auto-injects a $schema field when it first loads your config, so your editor gets completions and validation out of the box:

VS Code / Cursor: trust the schema domain

Add to your settings.json so the editor can download schemas for autocompletion:

{
  "json.schemaDownload.trustedDomains": {
    "https://mimo.xiaomi.com/": true
  }
}

Data directories

Beyond config files, MiMoCode stores runtime data under XDG paths (or $MIMOCODE_HOME):

To remove stored credentials, delete auth.json from the data directory. On macOS, XDG data defaults to ~/Library/Application Support/mimocode/.

Custom OpenAI-Compatible Endpoints Copy Section

If your provider is not in the built-in model catalog, configure it directly with its base URL, API key, and model ID:

{
  "$schema": "https://mimo.xiaomi.com/mimocode/config.json",
  "model": "custom/MODEL_NAME",
  "provider": {
    "custom": {
      "name": "Custom",
      "npm": "@ai-sdk/openai-compatible",
      "only_configured_models": true,
      "models": {
        "MODEL_NAME": {
          "name": "MODEL_NAME"
        }
      },
      "options": {
        "baseURL": "BASE_URL",
        "apiKey": "API_KEY"
      }
    }
  }
}

• Use the exact keys baseURL and apiKey.
• Preserve the base URL and model ID exactly as supplied. MiMoCode does not require a known provider and you should not add or remove /v1 unless the endpoint requires it.
• The key under models is the upstream model ID. Model IDs containing / are supported because only the first / in model separates the provider ID from the model ID.
• Replace custom with another unused lowercase provider ID if needed, and use the same ID in the top-level model value.
• @ai-sdk/openai-compatible is for OpenAI-compatible APIs. Services using a different wire protocol require their provider-specific adapter.

Put user-wide settings in ~/.config/mimocode/mimocode.jsonc (or mimocode.json in the same directory), or project-only settings in .mimocode/mimocode.jsonc (or .json), and merge them with any existing configuration. Because apiKey is stored as plaintext, keep the file readable only by your user and never commit it. Run mimo models or use the TUI model picker to verify the configured model.

To declare which input modalities a custom model supports (image, audio, video, PDF), run /modalities in the TUI — a multi-select dialog that persists the setting to config without hand-editing.

Key Options Copy Section

• Provider and model selection
• Agent permissions and custom agents
• Checkpoint and memory behavior
• MCP server connections
• Keybindings and theme

Max Mode (parallel best-of-N reasoning with judge selection) can be enabled via experimental.maxMode in the config.

Allowing the system temp directory (/tmp)

By default, reading or writing files outside the project working directory triggers an
external_directory permission prompt — including the system temp directory. This is
intentional: MiMoCode does not silently widen permissions, so you stay in control of what
the model can touch outside your project.

The temp directory comes up often because most models reach for it as scratch space (e.g.
a quick script, a throwaway data file). If you trust your environment and would rather not
be prompted each time, you can opt in by allowing it in your config:

{
  "$schema": "https://mimo.xiaomi.com/mimocode/config.json",
  "permission": {
    "external_directory": {
      "/tmp/**": "allow"
    }
  }
}

This setting has known risks — use it at your own risk. The temp directory is
world-writable and shared with every other process and user on the machine. Auto-allowing
it means the model can read and write there without confirmation, which widens your exposure
to predictable temp-path / symlink tricks (e.g. another process pre-creating /tmp/foo as a
symlink to a sensitive file). For that reason it is only recommended for single-user,
controlled environments or inside a container. Keep the allowlist as narrow as possible.

Skipping permission prompts (--dangerously-skip-permissions)

For trusted, disposable environments (containers, sandboxes, CI) you can auto-approve
everything the agent does instead of confirming each action:

# TUI — prompts once for an explicit confirmation on startup
mimo --dangerously-skip-permissions

# Headless
mimo run --dangerously-skip-permissions "your prompt"

# Or via environment variable (any surface)
MIMOCODE_DANGEROUSLY_SKIP_PERMISSIONS=1 mimo

This injects an allow-all base underneath your config, so a tool with no rule
auto-approves — but any explicit rule you wrote still wins (the last matching rule wins,
and your rules sit after the injected *). A deny still blocks; note that a leftover
ask rule also still prompts, and a top-level "*": "ask" makes the flag a no-op. In the
TUI it shows a red warning and requires you to accept the risk before it takes effect (the
prompt is skipped when there is no TTY, so in CI it activates with no confirmation).

This is dangerous. With permissions bypassed, a malicious prompt, file, or plugin can
run arbitrary shell commands and read, modify, or exfiltrate your data without any
confirmation. Only use it where you fully trust the workspace.

For a lighter-weight option, the /skip-permissions command toggles auto-allow at runtime
inside the TUI: deny rules still block, and forced-ask operations (e.g. destructive bash)
auto-reject after 60 seconds with feedback the model can act on instead of hanging.

Development Copy Chapter

bun ci                   # Install dependencies (= bun install --frozen-lockfile)
bun run dev              # Run in development mode
bun run typecheck          # Type check

Relationship to OpenCode Copy Chapter

MiMoCode is built as a fork of OpenCode. It keeps all core OpenCode capabilities (multiple providers, TUI, LSP, MCP, plugins) and adds persistent memory, intelligent context management, subagent orchestration, goal-driven autonomous loops, compose-next end-to-end delivery, Dynamic Workflows, and self-improvement via dream/distill.

Community Copy Chapter

Scan the QR code to join the community group chat:

License Copy Chapter

Source code is licensed under the MIT License.

Use of MiMoCode is also subject to the Use Restrictions.
Use of Xiaomi MiMo-hosted services is subject to the MiMo Terms of Service.
Use of the MiMo name, logo, and trademarks is subject to the MiMo Trademark Policy.

Overview (`packages/cli/README.md`) Copy Section

js

To install dependencies:

bun ci

To run:

bun run index.ts

This project was created using bun init in bun v1.2.12. Bun is a fast all-in-one JavaScript runtime.

Overview (`packages/cli/src/acp/README.md`) Copy Section

ACP (Agent Client Protocol) Implementation

This directory contains a clean, protocol-compliant implementation of the Agent Client Protocol for opencode.

Architecture Copy Chapter

The implementation follows a clean separation of concerns:

Core Components Copy Section

• agent.ts - Implements the Agent interface from @agentclientprotocol/sdk

  • Handles initialization and capability negotiation
  • Manages session lifecycle (session/new, session/load)
  • Processes prompts and returns responses
  • Properly implements ACP protocol v1

• client.ts - Implements the Client interface for client-side capabilities

  • File operations (readTextFile, writeTextFile)
  • Permission requests (auto-approves for now)
  • Terminal support (stub implementation)

• session.ts - Session state management

  • Creates and tracks ACP sessions
  • Maps ACP sessions to internal opencode sessions
  • Maintains working directory context
  • Handles MCP server configurations

• server.ts - ACP server startup and lifecycle

  • Sets up JSON-RPC over stdio using the official library
  • Manages graceful shutdown on SIGTERM/SIGINT
  • Provides Instance context for the agent

• types.ts - Type definitions for internal use

Usage Copy Chapter

Command Line Copy Section

# Start the ACP server in the current directory
opencode acp

# Start in a specific directory
opencode acp --cwd /path/to/project

Question Tool Opt-In Copy Section

ACP excludes QuestionTool by default.

MIMOCODE_ENABLE_QUESTION_TOOL=1 opencode acp

Enable this only for ACP clients that support interactive question prompts.

Programmatic Copy Section

import { ACPServer } from "./acp/server"

await ACPServer.start()

Integration with Zed Copy Section

Add to your Zed configuration (~/.config/zed/settings.json):

{
  "agent_servers": {
    "OpenCode": {
      "command": "opencode",
      "args": ["acp"]
    }
  }
}

Protocol Compliance Copy Chapter

This implementation follows the ACP specification v1:

✅ Initialization

• Proper initialize request/response with protocol version negotiation
• Capability advertisement (agentCapabilities)
• Authentication support (stub)

✅ Session Management

• session/new - Create new conversation sessions
• session/load - Resume existing sessions (basic support)
• Working directory context (cwd)
• MCP server configuration support

✅ Prompting

• session/prompt - Process user messages
• Content block handling (text, resources)
• Response with stop reasons

✅ Client Capabilities

• File read/write operations
• Permission requests
• Terminal support (stub for future)

Current Limitations Copy Chapter

Not Yet Implemented Copy Section

1. Streaming Responses - Currently returns complete responses instead of streaming via session/update notifications
2. Tool Call Reporting - Doesn't report tool execution progress
3. Session Modes - No mode switching support yet
4. Authentication - No actual auth implementation
5. Terminal Support - Placeholder only
6. Session Persistence - session/load doesn't restore actual conversation history

Future Enhancements Copy Section

• Real-time Streaming: Implement session/update notifications for progressive responses
• Tool Call Visibility: Report tool executions as they happen
• Session Persistence: Save and restore full conversation history
• Mode Support: Implement different operational modes (ask, code, etc.)
• Enhanced Permissions: More sophisticated permission handling
• Terminal Integration: Full terminal support via opencode's bash tool

Testing Copy Chapter

# Run ACP tests
bun test test/acp.test.ts

# Test manually with stdio
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1}}' | opencode acp

Design Decisions Copy Chapter

Why the Official Library? Copy Section

We use @agentclientprotocol/sdk instead of implementing JSON-RPC ourselves because:

• Ensures protocol compliance
• Handles edge cases and future protocol versions
• Reduces maintenance burden
• Works with other ACP clients automatically

Clean Architecture Copy Section

Each component has a single responsibility:

• Agent = Protocol interface
• Client = Client-side operations
• Session = State management
• Server = Lifecycle and I/O

This makes the codebase maintainable and testable.

Mapping to OpenCode Copy Section

ACP sessions map cleanly to opencode's internal session model:

• ACP session/new → creates internal Session
• ACP session/prompt → uses SessionPrompt.prompt()
• Working directory context preserved per-session
• Tool execution uses existing ToolRegistry

References Copy Chapter

• ACP Specification
• TypeScript Library
• Protocol Examples

Overview (`packages/cli/src/sync/README.md`) Copy Section

tl;dr All of these APIs work, are properly type-checked, and are sync events are backwards compatible with Bus:

// The schema from `Updated` typechecks the object correctly
SyncEvent.run(Updated, { sessionID: id, info: { title: "foo" } })

// `subscribeAll` passes a generic sync event
SyncEvent.subscribeAll((event) => {
  // These will be type-checked correctly
  event.id
  event.seq
  // This will be unknown because we are listening for all events,
  // and this API is only used to record them
  event.data
})

// This works, but you shouldn't publish sync event like this (should fail in the future)
Bus.publish(Updated, { sessionID: id, info: { title: "foo" } })

// Update event is fully type-checked
Bus.subscribe(Updated, (event) => event.properties.info.title)

// Update event is fully type-checked
client.subscribe("session.updated", (evt) => evt.properties.info.title)

Goal

Syncing with only one writer Copy Chapter

This system defines a basic event sourcing system for session replayability. The goal is to allow for one device to control and modify the session, and allow multiple other devices to "sync" session data. The sync works by getting a log of events to replay and replaying them locally.

Because only one device is allowed to write, we don't need any kind of sophisticated distributed system clocks or causal ordering. We implement total ordering with a simple sequence id (a number) and increment it by one every time we generate an event.

Bus event integration and backwards compatibility Copy Chapter

This initial implementation aims to be fully backwards compatible. We should be able to land this without any visible changes to the user.

An existing Bus abstraction to send events already exists. We already send events like session.created through the system. We should not duplicate this.

The difference in event sourcing is events are sent before the mutation happens, and "projectors" handle the effects and perform the mutations. This difference is subtle, and a necessary change for syncing to work.

So the goal is:

• Introduce a new syncing abstraction to handle event sourcing and projectors
• Seamlessly integrate these new events into the same existing Bus abstraction
• Maintain full backwards compatibility to reduce risk

My approach Copy Chapter

This directory introduces a new abstraction: SyncEvent. This handles all of the event sourcing.

There are now "sync events" which are different than "bus events". Bus events are defined like this:

const Diff = BusEvent.define(
  "session.diff",
  z.object({
    sessionID: SessionID.zod,
    diff: Snapshot.FileDiff.array(),
  }),
)

You can do Bus.publish(Diff, { ... }) to push these events, and Bus.subscribe(Diff, handler) to listen to them.

Sync events are a lower-level abstraction which are similar, but also handle the requirements for recording and replaying. Defining them looks like this:

const Created = SyncEvent.define({
  type: "session.created",
  version: 1,
  aggregate: "sessionID",
  schema: z.object({
    sessionID: SessionID.zod,
    info: Info,
  }),
})

Not too different, except they track a version and an "aggregate" field (will explain that later).

You do this to run an event, which is kind of like Bus.publish except that it runs through the event sourcing system:

SyncEvent.run(Created, { ... })

The data passed as the second argument is properly type-checked based on the schema defined in Created.

Importantly, sync events automatically re-publish as bus events. This makes them backwards compatible, and allows the Bus to still be the single abstraction that the system uses to listen for individual events.

We have upgraded many of the session events to be sync events (all of the ones that mutate the db). Sync and bus events are largely compatible. Here are the differences:

Event shape Copy Section

• The shape of the events are slightly different. A sync event has the type, id, seq, aggregateID, and data fields. A bus event has the type and properties fields. data and properties are largely the same thing. This conversion is automatically handled when the sync system re-published the event throught the bus.

The reason for this is because sync events need to track more information. I chose not to copy the properties naming to more clearly disambiguate the event types.

Event flow Copy Section

There is no way to subscribe to individual sync events in SyncEvent. You can use subscribeAll to receive all of the events, which is needed for clients that want to record them.

To listen for individual events, use Bus.subscribe. You can pass in a sync event definition to it: Bus.subscribe(Created, handler). This is fully supported.

You should never "publish" a sync event however: Bus.publish(Created, ...). I would like to force this to be a type error in the future. You should never be touching the db directly, and should not be manually handling these events.

Backwards compatibility Copy Section

The system install projectors in server/projectors.js. It calls SyncEvent.init to do this. It also installs a hook for dynamically converting an event at runtime (convertEvent).

This allows you to "reshape" an event from the sync system before it's published to the bus. This should be avoided, but might be necessary for temporary backwards compat.

The only time we use this is the session.updated event. Previously this event contained the entire session object. The sync even only contains the fields updated. We convert the event to contain to full object for backwards compatibility (but ideally we'd remove this).

It's very important that types are correct when working with events. Event definitions have a schema which carries the defintiion of the event shape (provided by a zod schema, inferred into a TypeScript type). Examples:

// The schema from `Updated` typechecks the object correctly
SyncEvent.run(Updated, { sessionID: id, info: { title: "foo" } })

// `subscribeAll` passes a generic sync event
SyncEvent.subscribeAll((event) => {
  // These will be type-checked correctly
  event.id
  event.seq
  // This will be unknown because we are listening for all events,
  // and this API is only used to record them
  event.data
})

// This works, but you shouldn't publish sync event like this (should fail in the future)
Bus.publish(Updated, { sessionID: id, info: { title: "foo" } })

// Update event is fully type-checked
Bus.subscribe(Updated, (event) => event.properties.info.title)

// Update event is fully type-checked
client.subscribe("session.updated", (evt) => evt.properties.info.title)

The last two examples look similar to SyncEvent.run, but they were the cause of a lot of grief. Those are existing APIs that we can't break, but we are passing in the new sync event definitions to these APIs, which sometimes have a different event shape.

I previously mentioned the runtime conversion of events, but we still need to the types to work! To do that, the define API supports an optional busSchema prop to give it the schema for backwards compatibility. For example this is the full definition of Session.Update:

const Update = SyncEvent.define({
  type: "session.updated",
  version: 1,
  aggregate: "sessionID",
  schema: z.object({
    sessionID: SessionID.zod,
    info: partialSchema(Info),
  }),
  busSchema: z.object({
    sessionID: SessionID.zod,
    info: Info,
  }),
})

Important: the conversion done in convertEvent is not automatically type-checked with busSchema. It's very important they match, but because we need this at type-checking time this needs to live here.

Internally, the way this works is busSchema is stored on a properties field which is what the bus system expects. Doing this made everything with Bus "just work". This is why you can pass a sync event to the bus APIs.

Alternatives

These are some other paths I explored:

• Providing a way to subscribe to individual sync events, and change all the instances of Bus.subscribe in our code to it. Then you are directly only working with sync events always.
  • Two big problems. First, Bus is instance-scoped, and we'd need to make the sync event system instance-scoped too for backwards compat. If we didn't, those listeners would get calls for events they weren't expecting.
  • Second, we can't change consumers of our SDK. So they still have to use the old events, and we might as well stick with them for consistency
• Directly add sync event support to bus system
  • I explored adding sync events to the bus, but due to backwards compat, it only made it more complicated (still need to support both shapes)
• I explored a convertSchema function to convert the event schema at runtime so we didn't need busSchema
  • Fatal flaw: we need type-checking done earlier. We can't do this at run-time. This worked for consumers of our SDK (because it gets generated TS types from the converted schema) but breaks for our internal usage of Bus.subscribe calls

I explored many other permutations of the above solutions. What we have today I think is the best balance of backwards compatibility while opening a path forward for the new events.

Overview (`packages/cli/src/provider/sdk/copilot/README.md`) Copy Section

This is a temporary package used primarily for GitHub Copilot compatibility.

Avoid making changes to these files unless you only want to affect the Copilot provider.

Also, this should ONLY be used for the Copilot provider.

Overview (`packages/cli/src/skill/builtin/.bundle/docx-official/README.md`) Copy Section

docx skill

Apache-2.0 licensed toolkit for producing, editing, and reading Microsoft Word
(.docx) files with Claude. Written from scratch against the public
ECMA-376 / ISO/IEC 29500
specification of Office Open XML, so it can be embedded in commercial products
without special agreement.

What's here Copy Chapter

docx/
├── SKILL.md         entry point and decision matrix
├── create.md        authoring a .docx from scratch (python-docx recipes)
├── edit.md          template fill, XML surgery, tracked changes, comments
├── read.md          text extraction, structural walk, metadata
├── LICENSE          Apache-2.0 + third-party attributions
└── scripts/
    ├── explode.py            .docx → pretty-printed XML directory
    ├── assemble.py           XML directory → .docx
    ├── extract_text.py       extract plain text (stdlib fallback if lxml absent)
    ├── render_pdf.py         render to PDF via LibreOffice for QA
    ├── transcode.py          doc→docx, docx→pdf, docx→png via LibreOffice
    ├── audit.py              report-style well-formedness probes
    ├── resolve_revisions.py  accept every tracked change without Word/LibreOffice
    └── annotate.py           add a review comment (comments.xml + rels wired up)

Start with SKILL.md — it has the decision matrix that points you at the
right sub-guide.

Quick start Copy Chapter

All scripts include PEP 723 inline metadata, so
uv run resolves dependencies automatically:

uv run scripts/audit.py report.docx           # opens cleanly?
uv run scripts/extract_text.py report.docx    # what does it actually say?
uv run scripts/render_pdf.py report.docx      # visual sanity check

If you don't use uv, install dependencies once:

python3 -m pip install --upgrade python-docx lxml
# Optional but useful for the QA loop:
brew install --cask libreoffice           # or: apt-get install libreoffice
brew install poppler                       # for pdftoppm (PDF → PNG)

Author a document:

from docx import Document
doc = Document()
doc.add_heading("Q3 Financial Review", 0)
doc.add_paragraph("Revenue rose 12% YoY.")
doc.save("report.docx")

Run the standard QA loop:

uv run scripts/audit.py report.docx           # opens cleanly?
uv run scripts/extract_text.py report.docx            # what does it actually say?
uv run scripts/render_pdf.py report.docx             # visual sanity check

Design goals Copy Chapter

1. No proprietary dependencies. All runtime dependencies are permissively
   licensed (python-docx MIT, lxml BSD-3-Clause). Optional external tools
   (LibreOffice, Poppler) are invoked as CLIs; nothing is bundled or linked.
2. Standard library first. Scripts fall back to xml.etree and zipfile
   where practical, so text extraction and packing work in restricted
   environments that don't have python-docx installed.
3. Small, self-contained scripts. Each script has one job, a docstring
   with usage examples at the top, and a main(argv) entry point you can
   inspect at a glance. No plugin systems, no shared framework code.
4. Round-trippable. explode.py + assemble.py produce byte-for-byte stable
   archives when the source tree is unchanged, so version control on exploded
   docx trees stays sane.

What this is not Copy Chapter

• Not a full document renderer. Use LibreOffice, Word, or Pandoc for that.
• Not an ECMA-376 schema validator. audit.py runs quick well-formedness
  checks and a python-docx round-trip; it does not validate against the
  formal schemas.
• Not for .doc (legacy Word 97-2003), .docm (macro-enabled), or .rtf.
  Convert to .docx first with LibreOffice: soffice --headless --convert-to docx file.doc.

Attribution Copy Chapter

This skill is an independent implementation. Design patterns and API usage
come from public documentation of Office Open XML (ECMA-376 / ISO/IEC 29500)
and the linked open-source libraries. No third-party proprietary code is
included.

Third-party licenses Copy Chapter

This skill only bundles Apache-2.0 licensed code of its own. The runtime and
optional tools it calls out to have their own licenses, which you must
comply with when redistributing a product that ships (or auto-installs) any
of them:

If your product ships as a self-contained bundle that includes the GPL/MPL
binaries, review the corresponding license before release.

Contributing Copy Chapter

The skill is meant to be forked and adapted. When you extend it:

• Keep each script self-contained (single file, doc-string usage at the top,
  no shared helpers imported from elsewhere in the repo). It should be safe
  to copy any one script into another project.
• Match the existing docstring style and CLI shape (argparse, main(argv),
  numeric exit codes: 0 OK, 1 failure, 2 usage/IO).
• Test round-tripping (explode → assemble → inspect) against any docx you touch.

Overview (`packages/cli/src/skill/builtin/.bundle/pdf-official/README.md`) Copy Section

pdf skill

Apache-2.0 toolkit for reading, composing, transforming, and filling PDF
files. Built on top of permissively-licensed open-source libraries so the
guides and scripts can be embedded in commercial products without special
agreement.

Layout Copy Chapter

pdf/
├── SKILL.md            entry point + routing matrix
├── extract.md          pull text, tables, metadata, images out of a PDF
├── compose.md          author a fresh PDF (reportlab, canvas + Platypus)
├── transform.md        combine, carve, rotate, crop, watermark, encrypt
├── interactive.md      fill AcroForm widgets or stamp text onto scans
├── LICENSE             Apache-2.0 + third-party attributions
└── scripts/
    ├── survey.py           metadata + counts + form / scan hints (JSON out)
    ├── text_dump.py         extract text (poppler or pypdf; auto-fallback)
    ├── render_pages.py      rasterise pages via pypdfium2 (no GPL)
    ├── combine.py           append PDFs, optional --preserve-metadata
    ├── carve.py             split by range / per page / fixed chunk
    ├── reorient.py          rotate selected pages
    ├── recognize.py         Tesseract OCR wrapper, optional --parallel
    ├── sanity_check.py      graduated OK/INFO/WARN/ERROR check list
    ├── probe_fields.py      list AcroForm widgets OR dump page skeleton
    ├── apply_values.py      fill AcroForm from values.json (validated)
    └── overlay_text.py      stamp text/checks onto a non-fillable PDF

Start with SKILL.md — it has the routing matrix that points you at the
right sub-guide.

Quick start Copy Chapter

Install the permissive Python-only path:

python3 -m pip install --upgrade pypdf pdfplumber pypdfium2 reportlab Pillow

Add OCR and CLI helpers on demand:

# macOS
brew install qpdf tesseract poppler
# Debian / Ubuntu
apt-get install -y qpdf tesseract-ocr poppler-utils

Skim any document in three commands:

scripts/survey.py contract.pdf --pretty      # metadata, page count, form
scripts/text_dump.py contract.pdf > out.txt   # plain text
scripts/render_pages.py contract.pdf pages/   # PNG per page for inspection

Combine three quarterly reports and encrypt:

scripts/combine.py 2026Q1.pdf 2026Q2.pdf 2026Q3.pdf --out annual.pdf
qpdf --encrypt reader owner 256 --print=full -- annual.pdf annual-locked.pdf

Design goals Copy Chapter

1. Permissive default. Runtime Python deps are BSD / MIT / Apache. qpdf
   and Tesseract are Apache-2.0. Poppler (GPL) is optional — the skill runs
   end to end without it.
2. Single-file scripts. Every script under scripts/ is one file with a
   docstring at the top and a _main(argv) entry point. Any one script can
   be copied into another project without touching the rest.
3. Explicit coordinate systems. PDF points (y up from bottom) for
   authoring; image pixels (y down from top) for visual analysis. The
   conversion lives in one place (interactive.md §2.c).
4. Show the library call first, wrapper second. Every guide demonstrates
   the underlying pypdf/reportlab/pypdfium2 call before the CLI wrapper, so
   readers can swap in their own script.

What this is not Copy Chapter

• Not a pixel-perfect renderer — use a browser, pdftoppm, or pypdfium2
  directly for that.
• Not a schema validator. scripts/sanity_check.py is an "opens + round-trips
  cleanly" check, not conformance to ISO 32000.
• Not an XFA form filler. pypdf only handles AcroForm; XFA-only files must
  be flattened first.

Attribution Copy Chapter

Independent implementation. Design patterns come from public documentation
of the linked open-source libraries and the ISO 32000 PDF specification.

Third-party license attributions for every runtime dependency (pypdf,
pdfplumber, pypdfium2, reportlab, pdf-lib, pdfjs-dist, qpdf, Tesseract,
poppler-utils, ImageMagick) are enumerated in LICENSE. If you
are packaging this skill into a product, that section is what your legal
review should check — especially the notes on the optional poppler-utils
(GPL-2.0) and ImageMagick paths.

Contributing Copy Chapter

• Keep each script single-file with argparse + a _main(argv) entry.
• Prefer the Python-only path (no poppler, no ImageMagick) when both work.
• New capabilities go in the matching sub-guide (extract, compose,
  transform, or interactive) with a runnable example before the wrapper.
• Exit codes: 0 OK, 1 runtime failure, 2 bad usage, 3 validation
  failure.

Overview (`packages/cli/src/skill/builtin/.bundle/super-research/README.md`) Copy Section

super-research

English · 中文 · 日本語 · Français · Español · Русский

Claude Code / Claude.ai 的自主研究 skill。让 agent 长时间跑（几分钟到通宵）后，产出可对比、诚实、可审计的证据，而不是一个 one-shot 的黑箱答案。

灵感来源：Karpathy 的 autoresearch 方法论。此 skill 把它推广到六种研究模式。

是什么 Copy Chapter

一个"如果你把 agent 留一晚上，早上要能相信它的产出"的工作规程。核心不是具体流程，而是同一份纪律：

1. 先立契约再动手 — 把目标、主输出、停止条件写下来，确认一次。之后就不再问。
2. 基线先行 — 每种模式都有"我啥都没做时的答案"（原始代码 / 头三个搜索结果 / 未变换的原始数据）。先记录，否则"更好"和"显著"都无从谈起。
3. 每一步都进机读日志，失败也写 — TSV（不是 CSV，因为描述里会有逗号）。悄悄丢掉失败的尝试是最快的自欺方式。
4. 循环中不请示 — 契约定好后 agent 不停下来问"要不要继续"。人可能在睡觉。
5. 不作弊 — 不改 eval 代码，不筛选源，不 p-hack，不挑好看的子集。

六种模式 Copy Chapter

Skill 会根据用户话术自动选择模式。你也可以在 prompt 里明确指定。

相邻模式辨析（skill 自己也会挑，但你可以显式引导）：

• Experiment loop vs Benchmark：experiment 改进一个系统，benchmark 从多个候选里选。要"选型"就是 benchmark；要"把这个指标推低"就是 experiment。
• Experiment loop vs Ablation：都是改代码 + 测指标。experiment 择优保留；ablation 全部保留、绝不因为找到大效应而提前停 —— 目标是理解不是优化。
• Root-cause vs Experiment loop：root-cause 调查一个已经坏的基线；experiment 从一个可以工作的基线继续爬。日志字段和停止规则完全不同。

怎么用 Copy Chapter

一句话触发 Copy Section

Skill 会在符合触发词的场景下自动被 Claude 拉起来。你也可以在 prompt 里显式说：

「按 super-research 的 <mode> 模式，跑一晚，产物放 <dir>/」

典型的对话流 Copy Section

你 : 帮我在 lib_a、lib_b、lib_c 里选一个做文本清洗 —— 对比评测一下，
     不要调优候选，五个测试用例每个至少跑两次。
Claude: [触发 skill → 读 SKILL.md + references/benchmark-comparison.md]
        [起草契约：候选、任务矩阵、指标、公平预算、目录]
        [请你确认一次 —— 这是你最后一次开口的机会]
你 : 确认
Claude: [进入自主循环 — 冒烟测试 harness → 跑矩阵 → 每格记入 matrix.tsv →
         聚合 → drop-one-case 稳定性检查 → 生成 report.md]
        [产出最终报告：胜者 / 排名表 / 稳定性 / 集成成本 / 日志路径]

关键点：契约确认之后 Claude 不再提问。它可能跑几十分钟到几小时，你可以离开。

每种模式的产物 Copy Section

日志一律 TSV（tab 分隔），带表头。目录默认放在当前工作目录下，<tag> 用日期（比如 jul7）。

最终报告结构 Copy Section

所有模式最后都给一份紧凑的 markdown（≤1 页）：

• Contract：你让我做什么
• Baseline vs final：起点数字 vs 终点数字
• What worked：3–5 条带证据
• What didn't：死胡同、崩溃、矛盾 —— 这才是高信号
• Open questions / next steps
• Where to look：日志文件、分支、artifact 路径

要点是：让人在 5 分钟内验证工作、知道下一步看哪。不是讲故事。

目录结构 Copy Chapter

super-research/
├── SKILL.md                     # frontmatter (触发) + 共享纪律 + 模式选择表
├── references/                  # 六种模式各一份，触发后才被 Claude 读入
│   ├── experiment-loop.md
│   ├── topic-survey.md
│   ├── quant-analysis.md
│   ├── benchmark-comparison.md
│   ├── root-cause.md
│   └── ablation-study.md
└── evals/                       # 用于测试 skill 本身
    ├── evals.json               # 8 个测试 case 的定义 + 断言
    ├── toy_repo/                # experiment-loop 用（合成训练脚本）
    ├── toy_dataset/             # quant-analysis 用（Simpson's paradox 数据）
    ├── toy_bench/               # benchmark 用（3 个 cleaner × 5 个 case）
    ├── toy_regression/          # root-cause 用（可 bisect 的 5-commit 仓库）
    └── toy_pipeline/            # ablation 用（5 个可开关的 pipeline 组件）

Progressive disclosure（怎么设计的） Copy Chapter

• SKILL.md 常驻上下文：只放共享纪律 + 模式选择表。<100 行。
• references/<mode>.md 按需加载：Claude 挑一个模式后才读那一份 mode 文件。互不干扰。
• evals 完全不入上下文：只在跑 skill-creator 的评测时用。

这样 Claude 拉起 skill 时只多读几百行、进入模式后只多读一份 reference，不会把 6 种模式的规则全塞进去。

测试与迭代 skill 本身 Copy Chapter

evals/evals.json 里有 8 个 case，覆盖所有六种模式加两个纪律测试（"handles-crash-gracefully"、"ambiguous-goal-must-clarify"）。每个 case 有：

• prompt：给 agent 的原始指令
• files：需要放到工作目录的 fixture
• expectations：可编程验证的断言列表

跑评测的推荐路径：用 skill-creator skill（/skill-creator 或让 Claude 触发），它会：

1. 对每个 case 起两个 subagent —— 一个带 skill、一个不带（baseline）
2. 收集产物，跑断言，产出 benchmark.json 和 HTML 视图
3. 让人点开对比 with/without 差异

Fixture 都是自足的、秒级完成（toy_repo/run.py 用 time.sleep(0.5) 模拟训练；toy_regression/setup.sh 每次现生成 git repo；toy_pipeline/pipeline.py 是纯合成分数）。

我该什么时候**不**用这个 skill Copy Chapter

• 一次性的、几分钟能搞定的小任务 —— 用普通对话就行，别开循环
• 目标不能压成一个数字或一个可回答的问题 —— 先想清楚再来
• 结果需要每一步都让人拍板 —— 那本质上不是自主研究，是 pair programming

Skill 的价值在规模 × 纪律：跑十个便宜实验按同一套标准，胜过一个聪明但没验证的断言。这里没有便宜实验/没有可对比标准时，纪律就是空转。

Overview (`packages/cli/src/skill/builtin/.bundle/xlsx-official/README.md`) Copy Section

xlsx skill (Apache-2.0)

A permissively-licensed toolkit for creating, editing, reading, and analyzing
Microsoft Excel (.xlsx) files.

About Copy Chapter

This is an independent implementation, written from scratch against the public
ECMA-376 SpreadsheetML specification and built on permissively-licensed
third-party libraries. It is licensed under Apache-2.0 (see LICENSE),
which allows commercial use, modification, and redistribution.

• Written from scratch. The API surface follows what the ECMA-376
  specification and the underlying open-source libraries (openpyxl, pandas)
  naturally provide.
• Apache-2.0 licensed. Use it in commercial projects, ship it to customers,
  and fork it freely, subject to the terms in LICENSE.

Bundling this skill in a product? Copy Chapter

If you plan to redistribute this skill as part of a larger product, you take
on the license obligations of every dependency you ship with it. The core set:

None of these are copyleft in a way that "infects" your product code, but all of
them require you to keep their license text alongside anything you ship.
Practical checklist for a product build:

1. Copy this skill's LICENSE into your THIRD_PARTY_LICENSES/ or
   equivalent directory in your product.
2. Add the license texts of openpyxl, pandas, lxml, xlsxwriter (if you
   depend on them) — they usually live in the LICENSE file of each installed
   package.
3. If you install LibreOffice as part of your product, ship its LICENSE and
   NOTICE files too.
4. If you modified the skill, note the modifications (Apache-2.0 §4b).

What's inside Copy Chapter

Runtime requirements Copy Chapter

python3 -m pip install --upgrade openpyxl pandas lxml
# Recommended extras
python3 -m pip install --upgrade xlsxwriter openpyxl-image-loader
# For recalculation + PDF export:
#   macOS       brew install --cask libreoffice
#   Debian/Ubuntu apt-get install -y libreoffice

Note on the overview.py name: the script is deliberately not named
inspect.py, because that would shadow Python's stdlib inspect module and
break NumPy's import when the script's directory ends up on sys.path.

openpyxl writes formulas as strings — it does not evaluate them. If you emit
formulas and want their values to appear in the saved file, run
scripts/bake.py after saving. LibreOffice does the recalculation in a
headless subprocess.

Non-goals Copy Chapter

• .xls (legacy Excel 97-2003). Convert to .xlsx first with LibreOffice:
  soffice --headless --convert-to xlsx old.xls.
• VBA macros. This skill does not produce .xlsm files or write VBA. If
  the user needs automation, ship a Python script alongside the workbook.
• Real-time Excel automation (via COM on Windows or AppleScript on macOS).
  This is a file-in / file-out toolkit.

Where each capability lives Copy Chapter

Start at SKILL.md — the decision matrix routes you to the right
guide.

Overview (`packages/cli/src/skill/builtin/.bundle/super-research/evals/toy_bench/README.md`) Copy Section

toy_bench

A tiny stand-in for a real "select among N candidates" comparison. Three implementations of a text-cleaner, five fixed test cases, one correctness metric.

• candidates/cleaner_a.py, cleaner_b.py, cleaner_c.py — the three candidates. Each reads stdin, writes cleaned text to stdout. They differ in how they handle unicode, trailing whitespace, and empty input; none is uniformly best.
• cases/ — five input files (case01.in…case05.in) plus their gold outputs (case01.gold…). The comparison should hold this set fixed.
• run_case.sh <candidate> <case> — runs the candidate on the case and prints a similarity score (0.0–1.0, higher is better) plus a wall-clock time. If the candidate crashes or times out, the harness prints status=error and score 0.

The correct benchmark-mode behavior is: run each of the 3 candidates on each of the 5 cases (≥2 reps), log every cell including failures, and produce a ranking with a drop-one-case stability check.

Overview (`packages/cli/src/skill/builtin/.bundle/super-research/evals/toy_dataset/README.md`) Copy Section

toy_dataset

A synthetic 2000-row dataset with a deliberately misleading confounder (a Simpson's-paradox setup).

Files:

• dataset.csv — 2005 rows (5 are intentional duplicates), 4 columns: id, x, y, w (categorical A/B/C/D), age (~3% missing).
• generate.py — reproducible generator.

Question the user will ask: "Does X predict Y?"

Naive answer (raw correlation): corr(X, Y) ≈ +0.91 → strong positive relationship.

Correct answer (controlling for W): Within each W stratum, corr(X, Y) ≈ -0.63 → the true relationship is negative. The apparent positive raw correlation is entirely driven by W (which pushes both X and Y up together across strata).

An analyst following the quant-analysis mode should catch this by looking at distributions and cross-tabs before reporting the raw correlation.

Overview (`packages/cli/src/skill/builtin/.bundle/super-research/evals/toy_pipeline/README.md`) Copy Section

toy_pipeline

A stand-in for "which parts of my pipeline actually matter". Synthetic scoring — no real training — so ablations run in seconds.

• pipeline.py — the reference configuration. Prints score: X.YYYYYY (higher is better) and seed: N.
• Component switches at the top: ENABLED_NORMALIZE, ENABLED_DEDUPE, ENABLED_WEIGHT_BOOST, ENABLED_SMOOTH, ENABLED_GUARD. Toggle each to False to ablate.
• SEED is also at the top — changing it varies only the measurement noise, so a noise floor is observable.
• Run: python pipeline.py. Extract: grep "^score:" run.log.

Expected leave-one-out results (5 seeds each, reference noise floor ≈ 0.003):

The correct ablation-mode behavior: run the reference at ≥3 seeds first to establish the noise floor, then run each single-component-off configuration at ≥2 seeds, and produce a per-component classification. The guard-improves-when-removed row is the "surprising positive" the mode file warns to investigate rather than celebrate.

The fixture is deliberately transparent — deltas are explicit in pipeline.py. The eval isn't testing whether the agent can discover effects; it's testing whether the agent runs the full LOO matrix, logs every row (including the crash and the null), compares deltas against the measured noise floor, and reports the surprising positive honestly instead of quietly dropping it.

Overview (`packages/cli/src/skill/builtin/.bundle/super-research/evals/toy_regression/README.md`) Copy Section

toy_regression

A stand-in for "used to work, now broken — find why". Not a live git repo (the skill dir shouldn't nest git repos); setup.sh seeds a fresh one when the agent needs it.

• setup.sh <target_dir> — creates <target_dir> with an initialized git repo containing 5 commits. commit-1 is a working reference (all tests pass). commit-3 introduces a subtle regression (see below). commit-5 (HEAD) shows the symptom.
• The repro: python solver.py 0 should print even but raises ValueError: unexpected parity result: 0. python test_solver.py exits 1 with one failing case (classify(0)).
• Tests: python test_solver.py — plain assertions, no pytest dependency. Passes fully on commit-1 / commit-2, fails one case on commit-3 onward.

The planted regression (agent shouldn't peek at this until after the investigation): commit-3 rewrites is_even from return x % 2 == 0 to return x and (x % 2 == 0), adding a "short-circuit" comment. Looks defensive, but for x = 0 the and short-circuits to the value 0 (not False), and classify uses is True / is False identity checks that reject 0. Commits 2 and 4 are unrelated no-op refactors (adding a docstring, renaming a helper) — they look suspicious in a diff but aren't the cause.

The correct root-cause mode behavior: bisect to commit-3, then demonstrate two-way reversal (revert-only-commit-3 → tests pass; cherry-pick-commit-3-onto-HEAD~4 → tests fail).

Overview (`packages/cli/src/skill/builtin/.bundle/super-research/evals/toy_repo/README.md`) Copy Section

toy_repo

A tiny stand-in for a real training script. Used for testing autonomous research loops without spending minutes per experiment.

• run.py — the mutable file. Contains a handful of tunable constants at the top (LEARNING_RATE, HIDDEN_DIM, DEPTH, DROPOUT, MOMENTUM). Prints val_loss: X.YYYYYY (lower is better) and peak_memory_gb: Z.ZZ. Runs in about 0.5 s.
• Run with: python run.py
• Extract metric: grep "^val_loss:" run.log

Compose Spec Actor Drop Context (`docs/compose/spec/actor-drop-context.md`) Copy Section

feature: actor-drop-context status: delivered updated: 2026-09-14 branch: feat/actor-drop-context commits: bceb411c..655fa209 Copy Chapter

Actor tool: drop model-facing context

Report Copy Chapter

What was built — Model-facing actor spawn/run no longer accept any context argument. The JSON schema is a strict object without that field; the shell parser rejects --context after the three positionals with a teachable system-only error; execute always calls Actor.spawn with context: "none". Tool descriptions no longer advertise conversation/fork inheritance. System/runtime callers that already pass forkContext (checkpoint-writer, session peer) are unchanged.

Verification — bun typecheck (packages/cli) PASS; bun test actor.shell + checkpoint-tool-description + actor + actor-recover PASS (76); bun test actor/spawn + actor-subagent-gating + actor-spawn-preference PASS (37 pass, 1 skip live-router). Independent review: T1/T2 met, no critical findings; few-shot examples restored after review note.

Journey log — ① Root of desktop “spawn 秒退” was context:"full" registering a fork agent without ForkContext; ② Models must not create forks — only system callers keep that path; ③ Shell reject-after-positionals mirrors --actor so quoted positionals are not misread; ④ recoverActorArgs drops top-level context (safe none) while envelope context is schema-rejected; ⑤ Do not delete unrelated few-shot examples when rewriting tool copy.

[S1] Problem Copy Chapter

Model-facing actor spawn/run advertised context: none|state|full. context:"full" registers the child as a fork agent, but tool/actor.ts never passes ForkContext, so the child turn dies with empty MessageAbortedError ("秒退") while gate/postStop still fire. Models must not create forks.

[S2] Design Copy Chapter

• Model-facing actor tool supports only standard spawn/run (plus status/wait/cancel/send/models). No context field on JSON schema or shell parser.
• z.strictObject rejects any context key on spawn/run operations.
• Shell parser rejects --context / --context= after the three positionals with a teachable flag error (system-only message).
• Execute always calls Actor.spawn with context: "none". No checkpoint-summary injection from the tool path.
• System/runtime callers that already pass forkContext (checkpoint-writer, session peer) are unchanged.
• Tool copy (actor.txt, actor.checkpoint.txt) no longer teaches a model-facing context/fork parameter.

[S3] Out of Scope Copy Chapter

• Runtime Actor.spawn({context, forkContext}) API stays for system callers.
• Desktop UI/prompt snapshot updates (separate desktop pin follow-up).
• Changing contextMode registry semantics or fork runLoop itself.

Tasks Copy Chapter

• T1: Remove context from actor tool schema, shell parser, execute path, and tool descriptions — acceptance: spawn/run schema rejects context; shell rejects --context; execute always uses context:"none"; descriptions omit model-facing context (covers: S2)
• T2: Update/add unit tests — acceptance: shell rejects --context; schema rejects context; description tests do not require context="state"; actor/spawn system tests still pass (covers: S2; depends: T1)

Compose Spec Bun Text Import Esm Collision (`docs/compose/spec/bun-text-import-esm-collision.md`) Copy Section

feature: bun-text-import-esm-collision status: delivered updated: 2026-08-03 branch: fix/workflow-script-ext commits: 09d03d67..e8f1a8d1 Copy Chapter

Built-in workflow scripts collide with the ESM parser

Report Copy Chapter

What was built — The four built-in workflow scripts are no longer imported. A Bun macro
reads the directory at build time and their sources are inlined into the bundle, so the files
never enter the module graph and nothing can attempt to parse them.

Verification — From packages/cli.

The counts rise by one because the test that previously failed to load now runs.
bun run build:local compiles; bun build --target=bun src/workflow/builtin.ts shows the macro
call site replaced by an object literal, so the development fallback below is unreachable in a
bundle; mimo debug agent build from the compiled binary, run in an empty directory, loads the
workflow registry. bun.lock is unmodified.

Journey log

• The first fix renamed the files to .js.fn so no loader would try. It worked, and it was the
  wrong shape: the defect was that the scripts were reachable as modules, not that they were
  named .js. Renaming also took them out of oxlint and editor highlighting, and touched every
  reference to them. Asking what makes the failure impossible rather than unlikely gave a
  better answer than iterating on the first one that worked.
• The macro form was already in this codebase twice for the same job. Searching for precedent
  before inventing an extension would have found it immediately.
• Two Bun constraints only surfaced by running into them, and the published pattern in
  skill/builtin/extract.ts already encodes both — reading it properly instead of assuming its
  shape would have saved two failed builds.
• An explicit list of the four filenames survived into the first macro version out of habit.
  Nothing outside this module references those filenames, so it was pure ceremony from the era
  when static imports forced it.

[S1] Problem Copy Chapter

The four scripts in src/workflow/builtin/ are workflow function bodies, not modules: each
ends in a top-level return, because the sandbox evaluates them inside a function wrapper.
They were imported as raw text via with { type: "text" } so that they would embed into the
compiled binary, which has no source tree to read at runtime.

That left them reachable as modules, and under bun test one was occasionally loaded through
the ECMAScript parser instead of the text loader, where a top-level return is a syntax error:

# Unhandled error between tests
error: Top-level return cannot be used inside an ECMAScript module
    at .../src/workflow/builtin/fact-check.js:1:1

No assertion produced it. Bun counts the event once as a failure and once as an error, and one
test never starts, so a test file silently loses coverage. Reproducible with two files, in
either order, each of which passes alone:

bun test test/cli/tui/plugin-toggle.test.ts test/cli/tui/thread.test.ts

Continuous integration missed it because test.yml shards test files across four processes, so
the two files that collide are usually not in the same one.

Two measurements pinned it down. An onResolve hook showed the importer was always
builtin.ts itself — the legitimate text import, with no second importer anywhere — and that
thread.test.ts alone re-evaluates builtin.ts on the order of a hundred times in one
process, of which a handful took the ESM path. Three explanations were tried and falsified:
leaked test state (both files restore their spies), a static-plus-dynamic import race, and
cache exhaustion under concurrent re-imports; neither of the latter two reproduces standalone.

This reads as a Bun defect — a static import carrying with { type: "text" } should reach the
text loader every time — but no minimal standalone reproduction was isolated, so the trigger
for the re-evaluation remains unexplained.

[S2] Design Copy Chapter

builtin.macro.ts reads builtin/*.js with fs.readdirSync / fs.readFileSync and returns
{ file, script }[]. builtin.ts consumes it through with { type: "macro" }, so the call is
evaluated at transpile and the sources are inlined as string literals. A file read at build time
is never in the module graph, whatever it is named, which is why this fixes the cause rather
than the symptom — and why the scripts keep their .js names, stay inside oxlint's coverage,
and need no changes anywhere else.

The directory is the registry, as it is for built-in skills in skill/builtin/bundle.macro.ts.
Nothing outside this module refers to the filenames; consumers look workflows up by meta.name,
which each script declares itself.

Three consequences follow from that, all accepted because the directory is curated. Losing a
script is no longer a boot failure — it simply stops registering, and callers get the existing
unknown-workflow error — so builtin.test.ts asserts the registered set to make a deletion
loud. A stray .js dropped there becomes a shipped workflow rather than being inert, and a
malformed meta in it fails app boot. Two scripts declaring the same meta.name silently
last-wins, unchanged from before.

Two Bun constraints shape the call site, both already encoded in the pattern
skill/builtin/extract.ts established:

• Macros are not expanded in every transpile path. Under bun test the macro import is stripped
  without the call being replaced, surfacing as a ReferenceError, so the macro module is also
  imported normally and the macro form falls back to it. A try/catch is warranted here
  against the repository's general preference because a non-expanded macro is not otherwise
  detectable.
• Macro arguments must be statically known. A per-filename signature would make a misspelled
  name a build error, but it cannot pass through the fallback wrapper — the argument stops being
  static and the build fails with Cannot convert identifier to JS.

[S3] Out of Scope Copy Chapter

• Reporting upstream. This removes the repository's exposure, not the loader behaviour. The
  reproduction and measurements are recorded above so a report can be assembled without
  repeating the work.
• Why thread.test.ts re-evaluates builtin.ts a hundred times. It is the condition that made
  the collision likely and it presumably still holds.
• Rejected: renaming to .js.fn or .txt (treats the extension as the defect, costs lint
  coverage; .txt would also collide with session/prompt/compose.txt), and making the scripts
  valid ESM (the top-level return is the sandbox contract that user-authored workflows depend
  on).

Tasks Copy Chapter

• T1: Read the scripts through a build-time macro instead of importing them — acceptance: the two-file reproduction runs all four tests with no failure or error (covers: S2)
• T2: Add the dev fallback the macro pattern requires — acceptance: bun test loads the registry rather than throwing ReferenceError, and bun typecheck passes with no suppressions (covers: S2)
• T3: Confirm the sources still reach a compiled standalone binary — acceptance: the bundler output shows the macro call site replaced by a literal, and a command that loads the registry runs from the binary in an empty directory (covers: S2)

Compose Spec Checkpoint Capture Defect (`docs/compose/spec/checkpoint-capture-defect.md`) Copy Section

feature: checkpoint-capture-defect status: delivered updated: 2026-10-20 branch: fix/checkpoint-capture-defect commits: 115eeee3..6cb88c78 Copy Chapter

Checkpoint prefix capture defect containment

Report Copy Chapter

What was built — The prefix-capture closure installed by SessionPrompt.layer is now total except for interruption: one Effect.catchCause around the whole effect logs checkpoint prefix capture failed and returns the empty prefix, so a Provider.getModel / Session.get defect no longer escapes tryStartCheckpointWriter (and through fireCheckpoints the foreground turn) or fork-query. drainWriters classifies its snapshot of writer Deferreds with Deferred.isDone instead of reading the live map. The F40 test now settles writer1 and asserts the newest pending fires as a second writer.

Verification — bun run typecheck (packages/cli): PASS. bun test --timeout 30000 on prompt-effect, checkpoint-drain, checkpoint-fork-mode, checkpoint-child-session, checkpoint-main-slice, checkpoint-memory-write, prune, prune-skip-system in one process: 179 pass / 3 skip / 0 fail. New capture cases (unknown model / unknown session) and the drain "settling during drain" case were confirmed failing on the base code ({drained:0,timedOut:1}). After review nits: checkpoint-drain 4/4 PASS, typecheck PASS. Independent review: no critical findings.

Journey log

• Effect 4 beta: Effect.catch and Effect.ignore do not see a throw inside Effect.fn; best-effort boundaries need catchCause with a hasInterrupts re-raise.
• A drain test that forks the drain must use forkChild({ startImmediately: true }), otherwise the writer settles and is removed before the drain snapshots it.
• Review follow-up (not done): on a capture miss fork-query silently runs with an empty prefix; returning an explicit "unavailable" message would be clearer.

[S1] Problem Copy Chapter

Follow-ups from #2687. The prefix-capture closure that SessionPrompt.layer
installs into prefixCaptureRef is documented as best-effort, but
Provider.getModel and Session.get throw inside Effect.fn, which is a
defect. The closure guards them with Effect.catch, which only sees typed
failures. The defect escapes through tryStartCheckpointWriter, past
prune.ts's Effect.catch and the runLoop's fireCheckpoints(...).pipe(Effect.ignore),
and fails the user's current turn. tool/session.ts fork-query is exposed the
same way.

Secondary: drainWriters derives timedOut from writers.size after the wait.
The settle watcher deletes entries only after a DB write on a detached fiber,
and writers started during the wait are also counted, so the numbers can be
wrong (even negative drained). Return values are only logged today.

The F40 test in checkpoint-drain.test.ts claims to cover "drain pending" but
never settles writer1.

[S2] Design Copy Chapter

Capture is total except for interruption. The whole capture effect is wrapped
in Effect.catchCause: interrupts are re-raised, every other cause is logged
(checkpoint prefix capture failed) and the closure returns the empty prefix
({ system: [], tools: {}, inheritedMessages: [], parentPermission: [] }) — the
same value it already returns for a typed miss. One boundary covers both
callers (checkpoint writer, fork-query) and any future step added inside the
closure. The existing narrower getLanguage guard stays.

drainWriters classifies by Deferred. It snapshots the writing Deferreds it
waits on and, after the bounded wait, counts Deferred.isDone over that
snapshot. writers map membership is no longer consulted for the result.

F40 test covers pending. The test's stub actor exposes its spawned outcome
Deferreds; the test settles writer1 and asserts that a second spawn happens
(the queued pending fires).

[S3] Out of Scope Copy Chapter

• Replacing the module-global spawnRef / prefixCaptureRef (prod has one
  runtime; only test contamination is affected).
• The check-then-register window in tryStartCheckpointWriter between
  writers.get and writers.set (not reproduced; would need a reservation
  mechanism).
• Changing Provider.getModel / Session.get to typed failures (wide blast radius).

Tasks Copy Chapter

• T1: Wrap capture closure in interrupt-preserving catchCause — acceptance: real prefixCaptureRef.current called with an unknown modelID and with an unknown sessionID succeeds with the empty prefix; new tests fail before the fix (covers: S2)
• T2: drainWriters counts via Deferred.isDone over the snapshot — acceptance: checkpoint-drain.test.ts hanging-writer case still reports { drained: 0, timedOut: 1 }, and a settled writer reports drained: 1, timedOut: 0 (covers: S2)
• T3: F40 test settles writer1 and asserts pending fires a second spawn (covers: S2; depends: T2)

Compose Spec Checkpoint Writer Safety (`docs/compose/spec/checkpoint-writer-safety.md`) Copy Section

feature: checkpoint-writer-safety status: delivered updated: 2026-07-22 branch: investigate/checkpoint-writer-sandbox commits: 0cb81dba827e27549bde6fba794e27509ef1bf65..25f175dd Copy Chapter

Checkpoint Writer Safety

Report Copy Chapter

What was built - The checkpoint writer is now confined to normal paths under the memory tree at the unified write gate; the existing precise memory allowlist remains authoritative inside that tree. Dream/distill retain their prior memory-or-.mimocode/ behavior, while ordinary agents retain normal source writes. The gate now obtains its worktree from InstanceState.context, so InstanceRef-bound actor fibers cannot skip the sandbox.

Invalid-output recovery now selects an explicit role policy. Primary turns keep the user-facing reminder, ordinary actors receive a parent-facing reminder, and checkpoint writers receive a scoped recovery instruction that either finishes authorized memory edits or returns CHECKPOINT_COMPLETE. System-agent policy coverage is exhaustive. Terminal assistant errors now fail actor outcomes, so exhausted checkpoint recovery leaves the watermark unchanged through the existing transactional settlement path.

Verification - From packages/cli, bun test test/tool/memory-path-guard.test.ts test/tool/apply_patch.test.ts test/agent/ask-routing.test.ts test/session/invalid-output-continuation.test.ts test/actor/spawn.test.ts test/session/checkpoint-watermark-transactional.test.ts test/session/checkpoint-child-session.test.ts test/session/checkpoint-permission.test.ts passed 151 tests with 286 assertions and 0 failures. bun typecheck passed. git diff --check passed. Targeted oxlint reported 0 errors; remaining warnings were existing large-file/test idioms. Independent final review approved spec compliance, correctness, and codebase consistency with no remaining findings.

Journey log

• The incident was one writer reactivated by the generic user-facing empty-output reminder, not duplicate checkpoint-writer spawns.
• The unified memory guard was precise only after a path entered the memory tree; a separate checkpoint-writer memory-only sandbox was required for source paths.
• SessionPrompt.prompt could return a terminal assistant error that Actor previously converted to success; propagating that error restores watermark transactionality.
• A combined AppRuntime watermark E2E was process-state dependent, so stable boundary tests cover checkpoint exhaustion → actor failure and writer failure → unchanged watermark separately.
• Symlink/hardlink topology inside the application-managed memory tree is explicitly user-owned and outside this lexical path-boundary threat model.

[S1] Problem Copy Chapter

The checkpoint writer is a system-spawned actor whose successful work is expressed through memory-file edits followed by an intentionally empty stop. The generic invalid-output continuation treats that empty stop as a missing user-facing answer and injects a prompt telling the writer to answer the user or call another tool. Because the writer receives full parent context, that retry can make it resume the parent's development task instead of terminating.

The writer also receives general file-editing tools. Those tools call the unified write gate, but the current system-agent sandbox covers only dream and distill. The memory-specific guard precisely restricts checkpoint-writer paths only after a target is recognized as part of the memory tree; it permits non-memory targets to pass through. A drifted checkpoint writer can therefore edit source files with write, edit, or apply_patch.

The observed incident used both gaps: a generic empty-output retry reactivated a completed checkpoint writer, and the missing hard path boundary allowed it to patch project source. Prompt instructions and tool allowlists alone are insufficient because either can drift or be widened later.

[S2] Design Copy Chapter

[S2.1] Checkpoint Writer Write Boundary Copy Section

The unified write gate must enforce a checkpoint-writer-specific sandbox before applying the existing precise memory allowlist:

• checkpoint-writer may target only files under the resolved memory root.
• Within the memory root, assertMemoryWriteAllowed remains authoritative for canonical MEMORY.md, checkpoint.md, notes.md, permitted spillovers, and permitted task narratives.
• checkpoint-writer must not write project source, repository configuration, any worktree path, or .mimocode/.
• dream and distill retain their existing memory-root or worktree .mimocode/ sandbox.
• Primary and ordinary agents retain their existing source-write behavior.
• Every file-mutating tool that uses assertWriteAllowed, including write, edit, apply_patch, and notebook_edit, receives the same boundary. apply_patch must enforce it for add, update, delete, and both sides of move operations.

Removing apply_patch from the checkpoint writer's tool whitelist is not a substitute for this boundary.

[S2.2] Role-Specific Invalid-Output Policies Copy Section

Invalid-output continuation must select a policy from the execution role rather than sharing one user-facing prompt across all agents:

• A primary turn (agentID === "main") retains the existing user-facing retry that asks for a final answer or a valid tool call.
• An ordinary actor/subagent receives an actor-facing retry that asks it to return a usable result to its parent or continue the necessary tool work. It must not claim that it is answering the user directly.
• checkpoint-writer receives the checkpoint-specific policy in [S2.3].
• Existing system agents must declare an explicit policy. The declared policy keys and SYSTEM_SPAWNED_AGENT_TYPES must remain synchronized by a regression test so a future system agent cannot silently inherit a default user-facing retry.
• dream and distill require a non-empty summary and use a system/actor-facing retry rather than the primary-user wording.

Policy selection must be centralized near the invalid-output continuation. Do not scatter independent agent-name checks across the three run-loop classification sites.

[S2.3] Checkpoint-Specific Retry Copy Section

An empty or think-only checkpoint-writer stop remains retryable, but it must never receive the generic primary-agent reminder. The synthetic checkpoint reminder must:

• restate that the actor is the checkpoint writer;
• forbid answering or continuing the parent session's task;
• restrict further work to the authorized checkpoint and memory paths already supplied to the writer;
• tell the writer to finish any incomplete authorized edits; and
• tell the writer to return exactly CHECKPOINT_COMPLETE without further tool calls when the authorized edits are already complete.

The fixed marker is ordinary non-empty assistant text, so existing classification terminates naturally without a checkpoint-specific classifier branch. Existing bounded invalid-output retry limits remain in force. This design intentionally does not add a checkpoint content hash, write ledger, or dedicated commit tool: a capable model gets one correctly scoped recovery instruction, while the hard write boundary makes drift non-destructive.

[S2.4] Actor Error Outcomes Copy Section

If SessionPrompt.prompt returns a terminal assistant carrying assistant.error, Actor.runAgentLoop must fail instead of converting the result into a successful actor outcome with no text. This applies to all actors/subagents and does not change direct primary-session behavior.

For checkpoint writers, exhausting invalid-output recovery therefore produces a failed actor outcome. The checkpoint settlement watcher must leave last_checkpoint_message_id unchanged, preserving the existing invariant that an uncheckpointed delta is re-covered by a later writer.

[S2.5] Regression Contract Copy Section

Tests must cover the real boundaries rather than prompt text alone:

• checkpoint-writer source and .mimocode/ writes fail through the unified gate;
• valid checkpoint and project-memory writes continue to pass;
• unauthorized memory-tree paths continue to fail;
• apply_patch cannot mutate source as checkpoint-writer;
• primary, ordinary actor, and checkpoint-writer empty outputs receive their respective prompts;
• the checkpoint reminder contains no instruction to answer the user and converges when the model returns CHECKPOINT_COMPLETE;
• actor terminal assistant errors produce failure outcomes;
• primary invalid-output recovery and existing dream/distill sandbox behavior do not regress; and
• every system-spawned agent has an explicit invalid-output policy.

[S3] Out of Scope Copy Chapter

• Modifying Compose skills, compose.txt, the Compose workflow, or PR descriptions.
• Changing the checkpoint writer's full-context or child-session architecture.
• Removing file-editing tools from the checkpoint writer solely as a safety mechanism.
• Introducing a dedicated checkpoint commit tool, transactional multi-file writes, checkpoint hashes, or tool-history success ledgers.
• Changing checkpoint content schemas, spillover formats, memory paths, or watermark selection.
• Sandboxing direct shell filesystem writes for agents that are allowed to use shell tools; checkpoint-writer does not currently receive a shell tool.
• Detecting symlink or hardlink escapes deliberately placed inside the application-managed memory tree; this boundary protects normal resolved paths and .. traversal, not adversarial filesystem topology controlled by the user.
• Modifying or repairing historical database records.

Tasks Copy Chapter

• T1: Enforce the checkpoint-writer memory-only sandbox in the unified write gate - acceptance: checkpoint-writer source and .mimocode/ targets are rejected while valid memory targets, dream/distill behavior, and normal-agent source writes pass (covers: S2.1, S2.5)
• T2: Add centralized role-specific invalid-output policy selection and checkpoint completion-marker retry - acceptance: primary, ordinary actor, checkpoint-writer, dream, and distill receive their specified prompts, the checkpoint path converges on CHECKPOINT_COMPLETE, and system-agent policy coverage is exhaustive (covers: S2.2, S2.3, S2.5)
• T3: Propagate terminal assistant errors as actor failures - acceptance: an actor whose prompt terminates with assistant.error resolves failure, while successful text and structured actor results remain successful (covers: S2.4, S2.5)
• T4: Add apply-patch and checkpoint outcome regressions - acceptance: checkpoint-writer apply_patch cannot mutate source, valid checkpoint and project-memory mutations succeed, exhausted checkpoint recovery resolves actor failure, failed writer settlement leaves the watermark unchanged, and primary recovery remains unchanged (covers: S2.1, S2.3, S2.4, S2.5; depends: T1, T2, T3)
• T5: Run focused tests and package typecheck, then obtain independent review - acceptance: all focused suites and bun typecheck pass from packages/cli, and review confirms write-boundary, retry-policy, actor-outcome, and scope compliance (covers: S2.1, S2.2, S2.3, S2.4, S2.5; depends: T4)

Compose Spec Compaction Replay Keep Media (`docs/compose/spec/compaction-replay-keep-media.md`) Copy Section

feature: compaction-replay-keep-media status: delivered updated: 2026-10-14 branch: fix/compaction-replay-keep-media commits: e27e87de81..eba028f270 Copy Chapter

Compaction Replay Keeps Media

Report Copy Chapter

What was built — After provider-overflow compaction, the replayed last user message now copies every non-compaction part verbatim, including media file parts. The replayed image keeps its mime, filename, url (data URL) and source, so the client can render and preview it and the next model turn sends the image to the provider as image_url content. The summarization request still strips media under overflow. Durable attachment identity in the provenance envelope is the attachment's own file name and local path (from source.path, or from a file: URL when source.path is absent); [Image: <file name>] / [PDF: <file name>] markers in the message text carry that same file name, so the marker text itself is session-stable identity across compaction, handoff, and restarts.

Verification — From packages/cli: bun test test/session/prompt-effect.test.ts test/session/message-v2.test.ts --timeout 30000 passed (173 pass, 3 skip, 0 fail); bun test test/session/prompt-effect.test.ts --timeout 30000 -t "keeps replayed media" passed (17 assertions); bun run typecheck and git diff --check passed. The regression test drives the follow-up turn with an image-capable test model and asserts the HTTP request contains the real PNG as image_url and no [Attached image/png text; with the old placeholder substitution restored, the placeholder, source and wire-image assertions fail. Client end-to-end: a client build pinned to this branch ran mimo-dev/mimo-v2.6-flash through a local proxy that answered the first image-bearing request with a standard context-length error; the engine ran overflow compaction, the replayed message kept the same image file part (same data URL and source.path), the client rendered its thumbnail, the follow-up request carried the image, and the model described the image content. Independent review found no critical or major issues.

Journey log

• Overflow replay only fires when earlier user content remains after the replayed message is removed from the summarization input; a single-message session skips replay, so the test needs an earlier user message.
• Asserting on raw sessions.messages cannot detect replay regressions because it still contains the pre-boundary original.
• Images on send go through prepareImage; test fixtures must be decodable PNG/JPEG bytes, and the test model must declare image input or ProviderTransform replaces the image before the wire.
• A small context window (compaction.max_context or MIMOCODE_COMPACTION_TRIGGER_RATIO) only triggers threshold compaction, which never replays; reproducing replay requires the provider to reject the request as a context overflow.
• Provider requests can contain the literal image_url inside a tool description; detect real images on the wire with "image_url":{"url":"data:image/.
• Attachment identity that must survive compaction is the file name and local path already listed in the provenance envelope (the path is source.path, or the file: URL when source.path is absent). Paste markers ([Image: <file name>] / [PDF: <file name>]) carry the attachment's own file name, so the marker text itself is a durable key across compaction, handoff, or restarts; the envelope lists - filename (mime) plus path and tells the model to match a marker by that name.
• Clipboard pastes without a disk spill used to share the part name clipboard, so two pasted images collided in the envelope. Paste-time unique names (mimo-paste-…) give each attachment a distinct file name even when no local path exists.

[S1] Problem Copy Chapter

When the provider rejects a request as a context overflow, SessionCompaction.process runs with overflow: true. It takes the last real user message out of the compaction input, summarizes the earlier history, and then replays that user message as a new persisted user message after the summary so the model can answer it.

While copying the parts of the replayed message, the engine replaces every media file part (MessageV2.isMedia: images, PDF) with a text part [Attached <mime>: <filename>]. The replacement is written to the database. The original image content — a data: URL in url, plus source.path pointing at the local attachment file — is no longer referenced by the replayed message. As a result:

• The client renders the replayed message with the placeholder text instead of an image thumbnail, and the image cannot be previewed.
• The model never sees the image again, while the copied provenance envelope (# Files mentioned by the user …) still tells it to look at the attached image.

[S2] Design Copy Chapter

[S2.1] Replay copies media parts verbatim Copy Section

When replaying the user message after overflow compaction, every part except compaction is copied as-is, including media file parts. A copied file part keeps mime, filename, url and source unchanged; only id, messageID and sessionID are reassigned, exactly like every other replayed part. The [Attached <mime>: <filename>] substitution in the replay path is removed.

[S2.2] Replayed media reaches the model Copy Section

The replayed message is an ordinary user message after the compaction boundary. On the next turn its media file parts are converted to model file content by the normal MessageV2.toModelMessages path (no stripMedia), so the model receives the image.

[S2.3] Unchanged behavior Copy Section

• The summarization request itself keeps stripMedia: true under overflow: historical media is still dropped from the summary input.
• If the replayed message's media alone makes the next request overflow again, the existing overflow handling applies; this change adds no new retry or fallback path.

[S3] Out of Scope Copy Chapter

• Client rendering changes; message renderers already render persisted image file parts.
• The non-replay continue message and its overflow wording.
• Repairing messages already persisted with the placeholder text.

Tasks Copy Chapter

• T1: Copy media file parts verbatim in the overflow replay — acceptance: after provider-overflow compaction with a replayed user message containing an image/png file part, the persisted replayed message contains a file part with the same mime, filename, url and source as the original, and contains no [Attached image/png: …] text part (covers: S2.1)
• T2: Regression test for replayed media sent to the model — acceptance: in the provider-overflow compaction test, the summarization request does not contain the image data while the follow-up model request built from the replayed message contains the image data; the existing assertion on [Attached image/png: large.png] is replaced accordingly (covers: S2.2, S2.3; depends: T1)

Compose Spec Context Budget Control (`docs/compose/spec/context-budget-control.md`) Copy Section

feature: context-budget-control status: in-progress updated: 2026-08-05 branch: investigate/context-limit-double-rebuild commits: 028f3178..3b15062d Copy Chapter

Context Budget Control (user-adjustable early compaction)

Report Copy Chapter

What was built — compaction.max_context lets a user compact earlier than the model's own window, expressed as a token count, a "300K" / "1M" / "50%" shorthand, or a map keyed by "/<modelID>" with wildcards. Overflow.contextWindow() is the single place that resolves the provider cap (limit.input || limit.context), applies the budget as a clamp, and subtracts the reserves; usable() is now a thin wrapper over it, so the compaction trigger, checkpoint thresholds, and pruning all follow the budget without further plumbing. With no budget configured the arithmetic reduces to the previous expression for both model shapes.

The prompt and subagent footers divide usage by the internal trigger and mark a configured budget with ↓; the sidebar instead shows usage against the user-controlled active limit and compares that setting with the provider cap. /status gained a diagnostic Context block (window, budget + source, reserved, compact-at, used), and mimocode models prints the same underlying values without --verbose. /context-limit opens a preset picker (Model default / 200K / 300K / 500K / 1M / Custom…) that writes only the current model's key into the global config, refusing while a session is busy because a config write disposes the instance and cancels in-flight runners.

The 2026-07-31 follow-up makes usable() the only automatic context-switch boundary. Checkpoint thresholds continue to keep the checkpoint fresh, but their final 80%/90% rung no longer triggers an early rebuild. The sidebar presents the user-controlled limit relative to the provider cap, so a 300K budget on a 922K model renders limit 300K of 922K; the reserve-adjusted trigger remains an internal detail available in /status.

Separately, the merged PR #1926 was corrected: it assigned limit.context = 300_000 for every gpt-* model under Codex OAuth, which raised the window for gpt-4o (128K) and gpt-3.5-turbo (16K), broke the limit.context === 0 sentinel for image models, and never moved the compaction trigger for the 1M-class models it targeted because usable() reads limit.input when the catalog publishes one. It is now a clamp on both fields at 372,000 — the capacity OpenAI's Codex registry declares and that a 350,317-token request demonstrably reaches — applied only when a window exists and only when limit.input already exists. The 272K figure circulating for Codex is the 2x-input billing boundary, not capacity, so it ships as a documented compaction.max_context recipe (see S2.5).

Verification

• bun typecheck (packages/cli) — PASS, post-rebase.
• bun typecheck (packages/cli) — PASS for the 2026-07-31 follow-up.
• bun test test/session/auto-overflow-writer-first.test.ts test/session/prune.test.ts test/session/prompt-rebuild-reset.test.ts test/session/overflow.test.ts test/session/checkpoint-thresholds.test.ts test/cli/tui/sidebar-context.test.tsx — 94 pass / 0 fail for the 2026-07-31 follow-up.
• bun test test/session/overflow.test.ts test/plugin/codex.test.ts test/session/checkpoint-thresholds.test.ts test/session/prune.test.ts — 96 pass / 0 fail.
• bun test test/config test/session/checkpoint-thresholds.test.ts — 188 pass / 4 skip / 0 fail.
• Full bun test before the review fixes — 4359 pass / 4 fail; every failure reproduced at base or passed in isolation (test/util/ssrf.test.ts DNS fail-closed fails at base; test/workflow/runtime.test.ts has 2 fails at base vs 1 here; test/session/checkpoint-rebuild-unify.test.ts passes in isolation in both trees). CI runs the full suite.
• CLI: MIMOCODE_CONFIG_CONTENT='{"compaction":{"max_context":{"openai/gpt-5*":"300K","openai/gpt-5.6":200000}}}' bun run src/index.ts models openai → gpt-5.6 window 922K / budget 200K / compacts at 180K; gpt-5.6-sol budget 300K / 280K; gpt-5.3-codex (272K cap) shows no budget because 300K clamps away; gpt-4o and o3 unchanged.
• Live TUI (tmux, isolated MIMOCODE_HOME, xiaomi/mimo-v2.5): picking 300K wrote "xiaomi/mimo-v2.5": 300000 to the global mimocode.jsonc, footer became 33.0K/260K↓ (13%), and /status showed window 1.05M · budget 300K · compacts at 260K. The sidebar follow-up renders the user setting against the model limit (limit 300K of 1.05M) and covers it with a TUI render test. Custom "50%" wrote 524288 (compacts at 484K). "Model default" wrote 0 and restored compacts at 1.01M. Selecting a tier mid-stream left the config untouched and kept the dialog open; the same action once idle wrote 200000.

Journey log

1. PR #1926's real defect was not "insufficient" but inert: usable() prefers limit.input, which every 1M-class GPT model publishes (922K), so the 300K assignment only changed the display denominator and the MCP tool budget. Any future provider-cap correction must set limit.input, not just limit.context.
2. Instance.dispose() — which every config write triggers — cancels all runners via the SessionRunState scope finalizer. Any TUI feature that persists config mid-session needs a busy guard; sync.data.session_status is the server-authoritative signal (message-derived status can stay "working" forever after a crash).
3. Config merges cannot delete keys, and null would fail schema validation, so "reset to model default" is expressed as 0. Writing a single leaf key (not a read-modify-write of the whole map) avoids promoting project-level entries into the user's global file and is safe for both the JSON mergeDeep and the JSONC patchJsonc writers.
4. SDK regeneration is currently broken on main: bun dev generate emits a dangling #/components/schemas/__schema0 ref from ToolStateCompleted.providerOutput, so @hey-api/openapi-ts fails. Confirmed at base commit; new config fields therefore need a narrow cast at the TUI boundary until that is fixed.
5. usable() can be 0 for a positive window (window smaller than the reserves, or a large compaction.reserved), which would have rendered Infinity% in three footers. Any UI that divides by it needs the guard now in tui/util/model.contextWindow.
6. Provider "context window" numbers in the wild are frequently a billing tier or a client's conservative default, not capacity — Codex ships 372K capacity, a 95% effective window, a 90% auto-compact default, and a 272K price boundary, all four called "the context window" somewhere. Ask which one a number is before hard-coding it into limit.

[S1] Problem Copy Chapter

S1.1 Three different quantities are conflated into `model.limit.context` Copy Section

Because there is only one field, any attempt to express (1) or (2) corrupts the other two.

S1.2 PR #1926 audit — the fix does not fire, and it over-raises other models Copy Section

packages/cli/src/plugin/codex.ts:379 (merged in 94a79289):

if (modelID.startsWith("gpt-")) model.limit.context = 300_000

Defect 1 — no effect on the auto-compact trigger for the targeted models.
packages/cli/src/session/overflow.ts:21-23 prefers limit.input whenever it is set:

return input.model.limit.input
  ? Math.max(0, input.model.limit.input - reserved)
  : Math.max(0, context - outputReserve - reserved)

models.dev catalog (bundled at build time as packages/cli/src/provider/models-snapshot.js, cached at ~/.cache/mimocode/models.json) for the openai provider:

(reserved = min(20_000, maxOutputTokens); outputReserve = min(maxOutputTokens, 20_000); maxOutputTokens = min(limit.output, 32_000), packages/cli/src/provider/transform.ts:1550-1555.)

So for every 1M-class GPT model — the exact case the PR was filed for — compaction still triggers at ~900K. What did change is the display denominator (prompt/index.tsx:480, sidebar/context.tsx:81, subagent-footer.tsx:55) and the MCP tool-catalog budget (prompt.ts:1359). Net effect: the footer now reads 900,000 (300%) while the engine keeps going. The user-visible symptom moved, the behaviour did not.

Defect 2 — assignment instead of clamp. gpt-4o (128K real) and gpt-3.5-turbo (16K real) are raised to 300K, guaranteeing provider-side overflow errors that previously could not happen. gpt-image-* has limit.context: 0, a sentinel that overflow.ts:15,28,50 uses to disable overflow handling entirely; setting it to 300K defeats that guard.

Defect 3 — not overridable and not per-plan. The plugin auth loader runs at provider.ts:1310-1329, after the config-driven model merge at provider.ts:1169-1279. A user on a plan with a different real window cannot restore or lower the value from mimocode.json. The value is also a bare literal with no provenance, so nothing can explain it in the UI.

Defect 4 — wrong layer for the general need. Even a correct provider-layer clamp only serves "the provider lies about its window". It does not serve "I want to compact at 200K on a 1M model" for cost, latency, cache-churn or answer-quality reasons — a request already filed as issue #1837 ("Context occupancy meter (% + tokens) and adjustable auto-compact threshold"), and adjacent to #1840 (switching to a smaller-window model mid-session).

S1.3 Checkpoint thresholds apply a second context-limit discount Copy Section

Checkpoint percentages use usable() as their denominator, and the final 80%/90% threshold also signals the prompt loop to rebuild. A configured 300K active limit therefore reports a 280K trigger but rebuilds at 252K, while a configured "90%" budget rebuilds at roughly 90% × 90% of the provider cap. Checkpoint thresholds are snapshot scheduling policy, not a second context limit, so they must not trigger an active-context rebuild.

S1.4 Existing knobs and why they are insufficient Copy Section

• compaction.reserved (config.ts:254) can be abused as an early-compact dial (reserved = context - target), but it is global across all models, is also consumed by compaction.ts:49-54 and prune.ts:274-292 as a safety buffer, and produces a nonsensical number for anyone reading the config.
• provider..models..limit.input (config/provider.ts:40-46) does already move the trigger, but it is per-model JSON archaeology, it lies about the provider's real cap, and for the Codex case it is overwritten by the plugin (Defect 3).
• MIMOCODE_DISABLE_AUTOCOMPACT is all-or-nothing.

S1.5 Requirement summary Copy Section

1. A user-settable working budget, distinct from the provider cap, expressible in common tiers (200K / 300K / 500K / 1M) plus "model default" and a custom value.
2. Never exceeds the provider's effective cap — the setting clamps, it never raises.
3. Discoverable from the TUI without editing JSON, and the resulting number must be printable ("what is my current context window, and where will it compact?").
4. The provider-layer Codex bug fixed correctly and independently of (1)–(3).

S1.6 A completed high-usage turn is rebuilt twice Copy Section

SessionProcessor marks a successfully completed model turn as "overflow" when its reported usage reaches Overflow.usable(). The post-process overflow handler rebuilds immediately, but the same completed assistant usage remains visible to later prompt loops. The next user turn can therefore consume that usage again in the preflight overflow check, insert a second checkpoint boundary, re-arm checkpoint thresholds, and run tail microcompaction again.

For a configured 372K budget with the default 20K reserve, the first trigger is 352K (94.6% of the configured limit). This is the intended trigger. The defect is processing that one high-water usage record twice, not the trigger percentage.

[S2] Design — route-independent core Copy Chapter

S2.1 Vocabulary Copy Section

• hardCap(model) = model.limit.input || model.limit.context — the largest prompt the API accepts. 0 keeps its current meaning: unknown/not applicable, overflow handling disabled.
• budget(cfg, model, …) = user-requested working budget, or undefined.
• effectiveCap = hardCap === 0 ? 0 : min(hardCap, budget ?? hardCap).
• usable() keeps its current meaning: effectiveCap minus reserves. It stays the single source of truth for "when do we compact".
• Checkpoint thresholds only schedule checkpoint writers. Crossing the final threshold does not rebuild or compact; usable() remains the only automatic context-switch boundary.

S2.2 `Overflow.usable()` becomes budget-aware Copy Section

packages/cli/src/session/overflow.ts:13-24 is the only place the arithmetic changes:

export function usable(input: { cfg: Config.Info; model: Provider.Model; budget?: number }) {
  const hard = input.model.limit.input || input.model.limit.context
  if (hard === 0) return 0
  const cap = Math.min(hard, resolveBudget(input) ?? hard)
  const reserved = input.cfg.compaction?.reserved ?? Math.min(COMPACTION_BUFFER, ProviderTransform.maxOutputTokens(input.model))
  const outputReserve = input.model.limit.input ? 0 : Math.min(ProviderTransform.maxOutputTokens(input.model), OUTPUT_CAP)
  return Math.max(0, cap - outputReserve - reserved)
}

Invariants:

• With no budget configured, the returned value is byte-identical to today for every model (the limit.input branch keeps outputReserve = 0; changing that is PR #1265's scope, not ours).
• A budget larger than hardCap is silently clamped, never applied upward.
• A budget below reserved + outputReserve yields 0; isOverflow then fires on the first turn. Reject such values at the write boundary (S2.4) rather than letting the session brick.
• pressureLevel / contextPressureLevel inherit the new denominator for free, so checkpoint thresholds (prune.ts:274-292) and preserveRecentBudget (compaction.ts:49-54) follow the budget automatically.

New exported helper for callers that need the numbers without the reserves:

export function window(input: { cfg: Config.Info; model: Provider.Model; budget?: number }): {
  hard: number        // provider cap
  effective: number   // after budget clamp
  usable: number      // compaction trigger
  source: "model" | "config" | "session" | "plugin"
}

source exists so the UI and CLI can explain why the number is what it is (fixes Defect 3's opacity).

S2.3 Budget resolution order Copy Section

Highest priority wins; each layer is optional:

1. session override (only if Route C is chosen)
2. compaction.max_context keyed by "/<modelID>", longest-match glob allowed ("openai/gpt-5*")
3. compaction.max_context scalar (all models)
4. none → hardCap

S2.4 Config schema Copy Section

Added to the existing compaction struct (packages/cli/src/config/config.ts:239-258):

max_context: Schema.optional(
  Schema.Union(TokenBudget, Schema.Record(Schema.String, TokenBudget)),
).annotate({
  description:
    'Compact earlier than the model window. Number of tokens or a string ("300K", "1M", "50%"). ' +
    'Either one value for all models, or a map keyed by "<providerID>/<modelID>" (globs allowed). ' +
    "Always clamped to the model's real window; never raises it.",
})

TokenBudget = number | string. String parsing reuses the existing grammar of prune.parseThreshold (packages/cli/src/session/prune.ts:65-80: "40%", "100K", "1.5M", plain digits) — extract it into a shared helper rather than writing a second parser. % is relative to hardCap.

Validation at write time (config load warns, slash command refuses): value must leave at least reserved + outputReserve + 1 tokens, else it is ignored with a log.warn naming the model.

S2.5 Provider-layer fix for Codex (independent of the user-facing knob) Copy Section

packages/cli/src/plugin/codex.ts becomes a clamp that also closes the limit.input hole and respects the sentinel:

const CODEX_GPT_CONTEXT_CAP = 372_000
if (modelID.startsWith("gpt-") && limit.context > 0) {
  limit.context = Math.min(limit.context, CODEX_GPT_CONTEXT_CAP)
  if (limit.input) limit.input = Math.min(limit.input, CODEX_GPT_CONTEXT_CAP)
}

Clamping limit.input is what actually moves the trigger; clamping limit.context is what makes the display honest. limit.input is only touched when the catalog already publishes one — introducing it would switch usable() to the input branch and silently drop the output reserve (that would move gpt-4o from 91,616 to 111,616). gpt-image-* / gpt-3.5-turbo / gpt-4o keep their real windows.

The cap value, resolved during implementation (2026-07-27):

• 372,000 = capacity. OpenAI's Codex model registry declares context_window = max_context_window = 372000 for the gpt-5.6 variants (openai/codex#31860 quotes the served catalog, which also applies effective_context_window_percent: 95 and a 90% auto-compact default on top), and a direct Codex request with 350,317 input tokens completes (can1357/oh-my-pi#5705). So 272K is not a hard rejection boundary.
• 272,000 = billing. Prompts above 272K input are priced at 2x input / 1.5x output for the whole request, and Codex's bundled metadata was lowered from 372000 to 272000 (openai/codex#33972) to keep default sessions inside the cheaper tier — after openai/codex#32486 pointed out the 353.4K effective window ran ~81K past it.

Those are the two quantities S1.1 separates, so the provider layer takes 372K and the 272K line is documented as a compaction.max_context recipe rather than baked into the cap. Users on plans with a smaller served catalog window (openai/codex#33069 reports 272K for Pro Lite) can lower it the same way; the clamp form can only reduce, so a stale literal never produces an over-long prompt.

S2.6 Display / "how do I see my context window" Copy Section

Three surfaces compute % independently against raw limit.context today, and none of them matches the trigger. All three switch to Overflow.contextWindow():

The TUI may import Overflow.window directly — TUI modules already import from @/session/* (app.tsx:55, routes/session/index.tsx:100) — and it already holds sync.data.config plus sync.data.provider[i].models[id].limit. No new server route is needed for display.

Note this intentionally changes an existing user-visible number: the footer % will read higher than before for models whose reserves are large, because it is now measured against the value that actually triggers compaction. That is the point of the change and must be called out in the PR description.

S2.7 One recovery per assistant usage record Copy Section

Every overflow recovery path that successfully frees context in the post-process phase sets skipOverflowCheck before continuing the current run loop. Across run loops, a checkpoint or compaction boundary with an ascending message ID newer than the completed assistant marks that usage as already recovered. Boundary timestamps are backdated to the checkpoint watermark, so this comparison uses message IDs rather than timestamps.

The next iteration or user turn may call the model on the rebuilt or compacted context, but must not run checkpoint scheduling, preflight overflow, or exit-time pruning against the same completed assistant usage. This applies to main-agent checkpoint rebuilds and subagent/fork compaction paths. If recovery inserts nothing (insert-failed), no marker exists and the usage remains eligible because no context was freed.

The invariant is behavioral, not time-based: no cooldown or percentage margin is introduced. A later assistant turn with newly measured high usage may still trigger its own recovery.

[S3] Routes — decision required Copy Chapter

Storage location for the user's budget. All routes share S2.1–S2.2 and S2.6; they differ in where the value lives and therefore in scope, persistence, and cost.

Route A — config only (`compaction.max_context`), no UI writer Copy Section

• Add schema (S2.4) + usable() (S2.2) + display (S2.6) + docs. Users hand-edit mimocode.json.
• Scope: global or per-model, per project or per user. Persistent. Read by every usable() call site for free (cfg is already an argument at all 6 sites).
• Cost: smallest. No SDK regeneration beyond the generated Config type, no migration, no new dialog.
• Gap: does not satisfy the user's "slash option with preset tiers" ask; not discoverable.

Route B — Route A + `/context-limit` slash command writing global config **(recommended)** Copy Section

• Picker dialog: Model default · 200K · 300K · 500K · 1M · Custom…, applied to the currently selected providerID/modelID, written as compaction.max_context["openai/gpt-5.6"].
• Mechanism already proven: sdk.client.global.config.update({ config: patch }) → sdk.client.instance.dispose() → sync.bootstrap(), exactly as component/dialog-model.tsx:318-338 and dialog-modalities.tsx:72-96 do. Server routes exist (PATCH /global/config, server/routes/global.ts:171-195).
• Constraint discovered during design: a config write forces Instance.dispose(), whose finalizer cancels every runner (session/run-state.ts:36-51). The command must therefore be rejected while the session is busy (guard on session status) or deferred to idle. This is a hard constraint, not a preference.
• Scope: per-model, persistent across sessions and projects. Matches "设置到模型上".
• Cost: Route A + one dialog + one command registration + a busy guard.

Route C — per-session override (session column) Copy Section

• Nullable max_context column on session (session/session.sql.ts:14-48), migration folder migration/<ts>_session_max_context/migration.sql (ALTER TABLE session ADD max_context integer;), touch fromRow / toRow / toPartialRow (session.ts:64-112, projectors.ts:37-63), Session.setMaxContext next to setTitle (session.ts:681-720), extend the session.update body allow-list (server/routes/instance/session.ts:378-389), regenerate the SDK (./packages/sdk/js/script/build.ts).
• Requires threading sessionID (or the resolved budget) into the 6 usable() call sites: processor.ts:638, prune.ts:274, prune.ts:371, compaction.ts:53, prompt.ts:1334, prompt.ts:1346, prompt.ts:3203. All of them have sessionID in scope.
• Writes are safe mid-turn (patch() is a SyncEvent.run, no dispose) and propagate to the TUI automatically via session.updated (sync/index.ts:215-249, server/projectors.ts:11-24, tui/context/sync.tsx:439-452).
• Scope: per session, survives resume. This is what issue #1837's acceptance criteria literally ask for ("per-session and restored on resume", "does not rewrite global config unless save as default").
• Cost: highest — migration + SDK regen + signature churn across 7 call sites.

Route D — provider-layer fix only (S2.5) Copy Section

• Fixes the Codex bug correctly. Ships no user-facing knob. Should be done regardless of A/B/C because it is a correctness regression fix, and it is independently testable.

Decision (2026-07-27, user) Copy Section

Route D + B, with A as the substrate. Budget is keyed per model — compaction.max_context["/<modelID>"]; a scalar form stays accepted by the schema but /context-limit always writes the keyed form. Route C is deferred (see S4).

Recommendation Copy Section

D + B, with A as the substrate: D closes the shipped regression, A gives the durable expressible policy that every call site already reads, B makes it discoverable with the preset tiers requested. Defer C until per-session divergence is actually demanded — the per-model config value already covers "I always want 300K on this model", and C's cost is dominated by plumbing rather than by design risk. If C is chosen later it layers on top of A without changing A's semantics (it is priority 1 in S2.3).

Rejected alternatives:

• Overload provider.*.models.*.limit.context as the user knob (what #1926 does at plugin level): destroys the distinction in S1.1, lies to the provider-cap consumers (acp/agent.ts:76, prompt.ts:1359), and cannot express "compact early" without also mis-reporting the model.
• Overload compaction.reserved: global-only, and collides with its safety-buffer role in compaction.ts and prune.ts.
• TUI KV / model.json as the store: the TUI runs in a separate realm from the session engine (Worker + HTTP-shaped transport, tui/thread.ts:270-335, tui/worker.ts:50-68), so server code cannot read it in memory, and it would not apply to mimo run / serve / ACP clients.
• Per-request PromptInput.maxContext: not sticky across compaction continuations, retries, or LoopInput wakes (prompt.ts:4460), and needs threading into Processor anyway.

[S4] Out of scope Copy Chapter

• Per-session budget override (Route C) — deferred by the 2026-07-27 decision; layers on top of S2.3 priority 1 when demanded.
• Multi-pass compaction when history already exceeds the target window (issue #1840). A budget makes that state rarer, it does not resolve it.
• Changing the limit.input output-reserve semantics (open PR #1265).
• Lowering DEFAULT_CONTEXT_WINDOW (provider.ts:35), repeatedly proposed and closed (#1863, #648, #626).
• A live slider / drag UI. Preset tiers plus custom entry only.
• Per-agent or per-subagent budgets.
• Automatic budget inference from observed provider overflow errors.

Tasks Copy Chapter

Route D (do first, independent):

• T1: Replace the assignment in plugin/codex.ts with a clamp, including limit.input and the limit.context === 0 guard — acceptance: bun test test/plugin/codex.test.ts asserts gpt-5.6-sol → {context: 372K, input: 372K}, gpt-5.3-codex → {context: 372K, input: 272K}, gpt-4o → {context: 128K} unchanged and no input introduced, gpt-image-1 → {context: 0} unchanged, o3 → {context: 200K} unchanged (covers: S2.5)
• T2: Confirm the real Codex prompt cap and either keep the literal or make it plan-derived — acceptance: the chosen value is documented in a code comment with its source (covers: S2.5; depends: T1). Resolved to 372,000 with sources in the comment: OpenAI's Codex model registry declares context_window = max_context_window = 372000 for the gpt-5.6 variants (openai/codex#31860 quotes the served catalog), and a direct Codex request with 350,317 input tokens completes (can1357/oh-my-pi#5705). The 272,000 figure that Codex's bundled metadata was lowered to (openai/codex#33972) is the >272K 2x-input / 1.5x-output billing boundary, i.e. a spending policy — documented as a compaction.max_context recipe instead of baked into the cap.

Route A (substrate):

• T3: Extract the threshold grammar from prune.ts into Token.parseQuantity and unit-test "300K" / "1.5M" / "50%" / plain number / invalid input — acceptance: bun test covers all five, prune.ts behaviour and error messages unchanged (covers: S2.4)
• T4: Add compaction.max_context to the config schema with scalar + keyed-map forms and a validation warning — acceptance: a config with {"compaction":{"max_context":{"openai/gpt-5*":"300K"}}} type-checks and parses; a value below the reserves logs a warning and is ignored (covers: S2.3, S2.4; depends: T3). The warning fires on first use rather than at load, so it names the model it applies to.
• T5: Make Overflow.usable() budget-aware and add Overflow.contextWindow() per S2.2 — acceptance: unit tests show (a) no budget → identical numbers to main for a limit.input model and a context-only model, (b) budget above the cap is clamped, (c) budget 300K on a 1.05M/922K model yields usable = 280K and isOverflow fires there (covers: S2.2; depends: T4)
• T6: Document compaction.max_context wherever compaction.* is documented — acceptance: the doc states the clamp rule and the "/<modelID>" key form (covers: S2.4; depends: T4)

Route B (UI writer):

• T7: Add /context-limit command + preset picker dialog writing compaction.max_context["/<model>"] via global.config.update → instance.dispose() → sync.bootstrap() — acceptance: selecting 300K on a 1M model persists to the global config, the footer denominator updates without restart, and Model default resets the model (covers: S3 Route B; depends: T5). Reset writes 0 instead of deleting the key — a config merge cannot delete.
• T8: Refuse the write while a session is busy, with an explanatory toast — acceptance: invoking the command mid-turn leaves the config untouched; the same action once idle writes (covers: S3 Route B; depends: T7)

Display (needed by any route):

• T9: Switch the prompt footer, sidebar context widget, and subagent footer to Overflow.contextWindow() — acceptance: prompt/subagent usage uses the internal trigger, while sidebar usage uses the active setting and compares it with the provider cap (covers: S2.6; depends: T5)
• T10: Add a Context block to the /status dialog showing provider window, budget + source, reserved, compact-at, current tokens and % — acceptance: with and without a configured budget the block renders correct numbers and the correct source label (covers: S2.6; depends: T5)
• T11: Surface the context window in the models CLI command without --verbose — acceptance: mimocode models openai prints each model's provider window and compact-at (covers: S2.6; depends: T5)
• T12: Decouple the final checkpoint threshold from the prompt-loop rebuild condition — acceptance: crossing the final checkpoint threshold below usable() writes a checkpoint but inserts no rebuild or compaction boundary; reaching usable() still follows the existing rebuild path (covers: S1.3, S2.1; depends: T5)
• T13: Show the configured active limit relative to the provider hard cap in the sidebar — acceptance: a 300K budget on a 922K model renders limit 300K of 922K, while the reserve-adjusted trigger remains internal and available in /status (covers: S2.6; depends: T5)
• T14: Consume each assistant usage at most once during overflow recovery — acceptance: post-process recovery sets the current-loop skip guard; across user turns, a newer boundary prevents the recovered assistant from driving checkpoint scheduling, preflight overflow, or exit-time pruning; equivalent subagent/fork recovery paths set the same guard (covers: S1.6, S2.7; depends: T12)
• T15: Add regression coverage for duplicate recovery — acceptance: a low-usage initialization turn, a successful high-usage turn, and a following user turn produce two distinct checkpoint boundaries on current main, but exactly one boundary and one writer after T14; existing preflight and provider-overflow fallback tests remain green (covers: S1.6, S2.7; depends: T14)

Compose Spec Cron Session Affinity (`docs/compose/spec/cron-session-affinity.md`) Copy Section

feature: cron-session-affinity status: delivered updated: 2026-10-12 branch: fix/cron-session-affinity commits: 3c6e6bb0..4c3a7e46 Copy Chapter

Cron Session Affinity

Report Copy Chapter

What was built — Scheduled cron / loop prompts now fire into the session that created the job instead of whichever session first started the process-wide CronBridge. onFire resolves the inject target via fireTargetSessionId(task, bridgeSession); createdBySessionId is stamped on armLoop and inherited across keepalive re-arms so a loop owned by session B keeps its stamp even when the bridge is mounted on A. get / delete / rename / list share one ownership rule: hide only tasks stamped to another session; legacy unmarked rows stay visible and fire into the current bridge session. Empty-string stamps count as unmarked everywhere.

Verification — bun test packages/cli/test/cron packages/cli/test/tool/cron.test.ts packages/cli/test/session/cron-bridge.integration.test.ts → 79 pass / 0 fail. bun run typecheck → PASS. Lint on touched files: 0 errors (warnings pre-existing). Review 1 of 3c6e6bb0..bfdb2b17 found CRITICAL (keepalive armLoop dropped the owner stamp) → fixed in 082b8124. Review 2 of the PR found CRITICAL on the post-fire path (one-shot loop row removed after fire, so inherit-from-prior found nothing) → fixed in 4c3a7e46 by persisting the owner on LoopState. Re-review of 4c3a7e46 → APPROVE, no remaining criticals.

Journey log —

1. User guess "cron never marks the session" was only half-right: createdBySessionId existed on schedule but was ignored at fire time and never written by armLoop.
2. loop is not a standalone tool: /loop is a skill wrapping cron schedule; cron also has a loop action (armLoop). Both shared the wrong-session fire path.
3. Desktop EngineInstanceStore already accepts cron into non-active sessions by design (R2/R9); the bug was engine-side routing, not desktop mis-attribution. Sidebar lag for a never-listed session (30s poll) is a UI-discovery gap, out of scope.
4. Keepalive affinity needed two layers: inherit-from-prior covers supersession of a live row; LoopState.createdBySessionId covers the post-fire path where the one-shot row is already gone. Persist owner on the longer-lived state object.
5. e2e fireToInject mirrors production onFire rather than invoking it (AppRuntime dynamic-import seam); helper-level tests cover the contract, not the live callback wiring.

[S1] Problem Copy Chapter

Users (notably from mimo-desktop multi-session hosts) report that scheduled
cron / loop prompts fire into the wrong session. Code confirmed this:

• CronBridge.onFire always injected into handle.sessionID (the first session
  that called start) and never read task.createdBySessionId.
• CronBridge is a single-slot singleton; a second session's start is a no-op,
  so every fire in the process landed on the first session.
• scheduler.armLoop never wrote createdBySessionId, so loop tasks had no
  owner stamp at all (and keepalive re-arm dropped any stamp).
• get / delete / rename only applied a session filter when the caller
  explicitly passed session_id; the tool schema claims "defaults to current
  session" but did not enforce it.
• LoopState is a process-global map keyed by prompt text only.

[S2] Design Copy Chapter

Fire routing Copy Section

When a task fires, inject into the task's owning session:

1. Target session = task.createdBySessionId when present (truthy).
2. Legacy / unmarked tasks (no stamp, or empty-string stamp) fall back to the
   current bridge session (previous behavior) so existing durable jobs keep firing.

injectScheduledPrompt already accepts an explicit sessionID; onFire passes
the target session rather than handle.sessionID. Sentinel expansion
(resolveAtFireTime) uses the bridge's workspaceRoot and the target
session id so the cache is keyed per receiving session.

Session stamping Copy Section

• scheduler.add stamps createdBySessionId when input.session_id is set.
• armLoop accepts and stamps session_id. Owner resolution is truthiness
  ("" = unmarked): explicit session_id, else a stamped prior same-prompt
  loop task, else LoopState.createdBySessionId. LoopState outlives the
  one-shot task (which the tick removes after fire), so post-fire keepalive
  re-arms still stamp the creating session.
• The cron tool's loop action passes sessionID (resolved like schedule).

Ownership on read/update/delete Copy Section

• CronTool always passes session_id: sessionID (resolved from
  op.session_id || ctx.sessionID) to get / delete / rename, matching
  list / schedule.
• findById ownership check: when a session filter is supplied, a task with a
  different createdBySessionId is not visible. A task with no
  createdBySessionId stays visible (legacy tolerance), matching the fire-time
  fallback. When no filter is supplied (internal callers), behavior is
  unchanged.
• list uses the same rule (hide only tasks stamped to another session) so
  legacy unmarked rows remain discoverable and cancellable.
• Empty-string stamps are treated as unmarked across fire/list/findById.

Loop state Copy Section

armLoop stamps the task and stores the owner on LoopState.createdBySessionId
so affinity survives post-fire removal of the one-shot loop row. LoopState
remains keyed by prompt for this iteration (keepalive and max-age). Full
per-session LoopState isolation is out of scope; see S3.

Desktop (mimo-desktop) alignment Copy Section

EngineInstanceStore is a passive mirror: apply() accepts message.* /
session.status for any sessionID without requiring the session to be the
selected/active one. engineAwareActivity lights the sidebar spinner from
sessionStatus[type≠idle]. refreshActivity (2s) hydrates non-idle sessions;
loadEngineSessions (30s / window focus) rebuilds the convo list from the
engine session list. So a fire into a cold (unselected) session is intentional
and correctly attributed after this fix — the creating conversation is the one
that goes busy. Remaining desktop-side lag (a session not yet in convos may
take up to 30s to appear in the sidebar) is a UI-discovery gap, not a
correctness bug, and is out of scope here.

Error / edge behavior Copy Section

• Target session id present but the session is gone: injectScheduledPrompt
  already fails into the existing log path; no new recovery.
• Same-tick double-fire latch and lock ownership stay unchanged.
• Non-owner processes still only fire session-store tasks; durable file tasks
  remain lock-owner-only.

[S3] Out of Scope Copy Chapter

• Multi-slot CronBridge / per-session keepalive sweeps.
• Per-session isLoading gating (busy of one session still delays the whole
  tick).
• Re-keying LoopState by (session, prompt).
• Migrating or deleting legacy unmarked durable tasks.
• Desktop UI / Automations page changes; 30s sidebar discovery lag.

Tasks Copy Chapter

• T1: Route onFire through task.createdBySessionId with fallback to bridge session — acceptance: a task stamped with session B injects into B while the bridge is mounted on A (covers: S2)
• T2: Stamp createdBySessionId in armLoop and pass session_id from the cron tool loop action — acceptance: created loop task has createdBySessionId equal to the calling session (covers: S2; depends: T1)
• T3: Always pass resolved sessionID into get/delete/rename in CronTool — acceptance: get/delete/rename from session A cannot act on a task stamped to session B (covers: S2; depends: T1)
• T4: Regression tests for cross-session fire routing, loop stamping, and ownership filter — acceptance: tests fail before the fix and pass after (covers: S2; depends: T1, T2, T3)

Compose Spec Default Model Stable Fallback (`docs/compose/spec/default-model-stable-fallback.md`) Copy Section

feature: default-model-stable-fallback status: delivered updated: 2026-09-01 branch: default-model-stable-fallback commits: fa69916897..afdd76ec62 Copy Chapter

Default Model Stable Fallback

Report Copy Chapter

What was built — Provider.defaultModel() no longer ranks models with the TUI menu sort() priority list (gpt-5 / claude-sonnet-4 / gemini-3-pro, then latest). The chain is now: validated cfg.model (warn + fall through if missing) → existing recent → first allowed provider with a usable chat model (toolcall + text input + non-zero context), first by id ascending. Stale cfg.model values that are no longer in the live registry fall through instead of being returned blindly. Capability filter prevents last-resort from selecting models like live openai/chatgpt-image-latest (tool_call: false, context: 0).

Verification — bun test test/provider → pass / 0 fail (includes new cases: invalid cfg fallthrough, recent hit over id-asc first, valid cfg beats recent, invalid cfg + recent, non-chat last-resort skip, no priority-substring preference). bun run typecheck → clean.

Journey log — Desktop does not write TUI state/model.json recent, so empty recent is the common Desktop case, not a rare one; a “first provider model” fallback without a product-default path would re-open the same bug. First review flagged a missing recent-hit test and a weak last-resort test; both were fixed before finalize.

[S1] Problem Copy Chapter

Provider.defaultModel() is the engine's last-resort model resolver for internal tasks (title generation, predict, agents, MCP sampling) when no session context is available.

Its final fallback previously did:

1. pick the first allowed provider
2. run sort() over that provider's models (priority substrings gpt-5 / claude-sonnet-4 / gemini-3-pro, then latest, then id desc)

That sort was written for TUI menu ranking, not as a product default. On MiMo Desktop:

• cfg.model is not injected
• TUI-only state/model.json recent is almost always empty
• the registry may contain router leftovers (e.g. claude-sonnet-4-6-006)

Result: title generation and other cheap tasks can resolve to an unavailable or unsupported model while the user's conversation model works fine. Log evidence already exists in Desktop (title generation → 400 Unsupported model / ProviderModelNotFoundError).

cfg.model also returned without existence validation, so a stale configured default was forwarded until the request failed.

[S2] Design Copy Chapter

Provider.defaultModel() is a stable, validated chain. No product-priority substring ranking.

1. cfg.model
   - parse provider/model
   - MUST exist in the live provider registry
   - missing → warn + fall through (do not throw)
2. state/model.json recent[]
   - first entry whose provider+model still exist
3. first allowed provider that has a usable chat model
   - usable = toolcall && text input && limit.context > 0
   - first such model by id ascending (deterministic)
   - no priority list, no "latest" preference
4. no provider / no usable model → throw the existing clear errors
   ("no providers found" / "no models found")

Contracts:

• sort() stays for TUI menus / defaultModelIDs / ACP listing. Only defaultModel() stops using it.
• defaultModel() return type is unchanged: Effect<{ providerID, modelID }>.
• Call sites that catch resolution failure keep working; success no longer depends on priority substrings.
• Existence checks use the same in-memory InstanceState provider map already used for recent.

Not changing in this feature:

• cheap-task preferred session model (separate fix, Plan B)
• Desktop injecting model / model_groups.lite
• writing recent from Desktop

[S3] Out of Scope Copy Chapter

• Changing getSmallModel / genTitle to prefer the conversation model
• Injecting Desktop model_groups.lite
• Rewriting TUI's own UI fallback in packages/app or cli/cmd/tui/context/local.tsx
• Deleting Provider.sort or defaultModelIDs
• Cost-aware last-resort pick (google-only setups can still land on an expensive usable model such as deep-research-*; filter only guarantees "usable", not "cheap")

Tasks Copy Chapter

• T1: Rewrite defaultModel() chain (validate cfg.model, keep recent, drop menu-priority sort; last-resort requires usable chat model) — acceptance: unit tests cover invalid cfg fallthrough, recent hit, cfg-beats-recent, non-chat skip, first-provider stable pick, and no priority substring preference (covers: S2)
• T2: Adjust/extend provider tests — acceptance: bun test packages/cli/test/provider passes; new cases assert the chain order and that gpt-5-like ids are not auto-preferred when earlier steps miss (covers: S2; depends: T1)

Compose Spec Default Port Ephemeral (`docs/compose/spec/default-port-ephemeral.md`) Copy Section

feature: default-port-ephemeral status: delivered updated: 2026-09-12 branch: feat/default-port-ephemeral commits: ecbe6e59c7c9383f99767ca3f755ad032c4dc3cc..98ef287528e9c54fefe0055a90462338adc02f4b Copy Chapter

Default Listen Port Ephemeral

Report Copy Chapter

What was built — Server.listen({ port: 0 }) now binds an OS-assigned ephemeral port on both node and bun adapters; the conventional 4096 preference is removed so embedders (MiMo Desktop) and other local tools no longer collide by default. Fixed ports require an explicit port / --port / config.server.port. Runtime hardcodes of localhost:4096 were removed from the plugin client placeholder and CLI help; documentation examples may still show --port 4096 when a known URL is required.

Verification — packages/cli: bun test test/cli/cmd/server-port-ephemeral.test.ts test/cli/cmd/serve-advertise.test.ts PASS 8/8; bun test test/skill/mimocode-docs.test.ts test/plugin/mimo.test.ts test/plugin/codex.test.ts PASS 44/44; bun typecheck PASS. Independent review: no critical findings.

Journey log — Prefer start(opts.port) over a special-case port===0 → 4096 branch; yargs default 0 therefore means ephemeral unless config supplies a port. Downstream Desktop must keep consuming listen-returned Server.url / Listener.port (already dynamic). Generated SDK default baseUrl and unmanaged packages/app UI placeholders still mention 4096 (out of runtime listen path). Node adapter is code-symmetric with bun; unit suite exercises the bun path under Bun.

[S1] Problem Copy Chapter

Server.listen({ port: 0 }) used to prefer a conventional serve port (4096), then fall back to start(0). That port collides with other local tools (MiMo Desktop embeds the engine in-process; OpenCode/CLI users also bind 4096). Port 0 is the OS standard “any free port” and should mean exactly that.

[S2] Design Copy Chapter

• Adapter (node + bun): port: 0 → start(0) (OS-assigned ephemeral). No intermediate bind of a conventional port. Explicit port: N binds only N.
• CLI: yargs default remains 0, so an unspecified --port now means ephemeral. Fixed ports require an explicit flag or config.server.port.
• Docs: network flags and skill/README examples that need a known port must pass it explicitly (e.g. --port 4096). Example strings may keep 4096; runtime code must not hardcode it as the listen target.
• In-process plugin client: dummy baseUrl / serverUrl fallback uses http://mimocode.internal (not a conventional listen port). Real traffic uses Server.url after listen or in-process app.fetch.
• Generated SDK default baseUrl: http://localhost:4096 is a client template, not a listen path; left as generated (docs/examples domain).

[S3] Out of Scope Copy Chapter

• Desktop-side engine-pin bump (downstream).
• Changing config.server.port schema (still optional and > 0).
• Rewriting all multilingual web docs / unmanaged packages/app UI placeholders beyond note-level consistency.

Tasks Copy Chapter

• T1: node+bun adapter 0 → start(0) — acceptance: source has no start(4096) preference (covers: S2)
• T2: plugin client no localhost:4096 hardcode — acceptance: plugin/index.ts uses non-4096 placeholder (covers: S2)
• T3: CLI/network + server.listen contract comments — acceptance: describe 0 as ephemeral (covers: S2)
• T4: unit test port 0 does not prefer 4096 when free/bound — acceptance: bun test green on new/updated suite (covers: S2)
• T5: docs/skill keep explicit-port examples; no new “default is 4096” claims — acceptance: capability-api/guide/README still show explicit --port (covers: S2)

Compose Spec Default Prompt P0 (`docs/compose/spec/default-prompt-p0.md`) Copy Section

feature: default-prompt-p0 status: delivered updated: 2026-09-19 branch: fix/default-prompt-p0 commits: 50cd7139..ac7bbf66 Copy Chapter

Default System Prompt P0 Cleanup

Report Copy Chapter

What was built — default.txt is a lean behavioral base prompt (System /
Doing tasks / Executing actions with care / Using your tools / Skills / Tone).
Architecture dumps (Agent system, native-agent catalog, permission pedagogy,
session lifecycle, plan-mode detail, MCP essay) are gone. Dispatch is task /
actor / workflow only. Memory is not restated (owned by
buildMemoryInstructions). compose never appears in base sys. Subagent return
format is off the main memory path (spawn RETURN_FORMAT_INSTRUCTION +
general.txt pointer); general keeps a nested-spawn ban and the
inspect/verify work-face.

general/explore carry work-face (case-sensitive snake_case tool ids,
parallel 1–3 / ≤8, trust-as-data) and parent-facing reporting. Model-facing
injectors across default, memory, recall hints, budgeted-read, truncate,
checkpoint render/reconcile, checkpoint-writer, dream/distill, write, and
workflow builtins use registered tool ids; bare glob/grep are qualified as
“the glob tool” / “the grep tool” when they could be read as shell.
Sibling provider prompts (glm.txt, deepseek.txt, minimax.txt, …) brand
residuals are deferred follow-up (S3).

Deletion → injection site (every removed block names who still carries it):

What stayed (on purpose) — identity + security IMPORTANTs; System
(permissions, tool surface, system-reminder, DATA-as-data, memory-stale,
compress); Doing tasks + Executing (blast radius); Using tools (case-sensitive
snake_case, parallel 1–3 / ≤8, task/actor/workflow routing); Skills
rules + two real roots; Tone (progress rhythm, end-of-turn summary).

Verification — From packages/cli:

• bun typecheck — PASS
• bun test test/agent/agent.test.ts — PASS (52)
• bun test test/session/llm-system-prompt.test.ts — PASS
• bun test test/session/prompt.test.ts test/session/budgeted-read.test.ts — PASS (65)
• bun test test/session/checkpoint-render-verify.test.ts — PASS
• CI on ba2312c1 — lint / typecheck / unit 1–4 SUCCESS
• 0543ef5a (Turn 1 read casing + glob tool qualifiers) — prompt-only; pre-push typecheck PASS
• compose-next review: acceptance criteria met after casing + general inspect/verify follow-ups

Journey log

1. Memory rewrite was wrong — already in buildMemoryInstructions; delete the section.
2. Over-slashed then restored Agent system; final product call: architecture out of base sys (mimocode-docs / tool desc own it); tests lock the slim shape.
3. Subagent return format belongs on spawn task injection, not the main memory block.
4. general must keep a nested-spawn ban and inspect/verify work-face: toolAllowlist is unset so it can inherit actor; without verify bullets the parent-report contract is unimplementable.
5. Tool-name casing across all injectors: English imperatives stay plain English (Read all sources, Glob \pattern`, Read CHECKPOINT_PATH). When naming the registered tool, use Use `glob` with …/the `grep` tool/ call formglob("…")— never jam a backticked id in front of an argument (``glob path`` is unreadable). Prefer registered snake_case ids overGrep/Read tool` prose when the word means the tool.

[S1] Problem Copy Chapter

default.txt mixed Claude Code brand residue, invented dispatch tools, a
wrong Memory block, compose advertising, and tool-limit/path dumps that
duplicate real injectors — while the architecture prose (Agent system, skills
rules, session, MCP, trust) is still needed. Memory/tool descriptions also
advertised capitalized tool names (Grep/Read/Edit) that violate the
case-sensitive registered-id rule.

[S2] Design Copy Chapter

Base sys = behavior + trust + tool routing + skills roots + tone. Delete wrong,
branded, or already-injected content. Architecture lives in tool descriptions /
mimocode-docs / runtime injectors. compose never appears. Return format is
spawn-owned. general forbids nested spawn. Tool names in every model-facing
injector use exact registered ids when naming the tool (Use \glob` with …, the `grep` tool, glob("…")`); leave English imperatives as plain English.
Do not jam a backticked id in front of an argument.

See Report tables.

[S3] Out of Scope Copy Chapter

• Sibling prompts (compose.txt, anthropic.txt, glm.txt, deepseek.txt, minimax.txt, …) residuals — deferred follow-up.
• Changing buildMemoryInstructions or skills catalog injection.
• Further slimming of Agent-system pedagogy beyond the deletions above.

Tasks Copy Chapter

• T1: Strip Claude brand + help/feedback + fix dispatch/tool ids
• T2: Delete Memory section (owned by buildMemoryInstructions)
• T3: Drop compose line, skill path dumps, workflow numeric limits (tool desc)
• T4: Slim base sys (no Agent-system dump); Skills + trust kept; subagent prompts carry work-face + parent reporting + nested-spawn ban
• T5: Regression test + verify

Compose Spec Desktop Child Process Env (`docs/compose/spec/desktop-child-process-env.md`) Copy Section

feature: desktop-child-process-env status: delivered updated: 2026-08-17 branch: fix/desktop-runtime-boundaries commits: 17c9cdcb70b27116456f742f2b0d384b76f79108..0d3d0dcadf999cd05cb5ea0ae22e5e43ac1bd305 Copy Chapter

Desktop Child Process Environment

Report Copy Chapter

What was built — MiMoCode now owns a process-level, replaceable child environment baseline. Embedding hosts can set it at startup through Server.listen({ childEnv }) or refresh it later through the Node entry's ChildProcessEnv.set(env). Hosts that never set a baseline retain existing behavior and read the current process.env for each spawn.

All inherited external process paths now resolve through the same boundary, including direct and Effect process wrappers, Bash, PTY, LSP, MCP, ripgrep and remaining native child_process calls. Inherited credentials are still scrubbed before explicit per-child environment overrides are applied.

Verification — bun typecheck passed. The affected regression suite passed 99 tests with 0 failures across child-process environment, credential environment, process, PTY, LSP, MCP, ripgrep and Bash coverage. git diff --check passed. Independent review passed spec compliance, correctness and codebase consistency after all critical findings were fixed.

Journey log —

• A frozen baseline was rejected because a future Desktop environment-sync action must replace the baseline for new child processes without changing session state.
• The no-host path reads current process.env on every spawn; freezing that fallback broke existing CLI runtime environment updates.
• Review found Effect commands with undefined env and native child_process calls could still inherit the engine process; both paths now explicitly resolve the shared baseline.
• LSP environment deltas are resolved at each spawn so a baseline refresh affects later commands in the same workflow.
• The structural guard uses the TypeScript AST to validate every native process call; Process wrapper clients pass only env deltas so the final spawn boundary resolves the baseline exactly once.

[S1] Problem Copy Chapter

MiMoCode runs in-process inside MiMo Desktop. Desktop adds engine control variables to the Electron process environment, and external tools currently derive their environment directly from that global state. Bash, PTY, LSP, MCP and shared process spawners can therefore observe Desktop-only values such as engine credentials, permission controls and NODE_ENV=production injected by electron-vite.

The existing Env.Service is mutable, instance-scoped configuration state, not a child-process boundary: several spawn paths run outside its Effect context and still read process.env directly. Session permission is unrelated and must remain persisted session state; this feature does not change permission semantics.

[S2] Design Copy Chapter

The process/spawn infrastructure owns one replaceable child environment baseline. A new foundation module exposes two operations:

setChildProcessEnv(env: NodeJS.ProcessEnv): void
childProcessEnv(explicit?: NodeJS.ProcessEnv): NodeJS.ProcessEnv

The Node embedding entry exports the host-facing setter as ChildProcessEnv.set(env). The resolver remains internal to spawn infrastructure. This gives Desktop one stable startup and future refresh contract without exposing arbitrary environment mutation over HTTP.

setChildProcessEnv copies the supplied values and atomically replaces the process-wide baseline. Future child processes use the new snapshot immediately; already-running children keep the environment they were spawned with. The baseline is not tied to a project instance or listener and is not reset when a listener stops. If no host sets a baseline, childProcessEnv reads the current process.env on each call, preserving existing CLI/TUI/ACP/run behavior when those surfaces intentionally mutate their own process environment.

MiMoCode adds an optional childEnv?: NodeJS.ProcessEnv field to the public Server.listen module contract only as an embedding adapter. listen sets childEnv before creating the HTTP runtime or initializing any project instance. Desktop supplies the option; ordinary CLI/TUI/ACP/serve callers omit it. Headless mimo run, which does not call Server.listen, naturally uses the default current process.env. A future Desktop environment-sync action can call the same process foundation setter without changing tool or session contracts.

All external process paths use one helper, childProcessEnv(explicitEnv?), with this order:

configured childEnv (or current process.env when no host set one)
  -> existing inherited-credential scrub
  -> explicit tool/plugin/MCP/LSP env overrides
  -> spawn

The foundation does not infer or reconstruct variables. The host-provided baseline is authoritative. Existing cleartext credential protection remains on the inherited half (MIMOCODE_AUTH_CONTENT and MIMOCODE_CONFIG_CONTENT); explicit per-child environment remains authoritative, so an MCP definition, LSP configuration, plugin hook, or future tool caller can intentionally override any value. NODE_ENV, user MIMO_* values, proxy variables and bundled runtime variables follow the baseline unchanged.

Every path that currently builds inherited child environment from process.env must call childProcessEnv: the direct process wrapper, Effect ChildProcessSpawner, Bash, PTY, LSP, MCP and ripgrep. Tool-local additions keep their existing order after the baseline, including plugin shell.env, Git identity floors, UTF-8 fixes and MCP/LSP explicit env.

MiMo Desktop obtains a complete environment snapshot from the same clean login-shell mechanism used to establish the user's terminal environment, adds bundled runtime variables, and passes the result as childEnv to Server.listen({ childEnv }). The snapshot is independent from Electron's mutated process.env, so Desktop/engine controls added later are absent by construction rather than removed heuristically. NODE_ENV is not synthesized or deleted: if the user's clean terminal environment contains it, it remains; if not, Desktop does not add it. Desktop continues to inject MIMOCODE_PERMISSION into the engine process; this feature does not move permissions into session storage or change cross-client behavior.

The engine module declaration in Desktop is expanded only for the childEnv option. The Desktop engine spec and bundled-runtimes spec remain the source of truth for the baseline construction and public MIMO_* runtime variables.

[S3] Out of Scope Copy Chapter

• Changing MIMOCODE_PERMISSION, session permission persistence, or permission precedence.
• Adding an HTTP endpoint for arbitrary environment mutation.
• Guessing or overriding NODE_ENV; child processes follow the clean terminal environment exactly, including its presence or absence of NODE_ENV.
• Adding model-visible per-call environment controls to the Bash schema.
• Reusing Env.Service for child-process inheritance or making child environment project-instance mutable.
• Constructing Desktop's clean-terminal environment, updating Desktop's virtual module declaration, adding Desktop E2E coverage, or bumping Desktop's engine pin. Those are downstream consumer work after this MiMoCode foundation lands.

Tasks Copy Chapter

• T1: Add the process-owned replaceable child environment foundation and Server.listen({ childEnv }) adapter — acceptance: each set replaces the snapshot for future spawns, existing children are unaffected, listener stop does not reset, and no-set callers keep current process.env behavior (covers: S2)
• T2: Route all inherited external process environments through childProcessEnv(explicit) — acceptance: direct and Effect spawners plus Bash/PTY/LSP/MCP/ripgrep use the same baseline and explicit env still overrides (covers: S2; depends: T1)
• T3: Add MiMoCode unit and structural regression tests — acceptance: baseline fidelity, credential scrub, replacement lifecycle and all spawn funnels are covered (covers: S2; depends: T2)

Compose Spec Disable Pascalcase And Flooding (`docs/compose/spec/disable-pascalcase-and-flooding.md`) Copy Section

feature: disable-pascalcase-and-flooding status: delivered updated: 2026-09-22 branch: codex/disable-pascalcase-and-flooding commits: 1579e7d9..HEAD Copy Chapter

Disable PascalCase Tool Projection and Toolcall Flooding

Report Copy Chapter

What was built — Removed the MiMo v2.6 PascalCase tool-name projection at
the model boundary and the entire toolcall-flooding detector. Canonical lowercase
tool IDs are advertised and replayed again; prompt display names (Edit,
Grep, Glob, …) remain unchanged. The FIFO safe-serial gate and fail-cascade
guard stay intact.

Verification — From packages/cli:

• PASS: bun typecheck
• PASS: bun test test/session/tool-fail-cascade.test.ts test/session/invalid-tool-cascade.test.ts test/tool/gate.test.ts test/tool/fail-cascade.test.ts test/session/structured-output.test.ts --timeout 30000
• Independent review previously found no critical findings

Journey log

1. Flooding and PascalCase are independent of the FIFO/fail-cascade gate; the
   gate file stayed out of the removal diff.
2. Historical prefix snapshots may still carry model_name; restoreTools
   ignores leftover keys (no migration).

[S1] Problem Copy Chapter

Two recent engine behaviors need a clean removal while keeping their surrounding
safety work:

1. MiMo v2.6 message-side tool names are projected to PascalCase (Read, Grep,
   Edit, …) at the model boundary (#2490). Prompt text already uses those
   display names and must stay that way, but the request/history casing rewrite
   should be removed cleanly so the harness again advertises canonical lowercase
   tool IDs.
2. Tool-call flooding detection (#2463 / #2487) buffers and cancels oversized
   batches. The whole flooding path should be removed, while the independent
   safe-serial FIFO gate (#2456) and fail-cascade guard stay intact.

[S2] Design Copy Chapter

Keep Copy Section

• Prompt and tool-description display labels (Edit, Grep, Glob, Read, …)
  introduced for human-facing instructions remain unchanged.
• packages/cli/src/tool/gate.ts FIFO admission (read/grep/glob overlap;
  every other top-level tool serial within an assistant step).
• Fail cascade in the same gate: FailCascadeError,
  FAIL_CASCADE_MESSAGE, MIMOCODE_DISABLE_FAIL_CASCADE, and all
  fail-cascade / gate tests and behavior.
• Provider-native buffering (for example the OpenAI-compatible complete-call
  delay until EOF) is untouched.

Remove — PascalCase model-boundary projection Copy Section

Delete the mimo-v2.6 casing rewrite end to end so schema and history names stay
canonical:

• Delete packages/cli/src/tool/names.ts (usesPascalCaseTools,
  defaultToolName, toolSurface, NamedTool).
• Drop modelName from tool definitions and the MIMOCODE_PASCAL_CASE_TOOLS
  flag.
• Stop projecting tools/messages in session/llm.ts; restore/prefix rewrite
  branches that only exist for projected names go away.
• Drop modelName / model_name plumbing from tool/tool.ts,
  tool/registry.ts, session/prompt.ts, session/llm-request-prefix.ts,
  session/prefix-snapshot.ts, and session/session.sql.ts.
• Delete PascalCase tests and flag tests.

Internal execution, permissions, events, and persisted tool IDs were already
canonical and need no behavioral change.

Remove — toolcall flooding Copy Section

Delete the flooding detector completely:

• Delete packages/cli/src/session/toolcall-flooding.ts
  (middleware, guardToolCallStream, ToolCallFloodingError,
  TOOLCALL_FLOODING_*).
• Remove middleware wiring and flooding name-restore from session/llm.ts.
• Remove flooding recovery (cancelled batch parts, recovery reminder,
  releasedCallID skip) and related retrySafe special cases from
  session/processor.ts.
• Delete MIMOCODE_DISABLE_TOOLCALL_FLOODING_DETECT.
• Delete flooding tests; strip flooding flag combinations from fail-cascade,
  invalid-tool-cascade, structured-output, and tool-safety-flag tests.

Interaction contract Copy Section

• Fail cascade and FIFO serial remain independent of both removals.
• A non-read/search tool failure still cancels the rest of the batch via the
  gate; no flooding path reintroduces a generation barrier or early abort.
• Invalid-tool handling and ToolCompat name repair stay as they are.
• doom_loop keeps its existing three-identical-calls ask.

[S3] Out of Scope Copy Chapter

• Reverting prompt display names back to lowercase labels.
• Changing FIFO / fail-cascade semantics or flags.
• Open PR #2514 flood quota / generation barrier — not merged.
• GPT/Codex tool surfaces, MCP tool names, and the shared exec gateway.
• Database migrations for historical prefix snapshots that stored model_name.

Tasks Copy Chapter

• T1: Remove PascalCase projection — acceptance: MiMo v2.6 requests advertise
  lowercase canonical tools and history replays the same names; no
  MIMOCODE_PASCAL_CASE_TOOLS / modelName remains; prompt display names still
  say Edit/Grep/Glob (covers: S2).
• T2: Remove toolcall flooding — acceptance: no flooding module, middleware,
  recovery reminder, or flag remains; tools execute without a flooding generation
  barrier (covers: S2).
• T3: Preserve safe serial and fail cascade — acceptance: gate FIFO and
  fail-cascade tests still pass unchanged in behavior; flood-related test cases
  are gone (covers: S2; depends: T1, T2).
• T4: Verify — acceptance: package typecheck and focused suites pass
  (covers: S2; depends: T3).

Compose Spec Exec Subtool Metadata (`docs/compose/spec/exec-subtool-metadata.md`) Copy Section

feature: exec-subtool-metadata status: delivered updated: 2026-08-24 branch: codex/exec-subtool-metadata commits: 84f17b64233ae6bd4b65bb8ccd6325fb8a2cdf16..bc1abe91dc7334d709a7ab454269f58d50954b8f Copy Chapter

Exec Sub-tool Metadata

Report Copy Chapter

What was built — exec nested-tool progress now uses a 150 ms trailing-edge debounce while preserving the first admitted call's immediate running snapshot. Every outer terminal path cancels pending progress, terminalizes any nested calls still running, publishes the final complete sub_parts snapshot, and waits for the metadata write. Late nested completions cannot overwrite or republish stale terminal state. Existing result and attachment size limits remain unchanged.

Verification — bun test test/tool/tool-script.test.ts test/session/messages-default-main.test.ts (64 pass, 0 fail); bun typecheck (PASS); git diff --check (PASS). Independent review of the complete diff and affected-area fixes (PASS; no critical findings).

Journey log — The initial implementation was a fixed-window coalescer; review identified that true trailing-edge debounce requires resetting the timer on every update. Review also exposed detached nested promises that could leave persisted snapshots stuck in running; terminalization and a closed progress channel now make the terminal state deterministic. No new DB schema or size policy was introduced.

[S1] Problem Copy Chapter

exec runs multiple tools inside a sandbox, but the nested tool metadata is currently discarded. The outer tool only keeps aggregate counts and a bounded trace, so a caller cannot reconstruct a nested tool result as if it had been invoked directly. In particular, actor.spawn publishes its { sessionId, actorId } through the nested context; exec swallows that callback, leaving TUI/Desktop without a reliable clickable subagent reference during execution.

The outer ToolPart is persisted by the existing part.data JSON column in SQLite. The loss happens before persistence, in tool-script.ts, so a new database table is not required for the core fix.

The Desktop MR !3727 (mimo-desktop merge 82c4ddf7a, implementation 63ae744e5) only standardized exec summaries and script/XML rendering. Its own design document records the nested-actor gap. Desktop currently receives raw engine messages from its message API; once nested metadata is present in the engine part, Desktop can project it into its live/history/shared schemas without a second source of truth.

[S2] Design Copy Chapter

For every nested call, exec maintains one ordered, replayable record in outer state.metadata.sub_parts. The record is a ToolPart-compatible snapshot with only the outer identity fields omitted (id, sessionID, messageID are not real persisted parts):

type ExecSubPartSnapshot = {
  seq: number
  type: "tool"
  callID: string
  tool: string
  state: {
    status: "running" | "completed" | "error"
    input: Record<string, unknown>
    title?: string
    output?: string
    error?: string
    metadata?: Record<string, unknown>
    time: { start: number; end?: number }
    attachments?: unknown[]
  }
}

The envelope is versioned as metadata.exec_schema: 1. viewExecSubtools(metadata) is a pure view function: it validates the version and entries, drops malformed records, preserves invocation order, and returns the nested tool view list. It performs no storage writes, no network calls, and never evaluates the original script. Desktop and TUI can use this list to render ordinary tool rows, with an additional outer exec fold.

The first admitted nested call publishes an initial snapshot immediately with status: "running"; later admissions and metadata callbacks update only their records through the coalesced progress path. A completed or failed call replaces its state with the same fields a direct tool part would expose. Calls not yet admitted do not appear. Terminal success, budget, timeout, cancellation, and error returns all republish the complete array, so SessionProcessor.completeToolCall replacing the part metadata cannot erase it.

Live progress publication is trailing-edge debounced (100–200 ms target window) so repeated nested metadata callbacks coalesce to the newest snapshot. The outer exec terminal path cancels any pending timer, publishes the latest complete snapshot immediately, waits for that write, and then returns terminal metadata. Nested completion events do not each force a full-array write; only the outer terminal flush is unconditional.

If the outer script terminates before an admitted nested promise settles, the terminal flush converts remaining running snapshots to terminal errors and closes the progress channel. Late host completions cannot publish stale updates into the already terminal outer part.

sub_parts is JSON-safe by contract because it is stored inside the existing ToolState.metadata record and therefore inside PartTable.data. No migration or new table is added. Existing consumers that only understand counts/recent remain compatible. Consumers that need full details can read the raw message part and pass state.metadata to viewExecSubtools; malformed or absent records degrade to the existing summary.

The TUI exec block exposes nested records in its expanded view. Any nested actor record with a valid target (sessionId + actorId from metadata, or an actor target in its input) is rendered as a clickable subagent entry, regardless of whether the action is spawn, run, wait, status, or send. Desktop can implement the same projection in live/history/share-history by forwarding exec_schema and sub_parts through its existing tool-step schema; actor notifications remain the authoritative terminal lifecycle event and must not be duplicated.

[S3] Out of Scope Copy Chapter

• A separate SQLite table or query API for nested calls; the canonical storage remains PartTable.data.
• Reworking Desktop MR !3727 itself; this branch records the engine contract and the evidence that its requested full-information path is feasible.
• Persisting arbitrary binary attachments across the sandbox boundary; existing attachment behavior is unchanged.
• Changing the model-visible exec result envelope or the existing counts/recent summary fields.

Tasks Copy Chapter

• T1: Define and collect versioned ToolPart-compatible sub_parts, including progressive callbacks and actor references — acceptance: every admitted nested call appears once with direct-call input/output/metadata/status/time fields, and a running snapshot is published through the coalesced progress path before it settles (covers: S2)
• T2: Republish sub_parts on every terminal exec path and verify it survives outer tool-part completion/persistence — acceptance: terminal metadata cancels pending progress, flushes the latest snapshot immediately, retains all snapshots, and an SQLite-backed part round-trip returns the same envelope (covers: S2; depends: T1)
• T3: Implement the pure viewExecSubtools projection and render valid nested actor records as clickable TUI subagent entries — acceptance: the view function returns only valid current snapshots in sequence order; actor rows with any supported action navigate to the actor route; non-actor/invalid rows remain safe summaries (covers: S2; depends: T1)
• T4: Add regression coverage and document the Desktop MR !3727 data contract — acceptance: tool, view, persistence, and TUI tests cover partial live snapshots, complete fields, actor refs, terminal replacement, and fallback behavior (covers: S2)

Compose Spec Exec Tool View (`docs/compose/spec/exec-tool-view.md`) Copy Section

feature: exec-tool-view status: delivered updated: 2026-07-27 branch: feat/exec-tool-view commits: 47c8425f..6479a56b Copy Chapter

exec Tool View (bash-style collapse)

Report Copy Chapter

What was built — exec (the parallel tool-call script tool) now renders like bash. Once input.code has streamed in, the part lives in a BlockTool for the rest of its life; collapsing caps the script and its output at a 10-row budget with a … marker instead of compressing everything into a one-line summary. Expanding shows both in full. The click handler and the expand/collapse hint appear only when something actually overflows, so a short script with short output is a static block — the same rule bash uses.

The budget counts rendered rows, not source lines. The first cut of this change counted source lines and bounded nothing: exec returns JSON, one line of it wraps to dozens of terminal rows, and the collapsed block still filled the screen. Estimation and clipping now live in packages/cli/src/cli/cmd/tui/util/collapse.ts and are shared with Bash, which had the same latent defect for long single-line output. Height is measured in display cells (Bun.stringWidth, plus one cell per tab), so CJK and emoji count double; a line straddling the budget is sliced on the cell budget without splitting a wide character, so a single 4000-char line still shows its head.

The pre-execution state keeps the single InlineTool pending line (~ Writing script...). Because that branch is only reachable while code is still empty, its failure color, spinner and summary children were unreachable and were removed; InlineTool's iconColor prop lost its last user and was deleted. exec output now passes through stripAnsi like bash's, since nested bash calls put raw escape sequences into <return_value> / <logs>.

On the backend, exec re-publishes the per-tool counts map in its terminal metadata. SessionProcessor.completeToolCall (packages/cli/src/session/processor.ts:359) replaces part metadata rather than merging it, so the live breakdown streamed through ctx.metadata used to vanish the moment a run finished and the summary degraded to 12 calls.

Verification

• cd packages/cli && bun typecheck — PASS (clean), re-run after the display-cell rework.
• cd packages/cli && bun test test/cli/tui/collapse.test.ts — PASS, 16 pass / 0 fail (row estimation, clipping, CJK/emoji/tab widths, a budget invariant across grapheme classes, and the over-wide-cluster guard — verified to go red when the guard is removed).
• cd packages/cli && bun test test/tool/tool-script.test.ts — PASS, 42 pass / 0 fail.
• cd packages/cli && bun test test/tool test/cli/tui — PASS, 874 pass / 10 skip / 0 fail.
• Independent subagent review of 47c8425f..b5dbe888: both acceptance criteria met, no critical findings. Two of its three minor findings were fixed in 1e463724 (dead pending-branch props, missing stripAnsi); the third (clip() being a plain function rather than a memo) was rejected — reads of expanded() inside JSX children are tracked by the render effect. A second review covered the row-budget and display-cell work and found one CRITICAL — a per-code-point width walk under-charged variation-selector emoji and clipped ~2x the budget — fixed by segmenting graphemes (36372846), plus a scrollbox-chrome under-reservation. Its re-review passed after fuzzing the budget invariant over regional indicators, skin tones, combining marks and Hangul jamo; two residual nits were fixed in 6e23a566. A third review covered that residual fix and found the new guard test was not exercising the guard (its budget equalled the cluster width) — tightened in 6479a56b.
• Not covered: there is no render harness for the components in routes/session/index.tsx, so wiring (which memo feeds which <text>) was reviewed by reading, not asserted. The row math itself is unit-tested. exec is gated to GPT-toolset models (registry.ts:379-381), so no live TUI run was performed; both display defects were reported from user screenshots, not caught by a test.

Journey log

• A source-line collapse budget is meaningless for tools whose output can be one enormous line. exec returns JSON via JSON.stringify(parsed, null, 2), but each string value inside it (a nested bash stdout, a grep result set) keeps its \n escaped, so 40 rows of text arrive as one source line. Budget rendered rows for anything block-shaped.

• Bun.stringWidth returns 0 for a tab (and for a newline) — found via component/prompt/offset.ts, which special-cases both to stay aligned with @opentui's editor offsets. Any width math over raw tool output has to handle tabs explicitly.

• Bun.stringWidth is also not additive over code points: "❤️" is 2 as a unit but 1 + 0 when summed per code point. The second review caught this as a real overshoot of the row budget; per-character width walks must segment by grapheme cluster.

• ctx.width (contentWidth, routes/session/index.tsx:244) subtracts the conversation box padding but not the transcript scrollbox's viewport padding or its always-visible scrollbar, so it over-states usable text columns by ~3 cells for any exact-width math.

• The spec's original §S2 rule — leave the two pre-execution error returns without counts — did not survive contact with the type system: Tool.define infers metadata as the union of execute's return literals, and bun typecheck covers test/, so a non-uniform union makes result.metadata.counts inaccessible in tests. All five terminal returns now carry counts (empty map for the pre-execution pair, behaviorally identical). §S2 records the delivered rule.

• Hoisting trace above the code-size guard so tally() could be shared briefly left a duplicated const trace declaration; caught by grepping declarations, not by the first typecheck pass.

• Anything streamed via ctx.metadata must be re-emitted in every terminal return or it is lost on completion — a general trap for future live-progress tools.

[S1] Problem Copy Chapter

The exec tool (parallel tool-call script, packages/cli/src/tool/tool-script.ts, tool id exec) renders in the TUI through ToolScript (packages/cli/src/cli/cmd/tui/routes/session/index.tsx:2292-2345) as a binary toggle:

• Collapsed (default): a single InlineTool line — » exec 12 calls · read×7 grep×4. Neither the script nor its output is visible.
• Expanded: a BlockTool dumping the full input.code and the full props.output with no truncation at all.

Every other block-shaped tool — bash above all (index.tsx:2922-2987) — treats collapse as overflow protection, not as compression to one line: the command is always visible, and the first 10 output lines leak through with a … marker. exec is the odd one out, so a batch of parallel tool calls is either invisible or floods the transcript.

A second, smaller defect: per-tool counts are streamed live through ctx.metadata (tool-script.ts:411-419) but the terminal metadata returned by execute is only { status, toolCalls } (tool-script.ts:549,568,575). SessionProcessor.completeToolCall replaces part metadata rather than merging it (packages/cli/src/session/processor.ts:359), so the moment a run finishes the breakdown disappears and the summary degrades to 12 calls.

[S2] Design Copy Chapter

Collapsed/expanded behavior (TUI) Copy Section

Restructure ToolScript to mirror Bash:

• Shape selection is a <Switch> on whether script source has arrived. With no input.code yet, keep the existing single InlineTool pending line (~ Writing script...). Once input.code is a non-empty string, render BlockTool for the rest of the part's life, with spinner={isRunning()} on the title.
• BlockTool title stays # exec · , where summary keeps its current composition (N calls · read×7 grep×4(1!), prefixed with the failure status when the run did not complete).
• Body, in order:
  1. script source — clipped to a 10-rendered-row budget when collapsed with a … marker; full source when expanded;
  2. output — the props.output string with ANSI stripped (nested bash calls embed escape sequences), clipped to the same 10-row budget when collapsed, full when expanded. The XML envelope (<exec status=…>, <return_value>, <logs>, ``) is displayed verbatim, exactly as bash shows raw stdout. Coloured theme.error when the run failed.
  3. hint line Click to expand / Click to collapse, rendered only when at least one of the two blocks overflows.
• onClick is wired only when something overflows, so a short script with short output is a static, non-hoverable block (bash parity, index.tsx:2967).
• The budget counts rendered rows, not source lines: exec returns JSON, and one line of it wraps to dozens of terminal rows, so a source-line budget does not bound the collapsed height at all. Per-line height is ceil(width(line) / columns) where width is Bun.stringWidth plus one cell per tab (Bun.stringWidth reports 0 for tabs, and the real tab stop in a static <text> is unverified) — so CJK and emoji count as two cells. columns comes from ctx.width minus the transcript scrollbox chrome and the block's border and padding. A line straddling the budget is sliced on the cell budget, dropping whole grapheme clusters, so a single huge line still shows its head instead of collapsing to a bare ….
• Slicing walks grapheme clusters (Intl.Segmenter), not code points: Bun.stringWidth is not additive over code points — "❤️" (U+2764 U+FE0F) measures 2 as a unit but 1 + 0 summed — so a per-code-point walk under-charges emoji-presentation sequences and overshoots the budget.
• The prompt editor has its own width translation at component/prompt/offset.ts (tab = 2, newline = 1) because it must match @opentui's editor offsets. That is a different coordinate system and is deliberately not shared with Collapse.
• Known limitation (accepted, follow-up): the height estimate assumes character wrapping, but <text> renders through @opentui TextBufferRenderable whose wrapMode defaults to "word". A row therefore breaks early at a space and the leftover spills into an extra row, so the collapsed block can exceed the 10-row budget and the final sliced row looks ragged rather than full. The budget is an approximate ceiling, not a hard bound. Two fixes exist and both were declined for now: simulating greedy word wrap in Collapse (duplicates renderer internals) and forcing wrapMode="char" on these bodies (loses word-boundary readability elsewhere). The collapsed view is readable as-is.
• The row-budget helpers live in packages/cli/src/cli/cmd/tui/util/collapse.ts (lines, columns, rows, clip) and are shared by Bash and ToolScript — bash has the same long-single-line defect. hasLongDisplayLine / Write's line count reuse Collapse.lines.
• The pending branch is only reachable while code is empty, so it carries no failure color, spinner, or summary. InlineTool's iconColor prop has no other user and is removed.

Not in this change: syntax highlighting for the script body, envelope parsing, live output streaming.

Terminal metadata (backend) Copy Section

exec keeps the per-tool breakdown after completion: the aggregation previously inlined in publishProgress is extracted into one host-side tally() helper (hoisted above the code-size guard together with trace), and the resulting counts map is included in all five terminal returns — code-too-large, transpile-error, failure, result-too-large, success. The two pre-execution returns emit an empty map, which is behaviorally identical to omitting the field (the TUI renders an empty counts as no breakdown) but keeps the inferred metadata union uniform so metadata.counts stays accessible to typed consumers, including tests.

running: true is not part of terminal metadata; the TUI derives running state from part.state.status.

[S3] Out of Scope Copy Chapter

• Streaming logs / per-call trace lines into metadata for a live-scrolling collapsed view.
• A dedicated exec panel with per-call expansion (WorkflowPanel-style).
• Parsing the <exec> envelope to render return_value / trace as distinct sections.
• TypeScript syntax highlighting of the script body.
• Any change to the exec enablement gate (registry.ts:379-381, GPT-toolset only).
• Making the row budget a hard bound (see the word-wrap follow-up in S2): neither simulating greedy word wrap nor switching these bodies to wrapMode="char" is done here.

Tasks Copy Chapter

• T1: Retain per-tool counts in exec terminal metadata — acceptance: bun test test/tool/tool-script.test.ts passes with a new assertion that a completed run's metadata carries counts with per-tool n/errors, and that a failed inner call is reflected in errors (covers: S2)
• T2: Render exec as a bash-style collapsible block — acceptance: ToolScript renders BlockTool whenever input.code is non-empty, showing a clipped script + clipped output + … markers while collapsed and full content when expanded, with the hint/click wiring gated on overflow; bun typecheck clean (covers: S2)
• T3: Budget the collapsed height in rendered rows — acceptance: bun test test/cli/tui/collapse.test.ts passes, covering wrapped-height counting, whole-line drops, mid-line slicing at the budget, and the column floor; Bash and ToolScript both consume the shared helper (covers: S2)
• T4: Measure height in display cells — acceptance: bun test test/cli/tui/collapse.test.ts covers CJK and emoji counting as two cells, a tab charged at least one cell, and a slice that stops before splitting a wide character (covers: S2)

Compose Spec Flaky Test Isolation (`docs/compose/spec/flaky-test-isolation.md`) Copy Section

feature: flaky-test-isolation status: delivered updated: 2026-07-27 branch: fix/flaky-test-isolation commits: 028f3178..f4daa79e Copy Chapter

Flaky Test Isolation

Report Copy Chapter

What was built — Three suites that failed off-CI for environment reasons now assert the behavior
they claim to. assertSafeUrl takes the DNS resolver as an optional parameter, so the fail-closed and
rebinding assertions run against a stub instead of whichever resolver the developer's network hands
them; the rebinding branch gained its first test. checkpoint-rebuild-unify wipes
ActorRegistryTable before each test, because renderRebuildContext reads the process-wide
ActorRegistry.listActive() and earlier test files leave background actors behind in the singleton
SQLite client.

The workflow cancel-cascade test no longer times out. Its assertions always passed in ~280ms; the
budget was consumed by an unbounded teardown. Reclaiming the run's children notifies the parent
session's main inbox, which re-arms the parent's main runner against the auto-answering test LLM,
and SessionRunState's instance-state finalizer then awaits Runner.cancel from inside an
uninterruptible finalizer, where no timeout can fire. The test drains that runner itself, bounded, on
the interruptible side of scope close. The same drain let the previously-skipped orphan-on-cancel
regression test come back, restoring the only coverage of that bug; its recorded skip rationale
blamed a slow cancel, which measurement disproved.

Verification — bun test test/util/ssrf.test.ts passed 23 tests.
bun test test/actor test/session/checkpoint-rebuild-unify.test.ts passed 130 tests / 2 skip, having
reproduced the failure on the same command before the fix.
bun test test/workflow/runtime.test.ts passed three consecutive times (28 pass, 1 skip) and again
after the review follow-up. bun test (full suite) passed three times: 4360 pass / 0 fail twice
before the unskip and 4361 pass / 37 skip / 0 fail after, 4399 tests across 418 files.
bun typecheck passed. oxlint on the four changed files reported 49 warnings / 0 errors against 48 /
0 on main; the single added warning is another instance of the await-thenable false positive that
already fires 20 times in that file.

Journey log

• The first fix attempt for the cancel test — swapping llm.hang for hangUntil + release, the
  idiom runtime-worktree.test.ts uses — made it strictly worse: releasing the hang lets the child
  resume, so it was still Running at teardown and the isolated run started hanging too. The
  established idiom in a sibling file was the wrong tool here.
• Measuring before theorising was what cracked it. Probes showed the assertions finishing in 280ms,
  raising the budget to 180s still timing out (so: deadlock, not slowness), and
  process._getActiveHandles() empty (so: an Effect fiber, not a socket).
• Naming the stuck disposer needed the stack captured at the InstanceState.make call site, outside
  the returned Effect.gen — inside it, every frame is Effect runtime internals. A first attempt
  filtered stack lines on /src/, which matches every path under ~/src, and silently kept nothing.
• Effect finalizers run uninterruptibly, so an Effect.timeout placed inside one never fires. That
  is why the deadlock presented as infinite rather than as a bounded 6s stall.
• Bisecting showed any predecessor test triggered the hang, which ruled out a specific
  interaction and pointed at process-global state instead.

[S1] Problem Copy Chapter

Three suites in packages/cli fail off-CI for reasons unrelated to the behavior they claim to
cover. Each failure is an environment or harness artifact, not a product defect, so each one trains
readers to ignore red output.

1. test/util/ssrf.test.ts asserts that assertSafeUrl rejects an unresolvable hostname by asking
   the real resolver for a .invalid name. Resolvers that answer for .invalid (ISP or corporate
   DNS, mDNS) make the call succeed, so the assertion depends on which network the developer sits on.
2. test/session/checkpoint-rebuild-unify.test.ts asserts that insertRebuildBoundary returns
   false when there is nothing to push. renderRebuildContext reads
   ActorRegistry.listActive(), which is process-wide, and the SQLite client is a process-level
   singleton, so background actors left pending/running by an earlier test file make the context
   non-empty. It passes alone and fails in a whole-suite run.
3. test/workflow/runtime.test.ts "cancel stops in-flight child agents and marks the run cancelled"
   exhausts its 30s budget. The assertions complete in ~280ms; the remaining time is a teardown
   deadlock, and it is not a slow path but an unbounded one — raising the budget to 180s still times
   out.

[S2] Design Copy Chapter

SSRF resolver injection. assertSafeUrl takes the resolver as an optional second parameter
defaulting to dns/promises.lookup, mirroring the fetchImpl parameter safeFetch already exposes
for the same reason. The DNS-dependent assertions inject a stub, so they pin the behavior that
matters — resolution failure means reject, and a hostname resolving into a blocked range means
reject — without consulting a real resolver. Production callers are unchanged.

Rebuild-context actor leakage. listActive() stays process-wide: peer actors legitimately live
in child sessions, so scoping the query to one session_id would drop live children from the "Active
actors" section. The test instead wipes ActorRegistryTable in beforeEach, the same isolation
test/session/checkpoint-rebuild-v3.test.ts already applies for the same reason, and consistent with
how that test already neutralizes the other inputs (deleting the memory dirs, capping recent_user
to 0).

Cancel-cascade teardown deadlock. Reclaiming the workflow's children makes each one notify the
parent session's main inbox, which re-arms the parent's main runner against the auto-answering
test LLM. SessionRunState's instance-state finalizer cancels every runner still in its map, and
Runner.cancel awaits Deferred.await(run.done). Effect finalizers run uninterruptibly, so that
await cannot be bounded from inside and the instance disposer never returns. The test drains the
runner map itself — SessionRunState.cancel(parent.id), bounded and ignored — after its assertions
and before the fixture scope closes, where the cancel is still interruptible and the bound applies.

Out of the three, only the SSRF change touches src/, and it is additive.

Restored orphan-on-cancel coverage. The sibling test in the same describe, "cancel during an
in-flight fan-out reclaims every child (no orphan)", was skipped under the same symptom with the
diagnosis "cancel itself does not return before the test deadline". That diagnosis is wrong —
cancel returns in ~300ms — and the real cause is the teardown deadlock above. With the same drain
applied it is unskipped, restoring the only coverage of the MR104 orphan-on-cancel regression.

[S3] Out of Scope Copy Chapter

• Bounding Instance.dispose() so a stuck instance-state finalizer cannot wedge teardown.
  Instance.disposeDirectory already bounds its path with DIRECTORY_DISPOSE_TIMEOUT; the direct
  dispose() path does not. That is a real robustness gap, reachable in production whenever an
  instance is disposed while a session run is live, but changing teardown semantics is a separate
  change with its own risk surface.
• Session-scoping the "Active actors" rebuild section.
• The other llm.hang call sites in test/workflow/runtime.test.ts. They pass today; converting
  them is unverified churn.

Tasks Copy Chapter

• T1: Inject the resolver into assertSafeUrl and rewrite the DNS assertions against a stub —
  acceptance: bun test test/util/ssrf.test.ts passes with no network dependency (covers: S2)
• T2: Wipe leaked ActorRegistryTable rows in checkpoint-rebuild-unify — acceptance:
  bun test test/actor test/session/checkpoint-rebuild-unify.test.ts passes, having failed
  before (covers: S2)
• T3: Quiesce the parent session before teardown in the cancel-cascade test — acceptance:
  bun test test/workflow/runtime.test.ts passes with zero failures (covers: S2)
• T4: Confirm no further local-only failures across two full runs — acceptance: the union of two
  bun test runs adds no failure attributable to this branch (covers: S1)
• T5: Unskip the orphan-on-cancel test with the same drain — acceptance:
  bun test test/workflow/runtime.test.ts green three consecutive times and a full run stays
  green (covers: S2; depends: T3)

Compose Spec History Chunk Large Bodies (`docs/compose/spec/history-chunk-large-bodies.md`) Copy Section

feature: history-index-tool-output-budget status: delivered updated: 2026-09-16 branch: feat/history-chunk-large-bodies commits: b4cc11cd652195af9a80297ed543218f3172e6c4..HEAD Copy Chapter

History FTS Index Budget (tool-output policy)

Report Copy Chapter

What was built — History FTS is truncated before write on the same path as tool call results: pure previewToolOutput in tool/truncate.ts is shared by Truncate.output and history extract / writer / import. Tool parts prefer the stored tool-result string (including Full output saved to: when tools truncated); other kinds compose then preview with the same 50KiB / 2000-line budget. Full text stays in PartTable / tool-output files for history get. Migration v6 removes legacy chunk rows and rebuilds one truncated index row per original part.

Verification — packages/cli: bun test test/history/ green after budget tests; tsgo --noEmit filtered to src/history/test/history clean.

Journey log

• Root cause is missing pre-write truncation, not chunking: tool results are capped; history indexed full part payloads (patch ~38MB, reasoning ~600KB).
• User required the tool-call-result path — previewToolOutput extracted from truncate.ts; history writer/import call it before FTS insert.
• Chunk deletion uses exact base id plus the binary prefix range [id + '#', id + '$'), preserving literal _/% while using the primary-key index.
• Post-LIMIT dedupe under-filled search — over-fetch limit*24 before dedupe.

[S1] Problem Copy Chapter

Tool outputs already have a staged length policy before entering the model (truncate.output: ≤50KiB / 2000 lines; full text saved to tool-output files). History FTS extract had no equivalent budget and indexed unbounded part payloads. On a real ~7.3GB trajectory DB this produced multi-MB FTS documents and CPU-heavy snippet()+bm25() ranking.

[S2] Design Copy Chapter

Contracts Copy Section

• Single write path upsertHistoryBody: cleanDataUrls then previewToolOutput before FTS insert (live writer, import, migration rebuild, test backfill)
• Pure preview lives in tool/preview.ts (no Log/Global); tool/truncate.ts re-exports and owns model-facing Truncate.output
• Extract also strips data-URLs before preview so binary payloads never consume the tool-result budget
• Budget: MAX_BYTES=50KiB / MAX_LINES=2000 from tool/preview.ts, head+tail when tail looks like errors; index bodies hard-clamp to this ceiling
• Migration batch (migration-batch.ts) is Log-free; scheduler startIndexMigration accepts optional migrate for tests and clears jobs after 5 failed attempts
• Migration v6 SQL marks prior history_index_migration versions done so superseded state cannot linger at clean
• Search keeps temporary limit*24 over-fetch (debt history-search-overfetch-after-v6); tighten to limit after v6 — see Follow-ups
• Search uses CROSS JOIN so SQLite evaluates MATCH once, then rowid lookup (Node SQLite plan regression covered in tests)
• Tool body composition: input JSON previewed at ~25% budget; tool output previews keep the Full output saved to: path hint inside budget
• Migration scheduler: limited error backoff (5 attempts) + jobs slot clear on done/error/abort so restart works; stopIndexMigration deletes the slot
• previewToolOutput reserves MARKER_RESERVE bytes so omission markers stay within MAX_BYTES; single-line giant outputs keep a head slice instead of only the marker
• Tool parts: index stored tool-result string when present (incl. Full output saved to: ); still bound legacy payloads
• history get reads full PartTable text
• No new index chunks are written. Indexed deletion and search normalization only support legacy chunks during background cleanup.

Background migration v6 Copy Section

• Always start clean → repair
• clean: delete legacy chunk rows and orphan index rows; never reconstruct text by joining old chunks.
• repair: read original parts, apply the shared truncate policy, and upsert exactly one row under the original part id. The 50KiB preview must not be split again at 48,000 characters.
• Recreate history_part_ad for chunk ids
• Separate the state insert, trigger drop, and trigger creation with Drizzle statement breakpoints so Node SQLite executes all three statements. test/history/node-migration.test.ts verifies deletion removes chunk rows while preserving unrelated parts through the actual Node driver.
• Startup waits one second before background work. Each transaction processes at most 32 rows and yields after an 8ms budget, checked between rows. Read one original body at a time; cursor and writes commit together, so yielding/restarting cannot skip unfinished rows.
• Rest after each batch for at least 100ms and at least 19 times its elapsed duration (including commit), targeting at most a 5% migration duty cycle per process. This is cooperative throttling, not a hard process CPU cap: an individual synchronous row or commit can exceed 8ms, and normal application work has a separate cost.
• The follow-up schema migration 20260916000000_history_single_row_index replaces the delete trigger with the indexed prefix range and starts v6 even on databases that already completed v5; those databases can still contain chunks. V6 resumes its own persisted cursor on subsequent launches.
• Regression coverage: exact/chunk deletion preserves adjacent ids and literal wildcard characters; both deletion paths use an indexed query plan; both migration phases yield without losing cursor progress; the scheduler rests after work and cancels on database close.

Follow-ups Copy Chapter

• history-search-overfetch-after-v6 — after v6 migration completes on a database (or once production fleet has finished v6), set service.ts search fetchLimit back to limit and drop the legacy over-fetch comment.

[S3] Out of Scope Copy Chapter

• buildFtsQuery AND/OR semantics
• Changing which part types are indexed
• Desktop engine-pin bump / shipping
• Online surgery of production DB outside the background migration

Tasks Copy Chapter

• T1: index-preview.ts + extract() tool-output budget (covers: S2)
• T2: chunk-write.ts shared upsert/delete; writer + import (covers: S2)
• T3: service.ts search/get chunk-id normalize + over-fetch dedupe (covers: S2)
• T4: Migration v6 + indexed trigger (covers: S2)
• T5: Tests: index-preview, extract budgets, chunk-write, backfill (covers: S2)
• T6: history unit suite + typecheck (covers: S2; depends: T1-T5)

Compose Spec Host Error Registry (`docs/compose/spec/host-error-registry.md`) Copy Section

feature: host-error-registry status: in-progress updated: 2026-09-24 branch: feat/host-error-registry commits: Copy Chapter

Host Error Registry

Report Copy Chapter

[S1] Problem Copy Chapter

Hosts need stable codes and explicit retry behavior for their own LLM API business failures, without teaching the engine product codes. Engine error names, broad HTTP statuses and message fingerprints cannot identify a particular host's API response safely.

[S2] Design Copy Chapter

Trust and scope Copy Section

The catalog is data only. The engine matches at the LLM API boundary using the providerID from the selected model's trusted call context. It never infers source from response JSON, URLs, message text or error metadata. Hosts must reserve their providerID and prevent BYOK overrides. No product provider IDs or business codes are built into the engine.

Only SDK API failures and structured provider error events are eligible. Tool errors, invalid output, aborts, programming errors and filesystem errors do not acquire host codes. Native transport failures without an API response remain on the engine's network path.

Catalog v2 Copy Section

This replaces unpublished v1; no birth-identity compatibility layer is retained.

type RetryClass = "terminal" | "persistent" | "bounded"
type JsonValue = string | number | boolean | null | readonly JsonValue[] | { readonly [key: string]: JsonValue }
type HostResponseMatch =
  | { readonly kind: "field"; readonly path: string; readonly value: string | number | boolean | null }
  | { readonly kind: "json"; readonly value: JsonValue }
  | { readonly kind: "empty" }
interface HostErrorRule {
  readonly match: {
    readonly providerID: string
    readonly statusCode?: number
    readonly response: HostResponseMatch
  }
  readonly code: string
  readonly retryClass: RetryClass
}
interface HostErrorCatalog {
  readonly protocolVersion: 2
  readonly rules: readonly HostErrorRule[]
}

Example (synthetic values):

{
  "protocolVersion": 2,
  "rules": [
    {
      "match": {
        "providerID": "test-host",
        "response": { "kind": "field", "path": "/failure/reason", "value": "busy" }
      },
      "code": "host.example.busy",
      "retryClass": "persistent"
    },
    {
      "match": {
        "providerID": "test-host",
        "statusCode": 403,
        "response": { "kind": "json", "value": { "error": "Example restricted account", "code": 403 } }
      },
      "code": "host.example.restricted",
      "retryClass": "bounded"
    },
    {
      "match": { "providerID": "test-host", "statusCode": 401, "response": { "kind": "empty" } },
      "code": "host.example.unauthorized",
      "retryClass": "terminal"
    }
  ]
}

All conditions within a rule are AND; the first matching rule wins. Field paths are RFC 6901 JSON Pointers, not dotted paths or URI fragments. The empty pointer "" selects the root; /token selects a member, / selects an empty key, and ~0/~1 decode to ~// without percent decoding. For example, /items/0/a~1b selects the a/b member of the first item. Arrays accept only canonical nonnegative indexes (0 or a nonzero digit followed by digits); leading zeros, signs, -, length and out-of-range indexes do not resolve. Those tokens remain valid object member names. Traversal reads only own properties and never boxes scalars or reads prototypes.

Field values use strict typed equality for strings, numbers, booleans and null; missing paths and malformed/non-JSON bodies never match null. JSON selectors accept any JSON root, including arrays, scalars and null, and compare the complete structure: object key order is ignored, additional keys and array ordering remain significant, and no type coercion occurs. Empty matches only missing/whitespace response bodies and require a statusCode; JSON null is not empty. No substring or regex matching is supported. An exact restricted-account 403 rule does not change unrelated 403 handling.

The schema rejects invalid versions, unknown keys, invalid classes, empty codes/provider IDs and malformed selectors as a whole, including nonempty pointers without a leading slash and any tilde escape other than ~0 or ~1. Rejected catalogs preserve the previous snapshot. The public loader also returns { ok: false, reason } for validation or cloning exceptions without replacing that snapshot. Valid catalogs replace it atomically; an empty array disables new bindings. Snapshots are deeply frozen.

Boundary and lifetime Copy Section

bindHostError(error, { providerID }) first matches only inside the actual provider doStream() invocation and its returned raw provider stream (error parts and stream-read failures). Host transport wrappers, plugin preparation, SDK tool repair and the surrounding attempt never create new bindings. The raw stream wrapper preserves backpressure and propagates cancellation upstream. Matches and misses are cached by raw object identity and trusted providerID.

At the trusted doStream boundary, enable the SDK's existing includeRawChunks option. Some compatible adapters emit a raw frame followed immediately by an error part containing only the message string. Retain at most one raw error frame; restore structure only when the immediately following part is an error with the same string message. Both {error: {...}} and {type: "error", error: {...}} are supported. Matching uses the original complete raw JSON, not the normalization envelope. Intervening parts, normal raw frames, completion, cancellation and read errors clear the pending frame. Normal raw chunks never trigger catalog matching and internally requested raw parts are consumed before reaching the SDK fullStream/UI; an explicitly requested raw stream retains its requested visibility. No fetch or SSE parser is added.

Outside that boundary, inheritHostError follows only the SDK RetryError last-error chain to an existing binding, including cached misses, without consulting the catalog. Earlier retry-history entries cannot donate a binding to an unbound last error. Normalization also performs this inheritance before unwrapping content; the same failure retains its binding across catalog reloads. SDK-flattened stream errors use their retained original data frame for structured matching. A structured type: "error" protocol frame may carry arbitrary JSON payload fields; recognition does not require particular business field names. An outer type: "error" frame is authoritative even when its data member resembles another error frame; only flattened wrappers fall back to data.

Generic normalization and retry decisions do not match catalogs. They only propagate/read existing bindings. NamedError has no global enrichment hook. Direct construction does not stamp. Live request, processor and max-mode retry paths use fromLiveError: API host fields require an existing binding for the trusted providerID, and an absent binding or cached miss clears supplied stamps. Plugin preparation and whole-attempt failures cannot promote a plain APIError-shaped object or a constructed APIError into a host error. No catalog matching occurs at these outer boundaries. Live non-API errors always discard supplied host fields as well, preventing local output, abort or unknown errors from carrying a forged host identity to events.

fromError retains its trusted restoration/idempotence contract: schema/JSON/SQLite/event round-trips preserve API host fields without consulting the current catalog. Restoring serialized fields does not grant a live binding. Only an already-bound source transfers its binding to a normalized APIError, allowing repeated live normalization and SDK last-error wrapping to preserve the same decision across catalog reloads; a JSON clone is not live provenance. Real abort/context/load-key normalization remains native and does not gain a new host code.

Native retry facts follow only an SDK RetryError's lastError (or final array entry when lastError is absent) and actual cause links. Earlier attempts are not causes of the final failure. Normalization stores effective cause facts in metadata.causeChain, including a single remaining fact after removing an SDK retry wrapper; when the full diagnostic summary differs, it is retained separately as metadata.retryHistory. Retry classification never reads retryHistory, so an earlier timeout cannot turn a final TypeError into persistent recovery, nor can an earlier HTTP404 stop recovery of a final HTTP503. If normalization would otherwise lose a bare error's safety-terminal identity, its current operative summary is retained as causeChain even without a cause wrapper. Already-terminal normalized output is left unchanged so repeated restoration remains idempotent.

Behavior precedence Copy Section

1. User cancellation, actual context overflow, missing API keys and other true engine safety failures stop retry. Stream error code and type are checked independently for context overflow: a numeric business code cannot hide a context_length_exceeded/context_window_exceeded type. This applies to raw and SDK-flattened frames, with or without a catalog, and normalizes to an unstamped ContextOverflowError. HTTP provider messages explicitly saying that the prompt exceeds the model's context window also normalize to ContextOverflowError when the response has no structured overflow code; the same decision applies to the structured response error message when the SDK message is generic. Ordinary model-window configuration errors and output-limit errors remain API errors. Unsafe tool-side-effect replay remains forbidden.
2. Explicit matched host behavior controls API errors. Terminal business failures cannot become network retries because their body/message mentions IO or because HTTP status is 5xx. Precisely matched host bounded errors can override broad HTTP400/403 heuristics.
3. Unmatched native network/timeout errors retain mandatory persistent recovery (including HTTP408/504 legacy handling).
4. Otherwise existing HTTP, quota and non-network heuristics apply. An unmatched HTTP401 is terminal even when a gateway labels its response upstream_error: repeating an unchanged unauthorized model request cannot restore credentials. Native stream_read_error/upstream_error and rate-limit signals retain their precedence over the broad HTTP400/403/422 fallback; ordinary client failures without those signals remain terminal.

The stored host class is behavioral, independent from the diagnostic RetryKind. RetryDecision carries hostCode and hostRetryClass; retry status/events continue carrying hostCode. Terminal decisions emit no retry event. Malformed persisted stamps with hostCode but no valid class fail closed as terminal; class without code is ignored.

Budgets Copy Section

max-candidate/max-judge retain their own isolation budgets. For normal request/live-step:

• Host persistent forces mode: persistent, no maxRetries, and maxElapsedMs=0. Neither global/provider configuration nor caller budgets may downgrade this. Exponential backoff, delay caps, Retry-After and jitter remain effective.
• Host bounded uses the phase request/stream budget, never the default-persistent server/rateLimit budget. Force bounded mode; missing/nonfinite count and nonpositive/nonfinite deadline fall back to existing phase defaults: request 4 retries / 30 seconds, stream 5 retries / 10 minutes. Explicit finite configured limits remain valid.
• Native network forces persistent, without attempts/deadlines, as before.
• The schedule enforces these semantics even when supplied a custom budget callback. Persistent retries remain cancellable and respect replay safety. Silent-overload limits cannot cap host persistent recovery.

Persisted event ownership Copy Section

Effect InstanceRef is authoritative over ambient instance ALS when both exist. InstanceState.bind captures that Fiber context first, falling back to ALS only when the Fiber has no instance reference; callbacks outside either context remain unchanged. This is the same precedence used by InstanceState.context.

Database transaction callbacks and deferred post-commit effects must restore the captured owner before invoking synchronous instance consumers. Persisting a message or part under conflicting ALS must publish both its project Bus event and GlobalBus ordinary/sync envelopes to the Fiber owner's directory and project, never to the ambient instance. The database write succeeding alone is not sufficient verification. This fixes the callback bridge without changing SyncEvent payloads, retry behavior, or host matching boundaries.

Bootstrap and API Copy Section

Keep loadHostErrorCatalog, loadHostErrorCatalogFile, hostErrorCatalog, and HOST_ERROR_CATALOG. Load before accepting traffic in CLI/shared-server paths; initialization runs once and cannot overwrite later explicit reloads. No new HTTP control plane is introduced.

[S3] Out of Scope Copy Chapter

Product codes, UI copy, source inference, BYOK ownership enforcement, regex/plugin matching, default budget number changes, and multi-host catalog merging.

Tasks Copy Chapter

• Specify the v2 schema, boundary and behavior contract.
• Replace birth identity matching with API-bound response matching and remove global constructor stamping.
• Wire all provider error events/thrown failures and preserve normalized API bindings.
• Enforce behavior budgets with safety precedence and native network recovery.
• Verify malformed input, provider isolation, exact-body matching, reload stability, non-API exclusion, persisted envelopes, bounded exhaustion, terminal no-retry, cancellation and recovery beyond one virtual hour.
• Run package typecheck and focused/expanded regression suites; document results.
• Reproduce persisted message event cross-directory routing under conflicting ALS/Fiber contexts, align callback binding precedence, and verify database persistence plus owner/wrong-owner/GlobalBus delivery.

Delivery verification Copy Chapter

• Focused registry/retry/max-mode-input suite after boundary review: 120 pass, 0 fail (867 assertions).
• Provider/LLM/max-mode/prompt/compaction regression suite after compatible-adapter review: 140 pass, 0 fail (490 assertions). The two max-mode-input cases overlap; 258 distinct tests passed across both runs.
• Effect TestClock drives both request and stream host-persistent schedules through 70 failures and 71 virtual minutes to successful recovery despite bounded caller budgets and silent-overload predicates. The empty-catalog native network path also recovers after 70 failures. User interruption during a wait prevents further requests even after advancing two hours.
• Exact restricted-account HTTP403 exhausts request/stream count budgets despite a persistent custom budget. Host persistent retains max-candidate/max-judge isolation and cannot cross unsafe replay boundaries. Synthetic terminal business responses with HTTP400/408/500/503/504 and network-looking messages never retry.
• Real local HTTP/SDK integration preserves host codes on errors after output. The test first exposed SDK-flattened errors containing the original frame in data; matching now uses that structured frame. The existing HTTP408/429/503 recovery test still verifies correct-directory delivery, zero wrong-directory events and matching GlobalBus.directory.
• Boundary review reproduced a plugin preparation APICallError incorrectly acquiring a host code, then fixed it by moving first binding from whole-attempt/fullStream to actual doStream/raw provider stream. A real tool-repair callback throwing the same API-shaped error remains native; HTTP and post-output SSE bindings plus provider cancellation still pass. SDK RetryError inherits only an already-bound last error, preserving reload identity and provider isolation.
• Safety review reproduced a numeric business code masking context_length_exceeded in a stream error type. Independent code/type checks now keep raw/SDK-flattened frames and JSON round-trips terminal and unstamped, with and without a catalog.
• Real @ai-sdk/openai-compatible post-output SSE tests first reproduced loss of structured error fields into a string. Six red-to-green cases cover terminal/persistent/context behavior with and without top-level type. Persistent retries the actual request to recovery despite a zero-retry caller budget; terminal/context stop after one request. Complete-JSON and field selectors both work; raw chunks never appear in returned fullStream events and schema/JSON normalization retains the result.
• Production-routing follow-up: four regression cases failed on the old ALS-first binding. The real Session service test confirmed message/part rows persisted while the owner received neither event, the wrong instance received both, and all four ordinary/sync GlobalBus envelopes carried the wrong directory and project. Fiber-first binding makes the same test pass; additional cases cover deferred async callbacks, database use/transaction commit effects, Fiber-only, ALS-only and context-free binding.
• Post-routing regression run: 216 pass, 0 fail (1161 assertions) across instance-state, run-service, database, storage, sync, three Bus suites, registry, retry and two LLM suites. Package bun typecheck and git diff --check pass.
• Generic selector follow-up first reproduced 18 failures against the old path schema (6 tests still passed). Final registry/retry/LLM/LLM-retry/provider-error/message-v2 suites: 230 pass, 0 fail (2315 assertions), including 31 registry tests. Coverage includes root scalars/arrays/null, escaped and empty keys, canonical array indexes, own-property traversal, strict types, whole-catalog rejection, retained snapshots and arbitrary structured error payloads through bind/fromError.
• Complete-JSON matching also preserves literal prototype-named keys. A separate red test exposed record-schema stripping of __proto__ and rejection of an own constructor; strict JSON validation plus a detached clone now preserves those keys without reading inherited members during pointer resolution. Package bun typecheck and git diff --check pass.
• Malformed RetryError follow-up reproduced failures in both API response extraction and binding inheritance when lastError was absent and errors was missing or non-array. Both paths now guard the history with Array.isArray, matching message-v2 normalization; valid lastError remains preferred and a genuine array still falls back to its final entry. Two new path-specific regressions cover missing/null/scalar/object/array-like history without borrowing a forged binding. Registry plus message-v2: 76 pass, 0 fail (1496 assertions); the final six-suite run above also passes. Package bun typecheck and git diff --check pass.
• Review follow-up reproduced two failures before correction: nested error-shaped data displaced an outer raw error frame, and direct catalog loading leaked validation/clone exceptions. Field and complete-JSON regressions now preserve the outer frame; Proxy/DataCloneError and throwing-getter inputs return rejection while retaining the previous snapshot and rule behavior. Registry-only verification: 31 pass, 0 fail (786 assertions); final expanded verification is the six-suite result above.
• Native retry/source-trust follow-up added eight regressions, first failing in a seven-case run plus a separate non-API field-exclusion case. Real SDK HTTP408→TypeError history now stays bounded; earlier 404/401/network attempts cannot classify the final 503, while a final error's actual network cause survives JSON. Empty/unmatched catalogs retain HTTP400 stream/rate-limit recovery. Real chat.params plugins throwing either a plain APIError-shaped object or a constructed APIError with forged bounded stamps now stop after one attempt, not two. Strict live normalization rejects forged API and non-API fields but preserves existing bindings across reloads and repeated normalization; trusted schema/JSON restoration retains fields without acquiring a live binding. Final six-suite verification: 238 pass, 0 fail (2401 assertions); processor/max-mode verification: 30 pass, 2 existing skips, 0 fail. Package typecheck and git diff --check pass.
• Independent review reproduced loss of a single final safety fact after removing the SDK retry wrapper. Cause-bearing inputs now retain every nonempty operative summary, including one entry. A real generateText HTTP408→SubscriptionUsageLimitError regression verifies terminal decisions before normalization, after live normalization and after JSON restoration; equivalent FreeUsageLimitError/ProviderAuthError/ContextOverflowError cases and the earlier-history→503 controls pass. The new test failed before the one-line preservation fix. Registry/message-v2/retry verification: 185 pass, 0 fail (2250 assertions); package typecheck and git diff --check pass.
• Final review follow-up first reproduced two boundary failures: malformed output-length name-only objects bypassed schema validation and crashed strict live normalization, and bare safety-named Errors lost terminality without a cause wrapper. Removed the redundant output-length direct-return branch; valid instances and serialized forms still pass the existing schema path. Safety facts are supplemented only when normalization loses terminality, preserving raw/live/JSON decisions and repeated restoration without growing metadata. Final six-suite verification: 242 pass, 0 fail (2475 assertions); package typecheck and git diff --check pass.

Compose Spec Inbox (`docs/compose/spec/inbox.md`) Copy Section

feature: inbox status: in-progress updated: 2026-09-26 Copy Chapter

Inbox 输入队列

每个 lane (sessionID, agentID) 的唯一持久化输入队列。所有外部输入（用户 prompt、actor send、子任务完成通知、workflow/spawn 投递）走同一套受理、认领、结算、停止逻辑。

目标 Copy Chapter

1. 一个调度归属：inbox 是 lane 的唯一输入队列与受理/认领/结算所有者。Runner 只持有执行租约。
2. 输入同构：任何来源的输入在受理时写成接收方切片的一条 user 消息加一行 inbox 记录，不按发送方或 type 分叉行为。
3. 唤醒同构：任何受理都递增 input_revision，显式 actor.wait 与自动等待一律以 interrupted 结束。
4. 读取聚合：每个步骤边界认领该 lane 全部 accepted 记录，多条输入同边界一起对模型可见。
5. 可见性：只对模型隐藏仍在排队的输入（accepted 未认领，或被其他运行认领）。
6. 停止语义：用户停止把 accepted/claimed 记录结算为 cancelled，消息保留且对模型可见，不自动执行。
7. 回执契约稳定：HTTP prompt_async 202 {receiptId}、GET /session/:sessionID/receipt/:receiptId、session.receipt.updated 事件由 inbox 记录提供，PublicReceipt 单源。

表结构 Copy Chapter

新迁移目录 packages/cli/migration/<ts>_inbox_queue/。已发布的 20260527000100_inbox 迁移不改。SQLite 不支持的列变更用表重建。

`inbox`（重建） Copy Section

索引：

• inbox_receiver_idx (receiver_session_id, receiver_actor_id, id)
• inbox_state_idx (receiver_session_id, receiver_actor_id, state)
• inbox_created_idx (created_at)
• inbox_idem_idx 唯一 (receiver_session_id, idempotency_key) WHERE idempotency_key != ''

`inbox_lane_state`（新表） Copy Section

主键 (session_id, agent_id)。

`inbox_session_epoch`（新表） Copy Section

turn_legacy_bootstrap 不再需要：旧历史消息没有 inbox 记录，按可见性规则直接对模型可见。

新迁移做什么 Copy Chapter

packages/cli/migration/<ts>_inbox_queue/migration.sql（<ts> 晚于已发布的最新迁移 20261012000000_history_cjk_unigram）：

1. 表重建 inbox：建 inbox_new（上表列）→ 把旧行拷入（content 保留、input_message_id 置 NULL、state='accepted'、time_updated=created_at）→ 丢旧表 → 改名 → 建四个索引。
2. 建 inbox_lane_state、inbox_session_epoch。
3. 不写清理 turn_receipt / turn_lane_state / turn_session_epoch / turn_legacy_bootstrap 的语句（那四个表与两个迁移目录从未发布，当从不存在，直接删掉目录即可）。

旧行转成消息不在 SQL 里做：生成 MessageID 与确定 synthetic 消息的 agent/model 都依赖运行时，见「已发布数据」。

状态机 Copy Chapter

accepted → claimed → settled   (outcome success | assistant_error)
                   → cancelled (outcome interrupted | never_ran)
accepted → cancelled | rejected
claimed  → cancelled           (停止 / epoch；consumed 区分 interrupted 与 never_ran)

• settled + assistant_error：回合已跑，assistant 消息带错误。
• 一个 runId 可认领 N 条记录；认领与执行通过 acquireUseRelease 形成完整生命周期，退出时统一结算，覆盖已认领但尚未进入 runLoop 的取消。runLoop 共用结算处理，成功、assistant 错误与执行中断均覆盖，每条 claimed 记录得到终态。
• 幂等：唯一性按会话（receiver_session_id + idempotency_key）。并发 accept 同键一条插入胜出，另一条返回同一记录。

受理（accept） Copy Chapter

一个事务内完成：

1. 把输入写成接收方切片的一条 user 消息。agent 发来的标记 synthetic，消息 provenance 为 { source: "agent", senderSessionID?, senderActorID? }。synthetic 消息的 agent/model 在受理时按接收方确定（resolveDrainSeed 语义：standing peer 跨切片搜索，无历史时使用注册 agent 与默认模型；workflow 父 agent 只搜本切片）。缺少接收方模型来源的协调切片使用 system agent/model 保存消息；laneKick 仅在接收方切片能够解析真实模型时执行，防止子 actor 通知凭空产生真实回合。
2. 写一行 inbox 记录：state=accepted、epoch、input_message_id 指向该消息、幂等键、type、发送方。
3. 递增该 lane 的 input_revision。

事务提交后发布 session.receipt.updated。lane 空闲时经唯一调度路径（schedulerRef.kick）启动执行。laneKick 在执行租约内认领输入；子 actor 的续执行先取得 ActorExecution，再认领待处理记录，认领为空时结束，不发送额外终止通知。spawn/hook 初始执行沿用其外层 actor 生命周期，续执行由自己的 runTurn 负责终止通知。

用户 prompt 与 agent 输入共用 inbox.accept：sessions.persistQueuedUser 并入其中，不再单独存在。消息上的 queueAdmission 标记删除，排队状态只以 inbox 记录为准。

noReply 的 prompt 只写入历史、不请求执行，所以不经受理：直接写成没有 inbox 记录的普通 user 消息，按可见性规则对模型可见，不递增 input_revision，不启动执行，也不会被之后的运行认领。

跨会话投递与发送前接收方存在性检查（InboxReceiverNotFound）保留。inbox 不再存正文。send 的 wake / isWakeCancelled / wakeEpoch 参数由 AdmissionGuard（isCancelled / expectedEpoch）取代。会话停止时发出的子 actor 终止通知照常受理，随后由停止规则结算，没有单独的受理即作废路径。

唤醒 Copy Chapter

任何受理都递增 input_revision。显式 actor.wait 与自动等待（waitForSubagents）都经 observeInput(lane, afterRevision) 解除并返回 interrupted（有新输入到达），不取消子 actor。lane 空闲时受理即通过唯一调度路径启动执行。

读取 Copy Chapter

每个步骤边界认领该 lane 的 accepted 记录（claimNext），单次最多 100 条（MAX_CLAIM_PER_STEP），对应消息对模型可见并记录 delivery（delivery_message_id，事件在事务提交后发布）。写入 delivery_message_id 的同一事务把 consumed 置为 true：从这一刻起输入已被模型读入，之后停止结算为 interrupted。多条输入在同一边界一起读到。inbox.drain 及其手工回滚逻辑删除。extendClaim 在同一运行内认领边界到达的新输入。

可见性 Copy Chapter

只对模型隐藏仍在排队的输入：

• inbox 记录为 accepted（未认领）→ 隐藏。
• 被其他运行 claimed → 隐藏。
• cancelled、settled → 可见。
• 没有 inbox 记录的消息（历史、压缩 replay、导入等）→ 可见。

停止 Copy Chapter

用户停止时，该会话所有 accepted/claimed 记录结算为 cancelled：outcome 按是否已被模型读入取 interrupted（consumed=true）或 never_ran（consumed=false）。停止操作由 withStop 包围：期间抑制该会话的调度与认领，输入仍正常受理；停止操作收尾复用相同结算规则处理期间收到的输入，不再次递增 epoch。消息留在消息记录里、对模型可见，不自动执行。下次任何输入触发运行时模型会看到它们。用户 prompt 与 agent 消息同一规则。keep-suspended / drop 策略与 suspended 列删除。

abortSession 仍递增会话 epoch；epoch 低于当前值的 accepted/claimed 记录不可再被认领。

对外契约 Copy Chapter

PublicReceipt 字段：id、lane、state、type、senderSessionID?、senderActorID?、epoch、consumed、outcome?、inputMessageID、deliveryMessageID?、error?。内部记账（runId、claimFrontier、idempotencyKey、time）不进外部契约。

每条记录只承载一条输入，字段直接平铺在回执上，没有 intent 包装。resume 与 shell 是独占入口（C-03），不写 inbox 记录，因此不存在 resume、shell、wake 类型。

记录只引用两条消息：

• inputMessageID：受理时写入的 user 消息。客户端用它把回执关联到消息。
• deliveryMessageID：首次读入该输入的 model-step assistant 消息，只写一次；引擎渲染上下文时用它确定输入的位置，客户端用它判断输入已被消费。写入时发布 session.receipt.updated。

结算（ack）只写 state / outcome / error，不记录任何消息 ID。OpenAPI 响应 schema 与 HTTP body 共用 PublicReceipt zod 单源。

fork Copy Chapter

fork 的目的是让新会话继承原会话的 prefix cache，所以新会话渲染出的上下文必须与原会话逐条一致。

复制消息时按原会话渲染给模型的顺序写入：先按「可见性」过滤，再按 delivery_message_id 把已消费的输入移到对应 delivery 消息之前，然后按这个顺序为每条消息分配递增的新 MessageID（消息 ID 是全局主键，必须换新），assistant 的 parentID 指向对应的新 ID。消息读取按创建时间排序、再按 ID 排序，所以复制时把每条消息的 time.created 取为它的原值与序列中前一条消息 time.created 的较大值，使创建时间沿渲染顺序不递减。仍在排队的输入（accepted 或 claimed 未消费）按受理顺序排在末尾。messageID 截断点按渲染顺序计算：只复制渲染序列中该消息之前的部分。

fork 不复制 inbox 记录，也不改写任何记录里的消息 ID。新会话里的消息全部是没有 inbox 记录的普通历史，按可见性规则对模型可见，存储顺序即渲染顺序。

已发布数据 Copy Chapter

用户机器上可能存在旧格式待处理 inbox 行（有 content、无 input_message_id）。inbox 服务启动时把它们转为新模型：用与受理相同的写消息逻辑把 content 渲染为一条 synthetic user 消息，写入 input_message_id 并清空 content，state 保持 accepted、input_revision 照增。这是唯一的转换实现；content 列只为这些旧行保留为可空，新行永远为空。正文为空白或渲染为空白的旧行直接结算为 rejected，同时清空 content，后续启动不再转换。

GC Copy Chapter

原有 7 天按 created_at 清理改为：已结算记录（settled / cancelled / rejected）在 time_updated 之后 7 天清理。accepted / claimed 不按年龄清理。

每个调用方如何改 Copy Chapter

`packages/cli/src/actor/notification.ts` Copy Section

• makeTerminalNotifier 改调 inbox.accept（原 inbox.send）：content 改为在受理时写入 user 消息，不再先落 content 再 drain。
• wake / isWakeCancelled / wakeEpoch 参数换成 AdmissionGuard（isCancelled / expectedEpoch）。
• wake: false（会话停止时的终止通知）改为照常受理：inbox 记录照写、input_revision 照增，随后由停止规则结算。
• 删掉 sent.wakeSuppressed 分支判断。

`packages/cli/src/actor/spawn.ts` Copy Section

• cancel(..., { wake }) 的 wake 选项与 notifyTerminal 的 wake: false 传递链改为走 AdmissionGuard。
• wakeEpoch 捕获改为 expectedEpoch 语义（发送前捕获、受理时校验）。
• 删掉对 turnQueueRef 的直接依赖，改用 inbox 服务。

`packages/cli/src/workflow/runtime.ts` Copy Section

• inbox.send 改 inbox.accept；wake: false 同上。
• 子 agent 完成通知同样受理（写 user 消息 + inbox 记录 + 增 input_revision），因此会唤醒父 agent 的等待。resolveDrainSeed 的「workflow 父 agent 只搜本切片」语义在受理时生效，不凭空产生真实回合。

`packages/cli/src/tool/actor.ts` Copy Section

• inboxServiceRef.current.send 改 accept；返回值给 inputMessageID 与 inboxID。
• InboxReceiverNotFound 错误分支保留。

`packages/cli/src/session/prompt.ts` Copy Section

• createUserMessage → sessions.persistQueuedUser 与 tq.admit 合并为一次 inbox.accept（同一事务写消息 + inbox 记录 + 增 input_revision）。queueAdmission 标记由 inbox 记录取代。
• 删掉 inbox.drain 全部调用（约 862、4610、4735、6228 行）及 deferInbox 分叉；步骤边界改为 claimNext / extendClaim。
• 认领可见性过滤（约 4766–4785 行）改为按 inbox 记录状态判断：accepted 未认领或其他运行 claimed 的消息隐藏；其余可见。
• recordDelivery 写 delivery_message_id，事件在事务提交后发布。
• 运行结束结算（ack）不再传 messageId。
• abortSession 去掉 queuedPolicy；cancel 不再收 AbortPolicy。
• waitForSubagents 与显式 actor.wait 都用 observeInput 解除；任一输入唤醒。
• 删掉 requireClaim / inboxWake / LoopInput 相关字段与分叉（约 3536、6155、6227、7372、7546、7548 行）。

`packages/cli/src/session/session.ts` Copy Section

• fork 按「fork」一节改写：按渲染顺序复制消息，不复制 inbox 记录。

服务端路由 `packages/cli/src/server/routes/instance/session.ts` Copy Section

• prompt_async 202 {receiptId} 不变。
• GET /receipt/:receiptId 用 PublicReceipt 单源。
• abort 请求体去掉 queuedPolicy，响应 { epoch } 不变。

同步 `packages/cli/src/turn-queue/sync.ts` → `packages/cli/src/inbox/sync.ts` Copy Section

• 表名换成 inbox / inbox_lane_state / inbox_session_epoch。
• 去掉 bootstrap 分量。
• materializeHistory 继续为导入历史写 settled 记录。

其它 Copy Section

• packages/cli/src/effect/app-runtime.ts、control-plane/workspace.ts、sync/restore.ts、server/routes/instance/sync.ts、cli/cmd/export.ts、cli/cmd/import.ts、session/{codex,claude,opencode}-import.ts：import 路径换成 @/inbox，表名同步。
• 重新生成 SDK（./packages/sdk/script/build.ts）。

要删除的代码清单 Copy Chapter

测试点 (a)–(o) Copy Chapter

Compose Spec Log Safety (`docs/compose/spec/log-safety.md`) Copy Section

feature: log-safety status: delivered updated: 2026-07-27 branch: fix/tui-log-stderr commits: 014a2577..aa28c273 Copy Chapter

Log Safety

Report Copy Chapter

What was built — Logger instances own unique active files and serialize initialization, writes, rotation, and shutdown through one lifecycle queue. Cleanup preserves live files, recovers stale process and worker files, enforces archive count and size budgets, and stops file writes safely when finalization cannot complete. CLI hard exits use Log.exit() and normal TUI exits return through the top-level shutdown.

The logger no longer treats stderr as a fallback sink. Records reach stderr only under --print-logs; without a usable file sink they are dropped, and sink failures are swallowed rather than reported. The TUI worker flushes before its bounded teardown and closes its log as the last teardown step, so instance disposal and bus unsubscribe records land in the file instead of on the rendered screen.

Verification — MIMOCODE_PROCESS_ROLE=main bun test test/util/log.test.ts passed 18 tests / 53 expectations, and MIMOCODE_PROCESS_ROLE=worker bun test test/util/log.test.ts test/effect/app-runtime-logger.test.ts test/effect/runner-warn-log.test.ts passed 26 tests. bun typecheck passed. oxlint on the changed files reported zero warnings and zero errors.

Reproduction, before and after: running the same child-process script against the pre-fix log.ts leaked INFO … teardown after shutdown to stderr, while the fixed logger emitted nothing. End-to-end, a tmux-driven bun dev <dir> quit through the exit prompt command on main printed nine teardown records to stderr — the exact lines the user reported — with the worker log file ending at worker shutting down; on the delivered head stderr stayed empty and the worker log file contained the full teardown sequence through service=bus type=session.updated unsubscribing.

Journey log

• The first review exposed that a write queue alone is insufficient; lifecycle mutations must use the same queue.
• Capturing a stream before queued rotation can make shutdown close the wrong resource; shutdown now resolves the current stream only when its queued operation runs.
• Bun main and worker contexts share a PID, so stale worker recovery also needs the process role.
• Closing the worker log before its teardown traded one bug for another: the records were durable but were printed over the TUI. Flushing, then closing last, satisfies both; a worker killed mid-drain leaves an .active.log that the next initialization recovers.
• Gating the failure report behind print mode made it unreachable — print mode never opens a file — which is why the reporting path was removed instead of gated. Attempting to test a branch is the cheapest way to discover it cannot happen.
• bun dev writes its logs under the checkout's .dev-home (MIMOCODE_HOME in script/dev.ts), so redirecting only stderr to a file keeps the TUI on the real terminal while making a leak trivially greppable.

[S1] Problem Copy Chapter

The CLI main context and TUI worker initialize logging independently but can target the same file. Rotation and cleanup can therefore rename, truncate, or delete a file another context still writes. Log writes also discard asynchronous failures and fatal exits do not flush.

[S2] File Ownership And Retention Copy Chapter

Each logger initialization owns a unique active filename containing the timestamp, process role, PID, and a random instance identifier. Active files are distinguishable from completed and rotated files and are never selected by cleanup. Initialization, writes, rotation, and shutdown share one ordered lifecycle queue, so concurrent initialization closes the prior stream before replacing its state.

With rotation enabled, queued records that individually fit within the threshold rotate before an active file would exceed 50 MiB. Archived files are reduced to at most 10 and at most 200 MiB in total, and cleanup errors do not interrupt logging. A failed archive move uses a copy/remove fallback; if finalization still fails, the file sink closes instead of reopening the same oversized file with a reset counter. Explicitly disabling rotation continues to permit one active file to exceed 50 MiB.

[S3] Failure And Shutdown Behavior Copy Chapter

Stream failures are consumed by the logger and must not create unhandled promise rejections, crash on a stream error event, or recursively call the logger. They are not reported to any stream: a file failure can only happen while logging to a file, which is exactly when stderr belongs to the rendered TUI screen, so the missing or short log file is the only signal. flush() waits for queued writes and leaves the file sink open. shutdown() runs after earlier queued rotations, closes the final stream, and marks its file completed. CLI hard exits use Log.exit(), and normal TUI exits return through the top-level shutdown.

[S4] Terminal Isolation Copy Chapter

The logger writes to stderr only when the process was initialized with print (--print-logs), and then only the records themselves. Without a usable file sink — before initialization, after shutdown(), or when opening or finalizing the file failed — records are dropped. The TUI renders on the same terminal the process writes stderr to, so a leaked line corrupts the screen; a dropped record is preferable to a corrupted display.

The TUI worker therefore flushes, not closes, before its bounded teardown: queued records must be durable in case the host kills the worker mid-drain, while the teardown that follows (checkpoint drain, instance disposal, server stop) must still log to the file. The worker closes its log as the last teardown step. A worker killed before that leaves an .active.log that the next initialization recovers.

[S5] Testing Boundaries Copy Chapter

Tests use real temporary files and streams. They cover unique ownership across repeated and concurrent initialization, same-PID worker recovery, ordered concurrent writes, size rotation, shutdown queued behind a rotation, retention by count and total bytes, active-file preservation, disabled rotation, write failure without unhandled rejection, and flush/shutdown persistence.

Terminal isolation is verified in a child process, because the sink state is module-level: records emitted before initialization and after shutdown() produce empty stdout and stderr while earlier records remain in the file, an unusable log directory produces no output at all, and print mode still writes records to stderr — without creating a file, and unaffected by an unusable log directory. An isolated dev CLI run verifies that a post-initialization command error exits nonzero with no active log and one completed log.

[S6] Out Of Scope Copy Chapter

This change does not introduce per-record truncation, modify MCP/ACP/voice logging, add time-based retention, compress archives, change session/database retention, or remove the explicit rotation-disable option.

Tasks Copy Chapter

• T1: Implement unique active-file ownership and a serialized lifecycle queue — acceptance: concurrent initialization cannot target, leak, or clean another live active file, and file/count/total limits hold (covers: S2)
• T2: Add failure-safe flush, shutdown, and command exit lifecycle — acceptance: write/finalization failures do not reject globally or resume unsafe file writes, and CLI/TUI/worker exit paths close pending logs before termination (covers: S3; depends: T1)
• T3: Add and run focused tests and package typecheck — acceptance: all S5 cases pass from packages/cli and typecheck succeeds (covers: S5; depends: T1, T2)
• T4: Confine log records to the file sink unless print mode is active — acceptance: a record emitted after shutdown() or before init() produces no stderr output, while --print-logs still prints (covers: S4)
• T5: Keep the worker's file sink open across teardown — acceptance: a TUI quit writes the worker teardown records (instance disposal, bus unsubscribe) to the log file and nothing to stderr (covers: S4; depends: T4)

Compose Spec Loop Streak Recovery (`docs/compose/spec/loop-streak-recovery.md`) Copy Section

feature: loop-streak-recovery status: delivered updated: 2026-08-28 branch: feat/loop-streak-recovery commits: f02ee661a6..e5c9ba229b Copy Chapter

Loop Streak Recovery

Report Copy Chapter

What was built — Request-layer loop-streak crop behind experimental.loop_streak_recovery, aligned with turn recovery: no new user, lastUser/parentID unchanged, span persisted as an ignored+synthetic part on the existing parent user. Detection is thinking-primary (tools may drift). Spans re-apply on every later request until the feature is off. Cropped assistants stay in the DB; model-facing stream has no loop/recovery wording. max_span ceiling (default 64).

Verification — bun typecheck PASS; bun test test/session/loop-streak.test.ts PASS (24). Independent review of 9bab2c2a12 found 3 criticals + 3 mediums → fixed 5a597d938e → re-review PASS. Persisted-span follow-up after design critique that per-request re-detection breaks prefix stability. Follow-up review of f246a05e0: #1–#4 (re-apply suppressing text-loop, crop.kept, dead exports, key-range crop) confirmed and fixed in e5c9ba229b; #5 (span.toId === lastFinished.id "dead guard") rejected — empty-key lastFinished is not in entries, so the guard skips a new crop after the streak already broke. Second-pass review: #4's regression test used x_between, which sorts after a3 and never reached the streakKey clause — patched to an in-range id (a1narr) and mirrored for applyPersistedCrops.

Journey log — Suffix delete does not break Anthropic 20-block lookback by itself; real risks are deleting the anchor, a long recovery body, or middle-of-prefix edits. Streak key must be thinking-primary. Per-request re-detection is wrong: if the tail changes, the view flips, LCP truncates, and poison returns — detect once, persist the span as an ignored part on the parent user, re-apply every request. Never invent a Continue. user; transform.ts owns trailing-assistant Continue.

[S1] Problem Copy Chapter

Agent turns enter repetitive streaks: the same (or near-identical) thinking is replayed across consecutive assistant messages while tools only drift slightly. Current detectors often miss this shape:

• text-loop keys on visible text + tool inputs; pure thinking+tool loops with changing narration never trip it, and its recovery only appends a reminder.
• stepSignature / repeated-step nudge keys only on tool name+input and also only injects a reminder.
• Recovery never removes the poisoned history, so the next turn still sees the failed plan as few-shot context (observed in session ses_-ffe5fb84445ccffeZsPH2DWlj, where "I got stuck in a loop…" and identical 4935-char thinking replayed for many consecutive assistants).

Local DB evidence (message/part tables):

So "delete more than 20 Anthropic content blocks" is a normal case, not an edge case. That does not by itself break Anthropic lookback: lookback walks remaining blocks from the new breakpoint, and a suffix delete keeps the pre-loop write anchor within 1–2 blocks. The real cache risks are deleting the anchor, inserting a long recovery body, or middle-of-prefix edits.

[S2] Design Copy Chapter

Contracts Copy Section

1. Physical layer is audit-only. Loop recovery never removeMessages. DB keeps the full trajectory for replay, undo, and forensics.
2. Request-layer crop, no new user. Align with turn recovery (resume): do not create a Continue./recovery user. Reuse the existing parent user (lastUser unchanged → parentID matches resume). Persist the span as an ignored + synthetic text part on that user. Trailing-assistant repair stays in transform.ts.
3. Thinking is always in scope. Deletion unit is a whole assistant message (reasoning + text + tools + embedded results). No part-level surgery in v1.
4. Anchor is mandatory. The message immediately before the streak start is never removed (user or non-matching assistant).
5. No snapshot rollback. Dirty workspace after an edit streak is treated like an external file change; the model re-reads and re-plans.
6. Effectiveness > cache. Breaking the loop wins over a cache miss. Prefer prefix-safe crop; never keep poison thinking just to save cache.

Streak signature Copy Section

Per finished assistant message, build:

reasonHash = sha256(normalize(join(all reasoning part texts)))
toolSig    = stableStringify(tools in part-id order)

key = "reason:" + reasonHash     when reasoning is present
key = "tool:"   + toolSig        when only tools are present
key = ""                         when neither is present

Thinking is the loop source: crop eligibility keys on thinking alone so
slightly drifted tools still form one streak (MR-3931 shape). Tool-signature
keys are the fallback for thinking-less steps. Normalize reasoning like
normalizeForLoopDetection before hash. Do not rewrite stored parts;
hash is offline-only.

Detection Copy Section

Detect once per streak, not on every request. Re-detecting would flip the
request view, break the cache prefix, and re-introduce poison thinking after a
successful crop.

At the start of each loop iteration:

1. Re-apply every persisted span (extractAllCrops / applyPersistedCrops) from user-part metadata (kind: "loop_streak_crop"). Spans stay active for the life of the feature — including after the user sends a new message — so poison thinking cannot re-enter the request view.
2. Then, only when lastUser.id < lastFinished.id (continuing from a model step), detect a new streak on the already-cropped view:
   • Build keys for finished assistants.
   • Trigger when the last triggerCount (default 3) finished assistants share one key.
   • Walk backward while key matches; predecessor is the anchor (always kept).
   • Require span.toId === lastFinished.id.
   • On hit: crop the request view, persist an ignored + synthetic text part on the existing lastUser whose metadata.origin is { kind: "loop_streak_crop", fromId, toId, key, truncated }. Do not create a new user; do not reassign lastUser.
3. Clearing is explicit only: turn the feature off (next request returns to the full view). There is no auto-clear on user speech.

Persisting the span as an ignored part on the parent user gives: stable
prefix across later requests, restart survival, no new user/parentID, and no
model-facing loop wording. Cropped assistants stay in the DB.

Request crop Copy Section

kept     = messages with id < span.from OR id > span.to
         + force-include anchor (id < span.from, already kept)
span     = ignored synthetic part on the existing parent user

Later requests re-apply the same fromId..toId filter. No extra user is
inserted. If the cropped view ends on an assistant, transform.ts trailing-
assistant repair supplies Continue. on the wire only.

Invariants (assert in tests, log in prod):

• Kept prefix JSON equals original messages with span filtered out (no reorder, no field rewrite).
• Parts inside kept messages stay in part.id order.
• Tool_use/tool_result pairing is preserved because whole assistants are removed.
• Conversation after crop + recovery ends with a user message (Bedrock prefill safety).

Safety ceiling Copy Section

Ceiling exists only to stop a detector bug from nuking a multi-hour 600-message run. It is not a cache bound.

Cache audit (not a gate) Copy Section

On every crop, emit slog:

session_id, spanFrom, spanTo, anchorId,
nMessages, nParts, omittedBlocks, keptBlocks,
remainingSimilar, truncatedByCeiling,
cacheRisk: omittedBlocks > 20

omittedBlocks ≈ per cropped message: #reasoning + #text + 2×#tool.
Rough is fine; purpose is observability of "we routinely crop >20 blocks".

Do not skip crop when cacheRisk is true. Log only.

Provider notes Copy Section

Interaction with existing detectors Copy Section

• text-loop / text-ngram: keep as fallback when streak key does not fire (e.g. pure text loops with no tools/reasoning). If streak crop already ran for this turn, skip injecting another recovery user (loopStreakCropped).
• repeated-step nudge: keep; it fires on identical tools even when thinking differs. Streak crop keys on thinking when present, so both can independently surface related loops.
• try-best / doom_loop: unchanged (pause / permission). Independent of crop.

Recovery note content Copy Section

None in the model-facing stream. Span persistence uses an ignored +
synthetic part (text body irrelevant; not sent). No loop/recovery wording.
Counts/audit stay in slog. Wire-level trailing assistant uses transform.ts
Continue. only.

[S3] Out of Scope Copy Chapter

• Physical deletion / compaction of loop spans.
• Snapshot or filesystem rollback of edit streaks.
• Part-level tail surgery inside one assistant (interleaved R-T-R).
• Changing Anthropic breakpoint placement in transform.ts.
• Unifying try-best pause UX with streak crop.
• Cross-message "similar but not identical" clustering (fuzzy streak beyond exact key match).

Tasks Copy Chapter

• T1: Streak signature module — acceptance: pure functions compute reasonHash/toolSig/key from parts; unit tests cover empty reasoning, empty tools, order stability, normalize. (covers: S2)
• T2: Streak detector — acceptance: given a sequence of assistant keys, reports trigger, span [from,to], anchor predecessor; respects trigger_count and ceiling trailing-crop. (covers: S2; depends: T1)
• T3: Request cropper — acceptance: filters a message list by span without reorder/rewrite; creates no new user; invariants hold on fixture with parallel tools. (covers: S2; depends: T2)
• T4: prompt.ts integration — acceptance: after a finished step, experimental flag on, a 3× identical-thinking streak crops the next request and logs audit fields; flag off path unchanged. (covers: S2; depends: T3)
• T5: Regression tests — acceptance: MR-3931-shaped fixture (identical thinking, drifting tools) is cropped; pure tool-loop and pure text-loop still behave as before when keys differ; no crop when span would include the anchor. (covers: S2; depends: T4)
• T6: Align with turn recovery — acceptance: crop creates no new user; span persists as ignored synthetic part on the existing lastUser; lastUser/parentID unchanged; tests cover ignored-part extract + no-new-user. (covers: S2)

Compose Spec Mcp Readiness Hint (`docs/compose/spec/mcp-readiness-hint.md`) Copy Section

feature: mcp-readiness-hint status: delivered updated: 2026-10-20 branch: feat/mcp-readiness-hint commits: 113e3192..5d6de390 Copy Chapter

MCP Readiness Hint

Report Copy Chapter

What was built — Deferred MCP discovery reports configured servers, current connection status, and request-visible tool names/descriptions. Reminders compare against the latest reported server state, so unchanged failures stay quiet while recovery, disable/removal, and changed tool sets are reported. All reminders share one budget; diagnostics use existing preview and escaping helpers. Prompts contain concise status, tools, and search/use pointers.

No auxiliary mode state is written into user history. Existing real reminders and search/use calls provide deferral evidence; silent auto-mode sessions may re-evaluate when tools arrive. This accepts a cache change instead of altering original user messages for bookkeeping. MCP connection, permission, dispatch, registration, and storage implementations remain unchanged. One actor guard test now explicitly provides the Inbox and verifies actual delivery, removing a dependency on prior test initialization.

Verification — Run from packages/cli unless stated otherwise, for final code head 5d6de390:

• PASS — bun test test/session/prompt-effect.test.ts --timeout 30000: 135 passed, 3 skipped, 0 failed. Includes the full resume and MCP suites. The final assertion-only cleanup was rechecked with -t 'MCP auto mode can': 1 passed.
• PASS — bun test test/server/session-recovery.test.ts test/session/title-first-turn.test.ts test/session/tool-gate-cancel.test.ts test/server/session-select.test.ts test/tool/actor.test.ts test/tool/actor-send.test.ts test/tool/mcp-tool-search.test.ts --timeout 30000: 200 passed, 0 failed.
• PASS — bun run typecheck: exit 0 on the final code head.
• PASS — repository-root oxlint on the two changed MCP source files and the prompt-effect, mcp-tool-search, and actor tests: 0 errors and no new diagnostics. PRE-EXISTING LINT-141: 134 existing MCP-file warnings plus 7 existing actor-test warnings, compared by file, rule, message, and severity.
• PASS — repository root: git diff --check.
• PASS — independent MCP review and final scoped review of e5f2a933..5d6de390: spec compliance, correctness, and codebase consistency approved; no critical or blocking findings. The final documentation-only commit is excluded from the recorded range. Green remote CI is required before merge.

Journey log

• Readiness answers whether a server is connected; the authorized catalog answers which tools this request can use.
• Comparing with every historical state suppressed recovery. Compare with the latest state while ignoring volatile error details.
• Budget the complete set of reminders together, including status text and retractions, rather than allocating a full budget to every server.
• An auxiliary hidden mode marker caused ten CI failures by modifying original user messages during resume and related flows. It was removed entirely; no replacement storage mechanism was introduced. Auto-mode re-evaluation without actual reminder/call evidence is accepted.
• Another CI failure came from an actor test assuming Inbox was uninitialized. Explicit fixture setup and real delivery assertions fixed the test without changing actor behavior. Keep prompts and mechanisms simple; user configuration repair and cross-server ownership ambiguity stay out of scope.

[S1] Problem Copy Chapter

The model cannot tell MCP is not ready from the tool does not exist. Announcements were catalog-delta-driven, so “which MCPs exist / are connecting” was missing or delayed, and empty search reused one ambiguous sentence.

Readiness reminders must also stay accurate without accumulating repeated failures. A conversation-wide set of previously seen states suppresses recovery after connected → failed → connected. Ignoring disabled or removed servers leaves stale availability claims in history. Advertising a server's raw tool list can recommend tools that request permissions hide, while allocating a full context budget to every server multiplies the total reminder size.

[S2] Design Copy Chapter

Channels and timing Copy Section

MCP.readiness() is optional on the MCP service interface and never awaits connection settled. It reports configured server names, connection status, errors where applicable, and connected tools. resolveTools refreshes the model-facing snapshot on each model step; a search uses that step's snapshot. Connection changes during model generation are picked up at the next resolution, not pushed into an in-flight request.

Reminders are persisted synthetic text parts on the last user message through ensurePersistedUserSynthetic. They are appended only before that user's first assistant step. Already-sent message content is not rewritten by visible reminders. Deferred search/use definitions stay stable while deferral remains selected; an empty, silent auto-mode session can re-evaluate the mode when tools arrive. This preserves the existing prefix-cache contract. These reminders apply where deferred mcp_tool_search is exposed; the GPT/exec and direct-tool paths retain their existing behavior.

Latest-state comparison and bounded repetition Copy Section

Replay mcpReminder metadata in conversation order into the latest entry and the latest state per server. Compare the current semantic fingerprint with that server's latest reported state, rather than a set of every state ever seen. A fingerprint includes server identity, status, and sorted request-visible tool names. Hash the structured values to avoid delimiter collisions. Error text and tool ordering do not trigger a new reminder.

Previously announced servers absent from the current configuration receive a removed reminder. Repeated absence stays quiet. On disconnection, the new reminder briefly states that previously listed tools are unavailable; on a shrinking visible tool set, it names removed tools when the budget allows and otherwise uses a compact superseding statement. Actual MCP reminders and search/use calls provide the existing evidence for sticky deferral, including legacy mcpDeferredTools announcements. If none exists, auto may re-evaluate when tools arrive; a cache change in that case is accepted. Do not persist an auxiliary mode marker or modify an original user message merely to retain a cache decision. Compaction can discard that evidence and cause a fresh announcement, because it already rewrites the prefix.

Connection state and request-visible capabilities Copy Section

Connection state comes from MCP readiness and is never inferred from an empty search catalog. Before presenting tools to the model, intersect each connected server's tool names with the same catalog used by search and dispatch. That catalog applies request disables, permissions, agent allowlists, actor whitelists, executable checks, and local-name collision handling. List each surviving name once, use the catalog's description, and compute the displayed count from this filtered list. This does not change MCP registration or resolve ambiguous ownership between colliding server namespaces.

Consequently, a server can be connected with no tools available to this request. Do not claim the server itself exposes no tools. The reminder must never recommend a name that the current search/dispatch view excludes. The model receives names and short descriptions for discovery; complete parameter schemas remain on-demand through search.

One reminder budget per boundary Copy Section

Entry plus all changed-server reminders share min(floor(usable_input_tokens × 0.1), 20,000) estimated tokens. The existing unknown-context fallback remains 20,000; an exhausted known window has zero budget. Deduct each emitted part, including a separator allowance, then divide the remaining budget among remaining changed servers.

Count the entire text, including wrappers, status, instructions, diagnostics, and retractions. Connected tools fall back from descriptions to names, then a truncated list with a search hint, then compact status. Diagnostic previews and large retraction lists are bounded. Search-miss diagnostics reuse the same normalization and harness-tag escaping as reminders. If even a compact reminder cannot fit, emit no part and do not mark that outcome as delivered. Search still covers the complete authorized catalog.

Keep the mechanism and prompts simple Copy Section

Only report the server's current status, a short diagnostic when useful, and available tool names/descriptions with a search/use pointer. Avoid repeated instructions telling the model what to infer from a failure or how to work around the user's MCP setup. Ordinary ambiguity in invalid or conflicting MCP configuration is outside this amendment; preserve existing registration behavior.

Verification boundaries Copy Section

Use the real prompt serialization path with controlled MCP service snapshots to inspect what reaches the test model endpoint. Cover state recurrence, changing error details, disable/removal before and after connection, restored tool sets, request/permission/agent filtering, and a shared multi-server budget. Unit tests cover rendering, tiny/zero budgets, long errors and retractions, fingerprints, and escaped readiness/search output. Prompt tests also cover auto-mode re-evaluation without auxiliary message parts, legacy announcement evidence, and duplicate names within a server. Resume, cold-tool initialization, scheduled prompts, and title tests must not acquire auxiliary MCP bookkeeping parts in their original user messages. The actor guard test must exercise actual Inbox delivery independently of prior test initialization. Existing MCP integration tests protect prefix stability, sticky deferral, dispatch, lifecycle, and result handling. These tests establish context correctness; they do not measure a real model's tool-selection success rate.

[S3] Out of Scope Copy Chapter

• Changing FIRST_TURN_WAIT or connection lifecycle.
• Mid-turn ambient push into history.
• Full JSON Schema validation of mcp_tool_use arguments.
• Consuming MCP.ToolsChanged as a dirty signal.
• Extending readiness reminders to GPT/exec or non-deferred tool exposure.
• Empirical evaluation of real-model tool-selection success rates.
• Persisting auxiliary cache-mode state when there is no real MCP reminder or call.
• Repairing user MCP configuration, changing normalized-name registration ownership, or distinguishing all ambiguous cross-server name collisions.

Tasks Copy Chapter

• T4: Compare the latest server state — acceptance: repeated failures and error-detail changes add no reminder; failure/recovery and tool-set recurrence each reach the model (covers: S2)
• T5: Report unavailable and removed servers — acceptance: pending, disabled, and removed transitions invalidate prior tool availability once; pending-server removal is covered; initially disabled servers remain quiet (covers: S2)
• T6: Align advertised tools with request authorization — acceptance: request disables, permissions, and agent allowlists hide the same tools from reminders and search, with matching visible counts (covers: S2)
• T7: Enforce a shared reminder budget — acceptance: multi-server serialized reminders remain within one budget; long diagnostics, retractions, and zero budgets are covered without marking omitted outcomes delivered (covers: S2)
• T9: Remove auxiliary mode persistence — acceptance: auto mode may re-evaluate without real announcement/call evidence; original user messages remain unchanged across resume, cold initialization, scheduled prompts, and title handling (covers: S2)
• T10: Keep diagnostics safe and prompts concise — acceptance: search-miss names/errors use existing escaping and preview bounds; reminders contain status, tools, and a brief search/use pointer (covers: S2)
• T11: Make the actor send guard fixture deterministic — acceptance: the test proves a subagent may send via exec using actual inbox behavior, independent of prior app-runtime initialization (covers: S2)
• T8: Verify and independently review the integrated feature — acceptance: focused MCP suites and typecheck pass, lint introduces no diagnostics, and spec compliance/correctness/codebase consistency have no unresolved critical findings (covers: S2; depends: T4, T5, T6, T7, T9, T10, T11)

Compose Spec Mcp Tool Search (`docs/compose/spec/mcp-tool-search.md`) Copy Section

feature: mcp-tool-search status: completed updated: 2026-10-12 branch: feature/mcp-tool-search commits: c946f4c215aaf326036342a8c3dec6ad12d8772a..HEAD Copy Chapter

MCP Tool Lazy Loading

[S1] Problem Copy Chapter

Sending every complete MCP function definition to the model consumes context before the task needs any MCP capability. Hiding all metadata, however, leaves the model unable to discover capabilities it does not already know exist. OpenAI defer_loading is provider-specific and cannot generalize to Claude, Gemini, DeepSeek, MiMo, or compatibility gateways.

[S2] Deferral Mode Copy Chapter

The design follows Claude Code's deferred tools + Tool Search. MIMOCODE_MCP_TOOL_SEARCH selects the mode:

• true / 1 (default; also any unrecognized value): always defer.
• auto: defer MCP tools once their estimated definition size (name, description, transformed schema) exceeds 10% of the model context window; unknown windows assume 200,000 tokens.
• auto:N: same, with an N% threshold.
• false / 0: never defer; every effective MCP definition is exposed directly.

Codex-mode models (GPT family except GPT-OSS, or a codex harness) always defer. The decision is recomputed on every model step from the request-authorized MCP set, so it tracks servers connecting, disconnecting, or being filtered.

[S3] Deferred Catalog And Search Copy Chapter

When deferral applies, at least one effective MCP tool exists, and the model supports function calling, the request exposes one ordinary function named mcp_tool_search with a static description, so tool definitions stay byte-stable for the provider prefix cache.

The catalog (built from MCP.tools(), i.e. each server's tool listing) is announced to the model as a synthetic <system-reminder> text part appended to the last user message, never as a new user message, inside a tool result, or in the system prompt. The first announcement lists every deferred tool as - name: description preview; later ones carry only additions and removals relative to what earlier reminders announced. Each reminder part persists its delta in metadata.mcpDeferredTools, and the announced set is replayed from those parts, so compaction (which drops them) triggers a full re-announcement. Announcements are budgeted to 10% of the usable input window (capped at 20,000 tokens), falling back to names only and then to a truncated list; search always covers the complete catalog. System prompts declare that <system-reminder> content is harness-injected environment information.

The catalog contains only tools that survive request disables, permissions, agent allowlists, actor whitelists, executable checks, and local-name collision handling. External text — MCP names, descriptions, schemas, and MCP tool results — has <system-reminder>, <functions>, <function>, and <available-deferred-tools> tags escaped so it cannot forge harness content.

mcp_tool_search accepts query and optional max_results (default 5, max 20):

• select:a,b loads the named tools exactly (case-insensitive).
• A query equal to a tool name loads that tool.
• Otherwise a cached local BM25 index over names, descriptions, and recursive parameter names/descriptions ranks results; +term requires term in the tool name.

The result returns the matched tools' complete JSON Schema definitions inside a <functions> block, so the model learns parameters from the result. The literal name tool_search is intentionally avoided because OpenAI Responses adapters reserve it for the native provider protocol.

[S4] Conversation-Scoped Loading Copy Chapter

A successful search persists validated matched names in ordinary tool-result metadata. On every subsequent outer-loop step, MiMoCode scans completed searches across the conversation (newest first, bounded at 32 tools) and exposes those MCP definitions through the AI SDK activeTools subset. A loaded tool stays callable across user turns as long as it is still request-authorized; compaction drops older searches together with their messages. Model-visible output is never trusted as activation state.

[S5] Execution Safety Copy Chapter

All MCP executors remain in the full local tool map so existing permission checks, actor whitelists, plugin hooks, metrics, result normalization, truncation, attachments, cancellation, and MCP client dispatch are preserved. Before any side effect, the MCP wrapper rejects a call to an unauthorized tool, and — while deferral applies — a call to a tool not yet loaded, instructing the model to use mcp_tool_search. Search matches become callable only on the next outer-loop step. Local tools win on callable-name collisions.

[S6] Provider And ToolScript Behavior Copy Chapter

The mechanism uses an ordinary function tool and does not depend on OpenAI provider tools or defer_loading. Models without function calling receive neither MCP discovery nor MCP definitions. In Codex mode the outer surface stays exec; exec scripts reach every request-authorized MCP tool through ALL_TOOLS without a search round-trip, and mcp_tool_search is excluded from scripts.

[S7] Testing Boundaries Copy Chapter

Unit coverage: mode parsing, auto threshold, names-only catalog and truncation, select: / exact-name / +required queries, BM25 ranking and cache invalidation, <functions> rendering, limits, and Codex mode resolution. Integration coverage: GPT requests expose only exec; by default non-GPT requests hide MCP schemas, load searched tools on the next step, and keep them loaded in the next user turn; false exposes MCP tools directly; unloaded calls fail recoverably; non-tool-call models omit both discovery and definitions; MCP success/error normalization is unchanged.

[S8] Out Of Scope Copy Chapter

Semantic embeddings, MCP server summaries, MCP connection lifecycle, MCP naming, and provider-native tool_reference blocks.

Tasks Copy Chapter

• T1: Replace provider-native Tool Search with ordinary mcp_tool_search and cached local BM25 discovery.
• T2: Separate registered executors from model-visible activeTools and activate only searched matches.
• T3: Preserve MCP execution safety while removing ToolScript catalog leakage and inactive-call bypasses.
• T4: Align with Claude Code: on by default with an opt-in auto threshold, names-only deferred list, select: / +required queries, schema-bearing results, conversation-scoped loading.

Compose Spec Mcp Tool Use (`docs/compose/spec/mcp-tool-use.md`) Copy Section

feature: mcp-tool-use status: delivered updated: 2026-10-20 branch: feat/mcp-tool-use commits: 43c9daa20..bfdfd77ee Copy Chapter

MCP Tool Use

Report Copy Chapter

What was built — In deferred MCP mode, searched tools no longer join activeTools. A fixed native
mcp_tool_use tool ({ name, arguments }) is exposed next to mcp_tool_search and dispatches into the
existing MCP execution pipeline, so provider-facing tool definitions stay byte-stable across searches and
the prompt-cache prefix survives. Permission, plugin hooks and metrics (including the processor error
metric) use the real MCP tool name; the tool part and gate key are mcp_tool_use.

Arguments are pre-checked (object + own top-level required properties) after tool.execute.before;
failures return a recoverable error with the tool's <functions> schema. Unknown names point at
mcp_tool_search. Direct calls to deferred tools are rejected after the actor-whitelist check, with a
mcp_tool_use hint (or an exec hint on the GPT toolset). The TUI renders dispatched calls as the
underlying tool. Harness prompts (anthropic, gemini, beast) and search/reminder wording were updated.

Verification

• bun run typecheck (packages/cli): PASS.
• bun test on mcp-tool-search, prompt-effect, llm, tool-fail-cascade, tool-gate-cancel, tool-script: 266 pass / 3 skip / 0 fail after review fixes; deferred subset re-run after the last fix: PASS.
• Full bun test (packages/cli): 6092 pass / 66 fail under full-suite load; failing files (project, vcs, project-id, memory/paths, tool-gate-cancel, tool-fail-cascade, actor) pass in isolation on branch and main — PRE-EXISTING load flakes.
• Independent review: no critical findings; important/minor items fixed and re-reviewed.

Journey log

• Codex/GPT models defer MCP tools but reach them only via exec; older tests that searched then called a deferred tool directly with a GPT model exercised an unreachable path and were moved to the non-GPT model.
• The processor's executeTool checks the persisted part's tool name, so dispatched calls must batch under mcp_tool_use, not the MCP key.
• No JSON Schema validator is a direct dependency and the lockfile must not change, so argument checking stays structural and full validation is left to the MCP server.

[S1] Problem Copy Chapter

With MCP Tool Search (deferred mode), mcp_tool_search returns the schema of matched tools and
the next request adds those tools to activeTools (session/prompt.ts, loadedMcpTools, capped by
MCP_TOOL_SEARCH_MAX_LOADED). The provider-facing tool definitions therefore change after every
search. Tool definitions sit at the front of the prompt-cache prefix, so each search invalidates the
cached prefix for the rest of the conversation.

[S2] Design Copy Chapter

Keep the provider-facing tool list byte-stable for the whole session in deferred mode by routing every
deferred MCP call through one fixed dispatcher tool.

• mcp_tool_use tool. A native tool call (not text/XML) with parameters
  { name: string, arguments?: object }. It is exposed exactly when mcp_tool_search is exposed
  (deferred mode, non-GPT toolset, model supports tool calls) and placed in activeTools next to it.
  It is built in SessionPrompt (not the registry) so it can reuse the request-scoped MCP executor.
• No more loading. In deferred mode, searched tools are no longer added to activeTools;
  loadedMcpTools and MCP_TOOL_SEARCH_MAX_LOADED are removed. mcp_tool_search keeps returning the
  <functions> schema block (appended to history, so it never touches the cached prefix) and keeps its
  matchedTools metadata.
• Dispatch. mcp_tool_use resolves name against the request's searchable MCP catalog and runs the
  same MCP execution pipeline as a direct call (availability, actor whitelist, tool.execute.before/after
  plugin hooks with the real MCP tool name, permission ask keyed by the real tool name, truncation,
  metrics with the real tool name, progress metadata). The processor batch/gate key is mcp_tool_use,
  matching the persisted tool part. Its result is the underlying tool's result.
• No search prerequisite. Any request-authorized deferred MCP tool can be called without a prior
  search (search is a context optimization, not an authorization boundary, as with exec).
• Errors (recoverable, loop continues).
  • Unknown or unauthorized name → error naming the tool and telling the model to use
    mcp_tool_search.
  • arguments not an object, or missing a top-level required property of the tool's input schema →
    error that includes the tool's full schema in a <functions> block so the model can retry.
    (Full JSON Schema validation is left to the MCP server; no new validator dependency.)
• Direct calls in deferred mode. A direct call to a deferred MCP tool name is rejected with an error
  telling the model to call it through mcp_tool_use.
• Guidance text. The mcp_tool_search description, the deferred-tools <system-reminder>, and the
  search result tell the model to call tools via mcp_tool_use with { name, arguments }.
• Provider filter. llm.ts resolveTools exempts mcp_tool_use from permission-disabled filtering
  when it is active, as it does for mcp_tool_search (real-tool permission is enforced at dispatch).
• TUI. A mcp_tool_use part renders as the underlying tool: name from input.name, arguments from
  input.arguments.
• Non-deferred mode (MIMOCODE_MCP_TOOL_SEARCH=false, or auto below threshold) and the GPT/exec path
  are unchanged.
• Stability across MCP churn (amendment).
  • An empty catalog counts as deferred: unless mode is never, mcp_tool_search/mcp_tool_use are
    exposed even before any MCP server connects or is configured, so the first server to arrive never
    changes the tool list.
  • Deferral is sticky per conversation: once history shows a deferred-tools announcement or a search/use
    call, auto stays deferred even if the catalog drops under its threshold or empties. In auto, an
    empty first catalog persists a "no deferred MCP tools yet" announcement as that evidence.
  • Deferred-tools announcements are appended only while the last user message is the tail of the
    conversation; changes that happen mid-turn are announced on the next turn, so earlier messages are
    never rewritten. mcp_tool_search always searches the live catalog meanwhile.

[S3] Out of Scope Copy Chapter

• XML/text-embedded tool calls.
• Full JSON Schema validation of arguments.
• Changing when deferral is decided (shouldDeferMcpTools) or the reminder delta mechanism.
• Web/desktop app renderers.

Tasks Copy Chapter

• T1: Add MCP_TOOL_USE_ID, its parameters/description, and an argument pre-check helper to tool/mcp-tool-search.ts; update search description/reminder/result wording; remove MCP_TOOL_SEARCH_MAX_LOADED — acceptance: unit tests for the pre-check (non-object, missing required, valid) and wording pass (covers: S2)
• T2: Build the mcp_tool_use dispatcher in session/prompt.ts, drop search-based loading, reject direct deferred calls, exempt it in llm.ts — acceptance: session tests show the tool list is identical before and after a search, a mcp_tool_use call completes with the MCP result, unknown name / missing required args produce recoverable errors, direct deferred calls are rejected (covers: S2; depends: T1)
• T3: Render mcp_tool_use parts in the TUI as the underlying tool — acceptance: typecheck passes and the part shows the MCP tool name and its arguments (covers: S2; depends: T1)
• T4: Update harness prompt text mentioning deferred MCP tools — acceptance: prompts reference mcp_tool_use where loading via search was implied (covers: S2)

Compose Spec Memory Prompt Decouple (`docs/compose/spec/memory-prompt-decouple.md`) Copy Section

feature: memory-prompt-decouple status: delivered updated: 2026-09-14 branch: feat/memory-prompt-decouple commits: e485a2a..9780b2e Copy Chapter

Memory Prompt Decouple From Checkpoint

Report Copy Chapter

What was built — # Memory system is now always injected for main/peer
actors. MIMOCODE_DISABLE_CHECKPOINT only filters checkpoint-write subsections
(checkpoint.md / task progress paths, writer-as-curator, Active recall,
Four-vs-Two wording). Project MEMORY.md, global MEMORY.md, notes.md scratchpad,
subagent return format, and search-first rules stay on so embedders that close
checkpoint (e.g. Desktop) still teach the model where memory lives.

Verification —

• bun run typecheck from packages/cli — PASS
• bun test test/session/llm-system-prompt.test.ts test/tool/checkpoint-tool-description.test.ts test/flag/disable-checkpoint-flag.test.ts test/session/prune.test.ts — PASS (30 pass / 0 fail; llm-system-prompt 6/6)

Journey log

• Desktop sets MIMOCODE_DISABLE_CHECKPOINT=1 for checkpoint bugs; engine previously dropped the whole memory system prompt with that flag — wrong coupling.
• Existing test MIMOCODE_DISABLE_CHECKPOINT=true — memory instructions are not appended encoded the old coupling; inverted to core-on + ckpt-extras-off.
• Flag-on test must not assert absence of the string checkpoint-writer — base agent.prompt mentions that agent name; assert memory-system-specific copy instead.
• memory.disable_write remains a separate write kill-switch; this change does not couple prompts to it.
• After engine-pin bump Desktop gets memory paths while keeping checkpoint off; do not also copy # Memory system into desktop-base.

[S1] Problem Copy Chapter

# Memory system is injected by buildSystemArray only when
servesCheckpoint && !Flag.MIMOCODE_DISABLE_CHECKPOINT
(packages/cli/src/session/llm.ts). Desktop embeds the engine with
MIMOCODE_DISABLE_CHECKPOINT=1 because checkpoint had production bugs, so the
entire memory write/read contract disappears from the model: no MEMORY.md /
notes.md / global paths, no when-to-write rules, no search-first reflex.

Memory itself is a file system + FTS + memory tool. Checkpoint is one
writer of those files. Coupling the prompt to the checkpoint flag is wrong:
closing checkpoint for writer/rebuild bugs must not erase memory ownership
paths.

[S2] Design Copy Chapter

Contract: for main/peer actors (servesCheckpoint), # Memory system is
always injected. MIMOCODE_DISABLE_CHECKPOINT only toggles the checkpoint
write subsections inside that block, not the block itself.

Implementation choke points:

1. session/llm.ts buildSystemArray — injection if is servesCheckpoint
   only; buildMemoryInstructions(projectID, memoryRoot) internal
   checkpointEnabled splits ckpt extras.
2. buildMemoryInstructions / injection-site comments state always-on for
   main/peer; flag only narrows content.
3. tool/checkpoint-description.ts — unchanged. Base memory.txt stays;
   only memory.checkpoint.txt extra stays gated.
4. Session recall reminder (session/prompt.ts hasMemoryOrTasks) — already
   independent of the checkpoint flag; no change.
5. memory.disable_write remains the write switch (separate axis); this
   feature does not couple prompts to it.

Tests (engine): llm-system-prompt.test.ts flag-on case asserts core
memory present (# Memory system, MEMORY.md paths, Notes scratchpad, Subagent
return format, When to Edit, search-first) and ckpt extras absent (Active
recall, sole curator, Session checkpoint, session checkpoint.md path). Default
on path still expects Active recall + writer ownership. system-spawned actors
still receive no memory block.

[S3] Out of Scope Copy Chapter

• Re-enabling desktop checkpoint / fixing historical checkpoint bugs.
• Changing memory.disable_write semantics or memory-path-guard.
• Injecting memory system into system-spawned writers (they must keep using
  checkpoint task paths).
• Desktop prompt assets (desktop-base) — engine supplies the block after pin
  bump; desktop should not duplicate it.

Native memory paths Copy Chapter

Memory reads and FTS reconciliation support Windows drive, UNC and mixed-separator
paths as well as POSIX paths. memory/paths.ts normalizes separators only in the
layout-matching representation shared by parsePath and parseCcPath; native
filesystem paths remain the FTS identity and search result path. Nested keys use
/ for type detection. POSIX filenames containing backslashes keep their literal
characters. This leaves checkpoint gating and memory write permissions unchanged.

Desktop regression coverage is tracked by engine-runtime TP-R6-06: path parsing,
native buildPath round-trips, filesystem reconciliation/search, fingerprint hits,
updates/deletes, and the embedded Node memory tool.

Tasks Copy Chapter

• T1: llm.ts always inject # Memory system when servesCheckpoint; flag only filters ckpt extras — acceptance: with MIMOCODE_DISABLE_CHECKPOINT=true, main-agent system contains # Memory system + project MEMORY.md + notes.md and omits checkpoint-writer ownership / Active recall (covers: S2)
• T2: Update buildMemoryInstructions comments to match always-on contract — acceptance: comments no longer claim the whole block is skipped when checkpoint is off (covers: S2; depends: T1)
• T3: Invert/extend llm-system-prompt.test.ts for flag-on vs flag-off content split — acceptance: tests cover always-on core + ckpt-gated extras + system-spawned exclusion; suite green (covers: S2; depends: T1)
• T4: bun typecheck + bun test packages/cli/test/session/llm-system-prompt.test.ts from worktree — acceptance: typecheck clean; target tests pass (covers: S2; depends: T3)

Compose Spec Move Drive Mimo To Repository Skill (`docs/compose/spec/move-drive-mimo-to-repository-skill.md`) Copy Section

feature: move-drive-mimo-to-repository-skill status: delivered updated: 2026-08-23 branch: codex/move-drive-mimo commits: b7ff175e..dca3d16f Copy Chapter

Move Drive MiMo to a Repository Skill

Report Copy Chapter

What was built — Moved the complete drive-mimo skill from the built-in bundle to the repository-level .mimocode/skills/drive-mimo/ path. Removed its built-in README entries and bundled-only TUI localization metadata while preserving the skill behavior and helper script. Updated the helper invocation note to match the repository-managed executable bit.

Verification — bun ci PASS; bun test test/skill/skill.test.ts test/skill/bundle-discovery.test.ts test/skill/builtin.test.ts test/skill/skill-description.test.ts PASS (34 tests); bun typecheck PASS; scope and git diff --check checks PASS. Independent review PASS for spec compliance, correctness, and codebase consistency.

Journey log — The initial review found a translated README table entry missed by the first cleanup; it was removed and covered by re-review. A repository discovery regression test was added to assert bundled remains unset for project skills.

[S1] Problem Copy Chapter

drive-mimo is packaged and presented as a MiMoCode built-in skill even though it is repository-specific tooling for exercising MiMoCode. This makes it available outside the repository and gives it bundled-only TUI metadata.

[S2] Design Copy Chapter

Move the complete drive-mimo skill directory to the repository root at .mimocode/skills/drive-mimo/, where the project skill discovery path loads it as a non-bundled repository skill. Remove the built-in bundle copy and bundled-only README and localization entries. Preserve the skill name, frontmatter, behavior, helper script, and normal slash invocation behavior; update documentation where the repository-managed file mode differs from the extracted bundle.

[S3] Out of Scope Copy Chapter

Do not change the skill behavior, helper behavior, skill discovery implementation, or other built-in skills. Documentation corrections required by the new repository-managed layout are in scope.

Tasks Copy Chapter

• T1: Relocate the skill files to .mimocode/skills/drive-mimo/ — acceptance: the repository contains the complete skill and no built-in bundle copy (covers: S2)
• T2: Remove bundled-only documentation and localization references — acceptance: README and TUI locale catalogs no longer identify drive-mimo as bundled (covers: S2)
• T3: Verify repository discovery and absence from the built-in bundle — acceptance: focused tests/checks show the skill is discovered from the project path with bundled unset and absent from the extracted built-in bundle (covers: S2)

Compose Spec Npm Fds Launcher (`docs/compose/spec/npm-fds-launcher.md`) Copy Section

feature: npm-fds-launcher status: delivered updated: 2026-10-13 branch: feat/npm-fds-launcher commits: 8e1df4ab..8884c6fd Copy Chapter

npm FDS Launcher

Report Copy Chapter

What was built — @mimo-ai/cli is now a thin launcher instead of a hub of 12 optionalDependencies platform packages. mimo.js detects one target (os/arch/AVX2/musl), uses MIMOCODE_BIN_PATH or package-local vendor/mimo[.exe], otherwise downloads exactly one version-pinned FDS archive (releases/vX.Y.Z/<target>.{tar.gz|zip}) into vendor/, and forwards argv with inherited stdio. postinstall prefetches best-effort and never fails install. FDS failure exits 1 with the real error and a recommended curl/irm native install. npm uninstall deletes the binary with the package directory. Wrapper packaging drops optionalDependencies. READMEs mark npm as limited support: README.md / README.zh.md only recommend curl/irm; README_npm.md recommends the native installer over npm install @mimo-ai/cli and still names the package for users who need it.

Upgrade is package replace, not tree migration: no leftover-node_modules fallback. If the first run cannot reach FDS, it says so and points at curl/irm.

Verification — bun run typecheck — PASS. bun test ./test/installation/launcher.test.ts ./test/installation/launcher-bin.test.ts ./test/installation/postinstall.test.ts in packages/cli — PASS, 29 tests (12-target matrix, URL pin + MIMO_FDS_BASE, vendor hit offline, FDS fetch via stub, sha256 match/mismatch/skip-when-absent, argv/exit codes, postinstall best-effort, FDS-down error + curl/irm hint). Local E2E: packed @mimo-ai/[email protected] tgz (7.3 kB) → npm install on macOS arm64 → postinstall pulled releases/v0.1.15/mimocode-darwin-arm64.zip from production FDS into vendor/mimo → mimo.js --version printed 0.1.15; second run reused vendor. Production FDS probe: missing objects and unpublished *.sha256 return 404. Independent review: go after spec/checksum/comment fixes (a90a1057) and typecheck fix (8884c6fd).

Journey log

1. Multi-download is not postinstall picking wrong — npm already fetched every os/cpu match; baseline/musl siblings share those fields.
2. Do not put the launcher binary under Global.Path.cache (wiped on CACHE_VERSION).
3. Upgrade = uninstall old package + install new; do not paper over orphans with legacy node_modules lookup.
4. Bun.spawnSync deadlocks tests that also Bun.serve in-process — use async spawn around local stubs.

[S1] Problem Copy Chapter

npm install @mimo-ai/cli pulled several platform packages (~130 MB each) on Linux x64 because optionalDependencies matching cannot distinguish baseline vs AVX2 or musl vs glibc (os/cpu identical; libc was unset). Users saw multiple huge downloads while only one binary was used.

[S2] Delivered design Copy Chapter

Package Copy Section

• Name @mimo-ai/cli, bin: { "mimo": "./mimo.js" }, version = release version, "type": "module", engines.node >=20.10.0.
• No optionalDependencies. No npm platform packages — binaries ship as FDS/GitHub archives only.
• Shipped files: mimo.js, launcher.js, postinstall.mjs.

Runtime resolution (`mimo.js`) Copy Section

1. MIMOCODE_BIN_PATH → spawn that.
2. /vendor/mimo or vendor/mimo.exe → spawn that.
3. Else download from FDS into vendor/, then spawn.
4. On failure: exit 1 with the error and recommended curl -fsSL https://mimo.xiaomi.com/install | bash (Windows: irm https://mimo.xiaomi.com/install.ps1 | iex).