@spunto/build 0.24.0 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/build",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Spunto's shared Build engine — the devcontainer image protocol and VS Code extension registry clients, with no database, no HTTP framework and no UI.",
   "type": "module",
   "license": "MIT",
@@ -93,7 +93,8 @@
       "import": "./src/agent-runners/index.ts"
     },
     "./agent-runners/claude.mjs": "./src/agent-runners/claude.mjs",
-    "./agent-runners/codex.mjs": "./src/agent-runners/codex.mjs"
+    "./agent-runners/codex.mjs": "./src/agent-runners/codex.mjs",
+    "./agent-runners/mistral.mjs": "./src/agent-runners/mistral.mjs"
   },
   "files": [
     "src",

package/src/agent-runners/catalogs.ts

@@ -11,7 +11,12 @@
  *    2026-10-26. Each model comes back with `supportedEffortLevels`;
  *  - Codex: `codex debug models` of `@openai/codex` 0.164.0 — the catalog bundled in the binary,
  *    offline, on 2026-10-26 — the `visibility: "list"` models, with their
- *    `supported_reasoning_levels` and `default_reasoning_level`.
+ *    `supported_reasoning_levels` and `default_reasoning_level`;
+ *  - Mistral: the `model` and `thinking` options of a `session/new` of `vibe-acp` 3.0.4, then of
+ *    `session/set_config_option` for each model, on 2026-10-31, with a pay-as-you-go API key.
+ *    Not all in the binary: Vibe's own default is Medium 3.5, and the others came from Mistral's
+ *    remote config (a rollout of Large 4 as the default the account was in) — an account outside
+ *    it may lack them, which the runner then says, with the models it does have.
  *
  * `packages/build/scripts/agent-catalogs.mjs` prints both again, to diff against this file when a
  * pin is bumped.
@@ -82,7 +87,7 @@ const CODEX_REASONING: AgentParamValue[] = [
 
 const ALL_BUT_ULTRA = ["low", "medium", "high", "xhigh", "max"]
 
-export const AGENT_CATALOGS: Record<"claude" | "codex", AgentCatalog> = {
+export const AGENT_CATALOGS: Record<"claude" | "codex" | "mistral", AgentCatalog> = {
   claude: {
     // The SDK's aliases (`default`, `sonnet`, `opus`, `fable`, `haiku`) resolved to the ids they
     // stand for: a task records the model it ran, not a name whose meaning moves.
@@ -130,6 +135,28 @@ export const AGENT_CATALOGS: Record<"claude" | "codex", AgentCatalog> = {
         ],
       },
     ],
+  },  mistral: {
+    // Vibe's aliases, which are what `session/set_config_option` takes (and what `--model` gets).
+    models: [
+      { value: "mistral-medium-3.5", label: "Mistral Medium 3.5", description: "Vibe's own default (mistral-vibe-cli-latest)", default: true, params: { thinking: ["off", "high"] }, paramDefaults: { thinking: "high" } },
+      { value: "mistral-large-4-0-3", label: "Mistral Large 4", description: "mistral-large-4-0 — rolling out as Vibe's default", params: { thinking: ["low", "medium", "high"] }, paramDefaults: { thinking: "high" } },
+      { value: "glm-5-3", label: "GLM-5.3", description: "zai-glm-5-3, hosted by Mistral", params: { thinking: ["low", "high", "max"] }, paramDefaults: { thinking: "high" } },
+      { value: "zai-glm-5-3-flash", label: "GLM-5.3 Flash", description: "zai-glm-5-3-flash, hosted by Mistral", params: { thinking: ["low", "high", "max"] }, paramDefaults: { thinking: "high" } },
+    ],
+    params: [
+      {
+        id: "thinking",
+        label: "Thinking",
+        description: "How much the model reasons before it acts. Unset = the level Vibe last used for the model.",
+        values: [
+          { value: "off", label: "Off" },
+          { value: "low", label: "Low" },
+          { value: "medium", label: "Medium" },
+          { value: "high", label: "High" },
+          { value: "max", label: "Max" },
+        ],
+      },
+    ],
   },
 }
 

package/src/agent-runners/features.ts

@@ -4,7 +4,8 @@
 // Each one lays down, under /opt/spunto/agents:
 //   node/            a private Node — the runner must not depend on the project's (absent from a
 //                    Python image, swapped by an nvm feature that installs after this one)
-//   <id>/            the harness's official SDK, pinned, with the native binary it drives
+//   <id>/            the harness's official SDK, pinned, with the native binary it drives — or, for
+//                    a harness with no Node SDK (Mistral Vibe, Python), the harness itself, pinned
 //   /usr/local/bin/  the harness's CLI for the humans in the terminal, unless the image has one
 
 /** Where every agent feature installs. */
@@ -13,7 +14,18 @@ export const AGENT_HOME = "/opt/spunto/agents"
 export const AGENT_NODE_VERSION = "v24.11.1"
 const NODE_VERSION = AGENT_NODE_VERSION
 
-function featureScript(p: { id: string; label: string; packages: string; cli: string }): string {
+/** The pinned Mistral Vibe release, and the uv that installs it (with its own Python). */
+export const MISTRAL_VIBE_VERSION = "3.0.4"
+const UV_VERSION = "0.13.6"
+
+/** The SDK, from npm, into `<id>/` — what both Node harnesses install. */
+function npmInstall(id: string, packages: string): string {
+  return `mkdir -p "$HOME_DIR/${id}"
+PATH="$NODE_DIR/bin:$PATH" "$NODE_DIR/bin/npm" install --prefix "$HOME_DIR/${id}" \\
+  --omit=dev --no-audit --no-fund --no-update-notifier --loglevel=error ${packages}`
+}
+
+function featureScript(p: { id: string; label: string; install: string; cli: string }): string {
   return `#!/bin/sh
 set -e
 echo "[feature] ${p.id}: installing ${p.label}..."
@@ -42,9 +54,7 @@ if ! "$NODE_DIR/bin/node" -e 'process.exit(0)' 2>/dev/null; then
   rm -f /tmp/_spunto_node.tgz
 fi
 
-mkdir -p "$HOME_DIR/${p.id}"
-PATH="$NODE_DIR/bin:$PATH" "$NODE_DIR/bin/npm" install --prefix "$HOME_DIR/${p.id}" \\
-  --omit=dev --no-audit --no-fund --no-update-notifier --loglevel=error ${p.packages}
+${p.install}
 chmod -R a+rX "$HOME_DIR"
 
 ${p.cli}
@@ -57,7 +67,7 @@ export const AGENT_FEATURE_SCRIPTS: Record<string, string> = {
   "spunto-agent-claude.sh": featureScript({
     id: "claude",
     label: "the Claude Agent SDK",
-    packages: "@anthropic-ai/claude-agent-sdk@0.3.310",
+    install: npmInstall("claude", "@anthropic-ai/claude-agent-sdk@0.3.310"),
     // The SDK drives a native \`claude\` binary from a platform package; the same binary is the CLI.
     cli: `if ! command -v claude >/dev/null 2>&1; then
   for b in "$HOME_DIR"/claude/node_modules/@anthropic-ai/claude-agent-sdk-linux-*/claude; do
@@ -68,10 +78,32 @@ fi`,
   "spunto-agent-codex.sh": featureScript({
     id: "codex",
     label: "the Codex SDK",
-    packages: "@openai/codex-sdk@0.164.0",
+    install: npmInstall("codex", "@openai/codex-sdk@0.164.0"),
     cli: `if ! command -v codex >/dev/null 2>&1; then
   printf '#!/bin/sh\\nexec %s %s "$@"\\n' "$NODE_DIR/bin/node" "$HOME_DIR/codex/node_modules/@openai/codex/bin/codex.js" > /usr/local/bin/codex
   chmod 755 /usr/local/bin/codex
 fi`,
   }),
+  // Mistral Vibe has no Node SDK: the runner speaks ACP to `vibe-acp` itself (`../mistral.mjs`).
+  // Vibe is Python (≥ 3.12); uv installs it with a Python of its own, so the image's — absent, or
+  // too old — never matters, the way the private Node keeps the project's out of the runner.
+  "spunto-agent-mistral.sh": featureScript({
+    id: "mistral",
+    label: "Mistral Vibe",
+    install: `MISTRAL_DIR=$HOME_DIR/mistral
+mkdir -p "$MISTRAL_DIR"
+if ! "$MISTRAL_DIR/uv/uv" --version 2>/dev/null | grep -q "${UV_VERSION}"; then
+  echo "[feature] mistral: fetching uv ${UV_VERSION}"
+  fetch "https://astral.sh/uv/${UV_VERSION}/install.sh" /tmp/_spunto_uv_install.sh
+  UV_INSTALL_DIR="$MISTRAL_DIR/uv" UV_NO_MODIFY_PATH=1 sh /tmp/_spunto_uv_install.sh >/dev/null
+  rm -f /tmp/_spunto_uv_install.sh
+fi
+UV_PYTHON_INSTALL_DIR="$MISTRAL_DIR/python" UV_TOOL_DIR="$MISTRAL_DIR/tools" UV_TOOL_BIN_DIR="$MISTRAL_DIR/bin" \\
+  UV_CACHE_DIR=/tmp/_spunto_uv_cache UV_NO_CONFIG=1 \\
+  "$MISTRAL_DIR/uv/uv" tool install --force --managed-python --python 3.13 "mistral-vibe==${MISTRAL_VIBE_VERSION}"
+rm -rf /tmp/_spunto_uv_cache`,
+    cli: `for b in vibe vibe-acp; do
+  if ! command -v "$b" >/dev/null 2>&1; then ln -sf "$HOME_DIR/mistral/bin/$b" "/usr/local/bin/$b"; fi
+done`,
+  }),
 }

package/src/agent-runners/index.ts

@@ -7,8 +7,8 @@
  *    installs a private Node and the harness's **official SDK** (with the binary the SDK drives)
  *    under `/opt/spunto/agents/<id>`. Shipped by the platform itself (`localScript`), so an app
  *    never waits on a registry release;
- *  - a **runner**, a `.mjs` entry of ours (`claude.mjs`, `codex.mjs`) with its harness's adapter
- *    next to it (`claude/adapter.ts`, `codex/adapter.ts`). The caller **bundles** the two into one
+ *  - a **runner**, a `.mjs` entry of ours (`claude.mjs`, `codex.mjs`, `mistral.mjs`) with its harness's
+ *    adapter next to it (`claude/adapter.ts`, `codex/adapter.ts`, `mistral/adapter.ts`). The caller **bundles** the two into one
  *    file (esbuild, `platform: node`, `format: esm`) and writes it into the machine at the moment a
  *    session starts. Not baked: a runner fix reaches the next session, not the next rebuild;
  *  - the **Spunto agent contract** (`agent-v1`, `../agent-contract`), which is how the platform
@@ -35,7 +35,7 @@ import { AGENT_HOME } from "./features"
 /** The Node every runner runs on — the private one the features install. */
 export const AGENT_NODE = `${AGENT_HOME}/node/bin/node`
 
-export type AgentHarnessId = "claude" | "codex"
+export type AgentHarnessId = "claude" | "codex" | "mistral"
 
 export type AgentHarness = {
   id: AgentHarnessId
@@ -45,7 +45,8 @@ export type AgentHarness = {
   protocol: AgentProtocol
   /**
    * What this app's runner printed before the contract, and so how a session it started then is
-   * still read, until it ends (RFC 0048 § 9: a session keeps the dialect it began on).
+   * still read, until it ends (RFC 0048 § 9: a session keeps the dialect it began on). An app born
+   * on the contract (Mistral) has no such past: `agent-v1`.
    */
   legacyProtocol: AgentProtocol
   /** The runner's entry, a file of this package — to be bundled with what it imports. */
@@ -71,6 +72,14 @@ export const AGENT_HARNESSES: Record<AgentHarnessId, AgentHarness> = {
     runnerFile: new URL("./codex.mjs", import.meta.url),
     skillDirs: ["${CODEX_HOME:-$HOME/.codex}/skills"],
   },
+  mistral: {
+    id: "mistral",
+    featureId: "spunto-agent-mistral",
+    protocol: "agent-v1",
+    legacyProtocol: "agent-v1",
+    runnerFile: new URL("./mistral.mjs", import.meta.url),
+    skillDirs: ["${VIBE_HOME:-$HOME/.vibe}/skills"],
+  },
 }
 
 /** The variable a runner's text travels in, base64 — see `runnerCommand`. */
@@ -102,6 +111,6 @@ export function harnessOfFeature(featureId: string): AgentHarness | null {
   return Object.values(AGENT_HARNESSES).find((h) => h.featureId === featureId) ?? null
 }
 
-export { AGENT_FEATURE_SCRIPTS, AGENT_HOME, AGENT_NODE_VERSION } from "./features"
+export { AGENT_FEATURE_SCRIPTS, AGENT_HOME, AGENT_NODE_VERSION, MISTRAL_VIBE_VERSION } from "./features"
 export { AGENT_CATALOGS, MCP_ENV, OPTIONS_ENV, STREAM_ENV, agentOptionsError } from "./catalogs"
 export type { AgentCatalog, AgentMcpServer, AgentModel, AgentParam, AgentParamValue } from "./catalogs"

package/src/agent-runners/mistral/adapter.ts

@@ -0,0 +1,219 @@
+/**
+ * Mistral Vibe's dialect, read into our vocabulary — the **Agent Client Protocol** (ACP) that
+ * `vibe-acp` speaks on stdio: the `session/update` notifications of a turn, and the answer to its
+ * `session/prompt`. Written against what Vibe 3.0.4 printed on 2026-10-31, against the real API
+ * (`test/fixtures/fake-vibe-acp.mjs` replays those messages, shortened, never reshaped).
+ *
+ * Lives with the Mistral runner (RFC 0048 § 9): the runner bundles it and prints the contract.
+ *
+ * What ACP is like, and why the translator keeps state:
+ *
+ *  - text arrives in **chunks** (`agent_message_chunk`, `agent_thought_chunk`), each naming the
+ *    message it belongs to (`messageId`). A finished `message` / `thinking` is printed when the
+ *    message is over — another one starts, a tool is called, the turn ends — with the chunks joined
+ *    as its `source`. Under `SPUNTO_AGENT_STREAM`, each chunk is also a `message.delta`;
+ *  - a tool is a `tool_call` (`in_progress`, with its `rawInput`) then a `tool_call_update` that
+ *    settles it (`completed` / `failed`) — the pair is our `tool.call` / `tool.result`;
+ *  - usage is restated by Vibe after every step (`usage_update`: how full the window is, how large
+ *    it is, the session's cost), and the turn's answer carries the **session's** running token
+ *    totals (measured: the second turn's `inputTokens` include the first's, a resumed session's
+ *    too). So it is one `usage` of scope `session` per turn, the latest winning;
+ *  - the turn's end is the answer to `session/prompt`: a `stopReason`, or a JSON-RPC error.
+ */
+
+import { clip } from "../../agent-contract/vocabulary"
+
+type Obj = Record<string, unknown>
+export type ContractLine = Record<string, unknown>
+
+function obj(value: unknown): Obj {
+  return value && typeof value === "object" && !Array.isArray(value) ? (value as Obj) : {}
+}
+
+function num(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null
+}
+
+function str(value: unknown): string | null {
+  return typeof value === "string" && value ? value : null
+}
+
+/** The text of an ACP tool's `content` (its `content` blocks of text; diffs are the call's, not its output). */
+function contentText(content: unknown): string {
+  if (!Array.isArray(content)) return ""
+  return content
+    .map((c) => obj(c))
+    .filter((c) => c.type === "content" && obj(c.content).type === "text")
+    .map((c) => String(obj(c.content).text ?? ""))
+    .join("\n")
+}
+
+/** A tool's name as the agent knows it: Vibe's own (`bash`, `write_file`…), else ACP's kind. */
+function toolName(update: Obj): string {
+  return str(obj(update._meta).tool_name) ?? str(update.kind) ?? str(update.title) ?? "tool"
+}
+
+/** Vibe's application error codes (`vibe/acp/exceptions.py`) the contract has a word for. */
+const RATE_LIMITED = -31001
+
+export type MistralTranslator = {
+  /** One `session/update` notification's `update`. */
+  update(update: Obj): ContractLine[]
+  /** The answer to `session/prompt` — `{ result }` or `{ error }` — which ends the turn. */
+  ended(response: Obj): ContractLine[]
+  /** What Vibe said of the window last: how full, how large (for `session.started`). */
+  readonly window: { used: number | null; size: number | null }
+  /** The session's model, once the runner has set it — named on each turn's `usage`. */
+  model: string | null
+  /** The human's turn, as sent: Vibe's first "title" is a copy of it, said before the echo. */
+  prompted(text: string): void
+}
+
+export function mistralTranslator(opts: { stream?: boolean } = {}): MistralTranslator {
+  /** The text being written: one message (or thought) at a time, by `messageId`. */
+  let open: { kind: "message" | "thinking"; id: string | null; text: string; update: Obj } | null = null
+  /** Tool calls already settled — an update after the result says nothing new. */
+  const settled = new Set<string>()
+  /** The human's own words this session, to tell Vibe's own title from a copy of the prompt. */
+  const said: string[] = []
+  let lastTitle: string | null = null
+  const window = { used: null as number | null, size: null as number | null }
+  let costUsd: number | null = null
+
+  function flush(): ContractLine[] {
+    if (!open) return []
+    const { kind, text, update } = open
+    open = null
+    const clipped = clip(text)
+    if (!clipped.text.trim()) return []
+    // The chunks joined: what Vibe wrote, in one piece — the event's own words.
+    const source = { ...update, content: { type: "text", text } }
+    return kind === "message"
+      ? [{ type: "message", role: "assistant", text: clipped.text, truncated: clipped.truncated, source }]
+      : [{ type: "thinking", text: clipped.text, truncated: clipped.truncated, source }]
+  }
+
+  function chunk(kind: "message" | "thinking", update: Obj): ContractLine[] {
+    const text = typeof obj(update.content).text === "string" ? (obj(update.content).text as string) : ""
+    const id = str(update.messageId)
+    const out: ContractLine[] = []
+    const fresh = !open || open.kind !== kind || open.id !== id
+    if (fresh) {
+      out.push(...flush())
+      open = { kind, id, text: "", update }
+    }
+    open!.text += text
+    if (kind === "message" && opts.stream && text) out.push({ type: "message.delta", text, ...(fresh ? { start: true } : {}) })
+    return out
+  }
+
+  function result(update: Obj, id: string): ContractLine[] {
+    settled.add(id)
+    const raw = update.rawOutput
+    const text = contentText(update.content) || (typeof raw === "string" ? raw : raw === undefined ? "" : JSON.stringify(raw))
+    const { text: output, truncated } = clip(text)
+    return [{ type: "tool.result", callId: id, isError: update.status === "failed", output, truncated, source: update }]
+  }
+
+  const self: MistralTranslator = {
+    window,
+    model: null,
+    prompted(text) {
+      said.push(text)
+    },
+    update(update) {
+      switch (update.sessionUpdate) {
+        case "agent_message_chunk":
+          return chunk("message", update)
+        case "agent_thought_chunk":
+          return chunk("thinking", update)
+        case "user_message_chunk": {
+          // The human's own turn, echoed: the platform already has it. Kept to read the title by.
+          const text = obj(update.content).text
+          if (typeof text === "string") said.push(text)
+          return []
+        }
+        case "tool_call": {
+          const id = str(update.toolCallId)
+          const { text: input, truncated } = clip(update.rawInput ?? { title: update.title })
+          const out: ContractLine[] = [...flush(), { type: "tool.call", callId: id, name: toolName(update), input, truncated, source: update }]
+          if (id && (update.status === "completed" || update.status === "failed")) out.push(...result(update, id))
+          return out
+        }
+        case "tool_call_update": {
+          const id = str(update.toolCallId)
+          if (!id || settled.has(id) || (update.status !== "completed" && update.status !== "failed")) return []
+          return [...flush(), ...result(update, id)]
+        }
+        case "plan": {
+          const steps = (Array.isArray(update.entries) ? update.entries : [])
+            .map((e) => obj(e))
+            .map((e) => ({ text: clip(e.content).text, status: typeof e.status === "string" ? e.status : "pending" }))
+            .filter((s) => s.text)
+          return steps.length > 0 ? [...flush(), { type: "plan", steps, source: update }] : []
+        }
+        case "usage_update": {
+          window.used = num(update.used) ?? window.used
+          window.size = num(update.size) ?? window.size
+          const cost = obj(update.cost)
+          if (cost.currency === "USD" && num(cost.amount) !== null) costUsd = num(cost.amount)
+          return []
+        }
+        case "session_info_update": {
+          // Vibe names a session after the first prompt until it has a title of its own: only the
+          // latter is a name worth saying (the platform already has the prompt's).
+          // latter is a name worth saying (the platform already has the prompt's). Measured: the
+          // provisional one is the whole prompt, then « … ».
+          const title = str(update.title)?.replace(/\s+/g, " ").trim().slice(0, 200) ?? null
+          const stem = title?.replace(/(…|\.\.\.)$/, "").trim()
+          if (!title || !stem || title === lastTitle || said.some((s) => s.replace(/\s+/g, " ").trim().startsWith(stem))) return []
+          lastTitle = title
+          return [{ type: "session.title", title, source: update }]
+        }
+        // The session's slash commands, its mode, its options: Vibe's UI state, not the session's.
+        case "available_commands_update":
+        case "current_mode_update":
+        case "config_option_update":
+          return []
+      }
+      return [...flush(), { type: "raw", json: update }]
+    },
+    ended(response) {
+      const out = flush()
+      const error = response.error ? obj(response.error) : null
+      if (error) {
+        const message = clip(str(error.message) ?? "Mistral Vibe failed the turn.").text
+        const limit = error.code === RATE_LIMITED ? { kind: "rate", status: 429, message, resetsAt: null } : null
+        out.push({ type: "session.ended", status: "failed", stopReason: null, summary: message, ...(limit ? { limit } : {}), source: response })
+        return out
+      }
+      const res = obj(response.result)
+      const usage = obj(res.usage)
+      if (Object.keys(usage).length > 0 || window.used !== null) {
+        out.push({
+          type: "usage",
+          scope: "session",
+          model: self.model,
+          inputTokens: num(usage.inputTokens),
+          outputTokens: num(usage.outputTokens),
+          cacheReadTokens: num(usage.cachedReadTokens),
+          contextTokens: window.used,
+          contextWindow: window.size,
+          costUsd,
+          source: response,
+        })
+      }
+      const stopReason = str(res.stopReason)
+      if (stopReason === "end_turn") {
+        out.push({ type: "session.ended", status: "succeeded", stopReason, summary: "", source: response })
+      } else {
+        // `cancelled` (an interrupt), `max_tokens`, `max_turn_requests`, `refusal`: the turn did
+        // not finish its work, whatever the reason — the same reading as Claude's and Codex's.
+        const summary = stopReason === "cancelled" ? "Interrupted." : `Mistral Vibe stopped the turn (${stopReason ?? "no reason given"}).`
+        out.push({ type: "session.ended", status: "failed", stopReason, summary, source: response })
+      }
+      return out
+    },
+  }
+  return self
+}

package/src/agent-runners/mistral.mjs

@@ -0,0 +1,355 @@
+#!/usr/bin/env node
+// The Mistral runner (RFC 0048): same contract as `claude.mjs` and `codex.mjs`, over **Mistral
+// Vibe**, which has no Node SDK — so the runner is an ACP client (Agent Client Protocol, JSON-RPC
+// 2.0 on stdio) of `vibe-acp`, the binary the `spunto-agent-mistral` feature installs. Bundled
+// with its adapter by the platform, like every runner.
+//
+//   node mistral.mjs run [--model <alias>] [--resume <session id>]
+//   stdin   {"type":"user","text"} · {"type":"interrupt","id"} · {"type":"title",…} (ignored:
+//           Vibe names its sessions itself, and the runner says so when it does) ; closed = the
+//           session ends after its turn
+//   stdout  **our** vocabulary (`agent-v1`): each `session/update` and each turn's answer read
+//           here (`./mistral/adapter.ts`), with the ACP message itself as `source`
+//   env     SPUNTO_AGENT_OPTIONS — the task's parameters (`./catalogs.ts`): `{"thinking":"high"}`
+//           SPUNTO_AGENT_MCP — the org's MCP servers, through the platform's gateway (RFC 0049)
+//           SPUNTO_AGENT_STREAM — "1": also print each chunk of a message as it is written
+//   exit    0 once the input is closed and the last turn is over, 1 when the session could not run
+//
+// One `vibe-acp` process is the whole session: it stays alive between turns, a message sent during
+// a turn waits for it to end (ACP runs one prompt at a time), and an interrupt is ACP's own
+// `session/cancel` — the tool in flight is stopped, the turn ends `cancelled`, the session listens.
+//
+// Credentials: `MISTRAL_API_KEY` as a secret, read by Vibe itself — or a `vibe --setup` done by
+// hand in the machine's terminal, which Vibe keeps in `~/.vibe`.
+
+import { spawn } from "node:child_process"
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+import { createInterface } from "node:readline"
+import { mistralTranslator } from "./mistral/adapter"
+
+const ACP = process.env.SPUNTO_VIBE_ACP || "/opt/spunto/agents/mistral/bin/vibe-acp"
+
+function out(obj) {
+  process.stdout.write(`${JSON.stringify(obj)}\n`)
+}
+
+/** A failure the platform can read: the turn ends, failed, saying why — then a non-zero exit. */
+function fail(message) {
+  out({ type: "session.ended", status: "failed", stopReason: null, summary: message })
+  child?.kill()
+  process.exit(1)
+}
+
+function parseArgs(argv) {
+  const [verb, ...rest] = argv
+  if (verb !== "run") fail(`mistral runner: unknown verb "${verb ?? ""}" (expected "run")`)
+  const args = {}
+  for (let i = 0; i < rest.length; i++) {
+    const flag = rest[i]
+    if (flag === "--model" || flag === "--resume") {
+      const value = rest[++i]
+      if (value) args[flag.slice(2)] = value
+    } else {
+      fail(`mistral runner: unknown flag "${flag}"`)
+    }
+  }
+  return args
+}
+
+let child = null
+const args = parseArgs(process.argv.slice(2))
+
+/** The task's parameters. Checked by the platform against the catalog; read defensively all the same. */
+function readOptions() {
+  try {
+    const parsed = JSON.parse(process.env.SPUNTO_AGENT_OPTIONS || "{}")
+    return parsed && typeof parsed === "object" ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+const params = readOptions()
+
+/**
+ * The org's MCP servers (RFC 0049), as ACP's `mcpServers`: Streamable HTTP servers on the
+ * platform's gateway, with the machine's identity as the bearer — never the vendor's token.
+ */
+function readMcpServers() {
+  let listed
+  try {
+    listed = JSON.parse(process.env.SPUNTO_AGENT_MCP || "[]")
+  } catch {
+    return []
+  }
+  const api = (process.env.SPUNTO_API_URL || "").replace(/\/$/, "")
+  const token = process.env.SPUNTO_WORKER_TOKEN
+  if (!Array.isArray(listed) || !api || !token) return []
+  return listed
+    .filter((s) => s && typeof s.name === "string" && typeof s.path === "string")
+    .map((s) => ({ type: "http", name: s.name, url: `${api}${s.path}`, headers: [{ name: "Authorization", value: `Bearer ${token}` }] }))
+}
+
+/**
+ * Trust the task's checkout, as Vibe's own prompt would on a first run: an untrusted folder's
+ * `AGENTS.md`, `.vibe/` config and skills are ignored — the session would not behave like the CLI
+ * in that repository. Nobody is there to answer the prompt, and the machine is the task's.
+ */
+function trustCwd(cwd) {
+  try {
+    const home = process.env.VIBE_HOME || join(homedir(), ".vibe")
+    const file = join(home, "trusted_folders.toml")
+    const text = existsSync(file) ? readFileSync(file, "utf8") : ""
+    const entry = JSON.stringify(cwd)
+    if (text.includes(entry)) return
+    mkdirSync(home, { recursive: true })
+    const list = /^trusted\s*=\s*\[/m
+    writeFileSync(file, list.test(text) ? text.replace(list, (m) => `${m}${entry}, `) : `trusted = [${entry}]\n${text}`)
+  } catch (err) {
+    process.stderr.write(`mistral runner: could not trust ${cwd}: ${err?.message ?? err}\n`)
+  }
+}
+
+/**
+ * A session being resumed is the platform's to hold, so any `vibe-acp` still holding it is let go.
+ * Measured: after the API restarted, it resumed a task's session in a new runner while the old one
+ * still ran — and Vibe opens a session once (an OS lock, `logs/session/active/<id>.lock`), so the
+ * new one failed on "Session is already open". The holder is named in the lease's diagnostic file;
+ * it is stopped only if it is a Vibe (a pid can be reused), and its runner exits with it.
+ */
+async function releaseSession(id) {
+  const home = process.env.VIBE_HOME || join(homedir(), ".vibe")
+  const lease = join(home, "logs", "session", "active", `${id}.lock.json`)
+  let pid
+  try {
+    pid = JSON.parse(readFileSync(lease, "utf8")).process_id
+  } catch {
+    return
+  }
+  if (!Number.isInteger(pid) || pid === process.pid) return
+  try {
+    if (!readFileSync(`/proc/${pid}/cmdline`, "utf8").includes("vibe")) return
+    process.kill(pid, "SIGTERM")
+  } catch {
+    return // gone already
+  }
+  process.stderr.write(`mistral runner: stopped the Vibe (pid ${pid}) still holding session ${id}\n`)
+  for (let i = 0; i < 50; i++) {
+    try {
+      process.kill(pid, 0)
+    } catch {
+      return
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100))
+  }
+  try {
+    process.kill(pid, "SIGKILL")
+  } catch {}
+}
+
+const cwd = process.cwd()
+trustCwd(cwd)
+if (args.resume) await releaseSession(args.resume)
+
+// `vibe-acp`, or a test double of it (`.mjs`, run on this Node).
+child = /\.m?js$/.test(ACP)
+  ? spawn(process.execPath, [ACP], { stdio: ["pipe", "pipe", "pipe"] })
+  : spawn(ACP, [], { stdio: ["pipe", "pipe", "pipe"] })
+
+// Vibe logs freely on stderr; the tail is kept to say why, should it die.
+let stderrTail = ""
+child.stderr.on("data", (d) => {
+  stderrTail = (stderrTail + d).slice(-4000)
+})
+child.on("error", (err) => {
+  fail(`mistral runner: could not start Mistral Vibe at ${ACP} — is the project's image built with the Mistral app's feature? (${err?.message ?? err})`)
+})
+let closing = false
+child.on("exit", (code) => {
+  if (closing) return
+  const tail = stderrTail.trim().split("\n").slice(-5).join("\n")
+  fail(`mistral runner: Mistral Vibe exited (${code}) during the session${tail ? `: ${tail}` : ""}`)
+})
+
+// ── JSON-RPC over the child's stdio ─────────────────────────────────────────────────────────────
+
+let nextId = 0
+const waiting = new Map()
+/**
+ * `session/update`s are dropped until the first turn: while Vibe replays a loaded session's history
+ * (`session/load` — the platform has it), and while the runner sets the session up (a model change
+ * is announced as a pseudo tool call, `checkpoint-model-change`, which no one asked for).
+ */
+let quiet = true
+const translate = mistralTranslator({ stream: process.env.SPUNTO_AGENT_STREAM === "1" })
+
+function send(message) {
+  child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", ...message })}\n`)
+}
+
+/** A request; resolves with the whole response, `{ result }` or `{ error }`. */
+function request(method, params) {
+  const id = ++nextId
+  send({ id, method, params })
+  return new Promise((resolve) => waiting.set(id, resolve))
+}
+
+/** Vibe asking the client: permissions are granted (nobody is there to answer), the rest refused. */
+function answer(message) {
+  if (message.method === "session/request_permission") {
+    const options = Array.isArray(message.params?.options) ? message.params.options : []
+    const pick = options.find((o) => o.kind === "allow_always") ?? options.find((o) => o.kind === "allow_once")
+    send({ id: message.id, result: { outcome: pick ? { outcome: "selected", optionId: pick.optionId } : { outcome: "cancelled" } } })
+    return
+  }
+  send({ id: message.id, error: { code: -32601, message: `${message.method} is not offered by the Spunto runner` } })
+}
+
+createInterface({ input: child.stdout, crlfDelay: Infinity }).on("line", (line) => {
+  let message
+  try {
+    message = JSON.parse(line)
+  } catch {
+    return
+  }
+  if (!message || typeof message !== "object") return
+  if (message.method && message.id !== undefined && message.id !== null) return answer(message)
+  if (message.method === "session/update") {
+    const update = message.params?.update
+    // Only the window's figures are kept from the setup: they are the session's own.
+    if (update && (!quiet || update.sessionUpdate === "usage_update")) for (const l of translate.update(update)) out(l)
+    return
+  }
+  if (message.method) return // other notifications (`_vibe/…` extensions): Vibe's UI, not the session
+  const resolve = waiting.get(message.id)
+  if (resolve) {
+    waiting.delete(message.id)
+    resolve(message)
+  }
+})
+
+// ── The session ─────────────────────────────────────────────────────────────────────────────────
+
+const init = await request("initialize", {
+  protocolVersion: 1,
+  // No file system, no terminal: Vibe uses its own tools in the machine, where the task's work is.
+  clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+  clientInfo: { name: "spunto", title: "Spunto", version: "agent-v1" },
+})
+if (init.error) fail(`mistral runner: Mistral Vibe refused to start: ${init.error.message}`)
+
+const mcpServers = readMcpServers()
+let sessionId = args.resume ?? null
+let opened
+if (args.resume) {
+  opened = await request("session/load", { sessionId: args.resume, cwd, mcpServers })
+} else {
+  opened = await request("session/new", { cwd, mcpServers })
+  sessionId = opened.result?.sessionId ?? null
+}
+if (opened.error || !sessionId) {
+  const why = opened.error?.message ?? "no session id"
+  const hint = opened.error?.code === -32000 ? " — set MISTRAL_API_KEY in your secrets, or run `vibe --setup` in the machine's terminal" : ""
+  fail(`mistral runner: Mistral Vibe could not ${args.resume ? `resume session ${args.resume}` : "open a session"}: ${why}${hint}`)
+}
+
+/** The current value of one of the session's options (`model`, `thinking`, `mode`). */
+let configOptions = opened.result?.configOptions ?? []
+const optionValue = (id) => configOptions.find((o) => o?.id === id)?.currentValue ?? null
+
+async function setOption(configId, value, what) {
+  const res = await request("session/set_config_option", { sessionId, configId, value })
+  if (res.error) {
+    const choices = configOptions.find((o) => o?.id === configId)?.options?.map((o) => o.value) ?? []
+    fail(`mistral runner: ${what} "${value}" is not available here${choices.length ? ` — one of ${choices.join(", ")}` : ""} (${res.error.message})`)
+  }
+  configOptions = res.result?.configOptions ?? configOptions
+}
+
+// A task runs unattended in a disposable machine: every tool call approved, what
+// `bypassPermissions` is to Claude. Vibe's own name for it.
+await setOption("mode", "auto-approve", "Mode")
+if (args.model && optionValue("model") !== args.model) await setOption("model", args.model, "Model")
+// Vibe keeps a model's thinking level in its config: set on every session that asks for one.
+if (typeof params.thinking === "string" && params.thinking) await setOption("thinking", params.thinking, "Thinking")
+
+const model = optionValue("model") ?? args.model ?? null
+translate.model = model
+
+let announced = false
+function announce() {
+  if (announced) return
+  announced = true
+  quiet = false
+  out({ type: "session.started", harness: "mistral", model, sessionId, cwd, contextWindow: translate.window.size })
+}
+
+const pending = []
+let closed = false
+let inFlight = false
+let wake = null
+
+createInterface({ input: process.stdin, crlfDelay: Infinity })
+  .on("line", (line) => {
+    let msg
+    try {
+      msg = JSON.parse(line)
+    } catch {
+      return
+    }
+    if (!msg || typeof msg !== "object") return
+    if (msg.type === "user" && typeof msg.text === "string") {
+      pending.push(msg.text)
+      wake?.()
+    } else if (msg.type === "interrupt" && inFlight) {
+      cancel()
+    }
+  })
+  .on("close", () => {
+    closed = true
+    wake?.()
+  })
+
+/**
+ * ACP's cancel, a notification. Said again every second until the turn answers: one that lands
+ * before Vibe has started the turn would otherwise be lost, and the turn would run to its end.
+ */
+function cancel() {
+  const again = () => {
+    if (!inFlight) return clearInterval(timer)
+    send({ method: "session/cancel", params: { sessionId } })
+  }
+  const timer = setInterval(again, 1000)
+  again()
+}
+
+for (;;) {
+  if (pending.length === 0) {
+    if (closed) break
+    await new Promise((resolve) => (wake = resolve))
+    wake = null
+    continue
+  }
+  const text = pending.shift()
+  announce()
+  translate.prompted(text)
+  inFlight = true
+  const response = await request("session/prompt", { sessionId, prompt: [{ type: "text", text }] })
+  inFlight = false
+  for (const l of translate.ended(response)) out(l)
+}
+
+closing = true
+child.stdin.end()
+await new Promise((resolve) => {
+  const timer = setTimeout(() => {
+    child.kill()
+    resolve()
+  }, 5000)
+  child.once("exit", () => {
+    clearTimeout(timer)
+    resolve()
+  })
+})
+process.exit(0)

package/src/catalogs/index.ts

@@ -225,6 +225,13 @@ export const AVAILABLE_FEATURES: DevFeature[] = [
     description: "The Codex SDK and the Node its runner uses — injected by the Codex app",
     injected: true,
   },
+  {
+    id: "spunto-agent-mistral",
+    label: "Mistral Vibe (agent app)",
+    localScript: "spunto-agent-mistral.sh",
+    description: "Mistral Vibe (with its own Python) and the Node its runner uses — injected by the Mistral app",
+    injected: true,
+  },
   {
     // Always installed, whether or not it's picked here (lib/setup-script.ts § the two features
     // every worker image is made of): it's what creates the `vscode` user. Listed anyway so a

package/src/script/setup-script.ts

@@ -447,6 +447,15 @@ function buildFeatureInstallScript(ociRef: string, options?: Record<string, stri
 function buildLocalFeatureInstallScript(featureId: string, scriptFile: string): string | null {
   const scriptContent = localFeatureScript(scriptFile)
   if (!scriptContent) return null
+  return buildInlineFeatureInstallScript(featureId, scriptContent)
+}
+
+/**
+ * A feature whose install script the caller hands over as text — embedded in the recipe like a
+ * local one. What an app that serves its own feature gives (Spunto IDE's `ide.feature`, RFC 0059):
+ * no registry in between, and the recipe's text, so its key, moves with the script.
+ */
+function buildInlineFeatureInstallScript(featureId: string, scriptContent: string): string {
   const encoded = b64(scriptContent)
   return [
     `echo "[feature] ${featureId}: running local install script..."`,
@@ -468,11 +477,15 @@ function buildLocalFeatureInstallScript(featureId: string, scriptFile: string):
 export type ResolvedFeature = { id: string; script: string; ociRef?: string }
 
 function resolveFeatures(
-  features: { id: string; ociRef?: string; options?: Record<string, string> }[],
+  features: { id: string; ociRef?: string; options?: Record<string, string>; script?: string }[],
   warnId?: string,
 ): ResolvedFeature[] {
   const resolved: ResolvedFeature[] = []
   for (const f of features) {
+    if (f.script) {
+      resolved.push({ id: f.id, script: buildInlineFeatureInstallScript(f.id, f.script) })
+      continue
+    }
     const known = AVAILABLE_FEATURES.find((af) => af.id === f.id)
     if (known?.localScript) {
       const script = buildLocalFeatureInstallScript(f.id, known.localScript)
@@ -555,8 +568,14 @@ function commonUtilsOptions(): Record<string, string> {
  * Not strict: a base image where tmux won't install must still produce a usable worker, exactly as
  * the best-effort blocks it replaces did.
  */
-function spuntoPackOptions(params: { sshGatewayPublicKey?: string }): Record<string, string> {
-  return { installSshd: params.sshGatewayPublicKey ? "true" : "false" }
+function spuntoPackOptions(params: { sshGatewayPublicKey?: string; codeServerInPack?: boolean }): Record<string, string> {
+  return {
+    installSshd: params.sshGatewayPublicKey ? "true" : "false",
+    // A platform that installs the IDE apart (`spunto-ide`, Spunto's IDE app — RFC 0059) keeps the
+    // pack to its plumbing: tmux, dtach, sshd. Left out otherwise, so the recipe of a caller that
+    // never asks (spunto-lite) stays the same text.
+    ...(params.codeServerInPack === false ? { installCodeServer: "false" } : {}),
+  }
 }
 
 // The system-wide tmux configuration (mouse, OSC 52 clipboard, 50k scrollback, warm status bar)
@@ -689,11 +708,14 @@ export function defaultVscodeUserSettings(opts?: {
  * 1 → the hand-written blocks (vscode user, code-server, tmux, dtach, sshd).
  * 2 → common-utils + spunto-pack.
  * 3 → spunto-pack 1.1: the IDE wears Spunto's name, icons and themes (coderhammer/features).
+ * 4 → the IDE out of the pack (`codeServerInPack: false`): code-server comes from `spunto-ide`,
+ *     the feature of an IDE app, and only in the image of a project that has one (RFC 0059).
  */
-export const IMAGE_RECIPE_VERSION = 3
+export const IMAGE_RECIPE_VERSION = 4
 
 export function buildImageScript(params: {
-  features: { id: string; ociRef?: string; options?: Record<string, string> }[]
+  /** `script`: the feature's install script itself, embedded as is (an app that serves its own). */
+  features: { id: string; ociRef?: string; options?: Record<string, string>; script?: string }[]
   vscodeExtensions?: string[]
   sshGatewayPublicKey?: string
   /** Project-level DinD opt-in (base image bakes Docker itself, no feature). See projects.dind. */
@@ -703,6 +725,13 @@ export function buildImageScript(params: {
    * `--install-extension` calls below resolve ids against. Absent/unusable = Open VSX.
    */
   extensionsGallery?: string | null
+  /**
+   * Whether spunto-pack installs code-server, as it does by default. `false`: the pack is plumbing
+   * only (tmux, dtach, sshd), and code-server comes from a feature of the caller's — Spunto's IDE
+   * app puts `spunto-ide` among `features` for a project that has an IDE (RFC 0059). Extensions are
+   * then installed only if one of the features brought a code-server.
+   */
+  codeServerInPack?: boolean
 }): { script: string; hasDinD: boolean; resolvedFeatures: ResolvedFeature[]; steps: BuildStep[] } {
   const lines: string[] = ["set -e"]
 
@@ -818,6 +847,18 @@ export function buildImageScript(params: {
       )
     }
     extLines.push('echo "[build] Extensions installed"')
+    // code-server from a feature of the caller's (`codeServerInPack: false`): said plainly when none
+    // brought it, rather than one "command not found" per extension.
+    if (params.codeServerInPack === false) {
+      extLines.splice(
+        0,
+        0,
+        "if ! command -v code-server >/dev/null 2>&1; then",
+        '  echo "[build] No code-server in this image (no IDE feature) — VS Code extensions skipped"',
+        "else",
+      )
+      extLines.push("fi")
+    }
     const n = params.vscodeExtensions.length
     block("extensions", "VS Code extensions", "extensions", `${n} extension${n > 1 ? "s" : ""} · ${registry}`, extLines)
   }
@@ -1229,6 +1270,14 @@ export type StartScriptParams = {
    * assume). For a box where 8080 is taken by the host itself — a Blaxel sandbox's own API.
    */
   idePort?: number
+  /**
+   * Whether the box has an IDE to start — code-server, as it always had. `false`: a project without
+   * an IDE app (RFC 0059) — no extensions copied, no editor settings, no code-server loop; the
+   * terminal (tmux/dtach, the agent's) is not the IDE's and stays.
+   */
+  ide?: boolean
+  /** Settings the IDE app adds to the seeded defaults (`ide.config` → `userSettings`), over them. */
+  ideUserSettings?: Record<string, unknown>
 }
 
 /** code-server's port when the caller doesn't say otherwise. */
@@ -1243,6 +1292,7 @@ function idePortOf(port: number | undefined): number {
 export function buildStartScript(params: StartScriptParams): { script: string; hasDinD: boolean } {
   const { project, sshGatewayPublicKey, colorTabsByProject, extensionsGallery } = params
   const idePort = idePortOf(params.idePort)
+  const ide = params.ide !== false
   const homeDir = "/home/vscode"
   const username = "vscode"
 
@@ -1333,112 +1383,119 @@ export function buildStartScript(params: StartScriptParams): { script: string; h
     "done",
   )
 
-  // ── 4. Copy prebuilt extensions ───────────────────────────────────────────
-  push(
-    "",
-    'if [ -d ' + EXTENSIONS_DIR + ' ] && [ "$(ls -A ' + EXTENSIONS_DIR + ' 2>/dev/null)" ]; then',
-    `  mkdir -p ${homeDir}/.local/share/code-server/extensions`,
-    `  cp -rn ${EXTENSIONS_DIR}/. ${homeDir}/.local/share/code-server/extensions/ 2>/dev/null || true`,
-    `  chown -R ${username}:${username} ${homeDir}/.local`,
-    "fi",
-  )
+  // ── 4–5. The IDE: code-server, its extensions and settings (none without an IDE app) ───
+  if (ide) {
+    // ── 4. Copy prebuilt extensions ───────────────────────────────────────────
+    push(
+      "",
+      'if [ -d ' + EXTENSIONS_DIR + ' ] && [ "$(ls -A ' + EXTENSIONS_DIR + ' 2>/dev/null)" ]; then',
+      `  mkdir -p ${homeDir}/.local/share/code-server/extensions`,
+      `  cp -rn ${EXTENSIONS_DIR}/. ${homeDir}/.local/share/code-server/extensions/ 2>/dev/null || true`,
+      `  chown -R ${username}:${username} ${homeDir}/.local`,
+      "fi",
+    )
 
-  // ── 4b. Seed code-server user settings (no-clobber, stays user-overridable) ─
-  // Reordered window.title + per-project window color make parallel worker tabs
-  // tellable apart at a glance (see defaultVscodeUserSettings). Written no-clobber
-  // (guarded on the file, not `cp -n`) so a user's own settings.json survives restarts.
-  const vscodeSettings = JSON.stringify(
-    defaultVscodeUserSettings({ projectName: project.name, colorByProject: colorTabsByProject }),
-    null,
-    2,
-  )
-  push(
-    "",
-    `mkdir -p ${homeDir}/.local/share/code-server/User`,
-    `if [ ! -f ${homeDir}/.local/share/code-server/User/settings.json ]; then`,
-    `  echo ${JSON.stringify(b64(vscodeSettings))} | base64 -d > ${homeDir}/.local/share/code-server/User/settings.json`,
-    `  chown -R ${username}:${username} ${homeDir}/.local`,
-    "fi",
-  )
+    // ── 4b. Seed code-server user settings (no-clobber, stays user-overridable) ─
+    // Reordered window.title + per-project window color make parallel worker tabs
+    // tellable apart at a glance (see defaultVscodeUserSettings). Written no-clobber
+    // (guarded on the file, not `cp -n`) so a user's own settings.json survives restarts.
+    const vscodeSettings = JSON.stringify(
+      { ...defaultVscodeUserSettings({ projectName: project.name, colorByProject: colorTabsByProject }), ...params.ideUserSettings },
+      null,
+      2,
+    )
+    push(
+      "",
+      `mkdir -p ${homeDir}/.local/share/code-server/User`,
+      `if [ ! -f ${homeDir}/.local/share/code-server/User/settings.json ]; then`,
+      `  echo ${JSON.stringify(b64(vscodeSettings))} | base64 -d > ${homeDir}/.local/share/code-server/User/settings.json`,
+      `  chown -R ${username}:${username} ${homeDir}/.local`,
+      "fi",
+    )
 
-  // ── 4c. Restore the user's PORT secret for code-server's own terminal panel ─
-  // code-server reads $PORT to override --bind-addr (see § 5 below), so its
-  // whole process tree — including the integrated terminal it spawns — inherits
-  // PORT=<idePort> unless corrected. `terminal.integrated.env.linux` lets VS Code
-  // inject env overrides into terminals it spawns without touching the server
-  // process itself, so a `PORT` project secret still reaches the user's shell.
-  // Uses code-server's own bundled node (guaranteed present regardless of the
-  // devcontainer base image) since jq/node aren't guaranteed there.
-  const seedTerminalPortEnv = [
-    "const fs = require('fs')",
-    "const path = process.env.MP_SETTINGS_PATH",
-    "let settings = {}",
-    "try { settings = JSON.parse(fs.readFileSync(path, 'utf8')) } catch {}",
-    "settings['terminal.integrated.env.linux'] = { ...settings['terminal.integrated.env.linux'], PORT: process.env.MP_ORIGINAL_PORT }",
-    "fs.writeFileSync(path, JSON.stringify(settings, null, 2))",
-  ].join("\n")
-  const seedTerminalPortEnvEncoded = b64(seedTerminalPortEnv)
+    // ── 4c. Restore the user's PORT secret for code-server's own terminal panel ─
+    // code-server reads $PORT to override --bind-addr (see § 5 below), so its
+    // whole process tree — including the integrated terminal it spawns — inherits
+    // PORT=<idePort> unless corrected. `terminal.integrated.env.linux` lets VS Code
+    // inject env overrides into terminals it spawns without touching the server
+    // process itself, so a `PORT` project secret still reaches the user's shell.
+    // Uses code-server's own bundled node (guaranteed present regardless of the
+    // devcontainer base image) since jq/node aren't guaranteed there.
+    const seedTerminalPortEnv = [
+      "const fs = require('fs')",
+      "const path = process.env.MP_SETTINGS_PATH",
+      "let settings = {}",
+      "try { settings = JSON.parse(fs.readFileSync(path, 'utf8')) } catch {}",
+      "settings['terminal.integrated.env.linux'] = { ...settings['terminal.integrated.env.linux'], PORT: process.env.MP_ORIGINAL_PORT }",
+      "fs.writeFileSync(path, JSON.stringify(settings, null, 2))",
+    ].join("\n")
+    const seedTerminalPortEnvEncoded = b64(seedTerminalPortEnv)
 
-  push(
-    "",
-    'if [ -n "${PORT:-}" ]; then',
-    "  _mp_cs_bin=$(command -v code-server 2>/dev/null || true)",
-    '  if [ -n "$_mp_cs_bin" ]; then',
-    '    _mp_cs_bin=$(readlink -f "$_mp_cs_bin" 2>/dev/null || echo "$_mp_cs_bin")',
-    '    _mp_cs_node="$(dirname "$(dirname "$_mp_cs_bin")")/lib/node"',
-    '    if [ -x "$_mp_cs_node" ]; then',
-    `      mkdir -p ${homeDir}/.local/share/code-server/User`,
-    `      echo ${JSON.stringify(seedTerminalPortEnvEncoded)} | base64 -d > ${homeDir}/.mp_seed_terminal_port.js`,
-    `      MP_ORIGINAL_PORT="$PORT" MP_SETTINGS_PATH="${homeDir}/.local/share/code-server/User/settings.json" "$_mp_cs_node" ${homeDir}/.mp_seed_terminal_port.js`,
-    `      rm -f ${homeDir}/.mp_seed_terminal_port.js`,
-    `      chown -R ${username}:${username} ${homeDir}/.local`,
-    "    fi",
-    "  fi",
-    "fi",
-  )
+    push(
+      "",
+      'if [ -n "${PORT:-}" ]; then',
+      "  _mp_cs_bin=$(command -v code-server 2>/dev/null || true)",
+      '  if [ -n "$_mp_cs_bin" ]; then',
+      '    _mp_cs_bin=$(readlink -f "$_mp_cs_bin" 2>/dev/null || echo "$_mp_cs_bin")',
+      '    _mp_cs_node="$(dirname "$(dirname "$_mp_cs_bin")")/lib/node"',
+      '    if [ -x "$_mp_cs_node" ]; then',
+      `      mkdir -p ${homeDir}/.local/share/code-server/User`,
+      `      echo ${JSON.stringify(seedTerminalPortEnvEncoded)} | base64 -d > ${homeDir}/.mp_seed_terminal_port.js`,
+      `      MP_ORIGINAL_PORT="$PORT" MP_SETTINGS_PATH="${homeDir}/.local/share/code-server/User/settings.json" "$_mp_cs_node" ${homeDir}/.mp_seed_terminal_port.js`,
+      `      rm -f ${homeDir}/.mp_seed_terminal_port.js`,
+      `      chown -R ${username}:${username} ${homeDir}/.local`,
+      "    fi",
+      "  fi",
+      "fi",
+    )
 
-  // ── 5. Start code-server as vscode ────────────────────────────────────────
-  // Write the restart-loop to a temp script so quoting stays clean.
-  // Single-quoted heredoc: $VARS are NOT expanded here, they expand when the script runs
-  // (env is inherited from the start script via `su vscode` without -l).
-  // Write the restart-loop using base64 to avoid heredoc issues in DinD contexts
-  // where dockerd startup can affect /tmp mount visibility for child processes.
-  // Script lives in home dir (persistent volume) rather than /tmp.
-  const codeServerLoop = [
-    "#!/bin/bash",
-    "export SHELL=$(command -v zsh 2>/dev/null || echo /bin/bash)",
-    // Makes the editor's own Extensions view search the same registry the picker and the image
-    // build used (org setting — see lib/extension-registry.ts). Nothing when the org is on Open VSX.
-    ...galleryExport(extensionsGallery),
-    // The IDE is Spunto's, not Coder's (spunto-pack rebrands the files): the name in the title,
-    // no "Deploy code-server for your team" on the welcome page, no "code-server vX is out"
-    // notification. Each flag only if this code-server knows it — an unknown one stops it dead.
-    '_mp_cs_flags=""',
-    "for _f in --app-name --disable-getting-started-override --disable-update-check; do",
-    '  code-server --help 2>/dev/null | grep -q -- "$_f" || continue',
-    '  case "$_f" in --app-name) _mp_cs_flags="$_mp_cs_flags --app-name Spunto" ;; *) _mp_cs_flags="$_mp_cs_flags $_f" ;; esac',
-    "done",
-    "while true; do",
-    '  VSCODE_PROXY_URI="${PUBLIC_PROTOCOL}://${WORKER_SLUG}-{{port}}.${BASE_DOMAIN}" \\',
-    // PORT is overridden here (not unset globally) so a project secret named
-    // PORT can't make code-server bind elsewhere. This also leaks PORT=<idePort>
-    // into code-server's own process tree (its integrated terminal included) —
-    // § 4c above restores the original value for that terminal specifically.
-    // apps/agent/src/terminal.ts (dashboard's separate terminal feature) is a
-    // different process tree entirely and was never affected.
-    `    PORT=${idePort} code-server --bind-addr 0.0.0.0:${idePort} --auth none $_mp_cs_flags /workspace 2>&1`,
-    '  echo "[start] code-server exited ($?), restarting in 3s..."',
-    "  sleep 3",
-    "done",
-  ].join("\n")
-  const codeServerEncoded = b64(codeServerLoop)
+    // ── 5. Start code-server as vscode ────────────────────────────────────────
+    // Write the restart-loop to a temp script so quoting stays clean.
+    // Single-quoted heredoc: $VARS are NOT expanded here, they expand when the script runs
+    // (env is inherited from the start script via `su vscode` without -l).
+    // Write the restart-loop using base64 to avoid heredoc issues in DinD contexts
+    // where dockerd startup can affect /tmp mount visibility for child processes.
+    // Script lives in home dir (persistent volume) rather than /tmp.
+    const codeServerLoop = [
+      "#!/bin/bash",
+      "export SHELL=$(command -v zsh 2>/dev/null || echo /bin/bash)",
+      // Makes the editor's own Extensions view search the same registry the picker and the image
+      // build used (org setting — see lib/extension-registry.ts). Nothing when the org is on Open VSX.
+      ...galleryExport(extensionsGallery),
+      // The IDE is Spunto's, not Coder's (spunto-pack rebrands the files): the name in the title,
+      // no "Deploy code-server for your team" on the welcome page, no "code-server vX is out"
+      // notification. Each flag only if this code-server knows it — an unknown one stops it dead.
+      '_mp_cs_flags=""',
+      "for _f in --app-name --disable-getting-started-override --disable-update-check; do",
+      '  code-server --help 2>/dev/null | grep -q -- "$_f" || continue',
+      '  case "$_f" in --app-name) _mp_cs_flags="$_mp_cs_flags --app-name Spunto" ;; *) _mp_cs_flags="$_mp_cs_flags $_f" ;; esac',
+      "done",
+      "while true; do",
+      '  VSCODE_PROXY_URI="${PUBLIC_PROTOCOL}://${WORKER_SLUG}-{{port}}.${BASE_DOMAIN}" \\',
+      // PORT is overridden here (not unset globally) so a project secret named
+      // PORT can't make code-server bind elsewhere. This also leaks PORT=<idePort>
+      // into code-server's own process tree (its integrated terminal included) —
+      // § 4c above restores the original value for that terminal specifically.
+      // apps/agent/src/terminal.ts (dashboard's separate terminal feature) is a
+      // different process tree entirely and was never affected.
+      `    PORT=${idePort} code-server --bind-addr 0.0.0.0:${idePort} --auth none $_mp_cs_flags /workspace 2>&1`,
+      '  echo "[start] code-server exited ($?), restarting in 3s..."',
+      "  sleep 3",
+      "done",
+    ].join("\n")
+    const codeServerEncoded = b64(codeServerLoop)
 
-  push(
-    ...banner("START: CODE-SERVER"),
-    `echo ${JSON.stringify(codeServerEncoded)} | base64 -d > ${homeDir}/.mp_codeserver.sh`,
-    `chmod +x ${homeDir}/.mp_codeserver.sh`,
-    `su ${username} -s /bin/bash -c "${homeDir}/.mp_codeserver.sh" &`,
-  )
+    push(
+      ...banner("START: CODE-SERVER"),
+      `echo ${JSON.stringify(codeServerEncoded)} | base64 -d > ${homeDir}/.mp_codeserver.sh`,
+      `chmod +x ${homeDir}/.mp_codeserver.sh`,
+      `su ${username} -s /bin/bash -c "${homeDir}/.mp_codeserver.sh" &`,
+    )
+  }
+
+  // No IDE: nothing else would keep the script — and so the project's process, which the agent
+  // reports as `running` only while it lives — waiting at the end. A sleeper does, in its place.
+  if (!ide) push("", "while true; do sleep 3600; done &")
 
   // ── 6. postStartCommand ───────────────────────────────────────────────────
   // Wait for Docker if feature entrypoints were started — regardless of whether