@awak-app/simy-cli 0.7.10 → 0.7.12

package/src/codex-plugins/simy/hooks/update-dispatch-gate.mjs

@@ -0,0 +1,326 @@
+import { mkdirSync, realpathSync, readFileSync, readdirSync, unlinkSync } from 'node:fs';
+import { registerDispatchProvenance, normalizeDispatchIdentity } from './update-dispatch-identity.mjs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { readState, createStateStore, atomicSave, withLock, acquireLock, fail, digest, isMap, CONNECTION_STATES } from './update-state-store.mjs';
+
+export const DISPATCH_PROTOCOL = 3;
+export const DISPATCH_MODULE_DIGEST = createHash('sha256').update(readFileSync(new URL(import.meta.url))).digest('hex');
+export const detachmentRoot = () => resolve(process.env.SIMY_HOME?.trim() || join(homedir(), '.simy'));
+export const rootFromDelivery = root => basename(resolve(root)) === 'delivery-hooks' ? dirname(resolve(root)) : resolve(root);
+const path = root => join(resolve(root), 'update-detachment', 'gate.json');
+function read(root) {
+  const state = readState(path(root), { versions: [1, 2] }) || { schemaVersion: 1, revision: 0, generation: 0, connection: 'connected', attempts: {}, receipts: {}, events: {} };
+  if (!Number.isSafeInteger(state.generation) || !Number.isSafeInteger(state.revision) || !CONNECTION_STATES.includes(state.connection) || !['attempts', 'receipts', 'events'].every(key => isMap(state[key])) || (state.hookOwners !== undefined && !isMap(state.hookOwners)) || !Object.values(state.attempts).every(attempt => isMap(attempt) && typeof attempt.id === 'string' && Number.isSafeInteger(attempt.generation) && ['intent','sending','sent','provider_identified','result_saved','confirmed'].includes(attempt.phase))) fail('invalid_state');
+  if ((state.schemaVersion === 2 && ![2, 3].includes(state.minimumDispatchProtocol)) || (state.minimumDispatchProtocol !== undefined && ![2, 3].includes(state.minimumDispatchProtocol))) fail('writer_protocol_incompatible');
+  validateTaskFences(state, root);
+  return state;
+}
+const owners = new Map();
+export function captureDispatchOwner(root = detachmentRoot()) {
+  mkdirSync(root, { recursive: true, mode: 0o700 }); root = realpathSync(root); const state = read(root);
+  if (!owners.has(root)) owners.set(root, Object.freeze({ root, generation: state.generation, protocol: DISPATCH_PROTOCOL }));
+  return owners.get(root);
+}
+export function readDispatchGate(root = detachmentRoot()) { return read(root); }
+export function transitionConnection({ root = detachmentRoot(), expectedRevision, connection, eventId }) {
+  return withLock(path(root), () => {
+    const state = read(root);
+    if (eventId && state.events[digest(eventId)]) return state;
+    if (state.revision !== expectedRevision) fail('revision_conflict');
+    const allowed = { connected: ['detaching'], ready: ['connected', 'detaching'], detaching: ['detached', 'recovery_required'], detached: ['reconciling'], reconciling: ['ready', 'recovery_required'], recovery_required: ['reconciling', 'detaching'] };
+    if (!allowed[state.connection]?.includes(connection)) fail('invalid_transition');
+    if (connection === 'detaching') { state.generation++; state.schemaVersion = 2; state.minimumDispatchProtocol = DISPATCH_PROTOCOL; }
+    state.connection = connection; state.revision++;
+    if (eventId) state.events[digest(eventId)] = { revision: state.revision };
+    atomicSave(path(root), state); return state;
+  });
+}
+function applyReceipt(state, { attemptId, receiptId, providerExecutionId = null, resultRef = null }) {
+  if (![attemptId, receiptId].every(value => typeof value === 'string' && value.length > 0 && value.length <= 1024) || [providerExecutionId, resultRef].some(value => value !== null && (typeof value !== 'string' || !value || value.length > 2048))) fail('receipt_invalid');
+  const attempt = state.attempts[digest(attemptId)]; if (!attempt) fail('attempt_unknown');
+  const key = digest(receiptId), prior = state.receipts[key];
+  if (prior) { if (prior.attemptId !== attemptId || prior.providerExecutionId !== providerExecutionId || prior.resultRef !== resultRef) fail('receipt_conflict'); return false; }
+  state.receipts[key] = { attemptId, providerExecutionId, resultRef, generation: attempt.generation };
+  if (attempt.phase !== 'confirmed' && (resultRef || attempt.phase !== 'result_saved')) attempt.phase = resultRef ? 'result_saved' : 'provider_identified';
+  return true;
+}
+export function recordDispatchReceipt({ root = detachmentRoot(), ...receipt }) {
+  return withLock(path(root), () => {
+    const state = read(root);
+    if (applyReceipt(state, receipt)) { state.revision++; atomicSave(path(root), state); }
+    return state;
+  });
+}
+export function queueDispatchReceipt({ root = detachmentRoot(), ...receipt }) {
+  // Validate without mutating the live ledger before persisting intake.
+  applyReceipt(structuredClone(read(root)), receipt);
+  const item = { schemaVersion: 1, kind: 'receipt', ...receipt };
+  atomicSave(join(root, 'update-detachment', 'intake', `${digest(item)}.json`), item);
+  try { return flushDispatchIntake(root); } catch (error) { if (error.code !== 'state_busy') throw error; return null; }
+}
+export function confirmDispatch({ root = detachmentRoot(), attemptId }) {
+  return withLock(path(root), () => { const state = read(root), attempt = state.attempts[digest(attemptId)];
+    if (!attempt || !Object.values(state.receipts).some(item => item.attemptId === attemptId && item.resultRef)) fail('result_required');
+    attempt.phase = 'confirmed'; state.revision++; atomicSave(path(root), state); return state; });
+}
+export function dispatchWithFence(owner, { taskId, attemptId = randomUUID(), identity = null, provenance = null }, send) {
+  if (!owner || typeof send !== 'function' || typeof taskId !== 'string' || !taskId || typeof attemptId !== 'string' || !attemptId) fail('dispatch_identity_required');
+  return withLock(path(owner.root), () => {
+    const state = read(owner.root);
+    if (!['connected', 'ready'].includes(state.connection)) fail('dispatch_detached');
+    if (state.minimumDispatchProtocol && (owner.protocol !== DISPATCH_PROTOCOL || owner.protocol < state.minimumDispatchProtocol)) fail('writer_protocol_incompatible');
+    if (owner.generation !== state.generation) fail('owner_fenced');
+    if (provenance?.identity) identity = registerDispatchProvenance(provenance);
+    else if (identity) identity = normalizeDispatchIdentity(identity);
+    if (identity && identity.root !== resolve(owner.root)) fail('identity_root_mismatch');
+    assertTaskAdmissionState(state, { taskId, identity });
+    const key = digest(attemptId); if (Object.hasOwn(state.attempts, key)) fail('attempt_already_recorded');
+    state.attempts[key] = { id: attemptId, taskHash: digest(taskId), identityHash: identity ? digest(identity) : null, ...(provenance ? { provenance: { taskId: provenance.taskId, recordRef: provenance.recordRef, context: provenance.context, providerSession: provenance.providerSession }, identityStatus: identity ? 'bound' : provenance.context.account && provenance.context.device ? 'awaiting_provider_session' : 'unavailable' } : {}), generation: state.generation, phase: 'intent' };
+    state.revision++; atomicSave(path(owner.root), state);
+    state.attempts[key].phase = 'sending'; state.revision++; atomicSave(path(owner.root), state);
+    // Initiation must be synchronous: no await may separate this check and the
+    // transport write/spawn. Promise completion belongs to the result intake.
+    const value = send(attemptId);
+    return value;
+  }, { preserveResult: true });
+}
+
+// Hook state evaluation and stdout emission share the update barrier. Lifecycle
+// intake continues while detached, but it must not consume continuation budgets.
+export async function fenceHook(owner, taskId, evaluate, emit = null, beforeEmit = () => true, dispatchContext = () => null) {
+  const release = acquireLock(path(owner.root));
+  try {
+    const state = read(owner.root);
+    const initialContext = dispatchContext();
+    let admitted = true;
+    try { assertTaskAdmissionState(state, { taskId: initialContext?.taskId || taskId, identity: initialContext?.identity || initialContext?.provenance?.identity }); }
+    catch (error) { if (!['task_admission_blocked', 'task_admission_identity_required'].includes(error.code)) throw error; admitted = false; }
+    const allowed = admitted && ['connected', 'ready'].includes(state.connection) && owner.generation === state.generation && (!state.minimumDispatchProtocol || owner.protocol === DISPATCH_PROTOCOL);
+    const output = await evaluate(!allowed);
+    if (!allowed) { if (emit) emit({}); return {}; }
+    if (output?.decision === 'block') {
+      const context = dispatchContext(), attemptId = context?.attemptId || randomUUID();
+      const identity = context?.provenance?.identity ? registerDispatchProvenance(context.provenance) : null;
+      assertTaskAdmissionState(state, { taskId: context?.taskId || taskId, identity });
+      if (state.attempts[digest(attemptId)]) fail('attempt_already_recorded');
+      state.attempts[digest(attemptId)] = { id: attemptId, taskHash: digest(context?.taskId || taskId), identityHash: identity ? digest(identity) : null, generation: state.generation, phase: 'sending' };
+      state.revision++; atomicSave(path(owner.root), state);
+    }
+    if (!beforeEmit()) { if (emit) emit({}); return {}; }
+    if (emit) emit(output);
+    return output;
+  } finally { release(); }
+}
+
+// The provider remains live while hook invocations launch new Node processes.
+// Bind its session to the first observed generation durably, not to hook PID.
+export function captureHookOwner(root, provider, session, writer = null) {
+  return withLock(path(root), () => {
+    const state = read(root), key = digest([provider, session]);
+    state.hookOwners ||= {};
+    if (!Object.hasOwn(state.hookOwners, key)) {
+      state.hookOwners[key] = state.generation; state.revision++; atomicSave(path(root), state);
+    }
+    if (writer?.pid > 1 && writer.identity) {
+      state.writerCapabilities ||= {};
+      state.writerCapabilities[key] = { protocol: DISPATCH_PROTOCOL, pid: writer.pid, processIdentity: writer.identity, moduleDigest: DISPATCH_MODULE_DIGEST, generation: state.hookOwners[key] };
+      state.revision++; atomicSave(path(root), state);
+    }
+    return { root: realpathSync(root), generation: state.hookOwners[key], protocol: DISPATCH_PROTOCOL };
+  });
+}
+export function adoptHookOwner({ root = detachmentRoot(), provider, session, expectedRevision }) {
+  return withLock(path(root), () => {
+    const state = read(root);
+    if (state.revision !== expectedRevision) fail('revision_conflict');
+    if (state.connection !== 'reconciling') fail('reconciliation_required');
+    state.hookOwners ||= {}; state.hookOwners[digest([provider, session])] = state.generation;
+    state.revision++; atomicSave(path(root), state); return state;
+  });
+}
+
+// Bind only an actual Provider-reported session; never substitute a task ID.
+function applyIdentityIntake(state, item) {
+  const attempt = state.attempts[digest(item.attemptId)];
+  if (!attempt?.provenance) fail('provenance_unavailable');
+  if (attempt.provenance.providerSession && attempt.provenance.providerSession !== item.providerSession) fail('provider_session_mismatch');
+  const identity = normalizeDispatchIdentity({ ...attempt.provenance.context, session: item.providerSession });
+  if (attempt.identityHash && attempt.identityHash !== digest(identity)) fail('provider_session_mismatch');
+  registerDispatchProvenance(attempt.provenance, item.providerSession);
+  attempt.identityHash = digest(identity); attempt.identityStatus = 'bound';
+  const key = digest(`identity:${item.attemptId}:${item.providerExecutionId}`);
+  state.receipts[key] = { attemptId: item.attemptId, providerExecutionId: item.providerExecutionId, resultRef: null, generation: attempt.generation };
+  if (!['result_saved', 'confirmed'].includes(attempt.phase)) attempt.phase = 'provider_identified';
+  return identity;
+}
+export function flushDispatchIntake(root = detachmentRoot()) {
+  const directory = join(root, 'update-detachment', 'intake');
+  return withLock(path(root), () => {
+    const state = read(root); let names;
+    try { names = readdirSync(directory); } catch (error) { if (error.code === 'ENOENT') return state; throw error; }
+    const applied = [];
+    for (const name of names) {
+      if (!/^[a-f0-9]{64}\.json$/.test(name)) continue;
+      const item = readState(join(directory, name));
+      if (item?.kind === 'receipt') applyReceipt(state, item); else applyIdentityIntake(state, item);
+      applied.push(name);
+    }
+    if (applied.length) { state.revision++; atomicSave(path(root), state); for (const name of applied) unlinkSync(join(directory, name)); }
+    return state;
+  });
+}
+export function bindDispatchIdentity({ root = detachmentRoot(), attemptId, providerSession, providerExecutionId = providerSession }) {
+  const state = read(root), attempt = state.attempts[digest(attemptId)];
+  if (!attempt?.provenance) fail('provenance_unavailable');
+  if (attempt.provenance.providerSession && attempt.provenance.providerSession !== providerSession) fail('provider_session_mismatch');
+  const identity = normalizeDispatchIdentity({ ...attempt.provenance.context, session: providerSession });
+  if (attempt.identityHash && attempt.identityHash !== digest(identity)) fail('provider_session_mismatch');
+  const item = { schemaVersion: 1, attemptId, providerSession, providerExecutionId };
+  // Intake has its own durable file; an async hook holding the send lock must
+  // not lose already observed provider evidence or the running child handle.
+  atomicSave(join(root, 'update-detachment', 'intake', `${digest(item)}.json`), item);
+  try { flushDispatchIntake(root); } catch (error) { if (error.code !== 'state_busy') throw error; }
+  return identity;
+}
+export function observeDispatchEvent({ root = detachmentRoot(), attemptId, provider, event, onError = () => {} }) {
+  try {
+  const providerSession = provider === 'codex' && event?.type === 'thread.started' ? event.thread_id :
+    provider === 'claude' && ['system', 'result'].includes(event?.type) ? event.session_id : null;
+  if (!providerSession) return null;
+  const attempt = read(root).attempts[digest(attemptId)];
+  if (!attempt?.provenance?.context.account || !attempt.provenance.context.device) return null;
+  return bindDispatchIdentity({ root, attemptId, providerSession });
+  } catch (error) { onError(error); return null; }
+}
+
+// Callers must enumerate every live writer from actual discovery; absence of a
+// writer report is not proof that old hooks or a rollback binary are safe.
+function validateWriters(state, writers) {
+  if (!Array.isArray(writers)) fail('writer_inventory_required');
+  for (const writer of writers) {
+    if (!writer || !['codex', 'claude'].includes(writer.provider) || !writer.session) fail('writer_identity_required');
+    const key = digest([writer.provider, writer.session]);
+    const report = state.writerCapabilities?.[key];
+    if (!writer?.processIdentity || !Number.isSafeInteger(writer.pid) || !report || report.protocol !== DISPATCH_PROTOCOL || report.pid !== writer.pid || report.processIdentity !== writer.processIdentity || report.moduleDigest !== writer.moduleDigest) fail('writer_protocol_unverified');
+  }
+  return true;
+}
+export function assertWriterCompatibility({ root = detachmentRoot(), writers }) { return validateWriters(read(root), writers); }
+export function recordWriterCapability({ root = detachmentRoot(), provider, session, pid, processIdentity, moduleDigest }) {
+  if (!['codex', 'claude'].includes(provider) || !session || !Number.isSafeInteger(pid) || pid < 2 || !processIdentity || !moduleDigest) fail('writer_identity_required');
+  return withLock(path(root), () => {
+    const state = read(root); state.writerCapabilities ||= {};
+    state.writerCapabilities[digest([provider, session])] = { protocol: DISPATCH_PROTOCOL, pid, processIdentity, moduleDigest, generation: state.generation };
+    state.revision++; atomicSave(path(root), state); return state;
+  });
+}
+export function prepareUpgradeFence({ root = detachmentRoot(), expectedRevision, writers }) {
+  return withLock(path(root), () => {
+    const state = read(root); validateWriters(state, writers);
+    if (state.revision !== expectedRevision) fail('revision_conflict');
+    if (!['connected', 'ready', 'recovery_required'].includes(state.connection)) fail('invalid_transition');
+    state.generation++; state.schemaVersion = 2; state.minimumDispatchProtocol = DISPATCH_PROTOCOL;
+    state.connection = 'detaching'; state.revision++; atomicSave(path(root), state); return state;
+  });
+}
+
+const boundedText = value => typeof value === 'string' && value.trim().length > 0 && value.length <= 2048;
+const exactKeys = (value, keys) => isMap(value) && Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+const fenceKey = (identity, taskId) => digest([digest(identity), digest(taskId)]);
+const REASONS = ['provider_policy_unknown', 'provider_model_unknown', 'provider_identity_unverified'];
+function storedFenceIdentity(value, root) {
+  if (!exactKeys(value, ['root', 'account', 'origin', 'device', 'provider', 'session', 'worktree']) || !['root', 'account', 'origin', 'device', 'session', 'worktree'].every(key => boundedText(value[key])) || !['codex', 'claude'].includes(value.provider) || value.root !== realpathSync(root) || resolve(value.worktree) !== value.worktree) fail('task_fence_invalid');
+  let url; try { url = new URL(value.origin); } catch { fail('task_fence_invalid'); }
+  if (!['https:', 'http:'].includes(url.protocol) || url.origin !== value.origin) fail('task_fence_invalid');
+  // Archived worktrees remain valid historical identities; reading the ledger must not require them to exist.
+  return { root: value.root, account: value.account, origin: value.origin, device: value.device, provider: value.provider, session: value.session, worktree: value.worktree };
+}
+function admissionWriterMatches(state, item) {
+  const writer = state.writerCapabilities?.[digest([item.identity.provider, item.identity.session])], proof = item.admission;
+  return writer?.protocol === DISPATCH_PROTOCOL && writer.generation === state.generation && writer.pid === proof?.pid && writer.processIdentity === proof?.processIdentity && writer.moduleDigest === proof?.moduleDigest;
+}
+function validateTaskFences(state, root) {
+  if (state.taskFences === undefined) return;
+  if (state.minimumDispatchProtocol !== 3 || !exactKeys(state.taskFences, ['version', 'records']) || state.taskFences.version !== 1 || !isMap(state.taskFences.records)) fail('task_fence_invalid');
+  for (const [key, item] of Object.entries(state.taskFences.records)) {
+    if (!exactKeys(item, ['version', 'identity', 'identityHash', 'taskId', 'taskHash', 'generation', 'revision', 'status', 'reason', 'createdAt', 'admission']) || item.version !== 1 || !boundedText(item.taskId) || !Number.isSafeInteger(item.generation) || item.generation < 0 || item.generation > state.generation || !Number.isSafeInteger(item.revision) || item.revision < 1 || !['blocked', 'admitted'].includes(item.status) || !Number.isSafeInteger(item.createdAt) || !exactKeys(item.reason, ['code', 'evidenceRef']) || !REASONS.includes(item.reason.code) || !boundedText(item.reason.evidenceRef) || !exactKeys(item.identity, ['root', 'account', 'origin', 'device', 'provider', 'session', 'worktree']) || item.identity.root !== realpathSync(root)) fail('task_fence_invalid');
+    const identity = storedFenceIdentity(item.identity, root);
+    if (digest(identity) !== item.identityHash || digest(item.taskId) !== item.taskHash || key !== fenceKey(identity, item.taskId)) fail('task_fence_invalid');
+    if (item.status === 'blocked' ? item.admission !== null : !validObservation(item.admission, item, state, false)) fail('task_fence_invalid');
+  }
+}
+function assertTaskAdmissionState(state, { taskId, identity = null }) {
+  const records = state.taskFences?.records || {};
+  if (!identity) {
+    if (Object.values(records).some(item => item.taskId === taskId)) fail('task_admission_identity_required');
+    return true;
+  }
+  const item = records[fenceKey(identity, taskId)];
+  if (item && (item.status !== 'admitted' || item.generation !== state.generation || !admissionWriterMatches(state, item))) {
+    const error = new Error('Original task needs fresh verified provider policy and model admission.');
+    error.code = 'task_admission_blocked'; error.reasonCode = item.reason.code; throw error;
+  }
+  return true;
+}
+export function assertTaskAdmission(owner, { taskId, identity = null, provenance = null }) {
+  if (!owner || !boundedText(taskId)) fail('dispatch_identity_required');
+  identity = identity ? normalizeDispatchIdentity(identity) : provenance?.identity || null;
+  if (identity && identity.root !== owner.root) fail('identity_root_mismatch');
+  const state = read(owner.root);
+  if (owner.generation !== state.generation || owner.protocol !== DISPATCH_PROTOCOL || !['connected', 'ready'].includes(state.connection)) fail('owner_fenced');
+  return assertTaskAdmissionState(state, { taskId, identity });
+}
+export function readTaskAdmission({ root = detachmentRoot(), identity, taskId }) {
+  identity = storedFenceIdentity(identity, root);
+  if (identity.root !== realpathSync(root)) fail('identity_root_mismatch');
+  const state = read(root), record = state.taskFences?.records[fenceKey(identity, taskId)] || null;
+  return { revision: state.revision, generation: state.generation, record, canResume: ['connected', 'ready'].includes(state.connection) && (!record || record.status === 'admitted' && record.generation === state.generation && admissionWriterMatches(state, record)) };
+}
+function checkAdmissionOwner(state, owner, identity, taskId, expectedRevision) {
+  if (!owner || owner.root !== identity.root || owner.protocol !== DISPATCH_PROTOCOL || owner.generation !== state.generation) fail('owner_fenced');
+  if (!boundedText(taskId) || state.revision !== expectedRevision) fail('revision_conflict');
+}
+export function setTaskAdmissionFence({ owner, identity, taskId, expectedRevision, expectedFenceRevision = null, reason, writers }) {
+  identity = normalizeDispatchIdentity(identity);
+  return withLock(path(identity.root), () => {
+    const state = read(identity.root); checkAdmissionOwner(state, owner, identity, taskId, expectedRevision);
+    validateWriters(state, writers);
+    const registration = createStateStore(identity).read().tasks[digest(taskId)];
+    if (!registration?.identity || digest(registration.identity) !== digest(identity)) fail('task_admission_unregistered');
+    if (!exactKeys(reason, ['code', 'evidenceRef']) || !REASONS.includes(reason.code) || !boundedText(reason.evidenceRef)) fail('task_fence_reason_invalid');
+    const key = fenceKey(identity, taskId), previous = state.taskFences?.records[key];
+    if ((previous?.revision ?? null) !== expectedFenceRevision) fail('task_fence_revision_conflict');
+    state.taskFences ||= { version: 1, records: {} };
+    state.taskFences.records[key] = { version: 1, identity, identityHash: digest(identity), taskId, taskHash: digest(taskId), generation: state.generation, revision: (previous?.revision || 0) + 1, status: 'blocked', reason: { ...reason }, createdAt: Date.now(), admission: null };
+    // v2 writers validate minimumDispatchProtocol and cannot ignore taskFences.
+    state.schemaVersion = 2; state.minimumDispatchProtocol = 3; state.revision++;
+    atomicSave(path(identity.root), state); return state;
+  });
+}
+const OBSERVATION_KEYS = ['source', 'reference', 'observedAt', 'providerModel', 'permissionPolicyHash', 'pid', 'processIdentity', 'moduleDigest', 'identityHash', 'taskHash', 'generation', 'fenceRevision', 'nonce'];
+function validObservation(observation, item, state, fresh) {
+  if (!exactKeys(observation, OBSERVATION_KEYS) || !['provider_observation', 'explicit_permission_confirmation'].includes(observation.source) || !['reference', 'providerModel', 'processIdentity', 'moduleDigest', 'nonce'].every(key => boundedText(observation[key])) || !/^[a-f0-9]{64}$/.test(observation.permissionPolicyHash) || !Number.isSafeInteger(observation.pid) || observation.pid < 2 || !Number.isSafeInteger(observation.observedAt) || observation.identityHash !== item.identityHash || observation.taskHash !== item.taskHash || observation.generation !== item.generation || observation.fenceRevision !== item.revision - (item.status === 'admitted' ? 1 : 0)) return false;
+  if (!fresh) return true;
+  const writer = state.writerCapabilities?.[digest([item.identity.provider, item.identity.session])];
+  return observation.observedAt >= item.createdAt && Date.now() - observation.observedAt >= 0 && Date.now() - observation.observedAt <= 30_000 && writer?.protocol === DISPATCH_PROTOCOL && writer.generation === state.generation && writer.pid === observation.pid && writer.processIdentity === observation.processIdentity && writer.moduleDigest === observation.moduleDigest;
+}
+export async function admitTaskDispatch({ owner, identity, taskId, expectedRevision, expectedFenceRevision, verifyObservation }) {
+  identity = normalizeDispatchIdentity(identity);
+  if (typeof verifyObservation !== 'function') fail('task_admission_verifier_required');
+  const release = acquireLock(path(identity.root));
+  try {
+    const state = read(identity.root); checkAdmissionOwner(state, owner, identity, taskId, expectedRevision);
+    const item = state.taskFences?.records[fenceKey(identity, taskId)];
+    if (!item || item.status !== 'blocked' || item.revision !== expectedFenceRevision || item.generation !== state.generation) fail('task_fence_revision_conflict');
+    const nonce = randomUUID(); let timer;
+    const observation = await Promise.race([
+      Promise.resolve().then(() => verifyObservation(Object.freeze({ identity, taskId, generation: state.generation, fenceRevision: item.revision, nonce }))),
+      new Promise((_, reject) => { timer = setTimeout(() => reject(Object.assign(new Error('Provider admission observation timed out.'), { code: 'task_admission_observation_timeout' })), 2000); }),
+    ]).finally(() => clearTimeout(timer));
+    if (!validObservation(observation, item, state, true) || observation.nonce !== nonce) fail('task_admission_observation_invalid');
+    item.status = 'admitted'; item.revision++; item.admission = { ...observation }; state.revision++;
+    atomicSave(path(identity.root), state); return state;
+  } finally { release(); }
+}

package/src/codex-plugins/simy/hooks/update-dispatch-identity.mjs

@@ -0,0 +1,78 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, realpathSync, readdirSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { createStateStore, digest, fail, readState } from './update-state-store.mjs';
+
+const text = value => typeof value === 'string' && value.length > 0 && value.length <= 2048 ? value : null;
+export function normalizeDispatchIdentity(value) {
+  if (!value || !['codex', 'claude'].includes(value.provider) || !['root', 'account', 'origin', 'device', 'session', 'worktree'].every(key => text(value[key]))) fail('identity_required');
+  const url = new URL(value.origin);
+  if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || url.search || url.hash || !['', '/'].includes(url.pathname)) fail('identity_origin_invalid');
+  mkdirSync(value.root, { recursive: true, mode: 0o700 });
+  // Stable, whitelist-only ordering. No token, prompt, model or authority is copied.
+  return Object.freeze({ root: realpathSync(value.root), account: value.account, origin: url.origin,
+    device: value.device, provider: value.provider, session: value.session, worktree: realpathSync(value.worktree) });
+}
+function accountMetadata(root, origin) {
+  const hash = createHash('sha256').update(origin).digest('hex');
+  for (const file of [join(root, 'sessions', `${hash}.json`), join(root, 'session.json')]) {
+    let session;
+    try { session = JSON.parse(readFileSync(file, 'utf8')); }
+    catch (error) { if (error.code === 'ENOENT') continue; fail('account_metadata_unreadable'); }
+    if (session?.api_origin === origin) return session;
+  }
+  return null;
+}
+export function captureDispatchProvenance({ root, provider, providerSession = null, worktree, accountSession,
+  origin = accountSession?.api_origin || process.env.SIMY_WEB_ORIGIN || process.env.SIMY_API_ORIGIN || 'https://app.simy.one', taskId, recordRef }) {
+  if (!text(root) || !text(worktree) || !text(taskId) || !text(recordRef) || !['codex', 'claude'].includes(provider)) fail('provenance_invalid');
+  const url = new URL(origin);
+  if (url.username || url.password || url.search || url.hash || !['', '/'].includes(url.pathname) || !['http:', 'https:'].includes(url.protocol)) fail('identity_origin_invalid');
+  mkdirSync(root, { recursive: true, mode: 0o700 }); root = realpathSync(root);
+  const source = accountSession === undefined ? accountMetadata(root, url.origin) : accountSession;
+  if (source?.api_origin && new URL(source.api_origin).origin !== url.origin) fail('account_origin_mismatch');
+  const context = Object.freeze({ root, account: text(source?.account_id) || text(source?.auth_user_id),
+    origin: url.origin, device: text(source?.device_id), provider, worktree: realpathSync(worktree) });
+  const identity = providerSession && context.account && context.device ? normalizeDispatchIdentity({ ...context, session: providerSession }) : null;
+  return Object.freeze({ taskId, recordRef, context, providerSession, identity });
+}
+export function registerDispatchProvenance(provenance, providerSession = provenance?.providerSession) {
+  if (!provenance || !providerSession || !provenance.context.account || !provenance.context.device) fail('identity_unavailable');
+  if (provenance.providerSession && provenance.providerSession !== providerSession) fail('provider_session_mismatch');
+  const identity = normalizeDispatchIdentity({ ...provenance.context, session: providerSession });
+  createStateStore(identity).registerTask({ taskId: provenance.taskId, recordRef: provenance.recordRef, identity });
+  return identity;
+}
+// A retained registration describes a past canonical scope; it does not grant
+// execution admission. Its worktree may have been archived since registration.
+function retainedRegistrationIdentity(value, root) {
+  const keys = ['root', 'account', 'origin', 'device', 'provider', 'session', 'worktree'];
+  if (!value || Object.keys(value).length !== keys.length || !keys.every(key => text(value[key])) ||
+      !['codex', 'claude'].includes(value.provider) || value.root !== realpathSync(root) ||
+      !isAbsolute(value.worktree) || resolve(value.worktree) !== value.worktree) fail('registration_corrupt');
+  let url;
+  try { url = new URL(value.origin); } catch { fail('registration_corrupt'); }
+  if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || url.search || url.hash ||
+      !['', '/'].includes(url.pathname) || url.origin !== value.origin) fail('registration_corrupt');
+  return Object.freeze({ root: value.root, account: value.account, origin: value.origin,
+    device: value.device, provider: value.provider, session: value.session, worktree: value.worktree });
+}
+export function listDispatchRegistrations(root, { taskId = null, retained = false } = {}) {
+  if (taskId !== null && !text(taskId)) fail('registration_task_invalid');
+  const directory = join(resolve(root), 'update-detachment', 'scopes'); let names;
+  try { names = readdirSync(directory); } catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+  const registrations = [];
+  for (const name of names) {
+    if (!/^[a-f0-9]{64}\.json$/.test(name)) continue;
+    const state = readState(join(directory, name));
+    for (const [key, task] of Object.entries(state?.tasks || {})) {
+      if (taskId !== null && task.taskId !== taskId) continue;
+      if (!task.identity || !task.taskId) continue; // Older hash-only references stay unresolved.
+      const identity = retained ? retainedRegistrationIdentity(task.identity, root) : normalizeDispatchIdentity(task.identity);
+      const store = createStateStore(identity);
+      if (store.identityHash !== state.identityHash || digest(task.taskId) !== key) fail('registration_corrupt');
+      registrations.push({ identity, taskId: task.taskId, recordRef: task.recordRef });
+    }
+  }
+  return registrations;
+}

package/src/codex-plugins/simy/hooks/update-state-store.mjs

@@ -0,0 +1,73 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, openSync, writeFileSync, fsyncSync, closeSync, renameSync, unlinkSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+
+export const SCHEMA_VERSION = 1;
+export const CONNECTION_STATES = ['connected', 'detaching', 'detached', 'reconciling', 'ready', 'recovery_required'];
+export function fail(code) { const error = new Error(`Update detachment: ${code}`); error.code = code; throw error; }
+export const isMap = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+export const digest = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+export function readState(file, { versions = [SCHEMA_VERSION] } = {}) {
+  try { const state = JSON.parse(readFileSync(file, 'utf8')); if (!versions.includes(state.schemaVersion)) fail('unknown_schema'); return state; }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+export function atomicSave(file, state) {
+  mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  const fd = openSync(temporary, 'wx', 0o600);
+  try {
+    try { writeFileSync(fd, `${JSON.stringify(state)}\n`); fsyncSync(fd); } finally { closeSync(fd); }
+    renameSync(temporary, file);
+    // Node cannot fsync directory handles on Windows. Preserve file fsync and
+    // atomic rename there, matching coding-run-store; POSIX directory durability
+    // remains mandatory and every POSIX IO error still propagates.
+    if (process.platform !== 'win32') {
+      const directory = openSync(dirname(file), 'r');
+      try { fsyncSync(directory); } finally { closeSync(directory); }
+    }
+  }
+  finally { try { unlinkSync(temporary); } catch (error) { if (error.code !== 'ENOENT') throw error; } }
+}
+// A crashed owner leaves the lock in place. Never steal a lock using a timeout
+// or a PID alone (PID reuse); recovery requires an operator-verified boundary.
+export function acquireLock(file) {
+  mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+  const token = randomUUID();
+  let fd; try { fd = openSync(`${file}.lock`, 'wx', 0o600); } catch (error) { if (error.code === 'EEXIST') fail('state_busy'); throw error; }
+  try { writeFileSync(fd, JSON.stringify({ pid: process.pid, token })); fsyncSync(fd); }
+  catch (error) { closeSync(fd); unlinkSync(`${file}.lock`); throw error; }
+  let released = false;
+  return () => {
+    if (released) return; released = true; closeSync(fd);
+    let owner; try { owner = JSON.parse(readFileSync(`${file}.lock`, 'utf8')); } catch (error) { if (error.code === 'ENOENT') return; throw error; }
+    if (owner.token === token) unlinkSync(`${file}.lock`);
+  };
+}
+export function withLock(file, operation, { preserveResult = false } = {}) {
+  const release = acquireLock(file); let completed = false;
+  try { const result = operation(); completed = true; return result; }
+  finally { try { release(); } catch (error) { if (!completed || !preserveResult) throw error; } }
+}
+export function createStateStore({ root, account, origin, device, provider, session, worktree }) {
+  if (![root, account, origin, device, provider, session, worktree].every(value => typeof value === 'string' && value.length > 0)) fail('identity_required');
+  if (!['codex', 'claude'].includes(provider)) fail('provider_invalid');
+  const identityHash = digest([resolve(root), account, new URL(origin).origin, device, provider, session, resolve(worktree)]);
+  const file = join(resolve(root), 'update-detachment', 'scopes', `${identityHash}.json`);
+  const initial = () => ({ schemaVersion: 1, identityHash, revision: 0, generation: 0, connection: 'connected', tasks: {}, attempts: {}, receipts: {}, events: {} });
+  const read = () => { const state = readState(file) || initial(); if (state.identityHash !== identityHash || !Number.isSafeInteger(state.revision) || !Number.isSafeInteger(state.generation) || !CONNECTION_STATES.includes(state.connection) || !['tasks', 'attempts', 'receipts', 'events'].every(key => isMap(state[key]))) fail('invalid_state'); return state; };
+  const transact = (expectedRevision, change) => withLock(file, () => {
+    const state = read(); if (state.revision !== expectedRevision) fail('revision_conflict');
+    const next = change(structuredClone(state));
+    if (!next || next.identityHash !== identityHash || next.schemaVersion !== 1 || !CONNECTION_STATES.includes(next.connection) || !Number.isSafeInteger(next.generation) || next.generation < state.generation) fail('invalid_transition');
+    next.revision = state.revision + 1; atomicSave(file, next); return next;
+  });
+  const registerTask = ({ taskId, recordRef, identity = null }) => {
+    if (![taskId, recordRef].every(value => typeof value === 'string' && value.length > 0 && value.length <= 2048)) fail('task_reference_invalid');
+    return withLock(file, () => {
+      const state = read(), key = digest(taskId);
+      if (Object.hasOwn(state.tasks, key)) { if (state.tasks[key].recordRef !== recordRef || identity && state.tasks[key].identity && digest(state.tasks[key].identity) !== digest(identity)) fail('task_identity_conflict'); if (!identity || state.tasks[key].identity) return state; }
+      state.tasks[key] = { recordRef, taskId, ...(identity ? { identity } : {}) }; state.revision++; atomicSave(file, state); return state;
+    });
+  };
+  return { file, identityHash, read, transact, registerTask };
+}

package/src/delivery-hooks/desktop.js

@@ -30,7 +30,7 @@ export async function deliveryHookStatus({ root = rootDirectory(), now = Date.no
     })),
     runs: records.filter(r => r.run && r.providerArchived !== true).sort((a, b) => b.run.updatedAt - a.run.updatedAt).slice(0, 30).map(r => ({
       provider: r.provider, session: r.session, originalSessionTarget: originalSessionTarget(r.provider, r.session),
-      objective: r.run.objective, state: r.run.state, reason: r.run.reason, runId: r.run.id, revision: deliveryDecisionRevision(r.run), recoveryCause: r.run.recoveryCause, autoRecovery: r.run.managed?.autoRecovery === true,
+      objective: r.run.objective, state: r.run.state, reason: r.run.reason, runId: r.run.id, revision: deliveryDecisionRevision(r.run), recoveryCause: r.run.recoveryCause, stopReason: r.run.stopReason || null, autoRecovery: r.run.managed?.autoRecovery === true,
       continuations: r.run.continuations,
       continuationPolicy: r.run.managed?.continuationPolicy || 'bounded',
       startedAt: r.run.startedAt,