@sanqianx/claude-ai-workbench 0.13.2 → 0.13.3

package/src/backend/lib/native-task-history-index.js

@@ -1,475 +1,475 @@
-'use strict';
-
-// Native task history index - a rebuildable, scope-fixed index over one
-// session's durable history rows. Inputs are { offset, endOffset, event }
-// records whose byte boundaries a later file reader measured on the real
-// line; every accepted row is copied into a small immutable snapshot
-// (offsets, kind, roles, traceId, sequence, hash) at observe time - tool
-// bodies, results and source text are never stored, and later mutation of
-// the caller's record cannot rewrite an accepted fact. Ownership comes
-// solely from real claude/native-task-state rows (complete fixed scope,
-// sdkSessionId/taskId, canonical NativeTaskRef and a fully consistent
-// owner: sdk-launch tuple, ownerBasis, launcher kind, receipt and task
-// type); a row that fails any check is rejected whole - it applies no
-// status and consumes no row position. Child claude/native-trace rows
-// attach by actual (sdkSessionId, nativeAgentId); lifecycle rows such as
-// SubagentStop legitimately carry no tool id. Public-read
-// claude/native-task-transcript rows attach by the same trusted
-// (sdkSessionId, agent id) tuple - for a bound agent the taskId IS the
-// receipt agent id - and never create a task or claim ownership. Bash facts
-// route by (sdkSessionId, parent nativeAgentId, toolUseId) so identical
-// tool ids under different parents never cross. Pending rows hold metadata
-// only and are never artificially capped - a complete history rebuilds
-// completely. Pure index: no file I/O, no HTTP, no stop, no public cursor.
-
-const crypto = require('node:crypto');
-const { createTaskScope, createNativeTaskRef, nativeTaskKey, sameTaskScope } = require('./task-identity');
-
-const TASK_EVENT_TYPES = new Set(['claude/task-started', 'claude/task-progress', 'claude/task-updated', 'claude/task-notification']);
-const AGENT_TOOL_NAMES = new Set(['Agent', 'Task']);
-const TASK_STATUSES = new Set(['pending', 'running', 'completed', 'failed', 'stopped']);
-const TERMINAL_STATUSES = new Set(['completed', 'failed', 'stopped']);
-const TASK_KIND_BY_TYPE = new Map([['local_agent', 'agent'], ['local_bash', 'local_bash']]);
-const STATE_ASSOCIATIONS = new Set(['bound', 'main-command', 'unassigned']);
-const MAX_DIAGNOSTICS = 500;
-const MAX_SEEN_SIGNATURES = 2000;
-const DEFAULT_LIMIT = 100;
-const MAX_LIMIT = 1000;
-
-function id(value) { return typeof value === 'string' && value.trim() !== '' ? value : null; }
-function tupleKey() { return JSON.stringify([...arguments]); }
-function rowHash(event) { return crypto.createHash('sha256').update(JSON.stringify(event)).digest('hex'); }
-
-// Full consistency validation of a bound claude/native-task-state claim,
-// checked BEFORE anything is applied: canonical ref matching the row and
-// constructor scope, registry owner basis, launcher/receipt rules, a known
-// task type consistent with the established one, and the canonical
-// sdk-launch ownerRunId tuple. Returns a diagnostic code, or null when the
-// ownership claim is fully consistent.
-function validateBoundState(event, scope, sdkSessionId, taskId, establishedTaskType) {
-  const ref = createNativeTaskRef(event.taskRef);
-  if (!ref) return 'state-ref-invalid';
-  if (!sameTaskScope(ref, scope)) return 'state-ref-scope-mismatch';
-  if (ref.taskId !== taskId || ref.ownerRunId !== id(event.ownerRunId)) return 'state-ref-inconsistent';
-  if (event.typeConflict === true) return 'conflicted-type-not-bindable';
-  const taskType = id(event.taskType);
-  const taskKind = TASK_KIND_BY_TYPE.get(taskType) || null;
-  if (!taskKind) return 'unknown-task-type';
-  if (id(event.taskKind) !== taskKind) return 'state-kind-inconsistent';
-  if (establishedTaskType !== null && establishedTaskType !== taskType) return 'task-type-conflict-bind';
-  const owner = event.owner && typeof event.owner === 'object' ? event.owner : null;
-  if (!owner || id(owner.ownerBasis) !== 'sdk-tool-launch') return 'owner-basis-invalid';
-  const launcherKind = id(owner.launcherKind);
-  if (launcherKind !== 'root' && launcherKind !== 'nested') return 'owner-basis-invalid';
-  const parentNativeAgentId = id(owner.parentNativeAgentId);
-  const launcherToolUseId = id(owner.launcherToolUseId);
-  if (!launcherToolUseId) return 'owner-basis-invalid';
-  if ((launcherKind === 'root') !== (parentNativeAgentId === null)) return 'launcher-kind-inconsistent';
-  if (taskKind === 'local_bash' && launcherKind !== 'nested') return 'launcher-kind-inconsistent';
-  const receiptAgentId = id(owner.receiptAgentId);
-  if (taskKind === 'agent' && receiptAgentId !== taskId) return 'receipt-task-mismatch';
-  if (taskKind === 'local_bash' && receiptAgentId !== null && receiptAgentId !== taskId) return 'receipt-task-mismatch';
-  let tuple = null;
-  try { tuple = JSON.parse(event.ownerRunId); } catch (error) { tuple = null; }
-  const tupleOk = Array.isArray(tuple) && tuple.length === 5 && tuple[0] === 'sdk-launch' && tuple[1] === 1
-    && tuple[2] === sdkSessionId && tuple[3] === parentNativeAgentId && tuple[4] === launcherToolUseId;
-  if (!tupleOk) return 'owner-run-id-invalid';
-  return null;
-}
-
-class NativeTaskHistoryIndex {
-  constructor(scopeInput) {
-    const scope = createTaskScope(scopeInput);
-    if (!scope) throw new Error('NativeTaskHistoryIndex requires a valid fixed TaskScope');
-    this._scope = Object.freeze(scope);
-    this._tasks = new Map();
-    this._byRefKey = new Map();
-    this._agents = new Map();
-    this._bashByTool = new Map();
-    this._seenRows = new Map();
-    this._pendingTraces = new Map();
-    this._pendingDispatch = new Map();
-    this._pendingBash = new Map();
-    this._pendingRefs = 0;
-    this._diagnostics = [];
-    this._diagSeen = new Set();
-    this._stats = { rowsObserved: 0, rowsReplayed: 0, rowsIndexed: 0, rowsUnattributed: 0, diagnostics: 0 };
-  }
-
-  get scope() { return { storeScope: this._scope.storeScope, contextId: this._scope.contextId, parentSessionId: this._scope.parentSessionId }; }
-  diagnostics() { return this._diagnostics.map(d => ({ ...d })); }
-
-  // One durable row. Returns the number of NEW per-task view positions the
-  // row produced; rows held pending until their real binding state arrives
-  // count zero here. Everything the index keeps about the row is copied
-  // into one immutable snap before routing, so a later mutation of the
-  // caller's record cannot rewrite an accepted fact. Replaying a
-  // byte-identical row is a no-op; the same offset with a different range
-  // or content is an explicit conflict.
-  observe(record) {
-    this._stats.rowsObserved++;
-    if (!record || typeof record !== 'object' || !Number.isSafeInteger(record.offset) || record.offset <= 0
-      || !Number.isSafeInteger(record.endOffset) || record.endOffset <= record.offset
-      || !record.event || typeof record.event !== 'object') {
-      this._diag('invalid-record', {}); return 0;
-    }
-    const event = record.event;
-    if (event.type !== 'claude/native-task-state' && event.type !== 'claude/native-trace'
-      && event.type !== 'claude/native-task-transcript' && !TASK_EVENT_TYPES.has(event.type)) return 0;
-    const hash = rowHash(event);
-    const seen = this._seenRows.get(record.offset);
-    if (seen) {
-      this._stats.rowsReplayed++;
-      if (seen.endOffset !== record.endOffset) this._diag('row-range-conflict', { offset: record.offset, existingEnd: seen.endOffset, incomingEnd: record.endOffset });
-      else if (seen.hash !== hash) this._diag('row-content-conflict', { offset: record.offset });
-      return 0;
-    }
-    this._seenRows.set(record.offset, { endOffset: record.endOffset, hash });
-    const snap = Object.freeze({ offset: record.offset, endOffset: record.endOffset, kind: event.type, traceId: id(event.traceId), sequence: Number(event.sequence) || null, hash });
-    let added = 0;
-    if (event.type === 'claude/native-task-state') added = this._observeState(event, snap);
-    else if (event.type === 'claude/native-trace') added = this._observeTrace(event, snap);
-    else if (event.type === 'claude/native-task-transcript') added = this._observeTranscript(event, snap);
-    else added = this._observeTaskEvent(event, snap);
-    if (added === 0) this._stats.rowsUnattributed++;
-    return added;
-  }
-
-  // Only a real claude/native-task-state row with the complete fixed scope,
-  // a canonical NativeTaskRef and a fully consistent owner establishes
-  // ownership; anything insufficient stays explicitly unassigned. Every
-  // check runs to completion BEFORE anything is applied, so a rejected row
-  // applies no status, attaches no position, claims no agent and creates
-  // no task.
-  _observeState(event, snap) {
-    const sdkSessionId = id(event.sdkSessionId);
-    const taskId = id(event.taskId);
-    if (this._explicitScopeConflict(event) || !sameTaskScope(event.scope, this._scope)) {
-      this._diag('state-scope-mismatch', { sdkSessionId, taskId });
-      return 0;
-    }
-    if (!sdkSessionId || !taskId) { this._diag('state-missing-identity', { hasSession: sdkSessionId !== null, hasTask: taskId !== null }); return 0; }
-    const association = id(event.association);
-    if (!STATE_ASSOCIATIONS.has(association)) {
-      this._diag('unknown-association', { sdkSessionId, taskId, association: association === null ? null : association.slice(0, 40) });
-      return 0;
-    }
-    const taskKey = JSON.stringify([sdkSessionId, taskId]);
-    const existing = this._tasks.get(taskKey) || null;
-    if (association !== 'bound') {
-      if (existing && existing.association === 'bound') {
-        this._diag('association-conflict', { sdkSessionId, taskId, prior: 'bound', incoming: association });
-        return 0;
-      }
-      const task = this._ensureTask(sdkSessionId, taskId);
-      const added = this._attach(task, snap, 'state');
-      this._applyStatus(task, event);
-      this._applyType(task, event);
-      task.association = association;
-      if (association === 'main-command') {
-        task.mainToolUseId = id(event.mainToolUseId) || id(event.toolUseId) || task.mainToolUseId;
-        this._registerBash(sdkSessionId, null, task.mainToolUseId, task);
-      }
-      return added;
-    }
-    const err = validateBoundState(event, this._scope, sdkSessionId, taskId, existing ? existing.taskType : null);
-    if (err) { this._diag(err, { sdkSessionId, taskId }); return 0; }
-    const ref = createNativeTaskRef(event.taskRef);
-    const refKey = nativeTaskKey(ref);
-    if (existing && existing.association === 'bound') {
-      // An owner, once bound, is immutable: a later different owner is a
-      // diagnosed conflict that changes nothing, never a rewrite.
-      if (existing.ownerRunId !== ref.ownerRunId) {
-        this._diag('owner-conflict', { sdkSessionId, taskId, existing: existing.ownerRunId, incoming: ref.ownerRunId });
-        return 0;
-      }
-    } else {
-      const claimed = this._byRefKey.get(refKey);
-      if (claimed && claimed !== taskKey) { this._diag('owner-ref-collision', { sdkSessionId, taskId }); return 0; }
-    }
-    const task = this._ensureTask(sdkSessionId, taskId);
-    if (task.association !== 'bound') {
-      task.association = 'bound';
-      task.taskRef = ref;
-      task.ownerRunId = ref.ownerRunId;
-      const source = event.owner && typeof event.owner === 'object' ? event.owner : {};
-      task.owner = { ownerBasis: id(source.ownerBasis), launcherKind: id(source.launcherKind), parentNativeAgentId: id(source.parentNativeAgentId), launcherToolUseId: id(source.launcherToolUseId), receiptAgentId: id(source.receiptAgentId) };
-      this._byRefKey.set(refKey, task.taskKey);
-    }
-    const added = this._attach(task, snap, 'state');
-    this._applyStatus(task, event);
-    this._applyType(task, event);
-    this._flushPendingFor(task);
-    return added;
-  }
-
-  // Any explicitly present session/scope field that contradicts the fixed
-  // scope rejects the whole row; absent fields stay absent - the index
-  // never guesses a scope from silence. Returns the conflicting field
-  // name, or null when every explicit field agrees.
-  _explicitScopeConflict(event) {
-    if (event.parentSessionId !== undefined && id(event.parentSessionId) !== this._scope.parentSessionId) return 'parentSessionId';
-    if (event.contextId !== undefined && id(event.contextId) !== this._scope.contextId) return 'contextId';
-    if (event.storeScope !== undefined && id(event.storeScope) !== this._scope.storeScope) return 'storeScope';
-    if (event.scope !== undefined) {
-      if (!event.scope || typeof event.scope !== 'object') return 'scope';
-      if (id(event.scope.storeScope) !== this._scope.storeScope) return 'storeScope';
-      if (id(event.scope.contextId) !== this._scope.contextId) return 'contextId';
-      if (id(event.scope.parentSessionId) !== this._scope.parentSessionId) return 'parentSessionId';
-    }
-    return null;
-  }
-
-  // Child claude/native-trace rows: the actor (nativeAgentId) is the agent
-  // in whose context the event happened - its own tools, its lifecycle
-  // rows and the nested dispatch tools it launched all belong to that
-  // dispatcher. Lifecycle rows (SubagentStart/SubagentStop) legitimately
-  // carry no tool id; tool rows (PreToolUse/PostToolUse) must carry one.
-  // A root Agent/Task PostToolUse receipt only identifies the spawned
-  // agent: it is dispatch metadata for that agent, never the agent's own
-  // executed tool. A Bash fact feeds both the parent agent view and the
-  // command view, keyed by the REAL parent (root explicitly null) so
-  // identical tool ids under different parents never cross; each view
-  // holds the offset exactly once.
-  _observeTrace(event, snap) {
-    if (event.source !== 'sdk-hook') return 0;
-    const sdkSessionId = id(event.sdkSessionId);
-    if (!sdkSessionId) { this._diag('trace-missing-session', {}); return 0; }
-    const conflict = this._explicitScopeConflict(event);
-    if (conflict) {
-      this._diag(conflict === 'parentSessionId' ? 'trace-parent-session-mismatch' : 'trace-scope-mismatch', { sdkSessionId, field: conflict });
-      return 0;
-    }
-    const rawId = id(event.rawToolUseId);
-    const callbackId = id(event.callbackToolUseId);
-    if (rawId && callbackId && rawId !== callbackId) { this._diag('trace-id-mismatch', { sdkSessionId }); return 0; }
-    const toolUseId = rawId || callbackId;
-    const hookEvent = id(event.hookEvent);
-    if ((hookEvent === 'PreToolUse' || hookEvent === 'PostToolUse') && !toolUseId) {
-      this._diag('trace-missing-tool-use-id', { sdkSessionId, hookEvent });
-      return 0;
-    }
-    const actor = id(event.nativeAgentId);
-    const toolName = id(event.toolName);
-    const response = event.toolResponse && typeof event.toolResponse === 'object' ? event.toolResponse : null;
-    const receiptAgentId = response ? id(response.agentId) : null;
-    let added = 0;
-    if (actor) {
-      const taskKey = this._agents.get(tupleKey(sdkSessionId, actor));
-      if (taskKey) added += this._attach(this._tasks.get(taskKey), snap, 'trace');
-      else this._pend(this._pendingTraces, tupleKey(sdkSessionId, actor), snap);
-    } else if (receiptAgentId && AGENT_TOOL_NAMES.has(toolName) && hookEvent === 'PostToolUse') {
-      const taskKey = this._agents.get(tupleKey(sdkSessionId, receiptAgentId));
-      if (taskKey) added += this._attach(this._tasks.get(taskKey), snap, 'dispatch');
-      else this._pend(this._pendingDispatch, tupleKey(sdkSessionId, receiptAgentId), snap);
-    }
-    if (toolName === 'Bash') {
-      if (toolUseId) added += this._attachBash(sdkSessionId, actor, toolUseId, snap);
-      else this._diag('bash-trace-missing-tool-use-id', { sdkSessionId, hookEvent });
-    }
-    return added;
-  }
-
-  // Public-read transcript snapshots (claude/native-task-transcript). The
-  // row attaches to the bound agent task it was read for, routed by the
-  // same trusted (sdkSessionId, agent id) tuple the traces use - for a
-  // bound agent the row's taskId IS the receipt agent id. A transcript row
-  // never creates a task, never claims ownership, never applies a status:
-  // it is content evidence under an ownership someone else already proved.
-  // A row with no binding yet waits pending exactly like a trace row.
-  _observeTranscript(event, snap) {
-    if (event.source !== 'sdk-public-read') return 0;
-    const sdkSessionId = id(event.sdkSessionId);
-    const taskId = id(event.taskId);
-    if (!sdkSessionId || !taskId) { this._diag('transcript-missing-identity', { hasSession: sdkSessionId !== null, hasTask: taskId !== null }); return 0; }
-    const conflict = this._explicitScopeConflict(event);
-    if (conflict) { this._diag('transcript-scope-mismatch', { sdkSessionId, taskId, field: conflict }); return 0; }
-    const taskKey = this._agents.get(tupleKey(sdkSessionId, taskId));
-    if (taskKey) return this._attach(this._tasks.get(taskKey), snap, 'transcript');
-    this._pend(this._pendingTraces, tupleKey(sdkSessionId, taskId), snap);
-    return 0;
-  }
-
-  _attachBash(sdkSessionId, parentNativeAgentId, toolUseId, snap) {
-    const key = tupleKey(sdkSessionId, parentNativeAgentId, toolUseId);
-    const taskKey = this._bashByTool.get(key);
-    if (taskKey) return this._attach(this._tasks.get(taskKey), snap, 'trace');
-    this._pend(this._pendingBash, key, snap);
-    return 0;
-  }
-
-  // Pending rows keep only their immutable snap - offsets, hash and the
-  // routing decision made at observe time. There is deliberately no cap:
-  // an artificially truncated pending set would silently turn a complete
-  // history into an incomplete one.
-  _pend(map, key, snap) {
-    const list = map.get(key) || [];
-    list.push(snap);
-    map.set(key, list);
-    this._pendingRefs++;
-  }
-
-  // Canonical SDK task events (claude/task-*). Their sdkSessionId/taskId
-  // are real facts once present; rows without them are insufficient old
-  // data and never guess an identity. status may be an explicit null from
-  // the reviewed no-fake-success semantics.
-  _observeTaskEvent(event, snap) {
-    const sdkSessionId = id(event.sdkSessionId);
-    const taskId = id(event.taskId);
-    if (!sdkSessionId || !taskId) { this._diag('task-event-missing-identity', { type: event.type }); return 0; }
-    if (id(event.parentSessionId) !== null && event.parentSessionId !== this._scope.parentSessionId) {
-      this._diag('task-event-scope-mismatch', { type: event.type, sdkSessionId, taskId });
-      return 0;
-    }
-    const task = this._ensureTask(sdkSessionId, taskId);
-    this._applyStatus(task, event);
-    if (id(event.taskType) !== null) this._applyType(task, event);
-    return this._attach(task, snap, 'task-event');
-  }
-
-  _applyStatus(task, event) {
-    const raw = id(event.status);
-    const source = id(event.statusSource) || id(event.type);
-    if (raw === null) return;
-    if (!TASK_STATUSES.has(raw)) { this._diag('unknown-task-status', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, raw: raw.slice(0, 40) }); return; }
-    const prior = task.status;
-    if (prior === null) { task.status = raw; task.statusSource = source; return; }
-    if (TERMINAL_STATUSES.has(prior)) {
-      if (!TERMINAL_STATUSES.has(raw)) { this._diag('terminal-no-revival', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, incoming: raw }); return; }
-      if (raw !== prior) { this._diag('terminal-conflict', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, prior, incoming: raw }); return; }
-      return;
-    }
-    task.status = raw; task.statusSource = source;
-  }
-
-  _applyType(task, event) {
-    const taskType = id(event.taskType);
-    if (taskType === null) return;
-    if (task.taskType === null) {
-      task.taskType = taskType;
-      task.taskKind = TASK_KIND_BY_TYPE.get(taskType) || null;
-    } else if (taskType !== task.taskType) {
-      task.typeConflict = true;
-      this._diag('task-type-conflict', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, existing: task.taskType, incoming: taskType });
-    }
-  }
-
-  _ensureTask(sdkSessionId, taskId) {
-    const taskKey = JSON.stringify([sdkSessionId, taskId]);
-    let task = this._tasks.get(taskKey);
-    if (!task) {
-      task = { taskKey, sdkSessionId, taskId, taskKind: null, taskType: null, typeConflict: false, status: null, statusSource: null, association: 'unassigned', taskRef: null, ownerRunId: null, owner: null, mainToolUseId: null, view: new Map() };
-      this._tasks.set(taskKey, task);
-    }
-    return task;
-  }
-
-  _attach(task, snap, role) {
-    if (!task) return 0;
-    let entry = task.view.get(snap.offset);
-    if (!entry) {
-      entry = { offset: snap.offset, endOffset: snap.endOffset, kind: snap.kind, roles: new Set([role]), traceId: snap.traceId, sequence: snap.sequence, hash: snap.hash };
-      task.view.set(snap.offset, entry);
-      this._stats.rowsIndexed++;
-      return 1;
-    }
-    entry.roles.add(role);
-    return 0;
-  }
-
-  _flushPendingFor(task) {
-    if (task.association !== 'bound') return;
-    if (task.taskKind === 'agent' && task.owner && task.owner.receiptAgentId) {
-      const key = tupleKey(task.sdkSessionId, task.owner.receiptAgentId);
-      const claimant = this._agents.get(key);
-      if (claimant && claimant !== task.taskKey) { this._diag('agent-claim-conflict', { sdkSessionId: task.sdkSessionId, agentId: task.owner.receiptAgentId }); return; }
-      this._agents.set(key, task.taskKey);
-      this._flushList(this._pendingTraces, key, task, 'trace');
-      this._flushList(this._pendingDispatch, key, task, 'dispatch');
-    }
-    if (task.taskKind === 'local_bash' && task.owner) {
-      this._registerBash(task.sdkSessionId, task.owner.parentNativeAgentId, task.owner.launcherToolUseId, task);
-    }
-  }
-
-  _flushList(map, key, task, role) {
-    const list = map.get(key);
-    if (!list) return;
-    map.delete(key);
-    this._pendingRefs -= list.length;
-    for (const snap of list) this._attach(task, snap, role);
-  }
-
-  // First real claim on (sdkSessionId, parent nativeAgentId, toolUseId)
-  // wins - a root command claims with an explicit null parent. A different
-  // later claimant is a diagnosed conflict, never a silent re-route.
-  _registerBash(sdkSessionId, parentNativeAgentId, toolUseId, task) {
-    if (!toolUseId) return;
-    const key = tupleKey(sdkSessionId, parentNativeAgentId, toolUseId);
-    const existing = this._bashByTool.get(key);
-    if (existing && existing !== task.taskKey) { this._diag('bash-claim-conflict', { sdkSessionId, parentNativeAgentId, toolUseId }); return; }
-    this._bashByTool.set(key, task.taskKey);
-    this._flushList(this._pendingBash, key, task, 'trace');
-  }
-
-  // Metadata-only task snapshots; historical 'running' is a past
-  // observation and never a claim that a current process is still alive.
-  listTasks() {
-    const out = [];
-    for (const task of this._tasks.values()) {
-      let first = null, last = null;
-      for (const offset of task.view.keys()) {
-        if (first === null || offset < first) first = offset;
-        if (last === null || offset > last) last = offset;
-      }
-      out.push({ sdkSessionId: task.sdkSessionId, taskId: task.taskId, taskKind: task.taskKind, taskType: task.taskType, typeConflict: task.typeConflict === true, status: task.status, statusSource: task.statusSource, association: task.association, taskRef: task.taskRef, ownerRunId: task.ownerRunId, owner: task.owner, mainToolUseId: task.mainToolUseId, rowCount: task.view.size, firstOffset: first, lastOffset: last });
-    }
-    return JSON.parse(JSON.stringify(out));
-  }
-
-  // Internal byte-position pagination over one task's original rows, newest
-  // window first and ascending within a page. `before` is an exclusive raw
-  // offset boundary inside the same file era - NOT a public opaque cursor;
-  // stream sequences are never treated as positions.
-  listOffsets(taskRef, { before, limit } = {}) {
-    const ref = createNativeTaskRef(taskRef);
-    if (!ref) throw Object.assign(new Error('invalid native task reference'), { code: 'INVALID_TASK_REF' });
-    if (!sameTaskScope(ref, this._scope)) throw Object.assign(new Error('task reference scope does not match this index'), { code: 'SCOPE_MISMATCH' });
-    const size = limit === undefined ? DEFAULT_LIMIT : limit;
-    if (!Number.isSafeInteger(size) || size < 1 || size > MAX_LIMIT) throw Object.assign(new Error('limit must be between 1 and ' + MAX_LIMIT), { code: 'INVALID_LIMIT' });
-    let bound = null;
-    if (before !== undefined && before !== null) {
-      if (!Number.isSafeInteger(before) || before <= 0) throw Object.assign(new Error('invalid before offset'), { code: 'INVALID_BEFORE' });
-      bound = before;
-    }
-    const taskKey = this._byRefKey.get(nativeTaskKey(ref));
-    if (!taskKey) return { entries: [], nextBefore: null };
-    const task = this._tasks.get(taskKey);
-    const offsets = [...task.view.keys()].sort((a, b) => a - b).filter(offset => bound === null || offset < bound);
-    const start = Math.max(0, offsets.length - size);
-    const page = offsets.slice(start);
-    return { entries: page.map(offset => this._entrySnapshot(task.view.get(offset))), nextBefore: start > 0 && page.length > 0 ? page[0] : null };
-  }
-
-  _entrySnapshot(entry) {
-    return { offset: entry.offset, endOffset: entry.endOffset, kind: entry.kind, roles: [...entry.roles].sort(), traceId: entry.traceId, sequence: entry.sequence, hash: entry.hash };
-  }
-
-  stats() {
-    let bound = 0;
-    for (const task of this._tasks.values()) if (task.association === 'bound') bound++;
-    return { ...this._stats, tasksTotal: this._tasks.size, tasksBound: bound, tasksUnassigned: this._tasks.size - bound, pendingRefs: this._pendingRefs };
-  }
-
-  _diag(code, ids) {
-    this._stats.diagnostics++;
-    const signature = code + '|' + JSON.stringify(ids || {});
-    if (this._diagSeen.has(signature)) return;
-    if (this._diagSeen.size >= MAX_SEEN_SIGNATURES) return;
-    this._diagSeen.add(signature);
-    if (this._diagnostics.length >= MAX_DIAGNOSTICS) return;
-    this._diagnostics.push(Object.assign({ code }, ids || {}));
-  }
-}
-
-module.exports = { NativeTaskHistoryIndex };
+'use strict';
+
+// Native task history index - a rebuildable, scope-fixed index over one
+// session's durable history rows. Inputs are { offset, endOffset, event }
+// records whose byte boundaries a later file reader measured on the real
+// line; every accepted row is copied into a small immutable snapshot
+// (offsets, kind, roles, traceId, sequence, hash) at observe time - tool
+// bodies, results and source text are never stored, and later mutation of
+// the caller's record cannot rewrite an accepted fact. Ownership comes
+// solely from real claude/native-task-state rows (complete fixed scope,
+// sdkSessionId/taskId, canonical NativeTaskRef and a fully consistent
+// owner: sdk-launch tuple, ownerBasis, launcher kind, receipt and task
+// type); a row that fails any check is rejected whole - it applies no
+// status and consumes no row position. Child claude/native-trace rows
+// attach by actual (sdkSessionId, nativeAgentId); lifecycle rows such as
+// SubagentStop legitimately carry no tool id. Public-read
+// claude/native-task-transcript rows attach by the same trusted
+// (sdkSessionId, agent id) tuple - for a bound agent the taskId IS the
+// receipt agent id - and never create a task or claim ownership. Bash facts
+// route by (sdkSessionId, parent nativeAgentId, toolUseId) so identical
+// tool ids under different parents never cross. Pending rows hold metadata
+// only and are never artificially capped - a complete history rebuilds
+// completely. Pure index: no file I/O, no HTTP, no stop, no public cursor.
+
+const crypto = require('node:crypto');
+const { createTaskScope, createNativeTaskRef, nativeTaskKey, sameTaskScope } = require('./task-identity');
+
+const TASK_EVENT_TYPES = new Set(['claude/task-started', 'claude/task-progress', 'claude/task-updated', 'claude/task-notification']);
+const AGENT_TOOL_NAMES = new Set(['Agent', 'Task']);
+const TASK_STATUSES = new Set(['pending', 'running', 'completed', 'failed', 'stopped']);
+const TERMINAL_STATUSES = new Set(['completed', 'failed', 'stopped']);
+const TASK_KIND_BY_TYPE = new Map([['local_agent', 'agent'], ['local_bash', 'local_bash']]);
+const STATE_ASSOCIATIONS = new Set(['bound', 'main-command', 'unassigned']);
+const MAX_DIAGNOSTICS = 500;
+const MAX_SEEN_SIGNATURES = 2000;
+const DEFAULT_LIMIT = 100;
+const MAX_LIMIT = 1000;
+
+function id(value) { return typeof value === 'string' && value.trim() !== '' ? value : null; }
+function tupleKey() { return JSON.stringify([...arguments]); }
+function rowHash(event) { return crypto.createHash('sha256').update(JSON.stringify(event)).digest('hex'); }
+
+// Full consistency validation of a bound claude/native-task-state claim,
+// checked BEFORE anything is applied: canonical ref matching the row and
+// constructor scope, registry owner basis, launcher/receipt rules, a known
+// task type consistent with the established one, and the canonical
+// sdk-launch ownerRunId tuple. Returns a diagnostic code, or null when the
+// ownership claim is fully consistent.
+function validateBoundState(event, scope, sdkSessionId, taskId, establishedTaskType) {
+  const ref = createNativeTaskRef(event.taskRef);
+  if (!ref) return 'state-ref-invalid';
+  if (!sameTaskScope(ref, scope)) return 'state-ref-scope-mismatch';
+  if (ref.taskId !== taskId || ref.ownerRunId !== id(event.ownerRunId)) return 'state-ref-inconsistent';
+  if (event.typeConflict === true) return 'conflicted-type-not-bindable';
+  const taskType = id(event.taskType);
+  const taskKind = TASK_KIND_BY_TYPE.get(taskType) || null;
+  if (!taskKind) return 'unknown-task-type';
+  if (id(event.taskKind) !== taskKind) return 'state-kind-inconsistent';
+  if (establishedTaskType !== null && establishedTaskType !== taskType) return 'task-type-conflict-bind';
+  const owner = event.owner && typeof event.owner === 'object' ? event.owner : null;
+  if (!owner || id(owner.ownerBasis) !== 'sdk-tool-launch') return 'owner-basis-invalid';
+  const launcherKind = id(owner.launcherKind);
+  if (launcherKind !== 'root' && launcherKind !== 'nested') return 'owner-basis-invalid';
+  const parentNativeAgentId = id(owner.parentNativeAgentId);
+  const launcherToolUseId = id(owner.launcherToolUseId);
+  if (!launcherToolUseId) return 'owner-basis-invalid';
+  if ((launcherKind === 'root') !== (parentNativeAgentId === null)) return 'launcher-kind-inconsistent';
+  if (taskKind === 'local_bash' && launcherKind !== 'nested') return 'launcher-kind-inconsistent';
+  const receiptAgentId = id(owner.receiptAgentId);
+  if (taskKind === 'agent' && receiptAgentId !== taskId) return 'receipt-task-mismatch';
+  if (taskKind === 'local_bash' && receiptAgentId !== null && receiptAgentId !== taskId) return 'receipt-task-mismatch';
+  let tuple = null;
+  try { tuple = JSON.parse(event.ownerRunId); } catch (error) { tuple = null; }
+  const tupleOk = Array.isArray(tuple) && tuple.length === 5 && tuple[0] === 'sdk-launch' && tuple[1] === 1
+    && tuple[2] === sdkSessionId && tuple[3] === parentNativeAgentId && tuple[4] === launcherToolUseId;
+  if (!tupleOk) return 'owner-run-id-invalid';
+  return null;
+}
+
+class NativeTaskHistoryIndex {
+  constructor(scopeInput) {
+    const scope = createTaskScope(scopeInput);
+    if (!scope) throw new Error('NativeTaskHistoryIndex requires a valid fixed TaskScope');
+    this._scope = Object.freeze(scope);
+    this._tasks = new Map();
+    this._byRefKey = new Map();
+    this._agents = new Map();
+    this._bashByTool = new Map();
+    this._seenRows = new Map();
+    this._pendingTraces = new Map();
+    this._pendingDispatch = new Map();
+    this._pendingBash = new Map();
+    this._pendingRefs = 0;
+    this._diagnostics = [];
+    this._diagSeen = new Set();
+    this._stats = { rowsObserved: 0, rowsReplayed: 0, rowsIndexed: 0, rowsUnattributed: 0, diagnostics: 0 };
+  }
+
+  get scope() { return { storeScope: this._scope.storeScope, contextId: this._scope.contextId, parentSessionId: this._scope.parentSessionId }; }
+  diagnostics() { return this._diagnostics.map(d => ({ ...d })); }
+
+  // One durable row. Returns the number of NEW per-task view positions the
+  // row produced; rows held pending until their real binding state arrives
+  // count zero here. Everything the index keeps about the row is copied
+  // into one immutable snap before routing, so a later mutation of the
+  // caller's record cannot rewrite an accepted fact. Replaying a
+  // byte-identical row is a no-op; the same offset with a different range
+  // or content is an explicit conflict.
+  observe(record) {
+    this._stats.rowsObserved++;
+    if (!record || typeof record !== 'object' || !Number.isSafeInteger(record.offset) || record.offset <= 0
+      || !Number.isSafeInteger(record.endOffset) || record.endOffset <= record.offset
+      || !record.event || typeof record.event !== 'object') {
+      this._diag('invalid-record', {}); return 0;
+    }
+    const event = record.event;
+    if (event.type !== 'claude/native-task-state' && event.type !== 'claude/native-trace'
+      && event.type !== 'claude/native-task-transcript' && !TASK_EVENT_TYPES.has(event.type)) return 0;
+    const hash = rowHash(event);
+    const seen = this._seenRows.get(record.offset);
+    if (seen) {
+      this._stats.rowsReplayed++;
+      if (seen.endOffset !== record.endOffset) this._diag('row-range-conflict', { offset: record.offset, existingEnd: seen.endOffset, incomingEnd: record.endOffset });
+      else if (seen.hash !== hash) this._diag('row-content-conflict', { offset: record.offset });
+      return 0;
+    }
+    this._seenRows.set(record.offset, { endOffset: record.endOffset, hash });
+    const snap = Object.freeze({ offset: record.offset, endOffset: record.endOffset, kind: event.type, traceId: id(event.traceId), sequence: Number(event.sequence) || null, hash });
+    let added = 0;
+    if (event.type === 'claude/native-task-state') added = this._observeState(event, snap);
+    else if (event.type === 'claude/native-trace') added = this._observeTrace(event, snap);
+    else if (event.type === 'claude/native-task-transcript') added = this._observeTranscript(event, snap);
+    else added = this._observeTaskEvent(event, snap);
+    if (added === 0) this._stats.rowsUnattributed++;
+    return added;
+  }
+
+  // Only a real claude/native-task-state row with the complete fixed scope,
+  // a canonical NativeTaskRef and a fully consistent owner establishes
+  // ownership; anything insufficient stays explicitly unassigned. Every
+  // check runs to completion BEFORE anything is applied, so a rejected row
+  // applies no status, attaches no position, claims no agent and creates
+  // no task.
+  _observeState(event, snap) {
+    const sdkSessionId = id(event.sdkSessionId);
+    const taskId = id(event.taskId);
+    if (this._explicitScopeConflict(event) || !sameTaskScope(event.scope, this._scope)) {
+      this._diag('state-scope-mismatch', { sdkSessionId, taskId });
+      return 0;
+    }
+    if (!sdkSessionId || !taskId) { this._diag('state-missing-identity', { hasSession: sdkSessionId !== null, hasTask: taskId !== null }); return 0; }
+    const association = id(event.association);
+    if (!STATE_ASSOCIATIONS.has(association)) {
+      this._diag('unknown-association', { sdkSessionId, taskId, association: association === null ? null : association.slice(0, 40) });
+      return 0;
+    }
+    const taskKey = JSON.stringify([sdkSessionId, taskId]);
+    const existing = this._tasks.get(taskKey) || null;
+    if (association !== 'bound') {
+      if (existing && existing.association === 'bound') {
+        this._diag('association-conflict', { sdkSessionId, taskId, prior: 'bound', incoming: association });
+        return 0;
+      }
+      const task = this._ensureTask(sdkSessionId, taskId);
+      const added = this._attach(task, snap, 'state');
+      this._applyStatus(task, event);
+      this._applyType(task, event);
+      task.association = association;
+      if (association === 'main-command') {
+        task.mainToolUseId = id(event.mainToolUseId) || id(event.toolUseId) || task.mainToolUseId;
+        this._registerBash(sdkSessionId, null, task.mainToolUseId, task);
+      }
+      return added;
+    }
+    const err = validateBoundState(event, this._scope, sdkSessionId, taskId, existing ? existing.taskType : null);
+    if (err) { this._diag(err, { sdkSessionId, taskId }); return 0; }
+    const ref = createNativeTaskRef(event.taskRef);
+    const refKey = nativeTaskKey(ref);
+    if (existing && existing.association === 'bound') {
+      // An owner, once bound, is immutable: a later different owner is a
+      // diagnosed conflict that changes nothing, never a rewrite.
+      if (existing.ownerRunId !== ref.ownerRunId) {
+        this._diag('owner-conflict', { sdkSessionId, taskId, existing: existing.ownerRunId, incoming: ref.ownerRunId });
+        return 0;
+      }
+    } else {
+      const claimed = this._byRefKey.get(refKey);
+      if (claimed && claimed !== taskKey) { this._diag('owner-ref-collision', { sdkSessionId, taskId }); return 0; }
+    }
+    const task = this._ensureTask(sdkSessionId, taskId);
+    if (task.association !== 'bound') {
+      task.association = 'bound';
+      task.taskRef = ref;
+      task.ownerRunId = ref.ownerRunId;
+      const source = event.owner && typeof event.owner === 'object' ? event.owner : {};
+      task.owner = { ownerBasis: id(source.ownerBasis), launcherKind: id(source.launcherKind), parentNativeAgentId: id(source.parentNativeAgentId), launcherToolUseId: id(source.launcherToolUseId), receiptAgentId: id(source.receiptAgentId) };
+      this._byRefKey.set(refKey, task.taskKey);
+    }
+    const added = this._attach(task, snap, 'state');
+    this._applyStatus(task, event);
+    this._applyType(task, event);
+    this._flushPendingFor(task);
+    return added;
+  }
+
+  // Any explicitly present session/scope field that contradicts the fixed
+  // scope rejects the whole row; absent fields stay absent - the index
+  // never guesses a scope from silence. Returns the conflicting field
+  // name, or null when every explicit field agrees.
+  _explicitScopeConflict(event) {
+    if (event.parentSessionId !== undefined && id(event.parentSessionId) !== this._scope.parentSessionId) return 'parentSessionId';
+    if (event.contextId !== undefined && id(event.contextId) !== this._scope.contextId) return 'contextId';
+    if (event.storeScope !== undefined && id(event.storeScope) !== this._scope.storeScope) return 'storeScope';
+    if (event.scope !== undefined) {
+      if (!event.scope || typeof event.scope !== 'object') return 'scope';
+      if (id(event.scope.storeScope) !== this._scope.storeScope) return 'storeScope';
+      if (id(event.scope.contextId) !== this._scope.contextId) return 'contextId';
+      if (id(event.scope.parentSessionId) !== this._scope.parentSessionId) return 'parentSessionId';
+    }
+    return null;
+  }
+
+  // Child claude/native-trace rows: the actor (nativeAgentId) is the agent
+  // in whose context the event happened - its own tools, its lifecycle
+  // rows and the nested dispatch tools it launched all belong to that
+  // dispatcher. Lifecycle rows (SubagentStart/SubagentStop) legitimately
+  // carry no tool id; tool rows (PreToolUse/PostToolUse) must carry one.
+  // A root Agent/Task PostToolUse receipt only identifies the spawned
+  // agent: it is dispatch metadata for that agent, never the agent's own
+  // executed tool. A Bash fact feeds both the parent agent view and the
+  // command view, keyed by the REAL parent (root explicitly null) so
+  // identical tool ids under different parents never cross; each view
+  // holds the offset exactly once.
+  _observeTrace(event, snap) {
+    if (event.source !== 'sdk-hook') return 0;
+    const sdkSessionId = id(event.sdkSessionId);
+    if (!sdkSessionId) { this._diag('trace-missing-session', {}); return 0; }
+    const conflict = this._explicitScopeConflict(event);
+    if (conflict) {
+      this._diag(conflict === 'parentSessionId' ? 'trace-parent-session-mismatch' : 'trace-scope-mismatch', { sdkSessionId, field: conflict });
+      return 0;
+    }
+    const rawId = id(event.rawToolUseId);
+    const callbackId = id(event.callbackToolUseId);
+    if (rawId && callbackId && rawId !== callbackId) { this._diag('trace-id-mismatch', { sdkSessionId }); return 0; }
+    const toolUseId = rawId || callbackId;
+    const hookEvent = id(event.hookEvent);
+    if ((hookEvent === 'PreToolUse' || hookEvent === 'PostToolUse') && !toolUseId) {
+      this._diag('trace-missing-tool-use-id', { sdkSessionId, hookEvent });
+      return 0;
+    }
+    const actor = id(event.nativeAgentId);
+    const toolName = id(event.toolName);
+    const response = event.toolResponse && typeof event.toolResponse === 'object' ? event.toolResponse : null;
+    const receiptAgentId = response ? id(response.agentId) : null;
+    let added = 0;
+    if (actor) {
+      const taskKey = this._agents.get(tupleKey(sdkSessionId, actor));
+      if (taskKey) added += this._attach(this._tasks.get(taskKey), snap, 'trace');
+      else this._pend(this._pendingTraces, tupleKey(sdkSessionId, actor), snap);
+    } else if (receiptAgentId && AGENT_TOOL_NAMES.has(toolName) && hookEvent === 'PostToolUse') {
+      const taskKey = this._agents.get(tupleKey(sdkSessionId, receiptAgentId));
+      if (taskKey) added += this._attach(this._tasks.get(taskKey), snap, 'dispatch');
+      else this._pend(this._pendingDispatch, tupleKey(sdkSessionId, receiptAgentId), snap);
+    }
+    if (toolName === 'Bash') {
+      if (toolUseId) added += this._attachBash(sdkSessionId, actor, toolUseId, snap);
+      else this._diag('bash-trace-missing-tool-use-id', { sdkSessionId, hookEvent });
+    }
+    return added;
+  }
+
+  // Public-read transcript snapshots (claude/native-task-transcript). The
+  // row attaches to the bound agent task it was read for, routed by the
+  // same trusted (sdkSessionId, agent id) tuple the traces use - for a
+  // bound agent the row's taskId IS the receipt agent id. A transcript row
+  // never creates a task, never claims ownership, never applies a status:
+  // it is content evidence under an ownership someone else already proved.
+  // A row with no binding yet waits pending exactly like a trace row.
+  _observeTranscript(event, snap) {
+    if (event.source !== 'sdk-public-read') return 0;
+    const sdkSessionId = id(event.sdkSessionId);
+    const taskId = id(event.taskId);
+    if (!sdkSessionId || !taskId) { this._diag('transcript-missing-identity', { hasSession: sdkSessionId !== null, hasTask: taskId !== null }); return 0; }
+    const conflict = this._explicitScopeConflict(event);
+    if (conflict) { this._diag('transcript-scope-mismatch', { sdkSessionId, taskId, field: conflict }); return 0; }
+    const taskKey = this._agents.get(tupleKey(sdkSessionId, taskId));
+    if (taskKey) return this._attach(this._tasks.get(taskKey), snap, 'transcript');
+    this._pend(this._pendingTraces, tupleKey(sdkSessionId, taskId), snap);
+    return 0;
+  }
+
+  _attachBash(sdkSessionId, parentNativeAgentId, toolUseId, snap) {
+    const key = tupleKey(sdkSessionId, parentNativeAgentId, toolUseId);
+    const taskKey = this._bashByTool.get(key);
+    if (taskKey) return this._attach(this._tasks.get(taskKey), snap, 'trace');
+    this._pend(this._pendingBash, key, snap);
+    return 0;
+  }
+
+  // Pending rows keep only their immutable snap - offsets, hash and the
+  // routing decision made at observe time. There is deliberately no cap:
+  // an artificially truncated pending set would silently turn a complete
+  // history into an incomplete one.
+  _pend(map, key, snap) {
+    const list = map.get(key) || [];
+    list.push(snap);
+    map.set(key, list);
+    this._pendingRefs++;
+  }
+
+  // Canonical SDK task events (claude/task-*). Their sdkSessionId/taskId
+  // are real facts once present; rows without them are insufficient old
+  // data and never guess an identity. status may be an explicit null from
+  // the reviewed no-fake-success semantics.
+  _observeTaskEvent(event, snap) {
+    const sdkSessionId = id(event.sdkSessionId);
+    const taskId = id(event.taskId);
+    if (!sdkSessionId || !taskId) { this._diag('task-event-missing-identity', { type: event.type }); return 0; }
+    if (id(event.parentSessionId) !== null && event.parentSessionId !== this._scope.parentSessionId) {
+      this._diag('task-event-scope-mismatch', { type: event.type, sdkSessionId, taskId });
+      return 0;
+    }
+    const task = this._ensureTask(sdkSessionId, taskId);
+    this._applyStatus(task, event);
+    if (id(event.taskType) !== null) this._applyType(task, event);
+    return this._attach(task, snap, 'task-event');
+  }
+
+  _applyStatus(task, event) {
+    const raw = id(event.status);
+    const source = id(event.statusSource) || id(event.type);
+    if (raw === null) return;
+    if (!TASK_STATUSES.has(raw)) { this._diag('unknown-task-status', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, raw: raw.slice(0, 40) }); return; }
+    const prior = task.status;
+    if (prior === null) { task.status = raw; task.statusSource = source; return; }
+    if (TERMINAL_STATUSES.has(prior)) {
+      if (!TERMINAL_STATUSES.has(raw)) { this._diag('terminal-no-revival', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, incoming: raw }); return; }
+      if (raw !== prior) { this._diag('terminal-conflict', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, prior, incoming: raw }); return; }
+      return;
+    }
+    task.status = raw; task.statusSource = source;
+  }
+
+  _applyType(task, event) {
+    const taskType = id(event.taskType);
+    if (taskType === null) return;
+    if (task.taskType === null) {
+      task.taskType = taskType;
+      task.taskKind = TASK_KIND_BY_TYPE.get(taskType) || null;
+    } else if (taskType !== task.taskType) {
+      task.typeConflict = true;
+      this._diag('task-type-conflict', { sdkSessionId: task.sdkSessionId, taskId: task.taskId, existing: task.taskType, incoming: taskType });
+    }
+  }
+
+  _ensureTask(sdkSessionId, taskId) {
+    const taskKey = JSON.stringify([sdkSessionId, taskId]);
+    let task = this._tasks.get(taskKey);
+    if (!task) {
+      task = { taskKey, sdkSessionId, taskId, taskKind: null, taskType: null, typeConflict: false, status: null, statusSource: null, association: 'unassigned', taskRef: null, ownerRunId: null, owner: null, mainToolUseId: null, view: new Map() };
+      this._tasks.set(taskKey, task);
+    }
+    return task;
+  }
+
+  _attach(task, snap, role) {
+    if (!task) return 0;
+    let entry = task.view.get(snap.offset);
+    if (!entry) {
+      entry = { offset: snap.offset, endOffset: snap.endOffset, kind: snap.kind, roles: new Set([role]), traceId: snap.traceId, sequence: snap.sequence, hash: snap.hash };
+      task.view.set(snap.offset, entry);
+      this._stats.rowsIndexed++;
+      return 1;
+    }
+    entry.roles.add(role);
+    return 0;
+  }
+
+  _flushPendingFor(task) {
+    if (task.association !== 'bound') return;
+    if (task.taskKind === 'agent' && task.owner && task.owner.receiptAgentId) {
+      const key = tupleKey(task.sdkSessionId, task.owner.receiptAgentId);
+      const claimant = this._agents.get(key);
+      if (claimant && claimant !== task.taskKey) { this._diag('agent-claim-conflict', { sdkSessionId: task.sdkSessionId, agentId: task.owner.receiptAgentId }); return; }
+      this._agents.set(key, task.taskKey);
+      this._flushList(this._pendingTraces, key, task, 'trace');
+      this._flushList(this._pendingDispatch, key, task, 'dispatch');
+    }
+    if (task.taskKind === 'local_bash' && task.owner) {
+      this._registerBash(task.sdkSessionId, task.owner.parentNativeAgentId, task.owner.launcherToolUseId, task);
+    }
+  }
+
+  _flushList(map, key, task, role) {
+    const list = map.get(key);
+    if (!list) return;
+    map.delete(key);
+    this._pendingRefs -= list.length;
+    for (const snap of list) this._attach(task, snap, role);
+  }
+
+  // First real claim on (sdkSessionId, parent nativeAgentId, toolUseId)
+  // wins - a root command claims with an explicit null parent. A different
+  // later claimant is a diagnosed conflict, never a silent re-route.
+  _registerBash(sdkSessionId, parentNativeAgentId, toolUseId, task) {
+    if (!toolUseId) return;
+    const key = tupleKey(sdkSessionId, parentNativeAgentId, toolUseId);
+    const existing = this._bashByTool.get(key);
+    if (existing && existing !== task.taskKey) { this._diag('bash-claim-conflict', { sdkSessionId, parentNativeAgentId, toolUseId }); return; }
+    this._bashByTool.set(key, task.taskKey);
+    this._flushList(this._pendingBash, key, task, 'trace');
+  }
+
+  // Metadata-only task snapshots; historical 'running' is a past
+  // observation and never a claim that a current process is still alive.
+  listTasks() {
+    const out = [];
+    for (const task of this._tasks.values()) {
+      let first = null, last = null;
+      for (const offset of task.view.keys()) {
+        if (first === null || offset < first) first = offset;
+        if (last === null || offset > last) last = offset;
+      }
+      out.push({ sdkSessionId: task.sdkSessionId, taskId: task.taskId, taskKind: task.taskKind, taskType: task.taskType, typeConflict: task.typeConflict === true, status: task.status, statusSource: task.statusSource, association: task.association, taskRef: task.taskRef, ownerRunId: task.ownerRunId, owner: task.owner, mainToolUseId: task.mainToolUseId, rowCount: task.view.size, firstOffset: first, lastOffset: last });
+    }
+    return JSON.parse(JSON.stringify(out));
+  }
+
+  // Internal byte-position pagination over one task's original rows, newest
+  // window first and ascending within a page. `before` is an exclusive raw
+  // offset boundary inside the same file era - NOT a public opaque cursor;
+  // stream sequences are never treated as positions.
+  listOffsets(taskRef, { before, limit } = {}) {
+    const ref = createNativeTaskRef(taskRef);
+    if (!ref) throw Object.assign(new Error('invalid native task reference'), { code: 'INVALID_TASK_REF' });
+    if (!sameTaskScope(ref, this._scope)) throw Object.assign(new Error('task reference scope does not match this index'), { code: 'SCOPE_MISMATCH' });
+    const size = limit === undefined ? DEFAULT_LIMIT : limit;
+    if (!Number.isSafeInteger(size) || size < 1 || size > MAX_LIMIT) throw Object.assign(new Error('limit must be between 1 and ' + MAX_LIMIT), { code: 'INVALID_LIMIT' });
+    let bound = null;
+    if (before !== undefined && before !== null) {
+      if (!Number.isSafeInteger(before) || before <= 0) throw Object.assign(new Error('invalid before offset'), { code: 'INVALID_BEFORE' });
+      bound = before;
+    }
+    const taskKey = this._byRefKey.get(nativeTaskKey(ref));
+    if (!taskKey) return { entries: [], nextBefore: null };
+    const task = this._tasks.get(taskKey);
+    const offsets = [...task.view.keys()].sort((a, b) => a - b).filter(offset => bound === null || offset < bound);
+    const start = Math.max(0, offsets.length - size);
+    const page = offsets.slice(start);
+    return { entries: page.map(offset => this._entrySnapshot(task.view.get(offset))), nextBefore: start > 0 && page.length > 0 ? page[0] : null };
+  }
+
+  _entrySnapshot(entry) {
+    return { offset: entry.offset, endOffset: entry.endOffset, kind: entry.kind, roles: [...entry.roles].sort(), traceId: entry.traceId, sequence: entry.sequence, hash: entry.hash };
+  }
+
+  stats() {
+    let bound = 0;
+    for (const task of this._tasks.values()) if (task.association === 'bound') bound++;
+    return { ...this._stats, tasksTotal: this._tasks.size, tasksBound: bound, tasksUnassigned: this._tasks.size - bound, pendingRefs: this._pendingRefs };
+  }
+
+  _diag(code, ids) {
+    this._stats.diagnostics++;
+    const signature = code + '|' + JSON.stringify(ids || {});
+    if (this._diagSeen.has(signature)) return;
+    if (this._diagSeen.size >= MAX_SEEN_SIGNATURES) return;
+    this._diagSeen.add(signature);
+    if (this._diagnostics.length >= MAX_DIAGNOSTICS) return;
+    this._diagnostics.push(Object.assign({ code }, ids || {}));
+  }
+}
+
+module.exports = { NativeTaskHistoryIndex };