@code-yeongyu/senpi 2026.9.21-2 → 2026.9.22

package/docs/providers.md

@@ -22,6 +22,7 @@ Use `/login` in interactive mode, then select a provider:
 - GitHub Copilot
 - xAI (Grok/X subscription)
 - OpenRouter (OAuth-minted API key billed from OpenRouter credits)
+- Kimi Code (kimi.com / kimi.ai subscriptions)
 - Radius
 - Cursor (Pro/Ultra/Teams) — authentication only for now, see below
 
@@ -136,6 +137,13 @@ Upstreams that require explicit cache breakpoints get `cache_control` blocks thr
 
 senpi sends `prompt_cache_key` (set to the session id) on Moonshot requests. Kimi documents the field as required for the Kimi Code Plan and recommended for any multi-turn agent ([Kimi context caching](https://platform.kimi.ai/docs/guide/use-context-caching-feature-of-kimi-api)). Kimi reports cache hits as a flat `usage.cached_tokens` field, which senpi parses as cache-read tokens.
 
+### Kimi Code
+
+- Run `/login kimi-coding`, then select **Sign in with Kimi Code** and pick the service that hosts your account: **Mainland China (kimi.com)** or **Outside mainland China (kimi.ai)**
+- The region is stored with the credential; token refresh and model requests follow it (`auth.kimi.ai` + `api.kimi.ai/coding` for international accounts), so a `.ai` login keeps working after restarts and env changes
+- **Use an API key** asks the same region question and routes `KIMI_API_KEY` requests by it; `KIMI_CODE_REGION=global` (or `mainland-cn`) answers it for headless setups
+- `KIMI_CODE_OAUTH_HOST` / `KIMI_OAUTH_HOST` still override the auth host for new logins and for credentials saved before regions existed; a host other than the two official ones is kept verbatim and needs a `models.json` `baseUrl` for inference
+
 ### Radius
 
 Radius is a dynamic `pi-messages` gateway. `/login radius` stores OAuth tokens in `auth.json`; the gateway catalog is refreshed independently and cached in `models-store.json`. Custom Radius gateways can be declared in `models.json` with `"oauth": "radius"` and a gateway `baseUrl`.
@@ -286,7 +294,7 @@ senpi
 | Fireworks | `FIREWORKS_API_KEY` | `fireworks` |
 | Together AI | `TOGETHER_API_KEY` | `together` |
 | Baseten | `BASETEN_API_KEY` | `baseten` |
-| Kimi For Coding | `KIMI_API_KEY` | `kimi-coding` |
+| Kimi For Coding | `KIMI_API_KEY` (+ `KIMI_CODE_REGION`) | `kimi-coding` |
 | MiniMax | `MINIMAX_API_KEY` | `minimax` |
 | MiniMax (China) | `MINIMAX_CN_API_KEY` | `minimax-cn` |
 | Qwen Token Plan (existing catalog) | `QWEN_TOKEN_PLAN_API_KEY` | `qwen-token-plan` |

package/docs/rpc.md

@@ -207,7 +207,13 @@ are what this decision encodes; the other two are what a client must not undo el
   `ensureHost` records a `writer: { pid, startTime }` stamp in its pidfile and stops the host it names only when
   that stamp is this process (the start time is what keeps a recycled pid from inheriting the right). A pidfile
   written by anyone else fails the ensure with `HostEnsureRefusedError { reason: "foreign_writer" }` and the host
-  keeps running.
+  keeps running. That refusal is about signalling, so it holds only while something still accepts connections at
+  the public path: a registration that names a live process whose entry is GONE (it was replaced by another socket
+  and the replacement later exited) or whose entry nobody listens behind (a dead listener left it, a successor's
+  rename never landed) describes a generation nobody can reach, and binding a fresh generation to the free path
+  touches nothing of it. The ensure then starts one beside it, numbered after the stranded generation, which
+  keeps its registration until it exits; refusing there locked every client out until that process happened to
+  end (#1936). A named pipe has no entry to lose, so win32 keeps refusing.
 - **I2 - compatibility is protocol version + capabilities, never semver equality.** An ordinal that cannot be
   compared (a build without git metadata, a host that reports none) is EQUAL, and since a handoff requires
   STRICTLY greater, such a pair attaches instead of upgrading.
@@ -238,10 +244,11 @@ client's sessions. A GENERATION HANDOFF replaces the process while its sessions
    running host keeps serving.
 3. `handoffHost` then registers the successor (its own `generations/<instanceId>/host.pid`, the pointer
    moved onto it, and `settings.json { socket, generation }`) and sends
-   the predecessor SIGUSR1 = DRAIN: stop accepting, keep every connection already proxied, park each
-   retained session as soon as its turn settles, and exit through the ordinary idle path. Attached clients
-   see `session_closed { reason: "handoff_parked" }` for a parked session and reopen it with
-   `open_session { sessionPath }`.
+   the predecessor SIGUSR1 = DRAIN: stop accepting, announce `host_superseded` to every connection,
+   park attached and unattached sessions as their turns and requests settle, then exit independently of
+   connection occupancy. Clients see `session_closed { reason: "handoff_parked", sessionPath }` before
+   their connection closes and reopen with `open_session { sessionPath }` on the successor. Losing
+   ownership of the public socket triggers the same sequence even if SIGUSR1 never arrives.
 
 Two guards decide whether a handoff is attempted at all, and both fail closed:
 
@@ -485,7 +492,7 @@ exposing session content. The one exception is `session_closed` and `session_par
 `kind: "worker"`: they are delivered only to
 the connections attached to that session, so machine-driven work neither appears in nor disappears from a client that never
 asked for it. Every other lifecycle record, and every record of an `interactive` session, keeps today's broadcast. Host-level
-records (`host_stalled`, `host_memory_pressure`) are broadcast the same way and describe the host process rather than a
+records (`host_superseded`, `host_stalled`, `host_memory_pressure`) are broadcast the same way and describe the host process rather than a
 session. Correlated responses and dialog extension UI
 requests (select, confirm, input, and editor) are requester-only; other extension UI state records go to the session's
 attached connections. To observe a foreign session, open it by its existing
@@ -599,6 +606,48 @@ internal directory. The supervisor also exports `SENPI_RPC_HOST_WATCH_PPID` as a
 set only by the supervisor: a host started any other way (plain `senpi --mode rpc --listen …`, embedders, hand-started
 hosts) sees neither variable and is unaffected. A host whose supervisor is alive is never touched by this binding.
 
+### Supersession lifecycle: `host_superseded`
+
+Before parking for a generation handoff, the old host sends every connected client one unsolicited record:
+
+```json
+{"type":"host_superseded","instanceId":"old-host-uuid","generation":0,"successor":{"socket":"/tmp/agent/rpc.sock"}}
+```
+
+`instanceId` and `generation` identify the OLD host, matching its `get_protocol_info` response. `successor.socket`
+identifies the public socket, never the supervisor's private hop. `successor` is `null` when a drain is requested
+without a known replacement. This record has no request id or session handle; older clients can ignore it.
+
+1. The announcement is queued on every connection before handoff parking changes any session.
+2. Every parkable session, attached or unattached, is parked immediately. A session is **parkable** when no agent
+   run, bash/tool execution, compaction, queued session work, or in-flight host request remains. Accepted opens,
+   binding creation, close requests, and steer delivery must finish. This is the ordinary busy predicate with
+   **durable wake-source holds excluded**: persistent monitors, scheduled continuations and goal-loop holds do not
+   pin an old generation. They resume from the persisted session when reopened, as after a restart. Ordinary idle
+   eviction retains its broader activity predicate, including all wake sources.
+3. Active sessions keep serving their existing connections and park when their turns and requests settle. Each
+   released handle emits `session_closed { sessionId, reason: "handoff_parked", sessionPath }` after releasing its
+   file. This is not a session deletion: reopen `sessionPath` on the successor to obtain a new routing handle.
+   That `sessionPath` is the CANONICAL path the host reserved the file under, which is not necessarily the string
+   the client passed to `open_session` (a scratch dir under `/var/...` on macOS is reported as `/private/var/...`).
+   A client matching the record against its own stored path must canonicalize before comparing; reopening with
+   either spelling resolves to the same reservation.
+   The connection closes after its last attached session parks; a connection shared with another active session
+   stays open until that session also settles. A command racing parking on the old connection is either served
+   or answered by that terminal record and close, never `unknown_session` for the parked handle. New opens on a
+   draining connection are refused with `host_draining`.
+4. The **supervisor** starts `SENPI_RPC_HANDOFF_GRACE_MS` at supersession (default **600000 ms / 10 minutes**).
+   This is a soft grace, not an abort deadline or a delay before parking. At expiry it reports outstanding work
+   and requests another drain pass. Sessions still mid-turn or handling requests remain alive even beyond grace;
+   no turn is cut short. Parkable sessions never wait for grace. A bare socket host has no supervisor grace timer,
+   but follows the same announce/park/settle sequence.
+5. Once every session has parked and its terminal records have drained, the generation exits even if an observer
+   or client never voluntarily disconnects. Neither the normal idle timeout nor persistent-host mode can pin it.
+
+A client may react to `host_superseded` early, but the old generation retains each file until its work settles;
+`session_path_in_use` on the successor remains a retryable response until parking releases that claim. A client
+that ignores the announcement still receives the terminal record and connection close.
+
 ### Shared host occupancy (idle eviction, retention, empty-host exit)
 
 **The daemon does not cap sessions.** On the in-process runtime - the default for a `--listen` socket host, i.e. the
@@ -619,8 +668,8 @@ What the host does enforce are lifecycle windows, and they only ever return memo
   `session_parked { sessionId, sessionPath }` and there is no `close_session` response, because nothing closed the session -
   the routing handle was released while the session itself stays on disk and reopens with `open_session { sessionPath }`
   (as a NEW handle). A client that does not know `session_parked` ignores it and learns the handle is gone from its next
-  command's `unknown_session`. A GENERATION HANDOFF parks the same sessions for the same reason, but names itself in
-  the record it emits: `session_closed { sessionId, reason: "handoff_parked" }`, so a client can tell "the host handed
+  command's `unknown_session`. A GENERATION HANDOFF also parks attached sessions, using the distinct activity
+  predicate below, and emits `session_closed { sessionId, reason: "handoff_parked", sessionPath }`, so a client can tell "the host handed
   over, reopen by path" from "this session ended". An explicit `close_session` is `reason: "client_close"`; the host
   process exiting is `reason: "host_shutdown"` (even for a retained session - the process is going away, so this is not
   a park). `reason` is optional on the wire; a client that does not know a
@@ -836,6 +885,7 @@ In the response `error` field, machine-matchable:
 - `session_reservation_limit` (this worker already holds 64 live session paths; the open or session replacement was refused without disturbing the existing session)
 - `missing_session_id` (session-scoped command without `sessionId` in multi mode)
 - `multi_session_disabled` (`open_session` in classic mode)
+- `host_draining` (`open_session` on a connection whose generation is parking for a handoff; the successor already owns the public path, so re-resolve it and open there rather than retrying this connection)
 - `invalid_path` (relative `sessionPath`/`cwd`)
 - `open_failed: <detail>`
 - `invalid_session_context: <detail>` (`open_session.context` past a documented cap: more than 32 keys, a key that does not match `^[a-z][a-z0-9_]*$`, a non-string or >16 KiB value, or more than 32 KiB of JSON in total; the detail names the cap and its byte budget)

package/node_modules/@code-yeongyu/senpi-codemode/CHANGELOG.md

@@ -12,6 +12,21 @@
 
 ### Removed
 
+## [2026.9.22] - 2026-09-21
+
+### Breaking Changes
+
+### Added
+
+- `eval` runs up to `maxDetachedCells` background cells per session (default 15, `SENPI_CODEMODE_MAX_DETACHED_CELLS`) and queues same-language cells on their kernel instead of rejecting them; `list` observes live and recent cells, and resetting a busy language refuses with `eval_kernel_busy_reset_refused` instead of stopping live work. ([#1908](https://github.com/code-yeongyu/senpi/issues/1908))
+- `agent()` forwards `isolated`, `apply`, and `merge` when the task host advertises isolation. Hosts that do not still drop those options with the existing warning. A foreground call whose isolation did not apply now raises instead of looking successful; with `handle: true` the isolation result arrives on completion. ([#1910](https://github.com/code-yeongyu/senpi/issues/1910))
+
+### Changed
+
+### Fixed
+
+### Removed
+
 ## [2026.9.21-2] - 2026-09-21
 
 ### Breaking Changes

package/node_modules/@code-yeongyu/senpi-codemode/README.md

@@ -93,6 +93,7 @@ Configuration is loaded in this order:
   "foregroundWindowSeconds": 60,
   "runBudgetSeconds": 300,
   "hardLimitSeconds": 1800,
+  "maxDetachedCells": 15,
   "parallelPoolWidth": 4,
   "taskTools": {
     "task": "task",
@@ -110,9 +111,10 @@ Configuration is loaded in this order:
 | --- | --- | --- |
 | `languages` | `py`/`js` enabled; `rb`/`jl` disabled | Selects desired languages before interpreter detection. |
 | `cellTimeoutSeconds` | `30` | Idle time an interactive call blocks the turn before the cell detaches. Print/json calls never detach. |
-| `foregroundWindowSeconds` | `60` | Caps `cellTimeoutSeconds` and the grace a bridge-parked cell gets before it detaches, so an interactive call never blocks the turn longer than this. Env override: `SENPI_CODEMODE_FOREGROUND_SECONDS`. |
-| `runBudgetSeconds` | `300` | Kill deadline for a cell's own execution time - child processes, network, timers, CPU. Time parked in host tool calls (`agent()`, `tool.*`) is not charged, and the budget keeps counting after the cell detaches. A per-call `timeout` replaces it for that cell. Env override: `SENPI_CODEMODE_RUN_BUDGET_SECONDS`. |
-| `hardLimitSeconds` | `1800` | Wall-clock kill deadline for a cell, parked or not; a per-call `timeout` above it raises it. Env override: `SENPI_CODEMODE_HARD_LIMIT_SECONDS`. |
+| `foregroundWindowSeconds` | `60` | Submission-based foreground limit, including queue and bridge pauses. The cell detaches if capacity is available; otherwise it is cancelled with `eval_background_capacity_reached`. Env override: `SENPI_CODEMODE_FOREGROUND_SECONDS`. |
+| `runBudgetSeconds` | `300` | Kill deadline for a cell's own execution time - child processes, network, timers, CPU. Time queued or parked in host tool calls (`agent()`, `tool.*`) is not charged, and the budget keeps counting after the cell detaches. A per-call `timeout` replaces it for that cell. Env override: `SENPI_CODEMODE_RUN_BUDGET_SECONDS`. |
+| `hardLimitSeconds` | `1800` | Wall-clock kill deadline from submission, including queue and parked time; a per-call `timeout` above it raises it. Env override: `SENPI_CODEMODE_HARD_LIMIT_SECONDS`. |
+| `maxDetachedCells` | `15` | Global detached-cell capacity across all kernels, including queued cells. At capacity, interactive cells stay foreground until completion or the foreground window elapses. Env override: `SENPI_CODEMODE_MAX_DETACHED_CELLS`. |
 | `parallelPoolWidth` | `4` | Maximum concurrent `parallel()` thunks. |
 | `taskTools.task` | `"task"` | Registered tool name used by `agent()`. |
 | `taskTools.output` | `"task_output"` | Registered tool name used by `output()`. |
@@ -126,6 +128,9 @@ enables; `0` or `false` disables. Any other value leaves the file setting in
 effect.
 
 Malformed JSON or invalid settings fall back to defaults with a warning.
+The detached-cell environment override uses the run-budget parser: a positive
+base-10 integer wins over the file value; zero, negative, and malformed values
+leave the file value in effect.
 
 ## Cell helpers
 
@@ -162,13 +167,25 @@ tasks return the requested transcript. Missing tools produce a clear
 availability error instead of importing an orchestration package. `agent()`
 delegates through the tool contract, so task-engine permissions, progress
 updates, and transcripts remain owned by that engine.
-`isolated`, `apply`, and `merge` are accepted for compatibility but emit a
-warning because this task-engine integration has no isolation model.
+`isolated` and `apply` accept booleans; `merge` accepts `"patch"` or `"branch"`
+(and `false`/`true` aliases respectively). The bridge checks the configured task
+parameter schema once per bridge, using the same host catalog as `tool_schema()`.
+If it advertises `isolated`, these options are forwarded; otherwise they are
+omitted with the existing warning. Senpi does not implement isolation itself.
+A foreground host result with `details.isolation.changes_applied === false`
+raises `AgentIsolationNotAppliedError` (`isolation_not_applied`), including any
+`patch_path`, `branch_name`, and `manual_command` recovery fields in its message.
+The bridge retains host `details.isolation`; successful foreground helpers still
+return text or parsed JSON.
 
 Background `agent()` handles retain `id` and `agent://<id>` and include `run_epoch`.
 The host must return structured `details.task_id` (`st_` plus lowercase hex) and
 an integer `details.run_epoch >= 0`. Missing or malformed details raise
-`invalid_task_handle`; prose IDs are never used. Foreground text/JSON is unchanged.
+`invalid_task_handle`; prose IDs are never used. Handles return immediately,
+so final isolation results are not available on the initial handle: await the
+completion notification or read `task_output` (via `output()`) after completion.
+Any isolation metadata supplied by the host on a handle is preserved as
+`details.isolation`, not interpreted as a foreground apply failure.
 
 `workpool` takes exactly one of `{category, prompt, model?}` or
 `{subagent_type, prompt, model?}` as its plain-data agent spec. Mode is `fresh`
@@ -203,22 +220,28 @@ without a `summary` fails with a teaching error.
 `eval` accepts `on_timeout: "detach"|"error"`. The default is `"detach"` in
 interactive TUI, RPC, and app-server sessions; print and JSON one-shot runs
 default to `"error"` so their result is never silently detached. A detached
-cell keeps only its own language kernel busy. A new same-language call returns
-a busy error with its cell id and output tail; calls in other languages continue
-normally. Do not re-run the cell.
+cell keeps only its own language kernel busy. New same-language cells are admitted
+into its FIFO queue; calls in other languages continue normally. Queued cells may
+also detach, within the global `maxDetachedCells` cap. At capacity, the first idle
+detach attempt leaves the cell foreground and re-arms one wait for the remaining
+submission-based foreground window. At the window, it detaches if a slot is now
+free; otherwise it settles `cancelled` with `eval_background_capacity_reached`,
+listing the live cells and a stop-or-wait remedy. Cells that complete inside the
+window return normally. Cancelling a queued cell never interrupts its predecessor.
+Do not re-run a detached or queued cell; each detached cell completes as one notification.
 
 Queued steering also detaches an eligible interactive foreground call, including
 one paused in a host tool bridge, without cancelling its computation. If the
-language's detached slot is occupied, steering leaves the call waiting. Follow-up
+global detached cap is reached, steering leaves the call waiting. Follow-up
 messages, explicit `on_timeout: "error"`, and print/JSON calls do not trigger this
 transition; caller abort and existing deadlines retain their cancellation behavior.
 
 Every cell, detached or not, is bounded by two kill deadlines. The run budget
 (`runBudgetSeconds`, or the call's `timeout`) charges only the cell's own
-execution time and is paused while a host tool call is in flight, so a cell
+execution time and is paused while queued or while a host tool call is in flight, so a cell
 waiting on `agent()` survives while a runaway child process or loop does not.
 The hard limit (`hardLimitSeconds`, raised by a larger `timeout`) is wall-clock
-and bounds parked cells too. A cell killed by either deadline reports which one
+from submission and bounds queued and parked cells too. A cell killed by either deadline reports which one
 in its result or completion notification, together with whether kernel state
 survived; the tool schema states the configured numbers. The `timeout` value
 never changes the idle detach deadline: that is `cellTimeoutSeconds` capped by
@@ -227,9 +250,24 @@ never changes the idle detach deadline: that is `cellTimeoutSeconds` capped by
 While any cell is detached, the interactive footer shows a highlighted
 `↗ <language> · <summary>` status on the extension status line (the cell id
 when the call had no summary), clearing as soon as the last detached cell settles.
+Queued entries are labelled `queued`; an all-queued footer shows `(queued)` instead
+of an elapsed duration. Elapsed time counts only from execution start.
+
+Use `eval({ action: "list" })` without a language or cell id to see live and
+recently settled cells across languages. Each line includes the id, language,
+state, elapsed execution seconds, queue predecessors, and summary (or a short code
+preview); `details.cells` carries the typed cell metadata. Listing never consumes
+completion notifications.
+
+A run with `reset: true` resets only its selected language and is refused with
+`eval_kernel_busy_reset_refused` while any other cell in that language is live,
+including queued cells. The requesting cell fails without changing the kernel or
+cancelling existing work. Stop those cells explicitly or wait for their completion
+notifications before resetting; live cells in other languages do not block reset.
 
 Use `eval({ action: "peek", cell_id })` for its state and buffered output, or
-`eval({ action: "stop", cell_id })` to cancel it. Python stop interrupts the
+`eval({ action: "stop", cell_id })` to cancel it. Stopping a queued cell removes it
+without interrupting the active cell; kernel state is retained. Python running-cell stop interrupts the
 existing kernel and preserves variables. JavaScript stop is cooperative first:
 the worker rejects the cell's pending bridge `tool.*` calls and kills the
 `Bun.spawn` children it started, and a cell that settles within the 2 s grace

package/node_modules/@code-yeongyu/senpi-codemode/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/senpi-codemode",
-	"version": "2026.9.21-2",
+	"version": "2026.9.22",
 	"private": true,
 	"description": "Source-only senpi extension package for codemode evaluation tools",
 	"type": "module",
@@ -31,14 +31,14 @@
 	},
 	"dependencies": {
 		"@babel/parser": "8.0.4",
-		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.9.21-2",
+		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.9.22",
 		"typebox": "1.3.34"
 	},
 	"peerDependencies": {
-		"@code-yeongyu/senpi": "2026.9.21-2"
+		"@code-yeongyu/senpi": "2026.9.22"
 	},
 	"devDependencies": {
-		"@code-yeongyu/senpi": "2026.9.21-2"
+		"@code-yeongyu/senpi": "2026.9.22"
 	},
 	"keywords": [
 		"senpi",

package/node_modules/@code-yeongyu/senpi-codemode/src/bridges/agent-bridge.ts

@@ -2,6 +2,7 @@ import type { AgentToolResult } from "@code-yeongyu/senpi";
 import { type Static, Type } from "typebox";
 import { Check, Errors } from "typebox/value";
 import type { EvalStatusEvent, ExecuteTool } from "../tool/types.ts";
+import type { EvalSchemaToolInfo } from "./schema-bridge.ts";
 
 const agentArgsSchema = Type.Object(
 	{
@@ -14,7 +15,7 @@ const agentArgsSchema = Type.Object(
 		tools: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
 		isolated: Type.Optional(Type.Boolean()),
 		apply: Type.Optional(Type.Boolean()),
-		merge: Type.Optional(Type.Boolean()),
+		merge: Type.Optional(Type.Union([Type.Boolean(), Type.Literal("patch"), Type.Literal("branch")])),
 	},
 	{ additionalProperties: false },
 );
@@ -43,6 +44,9 @@ type TaskParams = {
 	readonly name?: string;
 	readonly run_in_background: boolean;
 	readonly tools?: readonly string[];
+	readonly isolated?: boolean;
+	readonly apply?: boolean;
+	readonly merge?: "patch" | "branch";
 };
 type ProgressContext = { readonly fallbackId: string; readonly warning?: string };
 
@@ -54,15 +58,32 @@ export interface RunEvalAgentOptions {
 	readonly callId: string;
 	readonly taskToolName: string;
 	readonly executeTool: AgentExecuteTool;
+	readonly listTools?: () => readonly EvalSchemaToolInfo[];
 	readonly signal?: AbortSignal;
 	readonly emitStatus?: (event: EvalStatusEvent) => void;
 }
 
-export type EvalAgentResult =
+export type EvalAgentResult = (
 	| { readonly text: string }
 	| { readonly text: string; readonly data: unknown }
 	| { readonly text: string; readonly parseError: string }
-	| { readonly text: string; readonly id: string; readonly handle: string; readonly run_epoch: number };
+	| { readonly text: string; readonly id: string; readonly handle: string; readonly run_epoch: number }
+) & { readonly details?: { readonly isolation: Readonly<Record<string, unknown>> } };
+
+// The session-owned executor identifies a bridge across JS and HTTP calls; do not retain retired sessions.
+const isolationCapabilities = new WeakMap<AgentExecuteTool, Map<string, boolean>>();
+
+export class AgentIsolationNotAppliedError extends Error {
+	readonly name = "AgentIsolationNotAppliedError";
+	readonly code = "isolation_not_applied";
+
+	constructor(isolation: Readonly<Record<string, unknown>>) {
+		const recovery = ["patch_path", "branch_name", "manual_command"]
+			.flatMap((key) => (typeof isolation[key] === "string" ? [`${key}: ${isolation[key]}`] : []))
+			.join("; ");
+		super(`agent() isolated changes were not applied${recovery ? `; ${recovery}` : ""}`);
+	}
+}
 
 class AgentArgumentsError extends Error {
 	readonly name = "AgentArgumentsError";
@@ -92,7 +113,8 @@ class AgentHandleError extends Error {
 export async function runEvalAgent(args: unknown, options: RunEvalAgentOptions): Promise<EvalAgentResult> {
 	const parsed = parseAgentArgs(args);
 	const structured = Object.hasOwn(parsed, "schema");
-	const warning = droppedOptionsWarning(parsed);
+	const supportsIsolation = taskSupportsIsolation(options);
+	const warning = supportsIsolation ? undefined : droppedOptionsWarning(parsed);
 	const fallbackId = parsed.label ?? options.callId;
 	if (warning) options.emitStatus?.({ op: "agent", id: fallbackId, status: "running", warning });
 
@@ -104,7 +126,7 @@ export async function runEvalAgent(args: unknown, options: RunEvalAgentOptions):
 
 	let result: AgentToolResult<unknown>;
 	try {
-		result = await options.executeTool(options.taskToolName, toTaskParams(parsed, structured), {
+		result = await options.executeTool(options.taskToolName, toTaskParams(parsed, structured, supportsIsolation), {
 			...(options.signal ? { signal: options.signal } : {}),
 			...(options.emitStatus
 				? {
@@ -119,12 +141,15 @@ export async function runEvalAgent(args: unknown, options: RunEvalAgentOptions):
 	}
 
 	const text = resultText(result);
+	const isolation =
+		isRecord(result.details) && isRecord(result.details.isolation) ? result.details.isolation : undefined;
+	const metadata = isolation === undefined ? {} : { details: { isolation } };
 	if (parsed.handle === true) {
 		const { task_id: id, run_epoch } = resultTaskHandle(result);
-		return { text, id, handle: `agent://${id}`, run_epoch };
+		return { text, id, handle: `agent://${id}`, run_epoch, ...metadata };
 	}
-	if (!structured) return { text };
-	return parseStructuredText(text);
+	if (isolation?.changes_applied === false) throw new AgentIsolationNotAppliedError(isolation);
+	return { ...(structured ? parseStructuredText(text) : { text }), ...metadata };
 }
 
 function parseAgentArgs(value: unknown): AgentArgs {
@@ -135,7 +160,21 @@ function parseAgentArgs(value: unknown): AgentArgs {
 	throw new AgentArgumentsError(summary || "invalid value");
 }
 
-function toTaskParams(args: AgentArgs, structured: boolean): TaskParams {
+function taskSupportsIsolation(options: RunEvalAgentOptions): boolean {
+	let capabilities = isolationCapabilities.get(options.executeTool);
+	if (!capabilities) {
+		capabilities = new Map();
+		isolationCapabilities.set(options.executeTool, capabilities);
+	}
+	const cached = capabilities.get(options.taskToolName);
+	if (cached !== undefined) return cached;
+	const schema = options.listTools?.().find((tool) => tool.name === options.taskToolName)?.parameters;
+	const supported = isRecord(schema) && isRecord(schema.properties) && schema.properties.isolated !== undefined;
+	capabilities.set(options.taskToolName, supported);
+	return supported;
+}
+
+function toTaskParams(args: AgentArgs, structured: boolean, supportsIsolation: boolean): TaskParams {
 	return {
 		prompt: structured
 			? `${args.prompt}\n\nRespond ONLY with JSON matching this JSON-Schema:\n${JSON.stringify(args.schema)}`
@@ -145,6 +184,11 @@ function toTaskParams(args: AgentArgs, structured: boolean): TaskParams {
 		...(args.label === undefined ? {} : { name: args.label }),
 		run_in_background: args.handle === true,
 		...(args.tools === undefined ? {} : { tools: args.tools }),
+		...(supportsIsolation && args.isolated !== undefined ? { isolated: args.isolated } : {}),
+		...(supportsIsolation && args.apply !== undefined ? { apply: args.apply } : {}),
+		...(supportsIsolation && args.merge !== undefined
+			? { merge: args.merge === true ? "branch" : args.merge === false ? "patch" : args.merge }
+			: {}),
 	};
 }
 

package/node_modules/@code-yeongyu/senpi-codemode/src/bridges/reserved-dispatch.ts

@@ -35,6 +35,7 @@ export async function runReservedTool(toolName: string, context: ReservedDispatc
 			callId: context.callId,
 			taskToolName: context.taskToolName,
 			executeTool: context.executeTool,
+			...(context.listTools === undefined ? {} : { listTools: context.listTools }),
 			...(context.signal === undefined ? {} : { signal: context.signal }),
 			emitStatus: context.emitStatus,
 		});

package/node_modules/@code-yeongyu/senpi-codemode/src/config/settings.ts

@@ -22,6 +22,7 @@ export const codemodeSettingsSchema = Type.Object(
 		foregroundWindowSeconds: Type.Optional(Type.Number({ minimum: 1 })),
 		runBudgetSeconds: Type.Optional(Type.Number({ minimum: 1 })),
 		hardLimitSeconds: Type.Optional(Type.Number({ minimum: 1 })),
+		maxDetachedCells: Type.Optional(Type.Number({ minimum: 1 })),
 		parallelPoolWidth: Type.Optional(Type.Number({ minimum: 1 })),
 		taskTools: Type.Optional(
 			Type.Object(
@@ -80,6 +81,8 @@ export interface CodemodeSettings {
 	readonly runBudgetSeconds: number;
 	/** Wall-clock kill deadline for a single cell; bounds detached and bridge-parked cells too. */
 	readonly hardLimitSeconds: number;
+	/** Maximum detached cells across all language kernels. */
+	readonly maxDetachedCells?: number;
 	readonly parallelPoolWidth: number;
 	readonly taskTools?: CodemodeTaskTools;
 	readonly outputSink?: CodemodeOutputSink;
@@ -87,6 +90,7 @@ export interface CodemodeSettings {
 }
 
 export type ResolvedCodemodeSettings = CodemodeSettings & {
+	readonly maxDetachedCells: number;
 	readonly taskTools: CodemodeTaskTools;
 	readonly outputSink: CodemodeOutputSink;
 	readonly statusEvents: boolean;
@@ -129,7 +133,10 @@ export const FOREGROUND_WINDOW_ENVIRONMENT_FLAG = "SENPI_CODEMODE_FOREGROUND_SEC
  */
 export const DEFAULT_RUN_BUDGET_SECONDS = 300;
 
+export const DEFAULT_MAX_DETACHED_CELLS = 15;
+
 export const RUN_BUDGET_ENVIRONMENT_FLAG = "SENPI_CODEMODE_RUN_BUDGET_SECONDS";
+export const MAX_DETACHED_CELLS_ENVIRONMENT_FLAG = "SENPI_CODEMODE_MAX_DETACHED_CELLS";
 
 // OMP settings-schema.ts:3211-3299 has language/path settings only; eval.ts:427
 // defaults timeout to 30s, and codemode pins concurrency-bridge.ts:30 width to 4.
@@ -144,6 +151,7 @@ export const defaultCodemodeSettings: ResolvedCodemodeSettings = {
 	foregroundWindowSeconds: DEFAULT_FOREGROUND_WINDOW_SECONDS,
 	runBudgetSeconds: DEFAULT_RUN_BUDGET_SECONDS,
 	hardLimitSeconds: DEFAULT_HARD_LIMIT_SECONDS,
+	maxDetachedCells: DEFAULT_MAX_DETACHED_CELLS,
 	parallelPoolWidth: 4,
 	taskTools: {
 		task: "task",
@@ -207,6 +215,15 @@ export function resolveRunBudgetSeconds(settings: CodemodeSettings, env: Environ
 	return positiveSecondsOverride(env[RUN_BUDGET_ENVIRONMENT_FLAG]) ?? settings.runBudgetSeconds;
 }
 
+/** Uses the same positive-integer environment parsing as the run budget. */
+export function resolveMaxDetachedCells(settings: CodemodeSettings, env: Environment = process.env): number {
+	return (
+		positiveSecondsOverride(env[MAX_DETACHED_CELLS_ENVIRONMENT_FLAG]) ??
+		settings.maxDetachedCells ??
+		DEFAULT_MAX_DETACHED_CELLS
+	);
+}
+
 function positiveSecondsOverride(value: string | undefined): number | undefined {
 	if (value === undefined) return undefined;
 	const parsed = Number.parseInt(value, 10);
@@ -250,6 +267,7 @@ function mergeSettings(input: CodemodeSettingsInput): ResolvedCodemodeSettings {
 		foregroundWindowSeconds: input.foregroundWindowSeconds ?? defaultCodemodeSettings.foregroundWindowSeconds,
 		runBudgetSeconds: input.runBudgetSeconds ?? defaultCodemodeSettings.runBudgetSeconds,
 		hardLimitSeconds: input.hardLimitSeconds ?? defaultCodemodeSettings.hardLimitSeconds,
+		maxDetachedCells: input.maxDetachedCells ?? DEFAULT_MAX_DETACHED_CELLS,
 		parallelPoolWidth: input.parallelPoolWidth ?? defaultCodemodeSettings.parallelPoolWidth,
 		taskTools: {
 			task: input.taskTools?.task ?? defaultCodemodeSettings.taskTools.task,

package/node_modules/@code-yeongyu/senpi-codemode/src/extension/eval-status.ts

@@ -28,7 +28,8 @@ function packLabels(labels: readonly string[], budget: number): string {
 }
 
 function labelOf(entry: EvalDetachedCellStatusEntry): string {
-	return entry.summary === undefined || entry.summary.length === 0 ? entry.cellId : entry.summary;
+	const label = entry.summary === undefined || entry.summary.length === 0 ? entry.cellId : entry.summary;
+	return entry.queuedBehind === undefined ? label : `queued ${label}`;
 }
 
 /**
@@ -52,10 +53,12 @@ export function formatElapsedSeconds(value: number): string {
 	return `${hours}h ${remainingMinutes}m`;
 }
 
-/** Whole seconds since the oldest detached cell was created; never negative on clock skew. */
+/** Whole seconds since the oldest executing detached cell started; queued cells do not tick. */
 export function evalCellElapsedSeconds(entries: readonly EvalDetachedCellStatusEntry[], nowMs: number): number {
 	let oldest = Number.POSITIVE_INFINITY;
-	for (const entry of entries) oldest = Math.min(oldest, entry.startedAtMs);
+	for (const entry of entries) {
+		if (entry.queuedBehind === undefined) oldest = Math.min(oldest, entry.startedAtMs);
+	}
 	if (!Number.isFinite(oldest)) return 0;
 	return Math.max(0, Math.round((nowMs - oldest) / 1000));
 }
@@ -67,7 +70,9 @@ export function formatEvalCellStatus(
 ): string | undefined {
 	const first = entries[0];
 	if (first === undefined) return undefined;
-	const suffix = ` (${formatElapsedSeconds(evalCellElapsedSeconds(entries, nowMs))})`;
+	const suffix = entries.every((entry) => entry.queuedBehind !== undefined)
+		? " (queued)"
+		: ` (${formatElapsedSeconds(evalCellElapsedSeconds(entries, nowMs))})`;
 	if (entries.length === 1) {
 		const head = `${DETACHED_GLYPH} ${first.language} · `;
 		return head + truncateEnd(labelOf(first), MAX_STATUS_LENGTH - head.length - suffix.length) + suffix;

package/node_modules/@code-yeongyu/senpi-codemode/src/index.ts

@@ -7,6 +7,7 @@ import {
 	defaultCodemodeSettings,
 	resolveForegroundWindowSeconds,
 	resolveHardLimitSeconds,
+	resolveMaxDetachedCells,
 	resolveRunBudgetSeconds,
 } from "./config/settings.ts";
 import { EvalNotifier } from "./extension/eval-notifier.ts";
@@ -181,6 +182,7 @@ export default function senpiCodemode(pi: CodemodeExtensionAPI, options: SenpiCo
 			settings: defaultCodemodeSettings,
 			cellManager: new EvalDetachedCellManager({
 				notifier,
+				maxDetachedCells: resolveMaxDetachedCells(defaultCodemodeSettings),
 				hardLimitSeconds: resolveHardLimitSeconds(defaultCodemodeSettings),
 				runBudgetSeconds: resolveRunBudgetSeconds(defaultCodemodeSettings),
 				onStatusChange: showDetachedCells,
@@ -219,6 +221,7 @@ export default function senpiCodemode(pi: CodemodeExtensionAPI, options: SenpiCo
 		const cellManager = new EvalDetachedCellManager({
 			artifactsDir: runtime.artifactsDir,
 			notifier,
+			maxDetachedCells: resolveMaxDetachedCells(runtime.settings),
 			hardLimitSeconds: resolveHardLimitSeconds(runtime.settings),
 			runBudgetSeconds: resolveRunBudgetSeconds(runtime.settings),
 			onStatusChange: showDetachedCells,

package/node_modules/@code-yeongyu/senpi-codemode/src/kernels/AGENTS.md

@@ -28,8 +28,8 @@ runner/prelude assets).
   AST-parsed (Babel) and rewritten to bridge-compatible dynamic imports.
 - JS runs on worker threads with an inline-worker fallback; py/rb/jl run as
   framed subprocesses through `shared/`.
-- Subprocess retirement/restart, worker recovery, timeout, and interrupt
-  semantics live here, never in the tool layer.
+- Each language keeps one serial FIFO kernel. Queued cancellation removes only
+  that cell; active interruption and runtime recovery stay in the kernel layer.
 - Every kernel exposes the active session's `PI_*` environment (`session-env.ts`):
   inherited values are deleted before the session's values are applied, so any
   child spawned from a cell sees the same session environment a bash-tool child

package/node_modules/@code-yeongyu/senpi-codemode/src/kernels/jl/prelude.jl

@@ -254,6 +254,12 @@ function output(ids...; format="raw", offset=nothing, limit=nothing)
     senpi_with_bridge_timeout_pause(() -> senpi_call_tool("__output__", arguments))
 end
 
+"""
+Delegate work with isolated/apply/merge; needs a host that supports isolation, otherwise a warning.
+merge accepts "patch"/"branch" (false/true aliases). Unapplied foreground changes raise
+an error with recovery instructions. Handles return immediately: await the completion
+notification or read task_output for the isolation result.
+"""
 function agent(prompt::AbstractString; agent="task", model=nothing, label=nothing, schema=nothing, isolated=nothing, apply=nothing, merge=nothing, handle=false, kwargs...)
     arguments = Dict{String, Any}("prompt" => string(prompt), "agent" => agent)
     for (key, value) in (("model", model), ("label", label), ("schema", schema), ("isolated", isolated), ("apply", apply), ("merge", merge))
@@ -272,6 +278,10 @@ function agent(prompt::AbstractString; agent="task", model=nothing, label=nothin
     result["handle"] = get(record, "handle", result["id"] === nothing ? nothing : "agent://" * string(result["id"]))
     result["run_epoch"] = get(record, "run_epoch", nothing)
     schema !== nothing && (result["data"] = parsed)
+    details = get(record, "details", nothing)
+    if details isa AbstractDict && haskey(details, "isolation")
+        result["details"] = Dict("isolation" => details["isolation"])
+    end
     result
 end