thincoder 0.12.62 → 0.12.64

package/src/acp/client-caps.mjs

@@ -0,0 +1,86 @@
+/**
+ * client-caps.mjs — `initialize` / `authenticate` handlers + the server-level
+ * client-capability snapshot (ACP-CLIENT.md §3.4 · §11.2 · §11.3).
+ *
+ * `initialize` is the protocol's ONLY capability-exchange point (schema:
+ * `InitializeRequest.clientCapabilities`). The snapshot written here is read once
+ * — by the auth-methods gate (this module) and the fs reverse-RPC gate
+ * (`bridge.mjs`) — and never mutated again (protocol semantics). Omitted
+ * capabilities are UNSUPPORTED (文档逐字「MUST treat all capabilities omitted in
+ * the initialize request as UNSUPPORTED」) — never optimistic defaults.
+ */
+import { ACP_ERRORS } from "./transport.mjs"
+
+/** Protocol versions this agent speaks (schema `ProtocolVersion`; v1 — §11.3 改法①). */
+export const SUPPORTED_PROTOCOL_VERSIONS = [1]
+
+/** Version negotiation (文档逐字): same version when supported, else the latest we support. */
+export function negotiateProtocolVersion(requested, supported = SUPPORTED_PROTOCOL_VERSIONS) {
+  const latest = Math.max(...supported)
+  return Number.isInteger(requested) && supported.includes(requested) ? requested : latest
+}
+
+/** `initialize.authMethods` entries (schema `AuthMethod` objects — `AuthMethodTerminal`
+ *  requires `id` + `name`). The `terminal` entry MUST be advertised **only when the client
+ *  enabled its terminal auth capability** (`clientCaps.auth.terminal === true`); otherwise
+ *  `[]`. `args` are APPENDED to the configured agent invocation (the descriptor cannot
+ *  provide a command) ⇒ the client actually launches `thincoder acp --login`. */
+export function authMethodsFor(clientCaps) {
+  if (clientCaps?.auth?.terminal !== true) return []
+  return [{
+    id: "terminal",
+    type: "terminal",
+    name: "Terminal login",
+    description: "Run `thincoder acp --login` in an interactive terminal to configure the provider API key.",
+    args: ["--login"],
+  }]
+}
+
+/**
+ * Build the initialize / authenticate handlers.
+ * @param {{ version: string, clientCaps: { current: object },
+ *           requireConfigured: () => { error?: object }, log?: (s: string) => void }} deps
+ *   `requireConfigured` = the shared credential gate (§11.5 — lives in handlers-session.mjs).
+ * @returns {Record<string, (params: object) => object>}
+ */
+export function createCapsHandlers({ version, clientCaps, requireConfigured, log = () => {} }) {
+  return {
+    initialize: (params) => {
+      const caps = params?.clientCapabilities && typeof params.clientCapabilities === "object" ? params.clientCapabilities : {}
+      clientCaps.current = caps // §3.4 — written once (initialize is the only exchange point)
+      log(`[acp] initialize — protocolVersion=${JSON.stringify(params?.protocolVersion)} auth.terminal=${caps.auth?.terminal === true}`)
+      return {
+        protocolVersion: negotiateProtocolVersion(params?.protocolVersion),
+        // 能力面如实声明（§11.3 改法③）：已实现的 loadSession + 四键 sessionCapabilities；
+        // promptCapabilities 全 false（本面不接 image/audio/embeddedContext——不虚报）；
+        // mcpCapabilities / additionalDirectories 省略 = 不支持（G7 / G4 本批不做）。
+        agentCapabilities: {
+          loadSession: true,
+          promptCapabilities: { image: false, audio: false, embeddedContext: false },
+          sessionCapabilities: { list: {}, resume: {}, delete: {}, close: {} },
+        },
+        authMethods: authMethodsFor(caps),
+        agentInfo: { name: "thincoder", version },
+      }
+    },
+
+    authenticate: (params) => {
+      // 契约形状（§11.2 改法③）：methodId 不属于**当前已宣告**的方法 → -32602；
+      // 凭据不可解析 → -32000；通过 → 空结果 `{}`（AuthenticateResponse 只有 `_meta`）。
+      // 注：契约禁止客户端以 `terminal` 调本方法——若客户端仍调且该法已宣告，本实现宽容放行。
+      const advertised = authMethodsFor(clientCaps.current)
+      const methodId = params?.methodId
+      if (!advertised.some((m) => m.id === methodId)) {
+        return {
+          error: {
+            ...ACP_ERRORS.INVALID_PARAMS,
+            message: `unknown auth method: ${String(methodId)} (advertised: ${advertised.map((m) => m.id).join(", ") || "none"})`,
+          },
+        }
+      }
+      const gate = requireConfigured()
+      if (gate.error) return gate
+      return {}
+    },
+  }
+}

package/src/acp/ext.mjs

@@ -0,0 +1,86 @@
+/**
+ * ext.mjs — ACP extension pull face (ACP-CLIENT.md §3.5): `checkpoint/*` + `memory/*`.
+ * **纯搬迁** from the former monolithic `acp.mjs` (cited block = 68 lines) + factory shape;
+ * zero semantics changed — only the credential gate is now the shared immediate predicate
+ * (§11.2 改法①) and `getCwd` / `log` come through `ctx`.
+ *
+ * Checkpoints are cwd-scoped (same store the TUI git tool uses); non-git cwds
+ * snapshot by full-directory copy instead of returning null.
+ * Memory reuses the same `~/.thincoder/memory.db` store the TUI does.
+ */
+import { join } from "node:path"
+import { configDir } from "@thincoder/core/config.mjs"
+import { createCheckpoint, listCheckpoints, rewind, isGitRepo } from "@thincoder/core/git/checkpoint.mjs"
+import { createMemory, list as memList, remove as memRemove } from "@thincoder/core/memory.mjs"
+import { ACP_ERRORS } from "./transport.mjs"
+
+/** Build the extension handlers. Shared state arrives via the single `ctx` (§3.5). */
+export function createExtHandlers(ctx) {
+  const { getCwd, requireConfigured } = ctx
+
+  return {
+    "checkpoint/create": async () => {
+      const gate = requireConfigured()
+      if (gate.error) return gate
+      const cp = await createCheckpoint(getCwd())
+      if (!cp) return { error: { ...ACP_ERRORS.INTERNAL, message: "checkpoint creation failed" } }
+      return { checkpoint: { id: cp.id, time: cp.time, files: cp.files, git: isGitRepo(getCwd()) } }
+    },
+
+    "checkpoint/list": async () => {
+      const gate = requireConfigured()
+      if (gate.error) return gate
+      const cps = await listCheckpoints(getCwd())
+      return { checkpoints: cps.map((c) => ({ id: c.id, time: c.time, files: (c.tracked?.length ?? 0) + (c.untracked?.length ?? 0), trackedCount: c.tracked?.length ?? 0, untrackedCount: c.untracked?.length ?? 0 })) }
+    },
+
+    "checkpoint/restore": async (params) => {
+      const gate = requireConfigured()
+      if (gate.error) return gate
+      if (!params.checkpointId || !params.path) {
+        return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: "checkpoint/restore requires checkpointId and path (single-file restore; full rewind is disabled)" } }
+      }
+      try {
+        await rewind(getCwd(), String(params.checkpointId), { path: String(params.path) })
+        return { restored: String(params.path) }
+      } catch (e) {
+        return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: e?.message ?? String(e) } }
+      }
+    },
+
+    "memory/list": async (params) => {
+      const gate = requireConfigured()
+      if (gate.error) return gate
+      const mem = ensureAcpMemory()
+      if (!mem) return { error: { ...ACP_ERRORS.INTERNAL, message: "memory unavailable" } }
+      const entries = await memList(mem, { type: params.type })
+      return { entries: entries.map((e) => ({ id: e.id, type: e.type, title: e.title, tags: e.tags ?? "", updatedAt: e.updatedAt ?? null })) }
+    },
+
+    "memory/remove": async (params) => {
+      const gate = requireConfigured()
+      if (gate.error) return gate
+      const id = Number(params.id)
+      if (!Number.isInteger(id) || id < 1) {
+        return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: `memory/remove requires a numeric id (got ${params.id})` } }
+      }
+      const mem = ensureAcpMemory()
+      if (!mem) return { error: { ...ACP_ERRORS.INTERNAL, message: "memory unavailable" } }
+      const ok = await memRemove(mem, id)
+      return ok ? { removed: id } : { error: { ...ACP_ERRORS.INVALID_PARAMS, message: `no memory entry #${id}` } }
+    },
+  }
+}
+
+/** Shared memory handle for ACP handlers (same ~/.thincoder store the TUI uses).
+ *  dbPath mirrors the TUI default (see cli/make-agent.mjs). */
+let _acpMemory = null
+function ensureAcpMemory() {
+  if (_acpMemory) return _acpMemory
+  try {
+    _acpMemory = createMemory({ dbPath: join(configDir, "memory.db") })
+    return _acpMemory
+  } catch {
+    return null // memory subsystem unavailable — handlers report it
+  }
+}

package/src/acp/handlers-session.mjs

@@ -0,0 +1,257 @@
+/**
+ * handlers-session.mjs — in-memory ACP session family (ACP-CLIENT.md §3.5):
+ * `session/{new,prompt,cancel,close,set_mode,set_config_option}` + `findSession` /
+ * `applyConfigOption` + the shared credential gate consumed by every gated handler
+ * across the four handler modules (§11.5).
+ *
+ * 认证门 = **凭据状态即时判据**（§11.2 改法① / D15——撤 `authenticated` 闩锁）：
+ * 受门 handler 首行求值，真 ⇒ 放行、假 ⇒ `-32000`。客户端可以不调 `authenticate`
+ * （契约逐字「**May** return an `auth_required` error … **if** the agent requires
+ * authentication」）。
+ */
+import { resolve } from "node:path"
+import { normalizeCwd, bindRecordStore, newSession, slotPath } from "@thincoder/core/session.mjs"
+import { PLAN_ENGINEERING_REFUSED } from "@thincoder/core/agent-tools/plan.mjs"
+import { ACP_ERRORS } from "./transport.mjs"
+
+/** ENG-PLAN-EXCLUSION（FR31 ② · E7「命令面逐面钉定」）：工程真值 = 核单源同键
+ *  `agent.config.agent.engineering`。 */
+const isEngineering = (agent) => agent?.config?.agent?.engineering === true
+
+/** Session-level config options exposed to clients — schema `SessionConfigOption.required = ["id","name"]`
+ *  (响应侧用 `id`；请求侧 `SetSessionConfigOptionRequest` 用 `configId`——不对称属契约本身 · §11.3 G2-8). */
+export const CONFIG_OPTIONS = [
+  { id: "model", name: "Model" },
+  { id: "thinking", name: "Thinking" },
+  { id: "mode", name: "Mode" },
+]
+
+/**
+ * Credential gate (§11.5 判据拆分 · 评审 #1). Evaluated per call — **no cross-call latch**.
+ * `isConfigured()` (boolean, same injection point as before) decides pass/deny; the sister
+ * probe `providerStatus()` → `{ ok, keyPresent, reason }` only picks the actionable message
+ * for a deny (it distinguishes "no key" from "key present but defaultModel unresolvable"):
+ *   ① `keyPresent === false`  ⇒ point at providers[].apiKey + `thincoder acp --login` (no reason glued in);
+ *   ② `keyPresent && !ok`     ⇒ name the reason verbatim — `defaultModelReason` 逐字含 "defaultModel"
+ *                               (§11.5: ② 必点名 `defaultModel`) + the same recovery paths.
+ * @param {{ isConfigured: () => boolean, providerStatus: () => { ok?: boolean, keyPresent?: boolean, reason?: string } }} deps
+ * @returns {() => { error?: object }} `{}` ⇒ the call may proceed.
+ */
+export function createRequireConfigured({ isConfigured, providerStatus }) {
+  return () => {
+    if (isConfigured()) return {}
+    let st = {}
+    try { st = providerStatus() ?? {} } catch { st = {} }
+    if (st.keyPresent !== true) {
+      return {
+        error: {
+          ...ACP_ERRORS.AUTH_REQUIRED,
+          message: `no provider API key configured — set providers[].apiKey in ~/.thincoder/config.json, or run "thincoder acp --login"`,
+        },
+      }
+    }
+    return {
+      error: {
+        ...ACP_ERRORS.AUTH_REQUIRED,
+        message: `credentials present but the session cannot be assembled: ${st.reason ?? "unknown provider reason"} (fix via /config → 默认模型, or run "thincoder acp --login")`,
+      },
+    }
+  }
+}
+
+/**
+ * Apply a session-level config option to the agent instance (memory only —
+ * the session's own runtime state, last-write-wins; not persisted to config.json).
+ * Returns true when the configId is known.
+ */
+export function applyConfigOption(agent, configId, value) {
+  switch (configId) {
+    case "model": {
+      if (typeof value !== "string" || !value.trim()) return false
+      if (!agent.provider) return false // nothing to configure
+      // Split on the FIRST colon only — model names may contain colons.
+      const ci = value.indexOf(":")
+      const provider = ci >= 0 ? value.slice(0, ci) : null
+      const model = (ci >= 0 ? value.slice(ci + 1) : value).trim()
+      if (provider && provider !== agent.provider.name) agent.provider.name = provider
+      agent.provider.model = model
+      return true
+    }
+    case "thinking": {
+      if (typeof value !== "boolean" || !agent.provider) return false
+      agent.provider.thinking = value ? { type: "enabled" } : { type: "disabled" }
+      return true
+    }
+    case "mode": {
+      if (value !== "plan" && value !== "normal") return false
+      agent.planMode = value === "plan"
+      return true
+    }
+    default:
+      return false
+  }
+}
+
+/**
+ * Build the in-memory session family. Shared state arrives via the single `ctx`
+ * (§3.5 — `{ getCwd, sessions, allocSessionId, notifyRef, requestRef, createSession,
+ * requireConfigured, log }`), so the id allocator and the slot family stay on one
+ * namespace.
+ */
+export function createSessionHandlers(ctx) {
+  const { getCwd, sessions, allocSessionId, notifyRef, requestRef, createSession, requireConfigured, log } = ctx
+
+  const findSession = (params) => {
+    const s = sessions.get(String(params?.sessionId))
+    if (!s) return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: `unknown session ${params?.sessionId}` } }
+    return { session: s }
+  }
+
+  return {
+    "session/new": async (params) => {
+      const gate = requireConfigured()
+      if (gate.error) return gate
+      if (params.cwd !== undefined && typeof params.cwd !== "string") {
+        return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: "cwd must be a string" } }
+      }
+      // Normalized comparison: resolve() collapses trailing slashes, and
+      // normalizeCwd().toLowerCase() makes the check case-insensitive on
+      // Windows (drive letter + path — a client sending "c:\\users\\…" vs
+      // process.cwd() "C:\Users\…" must match). The ternary guards against
+      // resolve(undefined) — it would coerce undefined to the literal
+      // "undefined" and resolve a nonsense path. Note: `requested` never
+      // feeds any path operation — the agent always runs in getCwd() — so
+      // a case-insensitive match on case-sensitive platforms is harmless.
+      const norm = (p) => normalizeCwd(p).toLowerCase()
+      const requested = params.cwd ? resolve(params.cwd) : getCwd()
+      if (norm(requested) !== norm(getCwd())) {
+        return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: `v1: cwd must equal the process working directory (${getCwd()})` } }
+      }
+      if (params.mcpServers?.length) {
+        log(`[acp] MCP forwarding is M2 scope — ignoring ${params.mcpServers.length} server(s)`)
+      }
+      try {
+        const id = allocSessionId()
+        const session = await createSession({ id, notify: notifyRef.current, request: requestRef.current, log })
+        // §11.5 装配后检查（兜底，与门互补）：门拦「key 缺失 / defaultModel 不可解析」；
+        // 本行拦「门放行但 provider 仍不可用」的残余（如 defaultModel 可解析而 provider 缺
+        // baseURL）——显式报错而**不建半死会话**（槽未认领、sessions 未登记——无半态）。
+        if (session?.agent?._providerInvalid) {
+          return {
+            error: {
+              ...ACP_ERRORS.AUTH_REQUIRED,
+              message: `session cannot be assembled: ${session.agent._providerInvalidReason ?? "provider unavailable"} (fix via /config → 默认模型, or run "thincoder acp --login")`,
+            },
+          }
+        }
+        // `id` is immutable after construction (baked into the callbacks) — never reassign.
+        // 2026-09-01 会诊 kimi/glm 🔴：立即认领独立槽（对齐 cmd-new）——否则首回合保存
+        // 走 _slot ??= activeSlot() → ensureActive 早退分支（slotSessions[active]===
+        // mySessionId 同进程恒真）→ 第二个会话拿到与第一个相同的槽号 → 双写同槽
+        // F2 互旋。getSessionId() 是进程级，_slot 是 agent 级——粒度错配必须在此切断。
+        session.agent._slot = await newSession(getCwd())
+        // TUI-OOM-ROOTCAUSE（SESSION.md §6.14）：新建槽绑定记录存储（baseHistory 空——
+        // identity 待固化）——与 /new 同语义
+        bindRecordStore(session.agent, { slotFile: slotPath(getCwd(), session.agent._slot), identity: session.agent._sessionStart ?? null, baseHistory: [] })
+        sessions.set(id, session)
+        // §11.3 G2-5：NewSessionResponse.required = ["sessionId"]（`id` / `configId` 键已收正）
+        return { sessionId: id, configOptions: [...CONFIG_OPTIONS] }
+      } catch (e) {
+        return { error: { code: ACP_ERRORS.INTERNAL.code, message: `failed to create session: ${e.message}` } }
+      }
+    },
+
+    "session/prompt": async (params) => {
+      const gate = requireConfigured()
+      if (gate.error) return gate
+      const found = findSession(params)
+      if (found.error) return found
+      // §11.3 G2-6：PromptRequest.required = ["sessionId","prompt"]（`prompt` = ContentBlock[]）——
+      // 读取位置由 `params.content` 收正为 `params.prompt`；取块策略不变（首个 text 块——G6 登记项）。
+      const blocks = Array.isArray(params?.prompt) ? params.prompt : []
+      const text = blocks.find((b) => b?.type === "text")?.text ?? ""
+      if (!text) return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: "prompt requires a text content block" } }
+      try {
+        await found.session.run(text)
+        return { stopReason: "end_turn" }
+      } catch (e) {
+        // Cancelled/interrupted turns are not errors on the wire.
+        if (e?.name === "AbortError" || e?.code === "ABORT_ERR") return { stopReason: "cancelled" }
+        return { error: { code: ACP_ERRORS.INTERNAL.code, message: e?.message ?? String(e) } }
+      }
+    },
+
+    "session/cancel": (params) => {
+      const gate = requireConfigured()
+      if (gate.error) return gate
+      const found = findSession(params)
+      if (found.error) return found
+      found.session.cancel()
+      return {}
+    },
+
+    "session/close": (params) => {
+      const gate = requireConfigured()
+      if (gate.error) return gate
+      // 未知会话静默返回 `{}`（既有语义，本批零改——会话族其余方法返 `unknown session`）。
+      const found = findSession(params)
+      if (!found.error) {
+        // Abort any in-flight turn first — the client is gone, the agent must
+        // stop consuming LLM tokens and emitting notifications.
+        found.session.cancel()
+        sessions.delete(String(params.sessionId))
+        log(`session ${params.sessionId} closed by client`)
+      }
+      return {}
+    },
+
+    "session/set_config_option": (params) => {
+      const gate = requireConfigured()
+      if (gate.error) return gate
+      const found = findSession(params)
+      if (found.error) return found
+      const { configId, value } = params
+      if (!configId || value === undefined) {
+        return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: "set_config_option requires configId and value" } }
+      }
+      // ENG-PLAN-EXCLUSION（FR31 ② / 评审轮 1 发现 #4 出口钉定）：工程模式 ⇒ plan 面**前置判**
+      // ⇒ 携共用文案的 INVALID_PARAMS。`applyConfigOption` 布尔契约零改（`false` 仍 = unknown
+      // configId——工程拒绝不经该路径，下方 `:unknown configId` 误导文案对 mode=plan 不再可达）；
+      // `mode:"normal"` 照常接受（唯一合法态，幂等）。
+      if (configId === "mode" && value === "plan" && isEngineering(found.session.agent)) {
+        return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: PLAN_ENGINEERING_REFUSED } }
+      }
+      const applied = applyConfigOption(found.session.agent, configId, value)
+      if (!applied) {
+        return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: `unknown configId: ${configId}` } }
+      }
+      // Last-write-wins on the internal state; notify the client of the change.
+      notifyRef.current("session/update", {
+        sessionId: String(params.sessionId),
+        update: { sessionUpdate: "config_option_update", configId, value },
+      })
+      return {}
+    },
+
+    "session/set_mode": (params) => {
+      const gate = requireConfigured()
+      if (gate.error) return gate
+      const found = findSession(params)
+      if (found.error) return found
+      if (params.mode !== "plan" && params.mode !== "normal") {
+        return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: "mode must be plan or normal" } }
+      }
+      // ENG-PLAN-EXCLUSION（FR31 ② / 同 #4）：工程模式 + `mode:"plan"` ⇒ 前置判 ⇒ 携共用文案
+      // 的 INVALID_PARAMS（状态零变、零通知）；`normal` 照常（幂等）。
+      if (params.mode === "plan" && isEngineering(found.session.agent)) {
+        return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: PLAN_ENGINEERING_REFUSED } }
+      }
+      found.session.agent.planMode = params.mode === "plan"
+      notifyRef.current("session/update", {
+        sessionId: String(params.sessionId),
+        update: { sessionUpdate: "current_mode_update", mode: params.mode },
+      })
+      return {}
+    },
+  }
+}

package/src/acp/handlers-slots.mjs

@@ -0,0 +1,196 @@
+/**
+ * handlers-slots.mjs — persisted-slot family (ACP-CLIENT.md §3.5 · §11.3):
+ * `session/{list,load,resume,delete}` + the #41 engineering-manifest predicate
+ * helpers (`slotEngineering` / `reattach`).
+ *
+ * id 命名空间边界（§11.3 · 评审 #7——本批只改字段名、不改语义）：本族按**持久化槽位号**
+ * 解析 `params.sessionId`（`Number(params.sessionId)`）；而 `session/prompt` / `cancel` /
+ * `close` / `set_*` 认的是 **ACP 会话 id**（入口分配器——与槽位号不同物，§6.1）⇒
+ * 把 `session/list` 的输出直喂 `session/prompt` 仍会 `unknown session`（原 G5，本批不做）。
+ */
+import { ACP_ERRORS } from "./transport.mjs"
+import { CONFIG_OPTIONS } from "./handlers-session.mjs"
+import { loadConfig } from "@thincoder/core/config.mjs"
+import { resolveEngineeringManifest } from "@thincoder/core/manifest.mjs"
+import { replayHistory } from "./bridge.mjs"
+import { listSlots, applySession, deleteSlot, loadSlotFile, slotOccupancy, loadManifest, saveManifest, getSessionId, newSession } from "@thincoder/core/session.mjs"
+
+/** Build the persisted-slot family. Shared state arrives via the single `ctx` (§3.5). */
+export function createSlotsHandlers(ctx) {
+  const { getCwd, sessions, allocSessionId, notifyRef, requestRef, createSession, requireConfigured, log } = ctx
+
+  /** #41 翻转族合值判据（MANIFEST.md §2.8 F3 触发条件口径 = §2.2 会话权威值）：「槽带
+   *  `engineering` 字段 ? 槽值 : config 回退」。本路装配期（`applySession` 之前）无会话
+   *  agent ⇒ 回退源 = 盘上 config（与装配产物同源：`defaultCreateSession` → `assembleAgent`
+   *  → `loadConfig`）。 */
+  const slotEngineering = (data) => data?.engineering !== undefined
+    ? data.engineering === true
+    : (() => { try { return loadConfig().agent?.engineering === true } catch { return false } })()
+
+  /** #41 装载后一行重估（F3 准翻列 / F4）：`applySession` 已按槽订正 config ⇒ 工程模式会话
+   *  就地判据（单源）+ 附着——缺档格 `writer:'main'` 建档；非工程模式零动作（零 manifest I/O）。
+   *  判据不通过 ⇒ 保持不附着（装载已发生——本行是「装载后订正」位，与入口门槛两分）+ 留痕。 */
+  const reattach = (ag) => {
+    if (ag?.config?.agent?.engineering !== true) return
+    const r = resolveEngineeringManifest(getCwd(), { writer: "main" })
+    if (r.ok) ag.manifest = r.manifest
+    else log(`[acp] engineering manifest not attached (${r.code}): ${r.message}`)
+  }
+
+  return {
+    "session/list": () => {
+      const gate = requireConfigured()
+      if (gate.error) return gate
+      const slots = listSlots(getCwd())
+      return {
+        // §11.3 G2-7：SessionInfo.required = ["sessionId","cwd"]（条目键 `id` 已收正）
+        sessions: slots.map((s) => ({
+          sessionId: String(s.slot),
+          cwd: getCwd(), // single-cwd model (design §4.5)
+          updatedAt: s.updatedAt ?? 0,
+          title: s.title ?? "",
+          messageCount: s.messageCount ?? 0,
+        })),
+      }
+    },
+
+    "session/load": async (params) => {
+      const gate = requireConfigured()
+      if (gate.error) return gate
+      const slot = Number(params.sessionId)
+      if (!Number.isInteger(slot) || slot < 1) {
+        return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: `invalid session id: ${params.sessionId}` } }
+      }
+      const data = loadSlotFile(getCwd(), slot)
+      if (!data) {
+        return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: `session ${slot} not found (corrupt or deleted)` } }
+      }
+      // 2026-08-31 会诊 deepseek 🟡（搬迁保留）：读槽走 session.mjs 共享 `loadSlotFile`（校验/
+      // 保现场/.tmp 回退与主路径一致）——本地实现此前无 .unreadable/.corrupted 保留。
+      // #41 先判（F3 合值 / F4 装配期判据）：目标槽合值 === true ⇒ 判据前置于 `createSession`
+      // （拒 ⇒ 走既有 ACP 错误通道、**不建会话**——无半态）；准 ⇒ 既有装载 + 下方重估。
+      if (slotEngineering(data)) {
+        const r = resolveEngineeringManifest(getCwd(), { writer: "main" })
+        if (!r.ok) {
+          return { error: { code: ACP_ERRORS.INTERNAL.code, message: `failed to load session ${slot}: ${r.message}` } }
+        }
+      }
+      try {
+        const id = allocSessionId()
+        const session = await createSession({ id, notify: notifyRef.current, request: requestRef.current, log })
+        // 2026-08-31 advisor round2 🟡：钉 _slot 前查活主——目标槽被另一活进程（CLI/另一
+        // IDE）占用时不得钉回（双方 sessionStart 一致 → F2 永不轮转 → 同槽 last-write-wins
+        // 静默互覆盖）。空闲则认领后钉回；占用则不钉 → 下次保存经 activeSlot 自然 fork
+        // 到新槽（与 switchToSlot 的"占用则 fork"语义对齐）。
+        const occ = slotOccupancy(getCwd(), slot)
+        // 2026-09-01 会诊 kimi/glm 🔴：同进程双会话同槽——slotOccupancy 排除本进程属主后，
+        // 同进程防护完全由 sameProcessPinned 承担：本进程另一 session 已钉该槽即视为占用
+        // （进程级属主无法区分 agent，双方 sessionStart 相同 → F2 永不触发 → 静默互覆盖）。
+        const sameProcessPinned = [...sessions.values()].some((s) => s.agent?._slot === slot)
+        const pinned = !occ.occupied && !sameProcessPinned
+        // TUI-OOM-ROOTCAUSE（SESSION.md §6.14）：钉槽（非占用）才绑定记录存储——
+        // 占用/fork 分支模式 F（首保存 fork 新槽后补绑）
+        applySession(session.agent, data, pinned ? { slot } : {})
+        reattach(session.agent)
+        if (pinned) {
+          const m = loadManifest(getCwd())
+          m.slotSessions ??= {}
+          m.slotSessions[slot] = getSessionId()
+          saveManifest(getCwd(), m)
+          session.agent._slot = slot
+        } else {
+          // 2026-09-01 advisor 🔴：占用时显式分配全新槽（fork）——原 `_slot = null` 的
+          // fork 会经 saveSession → activeSlot → ensureActive 分支1 早退（slotSessions
+          // [active] === mySessionId 同进程恒真）落回同进程 active 槽 → 两会话写同一槽
+          // 静默互覆盖。newSession 跳过活认领号/现存文件号，必定落到新槽。
+          session.agent._slot = await newSession(getCwd())
+        }
+        sessions.set(id, session)
+        // Replay the human line (role → chunk mapping, design §4.5) so the
+        // client renders the restored conversation.
+        replayHistory({ sessionId: id, notify: notifyRef.current, history: data.history, log })
+        log(`session ${slot} loaded as session ${id} (${data.history?.length ?? 0} messages replayed)${occ.occupied || sameProcessPinned ? ` — slot busy, forked to ${session.agent._slot}` : ""}`)
+        // §11.3：load/resume 响应 required = []（`id` / `cwd` 属多余键——同批收敛）
+        return { configOptions: [...CONFIG_OPTIONS] }
+      } catch (e) {
+        return { error: { code: ACP_ERRORS.INTERNAL.code, message: `failed to load session ${slot}: ${e.message}` } }
+      }
+    },
+
+    "session/resume": async (params) => {
+      const gate = requireConfigured()
+      if (gate.error) return gate
+      const slot = Number(params.sessionId)
+      if (!Number.isInteger(slot) || slot < 1) {
+        return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: `invalid session id: ${params.sessionId}` } }
+      }
+      const data = loadSlotFile(getCwd(), slot)
+      if (!data) {
+        return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: `session ${slot} not found (corrupt or deleted)` } }
+      }
+      // #41 先判（同 session/load——合值判据前置于 `createSession`；拒 ⇒ 不建会话）。
+      if (slotEngineering(data)) {
+        const r = resolveEngineeringManifest(getCwd(), { writer: "main" })
+        if (!r.ok) {
+          return { error: { code: ACP_ERRORS.INTERNAL.code, message: `failed to resume session ${slot}: ${r.message}` } }
+        }
+      }
+      try {
+        const id = allocSessionId()
+        const session = await createSession({ id, notify: notifyRef.current, request: requestRef.current, log })
+        // 2026-08-31 advisor round2 🟡：同 session/load——活主占用的槽不钉回（防同槽双写，
+        // 下次保存 fork 新槽）；空闲则认领后钉回。
+        const occ = slotOccupancy(getCwd(), slot)
+        // 2026-09-01 会诊 kimi/glm 🔴：同 session/load——同进程其他 session 已钉同槽视为占用 → fork
+        const sameProcessPinned = [...sessions.values()].some((s) => s.agent?._slot === slot)
+        const pinned = !occ.occupied && !sameProcessPinned
+        // TUI-OOM-ROOTCAUSE（SESSION.md §6.14）：同 load——钉槽才绑定（占用/fork 模式 F）
+        applySession(session.agent, data, pinned ? { slot } : {})
+        reattach(session.agent)
+        if (pinned) {
+          const m = loadManifest(getCwd())
+          m.slotSessions ??= {}
+          m.slotSessions[slot] = getSessionId()
+          saveManifest(getCwd(), m)
+          session.agent._slot = slot
+        } else {
+          // 2026-09-01 advisor 🔴：同 load——显式 newSession fork（_slot=null 的 fork 会
+          // 落回同进程 active 槽 → 两会话写同一槽静默互覆盖）
+          session.agent._slot = await newSession(getCwd())
+        }
+        sessions.set(id, session)
+        // resume: no history replay — the client keeps its own rendering.
+        log(`session ${slot} resumed as session ${id} (no replay)${occ.occupied || sameProcessPinned ? ` — slot busy, forked to ${session.agent._slot}` : ""}`)
+        return { configOptions: [...CONFIG_OPTIONS] }
+      } catch (e) {
+        return { error: { code: ACP_ERRORS.INTERNAL.code, message: `failed to resume session ${slot}: ${e.message}` } }
+      }
+    },
+
+    "session/delete": async (params) => {
+      const gate = requireConfigured()
+      if (gate.error) return gate
+      const slot = Number(params.sessionId)
+      if (!Number.isInteger(slot) || slot < 1) {
+        return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: `invalid session id: ${params.sessionId}` } }
+      }
+      // Only the persisted archive is removed; an active in-memory session
+      // with the same id keeps running (design §4.5).
+      if (!deleteSlot(getCwd(), slot)) {
+        return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: `session ${slot} not found` } }
+      }
+      // 2026-08-31 会诊 deepseek 🟡：被删槽的在存会话 _slot 仍钉着 → 下次保存会重建
+      // 文件并重注册（删后复活）。清空其 _slot，下次保存重新认领新槽。
+      // 2026-09-01 advisor round2 🔴：不能清 _slot 等下次保存——saveSession 走
+      // activeSlot → ensureActive 分支1 早退（slotSessions[active] === mySessionId 同
+      // 进程恒真）→ 落回同进程 active 槽（另一在存会话的槽）→ 两会话写同一槽静默
+      // 互覆盖（sessionStart 均 null → F2 永不轮转）。与 load/resume 同型修复：
+      // 立即 newSession 钉全新槽（跳过活认领号/现存文件号）。
+      for (const s of sessions.values()) {
+        if (s.agent?._slot === slot) s.agent._slot = await newSession(getCwd())
+      }
+      log(`session ${slot} archive deleted`)
+      return {}
+    },
+  }
+}