@sanqianx/claude-ai-workbench 0.13.2 → 0.13.4

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

@@ -1,217 +1,217 @@
-'use strict';
-
-// Native task control - the trusted first-stage coordinator deciding
-// whether ONE native background task may receive a targeted stop through a
-// CURRENT SDK query lease. It owns no transport and invents no facts: the
-// runner supplies three explicit trusted synchronous callbacks (live task
-// lookup, SDK query lease lookup, durability verdict) and this module only
-// combines their answers into one short receipt per stop request. Every
-// non-satisfiable case is an explicit rejection code - there is
-// deliberately NO fallback to session.abort, transport.close or stopping
-// the parent session. Receipts carry only fixed safe codes, short detail
-// tags and identity fields: upstream exception text is never copied into
-// a receipt (truncation is not redaction), a callback that throws or
-// answers asynchronously resolves an explicit unavailable receipt instead
-// of rejecting the stop() promise, and the task a lookup returns is
-// verified against the requested ref (taskId, ownerRunId, taskRef, SDK
-// session, kind/type) before any SDK call, so one broken lookup can never
-// widen into stopping a different task. This is not yet a product stop
-// API: runner, Service and API wiring is a later stage; unit tests use
-// fixtures and are not a real-SDK proof.
-
-const { createTaskScope, createNativeTaskRef, sameTaskScope } = require('./task-identity');
-
-const CONTROLLED_KINDS = new Set(['agent', 'local_bash']);
-// Mirrors TASK_KIND_BY_TYPE in the registry: a bound task's kind is
-// derived from its type there, so an inconsistent kind/type pair here can
-// only come from a broken lookup and must never reach the SDK.
-const KIND_BY_TYPE = new Map([['local_agent', 'agent'], ['local_bash', 'local_bash']]);
-const STOPPABLE_STATUSES = new Set(['pending', 'running']);
-const TERMINAL_STATUSES = new Set(['completed', 'failed', 'stopped']);
-const MAX_REQUEST_ID_LENGTH = 200;
-
-function id(value) { return typeof value === 'string' && value.trim() !== '' ? value : null; }
-function freeze(receipt) { return Object.freeze(receipt); }
-function own(object, key) { return Object.prototype.hasOwnProperty.call(object, key); }
-function isThenable(value) {
-  return !!value && (typeof value === 'object' || typeof value === 'function') && typeof value.then === 'function';
-}
-
-// The canonical owner tuple embedded in an ownerRunId. Anything that does
-// not parse back to ['sdk-launch', 1, sdkSessionId, parent, toolUseId]
-// cannot be identity-verified against a live task.
-function ownerTuple(ownerRunId) {
-  let tuple = null;
-  try { tuple = JSON.parse(ownerRunId); } catch (error) { return null; }
-  if (!Array.isArray(tuple) || tuple.length !== 5) return null;
-  if (tuple[0] !== 'sdk-launch' || tuple[1] !== 1) return null;
-  if (!id(tuple[2])) return null;
-  return tuple;
-}
-
-// Verifies that the object a trusted lookup returned really IS the task
-// the caller asked to stop. Own (not inherited) identity fields, matching
-// taskId / ownerRunId / taskRef, the SDK session embedded in the owner
-// tuple and kind/type compatibility are all required; any doubt becomes a
-// fixed detail tag and the stop is refused before the SDK is touched.
-function targetMismatch(ref, task) {
-  for (const key of ['taskId', 'sdkSessionId', 'ownerRunId', 'taskRef', 'taskKind', 'taskType']) {
-    if (!own(task, key)) return 'task-shape';
-  }
-  if (task.taskId !== ref.taskId) return 'task-id';
-  if (task.ownerRunId !== ref.ownerRunId) return 'owner-run';
-  const tuple = ownerTuple(ref.ownerRunId);
-  if (!tuple) return 'owner-run';
-  if (task.sdkSessionId !== tuple[2]) return 'sdk-session';
-  const taskRef = task.taskRef;
-  if (!taskRef || typeof taskRef !== 'object' || Array.isArray(taskRef)) return 'task-ref';
-  for (const key of ['kind', 'storeScope', 'contextId', 'parentSessionId', 'ownerRunId', 'taskId']) {
-    if (!own(taskRef, key)) return 'task-ref';
-  }
-  if (taskRef.kind !== ref.kind || taskRef.taskId !== ref.taskId || taskRef.ownerRunId !== ref.ownerRunId) return 'task-ref';
-  if (taskRef.storeScope !== ref.storeScope || taskRef.contextId !== ref.contextId || taskRef.parentSessionId !== ref.parentSessionId) return 'task-ref';
-  if (KIND_BY_TYPE.get(task.taskType) !== task.taskKind) return 'kind-type';
-  if (id(task.toolUseId) && tuple[4] !== task.toolUseId) return 'tool-use';
-  return null;
-}
-
-function createNativeTaskControl({ scope, runtimeEpoch, getLiveTask, getLease, isDurable } = {}) {
-  const fixedScope = createTaskScope(scope);
-  if (!fixedScope) throw new Error('createNativeTaskControl requires a fixed TaskScope');
-  if (!id(runtimeEpoch)) throw new Error('createNativeTaskControl requires a runtimeEpoch string');
-  // No default allow: every trusted callback must be supplied explicitly.
-  if (typeof getLiveTask !== 'function' || typeof getLease !== 'function' || typeof isDurable !== 'function') {
-    throw new Error('createNativeTaskControl requires explicit getLiveTask, getLease and isDurable functions');
-  }
-  const epoch = runtimeEpoch;
-  const frozenScope = Object.freeze({ storeScope: fixedScope.storeScope, contextId: fixedScope.contextId, parentSessionId: fixedScope.parentSessionId });
-  // requestId -> { payload, promise }: an id is bound to the full request
-  // payload (fixed scope + canonical ref + epoch). The same id replays the
-  // same result - in flight or settled, including deterministic failure
-  // receipts - and a different payload under the same id is a diagnosed
-  // conflict, never a second dispatch.
-  const requests = new Map();
-  // (epoch, scope, ref, leaseId) -> send receipt promise: the same lease
-  // and ref receive at most ONE SDK stopTask call whatever the requestIds;
-  // both 'requested' and 'unknown' outcomes stay cached. A later real
-  // terminal is only ever produced by independent SDK facts.
-  const sentStops = new Map();
-
-  function rejected(code, extra) {
-    return freeze(Object.assign({ ok: false, code }, extra || {}));
-  }
-
-  // Runs one trusted synchronous callback under the protocol contract. A
-  // throw, or a thenable answer that breaks the synchronous contract,
-  // becomes a fixed unavailable receipt: the exception text is dropped,
-  // stop() still resolves, the SDK is never called, and the answer is
-  // cached per requestId like any deterministic result - never swallowed
-  // into ok or stopped.
-  function syncAnswer(invoke, code, identity) {
-    let value;
-    try {
-      value = invoke();
-    } catch (error) {
-      return { failed: rejected(code, identity) };
-    }
-    if (isThenable(value)) return { failed: rejected(code, identity) };
-    return { value };
-  }
-
-  async function execute(ref, requestId) {
-    const lookedUp = syncAnswer(() => getLiveTask(ref), 'live-lookup-failed', { requestId });
-    if (lookedUp.failed) return lookedUp.failed;
-    const task = lookedUp.value;
-    if (!task || typeof task !== 'object' || Array.isArray(task)) return rejected('task-not-live', { requestId });
-    const identity = { requestId, taskId: task.taskId, sdkSessionId: task.sdkSessionId };
-    if (task.association === 'main-command') return rejected('task-main-command', identity);
-    if (task.association !== 'bound') return rejected('task-unassigned', identity);
-    if (task.typeConflict === true) return rejected('task-type-conflict', identity);
-    if (!CONTROLLED_KINDS.has(task.taskKind)) return rejected('task-kind-unknown', identity);
-    const mismatch = targetMismatch(ref, task);
-    if (mismatch) return rejected('task-target-mismatch', { requestId, taskId: ref.taskId, detail: mismatch });
-    if (TERMINAL_STATUSES.has(task.status)) {
-      // A terminal established by real SDK facts needs no SDK call at all.
-      return freeze(Object.assign({ ok: true, outcome: 'already-terminal', status: task.status, statusSource: task.statusSource || null, stopTaskSent: false }, identity));
-    }
-    if (!STOPPABLE_STATUSES.has(task.status)) return rejected('task-status-unknown', identity);
-    const durability = syncAnswer(() => isDurable(ref, task), 'durability-unavailable', identity);
-    if (durability.failed) return durability.failed;
-    if (durability.value !== true) return rejected('durability-insufficient', identity);
-    const leased = syncAnswer(() => getLease(task.sdkSessionId), 'lease-unavailable', identity);
-    if (leased.failed) return leased.failed;
-    const lease = leased.value;
-    if (!lease || typeof lease !== 'object' || Array.isArray(lease)) return rejected('lease-not-found', identity);
-    const leaseId = id(lease.leaseId);
-    if (lease.active !== true) return rejected('lease-inactive', Object.assign({ leaseId }, identity));
-    if (id(lease.sdkSessionId) !== task.sdkSessionId) return rejected('lease-session-mismatch', Object.assign({ leaseId }, identity));
-    if (!leaseId) return rejected('lease-invalid', identity);
-    // Lease identity fields must be the lease's own data: an object that
-    // only inherits sdkSessionId/leaseId/active/query from a prototype (or
-    // smuggles them through a promise-like shape) is never a real lease.
-    for (const key of ['leaseId', 'active', 'sdkSessionId', 'query']) {
-      if (!own(lease, key)) return rejected('lease-invalid', Object.assign({ leaseId }, identity));
-    }
-    if (!lease.query || typeof lease.query !== 'object' || typeof lease.query.stopTask !== 'function') {
-      return rejected('lease-handle-invalid', Object.assign({ leaseId }, identity));
-    }
-    const stopKey = JSON.stringify([epoch, frozenScope.storeScope, frozenScope.contextId, frozenScope.parentSessionId, ref.ownerRunId, ref.taskId, leaseId]);
-    let entry = sentStops.get(stopKey);
-    if (!entry) {
-      // Exactly one SDK call per lease+ref, invoked as a method so `this`
-      // is the real query object. The RPC resolving only proves the
-      // request left: the task status itself is never rewritten here, and
-      // a rejection is kept as an unknown outcome with NO upstream error
-      // text - receipts expose only this module's fixed codes.
-      const send = (async () => {
-        try {
-          await lease.query.stopTask(task.taskId);
-          return freeze({ ok: true, outcome: 'requested', stopTaskSent: true });
-        } catch (error) {
-          return freeze({ ok: false, outcome: 'unknown', code: 'stop-rejected', stopTaskSent: true });
-        }
-      })();
-      entry = { promise: send };
-      sentStops.set(stopKey, entry);
-      const base = await entry.promise;
-      return freeze(Object.assign({ leaseId, deduped: false }, base, identity));
-    }
-    const base = await entry.promise;
-    return freeze(Object.assign({ leaseId, deduped: true }, base, identity));
-  }
-
-  // Receipts always resolve (never throw): every unsatisfiable case is a
-  // short receipt with an explicit code and no upstream text, and even
-  // hostile property getters on the stop arguments cannot turn stop() into
-  // a rejected promise. Callers get a fresh copy per call, so mutating a
-  // returned receipt cannot rewrite the stored one.
-  function stop(args) {
-    let ref = null;
-    let requestId = null;
-    try {
-      if (!args || typeof args !== 'object') return Promise.resolve(rejected('request-invalid', { detail: 'stop-args' }));
-      ref = createNativeTaskRef(args.taskRef);
-      if (!ref) return Promise.resolve(rejected('request-invalid', { detail: 'taskRef' }));
-      requestId = args.requestId;
-      if (!id(requestId) || requestId.length > MAX_REQUEST_ID_LENGTH) return Promise.resolve(rejected('request-invalid', { detail: 'requestId' }));
-      if (!sameTaskScope(ref, frozenScope)) return Promise.resolve(rejected('ref-scope-mismatch', { requestId }));
-      if (!id(args.runtimeEpoch)) return Promise.resolve(rejected('request-invalid', { requestId, detail: 'runtimeEpoch' }));
-      if (args.runtimeEpoch !== epoch) return Promise.resolve(rejected('epoch-mismatch', { requestId }));
-    } catch (error) {
-      return Promise.resolve(rejected('request-invalid', { detail: 'stop-args' }));
-    }
-    const payload = JSON.stringify([frozenScope.storeScope, frozenScope.contextId, frozenScope.parentSessionId, ref.ownerRunId, ref.taskId, epoch]);
-    const existing = requests.get(requestId);
-    if (existing) {
-      if (existing.payload !== payload) return Promise.resolve(rejected('request-conflict', { requestId }));
-      return existing.promise.then(receipt => ({ ...receipt }));
-    }
-    const promise = execute(ref, requestId);
-    requests.set(requestId, { payload, promise });
-    return promise.then(receipt => ({ ...receipt }));
-  }
-
-  return { stop };
-}
-
-module.exports = { createNativeTaskControl };
+'use strict';
+
+// Native task control - the trusted first-stage coordinator deciding
+// whether ONE native background task may receive a targeted stop through a
+// CURRENT SDK query lease. It owns no transport and invents no facts: the
+// runner supplies three explicit trusted synchronous callbacks (live task
+// lookup, SDK query lease lookup, durability verdict) and this module only
+// combines their answers into one short receipt per stop request. Every
+// non-satisfiable case is an explicit rejection code - there is
+// deliberately NO fallback to session.abort, transport.close or stopping
+// the parent session. Receipts carry only fixed safe codes, short detail
+// tags and identity fields: upstream exception text is never copied into
+// a receipt (truncation is not redaction), a callback that throws or
+// answers asynchronously resolves an explicit unavailable receipt instead
+// of rejecting the stop() promise, and the task a lookup returns is
+// verified against the requested ref (taskId, ownerRunId, taskRef, SDK
+// session, kind/type) before any SDK call, so one broken lookup can never
+// widen into stopping a different task. This is not yet a product stop
+// API: runner, Service and API wiring is a later stage; unit tests use
+// fixtures and are not a real-SDK proof.
+
+const { createTaskScope, createNativeTaskRef, sameTaskScope } = require('./task-identity');
+
+const CONTROLLED_KINDS = new Set(['agent', 'local_bash']);
+// Mirrors TASK_KIND_BY_TYPE in the registry: a bound task's kind is
+// derived from its type there, so an inconsistent kind/type pair here can
+// only come from a broken lookup and must never reach the SDK.
+const KIND_BY_TYPE = new Map([['local_agent', 'agent'], ['local_bash', 'local_bash']]);
+const STOPPABLE_STATUSES = new Set(['pending', 'running']);
+const TERMINAL_STATUSES = new Set(['completed', 'failed', 'stopped']);
+const MAX_REQUEST_ID_LENGTH = 200;
+
+function id(value) { return typeof value === 'string' && value.trim() !== '' ? value : null; }
+function freeze(receipt) { return Object.freeze(receipt); }
+function own(object, key) { return Object.prototype.hasOwnProperty.call(object, key); }
+function isThenable(value) {
+  return !!value && (typeof value === 'object' || typeof value === 'function') && typeof value.then === 'function';
+}
+
+// The canonical owner tuple embedded in an ownerRunId. Anything that does
+// not parse back to ['sdk-launch', 1, sdkSessionId, parent, toolUseId]
+// cannot be identity-verified against a live task.
+function ownerTuple(ownerRunId) {
+  let tuple = null;
+  try { tuple = JSON.parse(ownerRunId); } catch (error) { return null; }
+  if (!Array.isArray(tuple) || tuple.length !== 5) return null;
+  if (tuple[0] !== 'sdk-launch' || tuple[1] !== 1) return null;
+  if (!id(tuple[2])) return null;
+  return tuple;
+}
+
+// Verifies that the object a trusted lookup returned really IS the task
+// the caller asked to stop. Own (not inherited) identity fields, matching
+// taskId / ownerRunId / taskRef, the SDK session embedded in the owner
+// tuple and kind/type compatibility are all required; any doubt becomes a
+// fixed detail tag and the stop is refused before the SDK is touched.
+function targetMismatch(ref, task) {
+  for (const key of ['taskId', 'sdkSessionId', 'ownerRunId', 'taskRef', 'taskKind', 'taskType']) {
+    if (!own(task, key)) return 'task-shape';
+  }
+  if (task.taskId !== ref.taskId) return 'task-id';
+  if (task.ownerRunId !== ref.ownerRunId) return 'owner-run';
+  const tuple = ownerTuple(ref.ownerRunId);
+  if (!tuple) return 'owner-run';
+  if (task.sdkSessionId !== tuple[2]) return 'sdk-session';
+  const taskRef = task.taskRef;
+  if (!taskRef || typeof taskRef !== 'object' || Array.isArray(taskRef)) return 'task-ref';
+  for (const key of ['kind', 'storeScope', 'contextId', 'parentSessionId', 'ownerRunId', 'taskId']) {
+    if (!own(taskRef, key)) return 'task-ref';
+  }
+  if (taskRef.kind !== ref.kind || taskRef.taskId !== ref.taskId || taskRef.ownerRunId !== ref.ownerRunId) return 'task-ref';
+  if (taskRef.storeScope !== ref.storeScope || taskRef.contextId !== ref.contextId || taskRef.parentSessionId !== ref.parentSessionId) return 'task-ref';
+  if (KIND_BY_TYPE.get(task.taskType) !== task.taskKind) return 'kind-type';
+  if (id(task.toolUseId) && tuple[4] !== task.toolUseId) return 'tool-use';
+  return null;
+}
+
+function createNativeTaskControl({ scope, runtimeEpoch, getLiveTask, getLease, isDurable } = {}) {
+  const fixedScope = createTaskScope(scope);
+  if (!fixedScope) throw new Error('createNativeTaskControl requires a fixed TaskScope');
+  if (!id(runtimeEpoch)) throw new Error('createNativeTaskControl requires a runtimeEpoch string');
+  // No default allow: every trusted callback must be supplied explicitly.
+  if (typeof getLiveTask !== 'function' || typeof getLease !== 'function' || typeof isDurable !== 'function') {
+    throw new Error('createNativeTaskControl requires explicit getLiveTask, getLease and isDurable functions');
+  }
+  const epoch = runtimeEpoch;
+  const frozenScope = Object.freeze({ storeScope: fixedScope.storeScope, contextId: fixedScope.contextId, parentSessionId: fixedScope.parentSessionId });
+  // requestId -> { payload, promise }: an id is bound to the full request
+  // payload (fixed scope + canonical ref + epoch). The same id replays the
+  // same result - in flight or settled, including deterministic failure
+  // receipts - and a different payload under the same id is a diagnosed
+  // conflict, never a second dispatch.
+  const requests = new Map();
+  // (epoch, scope, ref, leaseId) -> send receipt promise: the same lease
+  // and ref receive at most ONE SDK stopTask call whatever the requestIds;
+  // both 'requested' and 'unknown' outcomes stay cached. A later real
+  // terminal is only ever produced by independent SDK facts.
+  const sentStops = new Map();
+
+  function rejected(code, extra) {
+    return freeze(Object.assign({ ok: false, code }, extra || {}));
+  }
+
+  // Runs one trusted synchronous callback under the protocol contract. A
+  // throw, or a thenable answer that breaks the synchronous contract,
+  // becomes a fixed unavailable receipt: the exception text is dropped,
+  // stop() still resolves, the SDK is never called, and the answer is
+  // cached per requestId like any deterministic result - never swallowed
+  // into ok or stopped.
+  function syncAnswer(invoke, code, identity) {
+    let value;
+    try {
+      value = invoke();
+    } catch (error) {
+      return { failed: rejected(code, identity) };
+    }
+    if (isThenable(value)) return { failed: rejected(code, identity) };
+    return { value };
+  }
+
+  async function execute(ref, requestId) {
+    const lookedUp = syncAnswer(() => getLiveTask(ref), 'live-lookup-failed', { requestId });
+    if (lookedUp.failed) return lookedUp.failed;
+    const task = lookedUp.value;
+    if (!task || typeof task !== 'object' || Array.isArray(task)) return rejected('task-not-live', { requestId });
+    const identity = { requestId, taskId: task.taskId, sdkSessionId: task.sdkSessionId };
+    if (task.association === 'main-command') return rejected('task-main-command', identity);
+    if (task.association !== 'bound') return rejected('task-unassigned', identity);
+    if (task.typeConflict === true) return rejected('task-type-conflict', identity);
+    if (!CONTROLLED_KINDS.has(task.taskKind)) return rejected('task-kind-unknown', identity);
+    const mismatch = targetMismatch(ref, task);
+    if (mismatch) return rejected('task-target-mismatch', { requestId, taskId: ref.taskId, detail: mismatch });
+    if (TERMINAL_STATUSES.has(task.status)) {
+      // A terminal established by real SDK facts needs no SDK call at all.
+      return freeze(Object.assign({ ok: true, outcome: 'already-terminal', status: task.status, statusSource: task.statusSource || null, stopTaskSent: false }, identity));
+    }
+    if (!STOPPABLE_STATUSES.has(task.status)) return rejected('task-status-unknown', identity);
+    const durability = syncAnswer(() => isDurable(ref, task), 'durability-unavailable', identity);
+    if (durability.failed) return durability.failed;
+    if (durability.value !== true) return rejected('durability-insufficient', identity);
+    const leased = syncAnswer(() => getLease(task.sdkSessionId), 'lease-unavailable', identity);
+    if (leased.failed) return leased.failed;
+    const lease = leased.value;
+    if (!lease || typeof lease !== 'object' || Array.isArray(lease)) return rejected('lease-not-found', identity);
+    const leaseId = id(lease.leaseId);
+    if (lease.active !== true) return rejected('lease-inactive', Object.assign({ leaseId }, identity));
+    if (id(lease.sdkSessionId) !== task.sdkSessionId) return rejected('lease-session-mismatch', Object.assign({ leaseId }, identity));
+    if (!leaseId) return rejected('lease-invalid', identity);
+    // Lease identity fields must be the lease's own data: an object that
+    // only inherits sdkSessionId/leaseId/active/query from a prototype (or
+    // smuggles them through a promise-like shape) is never a real lease.
+    for (const key of ['leaseId', 'active', 'sdkSessionId', 'query']) {
+      if (!own(lease, key)) return rejected('lease-invalid', Object.assign({ leaseId }, identity));
+    }
+    if (!lease.query || typeof lease.query !== 'object' || typeof lease.query.stopTask !== 'function') {
+      return rejected('lease-handle-invalid', Object.assign({ leaseId }, identity));
+    }
+    const stopKey = JSON.stringify([epoch, frozenScope.storeScope, frozenScope.contextId, frozenScope.parentSessionId, ref.ownerRunId, ref.taskId, leaseId]);
+    let entry = sentStops.get(stopKey);
+    if (!entry) {
+      // Exactly one SDK call per lease+ref, invoked as a method so `this`
+      // is the real query object. The RPC resolving only proves the
+      // request left: the task status itself is never rewritten here, and
+      // a rejection is kept as an unknown outcome with NO upstream error
+      // text - receipts expose only this module's fixed codes.
+      const send = (async () => {
+        try {
+          await lease.query.stopTask(task.taskId);
+          return freeze({ ok: true, outcome: 'requested', stopTaskSent: true });
+        } catch (error) {
+          return freeze({ ok: false, outcome: 'unknown', code: 'stop-rejected', stopTaskSent: true });
+        }
+      })();
+      entry = { promise: send };
+      sentStops.set(stopKey, entry);
+      const base = await entry.promise;
+      return freeze(Object.assign({ leaseId, deduped: false }, base, identity));
+    }
+    const base = await entry.promise;
+    return freeze(Object.assign({ leaseId, deduped: true }, base, identity));
+  }
+
+  // Receipts always resolve (never throw): every unsatisfiable case is a
+  // short receipt with an explicit code and no upstream text, and even
+  // hostile property getters on the stop arguments cannot turn stop() into
+  // a rejected promise. Callers get a fresh copy per call, so mutating a
+  // returned receipt cannot rewrite the stored one.
+  function stop(args) {
+    let ref = null;
+    let requestId = null;
+    try {
+      if (!args || typeof args !== 'object') return Promise.resolve(rejected('request-invalid', { detail: 'stop-args' }));
+      ref = createNativeTaskRef(args.taskRef);
+      if (!ref) return Promise.resolve(rejected('request-invalid', { detail: 'taskRef' }));
+      requestId = args.requestId;
+      if (!id(requestId) || requestId.length > MAX_REQUEST_ID_LENGTH) return Promise.resolve(rejected('request-invalid', { detail: 'requestId' }));
+      if (!sameTaskScope(ref, frozenScope)) return Promise.resolve(rejected('ref-scope-mismatch', { requestId }));
+      if (!id(args.runtimeEpoch)) return Promise.resolve(rejected('request-invalid', { requestId, detail: 'runtimeEpoch' }));
+      if (args.runtimeEpoch !== epoch) return Promise.resolve(rejected('epoch-mismatch', { requestId }));
+    } catch (error) {
+      return Promise.resolve(rejected('request-invalid', { detail: 'stop-args' }));
+    }
+    const payload = JSON.stringify([frozenScope.storeScope, frozenScope.contextId, frozenScope.parentSessionId, ref.ownerRunId, ref.taskId, epoch]);
+    const existing = requests.get(requestId);
+    if (existing) {
+      if (existing.payload !== payload) return Promise.resolve(rejected('request-conflict', { requestId }));
+      return existing.promise.then(receipt => ({ ...receipt }));
+    }
+    const promise = execute(ref, requestId);
+    requests.set(requestId, { payload, promise });
+    return promise.then(receipt => ({ ...receipt }));
+  }
+
+  return { stop };
+}
+
+module.exports = { createNativeTaskControl };