@sanqianx/claude-ai-workbench 0.13.2 → 0.13.4

package/src/backend/lib/native-task-registry.js

@@ -1,325 +1,325 @@
-'use strict';
-// Native task registry - a pure in-memory index of native dispatch ownership
-// and real task status facts. No fs, no network, no SDK queries, no stop, no
-// event sequencing: runner/Service/persistent-history integration is a later
-// task and unit tests here are not a product gate.
-const { createTaskScope, createNativeTaskRef, nativeTaskKey, sameTaskScope } = require('./task-identity');
-
-const TASK_STATUSES = new Set(['pending', 'running', 'completed', 'failed', 'stopped']);
-const TERMINAL_STATUSES = new Set(['completed', 'failed', 'stopped']);
-const AGENT_TOOL_NAMES = new Set(['Agent', 'Task']);
-const LAUNCHER_TOOL_NAMES = new Set(['Agent', 'Task', 'Bash']);
-const TASK_KIND_BY_TYPE = new Map([['local_agent', 'agent'], ['local_bash', 'local_bash']]);
-const TASK_EVENT_SUBTYPES = new Set(['task_started', 'task_progress', 'task_updated', 'task_notification']);
-const MAX_DIAGNOSTICS = 200;
-
-function id(value) { return typeof value === 'string' && value.trim() !== '' ? value : null; }
-function ownerRunIdOf(sdkSessionId, parentNativeAgentId, launcherToolUseId) {
-  return JSON.stringify(['sdk-launch', 1, sdkSessionId, parentNativeAgentId, launcherToolUseId]);
-}
-function tupleKey() { return JSON.stringify([...arguments]); }
-
-class NativeTaskRegistry {
-  constructor(scopeInput) {
-    const scope = createTaskScope(scopeInput);
-    if (!scope) throw new Error('NativeTaskRegistry requires a valid fixed TaskScope');
-    this._scope = Object.freeze(scope);
-    this._tasks = new Map();
-    this._byToolUse = new Map();
-    this._byRefKey = new Map();
-    this._rootLaunchers = new Map();
-    this._nestedLaunchers = new Map();
-    this._receipts = new Map();
-    this._agents = new Map();
-    this._diagnostics = [];
-    this._diagSeen = new Set();
-  }
-
-  get scope() { return { storeScope: this._scope.storeScope, contextId: this._scope.contextId, parentSessionId: this._scope.parentSessionId }; }
-  diagnostics() { return this._diagnostics.map(d => ({ ...d })); }
-
-  // Raw SDK stream messages. Assistant messages only provide launcher facts
-  // (real tool_use blocks); model prose never creates tasks or owners.
-  observeSdkMessage(message) {
-    if (!message || typeof message !== 'object') return null;
-    if (message.type === 'assistant') return this._observeAssistant(message);
-    if (message.type === 'system') return this._observeTaskSystem(message);
-    return null;
-  }
-
-  _observeAssistant(message) {
-    const sdkSessionId = id(message.session_id);
-    if (!sdkSessionId) { this._diag('assistant-missing-session-id', {}); return null; }
-    if (id(message.parent_tool_use_id)) return null;
-    const raw = message.message && typeof message.message === 'object' ? message.message : message;
-    const blocks = Array.isArray(raw.content) ? raw.content : [];
-    let recorded = 0;
-    for (const block of blocks) {
-      if (!block || typeof block !== 'object' || block.type !== 'tool_use') continue;
-      const toolUseId = id(block.id);
-      if (!toolUseId) continue;
-      if (LAUNCHER_TOOL_NAMES.has(block.name)) {
-        const key = tupleKey(sdkSessionId, toolUseId);
-        if (!this._rootLaunchers.has(key)) { this._rootLaunchers.set(key, { toolName: block.name, sdkSessionId, toolUseId }); recorded++; }
-      }
-    }
-    if (recorded > 0) this._retryUnbound();
-    return recorded;
-  }
-
-  // Normalized claude/native-trace observations (W1-08 shape).
-  observeTrace(trace) {
-    if (!trace || typeof trace !== 'object') return null;
-    if (trace.type !== 'claude/native-trace' || trace.source !== 'sdk-hook') return null;
-    const hookEvent = id(trace.hookEvent);
-    const sdkSessionId = id(trace.sdkSessionId);
-    const toolName = id(trace.toolName);
-    if (!hookEvent || !sdkSessionId) { this._diag('trace-missing-identity', { hookEvent: hookEvent === null ? null : hookEvent.slice(0, 40) }); return null; }
-    if (id(trace.parentSessionId) !== this._scope.parentSessionId) {
-      this._diag('trace-parent-session-mismatch', { hookEvent, sdkSessionId, parentSessionId: id(trace.parentSessionId) });
-      return null;
-    }
-    if (hookEvent === 'SubagentStart' || hookEvent === 'SubagentStop') { this._diag(hookEvent === 'SubagentStop' ? 'subagent-stop-not-terminal' : 'subagent-start-not-launch', { sdkSessionId }); return null; }
-    const rawId = id(trace.rawToolUseId);
-    const callbackId = id(trace.callbackToolUseId);
-    const toolUseId = rawId || callbackId;
-    if (!toolUseId) { this._diag('trace-missing-tool-use-id', { hookEvent, sdkSessionId }); return null; }
-    if (rawId && callbackId && rawId !== callbackId) { this._diag('receipt-id-mismatch', { hookEvent, sdkSessionId, rawToolUseId: rawId, callbackToolUseId: callbackId }); return null; }
-    const dispatcher = id(trace.nativeAgentId);
-    if (hookEvent === 'PreToolUse') {
-      if (!dispatcher) { this._diag('pre-hook-missing-agent-context', { sdkSessionId, toolUseId }); return null; }
-      if (LAUNCHER_TOOL_NAMES.has(toolName)) {
-        const key = tupleKey(sdkSessionId, dispatcher, toolUseId);
-        if (!this._nestedLaunchers.has(key)) this._nestedLaunchers.set(key, { toolName, dispatcher, sdkSessionId, toolUseId });
-        this._retryUnbound();
-      }
-      return toolUseId;
-    }
-    if (hookEvent === 'PostToolUseFailure') { this._diag('receipt-failure-kept', { sdkSessionId, toolUseId }); return null; }
-    if (hookEvent !== 'PostToolUse') return null;
-    const response = trace.toolResponse && typeof trace.toolResponse === 'object' ? trace.toolResponse : null;
-    const agentId = response ? id(response.agentId) : null;
-    if (!AGENT_TOOL_NAMES.has(toolName)) {
-      if (agentId) this._diag('non-agent-receipt-ignored', { sdkSessionId, toolUseId, toolName });
-      return null;
-    }
-    if (!agentId) { this._diag('receipt-missing-agent-id', { sdkSessionId, toolUseId, toolName }); return null; }
-    this._recordReceipt(sdkSessionId, toolUseId, { agentId, dispatcher, toolName, sdkSessionId, toolUseId });
-    this._retryUnbound();
-    return toolUseId;
-  }
-
-  _observeTaskSystem(message) {
-    const subtype = message.subtype;
-    if (!TASK_EVENT_SUBTYPES.has(subtype)) return null;
-    const taskId = id(message.task_id);
-    const sdkSessionId = id(message.session_id);
-    if (!taskId || !sdkSessionId) { this._diag('task-event-missing-identity', { subtype, hasTaskId: taskId !== null, hasSessionId: sdkSessionId !== null }); return null; }
-    const task = this._ensureTask(sdkSessionId, taskId);
-    task.observedEvents++;
-    if (subtype === 'task_started') {
-      task.startedSeen = true;
-      const taskType = id(message.task_type);
-      if (task.taskType === null) task.taskType = taskType;
-      else if (taskType !== null && taskType !== task.taskType) {
-        task.typeConflict = true;
-        this._diag('task-type-conflict', { sdkSessionId, taskId, existing: task.taskType, incoming: taskType });
-      }
-    }
-    const toolUseId = id(message.tool_use_id);
-    if (toolUseId) {
-      if (task.toolUseId === null) {
-        task.toolUseId = toolUseId;
-        const key = tupleKey(sdkSessionId, toolUseId);
-        if (!this._byToolUse.has(key)) this._byToolUse.set(key, new Set());
-        this._byToolUse.get(key).add(task.taskKey);
-      } else if (task.toolUseId !== toolUseId) {
-        this._diag('task-tooluse-conflict', { sdkSessionId, taskId, existing: task.toolUseId, incoming: toolUseId });
-      }
-    }
-    this._applyStatus(task, message);
-    this._tryBind(task);
-    return task.taskKey;
-  }
-
-  _applyStatus(task, message) {
-    let raw = null;
-    if (message.subtype === 'task_notification') {
-      raw = id(message.status);
-      if (raw === null) { this._diag('notification-without-status', { sdkSessionId: task.sdkSessionId, taskId: task.taskId }); return; }
-    } else {
-      const patch = message.patch && typeof message.patch === 'object' ? message.patch : {};
-      raw = id(message.status) || id(patch.status) || (message.subtype === 'task_started' ? 'running' : null);
-    }
-    if (raw === null) {
-      if (message.subtype === 'task_progress' && task.status === null) { task.status = 'running'; task.statusSource = 'task_progress'; }
-      return;
-    }
-    if (!TASK_STATUSES.has(raw)) { this._diag('unknown-task-status', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, subtype: message.subtype, raw: String(raw).slice(0, 40) }); return; }
-    const prior = task.status;
-    if (prior === null) { task.status = raw; task.statusSource = message.subtype; return; }
-    if (TERMINAL_STATUSES.has(prior)) {
-      if (!TERMINAL_STATUSES.has(raw)) { this._diag('terminal-no-revival', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, subtype: message.subtype }); return; }
-      if (raw !== prior) { this._diag('terminal-conflict', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, prior, incoming: raw }); return; }
-      return;
-    }
-    task.status = raw; task.statusSource = message.subtype;
-  }
-
-  _ensureTask(sdkSessionId, taskId) {
-    const taskKey = JSON.stringify([sdkSessionId, taskId]);
-    let task = this._tasks.get(taskKey);
-    if (!task) {
-      task = { taskKey, sdkSessionId, taskId, toolUseId: null, status: null, statusSource: null, taskKind: null, taskType: null, startedSeen: false, typeConflict: false, association: 'unassigned', owner: null, mainToolUseId: null, observedEvents: 0 };
-      this._tasks.set(taskKey, task);
-    }
-    return task;
-  }
-
-  _recordReceipt(sdkSessionId, toolUseId, receipt) {
-    const key = tupleKey(sdkSessionId, toolUseId);
-    const claimants = this._byToolUse.get(key);
-    if (claimants) {
-      let matchesBound = false;
-      let boundCount = 0;
-      for (const taskKey of claimants) {
-        const t = this._tasks.get(taskKey);
-        if (t && t.owner) {
-          boundCount++;
-          if (t.owner.receiptAgentId === receipt.agentId && t.owner.parentNativeAgentId === receipt.dispatcher) matchesBound = true;
-        }
-      }
-      if (boundCount > 0 && !matchesBound) this._diag('owner-conflict-kept-first', { sdkSessionId, toolUseId, agentId: receipt.agentId, dispatcher: receipt.dispatcher });
-    }
-    const list = this._receipts.get(key) || [];
-    if (!list.some(r => r.agentId === receipt.agentId && r.dispatcher === receipt.dispatcher)) list.push(receipt);
-    this._receipts.set(key, list);
-  }
-
-  _tryBind(task) {
-    if (!task || task.owner !== null || task.toolUseId === null) return false;
-    if (!task.startedSeen) return false;
-    if (task.typeConflict) return false;
-    const taskKind = TASK_KIND_BY_TYPE.get(task.taskType) || null;
-    if (!taskKind) { this._diag('unknown-task-type', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, taskType: task.taskType }); return false; }
-    const key = tupleKey(task.sdkSessionId, task.toolUseId);
-    const root = this._rootLaunchers.get(key);
-    const matches = (this._receipts.get(key) || []).filter(r => r.agentId === task.taskId);
-    if (matches.length > 1) { this._diag('ambiguous-receipt', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, toolUseId: task.toolUseId }); return false; }
-    if (root && AGENT_TOOL_NAMES.has(root.toolName)) {
-      if (taskKind !== 'agent') { this._diag('task-type-conflict', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, toolUseId: task.toolUseId, launcherTool: root.toolName, taskType: task.taskType }); return false; }
-      if (matches.length === 1 && matches[0].dispatcher === null) return this._bind(task, { launcherKind: 'root', parentNativeAgentId: null, taskKind: 'agent', receipt: matches[0] });
-      return false;
-    }
-    if (matches.length === 1 && matches[0].dispatcher !== null) {
-      const receipt = matches[0];
-      const parentTaskKey = this._agents.get(tupleKey(task.sdkSessionId, receipt.dispatcher));
-      if (!parentTaskKey) { this._diag('unknown-dispatcher', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, toolUseId: task.toolUseId, dispatcher: receipt.dispatcher }); return false; }
-      const nested = this._nestedLaunchers.get(tupleKey(task.sdkSessionId, receipt.dispatcher, task.toolUseId));
-      if (!nested) { this._diag('receipt-without-launcher', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, toolUseId: task.toolUseId, dispatcher: receipt.dispatcher }); return false; }
-      const nestedKind = AGENT_TOOL_NAMES.has(nested.toolName) ? 'agent' : (nested.toolName === 'Bash' ? 'local_bash' : null);
-      if (taskKind !== nestedKind || nestedKind === null) { this._diag('task-type-conflict', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, toolUseId: task.toolUseId, launcherTool: nested.toolName, taskType: task.taskType }); return false; }
-      return this._bind(task, { launcherKind: 'nested', parentNativeAgentId: receipt.dispatcher, taskKind: nestedKind, receipt, parentTaskKey });
-    }
-    if (matches.length === 0) {
-      const candidates = [];
-      for (const entry of this._nestedLaunchers.values()) {
-        if (entry.sdkSessionId === task.sdkSessionId && entry.toolUseId === task.toolUseId && !candidates.some(c => c.dispatcher === entry.dispatcher)) candidates.push(entry);
-      }
-      if (candidates.length > 1) { this._diag('ambiguous-dispatcher', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, toolUseId: task.toolUseId }); return false; }
-      if (candidates.length === 1) {
-        const candidate = candidates[0];
-        const candidateKind = AGENT_TOOL_NAMES.has(candidate.toolName) ? 'agent' : (candidate.toolName === 'Bash' ? 'local_bash' : null);
-        if (taskKind !== candidateKind || candidateKind === null) { this._diag('task-type-conflict', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, toolUseId: task.toolUseId, launcherTool: candidate.toolName, taskType: task.taskType }); return false; }
-        if (candidateKind === 'agent') return false;
-        const parentTaskKey = this._agents.get(tupleKey(task.sdkSessionId, candidate.dispatcher));
-        if (!parentTaskKey) { this._diag('unknown-dispatcher', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, toolUseId: task.toolUseId, dispatcher: candidate.dispatcher }); return false; }
-        return this._bind(task, { launcherKind: 'nested', parentNativeAgentId: candidate.dispatcher, taskKind: 'local_bash', receipt: null, parentTaskKey });
-      }
-    }
-    if (root && root.toolName === 'Bash') {
-      if (taskKind !== 'local_bash') { this._diag('task-type-conflict', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, toolUseId: task.toolUseId, launcherTool: root.toolName, taskType: task.taskType }); return false; }
-      if (matches.length === 0) { task.association = 'main-command'; task.mainToolUseId = task.toolUseId; }
-      return false;
-    }
-    return false;
-  }
-  _bind(task, opts) {
-    const ownerRunId = ownerRunIdOf(task.sdkSessionId, opts.parentNativeAgentId, task.toolUseId);
-    const taskRef = createNativeTaskRef({ kind: 'native-task', storeScope: this._scope.storeScope, contextId: this._scope.contextId, parentSessionId: this._scope.parentSessionId, ownerRunId, taskId: task.taskId });
-    if (!taskRef) { this._diag('taskref-invalid', { sdkSessionId: task.sdkSessionId, taskId: task.taskId }); return false; }
-    const refKey = nativeTaskKey(taskRef);
-    if (this._byRefKey.has(refKey)) { this._diag('owner-ref-collision', { refKey, taskId: task.taskId }); return false; }
-    const parent = opts.parentTaskKey ? this._tasks.get(opts.parentTaskKey) : null;
-    const owner = { taskRef, ownerRunId, ownerBasis: 'sdk-tool-launch', launcherKind: opts.launcherKind, parentNativeAgentId: opts.parentNativeAgentId, launcherToolUseId: task.toolUseId, receiptAgentId: opts.receipt ? opts.receipt.agentId : null };
-    if (parent) owner.resolvedParent = { taskId: parent.taskId, sdkSessionId: parent.sdkSessionId, agentId: opts.receipt ? opts.receipt.dispatcher : opts.parentNativeAgentId, status: parent.status };
-    task.owner = owner;
-    task.taskKind = opts.taskKind;
-    task.association = 'bound';
-    this._byRefKey.set(refKey, task.taskKey);
-    if (opts.taskKind === 'agent' && opts.receipt) this._agents.set(tupleKey(task.sdkSessionId, opts.receipt.agentId), task.taskKey);
-    this._retryUnbound(task.taskKey);
-    return true;
-  }
-
-  _retryUnbound(exceptTaskKey) {
-    for (const task of this._tasks.values()) {
-      if (task.owner !== null || task.toolUseId === null) continue;
-      if (exceptTaskKey && task.taskKey === exceptTaskKey) continue;
-      this._tryBind(task);
-    }
-  }
-
-  list() { return [...this._tasks.values()].map(task => this._snapshot(task)); }
-
-  // Narrow trusted read-only binding query for the transcript collector:
-  // only bound agent tasks whose identity the registry itself established
-  // (SDK session id from the stream, receipt agent id from a real hook
-  // receipt). Fresh copies only; no status is interpreted here.
-  agentBindings() {
-    const out = [];
-    for (const task of this._tasks.values()) {
-      if (task.association !== 'bound' || task.taskKind !== 'agent') continue;
-      if (!task.owner || !task.owner.receiptAgentId || task.owner.receiptAgentId !== task.taskId) continue;
-      if (typeof task.sdkSessionId !== 'string' || !task.sdkSessionId || typeof task.taskId !== 'string' || !task.taskId) continue;
-      out.push({
-        sdkSessionId: task.sdkSessionId,
-        taskId: task.taskId,
-        taskRef: task.owner.taskRef ? JSON.parse(JSON.stringify(task.owner.taskRef)) : null,
-        ownerRunId: task.owner.ownerRunId || null,
-        status: task.status === undefined ? null : task.status,
-      });
-    }
-    return out;
-  }
-
-  getTask(ref) {
-    const taskRef = createNativeTaskRef(ref);
-    if (!taskRef) return null;
-    if (!sameTaskScope(taskRef, this._scope)) return null;
-    const taskKey = this._byRefKey.get(nativeTaskKey(taskRef));
-    if (!taskKey) return null;
-    const task = this._tasks.get(taskKey);
-    return task ? this._snapshot(task) : null;
-  }
-
-  _snapshot(task) {
-    return JSON.parse(JSON.stringify({
-      sdkSessionId: task.sdkSessionId, taskId: task.taskId, toolUseId: task.toolUseId,
-      status: task.status, statusSource: task.statusSource, taskKind: task.taskKind, taskType: task.taskType, startedSeen: task.startedSeen, typeConflict: task.typeConflict === true, association: task.association,
-      taskRef: task.owner ? task.owner.taskRef : null, ownerRunId: task.owner ? task.owner.ownerRunId : null,
-      owner: task.owner ? { ownerBasis: task.owner.ownerBasis, launcherKind: task.owner.launcherKind, parentNativeAgentId: task.owner.parentNativeAgentId, launcherToolUseId: task.owner.launcherToolUseId, receiptAgentId: task.owner.receiptAgentId, resolvedParent: task.owner.resolvedParent || null } : null,
-      mainToolUseId: task.mainToolUseId, observedEvents: task.observedEvents,
-    }));
-  }
-
-  _diag(code, ids) {
-    const signature = code + '|' + JSON.stringify(ids || {});
-    if (this._diagSeen.has(signature)) return;
-    if (this._diagnostics.length >= MAX_DIAGNOSTICS) return;
-    this._diagSeen.add(signature);
-    this._diagnostics.push(Object.assign({ code }, ids || {}));
-  }
-}
-
-module.exports = { NativeTaskRegistry };
+'use strict';
+// Native task registry - a pure in-memory index of native dispatch ownership
+// and real task status facts. No fs, no network, no SDK queries, no stop, no
+// event sequencing: runner/Service/persistent-history integration is a later
+// task and unit tests here are not a product gate.
+const { createTaskScope, createNativeTaskRef, nativeTaskKey, sameTaskScope } = require('./task-identity');
+
+const TASK_STATUSES = new Set(['pending', 'running', 'completed', 'failed', 'stopped']);
+const TERMINAL_STATUSES = new Set(['completed', 'failed', 'stopped']);
+const AGENT_TOOL_NAMES = new Set(['Agent', 'Task']);
+const LAUNCHER_TOOL_NAMES = new Set(['Agent', 'Task', 'Bash']);
+const TASK_KIND_BY_TYPE = new Map([['local_agent', 'agent'], ['local_bash', 'local_bash']]);
+const TASK_EVENT_SUBTYPES = new Set(['task_started', 'task_progress', 'task_updated', 'task_notification']);
+const MAX_DIAGNOSTICS = 200;
+
+function id(value) { return typeof value === 'string' && value.trim() !== '' ? value : null; }
+function ownerRunIdOf(sdkSessionId, parentNativeAgentId, launcherToolUseId) {
+  return JSON.stringify(['sdk-launch', 1, sdkSessionId, parentNativeAgentId, launcherToolUseId]);
+}
+function tupleKey() { return JSON.stringify([...arguments]); }
+
+class NativeTaskRegistry {
+  constructor(scopeInput) {
+    const scope = createTaskScope(scopeInput);
+    if (!scope) throw new Error('NativeTaskRegistry requires a valid fixed TaskScope');
+    this._scope = Object.freeze(scope);
+    this._tasks = new Map();
+    this._byToolUse = new Map();
+    this._byRefKey = new Map();
+    this._rootLaunchers = new Map();
+    this._nestedLaunchers = new Map();
+    this._receipts = new Map();
+    this._agents = new Map();
+    this._diagnostics = [];
+    this._diagSeen = new Set();
+  }
+
+  get scope() { return { storeScope: this._scope.storeScope, contextId: this._scope.contextId, parentSessionId: this._scope.parentSessionId }; }
+  diagnostics() { return this._diagnostics.map(d => ({ ...d })); }
+
+  // Raw SDK stream messages. Assistant messages only provide launcher facts
+  // (real tool_use blocks); model prose never creates tasks or owners.
+  observeSdkMessage(message) {
+    if (!message || typeof message !== 'object') return null;
+    if (message.type === 'assistant') return this._observeAssistant(message);
+    if (message.type === 'system') return this._observeTaskSystem(message);
+    return null;
+  }
+
+  _observeAssistant(message) {
+    const sdkSessionId = id(message.session_id);
+    if (!sdkSessionId) { this._diag('assistant-missing-session-id', {}); return null; }
+    if (id(message.parent_tool_use_id)) return null;
+    const raw = message.message && typeof message.message === 'object' ? message.message : message;
+    const blocks = Array.isArray(raw.content) ? raw.content : [];
+    let recorded = 0;
+    for (const block of blocks) {
+      if (!block || typeof block !== 'object' || block.type !== 'tool_use') continue;
+      const toolUseId = id(block.id);
+      if (!toolUseId) continue;
+      if (LAUNCHER_TOOL_NAMES.has(block.name)) {
+        const key = tupleKey(sdkSessionId, toolUseId);
+        if (!this._rootLaunchers.has(key)) { this._rootLaunchers.set(key, { toolName: block.name, sdkSessionId, toolUseId }); recorded++; }
+      }
+    }
+    if (recorded > 0) this._retryUnbound();
+    return recorded;
+  }
+
+  // Normalized claude/native-trace observations (W1-08 shape).
+  observeTrace(trace) {
+    if (!trace || typeof trace !== 'object') return null;
+    if (trace.type !== 'claude/native-trace' || trace.source !== 'sdk-hook') return null;
+    const hookEvent = id(trace.hookEvent);
+    const sdkSessionId = id(trace.sdkSessionId);
+    const toolName = id(trace.toolName);
+    if (!hookEvent || !sdkSessionId) { this._diag('trace-missing-identity', { hookEvent: hookEvent === null ? null : hookEvent.slice(0, 40) }); return null; }
+    if (id(trace.parentSessionId) !== this._scope.parentSessionId) {
+      this._diag('trace-parent-session-mismatch', { hookEvent, sdkSessionId, parentSessionId: id(trace.parentSessionId) });
+      return null;
+    }
+    if (hookEvent === 'SubagentStart' || hookEvent === 'SubagentStop') { this._diag(hookEvent === 'SubagentStop' ? 'subagent-stop-not-terminal' : 'subagent-start-not-launch', { sdkSessionId }); return null; }
+    const rawId = id(trace.rawToolUseId);
+    const callbackId = id(trace.callbackToolUseId);
+    const toolUseId = rawId || callbackId;
+    if (!toolUseId) { this._diag('trace-missing-tool-use-id', { hookEvent, sdkSessionId }); return null; }
+    if (rawId && callbackId && rawId !== callbackId) { this._diag('receipt-id-mismatch', { hookEvent, sdkSessionId, rawToolUseId: rawId, callbackToolUseId: callbackId }); return null; }
+    const dispatcher = id(trace.nativeAgentId);
+    if (hookEvent === 'PreToolUse') {
+      if (!dispatcher) { this._diag('pre-hook-missing-agent-context', { sdkSessionId, toolUseId }); return null; }
+      if (LAUNCHER_TOOL_NAMES.has(toolName)) {
+        const key = tupleKey(sdkSessionId, dispatcher, toolUseId);
+        if (!this._nestedLaunchers.has(key)) this._nestedLaunchers.set(key, { toolName, dispatcher, sdkSessionId, toolUseId });
+        this._retryUnbound();
+      }
+      return toolUseId;
+    }
+    if (hookEvent === 'PostToolUseFailure') { this._diag('receipt-failure-kept', { sdkSessionId, toolUseId }); return null; }
+    if (hookEvent !== 'PostToolUse') return null;
+    const response = trace.toolResponse && typeof trace.toolResponse === 'object' ? trace.toolResponse : null;
+    const agentId = response ? id(response.agentId) : null;
+    if (!AGENT_TOOL_NAMES.has(toolName)) {
+      if (agentId) this._diag('non-agent-receipt-ignored', { sdkSessionId, toolUseId, toolName });
+      return null;
+    }
+    if (!agentId) { this._diag('receipt-missing-agent-id', { sdkSessionId, toolUseId, toolName }); return null; }
+    this._recordReceipt(sdkSessionId, toolUseId, { agentId, dispatcher, toolName, sdkSessionId, toolUseId });
+    this._retryUnbound();
+    return toolUseId;
+  }
+
+  _observeTaskSystem(message) {
+    const subtype = message.subtype;
+    if (!TASK_EVENT_SUBTYPES.has(subtype)) return null;
+    const taskId = id(message.task_id);
+    const sdkSessionId = id(message.session_id);
+    if (!taskId || !sdkSessionId) { this._diag('task-event-missing-identity', { subtype, hasTaskId: taskId !== null, hasSessionId: sdkSessionId !== null }); return null; }
+    const task = this._ensureTask(sdkSessionId, taskId);
+    task.observedEvents++;
+    if (subtype === 'task_started') {
+      task.startedSeen = true;
+      const taskType = id(message.task_type);
+      if (task.taskType === null) task.taskType = taskType;
+      else if (taskType !== null && taskType !== task.taskType) {
+        task.typeConflict = true;
+        this._diag('task-type-conflict', { sdkSessionId, taskId, existing: task.taskType, incoming: taskType });
+      }
+    }
+    const toolUseId = id(message.tool_use_id);
+    if (toolUseId) {
+      if (task.toolUseId === null) {
+        task.toolUseId = toolUseId;
+        const key = tupleKey(sdkSessionId, toolUseId);
+        if (!this._byToolUse.has(key)) this._byToolUse.set(key, new Set());
+        this._byToolUse.get(key).add(task.taskKey);
+      } else if (task.toolUseId !== toolUseId) {
+        this._diag('task-tooluse-conflict', { sdkSessionId, taskId, existing: task.toolUseId, incoming: toolUseId });
+      }
+    }
+    this._applyStatus(task, message);
+    this._tryBind(task);
+    return task.taskKey;
+  }
+
+  _applyStatus(task, message) {
+    let raw = null;
+    if (message.subtype === 'task_notification') {
+      raw = id(message.status);
+      if (raw === null) { this._diag('notification-without-status', { sdkSessionId: task.sdkSessionId, taskId: task.taskId }); return; }
+    } else {
+      const patch = message.patch && typeof message.patch === 'object' ? message.patch : {};
+      raw = id(message.status) || id(patch.status) || (message.subtype === 'task_started' ? 'running' : null);
+    }
+    if (raw === null) {
+      if (message.subtype === 'task_progress' && task.status === null) { task.status = 'running'; task.statusSource = 'task_progress'; }
+      return;
+    }
+    if (!TASK_STATUSES.has(raw)) { this._diag('unknown-task-status', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, subtype: message.subtype, raw: String(raw).slice(0, 40) }); return; }
+    const prior = task.status;
+    if (prior === null) { task.status = raw; task.statusSource = message.subtype; return; }
+    if (TERMINAL_STATUSES.has(prior)) {
+      if (!TERMINAL_STATUSES.has(raw)) { this._diag('terminal-no-revival', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, subtype: message.subtype }); return; }
+      if (raw !== prior) { this._diag('terminal-conflict', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, prior, incoming: raw }); return; }
+      return;
+    }
+    task.status = raw; task.statusSource = message.subtype;
+  }
+
+  _ensureTask(sdkSessionId, taskId) {
+    const taskKey = JSON.stringify([sdkSessionId, taskId]);
+    let task = this._tasks.get(taskKey);
+    if (!task) {
+      task = { taskKey, sdkSessionId, taskId, toolUseId: null, status: null, statusSource: null, taskKind: null, taskType: null, startedSeen: false, typeConflict: false, association: 'unassigned', owner: null, mainToolUseId: null, observedEvents: 0 };
+      this._tasks.set(taskKey, task);
+    }
+    return task;
+  }
+
+  _recordReceipt(sdkSessionId, toolUseId, receipt) {
+    const key = tupleKey(sdkSessionId, toolUseId);
+    const claimants = this._byToolUse.get(key);
+    if (claimants) {
+      let matchesBound = false;
+      let boundCount = 0;
+      for (const taskKey of claimants) {
+        const t = this._tasks.get(taskKey);
+        if (t && t.owner) {
+          boundCount++;
+          if (t.owner.receiptAgentId === receipt.agentId && t.owner.parentNativeAgentId === receipt.dispatcher) matchesBound = true;
+        }
+      }
+      if (boundCount > 0 && !matchesBound) this._diag('owner-conflict-kept-first', { sdkSessionId, toolUseId, agentId: receipt.agentId, dispatcher: receipt.dispatcher });
+    }
+    const list = this._receipts.get(key) || [];
+    if (!list.some(r => r.agentId === receipt.agentId && r.dispatcher === receipt.dispatcher)) list.push(receipt);
+    this._receipts.set(key, list);
+  }
+
+  _tryBind(task) {
+    if (!task || task.owner !== null || task.toolUseId === null) return false;
+    if (!task.startedSeen) return false;
+    if (task.typeConflict) return false;
+    const taskKind = TASK_KIND_BY_TYPE.get(task.taskType) || null;
+    if (!taskKind) { this._diag('unknown-task-type', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, taskType: task.taskType }); return false; }
+    const key = tupleKey(task.sdkSessionId, task.toolUseId);
+    const root = this._rootLaunchers.get(key);
+    const matches = (this._receipts.get(key) || []).filter(r => r.agentId === task.taskId);
+    if (matches.length > 1) { this._diag('ambiguous-receipt', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, toolUseId: task.toolUseId }); return false; }
+    if (root && AGENT_TOOL_NAMES.has(root.toolName)) {
+      if (taskKind !== 'agent') { this._diag('task-type-conflict', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, toolUseId: task.toolUseId, launcherTool: root.toolName, taskType: task.taskType }); return false; }
+      if (matches.length === 1 && matches[0].dispatcher === null) return this._bind(task, { launcherKind: 'root', parentNativeAgentId: null, taskKind: 'agent', receipt: matches[0] });
+      return false;
+    }
+    if (matches.length === 1 && matches[0].dispatcher !== null) {
+      const receipt = matches[0];
+      const parentTaskKey = this._agents.get(tupleKey(task.sdkSessionId, receipt.dispatcher));
+      if (!parentTaskKey) { this._diag('unknown-dispatcher', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, toolUseId: task.toolUseId, dispatcher: receipt.dispatcher }); return false; }
+      const nested = this._nestedLaunchers.get(tupleKey(task.sdkSessionId, receipt.dispatcher, task.toolUseId));
+      if (!nested) { this._diag('receipt-without-launcher', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, toolUseId: task.toolUseId, dispatcher: receipt.dispatcher }); return false; }
+      const nestedKind = AGENT_TOOL_NAMES.has(nested.toolName) ? 'agent' : (nested.toolName === 'Bash' ? 'local_bash' : null);
+      if (taskKind !== nestedKind || nestedKind === null) { this._diag('task-type-conflict', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, toolUseId: task.toolUseId, launcherTool: nested.toolName, taskType: task.taskType }); return false; }
+      return this._bind(task, { launcherKind: 'nested', parentNativeAgentId: receipt.dispatcher, taskKind: nestedKind, receipt, parentTaskKey });
+    }
+    if (matches.length === 0) {
+      const candidates = [];
+      for (const entry of this._nestedLaunchers.values()) {
+        if (entry.sdkSessionId === task.sdkSessionId && entry.toolUseId === task.toolUseId && !candidates.some(c => c.dispatcher === entry.dispatcher)) candidates.push(entry);
+      }
+      if (candidates.length > 1) { this._diag('ambiguous-dispatcher', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, toolUseId: task.toolUseId }); return false; }
+      if (candidates.length === 1) {
+        const candidate = candidates[0];
+        const candidateKind = AGENT_TOOL_NAMES.has(candidate.toolName) ? 'agent' : (candidate.toolName === 'Bash' ? 'local_bash' : null);
+        if (taskKind !== candidateKind || candidateKind === null) { this._diag('task-type-conflict', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, toolUseId: task.toolUseId, launcherTool: candidate.toolName, taskType: task.taskType }); return false; }
+        if (candidateKind === 'agent') return false;
+        const parentTaskKey = this._agents.get(tupleKey(task.sdkSessionId, candidate.dispatcher));
+        if (!parentTaskKey) { this._diag('unknown-dispatcher', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, toolUseId: task.toolUseId, dispatcher: candidate.dispatcher }); return false; }
+        return this._bind(task, { launcherKind: 'nested', parentNativeAgentId: candidate.dispatcher, taskKind: 'local_bash', receipt: null, parentTaskKey });
+      }
+    }
+    if (root && root.toolName === 'Bash') {
+      if (taskKind !== 'local_bash') { this._diag('task-type-conflict', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, toolUseId: task.toolUseId, launcherTool: root.toolName, taskType: task.taskType }); return false; }
+      if (matches.length === 0) { task.association = 'main-command'; task.mainToolUseId = task.toolUseId; }
+      return false;
+    }
+    return false;
+  }
+  _bind(task, opts) {
+    const ownerRunId = ownerRunIdOf(task.sdkSessionId, opts.parentNativeAgentId, task.toolUseId);
+    const taskRef = createNativeTaskRef({ kind: 'native-task', storeScope: this._scope.storeScope, contextId: this._scope.contextId, parentSessionId: this._scope.parentSessionId, ownerRunId, taskId: task.taskId });
+    if (!taskRef) { this._diag('taskref-invalid', { sdkSessionId: task.sdkSessionId, taskId: task.taskId }); return false; }
+    const refKey = nativeTaskKey(taskRef);
+    if (this._byRefKey.has(refKey)) { this._diag('owner-ref-collision', { refKey, taskId: task.taskId }); return false; }
+    const parent = opts.parentTaskKey ? this._tasks.get(opts.parentTaskKey) : null;
+    const owner = { taskRef, ownerRunId, ownerBasis: 'sdk-tool-launch', launcherKind: opts.launcherKind, parentNativeAgentId: opts.parentNativeAgentId, launcherToolUseId: task.toolUseId, receiptAgentId: opts.receipt ? opts.receipt.agentId : null };
+    if (parent) owner.resolvedParent = { taskId: parent.taskId, sdkSessionId: parent.sdkSessionId, agentId: opts.receipt ? opts.receipt.dispatcher : opts.parentNativeAgentId, status: parent.status };
+    task.owner = owner;
+    task.taskKind = opts.taskKind;
+    task.association = 'bound';
+    this._byRefKey.set(refKey, task.taskKey);
+    if (opts.taskKind === 'agent' && opts.receipt) this._agents.set(tupleKey(task.sdkSessionId, opts.receipt.agentId), task.taskKey);
+    this._retryUnbound(task.taskKey);
+    return true;
+  }
+
+  _retryUnbound(exceptTaskKey) {
+    for (const task of this._tasks.values()) {
+      if (task.owner !== null || task.toolUseId === null) continue;
+      if (exceptTaskKey && task.taskKey === exceptTaskKey) continue;
+      this._tryBind(task);
+    }
+  }
+
+  list() { return [...this._tasks.values()].map(task => this._snapshot(task)); }
+
+  // Narrow trusted read-only binding query for the transcript collector:
+  // only bound agent tasks whose identity the registry itself established
+  // (SDK session id from the stream, receipt agent id from a real hook
+  // receipt). Fresh copies only; no status is interpreted here.
+  agentBindings() {
+    const out = [];
+    for (const task of this._tasks.values()) {
+      if (task.association !== 'bound' || task.taskKind !== 'agent') continue;
+      if (!task.owner || !task.owner.receiptAgentId || task.owner.receiptAgentId !== task.taskId) continue;
+      if (typeof task.sdkSessionId !== 'string' || !task.sdkSessionId || typeof task.taskId !== 'string' || !task.taskId) continue;
+      out.push({
+        sdkSessionId: task.sdkSessionId,
+        taskId: task.taskId,
+        taskRef: task.owner.taskRef ? JSON.parse(JSON.stringify(task.owner.taskRef)) : null,
+        ownerRunId: task.owner.ownerRunId || null,
+        status: task.status === undefined ? null : task.status,
+      });
+    }
+    return out;
+  }
+
+  getTask(ref) {
+    const taskRef = createNativeTaskRef(ref);
+    if (!taskRef) return null;
+    if (!sameTaskScope(taskRef, this._scope)) return null;
+    const taskKey = this._byRefKey.get(nativeTaskKey(taskRef));
+    if (!taskKey) return null;
+    const task = this._tasks.get(taskKey);
+    return task ? this._snapshot(task) : null;
+  }
+
+  _snapshot(task) {
+    return JSON.parse(JSON.stringify({
+      sdkSessionId: task.sdkSessionId, taskId: task.taskId, toolUseId: task.toolUseId,
+      status: task.status, statusSource: task.statusSource, taskKind: task.taskKind, taskType: task.taskType, startedSeen: task.startedSeen, typeConflict: task.typeConflict === true, association: task.association,
+      taskRef: task.owner ? task.owner.taskRef : null, ownerRunId: task.owner ? task.owner.ownerRunId : null,
+      owner: task.owner ? { ownerBasis: task.owner.ownerBasis, launcherKind: task.owner.launcherKind, parentNativeAgentId: task.owner.parentNativeAgentId, launcherToolUseId: task.owner.launcherToolUseId, receiptAgentId: task.owner.receiptAgentId, resolvedParent: task.owner.resolvedParent || null } : null,
+      mainToolUseId: task.mainToolUseId, observedEvents: task.observedEvents,
+    }));
+  }
+
+  _diag(code, ids) {
+    const signature = code + '|' + JSON.stringify(ids || {});
+    if (this._diagSeen.has(signature)) return;
+    if (this._diagnostics.length >= MAX_DIAGNOSTICS) return;
+    this._diagSeen.add(signature);
+    this._diagnostics.push(Object.assign({ code }, ids || {}));
+  }
+}
+
+module.exports = { NativeTaskRegistry };