@sanqianx/claude-ai-workbench 0.13.2 → 0.13.4

package/packages/server/lib/workbench-service.js

@@ -1,1675 +1,1696 @@
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const crypto = require('node:crypto');
-const {
-  normalizeContext, normalizeAttachments, normalizeAgentId, normalizeEffort, cleanId, PERMISSION_MODES, AGENTS,
-} = require('../../contracts');
-const { snapshotEvents, subscribeNormalized } = require('./event-stream');
-const { SessionHistory } = require('./session-history');
-const { recoverClaudeHistory } = require('./claude-history-recovery');
-// The history reader and task identity load from the same legacy runtime
-// tree as every other runtime module: loadLegacyRuntime binds to the owning
-// distribution, so a packaged server loads them from its own legacy tree and
-// a missing file fails the public entry instead of borrowing source code.
-const { loadLegacyRuntime } = require('./runtime-loader');
-const { createNativeTaskHistoryReader } = loadLegacyRuntime('native-task-history-reader');
-const { createNativeTaskRef } = loadLegacyRuntime('task-identity');
-
-const ACTIVE_STATES = new Set(['created', 'spawning', 'running', 'thinking', 'tool-running', 'pending-permission']);
-
-// Native fact rows are durable-by-contract: they go through the receipt
-// path (write + fsync) so nothing is ever built on facts that still live
-// only in memory. Plain chat events keep the batched append path.
-const NATIVE_FACT_TYPES = new Set(['claude/native-trace', 'claude/native-task-state', 'claude/native-task-transcript']);
-
-const DELTA_TYPES = new Set(['claude/text-delta', 'claude/thinking-delta']);
-
-// The same native fact as the committed row, ignoring fields that
-// legitimately differ between a journaled row and an in-memory replay of it.
-function canonicalNativeFact(event) {
-  const ordered = {};
-  for (const key of Object.keys(event || {}).sort()) {
-    if (key === 'at' || key === 'sequence' || key === 'sessionId' || key === 'contextId') continue;
-    ordered[key] = event[key];
-  }
-  return JSON.stringify(ordered);
-}
-
-// The earliest buffered same-id delta sequence a merged durable row is
-// proven to cover. Rows written since compaction kept provenance carry
-// compactFrom and are trusted as-is; older archives only admit the coverage
-// reading when a sequence gap exists AND the buffer's own fragments form a
-// strict prefix of the merged text — otherwise the row is a continuation
-// delta and must be appended, not substituted.
-function compactionCoverage(buffered, durable, lastBufferedSequence) {
-  const declared = Number(durable && durable.compactFrom);
-  if (Number.isSafeInteger(declared) && declared > 0) return declared;
-  const sequence = Number(durable && durable.sequence);
-  if (!Number.isSafeInteger(sequence) || sequence <= 0) return null;
-  if (!Number.isFinite(lastBufferedSequence) || sequence <= lastBufferedSequence + 1) return null;
-  let prefix = '';
-  let earliest = null;
-  for (const event of buffered) {
-    if (!event || event.type !== durable.type || event.id !== durable.id) continue;
-    const own = Number(event.sequence);
-    if (!Number.isSafeInteger(own) || own <= 0 || own >= sequence) continue;
-    prefix += String(event.text || '');
-    if (earliest === null || own < earliest) earliest = own;
-  }
-  if (earliest === null || prefix.length === 0) return null;
-  const text = String(durable.text || '');
-  return text.length > prefix.length && text.startsWith(prefix) ? earliest : null;
-}
-
-// The health identity accepts only a canonical persisted store id; nothing
-// volatile (port, PID, epoch) or malformed may pose as a store scope.
-const STORE_SCOPE_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
-
-class WorkbenchService {
-  constructor(options) {
-    this.runner = options.runner;
-    this.diagnostics = options.diagnostics || null;
-    this.knowledge = options.knowledge || null;
-    this.pendingInputs = new Map();
-    this.knowledgeBySession = new Map();
-    this.profiles = options.profiles;
-    this.contexts = options.contexts;
-    this.attachments = options.attachments;
-    this.projects = options.projects || null;
-    this.sessionArchive = options.sessionArchive || null;
-    this.uiPreferences = options.uiPreferences || null;
-    this.captureSettings = options.captureSettings || null;
-    this.conversationCapture = options.conversationCapture || null;
-    this.onCaptureSettingsSaved = options.onCaptureSettingsSaved || null;
-    this.agentDiscovery = options.agentDiscovery || null;
-    this.resolveRuntimeExecutable = options.resolveRuntimeExecutable || null;
-    this.modelContextWindows = options.modelContextWindows || null;
-    this.modelDetection = options.modelDetection || null;
-    // Trusted delegation stores: the immutable reservation ledger plus the
-    // write-once phase/claim journal. Null when the host wired none — the
-    // delegation APIs then answer explicit unavailability instead of
-    // pretending to run commands.
-    this.delegations = options.delegations || null;
-    // Per-service runtime generation: fresh for every WorkbenchService
-    // instance, constant for its lifetime, never persisted anywhere.
-    this.runtimeEpoch = crypto.randomUUID();
-    const injectedIdentity = options.storeIdentity || null;
-    const storeScope = injectedIdentity && injectedIdentity.available === true && typeof injectedIdentity.storeScope === 'string'
-      && STORE_SCOPE_PATTERN.test(injectedIdentity.storeScope)
-      ? injectedIdentity.storeScope
-      : null;
-    this.taskIdentity = Object.freeze({
-      storeScope,
-      runtimeEpoch: this.runtimeEpoch,
-      available: storeScope !== null,
-      errorCode: !storeScope && injectedIdentity ? injectedIdentity.errorCode || 'STORE_SCOPE_UNAVAILABLE' : null,
-    });
-    this.apiPrefix = String(options.apiPrefix || '/api/claude-workbench/v1').replace(/\/$/, '');
-    // Read from the synced manifest — a hardcoded literal here shipped 0.3.0
-    // in every /health response long after the actual release moved on.
-    this.version = options.version || require('../package.json').version;
-    this.maxSessions = Number(options.maxSessions || 50);
-    this.maxConcurrentRuns = Number(options.maxConcurrentRuns || 4);
-    this.testWorkspace = path.resolve(options.testWorkspace);
-    this.auditFile = options.auditFile;
-    this.historyRoot = options.historyRoot || path.join(path.dirname(this.auditFile || this.testWorkspace), 'session-history');
-    this.histories = new Map();
-    // Per-session native-fact committer closures, cached so every attach
-    // passes the SAME function reference: the runner's binding contract
-    // treats a different reference under the same identity as an owner
-    // conflict, and a naive closure-per-call would break idempotence.
-    this.nativeCommitters = new Map();
-    this.turnMonitors = new Map();
-    this.sessionAgents = new Map();
-    this.sessionRevision = 0;
-    this.sessionChangeLog = [];
-    this.sessionChangeListeners = new Set();
-    this.sessionSignatures = new Map();
-    const archiveRetentionDays = options.archiveRetentionDays === undefined ? 7 : Number(options.archiveRetentionDays);
-    this.archiveRetentionMs = Number.isFinite(archiveRetentionDays) && archiveRetentionDays > 0
-      ? archiveRetentionDays * 24 * 60 * 60 * 1000
-      : 0;
-    this.archiveSweeper = null;
-    // Archived sessions past the retention window are purged on boot and
-    // once a day for the lifetime of the process.
-    if (this.sessionArchive && this.archiveRetentionMs > 0) {
-      this.purgeExpiredArchivedSessions();
-      this.archiveSweeper = setInterval(() => {
-        try { this.purgeExpiredArchivedSessions(); } catch { /* retried next sweep */ }
-      }, Number(options.archiveSweepIntervalMs || 24 * 60 * 60 * 1000));
-      if (typeof this.archiveSweeper.unref === 'function') this.archiveSweeper.unref();
-    }
-    fs.mkdirSync(this.testWorkspace, { recursive: true });
-  }
-
-  health() {
-    // One observation point: both counters must come from the same
-    // listSessions snapshot, or a mid-mutation probe disagrees with itself
-    // and pays the full store scan twice.
-    const sessions = this.runner.listSessions({});
-    return {
-      status: 'ok', version: this.version, apiVersion: 'v1',
-      activeProcesses: this._activeCount(sessions), sessions: sessions.length,
-      time: new Date().toISOString(),
-      taskIdentity: { ...this.taskIdentity },
-      ...(this.conversationCapture ? { conversationCapture: { ...this.conversationCapture.status(), enabled: this.captureSettings?.read().terminalConversations === true } } : {}),
-    };
-  }
-
-  async runtime() {
-    let executable = null;
-    try { executable = await (this.resolveRuntimeExecutable ? this.resolveRuntimeExecutable() : this.runner.findClaudeExecutableForSdk()); } catch {}
-    const command = executable && (executable.cmd || executable);
-    return { runtime: 'claude-code', available: Boolean(command), executable: command ? path.basename(String(command)) : null, transport: 'agent-sdk' };
-  }
-
-  // Live availability probing when a discovery provider is wired in,
-  // otherwise fall back to what the injected runner can see.
-  listAgents() {
-    if (this.agentDiscovery) {
-      return { agents: Object.values(this.agentDiscovery()), scan: this.agentDiscovery.snapshot?.() };
-    }
-    let claudeAvailable = false;
-    try { const executable = this.runner.findClaudeExecutableForSdk(); claudeAvailable = Boolean(typeof executable === 'string' ? executable : executable?.cmd); } catch {}
-    return {
-      agents: Object.keys(AGENTS).map(id => {
-        const agent = AGENTS[id];
-        return {
-          id: agent.id, label: agent.label, transport: agent.transport,
-          authModes: [...agent.authModes],
-          capabilities: { ...agent.capabilities, generationParams: [...agent.capabilities.generationParams] },
-          available: id === 'claude-code' ? claudeAvailable : false,
-          version: null, reason: '',
-        };
-      }),
-    };
-  }
-
-  refreshAgents() {
-    if (this.agentDiscovery?.refresh) void this.agentDiscovery.refresh().catch(() => {});
-    return this.listAgents();
-  }
-
-  listProfiles() { return { profiles: this.profiles.list() }; }
-  getProfile(id) { return this.profiles.get(id); }
-  saveProfile(input, id) { return this.profiles.save(input, id); }
-  deleteProfile(id) { return this.profiles.delete(id); }
-  setCredential(id, credential) { return this.profiles.setCredential(id, credential); }
-
-  getCaptureSettings() {
-    if (!this.captureSettings) return { schema: 'capture-settings/v1', terminalConversations: false };
-    return this.captureSettings.read();
-  }
-
-  saveCaptureSettings(input = {}) {
-    if (!this.captureSettings) {
-      throw Object.assign(new Error('capture settings are not wired into this service'), { status: 501 });
-    }
-    const saved = this.captureSettings.save(input);
-    // Push the new scope into the driver immediately: sessions started after
-    // this call carry the matching AI_CODING_EVENT_BRIDGE_CAPTURE env.
-    if (typeof this.onCaptureSettingsSaved === 'function') this.onCaptureSettingsSaved(saved.terminalConversations);
-    return saved;
-  }
-
-  // ---- projects ----
-  listProjects() {
-    this._requireProjects();
-    return { projects: this.projects.list() };
-  }
-
-  getProject(id) {
-    this._requireProjects();
-    const projectId = cleanId(id, 'projectId');
-    const project = this.projects.get(projectId);
-    if (!project) throw Object.assign(new Error('project not found'), { status: 404 });
-    return project;
-  }
-
-  createProject(input = {}) {
-    this._requireProjects();
-    const project = this.projects.create(input);
-    this.contexts.register(project.id, project.rootPath);
-    this._audit('project-create', { projectId: project.id, rootPath: project.rootPath });
-    return project;
-  }
-
-  renameProject(id, input = {}) {
-    this._requireProjects();
-    const projectId = cleanId(id, 'projectId');
-    if (input.defaultAiProfileId) this.profiles.runtimeProfile(input.defaultAiProfileId);
-    const project = this.projects.update(projectId, input);
-    this._audit('project-rename', { projectId, name: project.name });
-    return project;
-  }
-
-  removeProject(id, options = {}) {
-    this._requireProjects();
-    const projectId = cleanId(id, 'projectId');
-    if (!this.projects.get(projectId)) throw Object.assign(new Error('project not found'), { status: 404 });
-    const keepSessions = options.keepSessions === true;
-    for (const session of this.runner.listSessions({ projectSlug: projectId })) {
-      if (ACTIVE_STATES.has(session.state) || session.backgroundTaskCount > 0) try { this.runner.abort(session.sessionId); } catch {}
-      if (!keepSessions) {
-        let deleted = false;
-        if (typeof this.runner.deleteSession === 'function') {
-          try { deleted = this.runner.deleteSession(session.sessionId) !== false; } catch {}
-        }
-        this.sessionArchive && this.sessionArchive.forget(session.sessionId);
-        this.knowledge?.forget(session.sessionId);
-        if (deleted) { this._removeHistory(session.sessionId); this._notifySessionDeleted(session); }
-      }
-      this.sessionAgents.delete(session.sessionId);
-    }
-    this.projects.remove(projectId);
-    this.contexts.unregister && this.contexts.unregister(projectId);
-    this._audit('project-remove', { projectId, keepSessions });
-    return true;
-  }
-
-  _requireProjects() {
-    if (!this.projects) throw Object.assign(new Error('project workspace support is not enabled'), { status: 501 });
-  }
-
-  // ---- session archive ----
-  archiveSession(sessionId) {
-    this._requireArchive();
-    const id = cleanId(sessionId, 'sessionId');
-    if (!this.runner.getState(id)) throw Object.assign(new Error('session not found'), { status: 404 });
-    const record = this.sessionArchive.archive(id);
-    this._notifySessionChange(id);
-    this._audit('session-archive', { sessionId: id });
-    return { sessionId: id, ...record };
-  }
-
-  restoreSession(sessionId) {
-    this._requireArchive();
-    const id = cleanId(sessionId, 'sessionId');
-    if (!this.runner.getState(id)) throw Object.assign(new Error('session not found'), { status: 404 });
-    const restored = this.sessionArchive.restore(id);
-    this._notifySessionChange(id);
-    this._audit('session-restore', { sessionId: id });
-    return { sessionId: id, restored };
-  }
-
-  // Archived sessions never restored within the retention window are deleted
-  // outright: the runner record goes first (best effort) and the archive mark
-  // only once the record is gone — a failed delete keeps the session hidden
-  // and retries on the next sweep instead of resurfacing unarchived.
-  purgeExpiredArchivedSessions() {
-    if (!this.sessionArchive || !(this.archiveRetentionMs > 0)) return [];
-    const purged = [];
-    for (const sessionId of this.sessionArchive.expired(this.archiveRetentionMs)) {
-      const previous = this.runner.getState(sessionId);
-      let deleted = true;
-      if (typeof this.runner.deleteSession === 'function') {
-        try { this.runner.deleteSession(sessionId); } catch { deleted = false; }
-      }
-      this.sessionAgents.delete(sessionId);
-      if (deleted) {
-        if (previous) this._notifySessionDeleted(previous);
-        this._removeHistory(sessionId);
-        this.knowledge?.forget(sessionId);
-        this.sessionArchive.forget(sessionId);
-        purged.push(sessionId);
-        this._audit('archive-expired', { sessionId });
-      }
-    }
-    return purged;
-  }
-
-  getUiPreferences() {
-    if (!this.uiPreferences) throw Object.assign(new Error('ui preferences support is not enabled'), { status: 501 });
-    return this.uiPreferences.read();
-  }
-
-  saveUiPreferences(input = {}) {
-    if (!this.uiPreferences) throw Object.assign(new Error('ui preferences support is not enabled'), { status: 501 });
-    return this.uiPreferences.save(input);
-  }
-
-  _requireArchive() {
-    if (!this.sessionArchive) throw Object.assign(new Error('session archive support is not enabled'), { status: 501 });
-  }
-
-  listSessions(contextId, options = {}) {
-    const id = cleanId(contextId, 'contextId');
-    const includeArchived = Boolean(options.includeArchived);
-    const all = this.runner.listSessions({ projectSlug: id });
-    const visible = includeArchived || !this.sessionArchive
-      ? all
-      : all.filter(session => !this.sessionArchive.isArchived(session.sessionId));
-    return visible.map((session, index) => this._summary(session, index === 0));
-  }
-
-  startSession(contextInput, aiProfileId, options = {}) {
-    if (this.destroyed) throw Object.assign(new Error('workbench is shut down'), { status: 503 });
-    const context = normalizeContext(contextInput);
-    if (this.runner.listSessions({}).length >= this.maxSessions) {
-      throw Object.assign(new Error('session limit reached'), { status: 429 });
-    }
-    const resolved = this.contexts.resolve(context);
-    const project = this.projects && this.projects.get(context.workspaceRef);
-    const agentId = normalizeAgentId(options.agentId || context.agentId || project && project.defaultAgentId);
-    const effort = normalizeEffort(options.effort);
-    // null explicitly selects the agent's login; omission inherits the project.
-    const profileChoice = aiProfileId !== undefined ? aiProfileId
-      : context.aiProfileId !== undefined ? context.aiProfileId : project && project.defaultAiProfileId;
-    const profileId = profileChoice ? cleanId(profileChoice, 'aiProfileId') : null;
-    const inheritsProject = aiProfileId === undefined && context.aiProfileId === undefined;
-    const selectedModel = options.model !== undefined ? options.model
-      : context.model !== undefined ? context.model : inheritsProject && project ? project.defaultModel : undefined;
-    const profile = this._runtimeProfile(profileId, selectedModel);
-    const started = this.runner.startChatSession({
-      slug: context.contextId,
-      projectPath: resolved.workspacePath,
-      kbPath: resolved.workspacePath,
-      // Persisted so later delegations can prove this session's trusted
-      // workspace without guessing from the current UI project.
-      workspaceRef: context.workspaceRef,
-      aiProfile: profile,
-      permissionMode: options.permissionMode || profile.permissionMode || 'default',
-      agentId,
-      effort,
-    });
-    // CLI drivers recycle numeric ids after a restart; a fresh session must
-    // not inherit the archived flag of an unrelated predecessor that happened
-    // to hold the same id.
-    if (this.sessionArchive && this.sessionArchive.isArchived(started.sessionId)) {
-      this.sessionArchive.forget(started.sessionId);
-    }
-    this.sessionAgents.set(started.sessionId, agentId);
-    // The native-task scope is bound from trusted service identity at
-    // session creation, before any input can arrive.
-    this._attachNativeTasks(started.sessionId);
-    const session = this.runner.getSession(started.sessionId);
-    if (session) {
-      session.selectedModel = profile.mainModel || null;
-      session.metadata = { ...(session.metadata || {}), inputOrigin: normalizeInputOrigin(options.inputOrigin) };
-    }
-    this._trackHistory(started.sessionId);
-    this._notifySessionChange(started.sessionId);
-    this._audit('session-start', { sessionId: started.sessionId, contextId: context.contextId, profileId, agentId });
-    return this._summary(this.runner.getState(started.sessionId), true);
-  }
-
-  loadSession(sessionId) {
-    const id = cleanId(sessionId, 'sessionId');
-    const state = this.runner.getState(id);
-    if (!state) throw Object.assign(new Error('session not found'), { status: 404 });
-    // An existing session binds its fixed native-task scope on first Service
-    // attach; it can never switch to a different one afterwards.
-    this._attachNativeTasks(id);
-    const usage = this.runner.getSessionTokenUsage(id);
-    return {
-      session: this._summary(state, true),
-      events: snapshotEvents(this.runner, id),
-      permission: state.pendingPermission || null,
-      permissionMode: state.permissionMode || 'default',
-      tokenUsage: { ...usage, hasUsage: Boolean(usage && (usage.used || usage.inputTokens || usage.outputTokens)) },
-    };
-  }
-
-  // Trusted-scope injection: the store scope, the runtime epoch and the
-  // durable-fact committer come from the frozen service task identity only -
-  // browser input and session options never reach them. Without a usable
-  // store identity the native-task feature stays explicitly unavailable
-  // while chat and history continue unchanged.
-  _attachNativeTasks(sessionId) {
-    if (!sessionId || !this.taskIdentity.available || !this.taskIdentity.storeScope) return false;
-    if (typeof this.runner.attachNativeTaskRuntime !== 'function') return false;
-    let committer = this.nativeCommitters.get(sessionId);
-    if (!committer) {
-      committer = this._nativeFactCommitter(sessionId);
-      this.nativeCommitters.set(sessionId, committer);
-    }
-    try {
-      const result = this.runner.attachNativeTaskRuntime(sessionId, {
-        storeScope: this.taskIdentity.storeScope,
-        runtimeEpoch: this.taskIdentity.runtimeEpoch,
-        commitNativeFact: committer,
-      });
-      return Boolean(result && result.attached);
-    } catch {
-      return false;
-    }
-  }
-
-  // The one trusted synchronous committer the runner's publish gate calls
-  // BEFORE a native fact reaches any buffer, listener or persisted
-  // snapshot. It goes through the sequence-validated durable receipt path
-  // (write + fsync), never a raw file bypass: a duplicate of an
-  // already-committed same-sequence fact is an idempotent success, a
-  // same-sequence disagreement is an explicit conflict failure, and a
-  // history that cannot even be attached is a fixed unavailable phase.
-  _nativeFactCommitter(sessionId) {
-    return event => {
-      try {
-        const history = this._history(sessionId);
-        const sequence = Number(event && event.sequence);
-        if (!Number.isSafeInteger(sequence) || sequence <= 0) {
-          return { ok: false, phase: 'sequence', error: 'native fact is not sequence-stamped' };
-        }
-        if (sequence <= history.highWater) {
-          const known = history.durableRow(sequence);
-          if (known && canonicalNativeFact(known) === canonicalNativeFact(event)) {
-            return { ok: true, phase: 'already-committed', sequence, highWater: history.highWater };
-          }
-          return {
-            ok: false, phase: 'conflict',
-            error: `native fact at sequence ${sequence} conflicts with the committed row`,
-            highWater: history.highWater,
-          };
-        }
-        return history.appendDurable([event]);
-      } catch {
-        return { ok: false, phase: 'history-unavailable', error: 'session history is not attachable' };
-      }
-    };
-  }
-
-  // Unbind this Service's own committer (same epoch + same closure
-  // reference); a different or second instance is refused by the runner.
-  _detachNativeTasks(sessionId) {
-    const committer = this.nativeCommitters.get(sessionId) || null;
-    this.nativeCommitters.delete(sessionId);
-    if (typeof this.runner.detachNativeTaskRuntime !== 'function') return;
-    try {
-      this.runner.detachNativeTaskRuntime(sessionId, {
-        runtimeEpoch: this.taskIdentity.runtimeEpoch,
-        commitNativeFact: committer,
-      });
-    } catch { /* binding already gone */ }
-  }
-
-  _history(id) {
-    if (this.histories.has(id)) return this.histories.get(id).history;
-    const session = this.runner.getSession(id);
-    const state = this.runner.getState(id);
-    if (!session || !state) throw Object.assign(new Error('session not found'), { status: 404 });
-    const first = session.outputBuffer?.[0];
-    const history = new SessionHistory({ file: this._historyFile(id), sessionId: id, startedAt: state.startedAt,
-      contextId: state.projectSlug, incomplete: Number(first?.sequence) > 1
-        || Number(session.turns) > (session.outputBuffer || []).filter(event => event.type === 'claude/user-prompt').length,
-      onError: error => this.diagnostics?.error('session.history.write.failed', '会话历史保存失败。', { phase: 'history', error: { code: error.code || 'HISTORY_WRITE_FAILED', message: '无法写入会话历史。' }, context: { sessionId: id } }),
-    });
-    this._reconcileHistory(id, history, session);
-    const unsubscribe = this.runner.subscribe(id, event => {
-      if (NATIVE_FACT_TYPES.has(event.type)) {
-        const sequence = Number(event.sequence);
-        if (Number.isSafeInteger(sequence) && sequence > 0 && sequence <= history.highWater) {
-          const known = history.durableRow(sequence);
-          if (known && canonicalNativeFact(known) === canonicalNativeFact(event)) {
-            // Idempotent replay of a committed fact - including the very
-            // fact the publish gate's committer just landed: no second
-            // write, but the session-change notification must still fire.
-          } else {
-            // A same-sequence fact is never blindly treated as "already
-            // written" and never overwrites the committed row: either the
-            // numbered row is missing or it disagrees with the replayed fact,
-            // and either way the conflict is an explicit diagnosis.
-            this.diagnostics?.error('session.history.durable.conflict', '原生任务事实与持久化历史同序号冲突；拒绝改写，原文件已保留。', {
-              phase: 'history', error: { code: 'HISTORY_DURABLE_CONFLICT', message: `native fact at sequence ${sequence} conflicts with the committed row` },
-              context: { sessionId: id, sequence, present: Boolean(known) },
-            });
-            return;
-          }
-        } else {
-          // Fallback for native facts that flowed ungated (a runner without
-          // a bound committer): the receipt is diagnosed, never faked.
-          const receipt = history.appendDurable([event]);
-          if (!receipt.ok) this.diagnostics?.error('session.history.durable.failed', '原生任务事实未能持久化；任务历史不可用，原文件已保留。', {
-            phase: 'history', error: { code: `HISTORY_DURABLE_${String(receipt.phase).toUpperCase()}`, message: String(receipt.error || 'durable append failed') },
-            context: { sessionId: id, highWater: receipt.highWater, pendingCount: receipt.pendingCount ?? null },
-          });
-        }
-      } else history.append(event);
-      this._notifySessionChange(id, event);
-    });
-    this.histories.set(id, { history, unsubscribe });
-    return history;
-  }
-
-  // Forward-only reconciliation between the runner snapshot counter and the
-  // durable journal, run once when a session's history is attached and
-  // therefore before any new sequence is minted for it. The old behavior
-  // reset a newer durable high-water mark back to an older snapshot count,
-  // which both silently dropped fresh events (sequence at or below the reset
-  // mark) and re-minted sequences the file already contained. Now both
-  // sides adopt max(snapshot, durable) and the losing side is repaired or
-  // explicitly marked instead of being rewritten: durable-ahead merges the
-  // missing durable tail into the replay buffer so subscribers can be
-  // served the gap; snapshot-ahead replays the contiguous in-memory prefix
-  // through the durable receipt path, and a hole that cannot be
-  // reconstructed is recorded as a recovery gap — never faked as complete.
-  _reconcileHistory(id, history, session) {
-    if (!history.exists || !Number.isFinite(session.eventSequence)) return;
-    const buffered = Array.isArray(session.outputBuffer) ? session.outputBuffer : [];
-    let bufferedMax = 0;
-    for (const event of buffered) {
-      const own = Number(event && event.sequence);
-      if (Number.isFinite(own) && own > 0 && own > bufferedMax) bufferedMax = own;
-    }
-    if (history.highWater > session.eventSequence) {
-      const tail = history.durableTail({ afterSequence: bufferedMax });
-      const lastDeltaSequence = new Map();
-      for (let i = buffered.length - 1; i >= 0; i--) {
-        const event = buffered[i];
-        if (!event || !DELTA_TYPES.has(event.type)) continue;
-        const id = event.id ?? null;
-        if (!lastDeltaSequence.has(id)) lastDeltaSequence.set(id, Number(event.sequence) || 0);
-      }
-      for (const event of tail.events) {
-        if (event && DELTA_TYPES.has(event.type)) {
-          const id = event.id ?? null;
-          const coveredFrom = compactionCoverage(buffered, event, lastDeltaSequence.get(id) || 0);
-          if (coveredFrom !== null) {
-            // A durable compaction subsumes fragments the replay buffer
-            // still holds in part: the merged row replaces them instead of
-            // concatenating onto them, so no client's cached prefix is
-            // duplicated and a cursor below the merged row resyncs
-            // explicitly instead of receiving the whole fragment as a delta.
-            for (let i = buffered.length - 1; i >= 0; i--) {
-              const held = buffered[i];
-              if (held && DELTA_TYPES.has(held.type) && held.id === event.id && Number(held.sequence) >= coveredFrom) buffered.splice(i, 1);
-            }
-            lastDeltaSequence.set(id, Number(event.sequence) || 0);
-          } else if (Number.isFinite(Number(event.sequence))) {
-            lastDeltaSequence.set(id, Math.max(lastDeltaSequence.get(id) || 0, Number(event.sequence)));
-          }
-        }
-        buffered.push(event);
-        while (buffered.length > 5000) buffered.shift();
-      }
-      session.eventSequence = Math.max(session.eventSequence, history.highWater);
-      return;
-    }
-    if (session.eventSequence > history.highWater) {
-      const above = [];
-      for (const event of buffered) {
-        const own = Number(event && event.sequence);
-        if (Number.isFinite(own) && own > history.highWater) above.push([own, event]);
-      }
-      above.sort((a, b) => a[0] - b[0]);
-      const catchUp = [];
-      let expected = history.highWater + 1;
-      for (const [sequence, event] of above) {
-        if (sequence !== expected) break;
-        catchUp.push(event);
-        expected += 1;
-      }
-      if (catchUp.length) {
-        const receipt = history.appendDurable(catchUp);
-        if (!receipt.ok) {
-          this.diagnostics?.error('session.history.reconcile.failed', '崩溃边界恢复未能补写会话历史；原文件已保留。', {
-            phase: 'history', error: { code: `HISTORY_DURABLE_${String(receipt.phase).toUpperCase()}`, message: String(receipt.error || 'durable append failed') },
-            context: { sessionId: id, highWater: receipt.highWater },
-          });
-          return;
-        }
-      }
-      if (history.highWater < session.eventSequence) {
-        // The gap marker is journaled, not kept in RAM: a restart must keep
-        // reporting the hole instead of presenting a healed-looking archive.
-        // A failed marker receipt is explicit and stays retryable — the
-        // next reconcile rewrites it instead of skipping it.
-        const recorded = history.recordRecoveryGap(history.highWater + 1, session.eventSequence);
-        if (!recorded.ok) {
-          this.diagnostics?.error('session.history.recovery.record.failed', '缺口标记未能持久化；原文件已保留，保持可重试。', {
-            phase: 'history', error: { code: `HISTORY_DURABLE_${String(recorded.phase).toUpperCase()}`, message: String(recorded.error || 'gap marker write failed') },
-            context: { sessionId: id, from: history.highWater + 1, to: session.eventSequence },
-          });
-        }
-        this.diagnostics?.error('session.history.recovery.gap', '会话历史存在无法重建的序号缺口；历史读取将显式标注。', {
-          phase: 'history', error: { code: 'HISTORY_RECOVERY_GAP', message: '快照与持久化历史之间存在缺口，不能宣称完整。' },
-          context: { sessionId: id, from: history.highWater + 1, to: session.eventSequence },
-        });
-      }
-    }
-  }
-
-  _trackHistory(id) {
-    try { return this._history(id); }
-    catch (error) {
-      this.diagnostics?.error('session.history.read.failed', '会话历史读取失败；实时会话仍可使用。', {
-        phase: 'history', error: { code: error.code || 'HISTORY_READ_FAILED', message: '会话历史不可用，原文件已保留。' }, context: { sessionId: id },
-      });
-      return null;
-    }
-  }
-
-  loadHistory(sessionId, options = {}) {
-    const id = cleanId(sessionId, 'sessionId');
-    try {
-      const history = this._history(id);
-      const state = this.runner.getState(id);
-      if (history.incomplete && !ACTIVE_STATES.has(state.state) && this._summary(state, false).agentId === 'claude-code') {
-        const session = this.runner.getSession(id);
-        const recovered = recoverClaudeHistory(session);
-        if (recovered) history.seedRecovered(recovered, Number(session.eventSequence) || history.highWater);
-      }
-      return history.read(options);
-    } catch (error) {
-      if (![400, 404].includes(error.status)) {
-        this.diagnostics?.error('session.history.read.failed', '会话历史读取失败，原文件已保留。', {
-          phase: 'history', error: { code: error.code || 'HISTORY_READ_FAILED', message: '无法读取完整会话历史。' }, context: { sessionId: id },
-        });
-        error.status = 503;
-      }
-      throw error;
-    }
-  }
-
-  _removeHistory(id) {
-    this.knowledgeBySession.delete(id);
-    this._detachNativeTasks(id);
-    const record = this.histories.get(id);
-    record?.unsubscribe(); record?.history.close();
-    this.histories.delete(id);
-    try { fs.unlinkSync(this._historyFile(id)); } catch (error) { if (error.code !== 'ENOENT') throw error; }
-  }
-
-  _historyFile(id) { return path.join(this.historyRoot, `${crypto.createHash('sha256').update(id).digest('hex')}.jsonl`); }
-
-  // ---- native task history (read-only over the session's own journal) ----
-
-  // The fixed scope every native-task read is bound to: the frozen trusted
-  // store identity plus the session's real project and id. Nothing in it is
-  // client-derived; the client only ever echoes it back for comparison.
-  _nativeTaskScope(state) {
-    return { storeScope: this.taskIdentity.storeScope, contextId: state.projectSlug, parentSessionId: state.sessionId };
-  }
-
-  _requireNativeTaskScope() {
-    if (!this.taskIdentity.available || !this.taskIdentity.storeScope) {
-      throw Object.assign(new Error('native task history is unavailable: the trusted store scope is not configured'), {
-        status: 503, code: this.taskIdentity.errorCode || 'STORE_SCOPE_UNAVAILABLE',
-      });
-    }
-    return this.taskIdentity.storeScope;
-  }
-
-  // The reader file always comes from the service's own session-history
-  // instance; recovery seeds never run on this path, and a failure keeps the
-  // original file and surfaces as an explicit unavailable answer.
-  _nativeHistoryFor(id) {
-    try {
-      return this._history(id);
-    } catch (error) {
-      if (error && (error.status === 400 || error.status === 404)) throw error;
-      throw Object.assign(new Error('native task history is not readable; the original history file is preserved'), {
-        status: 503, code: error && error.code ? error.code : 'HISTORY_READ_FAILED',
-      });
-    }
-  }
-
-  // A journal that has proven a write failure is never served as complete
-  // history: the newest facts may still live only in memory, so a page off
-  // the disk would silently omit them. Mirrors the SessionHistory read gate
-  // with a fixed safe message; the latched code token travels as the code.
-  // The same hole exists whenever ANY native fact is still pending behind a
-  // durable barrier - a recovery gap whose marker is not yet on disk, or a
-  // failed batch still awaiting its close-time marker: while the barrier
-  // head exists the native surfaces refuse with one generic pending code
-  // instead of serving the journal as complete. Ordinary chat reads are
-  // untouched, and a cleared barrier restores these reads.
-  _requireDurableJournal(history) {
-    if (history.error) {
-      throw Object.assign(new Error('会话历史写入失败，原文件已保留；原生任务历史暂不可用。'), { status: 503, code: history.error });
-    }
-    if (history.durableBarrier) {
-      throw Object.assign(new Error('尚有未提交历史事实，原生任务历史暂不可用。'), { status: 503, code: 'HISTORY_FACTS_PENDING' });
-    }
-  }
-
-  // The journal may know a recovery gap the on-disk scan can no longer see
-  // (the marker row disappeared after attach). The reader's own verdict
-  // stays untouched; the service-known hole is merged in, never dropped.
-  _nativeGapOverlay(history, page) {
-    const gap = history.recoveryGap;
-    if (!gap || page.incomplete.includes('history-gap')) return page;
-    const items = [{ code: 'service-recovery-gap', source: 'service', from: gap.from, to: gap.to }].concat(page.diagnostics.items);
-    const total = page.diagnostics.total + 1;
-    return {
-      ...page,
-      incomplete: [...page.incomplete, 'history-gap'],
-      diagnostics: { items: items.slice(0, 20), total, truncated: total > 20 },
-    };
-  }
-
-  // GET /sessions/:id/native-tasks - list observed native background tasks
-  // for the session out of its durable history. Pure read: no input is
-  // dispatched and no live handle is created; task rows are historical
-  // observations, never claims that anything is running or controllable.
-  async listNativeTasks(sessionId, query = {}) {
-    const id = cleanId(sessionId, 'sessionId');
-    const state = this.runner.getState(id);
-    if (!state) throw Object.assign(new Error('session not found'), { status: 404 });
-    const storeScope = this._requireNativeTaskScope();
-    if (typeof query.storeScope !== 'string' || query.storeScope === '') {
-      throw Object.assign(new Error('storeScope is required'), { status: 400 });
-    }
-    if (!STORE_SCOPE_PATTERN.test(query.storeScope)) {
-      throw Object.assign(new Error('storeScope is invalid'), { status: 400 });
-    }
-    if (typeof query.contextId !== 'string' || query.contextId === '') {
-      throw Object.assign(new Error('contextId is required'), { status: 400 });
-    }
-    const contextId = cleanId(query.contextId, 'contextId');
-    if (query.storeScope !== storeScope || contextId !== state.projectSlug) {
-      throw Object.assign(new Error('native task scope does not match this session; resync from the task list'), {
-        status: 409, code: 'SCOPE_MISMATCH', resync: true,
-      });
-    }
-    const history = this._nativeHistoryFor(id);
-    this._requireDurableJournal(history);
-    const scope = this._nativeTaskScope(state);
-    const reader = createNativeTaskHistoryReader({ file: history.file, scope });
-    let page;
-    try { page = await reader.listTasks(); }
-    catch (error) { if (error && error.status === 409) error.resync = true; throw error; }
-    return { ...this._nativeGapOverlay(history, page), scope: { ...scope } };
-  }
-
-  // POST /sessions/:id/native-tasks/history - page one bound task's events
-  // out of the same durable history. Pure read: no dispatch, no stop, no
-  // re-minted sequences, no SSE replay.
-  async loadNativeTaskHistory(sessionId, input = {}) {
-    const id = cleanId(sessionId, 'sessionId');
-    const state = this.runner.getState(id);
-    if (!state) throw Object.assign(new Error('session not found'), { status: 404 });
-    this._requireNativeTaskScope();
-    const ref = createNativeTaskRef(input && input.taskRef);
-    if (!ref) throw Object.assign(new Error('taskRef is not a valid native-task reference'), { status: 400, code: 'INVALID_TASK_REF' });
-    // The whole reference is checked against the real session scope before
-    // any journal is constructed or read, so a foreign-scope ref is a scope
-    // conflict even when the target file is missing or corrupt.
-    const scope = this._nativeTaskScope(state);
-    if (ref.storeScope !== scope.storeScope || ref.contextId !== scope.contextId || ref.parentSessionId !== scope.parentSessionId) {
-      throw Object.assign(new Error('taskRef scope does not match this session; resync from the task list'), {
-        status: 409, code: 'SCOPE_MISMATCH', resync: true,
-      });
-    }
-    const history = this._nativeHistoryFor(id);
-    this._requireDurableJournal(history);
-    const reader = createNativeTaskHistoryReader({ file: history.file, scope });
-    let page;
-    try { page = await reader.readTaskEvents(ref, { cursor: input.cursor, limit: input.limit }); }
-    catch (error) { if (error && error.status === 409) error.resync = true; throw error; }
-    return { ...this._nativeGapOverlay(history, page), taskRef: { ...ref }, scope: { ...scope } };
-  }
-
-  // ---- delegated sessions (trusted Workbench delegation commands) ----
-
-  _requireDelegations() {
-    if (!this.delegations || !this.delegations.ledger || !this.delegations.phases) {
-      throw Object.assign(new Error('delegated sessions are unavailable: the delegation ledger is not wired'), {
-        status: 503, code: 'DELEGATION_UNAVAILABLE',
-      });
-    }
-  }
-
-  _delegationSupported(agentId) {
-    if (typeof this.runner.supportsDelegatedSessions === 'function') {
-      return this.runner.supportsDelegatedSessions(agentId) === true;
-    }
-    return typeof this.runner.startDelegatedSession === 'function';
-  }
-
-  // The trusted workspace a delegated child inherits. Preference order: the
-  // parent's own persisted workspaceRef re-resolved through the real resolver,
-  // then — for sessions recorded before workspaceRef existed — a UNIQUE
-  // real-path match against the registered workspaces. Ambiguous or
-  // unresolvable is an explicit 409; the current UI project is never picked.
-  _delegationWorkspace(parentState) {
-    const parentSession = this.runner.getSession(parentState.sessionId);
-    const ref = parentSession && typeof parentSession.workspaceRef === 'string' && parentSession.workspaceRef
-      ? parentSession.workspaceRef : null;
-    if (ref) {
-      try {
-        const resolved = this.contexts.resolve({ contextId: parentState.projectSlug, workspaceRef: ref });
-        return { ref, rootPath: resolved.workspacePath };
-      } catch {
-        throw Object.assign(new Error('the parent workspace is no longer registered; no delegation was issued'), {
-          status: 409, code: 'DELEGATION_WORKSPACE_UNRESOLVED',
-        });
-      }
-    }
-    const recordedPath = parentSession && typeof parentSession.projectPath === 'string' && parentSession.projectPath
-      ? parentSession.projectPath : null;
-    if (!recordedPath) {
-      throw Object.assign(new Error('the parent session has no trusted workspace record; no delegation was issued'), {
-        status: 409, code: 'DELEGATION_WORKSPACE_UNRESOLVED',
-      });
-    }
-    const matches = this.contexts.findByRealPath(recordedPath);
-    if (matches.length === 1) return { ref: matches[0], rootPath: recordedPath };
-    if (matches.length === 0) {
-      throw Object.assign(new Error('the parent workspace does not match any registered workspace; no delegation was issued'), {
-        status: 409, code: 'DELEGATION_WORKSPACE_UNRESOLVED',
-      });
-    }
-    throw Object.assign(new Error('the parent workspace matches multiple registered workspaces; no delegation was issued'), {
-      status: 409, code: 'DELEGATION_WORKSPACE_AMBIGUOUS',
-    });
-  }
-
-  // Canonical command hash over EVERY choice that affects execution: the
-  // normalized text, the agent/profile/model/permission/effort selection and
-  // the resolved workspace. Credentials, env and prompt bodies beyond the
-  // command text itself never enter the ledger — only this hash does.
-  _delegationPayloadHash(command) {
-    const canonical = JSON.stringify({
-      schema: 'workbench-delegation-command/v1',
-      text: command.text,
-      agentId: command.agentId,
-      aiProfileId: command.aiProfileId,
-      model: command.model,
-      permissionMode: command.permissionMode,
-      effort: command.effort || null,
-      workspaceRef: command.workspaceRef,
-      contextId: command.contextId,
-      parentSessionId: command.parentSessionId,
-    });
-    return crypto.createHash('sha256').update(canonical, 'utf8').digest('hex');
-  }
-
-  _delegationDispatchState(record) {
-    const phases = this.delegations.phases.stateOf(record.delegationId);
-    const live = this.delegations.phases.isClaimLive(record.delegationId);
-    if (phases.outcome) {
-      const known = phases.outcome.outcome === 'dispatched';
-      return {
-        phase: known ? 'dispatched' : 'dispatch-unknown',
-        outcome: known ? 'dispatched' : 'unknown',
-        dispatch: { state: phases.outcome.outcome, attemptId: phases.outcome.attemptId, at: phases.outcome.at },
-        claim: phases.claim,
-      };
-    }
-    if (phases.claim) {
-      if (live) {
-        return { phase: 'dispatching', outcome: 'pending', dispatch: { state: 'dispatching', attemptId: phases.claim.attemptId }, claim: phases.claim };
-      }
-      // A claim nobody in this Service can still settle: the model receipt is
-      // unprovable, so the honest verdict is dispatch-unknown.
-      return {
-        phase: 'dispatch-unknown', outcome: 'unknown',
-        dispatch: { state: 'dispatch-unknown', attemptId: phases.claim.attemptId, reason: 'owner-unreachable' },
-        claim: phases.claim,
-      };
-    }
-    if (phases.childCreated) {
-      return { phase: 'child-created', outcome: 'not-dispatched', dispatch: { state: 'awaiting-dispatch' }, claim: null };
-    }
-    if (phases.childCreateFailed) {
-      return { phase: 'child-create-failed', outcome: 'not-started', dispatch: { state: 'not-dispatched', code: phases.childCreateFailed.code }, claim: null };
-    }
-    return { phase: 'reserved', outcome: 'not-started', dispatch: { state: 'not-dispatched' }, claim: null };
-  }
-
-  // Real child status straight from the runner. A missing child is reported
-  // as the explicit dangling fact it is — reads never resurrect it.
-  _delegationChild(record) {
-    const state = this.runner.getState(record.childSessionId);
-    if (!state) return { sessionId: record.childSessionId, present: false, state: 'missing' };
-    const summary = this._summary(state, ACTIVE_STATES.has(state.state));
-    return {
-      sessionId: record.childSessionId,
-      present: true,
-      state: state.state,
-      agentId: summary.agentId,
-      model: summary.model || null,
-      active: summary.active,
-      turns: summary.turns,
-      archived: summary.archived,
-    };
-  }
-
-  _delegationView(record) {
-    const status = this._delegationDispatchState(record);
-    return {
-      delegation: {
-        kind: 'delegated-session',
-        storeScope: record.scope.storeScope,
-        contextId: record.scope.contextId,
-        parentSessionId: record.scope.parentSessionId,
-        delegationId: record.delegationId,
-        childSessionId: record.childSessionId,
-        workspaceRef: record.workspace.ref,
-        requestId: record.requestId,
-        issuedAt: record.issuedAt,
-        source: record.source,
-        basis: record.basis,
-        sdkRunIdClaimed: false,
-        inputCausalityClaimed: false,
-        initiator: { type: 'external-api', authenticatedAs: null },
-        selection: { profileId: record.selection.profileId, model: record.selection.model },
-      },
-      phase: status.phase,
-      outcome: status.outcome,
-      dispatch: status.dispatch,
-      child: this._delegationChild(record),
-    };
-  }
-
-  _adoptDelegatedChild(childSessionId, agentId) {
-    this.sessionAgents.set(childSessionId, agentId);
-    this._attachNativeTasks(childSessionId);
-    this._trackHistory(childSessionId);
-    this._notifySessionChange(childSessionId);
-  }
-
-  _recordDelegationFailure(record, code) {
-    try {
-      this.delegations.phases.recordChildCreateFailed({ delegationId: record.delegationId, code });
-    } catch {
-      // The failure fact is diagnostics; the explicit error answer below is
-      // already the honest result and the reservation stays untouched.
-    }
-  }
-
-  // POST /sessions/:parentId/delegations — issue one delegation command.
-  // Frozen order (W1-DELEGATION-DECISIONS): validate → reserve (atomic fsync,
-  // idempotent by requestId, payload change = 409) → trusted child factory
-  // with the reserved identity (relation durable before anything else) →
-  // durable dispatch claim (exactly one owner) → send → durable outcome. Any
-  // unknown after the claim is reported as dispatch-unknown and never
-  // auto-re-input. accepted means the Workbench accepted the command, not
-  // that a model proved receipt.
-  async createDelegation(parentIdRaw, input = {}) {
-    this._requireDelegations();
-    const storeScope = this._requireNativeTaskScope();
-    const parentId = cleanId(parentIdRaw, 'sessionId');
-    if (!input || typeof input !== 'object' || Array.isArray(input)) {
-      throw Object.assign(new Error('delegation command must be an object'), { status: 400, code: 'DELEGATION_COMMAND_INVALID' });
-    }
-    const scopeInput = input.scope;
-    if (!scopeInput || typeof scopeInput !== 'object' || Array.isArray(scopeInput)
-      || Object.keys(scopeInput).length !== 2 || !('storeScope' in scopeInput) || !('contextId' in scopeInput)) {
-      throw Object.assign(new Error('scope must be an object with exactly storeScope and contextId; parentSessionId comes from the route'), {
-        status: 400, code: 'DELEGATION_SCOPE_INVALID',
-      });
-    }
-    if (typeof scopeInput.storeScope !== 'string' || !STORE_SCOPE_PATTERN.test(scopeInput.storeScope) || scopeInput.storeScope !== storeScope) {
-      throw Object.assign(new Error('scope.storeScope does not match this workbench; resync from health'), {
-        status: 409, code: 'DELEGATION_SCOPE_MISMATCH', resync: true,
-      });
-    }
-    const contextId = cleanId(scopeInput.contextId, 'contextId');
-    if (typeof input.requestId !== 'string' || !input.requestId.length || input.requestId.length > 256
-      || /[\u0000-\u001f\u007f]/.test(input.requestId)) {
-      throw Object.assign(new Error('requestId must be a non-empty string without control characters'), {
-        status: 400, code: 'DELEGATION_REQUEST_INVALID',
-      });
-    }
-    const requestId = input.requestId;
-    const text = typeof input.text === 'string' ? input.text.trim() : '';
-    if (!text || text.length > 200000) {
-      throw Object.assign(new Error('text must be a non-empty command of at most 200000 characters'), {
-        status: 400, code: 'DELEGATION_TEXT_INVALID',
-      });
-    }
-    const agentId = normalizeAgentId(input.agentId === undefined || input.agentId === null || input.agentId === '' ? undefined : input.agentId);
-    const effort = input.effort === undefined || input.effort === null || input.effort === '' ? undefined : normalizeEffort(input.effort);
-    const permissionMode = input.permissionMode === undefined || input.permissionMode === null || input.permissionMode === ''
-      ? 'default' : input.permissionMode;
-    if (!PERMISSION_MODES.includes(permissionMode)) {
-      throw Object.assign(new Error('permissionMode is invalid'), { status: 400, code: 'DELEGATION_SELECTION_REJECTED' });
-    }
-    if (input.metadata !== undefined || input.inputOrigin !== undefined) {
-      throw Object.assign(new Error('caller metadata does not grant trusted relations; omit metadata and inputOrigin'), {
-        status: 400, code: 'DELEGATION_CALLER_IDENTITY_REJECTED',
-      });
-    }
-
-    const parentState = this.runner.getState(parentId);
-    if (!parentState) throw Object.assign(new Error('parent session not found'), { status: 404, code: 'DELEGATION_PARENT_NOT_FOUND' });
-    if (parentState.projectSlug !== contextId) {
-      throw Object.assign(new Error('scope.contextId does not match the parent session; resync from the session list'), {
-        status: 409, code: 'DELEGATION_SCOPE_MISMATCH', resync: true,
-      });
-    }
-    if (!this._delegationSupported(agentId)) {
-      throw Object.assign(new Error(`agent "${agentId}" cannot run delegated sessions with a server-reserved identity`), {
-        status: 501, code: 'DELEGATION_AGENT_UNSUPPORTED',
-      });
-    }
-    // The selection resolves NOW so the payload hash covers the concrete
-    // profile/model the child will run with (unknown profile → 404 here).
-    const aiProfileId = input.aiProfileId === undefined ? (parentState.aiProfileId || null)
-      : input.aiProfileId === null ? null : cleanId(input.aiProfileId, 'aiProfileId');
-    const profile = this._runtimeProfile(aiProfileId, input.model === undefined ? undefined : input.model);
-    const model = profile.mainModel || null;
-    const workspace = this._delegationWorkspace(parentState);
-    if (this.runner.listSessions({}).length >= this.maxSessions) {
-      throw Object.assign(new Error('session limit reached'), { status: 429, code: 'DELEGATION_SESSION_LIMIT' });
-    }
-    const payloadHash = this._delegationPayloadHash({
-      text, agentId, aiProfileId, model, permissionMode, effort,
-      workspaceRef: workspace.ref, contextId, parentSessionId: parentId,
-    });
-
-    const record = this.delegations.ledger.reserve({
-      scope: { storeScope, contextId, parentSessionId: parentId },
-      requestId,
-      payloadHash,
-      workspace: { ref: workspace.ref, rootPath: workspace.rootPath, resolvedFrom: 'parent-session-record' },
-      selection: { profileId: aiProfileId, model },
-    });
-    this._audit('delegation-reserve', {
-      delegationId: record.delegationId, parentSessionId: parentId, contextId, childSessionId: record.childSessionId,
-    });
-
-    // Once a dispatch claim exists the input may already have reached a
-    // model: never re-create, never re-send — report the durable truth.
-    const prior = this._delegationDispatchState(record);
-    if (prior.claim) return { accepted: true, ...this._delegationView(record) };
-
-    if (typeof this.runner.startDelegatedSession !== 'function') {
-      throw Object.assign(new Error(`agent "${agentId}" cannot run delegated sessions with a server-reserved identity`), {
-        status: 501, code: 'DELEGATION_AGENT_UNSUPPORTED',
-      });
-    }
-    let started;
-    try {
-      started = this.runner.startDelegatedSession({
-        agentId,
-        reservedSessionId: record.childSessionId,
-        delegation: {
-          delegationId: record.delegationId,
-          parentSessionId: parentId,
-          storeScope,
-          contextId,
-        },
-        slug: contextId,
-        projectPath: workspace.rootPath,
-        kbPath: workspace.rootPath,
-        workspaceRef: workspace.ref,
-        aiProfile: profile,
-        permissionMode,
-        ...(effort ? { effort } : {}),
-      });
-    } catch (error) {
-      const code = error && typeof error.code === 'string' && error.code.startsWith('DELEGATION_')
-        ? error.code : 'DELEGATION_CHILD_CREATE_FAILED';
-      this._recordDelegationFailure(record, code);
-      if (error && error.status) throw error;
-      throw Object.assign(new Error('the delegated child session could not be created; no model input was sent'), {
-        status: 500, code,
-      });
-    }
-    if (!started || started.sessionId !== record.childSessionId) {
-      this._recordDelegationFailure(record, 'DELEGATION_CHILD_IDENTITY_MISMATCH');
-      throw Object.assign(new Error('the driver did not honor the reserved child identity; no model input was sent'), {
-        status: 500, code: 'DELEGATION_CHILD_IDENTITY_MISMATCH',
-      });
-    }
-    this._adoptDelegatedChild(record.childSessionId, agentId);
-    this.delegations.phases.recordChildCreated({
-      delegationId: record.delegationId,
-      childSessionId: record.childSessionId,
-      workspaceRef: workspace.ref,
-    });
-    this._notifySessionChange(record.childSessionId);
-
-    // Guards mirroring send()'s own pre-input checks: a refusal here happens
-    // provably before any input, so no claim is written and the reservation
-    // simply reports awaiting-dispatch.
-    const childState = this.runner.getState(record.childSessionId);
-    if (!childState) {
-      this._recordDelegationFailure(record, 'DELEGATION_CHILD_CREATE_FAILED');
-      throw Object.assign(new Error('the delegated child session could not be created; no model input was sent'), {
-        status: 500, code: 'DELEGATION_CHILD_CREATE_FAILED',
-      });
-    }
-    if (ACTIVE_STATES.has(childState.state) || this.pendingInputs.has(record.childSessionId)) {
-      throw Object.assign(new Error('the delegated child already has an active turn; the command stays reserved'), {
-        status: 409, code: 'DELEGATION_CHILD_BUSY',
-      });
-    }
-    if (this._activeCount() >= this.maxConcurrentRuns) {
-      throw Object.assign(new Error('runtime concurrency limit reached'), { status: 429, code: 'DELEGATION_CONCURRENCY_LIMIT' });
-    }
-
-    // Durable dispatch claim BEFORE the send: exactly one owner across
-    // Services and processes; a lost claim never sends.
-    let claim;
-    try {
-      claim = this.delegations.phases.claimDispatch({
-        delegationId: record.delegationId,
-        attemptId: crypto.randomUUID(),
-        ownerPid: process.pid,
-        ownerEpoch: this.runtimeEpoch,
-      });
-    } catch (error) {
-      throw Object.assign(new Error('the dispatch attempt could not be recorded; no model input was sent'), {
-        status: 503, code: error && typeof error.code === 'string' ? error.code : 'DELEGATION_CLAIM_FAILED',
-      });
-    }
-    if (!claim.claimed) {
-      return { accepted: true, ...this._delegationView(record) };
-    }
-
-    let outcome = 'dispatched';
-    let failureCode = null;
-    try {
-      await this.send(record.childSessionId, text, {
-        inputOrigin: 'agent-delegation',
-        permissionMode,
-        ...(effort ? { effort } : {}),
-      });
-    } catch (error) {
-      outcome = 'dispatch-unknown';
-      failureCode = error && typeof error.code === 'string' ? error.code : null;
-    }
-    try {
-      this.delegations.phases.recordOutcome({
-        delegationId: record.delegationId,
-        attemptId: claim.claim.attemptId,
-        outcome,
-      });
-    } catch {
-      // The receipt could not be proven on disk after a possibly accepted
-      // input: the only honest durable verdict is dispatch-unknown.
-      outcome = 'dispatch-unknown';
-      this.delegations.phases.abandonLiveClaim({
-        delegationId: record.delegationId,
-        attemptId: claim.claim.attemptId,
-      });
-    }
-    this._audit('delegation-dispatch', { delegationId: record.delegationId, childSessionId: record.childSessionId, outcome });
-    const view = this._delegationView(record);
-    if (failureCode && outcome === 'dispatch-unknown') view.dispatch.errorCode = failureCode;
-    return { accepted: true, ...view };
-  }
-
-  // GET /sessions/:parentId/delegations — trusted relations, durable command
-  // facts and the real child status. Pure read: no session is created, no
-  // input is sent, nothing is refreshed back to life.
-  listDelegations(parentIdRaw, query = {}) {
-    this._requireDelegations();
-    const storeScope = this._requireNativeTaskScope();
-    const parentId = cleanId(parentIdRaw, 'sessionId');
-    const parentState = this.runner.getState(parentId);
-    if (!parentState) throw Object.assign(new Error('parent session not found'), { status: 404, code: 'DELEGATION_PARENT_NOT_FOUND' });
-    if (typeof query.storeScope !== 'string' || !STORE_SCOPE_PATTERN.test(query.storeScope)) {
-      throw Object.assign(new Error('storeScope is invalid'), { status: 400, code: 'DELEGATION_SCOPE_INVALID' });
-    }
-    if (typeof query.contextId !== 'string' || !query.contextId) {
-      throw Object.assign(new Error('contextId is required'), { status: 400, code: 'DELEGATION_SCOPE_INVALID' });
-    }
-    const contextId = cleanId(query.contextId, 'contextId');
-    if (query.storeScope !== storeScope || contextId !== parentState.projectSlug) {
-      throw Object.assign(new Error('delegation scope does not match this session; resync from the session list'), {
-        status: 409, code: 'DELEGATION_SCOPE_MISMATCH', resync: true,
-      });
-    }
-    const records = this.delegations.ledger.list({ storeScope, contextId, parentSessionId: parentId });
-    return {
-      scope: { storeScope, contextId, parentSessionId: parentId },
-      delegations: records.map(record => this._delegationView(record)),
-    };
-  }
-
-  subscribe(sessionId, afterSequence, onEvent) {
-    const id = cleanId(sessionId, 'sessionId');
-    this._attachNativeTasks(id);
-    this._trackHistory(id);
-    return subscribeNormalized(this.runner, id, Number(afterSequence || 0), onEvent);
-  }
-
-  _notifySessionChange(id, event) {
-    const state = this.runner.getState(id);
-    if (!state) return;
-    const session = this.runner.getSession(id);
-    if (event?.type === 'claude/user-prompt' && event.text && session && !session.title) session.title = event.text.replace(/\s+/g, ' ').slice(0, 80);
-    const summary = this._summary(state, ACTIVE_STATES.has(state.state));
-    if (session?.title) summary.title = session.title;
-    const signature = JSON.stringify(summary);
-    if (this.sessionSignatures.get(id) === signature) return;
-    this.sessionSignatures.set(id, signature);
-    const change = { type: 'workbench/session-changed', revision: ++this.sessionRevision, contextId: summary.contextId, session: summary };
-    this.sessionChangeLog.push(change);
-    if (this.sessionChangeLog.length > 1000) this.sessionChangeLog.shift();
-    for (const listener of this.sessionChangeListeners) if (!listener.contextId || listener.contextId === summary.contextId) {
-      try { listener.callback(change); } catch { /* disconnected subscriber */ }
-    }
-  }
-
-  _notifySessionDeleted(state) {
-    const summary = this._summary(state, false);
-    this.sessionSignatures.delete(state.sessionId);
-    const change = { type: 'workbench/session-changed', deleted: true, revision: ++this.sessionRevision, contextId: summary.contextId, session: summary };
-    this.sessionChangeLog.push(change);
-    if (this.sessionChangeLog.length > 1000) this.sessionChangeLog.shift();
-    for (const listener of this.sessionChangeListeners) if (!listener.contextId || listener.contextId === summary.contextId) {
-      try { listener.callback(change); } catch { /* disconnected */ }
-    }
-  }
-
-  subscribeSessionChanges(contextId, afterRevision, callback) {
-    const id = contextId === '*' ? null : cleanId(contextId, 'contextId');
-    const sessions = this.runner.listSessions(id ? { projectSlug: id } : {});
-    for (const session of sessions) this._trackHistory(session.sessionId);
-    const after = Math.max(0, Number(afterRevision) || 0);
-    const first = this.sessionChangeLog[0]?.revision || 0;
-    if (after > this.sessionRevision || after && first > after + 1) {
-      callback({ type: 'workbench/resync', revision: this.sessionRevision, contextId: id });
-    } else if (after) {
-      for (const change of this.sessionChangeLog) if (change.revision > after && (!id || change.session.contextId === id)) callback(change);
-    } else callback({ type: 'workbench/sessions-snapshot', revision: this.sessionRevision, contextId: id, sessions: id ? this.listSessions(id, { includeArchived: true }) : sessions.map(s => this._summary(s, ACTIVE_STATES.has(s.state))) });
-    const listener = { contextId: id, callback };
-    this.sessionChangeListeners.add(listener);
-    return () => this.sessionChangeListeners.delete(listener);
-  }
-
-  async listCommands(sessionId) {
-    const id = cleanId(sessionId, 'sessionId');
-    const state = this.runner.getState(id);
-    if (!state) throw Object.assign(new Error('session not found'), { status: 404 });
-    if (typeof this.runner.listSupportedCommands !== 'function') return { commands: [] };
-    const profile = this._profileForSession(id, state);
-    const commands = await this.runner.listSupportedCommands(id, profile);
-    return { commands: Array.isArray(commands) ? commands : [] };
-  }
-
-  readAttachment(sessionId, attachmentId) {
-    const id = cleanId(sessionId, 'sessionId');
-    if (!this.runner.getState(id)) throw Object.assign(new Error('session not found'), { status: 404 });
-    const result = this.attachments && this.attachments.read(id, attachmentId);
-    if (!result) throw Object.assign(new Error('attachment not found'), { status: 404 });
-    return result;
-  }
-
-  async send(sessionId, text, options = {}, attachmentInput = []) {
-    if (this.destroyed) throw Object.assign(new Error('workbench is shut down'), { status: 503 });
-    const id = cleanId(sessionId, 'sessionId');
-    const state = this.runner.getState(id);
-    if (!state) throw Object.assign(new Error('session not found'), { status: 404 });
-    // A direct input can be the first Service contact for an existing or
-    // restored session: the trusted native-task scope binds before any SDK
-    // input can stream, without relying on an earlier snapshot request.
-    this._attachNativeTasks(id);
-    if (ACTIVE_STATES.has(state.state) || this.pendingInputs.has(id)) {
-      throw Object.assign(new Error('session already has an active turn'), { status: 409 });
-    }
-    if (this._activeCount() - (state.backgroundTaskCount > 0 ? 1 : 0) >= this.maxConcurrentRuns) {
-      throw Object.assign(new Error('runtime concurrency limit reached'), { status: 429 });
-    }
-    const value = String(text || '').trim();
-    const attachments = normalizeAttachments(attachmentInput);
-    if (!value && !attachments.length) throw Object.assign(new Error('text or attachments are required'), { status: 400 });
-    if (value.length > 200000) throw Object.assign(new Error('input exceeds 200000 characters'), { status: 413 });
-    const profile = this._profileForSession(id, state);
-    const session = this.runner.getSession(id);
-    this._trackHistory(id);
-    const request = { aborted: false };
-    this.pendingInputs.set(id, request);
-    try {
-    const knowledge = this.knowledge ? await this.knowledge.retrieve(session.projectPath || session.kbPath || state.projectPath, value, options?.knowledgeScope, { sessionId: id }) : null;
-    if (request.aborted) throw Object.assign(new Error('task cancelled before agent launch'), { status: 409 });
-    if (knowledge) this.knowledgeBySession.set(id, knowledge);
-    if (knowledge) this.knowledge.remember?.(id, knowledge);
-    const previousEventCount = session && session.outputBuffer ? session.outputBuffer.length : 0;
-    const captureTurn = this.conversationCapture && this.captureSettings?.read().terminalConversations ? {
-      projectPath: session.projectPath || session.kbPath, source: this._summary(state, false).agentId,
-      sessionId: id, turnId: `turn_${crypto.randomUUID()}`, inputOrigin: session.metadata?.inputOrigin === 'agent-delegation' ? 'agent-delegation' : normalizeInputOrigin(options?.inputOrigin || session.metadata?.inputOrigin),
-    } : null;
-    if (captureTurn) this._capture(captureTurn, 'user_prompt', value);
-    const stored = this.attachments ? this.attachments.saveMany(id, attachments) : attachments;
-    const displayAttachments = stored.map(item => ({
-      id: item.id, name: item.name, mediaType: item.mediaType, size: item.size,
-      width: item.width, height: item.height,
-      url: `${this.apiPrefix}/sessions/${encodeURIComponent(id)}/attachments/${encodeURIComponent(item.id)}`,
-    }));
-    const runtimeAttachments = attachments.map((item, index) => ({ ...displayAttachments[index], data: item.data }));
-    const inputOrigin = session.metadata?.inputOrigin === 'agent-delegation' ? 'agent-delegation' : normalizeInputOrigin(options?.inputOrigin || session.metadata?.inputOrigin);
-    try { await this.runner.sendInput(id, value, profile, { ...(options || {}), inputOrigin, knowledgeContext: knowledge?.prompt || '', attachments: runtimeAttachments, displayAttachments }); }
-    catch (error) { this._runtimeFailure(id, error); if (captureTurn) this._capture(captureTurn, 'session_end', undefined, 'failed'); throw error; }
-    this._watchTurn(id, previousEventCount, captureTurn);
-    this._audit('input', { sessionId: id, contextId: state.projectSlug, characters: value.length, attachments: attachments.length, attachmentBytes: attachments.reduce((sum, item) => sum + item.size, 0) });
-    return { accepted: true, sessionId: id, state: this.runner.getState(id)?.state, knowledge: knowledge ? { ...knowledge, prompt: undefined } : null };
-    } finally { this.pendingInputs.delete(id); }
-  }
-
-  knowledgeContext(sessionId) {
-    const id = cleanId(sessionId, 'sessionId');
-    if (!this.runner.getState(id)) throw Object.assign(new Error('session not found'), { status: 404 });
-    const value = this.knowledgeBySession.get(id) || this.knowledge?.saved?.(id);
-    return value ? { ...value, prompt: undefined } : { status: 'not-retrieved', references: [] };
-  }
-
-  resolvePermission(sessionId, requestId, decision) {
-    const id = cleanId(sessionId, 'sessionId');
-    const rid = cleanId(requestId, 'requestId');
-    this._trackHistory(id);
-    const result = this.runner.resolvePermission(id, rid, decision || {});
-    this._audit('permission-resolve', { sessionId: id, requestId: rid, allow: decision && decision.allow === true });
-    return result;
-  }
-
-  abort(sessionId, reason = 'user-abort') {
-    const id = cleanId(sessionId, 'sessionId');
-    if (!this.runner.getState(id)) throw Object.assign(new Error('session not found'), { status: 404 });
-    this._trackHistory(id);
-    if (this.pendingInputs.has(id)) this.pendingInputs.get(id).aborted = true;
-    this.runner.abort(id, reason);
-    // A net for runners that emit no aborted event: normally the monitor
-    // already released itself on that event, having recorded session_end once.
-    this._clearTurnMonitor(id);
-    this._audit('abort', { sessionId: id, reason });
-    return { accepted: true, sessionId: id };
-  }
-
-  setPermissionMode(sessionId, mode) {
-    const id = cleanId(sessionId, 'sessionId');
-    if (!PERMISSION_MODES.includes(mode)) throw Object.assign(new Error('invalid permission mode'), { status: 400 });
-    this._trackHistory(id);
-    const session = this.runner.getSession(id);
-    if (!session) throw Object.assign(new Error('session not found'), { status: 404 });
-    session.permissionMode = mode;
-    this._audit('permission-mode', { sessionId: id, mode });
-    return { sessionId: id, permissionMode: mode };
-  }
-
-  // Rebind an existing session to another AI profile/model (or back to the
-  // agent's own login with aiProfileId null). The session and its history
-  // survive; the next turn simply runs under the new selection.
-  updateSessionSelection(sessionId, aiProfileId, model) {
-    const id = cleanId(sessionId, 'sessionId');
-    const state = this.runner.getState(id);
-    if (!state) throw Object.assign(new Error('session not found'), { status: 404 });
-    if (ACTIVE_STATES.has(state.state) || state.backgroundTaskCount > 0) {
-      throw Object.assign(new Error('session already has an active turn'), { status: 409 });
-    }
-    this._trackHistory(id);
-    // _runtimeProfile resolves and validates the profile (404 unknown id,
-    // 400 disabled/missing credential/invalid model) exactly like startSession.
-    const profileId = aiProfileId ? cleanId(aiProfileId, 'aiProfileId') : null;
-    const profile = this._runtimeProfile(profileId, model === undefined ? undefined : model);
-    if (typeof this.runner.updateSelection === 'function') {
-      this.runner.updateSelection(id, profile, profile.mainModel || null);
-    } else {
-      const session = this.runner.getSession(id);
-      if (!session) throw Object.assign(new Error('session not found'), { status: 404 });
-      session.aiProfileId = profileId;
-      session.selectedModel = profile.mainModel || null;
-    }
-    this._audit('selection-update', { sessionId: id, contextId: state.projectSlug, profileId, model: profile.mainModel || null });
-    return this._summary(this.runner.getState(id), true);
-  }
-
-  async testProfile(profileId) {
-    const id = cleanId(profileId, 'profileId');
-    const profile = this.profiles.runtimeProfile(id);
-    return this._runProfileTest(profile, id);
-  }
-
-  async testProfileDraft(input = {}) {
-    if (!input || typeof input !== 'object' || Array.isArray(input) || !input.profile) {
-      throw Object.assign(new Error('profile is required'), { status: 400 });
-    }
-    const profile = this.profiles.runtimeDraft(input.profile, input.credential);
-    return this._runProfileTest(profile, profile.id);
-  }
-
-  // Detect the models a provider draft can actually use (endpoint model list
-  // joined with models.dev capability metadata). Uses the same draft+credential
-  // resolution as testProfileDraft, so a blank credential falls back to the
-  // stored secret of an already-saved profile.
-  async detectProfileModels(input = {}) {
-    if (!input || typeof input !== 'object' || Array.isArray(input) || !input.profile) {
-      throw Object.assign(new Error('profile is required'), { status: 400 });
-    }
-    if (!this.modelDetection) {
-      throw Object.assign(new Error('model detection is unavailable'), { status: 501 });
-    }
-    // Detection precedes model configuration, so an empty model list is fine here.
-    const profile = this.profiles.runtimeDraft(input.profile, input.credential, { requireModel: false });
-    const result = await this.modelDetection.detectModels({ profile });
-    this._audit('profile-detect-models', { profileId: profile.id, count: result.models.length, sources: Object.keys(result.sources) });
-    return result;
-  }
-
-  async _runProfileTest(profile, profileId) {
-    const id = cleanId(profileId, 'profileId');
-    const contextId = `profile-test-${Date.now().toString(36)}`;
-    const startedAt = Date.now();
-    const started = this.runner.startChatSession({
-      slug: contextId, projectPath: this.testWorkspace, kbPath: this.testWorkspace,
-      aiProfile: profile, permissionMode: 'default',
-    });
-    let firstEventMs = null;
-    let preview = '';
-    let unsubscribe = null;
-    try {
-      const outcome = await new Promise((resolve, reject) => {
-        const timeout = setTimeout(() => reject(new Error('Claude Code profile test timed out')), Math.min(profile.timeoutMs, 300000));
-        unsubscribe = this.runner.subscribe(started.sessionId, event => {
-          if (firstEventMs == null && event.type !== 'claude/session-ready') firstEventMs = Date.now() - startedAt;
-          if (event.type === 'claude/result') {
-            clearTimeout(timeout);
-            if (event.isError) {
-              reject(new Error(String(event.result || event.message || event.error || 'Claude Code returned an error result')));
-            } else {
-              preview = String(event.result || event.text || '').slice(0, 500);
-              resolve(event);
-            }
-          } else if (event.type === 'claude/error') {
-            clearTimeout(timeout); reject(new Error(String(event.message || event.error || 'Claude Code runtime error')));
-          } else if (event.type === 'claude/aborted') {
-            clearTimeout(timeout); reject(new Error('Claude Code profile test was aborted'));
-          }
-        });
-        this.runner.sendInput(started.sessionId, 'Reply with exactly: WORKBENCH_RUNTIME_OK', profile, { permissionMode: 'default' }).catch(error => {
-          clearTimeout(timeout); reject(error);
-        });
-      });
-      const state = this.runner.getState(started.sessionId);
-      return {
-        ok: true, runtime: 'claude-code', runtimeVerified: true, profileId: id,
-        model: outcome.model || state && state.model || profile.models.default,
-        firstEventMs: firstEventMs == null ? Date.now() - startedAt : firstEventMs,
-        durationMs: Date.now() - startedAt, resultPreview: redact(preview),
-      };
-    } finally {
-      try { unsubscribe && unsubscribe(); } catch {}
-      try { this.runner.abort(started.sessionId); } catch {}
-      try { this.runner.deleteSession(started.sessionId); } catch {}
-    }
-  }
-
-  destroy() {
-    if (this.destroyPromise) return this.destroyPromise;
-    this.destroyed = true;
-    for (const request of this.pendingInputs.values()) request.aborted = true;
-    this.sessionChangeListeners.clear();
-    this.agentDiscovery?.close?.();
-    this.conversationCapture?.close();
-    if (this.archiveSweeper) { clearInterval(this.archiveSweeper); this.archiveSweeper = null; }
-    for (const sessionId of this.turnMonitors.keys()) this._clearTurnMonitor(sessionId);
-    for (const session of this.runner.listSessions({})) {
-      if (ACTIVE_STATES.has(session.state)) try { this.runner.abort(session.sessionId); } catch {}
-    }
-    this.destroyPromise = Promise.resolve(this.runner.destroy?.()).finally(() => {
-      this.sessionChangeListeners.clear();
-      for (const { history, unsubscribe } of this.histories.values()) { unsubscribe(); history.close(); }
-      this.histories.clear();
-      // Closing the Service unbinds only its OWN committer bindings: the
-      // runner marks those runtimes non-sticky unavailable (rebindable by a
-      // successor), while bindings owned by another instance are refused
-      // there and stay untouched.
-      for (const sessionId of [...this.nativeCommitters.keys()]) this._detachNativeTasks(sessionId);
-    });
-    return this.destroyPromise;
-  }
-
-  _runtimeProfile(profileId, selectedModel) {
-    const profile = profileId ? this.profiles.runtimeProfile(profileId)
-      : { id: null, models: { default: '' }, timeoutMs: 300000 };
-    const model = selectedModel == null ? profile.models.default : String(selectedModel).trim();
-    if (model.length > 128 || /[\r\n\x00]/.test(model)) throw Object.assign(new Error('model is invalid'), { status: 400 });
-    return { ...profile, models: { ...profile.models, default: model }, mainModel: model };
-  }
-
-  _profileForSession(id, state) {
-    const session = this.runner.getSession(id);
-    const model = session && Object.prototype.hasOwnProperty.call(session, 'selectedModel')
-      ? session.selectedModel : state.selectedModel || state.model;
-    return this._runtimeProfile(state.aiProfileId, model);
-  }
-
-  _summary(session, active) {
-    const agentId = session.agentId
-      || (typeof this.runner.agentOf === 'function' ? this.runner.agentOf(session.sessionId) : null)
-      || this.sessionAgents.get(session.sessionId)
-      || 'claude-code';
-    return {
-      sessionId: session.sessionId,
-      contextId: session.projectSlug,
-      projectId: session.projectSlug,
-      agentId,
-      title: session.title || `Session ${String(session.sessionId).slice(-8)}`,
-      active: Boolean(active), state: session.state, model: session.model || null,
-      aiProfileId: session.aiProfileId || null, permissionMode: session.permissionMode || 'default',
-      selectedModel: session.selectedModel || this.runner.getSession(session.sessionId)?.selectedModel || null,
-      authSource: session.aiProfileId ? 'profile-injected' : 'agent-owned',
-      providerName: session.aiProfileId ? this.profiles.get(session.aiProfileId)?.name || 'Unavailable provider' : AGENTS[agentId].label,
-      archived: Boolean(this.sessionArchive && this.sessionArchive.isArchived(session.sessionId)),
-      turns: Number(session.turns || 0), startedAt: session.startedAt,
-      tasks: Array.isArray(session.tasks) ? session.tasks : [],
-      backgroundTaskCount: Number(session.backgroundTaskCount || 0),
-      // W-1: prefer the driver's live activity marker (refreshed at turn
-      // end); endedAt/startAt only predate it for legacy records.
-      updatedAt: session.updatedAt || session.endedAt || session.startedAt, connectionState: 'connected',
-    };
-  }
-
-  // Approximate context occupancy for the capacity bubble. Token totals come
-  // from the driver; the per-category split is a characters/4 estimate over
-  // the session event log and is explicitly flagged as such.
-  contextUsage(sessionId) {
-    const id = cleanId(sessionId, 'sessionId');
-    const state = this.runner.getState(id);
-    if (!state) throw Object.assign(new Error('session not found'), { status: 404 });
-    const usage = this.runner.getSessionTokenUsage(id) || {};
-    const contextWindow = this._contextWindowFor(state.model, this._sessionProfileContextWindow(id, state));
-    const breakdown = this._estimateBreakdown(id);
-    const used = Number(usage.used || usage.inputTokens || 0) || 0;
-    return {
-      sessionId: id,
-      agentId: this._summary(state, false).agentId,
-      model: state.model || null,
-      contextWindow,
-      used,
-      percent: contextWindow ? Math.round((used / contextWindow) * 1000) / 10 : null,
-      inputTokens: Number(usage.inputTokens || 0) || 0,
-      outputTokens: Number(usage.outputTokens || 0) || 0,
-      breakdown,
-      estimated: true,
-    };
-  }
-
-  _sessionProfileContextWindow(sessionId, state) {
-    try {
-      const profile = this._profileForSession(sessionId, state);
-      return profile ? Number(profile.contextWindow) || 0 : 0;
-    } catch { return 0; }
-  }
-
-  _contextWindowFor(model, profileContextWindow) {
-    if (!model && !profileContextWindow) return 200000;
-    if (this.modelContextWindows && typeof this.modelContextWindows.resolveContextWindow === 'function') {
-      try {
-        // The profile store defaults contextWindow to 200000; that default must
-        // not shadow the recognition table (e.g. MiniMax → 1M). Only an explicit
-        // non-default override wins over auto-detection.
-        const explicit = Number(profileContextWindow) > 0 && Number(profileContextWindow) !== 200000 ? Number(profileContextWindow) : undefined;
-        const resolved = this.modelContextWindows.resolveContextWindow({ profileContextWindow: explicit, model, fallback: 200000 });
-        if (resolved) return resolved;
-      } catch { /* fall through to the default */ }
-    }
-    return Number(profileContextWindow) > 0 ? Number(profileContextWindow) : 200000;
-  }
-
-  _estimateBreakdown(sessionId) {
-    const session = this.runner.getSession(sessionId);
-    const buckets = { messages: 0, tools: 0, other: 0 };
-    if (!session || !Array.isArray(session.outputBuffer)) return buckets;
-    for (const event of session.outputBuffer) {
-      const text = String(event.text || event.result || event.output || '');
-      const tokens = Math.ceil(text.length / 4);
-      if (event.type === 'claude/user-prompt' || event.type === 'claude/text-delta') buckets.messages += tokens;
-      else if (event.type === 'claude/tool-use' || event.type === 'claude/tool-result') buckets.tools += tokens;
-      else buckets.other += tokens;
-    }
-    return buckets;
-  }
-
-  _activeCount(sessions = null) { const list = Array.isArray(sessions) ? sessions : this.runner.listSessions({}); const active = new Set(list.filter(item => ACTIVE_STATES.has(item.state) || item.backgroundTaskCount > 0).map(item => item.sessionId)); return active.size + [...this.pendingInputs.keys()].filter(id => !active.has(id)).length; }
-  _capture(turn, eventType, content, outcome) {
-    try { this.conversationCapture.enqueue(turn, eventType, content, outcome); }
-    catch { this._audit('capture-gap', { sessionId: turn.sessionId, code: 'CAPTURE_QUEUE_UNAVAILABLE' }); }
-  }
-  _watchTurn(sessionId, previousEventCount, captureTurn) {
-    this._clearTurnMonitor(sessionId);
-    let seen = 0;
-    let unsubscribe = null;
-    let completed = false;
-    let responseText = '';
-    let released = false;
-    // The monitor owns capture and failure diagnostics on its own; there is no
-    // whole-task timer anymore, so keeping it must not depend on one.
-    const release = () => {
-      if (released) return;
-      released = true;
-      if (unsubscribe) { try { unsubscribe(); } catch {} }
-      this.turnMonitors.delete(sessionId);
-    };
-    unsubscribe = this.runner.subscribe(sessionId, event => {
-      if (released) return;
-      seen += 1;
-      if (seen <= previousEventCount) return;
-      if (event?.parentToolUseId) return;
-      if (event?.type === 'claude/text-delta') responseText += String(event.text || '');
-      if (['claude/result', 'claude/turn-end', 'claude/error', 'claude/aborted'].includes(event && event.type)) {
-        if (event.type === 'claude/error' || event.type === 'claude/result' && event.isError) this._runtimeFailure(sessionId, new Error(String(event.message || event.error || event.result || 'Agent 运行失败。')));
-        if (captureTurn && !completed) {
-          completed = true;
-          if (event.type === 'claude/result' && !event.isError && typeof event.result === 'string' && event.result) this._capture(captureTurn, 'assistant_response', event.result);
-          if (event.type === 'claude/turn-end' && !event.exitCode && responseText) this._capture(captureTurn, 'assistant_response', responseText);
-          this._capture(captureTurn, 'session_end', undefined, event.type === 'claude/result' && !event.isError || event.type === 'claude/turn-end' && !event.exitCode ? 'completed' : 'failed');
-        }
-        release();
-      }
-    });
-    // The synchronous replay may deliver the terminal event while
-    // `unsubscribe` is still unassigned, so release() could not detach yet.
-    if (released) { try { unsubscribe(); } catch {} }
-    else this.turnMonitors.set(sessionId, unsubscribe);
-  }
-  _clearTurnMonitor(sessionId) {
-    const unsubscribe = this.turnMonitors.get(sessionId);
-    if (unsubscribe) try { unsubscribe(); } catch {}
-    this.turnMonitors.delete(sessionId);
-  }
-  _runtimeFailure(sessionId, error) {
-    const state = this.runner.getState(sessionId);
-    this.diagnostics?.error('agent.runtime.failed', 'Agent 会话运行失败。', { projectId: /^project-[A-Za-z0-9._-]+$/.test(state?.projectSlug || '') ? state.projectSlug : undefined, runId: sessionId, phase: 'runtime', error, context: { agent: this.runner.agentOf?.(sessionId) || this.sessionAgents.get(sessionId) || state?.agentId || 'claude-code', sessionId } });
-  }
-  _audit(action, detail) {
-    if (!this.auditFile) return;
-    fs.mkdirSync(path.dirname(this.auditFile), { recursive: true });
-    fs.appendFileSync(this.auditFile, `${JSON.stringify({ at: new Date().toISOString(), action, ...detail })}\n`, 'utf8');
-  }
-}
-
-function redact(value) {
-  return String(value || '').replace(/(?:sk|key|token)-[a-zA-Z0-9._-]{8,}/gi, '[REDACTED]');
-}
-
-function normalizeInputOrigin(value) { return ['human', 'agent-delegation'].includes(value) ? value : 'unknown'; }
-
-module.exports = { WorkbenchService, ACTIVE_STATES, redact };
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('node:crypto');
+const {
+  normalizeContext, normalizeAttachments, normalizeAgentId, normalizeEffort, cleanId, PERMISSION_MODES, AGENTS,
+} = require('../../contracts');
+const { snapshotEvents, subscribeNormalized } = require('./event-stream');
+const { SessionHistory } = require('./session-history');
+const { parentContext } = require('./parent-context');
+const PARENT_CONTEXT = Symbol('trusted parent conversation snapshot');
+const { recoverClaudeHistory } = require('./claude-history-recovery');
+// The history reader and task identity load from the same legacy runtime
+// tree as every other runtime module: loadLegacyRuntime binds to the owning
+// distribution, so a packaged server loads them from its own legacy tree and
+// a missing file fails the public entry instead of borrowing source code.
+const { loadLegacyRuntime } = require('./runtime-loader');
+const { createNativeTaskHistoryReader } = loadLegacyRuntime('native-task-history-reader');
+const { createNativeTaskRef } = loadLegacyRuntime('task-identity');
+
+const ACTIVE_STATES = new Set(['created', 'spawning', 'running', 'thinking', 'tool-running', 'pending-permission']);
+
+// Native fact rows are durable-by-contract: they go through the receipt
+// path (write + fsync) so nothing is ever built on facts that still live
+// only in memory. Plain chat events keep the batched append path.
+const NATIVE_FACT_TYPES = new Set(['claude/native-trace', 'claude/native-task-state', 'claude/native-task-transcript']);
+
+const DELTA_TYPES = new Set(['claude/text-delta', 'claude/thinking-delta']);
+
+// The same native fact as the committed row, ignoring fields that
+// legitimately differ between a journaled row and an in-memory replay of it.
+function canonicalNativeFact(event) {
+  const ordered = {};
+  for (const key of Object.keys(event || {}).sort()) {
+    if (key === 'at' || key === 'sequence' || key === 'sessionId' || key === 'contextId') continue;
+    ordered[key] = event[key];
+  }
+  return JSON.stringify(ordered);
+}
+
+// The earliest buffered same-id delta sequence a merged durable row is
+// proven to cover. Rows written since compaction kept provenance carry
+// compactFrom and are trusted as-is; older archives only admit the coverage
+// reading when a sequence gap exists AND the buffer's own fragments form a
+// strict prefix of the merged text — otherwise the row is a continuation
+// delta and must be appended, not substituted.
+function compactionCoverage(buffered, durable, lastBufferedSequence) {
+  const declared = Number(durable && durable.compactFrom);
+  if (Number.isSafeInteger(declared) && declared > 0) return declared;
+  const sequence = Number(durable && durable.sequence);
+  if (!Number.isSafeInteger(sequence) || sequence <= 0) return null;
+  if (!Number.isFinite(lastBufferedSequence) || sequence <= lastBufferedSequence + 1) return null;
+  let prefix = '';
+  let earliest = null;
+  for (const event of buffered) {
+    if (!event || event.type !== durable.type || event.id !== durable.id) continue;
+    const own = Number(event.sequence);
+    if (!Number.isSafeInteger(own) || own <= 0 || own >= sequence) continue;
+    prefix += String(event.text || '');
+    if (earliest === null || own < earliest) earliest = own;
+  }
+  if (earliest === null || prefix.length === 0) return null;
+  const text = String(durable.text || '');
+  return text.length > prefix.length && text.startsWith(prefix) ? earliest : null;
+}
+
+// The health identity accepts only a canonical persisted store id; nothing
+// volatile (port, PID, epoch) or malformed may pose as a store scope.
+const STORE_SCOPE_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+class WorkbenchService {
+  constructor(options) {
+    this.runner = options.runner;
+    this.diagnostics = options.diagnostics || null;
+    this.knowledge = options.knowledge || null;
+    this.pendingInputs = new Map();
+    this.knowledgeBySession = new Map();
+    this.profiles = options.profiles;
+    this.contexts = options.contexts;
+    this.attachments = options.attachments;
+    this.projects = options.projects || null;
+    this.sessionArchive = options.sessionArchive || null;
+    this.uiPreferences = options.uiPreferences || null;
+    this.captureSettings = options.captureSettings || null;
+    this.conversationCapture = options.conversationCapture || null;
+    this.onCaptureSettingsSaved = options.onCaptureSettingsSaved || null;
+    this.agentDiscovery = options.agentDiscovery || null;
+    this.resolveRuntimeExecutable = options.resolveRuntimeExecutable || null;
+    this.modelContextWindows = options.modelContextWindows || null;
+    this.modelDetection = options.modelDetection || null;
+    // Trusted delegation stores: the immutable reservation ledger plus the
+    // write-once phase/claim journal. Null when the host wired none — the
+    // delegation APIs then answer explicit unavailability instead of
+    // pretending to run commands.
+    this.delegations = options.delegations || null;
+    // Per-service runtime generation: fresh for every WorkbenchService
+    // instance, constant for its lifetime, never persisted anywhere.
+    this.runtimeEpoch = crypto.randomUUID();
+    const injectedIdentity = options.storeIdentity || null;
+    const storeScope = injectedIdentity && injectedIdentity.available === true && typeof injectedIdentity.storeScope === 'string'
+      && STORE_SCOPE_PATTERN.test(injectedIdentity.storeScope)
+      ? injectedIdentity.storeScope
+      : null;
+    this.taskIdentity = Object.freeze({
+      storeScope,
+      runtimeEpoch: this.runtimeEpoch,
+      available: storeScope !== null,
+      errorCode: !storeScope && injectedIdentity ? injectedIdentity.errorCode || 'STORE_SCOPE_UNAVAILABLE' : null,
+    });
+    this.apiPrefix = String(options.apiPrefix || '/api/claude-workbench/v1').replace(/\/$/, '');
+    // Read from the synced manifest — a hardcoded literal here shipped 0.3.0
+    // in every /health response long after the actual release moved on.
+    this.version = options.version || require('../package.json').version;
+    this.maxSessions = Number(options.maxSessions || 50);
+    this.maxConcurrentRuns = Number(options.maxConcurrentRuns || 4);
+    this.testWorkspace = path.resolve(options.testWorkspace);
+    this.auditFile = options.auditFile;
+    this.historyRoot = options.historyRoot || path.join(path.dirname(this.auditFile || this.testWorkspace), 'session-history');
+    this.histories = new Map();
+    // Per-session native-fact committer closures, cached so every attach
+    // passes the SAME function reference: the runner's binding contract
+    // treats a different reference under the same identity as an owner
+    // conflict, and a naive closure-per-call would break idempotence.
+    this.nativeCommitters = new Map();
+    this.turnMonitors = new Map();
+    this.sessionAgents = new Map();
+    this.sessionRevision = 0;
+    this.sessionChangeLog = [];
+    this.sessionChangeListeners = new Set();
+    this.sessionSignatures = new Map();
+    const archiveRetentionDays = options.archiveRetentionDays === undefined ? 7 : Number(options.archiveRetentionDays);
+    this.archiveRetentionMs = Number.isFinite(archiveRetentionDays) && archiveRetentionDays > 0
+      ? archiveRetentionDays * 24 * 60 * 60 * 1000
+      : 0;
+    this.archiveSweeper = null;
+    // Archived sessions past the retention window are purged on boot and
+    // once a day for the lifetime of the process.
+    if (this.sessionArchive && this.archiveRetentionMs > 0) {
+      this.purgeExpiredArchivedSessions();
+      this.archiveSweeper = setInterval(() => {
+        try { this.purgeExpiredArchivedSessions(); } catch { /* retried next sweep */ }
+      }, Number(options.archiveSweepIntervalMs || 24 * 60 * 60 * 1000));
+      if (typeof this.archiveSweeper.unref === 'function') this.archiveSweeper.unref();
+    }
+    fs.mkdirSync(this.testWorkspace, { recursive: true });
+  }
+
+  health() {
+    // One observation point: both counters must come from the same
+    // listSessions snapshot, or a mid-mutation probe disagrees with itself
+    // and pays the full store scan twice.
+    const sessions = this.runner.listSessions({});
+    return {
+      status: 'ok', version: this.version, apiVersion: 'v1',
+      activeProcesses: this._activeCount(sessions), sessions: sessions.length,
+      time: new Date().toISOString(),
+      taskIdentity: { ...this.taskIdentity },
+      ...(this.conversationCapture ? { conversationCapture: { ...this.conversationCapture.status(), enabled: this.captureSettings?.read().terminalConversations === true } } : {}),
+    };
+  }
+
+  async runtime() {
+    let executable = null;
+    try { executable = await (this.resolveRuntimeExecutable ? this.resolveRuntimeExecutable() : this.runner.findClaudeExecutableForSdk()); } catch {}
+    const command = executable && (executable.cmd || executable);
+    return { runtime: 'claude-code', available: Boolean(command), executable: command ? path.basename(String(command)) : null, transport: 'agent-sdk' };
+  }
+
+  // Live availability probing when a discovery provider is wired in,
+  // otherwise fall back to what the injected runner can see.
+  listAgents() {
+    if (this.agentDiscovery) {
+      return { agents: Object.values(this.agentDiscovery()), scan: this.agentDiscovery.snapshot?.() };
+    }
+    let claudeAvailable = false;
+    try { const executable = this.runner.findClaudeExecutableForSdk(); claudeAvailable = Boolean(typeof executable === 'string' ? executable : executable?.cmd); } catch {}
+    return {
+      agents: Object.keys(AGENTS).map(id => {
+        const agent = AGENTS[id];
+        return {
+          id: agent.id, label: agent.label, transport: agent.transport,
+          authModes: [...agent.authModes],
+          capabilities: { ...agent.capabilities, generationParams: [...agent.capabilities.generationParams] },
+          available: id === 'claude-code' ? claudeAvailable : false,
+          version: null, reason: '',
+        };
+      }),
+    };
+  }
+
+  refreshAgents() {
+    if (this.agentDiscovery?.refresh) void this.agentDiscovery.refresh().catch(() => {});
+    return this.listAgents();
+  }
+
+  listProfiles() { return { profiles: this.profiles.list() }; }
+  getProfile(id) { return this.profiles.get(id); }
+  saveProfile(input, id) { return this.profiles.save(input, id); }
+  deleteProfile(id) { return this.profiles.delete(id); }
+  setCredential(id, credential) { return this.profiles.setCredential(id, credential); }
+
+  getCaptureSettings() {
+    if (!this.captureSettings) return { schema: 'capture-settings/v1', terminalConversations: false };
+    return this.captureSettings.read();
+  }
+
+  saveCaptureSettings(input = {}) {
+    if (!this.captureSettings) {
+      throw Object.assign(new Error('capture settings are not wired into this service'), { status: 501 });
+    }
+    const saved = this.captureSettings.save(input);
+    // Push the new scope into the driver immediately: sessions started after
+    // this call carry the matching AI_CODING_EVENT_BRIDGE_CAPTURE env.
+    if (typeof this.onCaptureSettingsSaved === 'function') this.onCaptureSettingsSaved(saved.terminalConversations);
+    return saved;
+  }
+
+  // ---- projects ----
+  listProjects() {
+    this._requireProjects();
+    return { projects: this.projects.list() };
+  }
+
+  getProject(id) {
+    this._requireProjects();
+    const projectId = cleanId(id, 'projectId');
+    const project = this.projects.get(projectId);
+    if (!project) throw Object.assign(new Error('project not found'), { status: 404 });
+    return project;
+  }
+
+  createProject(input = {}) {
+    this._requireProjects();
+    const project = this.projects.create(input);
+    this.contexts.register(project.id, project.rootPath);
+    this._audit('project-create', { projectId: project.id, rootPath: project.rootPath });
+    return project;
+  }
+
+  renameProject(id, input = {}) {
+    this._requireProjects();
+    const projectId = cleanId(id, 'projectId');
+    if (input.defaultAiProfileId) this.profiles.runtimeProfile(input.defaultAiProfileId);
+    const project = this.projects.update(projectId, input);
+    this._audit('project-rename', { projectId, name: project.name });
+    return project;
+  }
+
+  removeProject(id, options = {}) {
+    this._requireProjects();
+    const projectId = cleanId(id, 'projectId');
+    if (!this.projects.get(projectId)) throw Object.assign(new Error('project not found'), { status: 404 });
+    const keepSessions = options.keepSessions === true;
+    for (const session of this.runner.listSessions({ projectSlug: projectId })) {
+      if (ACTIVE_STATES.has(session.state) || session.backgroundTaskCount > 0) try { this.runner.abort(session.sessionId); } catch {}
+      if (!keepSessions) {
+        let deleted = false;
+        if (typeof this.runner.deleteSession === 'function') {
+          try { deleted = this.runner.deleteSession(session.sessionId) !== false; } catch {}
+        }
+        this.sessionArchive && this.sessionArchive.forget(session.sessionId);
+        this.knowledge?.forget(session.sessionId);
+        if (deleted) { this._removeHistory(session.sessionId); this._notifySessionDeleted(session); }
+      }
+      this.sessionAgents.delete(session.sessionId);
+    }
+    this.projects.remove(projectId);
+    this.contexts.unregister && this.contexts.unregister(projectId);
+    this._audit('project-remove', { projectId, keepSessions });
+    return true;
+  }
+
+  _requireProjects() {
+    if (!this.projects) throw Object.assign(new Error('project workspace support is not enabled'), { status: 501 });
+  }
+
+  // ---- session archive ----
+  archiveSession(sessionId) {
+    this._requireArchive();
+    const id = cleanId(sessionId, 'sessionId');
+    if (!this.runner.getState(id)) throw Object.assign(new Error('session not found'), { status: 404 });
+    const record = this.sessionArchive.archive(id);
+    this._notifySessionChange(id);
+    this._audit('session-archive', { sessionId: id });
+    return { sessionId: id, ...record };
+  }
+
+  restoreSession(sessionId) {
+    this._requireArchive();
+    const id = cleanId(sessionId, 'sessionId');
+    if (!this.runner.getState(id)) throw Object.assign(new Error('session not found'), { status: 404 });
+    const restored = this.sessionArchive.restore(id);
+    this._notifySessionChange(id);
+    this._audit('session-restore', { sessionId: id });
+    return { sessionId: id, restored };
+  }
+
+  // Archived sessions never restored within the retention window are deleted
+  // outright: the runner record goes first (best effort) and the archive mark
+  // only once the record is gone — a failed delete keeps the session hidden
+  // and retries on the next sweep instead of resurfacing unarchived.
+  purgeExpiredArchivedSessions() {
+    if (!this.sessionArchive || !(this.archiveRetentionMs > 0)) return [];
+    const purged = [];
+    for (const sessionId of this.sessionArchive.expired(this.archiveRetentionMs)) {
+      const previous = this.runner.getState(sessionId);
+      let deleted = true;
+      if (typeof this.runner.deleteSession === 'function') {
+        try { this.runner.deleteSession(sessionId); } catch { deleted = false; }
+      }
+      this.sessionAgents.delete(sessionId);
+      if (deleted) {
+        if (previous) this._notifySessionDeleted(previous);
+        this._removeHistory(sessionId);
+        this.knowledge?.forget(sessionId);
+        this.sessionArchive.forget(sessionId);
+        purged.push(sessionId);
+        this._audit('archive-expired', { sessionId });
+      }
+    }
+    return purged;
+  }
+
+  getUiPreferences() {
+    if (!this.uiPreferences) throw Object.assign(new Error('ui preferences support is not enabled'), { status: 501 });
+    return this.uiPreferences.read();
+  }
+
+  saveUiPreferences(input = {}) {
+    if (!this.uiPreferences) throw Object.assign(new Error('ui preferences support is not enabled'), { status: 501 });
+    return this.uiPreferences.save(input);
+  }
+
+  _requireArchive() {
+    if (!this.sessionArchive) throw Object.assign(new Error('session archive support is not enabled'), { status: 501 });
+  }
+
+  listSessions(contextId, options = {}) {
+    const id = cleanId(contextId, 'contextId');
+    const includeArchived = Boolean(options.includeArchived);
+    const all = this.runner.listSessions({ projectSlug: id });
+    const visible = includeArchived || !this.sessionArchive
+      ? all
+      : all.filter(session => !this.sessionArchive.isArchived(session.sessionId));
+    return visible.map((session, index) => this._summary(session, index === 0));
+  }
+
+  startSession(contextInput, aiProfileId, options = {}) {
+    if (this.destroyed) throw Object.assign(new Error('workbench is shut down'), { status: 503 });
+    const context = normalizeContext(contextInput);
+    if (this.runner.listSessions({}).length >= this.maxSessions) {
+      throw Object.assign(new Error('session limit reached'), { status: 429 });
+    }
+    const resolved = this.contexts.resolve(context);
+    const project = this.projects && this.projects.get(context.workspaceRef);
+    const agentId = normalizeAgentId(options.agentId || context.agentId || project && project.defaultAgentId);
+    const effort = normalizeEffort(options.effort);
+    // null explicitly selects the agent's login; omission inherits the project.
+    const profileChoice = aiProfileId !== undefined ? aiProfileId
+      : context.aiProfileId !== undefined ? context.aiProfileId : project && project.defaultAiProfileId;
+    const profileId = profileChoice ? cleanId(profileChoice, 'aiProfileId') : null;
+    const inheritsProject = aiProfileId === undefined && context.aiProfileId === undefined;
+    const selectedModel = options.model !== undefined ? options.model
+      : context.model !== undefined ? context.model : inheritsProject && project ? project.defaultModel : undefined;
+    const profile = this._runtimeProfile(profileId, selectedModel);
+    const started = this.runner.startChatSession({
+      slug: context.contextId,
+      projectPath: resolved.workspacePath,
+      kbPath: resolved.workspacePath,
+      // Persisted so later delegations can prove this session's trusted
+      // workspace without guessing from the current UI project.
+      workspaceRef: context.workspaceRef,
+      aiProfile: profile,
+      permissionMode: options.permissionMode || profile.permissionMode || 'default',
+      agentId,
+      effort,
+    });
+    // CLI drivers recycle numeric ids after a restart; a fresh session must
+    // not inherit the archived flag of an unrelated predecessor that happened
+    // to hold the same id.
+    if (this.sessionArchive && this.sessionArchive.isArchived(started.sessionId)) {
+      this.sessionArchive.forget(started.sessionId);
+    }
+    this.sessionAgents.set(started.sessionId, agentId);
+    // The native-task scope is bound from trusted service identity at
+    // session creation, before any input can arrive.
+    this._attachNativeTasks(started.sessionId);
+    const session = this.runner.getSession(started.sessionId);
+    if (session) {
+      session.selectedModel = profile.mainModel || null;
+      session.metadata = { ...(session.metadata || {}), inputOrigin: normalizeInputOrigin(options.inputOrigin) };
+    }
+    this._trackHistory(started.sessionId);
+    this._notifySessionChange(started.sessionId);
+    this._audit('session-start', { sessionId: started.sessionId, contextId: context.contextId, profileId, agentId });
+    return this._summary(this.runner.getState(started.sessionId), true);
+  }
+
+  loadSession(sessionId) {
+    const id = cleanId(sessionId, 'sessionId');
+    const state = this.runner.getState(id);
+    if (!state) throw Object.assign(new Error('session not found'), { status: 404 });
+    // An existing session binds its fixed native-task scope on first Service
+    // attach; it can never switch to a different one afterwards.
+    this._attachNativeTasks(id);
+    const usage = this.runner.getSessionTokenUsage(id);
+    return {
+      session: this._summary(state, true),
+      events: snapshotEvents(this.runner, id),
+      permission: state.pendingPermission || null,
+      permissionMode: state.permissionMode || 'default',
+      tokenUsage: { ...usage, hasUsage: Boolean(usage && (usage.used || usage.inputTokens || usage.outputTokens)) },
+    };
+  }
+
+  // Trusted-scope injection: the store scope, the runtime epoch and the
+  // durable-fact committer come from the frozen service task identity only -
+  // browser input and session options never reach them. Without a usable
+  // store identity the native-task feature stays explicitly unavailable
+  // while chat and history continue unchanged.
+  _attachNativeTasks(sessionId) {
+    if (!sessionId || !this.taskIdentity.available || !this.taskIdentity.storeScope) return false;
+    if (typeof this.runner.attachNativeTaskRuntime !== 'function') return false;
+    let committer = this.nativeCommitters.get(sessionId);
+    if (!committer) {
+      committer = this._nativeFactCommitter(sessionId);
+      this.nativeCommitters.set(sessionId, committer);
+    }
+    try {
+      const result = this.runner.attachNativeTaskRuntime(sessionId, {
+        storeScope: this.taskIdentity.storeScope,
+        runtimeEpoch: this.taskIdentity.runtimeEpoch,
+        commitNativeFact: committer,
+      });
+      return Boolean(result && result.attached);
+    } catch {
+      return false;
+    }
+  }
+
+  // The one trusted synchronous committer the runner's publish gate calls
+  // BEFORE a native fact reaches any buffer, listener or persisted
+  // snapshot. It goes through the sequence-validated durable receipt path
+  // (write + fsync), never a raw file bypass: a duplicate of an
+  // already-committed same-sequence fact is an idempotent success, a
+  // same-sequence disagreement is an explicit conflict failure, and a
+  // history that cannot even be attached is a fixed unavailable phase.
+  _nativeFactCommitter(sessionId) {
+    return event => {
+      try {
+        const history = this._history(sessionId);
+        const sequence = Number(event && event.sequence);
+        if (!Number.isSafeInteger(sequence) || sequence <= 0) {
+          return { ok: false, phase: 'sequence', error: 'native fact is not sequence-stamped' };
+        }
+        if (sequence <= history.highWater) {
+          const known = history.durableRow(sequence);
+          if (known && canonicalNativeFact(known) === canonicalNativeFact(event)) {
+            return { ok: true, phase: 'already-committed', sequence, highWater: history.highWater };
+          }
+          return {
+            ok: false, phase: 'conflict',
+            error: `native fact at sequence ${sequence} conflicts with the committed row`,
+            highWater: history.highWater,
+          };
+        }
+        return history.appendDurable([event]);
+      } catch {
+        return { ok: false, phase: 'history-unavailable', error: 'session history is not attachable' };
+      }
+    };
+  }
+
+  // Unbind this Service's own committer (same epoch + same closure
+  // reference); a different or second instance is refused by the runner.
+  _detachNativeTasks(sessionId) {
+    const committer = this.nativeCommitters.get(sessionId) || null;
+    this.nativeCommitters.delete(sessionId);
+    if (typeof this.runner.detachNativeTaskRuntime !== 'function') return;
+    try {
+      this.runner.detachNativeTaskRuntime(sessionId, {
+        runtimeEpoch: this.taskIdentity.runtimeEpoch,
+        commitNativeFact: committer,
+      });
+    } catch { /* binding already gone */ }
+  }
+
+  _history(id) {
+    if (this.histories.has(id)) return this.histories.get(id).history;
+    const session = this.runner.getSession(id);
+    const state = this.runner.getState(id);
+    if (!session || !state) throw Object.assign(new Error('session not found'), { status: 404 });
+    const first = session.outputBuffer?.[0];
+    const history = new SessionHistory({ file: this._historyFile(id), sessionId: id, startedAt: state.startedAt,
+      contextId: state.projectSlug, incomplete: Number(first?.sequence) > 1
+        || Number(session.turns) > (session.outputBuffer || []).filter(event => event.type === 'claude/user-prompt').length,
+      onError: error => this.diagnostics?.error('session.history.write.failed', '会话历史保存失败。', { phase: 'history', error: { code: error.code || 'HISTORY_WRITE_FAILED', message: '无法写入会话历史。' }, context: { sessionId: id } }),
+    });
+    this._reconcileHistory(id, history, session);
+    const unsubscribe = this.runner.subscribe(id, event => {
+      if (NATIVE_FACT_TYPES.has(event.type)) {
+        const sequence = Number(event.sequence);
+        if (Number.isSafeInteger(sequence) && sequence > 0 && sequence <= history.highWater) {
+          const known = history.durableRow(sequence);
+          if (known && canonicalNativeFact(known) === canonicalNativeFact(event)) {
+            // Idempotent replay of a committed fact - including the very
+            // fact the publish gate's committer just landed: no second
+            // write, but the session-change notification must still fire.
+          } else {
+            // A same-sequence fact is never blindly treated as "already
+            // written" and never overwrites the committed row: either the
+            // numbered row is missing or it disagrees with the replayed fact,
+            // and either way the conflict is an explicit diagnosis.
+            this.diagnostics?.error('session.history.durable.conflict', '原生任务事实与持久化历史同序号冲突；拒绝改写，原文件已保留。', {
+              phase: 'history', error: { code: 'HISTORY_DURABLE_CONFLICT', message: `native fact at sequence ${sequence} conflicts with the committed row` },
+              context: { sessionId: id, sequence, present: Boolean(known) },
+            });
+            return;
+          }
+        } else {
+          // Fallback for native facts that flowed ungated (a runner without
+          // a bound committer): the receipt is diagnosed, never faked.
+          const receipt = history.appendDurable([event]);
+          if (!receipt.ok) this.diagnostics?.error('session.history.durable.failed', '原生任务事实未能持久化；任务历史不可用，原文件已保留。', {
+            phase: 'history', error: { code: `HISTORY_DURABLE_${String(receipt.phase).toUpperCase()}`, message: String(receipt.error || 'durable append failed') },
+            context: { sessionId: id, highWater: receipt.highWater, pendingCount: receipt.pendingCount ?? null },
+          });
+        }
+      } else history.append(event);
+      this._notifySessionChange(id, event);
+    });
+    this.histories.set(id, { history, unsubscribe });
+    return history;
+  }
+
+  // Forward-only reconciliation between the runner snapshot counter and the
+  // durable journal, run once when a session's history is attached and
+  // therefore before any new sequence is minted for it. The old behavior
+  // reset a newer durable high-water mark back to an older snapshot count,
+  // which both silently dropped fresh events (sequence at or below the reset
+  // mark) and re-minted sequences the file already contained. Now both
+  // sides adopt max(snapshot, durable) and the losing side is repaired or
+  // explicitly marked instead of being rewritten: durable-ahead merges the
+  // missing durable tail into the replay buffer so subscribers can be
+  // served the gap; snapshot-ahead replays the contiguous in-memory prefix
+  // through the durable receipt path, and a hole that cannot be
+  // reconstructed is recorded as a recovery gap — never faked as complete.
+  _reconcileHistory(id, history, session) {
+    if (!history.exists || !Number.isFinite(session.eventSequence)) return;
+    const buffered = Array.isArray(session.outputBuffer) ? session.outputBuffer : [];
+    let bufferedMax = 0;
+    for (const event of buffered) {
+      const own = Number(event && event.sequence);
+      if (Number.isFinite(own) && own > 0 && own > bufferedMax) bufferedMax = own;
+    }
+    if (history.highWater > session.eventSequence) {
+      const tail = history.durableTail({ afterSequence: bufferedMax });
+      const lastDeltaSequence = new Map();
+      for (let i = buffered.length - 1; i >= 0; i--) {
+        const event = buffered[i];
+        if (!event || !DELTA_TYPES.has(event.type)) continue;
+        const id = event.id ?? null;
+        if (!lastDeltaSequence.has(id)) lastDeltaSequence.set(id, Number(event.sequence) || 0);
+      }
+      for (const event of tail.events) {
+        if (event && DELTA_TYPES.has(event.type)) {
+          const id = event.id ?? null;
+          const coveredFrom = compactionCoverage(buffered, event, lastDeltaSequence.get(id) || 0);
+          if (coveredFrom !== null) {
+            // A durable compaction subsumes fragments the replay buffer
+            // still holds in part: the merged row replaces them instead of
+            // concatenating onto them, so no client's cached prefix is
+            // duplicated and a cursor below the merged row resyncs
+            // explicitly instead of receiving the whole fragment as a delta.
+            for (let i = buffered.length - 1; i >= 0; i--) {
+              const held = buffered[i];
+              if (held && DELTA_TYPES.has(held.type) && held.id === event.id && Number(held.sequence) >= coveredFrom) buffered.splice(i, 1);
+            }
+            lastDeltaSequence.set(id, Number(event.sequence) || 0);
+          } else if (Number.isFinite(Number(event.sequence))) {
+            lastDeltaSequence.set(id, Math.max(lastDeltaSequence.get(id) || 0, Number(event.sequence)));
+          }
+        }
+        buffered.push(event);
+        while (buffered.length > 5000) buffered.shift();
+      }
+      session.eventSequence = Math.max(session.eventSequence, history.highWater);
+      return;
+    }
+    if (session.eventSequence > history.highWater) {
+      const above = [];
+      for (const event of buffered) {
+        const own = Number(event && event.sequence);
+        if (Number.isFinite(own) && own > history.highWater) above.push([own, event]);
+      }
+      above.sort((a, b) => a[0] - b[0]);
+      const catchUp = [];
+      let expected = history.highWater + 1;
+      for (const [sequence, event] of above) {
+        if (sequence !== expected) break;
+        catchUp.push(event);
+        expected += 1;
+      }
+      if (catchUp.length) {
+        const receipt = history.appendDurable(catchUp);
+        if (!receipt.ok) {
+          this.diagnostics?.error('session.history.reconcile.failed', '崩溃边界恢复未能补写会话历史；原文件已保留。', {
+            phase: 'history', error: { code: `HISTORY_DURABLE_${String(receipt.phase).toUpperCase()}`, message: String(receipt.error || 'durable append failed') },
+            context: { sessionId: id, highWater: receipt.highWater },
+          });
+          return;
+        }
+      }
+      if (history.highWater < session.eventSequence) {
+        // The gap marker is journaled, not kept in RAM: a restart must keep
+        // reporting the hole instead of presenting a healed-looking archive.
+        // A failed marker receipt is explicit and stays retryable — the
+        // next reconcile rewrites it instead of skipping it.
+        const recorded = history.recordRecoveryGap(history.highWater + 1, session.eventSequence);
+        if (!recorded.ok) {
+          this.diagnostics?.error('session.history.recovery.record.failed', '缺口标记未能持久化；原文件已保留，保持可重试。', {
+            phase: 'history', error: { code: `HISTORY_DURABLE_${String(recorded.phase).toUpperCase()}`, message: String(recorded.error || 'gap marker write failed') },
+            context: { sessionId: id, from: history.highWater + 1, to: session.eventSequence },
+          });
+        }
+        this.diagnostics?.error('session.history.recovery.gap', '会话历史存在无法重建的序号缺口；历史读取将显式标注。', {
+          phase: 'history', error: { code: 'HISTORY_RECOVERY_GAP', message: '快照与持久化历史之间存在缺口，不能宣称完整。' },
+          context: { sessionId: id, from: history.highWater + 1, to: session.eventSequence },
+        });
+      }
+    }
+  }
+
+  _trackHistory(id) {
+    try { return this._history(id); }
+    catch (error) {
+      this.diagnostics?.error('session.history.read.failed', '会话历史读取失败；实时会话仍可使用。', {
+        phase: 'history', error: { code: error.code || 'HISTORY_READ_FAILED', message: '会话历史不可用，原文件已保留。' }, context: { sessionId: id },
+      });
+      return null;
+    }
+  }
+
+  loadHistory(sessionId, options = {}) {
+    const id = cleanId(sessionId, 'sessionId');
+    try {
+      const history = this._history(id);
+      const state = this.runner.getState(id);
+      if (history.incomplete && !ACTIVE_STATES.has(state.state) && this._summary(state, false).agentId === 'claude-code') {
+        const session = this.runner.getSession(id);
+        const recovered = recoverClaudeHistory(session);
+        if (recovered) history.seedRecovered(recovered, Number(session.eventSequence) || history.highWater);
+      }
+      return history.read(options);
+    } catch (error) {
+      if (![400, 404].includes(error.status)) {
+        this.diagnostics?.error('session.history.read.failed', '会话历史读取失败，原文件已保留。', {
+          phase: 'history', error: { code: error.code || 'HISTORY_READ_FAILED', message: '无法读取完整会话历史。' }, context: { sessionId: id },
+        });
+        error.status = 503;
+      }
+      throw error;
+    }
+  }
+
+  _removeHistory(id) {
+    this.knowledgeBySession.delete(id);
+    this._detachNativeTasks(id);
+    const record = this.histories.get(id);
+    record?.unsubscribe(); record?.history.close();
+    this.histories.delete(id);
+    try { fs.unlinkSync(this._historyFile(id)); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+
+  _historyFile(id) { return path.join(this.historyRoot, `${crypto.createHash('sha256').update(id).digest('hex')}.jsonl`); }
+
+  // ---- native task history (read-only over the session's own journal) ----
+
+  // The fixed scope every native-task read is bound to: the frozen trusted
+  // store identity plus the session's real project and id. Nothing in it is
+  // client-derived; the client only ever echoes it back for comparison.
+  _nativeTaskScope(state) {
+    return { storeScope: this.taskIdentity.storeScope, contextId: state.projectSlug, parentSessionId: state.sessionId };
+  }
+
+  _requireNativeTaskScope() {
+    if (!this.taskIdentity.available || !this.taskIdentity.storeScope) {
+      throw Object.assign(new Error('native task history is unavailable: the trusted store scope is not configured'), {
+        status: 503, code: this.taskIdentity.errorCode || 'STORE_SCOPE_UNAVAILABLE',
+      });
+    }
+    return this.taskIdentity.storeScope;
+  }
+
+  // The reader file always comes from the service's own session-history
+  // instance; recovery seeds never run on this path, and a failure keeps the
+  // original file and surfaces as an explicit unavailable answer.
+  _nativeHistoryFor(id) {
+    try {
+      return this._history(id);
+    } catch (error) {
+      if (error && (error.status === 400 || error.status === 404)) throw error;
+      throw Object.assign(new Error('native task history is not readable; the original history file is preserved'), {
+        status: 503, code: error && error.code ? error.code : 'HISTORY_READ_FAILED',
+      });
+    }
+  }
+
+  // A journal that has proven a write failure is never served as complete
+  // history: the newest facts may still live only in memory, so a page off
+  // the disk would silently omit them. Mirrors the SessionHistory read gate
+  // with a fixed safe message; the latched code token travels as the code.
+  // The same hole exists whenever ANY native fact is still pending behind a
+  // durable barrier - a recovery gap whose marker is not yet on disk, or a
+  // failed batch still awaiting its close-time marker: while the barrier
+  // head exists the native surfaces refuse with one generic pending code
+  // instead of serving the journal as complete. Ordinary chat reads are
+  // untouched, and a cleared barrier restores these reads.
+  _requireDurableJournal(history) {
+    if (history.error) {
+      throw Object.assign(new Error('会话历史写入失败，原文件已保留；原生任务历史暂不可用。'), { status: 503, code: history.error });
+    }
+    if (history.durableBarrier) {
+      throw Object.assign(new Error('尚有未提交历史事实，原生任务历史暂不可用。'), { status: 503, code: 'HISTORY_FACTS_PENDING' });
+    }
+  }
+
+  // The journal may know a recovery gap the on-disk scan can no longer see
+  // (the marker row disappeared after attach). The reader's own verdict
+  // stays untouched; the service-known hole is merged in, never dropped.
+  _nativeGapOverlay(history, page) {
+    const gap = history.recoveryGap;
+    if (!gap || page.incomplete.includes('history-gap')) return page;
+    const items = [{ code: 'service-recovery-gap', source: 'service', from: gap.from, to: gap.to }].concat(page.diagnostics.items);
+    const total = page.diagnostics.total + 1;
+    return {
+      ...page,
+      incomplete: [...page.incomplete, 'history-gap'],
+      diagnostics: { items: items.slice(0, 20), total, truncated: total > 20 },
+    };
+  }
+
+  // GET /sessions/:id/native-tasks - list observed native background tasks
+  // for the session out of its durable history. Pure read: no input is
+  // dispatched and no live handle is created; task rows are historical
+  // observations, never claims that anything is running or controllable.
+  async listNativeTasks(sessionId, query = {}) {
+    const id = cleanId(sessionId, 'sessionId');
+    const state = this.runner.getState(id);
+    if (!state) throw Object.assign(new Error('session not found'), { status: 404 });
+    const storeScope = this._requireNativeTaskScope();
+    if (typeof query.storeScope !== 'string' || query.storeScope === '') {
+      throw Object.assign(new Error('storeScope is required'), { status: 400 });
+    }
+    if (!STORE_SCOPE_PATTERN.test(query.storeScope)) {
+      throw Object.assign(new Error('storeScope is invalid'), { status: 400 });
+    }
+    if (typeof query.contextId !== 'string' || query.contextId === '') {
+      throw Object.assign(new Error('contextId is required'), { status: 400 });
+    }
+    const contextId = cleanId(query.contextId, 'contextId');
+    if (query.storeScope !== storeScope || contextId !== state.projectSlug) {
+      throw Object.assign(new Error('native task scope does not match this session; resync from the task list'), {
+        status: 409, code: 'SCOPE_MISMATCH', resync: true,
+      });
+    }
+    const history = this._nativeHistoryFor(id);
+    this._requireDurableJournal(history);
+    const scope = this._nativeTaskScope(state);
+    const reader = createNativeTaskHistoryReader({ file: history.file, scope });
+    let page;
+    try { page = await reader.listTasks(); }
+    catch (error) { if (error && error.status === 409) error.resync = true; throw error; }
+    return { ...this._nativeGapOverlay(history, page), scope: { ...scope } };
+  }
+
+  // POST /sessions/:id/native-tasks/history - page one bound task's events
+  // out of the same durable history. Pure read: no dispatch, no stop, no
+  // re-minted sequences, no SSE replay.
+  async loadNativeTaskHistory(sessionId, input = {}) {
+    const id = cleanId(sessionId, 'sessionId');
+    const state = this.runner.getState(id);
+    if (!state) throw Object.assign(new Error('session not found'), { status: 404 });
+    this._requireNativeTaskScope();
+    const ref = createNativeTaskRef(input && input.taskRef);
+    if (!ref) throw Object.assign(new Error('taskRef is not a valid native-task reference'), { status: 400, code: 'INVALID_TASK_REF' });
+    // The whole reference is checked against the real session scope before
+    // any journal is constructed or read, so a foreign-scope ref is a scope
+    // conflict even when the target file is missing or corrupt.
+    const scope = this._nativeTaskScope(state);
+    if (ref.storeScope !== scope.storeScope || ref.contextId !== scope.contextId || ref.parentSessionId !== scope.parentSessionId) {
+      throw Object.assign(new Error('taskRef scope does not match this session; resync from the task list'), {
+        status: 409, code: 'SCOPE_MISMATCH', resync: true,
+      });
+    }
+    const history = this._nativeHistoryFor(id);
+    this._requireDurableJournal(history);
+    const reader = createNativeTaskHistoryReader({ file: history.file, scope });
+    let page;
+    try { page = await reader.readTaskEvents(ref, { cursor: input.cursor, limit: input.limit }); }
+    catch (error) { if (error && error.status === 409) error.resync = true; throw error; }
+    return { ...this._nativeGapOverlay(history, page), taskRef: { ...ref }, scope: { ...scope } };
+  }
+
+  // ---- delegated sessions (trusted Workbench delegation commands) ----
+
+  _requireDelegations() {
+    if (!this.delegations || !this.delegations.ledger || !this.delegations.phases) {
+      throw Object.assign(new Error('delegated sessions are unavailable: the delegation ledger is not wired'), {
+        status: 503, code: 'DELEGATION_UNAVAILABLE',
+      });
+    }
+  }
+
+  _delegationSupported(agentId) {
+    if (typeof this.runner.supportsDelegatedSessions === 'function') {
+      return this.runner.supportsDelegatedSessions(agentId) === true;
+    }
+    return typeof this.runner.startDelegatedSession === 'function';
+  }
+
+  // The trusted workspace a delegated child inherits. Preference order: the
+  // parent's own persisted workspaceRef re-resolved through the real resolver,
+  // then — for sessions recorded before workspaceRef existed — a UNIQUE
+  // real-path match against the registered workspaces. Ambiguous or
+  // unresolvable is an explicit 409; the current UI project is never picked.
+  _delegationWorkspace(parentState) {
+    const parentSession = this.runner.getSession(parentState.sessionId);
+    const ref = parentSession && typeof parentSession.workspaceRef === 'string' && parentSession.workspaceRef
+      ? parentSession.workspaceRef : null;
+    if (ref) {
+      try {
+        const resolved = this.contexts.resolve({ contextId: parentState.projectSlug, workspaceRef: ref });
+        return { ref, rootPath: resolved.workspacePath };
+      } catch {
+        throw Object.assign(new Error('the parent workspace is no longer registered; no delegation was issued'), {
+          status: 409, code: 'DELEGATION_WORKSPACE_UNRESOLVED',
+        });
+      }
+    }
+    const recordedPath = parentSession && typeof parentSession.projectPath === 'string' && parentSession.projectPath
+      ? parentSession.projectPath : null;
+    if (!recordedPath) {
+      throw Object.assign(new Error('the parent session has no trusted workspace record; no delegation was issued'), {
+        status: 409, code: 'DELEGATION_WORKSPACE_UNRESOLVED',
+      });
+    }
+    const matches = this.contexts.findByRealPath(recordedPath);
+    if (matches.length === 1) return { ref: matches[0], rootPath: recordedPath };
+    if (matches.length === 0) {
+      throw Object.assign(new Error('the parent workspace does not match any registered workspace; no delegation was issued'), {
+        status: 409, code: 'DELEGATION_WORKSPACE_UNRESOLVED',
+      });
+    }
+    throw Object.assign(new Error('the parent workspace matches multiple registered workspaces; no delegation was issued'), {
+      status: 409, code: 'DELEGATION_WORKSPACE_AMBIGUOUS',
+    });
+  }
+
+  // Canonical command hash over EVERY choice that affects execution: the
+  // normalized text, the agent/profile/model/permission/effort selection and
+  // the resolved workspace and context mode. Only the command hash is stored;
+  // opt-in parent context is frozen separately on the private reservation.
+  _delegationPayloadHash(command) {
+    const canonical = JSON.stringify({
+      schema: 'workbench-delegation-command/v1',
+      text: command.text,
+      agentId: command.agentId,
+      aiProfileId: command.aiProfileId,
+      model: command.model,
+      permissionMode: command.permissionMode,
+      effort: command.effort || null,
+      workspaceRef: command.workspaceRef,
+      contextId: command.contextId,
+      parentSessionId: command.parentSessionId,
+      ...(command.contextMode ? { contextMode: command.contextMode } : {}),
+    });
+    return crypto.createHash('sha256').update(canonical, 'utf8').digest('hex');
+  }
+
+  _delegationDispatchState(record) {
+    const phases = this.delegations.phases.stateOf(record.delegationId);
+    const live = this.delegations.phases.isClaimLive(record.delegationId);
+    if (phases.outcome) {
+      const known = phases.outcome.outcome === 'dispatched';
+      return {
+        phase: known ? 'dispatched' : 'dispatch-unknown',
+        outcome: known ? 'dispatched' : 'unknown',
+        dispatch: { state: phases.outcome.outcome, attemptId: phases.outcome.attemptId, at: phases.outcome.at },
+        claim: phases.claim,
+      };
+    }
+    if (phases.claim) {
+      if (live) {
+        return { phase: 'dispatching', outcome: 'pending', dispatch: { state: 'dispatching', attemptId: phases.claim.attemptId }, claim: phases.claim };
+      }
+      // A claim nobody in this Service can still settle: the model receipt is
+      // unprovable, so the honest verdict is dispatch-unknown.
+      return {
+        phase: 'dispatch-unknown', outcome: 'unknown',
+        dispatch: { state: 'dispatch-unknown', attemptId: phases.claim.attemptId, reason: 'owner-unreachable' },
+        claim: phases.claim,
+      };
+    }
+    if (phases.childCreated) {
+      return { phase: 'child-created', outcome: 'not-dispatched', dispatch: { state: 'awaiting-dispatch' }, claim: null };
+    }
+    if (phases.childCreateFailed) {
+      return { phase: 'child-create-failed', outcome: 'not-started', dispatch: { state: 'not-dispatched', code: phases.childCreateFailed.code }, claim: null };
+    }
+    return { phase: 'reserved', outcome: 'not-started', dispatch: { state: 'not-dispatched' }, claim: null };
+  }
+
+  // Real child status straight from the runner. A missing child is reported
+  // as the explicit dangling fact it is — reads never resurrect it.
+  _delegationChild(record) {
+    const state = this.runner.getState(record.childSessionId);
+    if (!state) return { sessionId: record.childSessionId, present: false, state: 'missing' };
+    const summary = this._summary(state, ACTIVE_STATES.has(state.state));
+    return {
+      sessionId: record.childSessionId,
+      present: true,
+      state: state.state,
+      agentId: summary.agentId,
+      model: summary.model || null,
+      active: summary.active,
+      turns: summary.turns,
+      archived: summary.archived,
+    };
+  }
+
+  _delegationView(record) {
+    const status = this._delegationDispatchState(record);
+    return {
+      delegation: {
+        kind: 'delegated-session',
+        storeScope: record.scope.storeScope,
+        contextId: record.scope.contextId,
+        parentSessionId: record.scope.parentSessionId,
+        delegationId: record.delegationId,
+        childSessionId: record.childSessionId,
+        workspaceRef: record.workspace.ref,
+        requestId: record.requestId,
+        issuedAt: record.issuedAt,
+        source: record.source,
+        basis: record.basis,
+        sdkRunIdClaimed: false,
+        inputCausalityClaimed: false,
+        initiator: { type: 'external-api', authenticatedAs: null },
+        selection: { profileId: record.selection.profileId, model: record.selection.model },
+      },
+      phase: status.phase,
+      outcome: status.outcome,
+      dispatch: status.dispatch,
+      child: this._delegationChild(record),
+      ...(record.context ? { context: { mode: record.context.mode, truncated: record.context.truncated } } : {}),
+    };
+  }
+
+  _adoptDelegatedChild(childSessionId, agentId) {
+    this.sessionAgents.set(childSessionId, agentId);
+    this._attachNativeTasks(childSessionId);
+    this._trackHistory(childSessionId);
+    this._notifySessionChange(childSessionId);
+  }
+
+  _recordDelegationFailure(record, code) {
+    try {
+      this.delegations.phases.recordChildCreateFailed({ delegationId: record.delegationId, code });
+    } catch {
+      // The failure fact is diagnostics; the explicit error answer below is
+      // already the honest result and the reservation stays untouched.
+    }
+  }
+
+  // POST /sessions/:parentId/delegations — issue one delegation command.
+  // Frozen order (W1-DELEGATION-DECISIONS): validate → reserve (atomic fsync,
+  // idempotent by requestId, payload change = 409) → trusted child factory
+  // with the reserved identity (relation durable before anything else) →
+  // durable dispatch claim (exactly one owner) → send → durable outcome. Any
+  // unknown after the claim is reported as dispatch-unknown and never
+  // auto-re-input. accepted means the Workbench accepted the command, not
+  // that a model proved receipt.
+  async createDelegation(parentIdRaw, input = {}) {
+    this._requireDelegations();
+    const storeScope = this._requireNativeTaskScope();
+    const parentId = cleanId(parentIdRaw, 'sessionId');
+    if (!input || typeof input !== 'object' || Array.isArray(input)) {
+      throw Object.assign(new Error('delegation command must be an object'), { status: 400, code: 'DELEGATION_COMMAND_INVALID' });
+    }
+    const scopeInput = input.scope;
+    if (!scopeInput || typeof scopeInput !== 'object' || Array.isArray(scopeInput)
+      || Object.keys(scopeInput).length !== 2 || !('storeScope' in scopeInput) || !('contextId' in scopeInput)) {
+      throw Object.assign(new Error('scope must be an object with exactly storeScope and contextId; parentSessionId comes from the route'), {
+        status: 400, code: 'DELEGATION_SCOPE_INVALID',
+      });
+    }
+    if (typeof scopeInput.storeScope !== 'string' || !STORE_SCOPE_PATTERN.test(scopeInput.storeScope) || scopeInput.storeScope !== storeScope) {
+      throw Object.assign(new Error('scope.storeScope does not match this workbench; resync from health'), {
+        status: 409, code: 'DELEGATION_SCOPE_MISMATCH', resync: true,
+      });
+    }
+    const contextId = cleanId(scopeInput.contextId, 'contextId');
+    if (typeof input.requestId !== 'string' || !input.requestId.length || input.requestId.length > 256
+      || /[\u0000-\u001f\u007f]/.test(input.requestId)) {
+      throw Object.assign(new Error('requestId must be a non-empty string without control characters'), {
+        status: 400, code: 'DELEGATION_REQUEST_INVALID',
+      });
+    }
+    const requestId = input.requestId;
+    if (input.contextMode !== undefined && input.contextMode !== 'parent-snapshot') {
+      throw Object.assign(new Error('unsupported context mode'), { status: 400, code: 'DELEGATION_CONTEXT_INVALID' });
+    }
+    const text = typeof input.text === 'string' ? input.text.trim() : '';
+    if (!text || text.length > 200000) {
+      throw Object.assign(new Error('text must be a non-empty command of at most 200000 characters'), {
+        status: 400, code: 'DELEGATION_TEXT_INVALID',
+      });
+    }
+    const agentId = normalizeAgentId(input.agentId === undefined || input.agentId === null || input.agentId === '' ? undefined : input.agentId);
+    const effort = input.effort === undefined || input.effort === null || input.effort === '' ? undefined : normalizeEffort(input.effort);
+    const permissionMode = input.permissionMode === undefined || input.permissionMode === null || input.permissionMode === ''
+      ? 'default' : input.permissionMode;
+    if (!PERMISSION_MODES.includes(permissionMode)) {
+      throw Object.assign(new Error('permissionMode is invalid'), { status: 400, code: 'DELEGATION_SELECTION_REJECTED' });
+    }
+    if (input.metadata !== undefined || input.inputOrigin !== undefined) {
+      throw Object.assign(new Error('caller metadata does not grant trusted relations; omit metadata and inputOrigin'), {
+        status: 400, code: 'DELEGATION_CALLER_IDENTITY_REJECTED',
+      });
+    }
+
+    const parentState = this.runner.getState(parentId);
+    if (!parentState) throw Object.assign(new Error('parent session not found'), { status: 404, code: 'DELEGATION_PARENT_NOT_FOUND' });
+    if (parentState.projectSlug !== contextId) {
+      throw Object.assign(new Error('scope.contextId does not match the parent session; resync from the session list'), {
+        status: 409, code: 'DELEGATION_SCOPE_MISMATCH', resync: true,
+      });
+    }
+    if (!this._delegationSupported(agentId)) {
+      throw Object.assign(new Error(`agent "${agentId}" cannot run delegated sessions with a server-reserved identity`), {
+        status: 501, code: 'DELEGATION_AGENT_UNSUPPORTED',
+      });
+    }
+    // The selection resolves NOW so the payload hash covers the concrete
+    // profile/model the child will run with (unknown profile → 404 here).
+    const aiProfileId = input.aiProfileId === undefined ? (parentState.aiProfileId || null)
+      : input.aiProfileId === null ? null : cleanId(input.aiProfileId, 'aiProfileId');
+    const profile = this._runtimeProfile(aiProfileId, input.model === undefined ? undefined : input.model);
+    const model = profile.mainModel || null;
+    const workspace = this._delegationWorkspace(parentState);
+    if (this.runner.listSessions({}).length >= this.maxSessions) {
+      throw Object.assign(new Error('session limit reached'), { status: 429, code: 'DELEGATION_SESSION_LIMIT' });
+    }
+    const payloadHash = this._delegationPayloadHash({
+      text, agentId, aiProfileId, model, permissionMode, effort,
+      workspaceRef: workspace.ref, contextId, parentSessionId: parentId,
+      contextMode: input.contextMode,
+    });
+
+    const record = this.delegations.ledger.reserve({
+      scope: { storeScope, contextId, parentSessionId: parentId },
+      requestId,
+      payloadHash,
+      workspace: { ref: workspace.ref, rootPath: workspace.rootPath, resolvedFrom: 'parent-session-record' },
+      selection: { profileId: aiProfileId, model },
+      ...(input.contextMode ? { context: () => {
+        this._history(parentId).flush();
+        const events = [];
+        let before;
+        do {
+          const page = this.loadHistory(parentId, { before, limit: 100 });
+          if (page.incomplete) throw Object.assign(new Error('parent conversation history is incomplete'), { status: 409, code: 'PARENT_CONTEXT_INCOMPLETE' });
+          events.unshift(...page.events);
+          before = page.nextCursor || null;
+        } while (before);
+        return parentContext(events, text);
+      } } : {}),
+    });
+    this._audit('delegation-reserve', {
+      delegationId: record.delegationId, parentSessionId: parentId, contextId, childSessionId: record.childSessionId,
+    });
+
+    // Once a dispatch claim exists the input may already have reached a
+    // model: never re-create, never re-send — report the durable truth.
+    const prior = this._delegationDispatchState(record);
+    if (prior.claim) return { accepted: true, ...this._delegationView(record) };
+
+    if (typeof this.runner.startDelegatedSession !== 'function') {
+      throw Object.assign(new Error(`agent "${agentId}" cannot run delegated sessions with a server-reserved identity`), {
+        status: 501, code: 'DELEGATION_AGENT_UNSUPPORTED',
+      });
+    }
+    let started;
+    try {
+      started = this.runner.startDelegatedSession({
+        agentId,
+        reservedSessionId: record.childSessionId,
+        delegation: {
+          delegationId: record.delegationId,
+          parentSessionId: parentId,
+          storeScope,
+          contextId,
+        },
+        slug: contextId,
+        projectPath: workspace.rootPath,
+        kbPath: workspace.rootPath,
+        workspaceRef: workspace.ref,
+        aiProfile: profile,
+        permissionMode,
+        ...(effort ? { effort } : {}),
+      });
+    } catch (error) {
+      const code = error && typeof error.code === 'string' && error.code.startsWith('DELEGATION_')
+        ? error.code : 'DELEGATION_CHILD_CREATE_FAILED';
+      this._recordDelegationFailure(record, code);
+      if (error && error.status) throw error;
+      throw Object.assign(new Error('the delegated child session could not be created; no model input was sent'), {
+        status: 500, code,
+      });
+    }
+    if (!started || started.sessionId !== record.childSessionId) {
+      this._recordDelegationFailure(record, 'DELEGATION_CHILD_IDENTITY_MISMATCH');
+      throw Object.assign(new Error('the driver did not honor the reserved child identity; no model input was sent'), {
+        status: 500, code: 'DELEGATION_CHILD_IDENTITY_MISMATCH',
+      });
+    }
+    this._adoptDelegatedChild(record.childSessionId, agentId);
+    this.delegations.phases.recordChildCreated({
+      delegationId: record.delegationId,
+      childSessionId: record.childSessionId,
+      workspaceRef: workspace.ref,
+    });
+    this._notifySessionChange(record.childSessionId);
+
+    // Guards mirroring send()'s own pre-input checks: a refusal here happens
+    // provably before any input, so no claim is written and the reservation
+    // simply reports awaiting-dispatch.
+    const childState = this.runner.getState(record.childSessionId);
+    if (!childState) {
+      this._recordDelegationFailure(record, 'DELEGATION_CHILD_CREATE_FAILED');
+      throw Object.assign(new Error('the delegated child session could not be created; no model input was sent'), {
+        status: 500, code: 'DELEGATION_CHILD_CREATE_FAILED',
+      });
+    }
+    if (ACTIVE_STATES.has(childState.state) || this.pendingInputs.has(record.childSessionId)) {
+      throw Object.assign(new Error('the delegated child already has an active turn; the command stays reserved'), {
+        status: 409, code: 'DELEGATION_CHILD_BUSY',
+      });
+    }
+    if (this._activeCount() >= this.maxConcurrentRuns) {
+      throw Object.assign(new Error('runtime concurrency limit reached'), { status: 429, code: 'DELEGATION_CONCURRENCY_LIMIT' });
+    }
+
+    // Durable dispatch claim BEFORE the send: exactly one owner across
+    // Services and processes; a lost claim never sends.
+    let claim;
+    try {
+      claim = this.delegations.phases.claimDispatch({
+        delegationId: record.delegationId,
+        attemptId: crypto.randomUUID(),
+        ownerPid: process.pid,
+        ownerEpoch: this.runtimeEpoch,
+      });
+    } catch (error) {
+      throw Object.assign(new Error('the dispatch attempt could not be recorded; no model input was sent'), {
+        status: 503, code: error && typeof error.code === 'string' ? error.code : 'DELEGATION_CLAIM_FAILED',
+      });
+    }
+    if (!claim.claimed) {
+      return { accepted: true, ...this._delegationView(record) };
+    }
+
+    let outcome = 'dispatched';
+    let failureCode = null;
+    try {
+      await this.send(record.childSessionId, text, {
+        [PARENT_CONTEXT]: record.context ? record.context.text : '',
+        inputOrigin: 'agent-delegation',
+        permissionMode,
+        ...(effort ? { effort } : {}),
+      });
+    } catch (error) {
+      outcome = 'dispatch-unknown';
+      failureCode = error && typeof error.code === 'string' ? error.code : null;
+    }
+    try {
+      this.delegations.phases.recordOutcome({
+        delegationId: record.delegationId,
+        attemptId: claim.claim.attemptId,
+        outcome,
+      });
+    } catch {
+      // The receipt could not be proven on disk after a possibly accepted
+      // input: the only honest durable verdict is dispatch-unknown.
+      outcome = 'dispatch-unknown';
+      this.delegations.phases.abandonLiveClaim({
+        delegationId: record.delegationId,
+        attemptId: claim.claim.attemptId,
+      });
+    }
+    this._audit('delegation-dispatch', { delegationId: record.delegationId, childSessionId: record.childSessionId, outcome });
+    const view = this._delegationView(record);
+    if (failureCode && outcome === 'dispatch-unknown') view.dispatch.errorCode = failureCode;
+    return { accepted: true, ...view };
+  }
+
+  // GET /sessions/:parentId/delegations — trusted relations, durable command
+  // facts and the real child status. Pure read: no session is created, no
+  // input is sent, nothing is refreshed back to life.
+  listDelegations(parentIdRaw, query = {}) {
+    this._requireDelegations();
+    const storeScope = this._requireNativeTaskScope();
+    const parentId = cleanId(parentIdRaw, 'sessionId');
+    const parentState = this.runner.getState(parentId);
+    if (!parentState) throw Object.assign(new Error('parent session not found'), { status: 404, code: 'DELEGATION_PARENT_NOT_FOUND' });
+    if (typeof query.storeScope !== 'string' || !STORE_SCOPE_PATTERN.test(query.storeScope)) {
+      throw Object.assign(new Error('storeScope is invalid'), { status: 400, code: 'DELEGATION_SCOPE_INVALID' });
+    }
+    if (typeof query.contextId !== 'string' || !query.contextId) {
+      throw Object.assign(new Error('contextId is required'), { status: 400, code: 'DELEGATION_SCOPE_INVALID' });
+    }
+    const contextId = cleanId(query.contextId, 'contextId');
+    if (query.storeScope !== storeScope || contextId !== parentState.projectSlug) {
+      throw Object.assign(new Error('delegation scope does not match this session; resync from the session list'), {
+        status: 409, code: 'DELEGATION_SCOPE_MISMATCH', resync: true,
+      });
+    }
+    const records = this.delegations.ledger.list({ storeScope, contextId, parentSessionId: parentId });
+    return {
+      scope: { storeScope, contextId, parentSessionId: parentId },
+      delegations: records.map(record => this._delegationView(record)),
+    };
+  }
+
+  subscribe(sessionId, afterSequence, onEvent) {
+    const id = cleanId(sessionId, 'sessionId');
+    this._attachNativeTasks(id);
+    this._trackHistory(id);
+    return subscribeNormalized(this.runner, id, Number(afterSequence || 0), onEvent);
+  }
+
+  _notifySessionChange(id, event) {
+    const state = this.runner.getState(id);
+    if (!state) return;
+    const session = this.runner.getSession(id);
+    if (event?.type === 'claude/user-prompt' && event.text && session && !session.title) session.title = event.text.replace(/\s+/g, ' ').slice(0, 80);
+    const summary = this._summary(state, ACTIVE_STATES.has(state.state));
+    if (session?.title) summary.title = session.title;
+    const signature = JSON.stringify(summary);
+    if (this.sessionSignatures.get(id) === signature) return;
+    this.sessionSignatures.set(id, signature);
+    const change = { type: 'workbench/session-changed', revision: ++this.sessionRevision, contextId: summary.contextId, session: summary };
+    this.sessionChangeLog.push(change);
+    if (this.sessionChangeLog.length > 1000) this.sessionChangeLog.shift();
+    for (const listener of this.sessionChangeListeners) if (!listener.contextId || listener.contextId === summary.contextId) {
+      try { listener.callback(change); } catch { /* disconnected subscriber */ }
+    }
+  }
+
+  _notifySessionDeleted(state) {
+    const summary = this._summary(state, false);
+    this.sessionSignatures.delete(state.sessionId);
+    const change = { type: 'workbench/session-changed', deleted: true, revision: ++this.sessionRevision, contextId: summary.contextId, session: summary };
+    this.sessionChangeLog.push(change);
+    if (this.sessionChangeLog.length > 1000) this.sessionChangeLog.shift();
+    for (const listener of this.sessionChangeListeners) if (!listener.contextId || listener.contextId === summary.contextId) {
+      try { listener.callback(change); } catch { /* disconnected */ }
+    }
+  }
+
+  subscribeSessionChanges(contextId, afterRevision, callback) {
+    const id = contextId === '*' ? null : cleanId(contextId, 'contextId');
+    const sessions = this.runner.listSessions(id ? { projectSlug: id } : {});
+    for (const session of sessions) this._trackHistory(session.sessionId);
+    const after = Math.max(0, Number(afterRevision) || 0);
+    const first = this.sessionChangeLog[0]?.revision || 0;
+    if (after > this.sessionRevision || after && first > after + 1) {
+      callback({ type: 'workbench/resync', revision: this.sessionRevision, contextId: id });
+    } else if (after) {
+      for (const change of this.sessionChangeLog) if (change.revision > after && (!id || change.session.contextId === id)) callback(change);
+    } else callback({ type: 'workbench/sessions-snapshot', revision: this.sessionRevision, contextId: id, sessions: id ? this.listSessions(id, { includeArchived: true }) : sessions.map(s => this._summary(s, ACTIVE_STATES.has(s.state))) });
+    const listener = { contextId: id, callback };
+    this.sessionChangeListeners.add(listener);
+    return () => this.sessionChangeListeners.delete(listener);
+  }
+
+  async listCommands(sessionId) {
+    const id = cleanId(sessionId, 'sessionId');
+    const state = this.runner.getState(id);
+    if (!state) throw Object.assign(new Error('session not found'), { status: 404 });
+    if (typeof this.runner.listSupportedCommands !== 'function') return { commands: [] };
+    const profile = this._profileForSession(id, state);
+    const commands = await this.runner.listSupportedCommands(id, profile);
+    return { commands: Array.isArray(commands) ? commands : [] };
+  }
+
+  readAttachment(sessionId, attachmentId) {
+    const id = cleanId(sessionId, 'sessionId');
+    if (!this.runner.getState(id)) throw Object.assign(new Error('session not found'), { status: 404 });
+    const result = this.attachments && this.attachments.read(id, attachmentId);
+    if (!result) throw Object.assign(new Error('attachment not found'), { status: 404 });
+    return result;
+  }
+
+  async send(sessionId, text, options = {}, attachmentInput = []) {
+    if (this.destroyed) throw Object.assign(new Error('workbench is shut down'), { status: 503 });
+    const id = cleanId(sessionId, 'sessionId');
+    const state = this.runner.getState(id);
+    if (!state) throw Object.assign(new Error('session not found'), { status: 404 });
+    // A direct input can be the first Service contact for an existing or
+    // restored session: the trusted native-task scope binds before any SDK
+    // input can stream, without relying on an earlier snapshot request.
+    this._attachNativeTasks(id);
+    if (ACTIVE_STATES.has(state.state) || this.pendingInputs.has(id)) {
+      throw Object.assign(new Error('session already has an active turn'), { status: 409 });
+    }
+    if (this._activeCount() - (state.backgroundTaskCount > 0 ? 1 : 0) >= this.maxConcurrentRuns) {
+      throw Object.assign(new Error('runtime concurrency limit reached'), { status: 429 });
+    }
+    const value = String(text || '').trim();
+    const attachments = normalizeAttachments(attachmentInput);
+    if (!value && !attachments.length) throw Object.assign(new Error('text or attachments are required'), { status: 400 });
+    if (value.length > 200000) throw Object.assign(new Error('input exceeds 200000 characters'), { status: 413 });
+    const profile = this._profileForSession(id, state);
+    const session = this.runner.getSession(id);
+    this._trackHistory(id);
+    const request = { aborted: false };
+    this.pendingInputs.set(id, request);
+    try {
+    const knowledge = this.knowledge ? await this.knowledge.retrieve(session.projectPath || session.kbPath || state.projectPath, value, options?.knowledgeScope, { sessionId: id }) : null;
+    if (request.aborted) throw Object.assign(new Error('task cancelled before agent launch'), { status: 409 });
+    if (knowledge) this.knowledgeBySession.set(id, knowledge);
+    if (knowledge) this.knowledge.remember?.(id, knowledge);
+    const previousEventCount = session && session.outputBuffer ? session.outputBuffer.length : 0;
+    const captureTurn = this.conversationCapture && this.captureSettings?.read().terminalConversations ? {
+      projectPath: session.projectPath || session.kbPath, source: this._summary(state, false).agentId,
+      sessionId: id, turnId: `turn_${crypto.randomUUID()}`, inputOrigin: session.metadata?.inputOrigin === 'agent-delegation' ? 'agent-delegation' : normalizeInputOrigin(options?.inputOrigin || session.metadata?.inputOrigin),
+    } : null;
+    if (captureTurn) this._capture(captureTurn, 'user_prompt', value);
+    const stored = this.attachments ? this.attachments.saveMany(id, attachments) : attachments;
+    const displayAttachments = stored.map(item => ({
+      id: item.id, name: item.name, mediaType: item.mediaType, size: item.size,
+      width: item.width, height: item.height,
+      url: `${this.apiPrefix}/sessions/${encodeURIComponent(id)}/attachments/${encodeURIComponent(item.id)}`,
+    }));
+    const runtimeAttachments = attachments.map((item, index) => ({ ...displayAttachments[index], data: item.data }));
+    const inputOrigin = session.metadata?.inputOrigin === 'agent-delegation' ? 'agent-delegation' : normalizeInputOrigin(options?.inputOrigin || session.metadata?.inputOrigin);
+    try { await this.runner.sendInput(id, value, profile, { ...(options || {}), parentContext: options[PARENT_CONTEXT] || '', inputOrigin, knowledgeContext: knowledge?.prompt || '', attachments: runtimeAttachments, displayAttachments }); }
+    catch (error) { this._runtimeFailure(id, error); if (captureTurn) this._capture(captureTurn, 'session_end', undefined, 'failed'); throw error; }
+    this._watchTurn(id, previousEventCount, captureTurn);
+    this._audit('input', { sessionId: id, contextId: state.projectSlug, characters: value.length, attachments: attachments.length, attachmentBytes: attachments.reduce((sum, item) => sum + item.size, 0) });
+    return { accepted: true, sessionId: id, state: this.runner.getState(id)?.state, knowledge: knowledge ? { ...knowledge, prompt: undefined } : null };
+    } finally { this.pendingInputs.delete(id); }
+  }
+
+  knowledgeContext(sessionId) {
+    const id = cleanId(sessionId, 'sessionId');
+    if (!this.runner.getState(id)) throw Object.assign(new Error('session not found'), { status: 404 });
+    const value = this.knowledgeBySession.get(id) || this.knowledge?.saved?.(id);
+    return value ? { ...value, prompt: undefined } : { status: 'not-retrieved', references: [] };
+  }
+
+  resolvePermission(sessionId, requestId, decision) {
+    const id = cleanId(sessionId, 'sessionId');
+    const rid = cleanId(requestId, 'requestId');
+    this._trackHistory(id);
+    const result = this.runner.resolvePermission(id, rid, decision || {});
+    this._audit('permission-resolve', { sessionId: id, requestId: rid, allow: decision && decision.allow === true });
+    return result;
+  }
+
+  abort(sessionId, reason = 'user-abort') {
+    const id = cleanId(sessionId, 'sessionId');
+    if (!this.runner.getState(id)) throw Object.assign(new Error('session not found'), { status: 404 });
+    this._trackHistory(id);
+    if (this.pendingInputs.has(id)) this.pendingInputs.get(id).aborted = true;
+    this.runner.abort(id, reason);
+    // A net for runners that emit no aborted event: normally the monitor
+    // already released itself on that event, having recorded session_end once.
+    this._clearTurnMonitor(id);
+    this._audit('abort', { sessionId: id, reason });
+    return { accepted: true, sessionId: id };
+  }
+
+  setPermissionMode(sessionId, mode) {
+    const id = cleanId(sessionId, 'sessionId');
+    if (!PERMISSION_MODES.includes(mode)) throw Object.assign(new Error('invalid permission mode'), { status: 400 });
+    this._trackHistory(id);
+    const session = this.runner.getSession(id);
+    if (!session) throw Object.assign(new Error('session not found'), { status: 404 });
+    session.permissionMode = mode;
+    this._audit('permission-mode', { sessionId: id, mode });
+    return { sessionId: id, permissionMode: mode };
+  }
+
+  // Rebind an existing session to another AI profile/model (or back to the
+  // agent's own login with aiProfileId null). The session and its history
+  // survive; the next turn simply runs under the new selection.
+  updateSessionSelection(sessionId, aiProfileId, model) {
+    const id = cleanId(sessionId, 'sessionId');
+    const state = this.runner.getState(id);
+    if (!state) throw Object.assign(new Error('session not found'), { status: 404 });
+    if (ACTIVE_STATES.has(state.state) || state.backgroundTaskCount > 0) {
+      throw Object.assign(new Error('session already has an active turn'), { status: 409 });
+    }
+    this._trackHistory(id);
+    // _runtimeProfile resolves and validates the profile (404 unknown id,
+    // 400 disabled/missing credential/invalid model) exactly like startSession.
+    const profileId = aiProfileId ? cleanId(aiProfileId, 'aiProfileId') : null;
+    const profile = this._runtimeProfile(profileId, model === undefined ? undefined : model);
+    if (typeof this.runner.updateSelection === 'function') {
+      this.runner.updateSelection(id, profile, profile.mainModel || null);
+    } else {
+      const session = this.runner.getSession(id);
+      if (!session) throw Object.assign(new Error('session not found'), { status: 404 });
+      session.aiProfileId = profileId;
+      session.selectedModel = profile.mainModel || null;
+    }
+    this._audit('selection-update', { sessionId: id, contextId: state.projectSlug, profileId, model: profile.mainModel || null });
+    return this._summary(this.runner.getState(id), true);
+  }
+
+  async testProfile(profileId) {
+    const id = cleanId(profileId, 'profileId');
+    const profile = this.profiles.runtimeProfile(id);
+    return this._runProfileTest(profile, id);
+  }
+
+  async testProfileDraft(input = {}) {
+    if (!input || typeof input !== 'object' || Array.isArray(input) || !input.profile) {
+      throw Object.assign(new Error('profile is required'), { status: 400 });
+    }
+    const profile = this.profiles.runtimeDraft(input.profile, input.credential);
+    return this._runProfileTest(profile, profile.id);
+  }
+
+  // Detect the models a provider draft can actually use (endpoint model list
+  // joined with models.dev capability metadata). Uses the same draft+credential
+  // resolution as testProfileDraft, so a blank credential falls back to the
+  // stored secret of an already-saved profile.
+  async detectProfileModels(input = {}) {
+    if (!input || typeof input !== 'object' || Array.isArray(input) || !input.profile) {
+      throw Object.assign(new Error('profile is required'), { status: 400 });
+    }
+    if (!this.modelDetection) {
+      throw Object.assign(new Error('model detection is unavailable'), { status: 501 });
+    }
+    // Detection precedes model configuration, so an empty model list is fine here.
+    const profile = this.profiles.runtimeDraft(input.profile, input.credential, { requireModel: false });
+    const result = await this.modelDetection.detectModels({ profile });
+    this._audit('profile-detect-models', { profileId: profile.id, count: result.models.length, sources: Object.keys(result.sources) });
+    return result;
+  }
+
+  async _runProfileTest(profile, profileId) {
+    const id = cleanId(profileId, 'profileId');
+    const contextId = `profile-test-${Date.now().toString(36)}`;
+    const startedAt = Date.now();
+    const started = this.runner.startChatSession({
+      slug: contextId, projectPath: this.testWorkspace, kbPath: this.testWorkspace,
+      aiProfile: profile, permissionMode: 'default',
+    });
+    let firstEventMs = null;
+    let preview = '';
+    let unsubscribe = null;
+    try {
+      const outcome = await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => reject(new Error('Claude Code profile test timed out')), Math.min(profile.timeoutMs, 300000));
+        unsubscribe = this.runner.subscribe(started.sessionId, event => {
+          if (firstEventMs == null && event.type !== 'claude/session-ready') firstEventMs = Date.now() - startedAt;
+          if (event.type === 'claude/result') {
+            clearTimeout(timeout);
+            if (event.isError) {
+              reject(new Error(String(event.result || event.message || event.error || 'Claude Code returned an error result')));
+            } else {
+              preview = String(event.result || event.text || '').slice(0, 500);
+              resolve(event);
+            }
+          } else if (event.type === 'claude/error') {
+            clearTimeout(timeout); reject(new Error(String(event.message || event.error || 'Claude Code runtime error')));
+          } else if (event.type === 'claude/aborted') {
+            clearTimeout(timeout); reject(new Error('Claude Code profile test was aborted'));
+          }
+        });
+        this.runner.sendInput(started.sessionId, 'Reply with exactly: WORKBENCH_RUNTIME_OK', profile, { permissionMode: 'default' }).catch(error => {
+          clearTimeout(timeout); reject(error);
+        });
+      });
+      const state = this.runner.getState(started.sessionId);
+      return {
+        ok: true, runtime: 'claude-code', runtimeVerified: true, profileId: id,
+        model: outcome.model || state && state.model || profile.models.default,
+        firstEventMs: firstEventMs == null ? Date.now() - startedAt : firstEventMs,
+        durationMs: Date.now() - startedAt, resultPreview: redact(preview),
+      };
+    } finally {
+      try { unsubscribe && unsubscribe(); } catch {}
+      try { this.runner.abort(started.sessionId); } catch {}
+      try { this.runner.deleteSession(started.sessionId); } catch {}
+    }
+  }
+
+  destroy() {
+    if (this.destroyPromise) return this.destroyPromise;
+    this.destroyed = true;
+    for (const request of this.pendingInputs.values()) request.aborted = true;
+    this.sessionChangeListeners.clear();
+    this.agentDiscovery?.close?.();
+    this.conversationCapture?.close();
+    if (this.archiveSweeper) { clearInterval(this.archiveSweeper); this.archiveSweeper = null; }
+    for (const sessionId of this.turnMonitors.keys()) this._clearTurnMonitor(sessionId);
+    for (const session of this.runner.listSessions({})) {
+      if (ACTIVE_STATES.has(session.state)) try { this.runner.abort(session.sessionId); } catch {}
+    }
+    this.destroyPromise = Promise.resolve(this.runner.destroy?.()).finally(() => {
+      this.sessionChangeListeners.clear();
+      for (const { history, unsubscribe } of this.histories.values()) { unsubscribe(); history.close(); }
+      this.histories.clear();
+      // Closing the Service unbinds only its OWN committer bindings: the
+      // runner marks those runtimes non-sticky unavailable (rebindable by a
+      // successor), while bindings owned by another instance are refused
+      // there and stay untouched.
+      for (const sessionId of [...this.nativeCommitters.keys()]) this._detachNativeTasks(sessionId);
+    });
+    return this.destroyPromise;
+  }
+
+  _runtimeProfile(profileId, selectedModel) {
+    const profile = profileId ? this.profiles.runtimeProfile(profileId)
+      : { id: null, models: { default: '' }, timeoutMs: 300000 };
+    const model = selectedModel == null ? profile.models.default : String(selectedModel).trim();
+    if (model.length > 128 || /[\r\n\x00]/.test(model)) throw Object.assign(new Error('model is invalid'), { status: 400 });
+    return { ...profile, models: { ...profile.models, default: model }, mainModel: model };
+  }
+
+  _profileForSession(id, state) {
+    const session = this.runner.getSession(id);
+    const model = session && Object.prototype.hasOwnProperty.call(session, 'selectedModel')
+      ? session.selectedModel : state.selectedModel || state.model;
+    return this._runtimeProfile(state.aiProfileId, model);
+  }
+
+  _summary(session, active) {
+    const agentId = session.agentId
+      || (typeof this.runner.agentOf === 'function' ? this.runner.agentOf(session.sessionId) : null)
+      || this.sessionAgents.get(session.sessionId)
+      || 'claude-code';
+    return {
+      sessionId: session.sessionId,
+      contextId: session.projectSlug,
+      projectId: session.projectSlug,
+      agentId,
+      title: session.title || `Session ${String(session.sessionId).slice(-8)}`,
+      active: Boolean(active), state: session.state, model: session.model || null,
+      aiProfileId: session.aiProfileId || null, permissionMode: session.permissionMode || 'default',
+      selectedModel: session.selectedModel || this.runner.getSession(session.sessionId)?.selectedModel || null,
+      authSource: session.aiProfileId ? 'profile-injected' : 'agent-owned',
+      providerName: session.aiProfileId ? this.profiles.get(session.aiProfileId)?.name || 'Unavailable provider' : AGENTS[agentId].label,
+      archived: Boolean(this.sessionArchive && this.sessionArchive.isArchived(session.sessionId)),
+      turns: Number(session.turns || 0), startedAt: session.startedAt,
+      tasks: Array.isArray(session.tasks) ? session.tasks : [],
+      backgroundTaskCount: Number(session.backgroundTaskCount || 0),
+      // W-1: prefer the driver's live activity marker (refreshed at turn
+      // end); endedAt/startAt only predate it for legacy records.
+      updatedAt: session.updatedAt || session.endedAt || session.startedAt, connectionState: 'connected',
+    };
+  }
+
+  // Approximate context occupancy for the capacity bubble. Token totals come
+  // from the driver; the per-category split is a characters/4 estimate over
+  // the session event log and is explicitly flagged as such.
+  contextUsage(sessionId) {
+    const id = cleanId(sessionId, 'sessionId');
+    const state = this.runner.getState(id);
+    if (!state) throw Object.assign(new Error('session not found'), { status: 404 });
+    const usage = this.runner.getSessionTokenUsage(id) || {};
+    const contextWindow = this._contextWindowFor(state.model, this._sessionProfileContextWindow(id, state));
+    const breakdown = this._estimateBreakdown(id);
+    const used = Number(usage.used || usage.inputTokens || 0) || 0;
+    return {
+      sessionId: id,
+      agentId: this._summary(state, false).agentId,
+      model: state.model || null,
+      contextWindow,
+      used,
+      percent: contextWindow ? Math.round((used / contextWindow) * 1000) / 10 : null,
+      inputTokens: Number(usage.inputTokens || 0) || 0,
+      outputTokens: Number(usage.outputTokens || 0) || 0,
+      breakdown,
+      estimated: true,
+    };
+  }
+
+  _sessionProfileContextWindow(sessionId, state) {
+    try {
+      const profile = this._profileForSession(sessionId, state);
+      return profile ? Number(profile.contextWindow) || 0 : 0;
+    } catch { return 0; }
+  }
+
+  _contextWindowFor(model, profileContextWindow) {
+    if (!model && !profileContextWindow) return 200000;
+    if (this.modelContextWindows && typeof this.modelContextWindows.resolveContextWindow === 'function') {
+      try {
+        // The profile store defaults contextWindow to 200000; that default must
+        // not shadow the recognition table (e.g. MiniMax → 1M). Only an explicit
+        // non-default override wins over auto-detection.
+        const explicit = Number(profileContextWindow) > 0 && Number(profileContextWindow) !== 200000 ? Number(profileContextWindow) : undefined;
+        const resolved = this.modelContextWindows.resolveContextWindow({ profileContextWindow: explicit, model, fallback: 200000 });
+        if (resolved) return resolved;
+      } catch { /* fall through to the default */ }
+    }
+    return Number(profileContextWindow) > 0 ? Number(profileContextWindow) : 200000;
+  }
+
+  _estimateBreakdown(sessionId) {
+    const session = this.runner.getSession(sessionId);
+    const buckets = { messages: 0, tools: 0, other: 0 };
+    if (!session || !Array.isArray(session.outputBuffer)) return buckets;
+    for (const event of session.outputBuffer) {
+      const text = String(event.text || event.result || event.output || '');
+      const tokens = Math.ceil(text.length / 4);
+      if (event.type === 'claude/user-prompt' || event.type === 'claude/text-delta') buckets.messages += tokens;
+      else if (event.type === 'claude/tool-use' || event.type === 'claude/tool-result') buckets.tools += tokens;
+      else buckets.other += tokens;
+    }
+    return buckets;
+  }
+
+  _activeCount(sessions = null) { const list = Array.isArray(sessions) ? sessions : this.runner.listSessions({}); const active = new Set(list.filter(item => ACTIVE_STATES.has(item.state) || item.backgroundTaskCount > 0).map(item => item.sessionId)); return active.size + [...this.pendingInputs.keys()].filter(id => !active.has(id)).length; }
+  _capture(turn, eventType, content, outcome) {
+    try { this.conversationCapture.enqueue(turn, eventType, content, outcome); }
+    catch { this._audit('capture-gap', { sessionId: turn.sessionId, code: 'CAPTURE_QUEUE_UNAVAILABLE' }); }
+  }
+  _watchTurn(sessionId, previousEventCount, captureTurn) {
+    this._clearTurnMonitor(sessionId);
+    let seen = 0;
+    let unsubscribe = null;
+    let completed = false;
+    let responseText = '';
+    let released = false;
+    // The monitor owns capture and failure diagnostics on its own; there is no
+    // whole-task timer anymore, so keeping it must not depend on one.
+    const release = () => {
+      if (released) return;
+      released = true;
+      if (unsubscribe) { try { unsubscribe(); } catch {} }
+      this.turnMonitors.delete(sessionId);
+    };
+    unsubscribe = this.runner.subscribe(sessionId, event => {
+      if (released) return;
+      seen += 1;
+      if (seen <= previousEventCount) return;
+      if (event?.parentToolUseId) return;
+      if (event?.type === 'claude/text-delta') responseText += String(event.text || '');
+      if (['claude/result', 'claude/turn-end', 'claude/error', 'claude/aborted'].includes(event && event.type)) {
+        if (event.type === 'claude/error' || event.type === 'claude/result' && event.isError) this._runtimeFailure(sessionId, new Error(String(event.message || event.error || event.result || 'Agent 运行失败。')));
+        if (captureTurn && !completed) {
+          completed = true;
+          if (event.type === 'claude/result' && !event.isError && typeof event.result === 'string' && event.result) this._capture(captureTurn, 'assistant_response', event.result);
+          if (event.type === 'claude/turn-end' && !event.exitCode && responseText) this._capture(captureTurn, 'assistant_response', responseText);
+          this._capture(captureTurn, 'session_end', undefined, event.type === 'claude/result' && !event.isError || event.type === 'claude/turn-end' && !event.exitCode ? 'completed' : 'failed');
+        }
+        release();
+      }
+    });
+    // The synchronous replay may deliver the terminal event while
+    // `unsubscribe` is still unassigned, so release() could not detach yet.
+    if (released) { try { unsubscribe(); } catch {} }
+    else this.turnMonitors.set(sessionId, unsubscribe);
+  }
+  _clearTurnMonitor(sessionId) {
+    const unsubscribe = this.turnMonitors.get(sessionId);
+    if (unsubscribe) try { unsubscribe(); } catch {}
+    this.turnMonitors.delete(sessionId);
+  }
+  _runtimeFailure(sessionId, error) {
+    const state = this.runner.getState(sessionId);
+    this.diagnostics?.error('agent.runtime.failed', 'Agent 会话运行失败。', { projectId: /^project-[A-Za-z0-9._-]+$/.test(state?.projectSlug || '') ? state.projectSlug : undefined, runId: sessionId, phase: 'runtime', error, context: { agent: this.runner.agentOf?.(sessionId) || this.sessionAgents.get(sessionId) || state?.agentId || 'claude-code', sessionId } });
+  }
+  _audit(action, detail) {
+    if (!this.auditFile) return;
+    fs.mkdirSync(path.dirname(this.auditFile), { recursive: true });
+    fs.appendFileSync(this.auditFile, `${JSON.stringify({ at: new Date().toISOString(), action, ...detail })}\n`, 'utf8');
+  }
+}
+
+function redact(value) {
+  return String(value || '').replace(/(?:sk|key|token)-[a-zA-Z0-9._-]{8,}/gi, '[REDACTED]');
+}
+
+function normalizeInputOrigin(value) { return ['human', 'agent-delegation'].includes(value) ? value : 'unknown'; }
+
+module.exports = { WorkbenchService, ACTIVE_STATES, redact };