@awak-app/simy-cli 0.5.37 → 0.5.39

package/src/session-supervision/action-association-api.js

@@ -0,0 +1,99 @@
+import { createHash } from 'node:crypto';
+import { readSession, isSessionValid } from '../session-store.js';
+import { webApiHeaders, webApiUrl } from '../web-api.js';
+
+const MAX_REQUEST_BYTES = 24 * 1024;
+const MAX_RESPONSE_BYTES = 96 * 1024;
+const TASK_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export class ActionAssociationApiError extends Error {
+  constructor(code) {
+    super('Action association service is unavailable.');
+    this.name = 'ActionAssociationApiError';
+    this.code = code;
+  }
+}
+
+async function boundedJson(response) {
+  const advertised = response.headers?.get?.('content-length');
+  if (advertised !== null && advertised !== undefined && (!/^\d+$/.test(advertised) || Number(advertised) > MAX_RESPONSE_BYTES)) {
+    throw new ActionAssociationApiError('invalid_response');
+  }
+  if (!response.body) throw new ActionAssociationApiError('invalid_response');
+  const chunks = []; let size = 0;
+  for await (const chunk of response.body) {
+    size += chunk.byteLength;
+    if (size > MAX_RESPONSE_BYTES) {
+      throw new ActionAssociationApiError('invalid_response');
+    }
+    chunks.push(Buffer.from(chunk));
+  }
+  try {
+    const value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    if (!value || typeof value !== 'object' || Array.isArray(value) || value.schemaVersion !== 1 ||
+        typeof value.scope?.organizationId !== 'string' || typeof value.scope?.userId !== 'string') {
+      throw new Error('Invalid envelope.');
+    }
+    return value;
+  } catch { throw new ActionAssociationApiError('invalid_response'); }
+}
+
+// Tokens and transcript fragments never appear in exceptions or desktop state.
+// Authentication is reread for every request; a late response from a previous
+// login cannot associate work in the newly selected account.
+export function createActionAssociationApi({ webOrigin, sessionRoot,
+  fetchImpl = fetch, readSessionImpl = readSession, now = Date.now, timeoutMs = 10_000 } = {}) {
+  const identity = session => createHash('sha256').update(`${webOrigin}\0${session.token}`).digest('hex');
+  const currentSession = async () => {
+    const session = await readSessionImpl(webOrigin, sessionRoot);
+    if (!isSessionValid(session, now(), webOrigin)) throw new ActionAssociationApiError('signed_out');
+    return session;
+  };
+  const request = async (path, method, payload, signal) => {
+    let response, session, url, body;
+    try {
+      session = await currentSession();
+      url = webApiUrl(path, { webOrigin, apiBaseUrl: session.api_base_url });
+      body = payload === undefined ? undefined : JSON.stringify(payload);
+      if (body && Buffer.byteLength(body) > MAX_REQUEST_BYTES) throw new ActionAssociationApiError('invalid_request');
+      const timeout = AbortSignal.timeout(timeoutMs);
+      response = await fetchImpl(url, {
+        method, headers: webApiHeaders(session, body ? { 'Content-Type': 'application/json' } : {}),
+        body, redirect: 'error', signal: signal ? AbortSignal.any([timeout, signal]) : timeout,
+      });
+      if (!response.ok) {
+        // Do not decode errors: upstream proxy/provider messages can contain
+        // private query context or credentials.
+        await response.body?.cancel?.().catch(() => {});
+        throw new ActionAssociationApiError(response.status === 409 ? 'conflict' :
+          response.status === 401 || response.status === 403 ? 'unauthorized' :
+            response.status === 404 ? 'unavailable' : 'offline');
+      }
+      const value = await boundedJson(response);
+      if (identity(await currentSession()) !== identity(session)) throw new ActionAssociationApiError('account_changed');
+      return value;
+    } catch (error) {
+      if (error instanceof ActionAssociationApiError) throw error;
+      throw new ActionAssociationApiError(signal?.aborted ? 'cancelled' : 'offline');
+    }
+  };
+  const taskPath = taskId => {
+    if (!TASK_ID.test(taskId || '')) throw new ActionAssociationApiError('invalid_request');
+    return `action-bindings/${taskId}`;
+  };
+  return {
+    async authRevision() {
+      try { return identity(await currentSession()); } catch { return null; }
+    },
+    candidates(payload, { signal } = {}) {
+      taskPath(payload?.taskId);
+      return request('actions/candidates', 'POST', payload, signal);
+    },
+    readBinding(taskId, { signal } = {}) {
+      return request(taskPath(taskId), 'GET', undefined, signal);
+    },
+    saveBinding(taskId, payload, { signal } = {}) {
+      return request(taskPath(taskId), 'PUT', payload, signal);
+    },
+  };
+}

package/src/session-supervision/action-association-host.js

@@ -0,0 +1,213 @@
+import { listRecords, updateRecord, TERMINAL, managedBudgetReason } from '../codex-plugins/simy/hooks/delivery-loop.mjs';
+import { createActionAssociationApi, ActionAssociationApiError } from './action-association-api.js';
+import { actionCandidateRequest, prepareActionAssociation, importActionBinding,
+  settleActionAssociation, cancelActionAssociation } from './action-association.js';
+
+const namespaceFor = (origin, scope) => JSON.stringify([new URL(origin).origin, scope.organizationId, scope.userId]);
+const identity = record => ({ provider: record.provider, session: record.session, taskId: record.run.managed.taskId });
+const eligible = record => record.run?.managed?.taskId && (!record.run.managed.handoff || record.run.managed.handoff.status === 'received');
+const publicCandidate = item => ({ id: item.id, revision: item.revision, title: item.title.slice(0,120) });
+const publicBinding = binding => binding ? { ...binding, reason: (binding.reason || '').slice(0,60), coveredWork: (binding.coveredWork || '').slice(0,60), evidence: [],
+  action: binding.action ? { ...binding.action, title: (binding.action.title || '').slice(0,120), description: null, projectName: (binding.action.projectName || '').slice(0,60) } : null } : null;
+const hardFailure = code => ['unauthorized', 'unavailable', 'invalid_request', 'invalid_response'].includes(code);
+
+// Association is optional metadata. Network failures never control the task's
+// work state; provider turns and their budgets remain owned by the supervisor.
+export function createActionAssociationHost({ root, sessionRoot, webOrigin, api = createActionAssociationApi({ webOrigin, sessionRoot }),
+  now = Date.now, refreshMs = 60_000, list = listRecords } = {}) {
+  const abort = new AbortController(), views = new Map();
+  let auth = null, closed = false, running = null, serial = Promise.resolve();
+  const enqueue = work => {
+    const result = serial.then(work); serial = result.catch(() => {}); return result;
+  };
+  const current = async () => {
+    const next = await api.authRevision();
+    if (next !== auth) {
+      auth = next; views.clear();
+      for (const record of (await list(root)).filter(eligible)) {
+        const association = record.run.managed.actionAssociation;
+        if (!association || association.authRevision === next) continue;
+        await updateRecord(root, record.provider, record.session, latest => {
+          const local = latest?.run?.managed?.actionAssociation;
+          if (!local || latest.run.managed.taskId !== record.run.managed.taskId) return latest;
+          local.invalidated = true; local.binding = null; delete local.outbox; local.status = 'unavailable';
+          return latest;
+        });
+      }
+    }
+    return next;
+  };
+  const fresh = async target => (await list(root)).find(record => eligible(record) && record.provider === target.provider && record.session === target.session && record.run.managed.taskId === target.taskId);
+  const valid = async expected => !closed && expected && await current() === expected;
+  const importEnvelope = async (record, envelope, expected, userCorrection = false) => {
+    if (!await valid(expected)) throw new ActionAssociationApiError('account_changed');
+    if (envelope.binding && envelope.binding.taskId !== record.run.managed.taskId) throw new ActionAssociationApiError('invalid_response');
+    const namespace = namespaceFor(webOrigin, envelope.scope);
+    const local = record.run.managed.actionAssociation;
+    // An empty remote binding must not erase a cached ambiguous/no-match result.
+    if (userCorrection || envelope.binding || local?.binding || local?.namespace && local.namespace !== namespace) {
+      await importActionBinding({ root, ...identity(record), namespace, binding: envelope.binding, userCorrection, now: now() });
+    }
+    await updateRecord(root, record.provider, record.session, latest => {
+      const local = latest?.run?.managed?.actionAssociation;
+      if (latest?.run?.managed?.taskId !== record.run.managed.taskId) return latest;
+      latest.run.managed.actionAssociation = { ...local, authRevision: expected };
+      if (!local?.job) delete latest.run.managed.actionAssociation.invalidated;
+      return latest;
+    });
+    return namespace;
+  };
+  async function sync(record, expected, force = false, queue = true) {
+    const target = identity(record), association = record.run.managed.actionAssociation;
+    let view = views.get(target.taskId);
+    const request = actionCandidateRequest(record);
+    const contextRevision = request?.context.revision || null;
+    if (!force && view?.auth === expected && view.contextRevision === contextRevision && now() < view.nextRefresh && (!association?.outbox || view.error)) {
+      if (queue && !view.error && view.snapshot && !association?.manualOverride && !association?.job && !association?.outbox && !TERMINAL.has(record.run.state)) await prepareActionAssociation({ root, record, snapshot: view.snapshot, webOrigin, now: now() });
+      return;
+    }
+    view = { ...view, auth: expected, contextRevision, nextRefresh: now() + refreshMs };
+    views.set(target.taskId, view);
+    try {
+      // Never publish an outbox from an earlier organization or login before a
+      // scoped server response confirms who owns the current request.
+      const snapshot = request ? await api.candidates(request, { signal: abort.signal }) : await api.readBinding(target.taskId, { signal: abort.signal });
+      const namespace = await importEnvelope(record, snapshot, expected);
+      view.namespace = namespace; view.error = null;
+      view.candidates = (snapshot.candidates || []).map(publicCandidate);
+      view.candidateTruncated = snapshot.retrieval?.truncated === true || view.candidates.length > 5;
+      view.snapshot = request ? snapshot : null;
+      let latest = await fresh(target);
+      if (!latest || !await valid(expected)) return;
+      const pending = latest.run.managed.actionAssociation?.outbox;
+      if (pending && pending.namespace === namespace && latest.run.managed.actionAssociation.authRevision === expected) {
+        if (snapshot.binding?.origin === 'automatic' && snapshot.binding.action?.id === pending.actionId && snapshot.binding.contextRevision === pending.contextRevision && snapshot.binding.candidateRevision === pending.candidateRevision) {
+          await settleActionAssociation({ root, ...target, outboxId: pending.id, namespace, binding: snapshot.binding, now: now() }); return;
+        }
+        if (snapshot.contextRevision !== pending.contextRevision || snapshot.candidateRevision !== pending.candidateRevision) {
+          await settleActionAssociation({ root, ...target, outboxId: pending.id, namespace, unavailable: true, now: now() });
+          view.nextRefresh = 0; return;
+        }
+        const payload = Object.fromEntries(['expectedRevision', 'contextRevision', 'candidateRevision', 'actionId', 'actionRevision', 'relation', 'coveredWork', 'reason', 'evidence'].map(key => [key, pending[key]]));
+        const saved = await api.saveBinding(target.taskId, { ...payload, origin: 'automatic' }, { signal: abort.signal });
+        if (!await valid(expected) || namespaceFor(webOrigin, saved.scope) !== namespace) return;
+        await settleActionAssociation({ root, ...target, outboxId: pending.id, namespace, binding: saved.binding, now: now() });
+        return;
+      }
+      if (queue && request && !latest.run.managed.actionAssociation?.manualOverride && !TERMINAL.has(latest.run.state)) {
+        // A read turn is queued only at the original session's safe boundary.
+        // Blocked tasks retain candidates for auxiliary correction in the UI.
+        await prepareActionAssociation({ root, record: latest, snapshot, webOrigin, now: now() });
+        await updateRecord(root, latest.provider, latest.session, currentRecord => {
+          if (currentRecord?.run?.managed?.taskId === target.taskId && currentRecord.run.managed.actionAssociation) currentRecord.run.managed.actionAssociation.authRevision = expected;
+          return currentRecord;
+        });
+      }
+    } catch (error) {
+      if (!await valid(expected)) return;
+      view.error = error.code || 'offline';
+      const latest = await fresh(target);
+      if (!latest) return;
+      if (error.code === 'conflict') {
+        try {
+          const remote = await api.readBinding(target.taskId, { signal: abort.signal });
+          const namespace = await importEnvelope(latest, remote, expected);
+          const box = latest.run.managed.actionAssociation?.outbox;
+          if (box && remote.binding) await settleActionAssociation({ root, ...target, outboxId: box.id, namespace, binding: remote.binding, now: now() });
+          else if (box) await settleActionAssociation({ root, ...target, outboxId: box.id, namespace, unavailable: true, now: now() });
+          view.namespace = namespace; view.nextRefresh = 0;
+        } catch { view.error = 'offline'; }
+      } else if (hardFailure(error.code)) {
+        view.candidates = []; view.snapshot = null;
+        await importActionBinding({ root, ...target, namespace: view.namespace || null, unavailable: true, now: now() });
+      } else view.nextRefresh = now() + Math.min(refreshMs, 15_000);
+    }
+  }
+  async function reconcile() {
+    const expected = await current(), records = (await list(root)).filter(eligible).slice(0, 30);
+    let cursor = 0;
+    await Promise.all(Array.from({ length: Math.min(3, records.length) }, async () => {
+    while (!closed && cursor < records.length) {
+      const record = records[cursor++];
+      const managed = record.run.managed, job = managed.actionAssociation?.job;
+      if (job && !managed.resumeLease && (!expected || TERMINAL.has(record.run.state) || ['paused', 'blocked'].includes(record.run.state) || record.run.state === 'recovery_required' && record.run.recoveryCause !== 'session_supervision' ||
+          managedBudgetReason(record.run, now()) || now() >= record.run.deadline || record.run.continuations >= record.run.maxContinuations ||
+          managed.understandingRevision !== job.understandingRevision || record.run.revision !== job.runRevision || managed.actionAssociation.invalidated)) {
+        await cancelActionAssociation({ root, ...identity(record), now: now() });
+      }
+      if (!expected) {
+        if (managed.actionAssociation?.namespace) await importActionBinding({ root, ...identity(record), namespace: null, unavailable: true, now: now() });
+        continue;
+      }
+      try { await sync(await fresh(identity(record)) || record, expected); } catch { /* Optional metadata never stops other task drives. */ }
+    }
+    }));
+  }
+  return {
+    async prepareCached(record) {
+      const view = views.get(record?.run?.managed?.taskId), request = actionCandidateRequest(record);
+      if (closed || !auth || !view || view.auth !== auth || view.error || !view.snapshot || !request || view.contextRevision !== request.context.revision || view.snapshot.contextRevision !== request.context.revision || view.namespace !== namespaceFor(webOrigin, view.snapshot.scope)) return record;
+      try {
+        const prepared = await prepareActionAssociation({ root, record, snapshot: view.snapshot, webOrigin, now: now() });
+        return prepared || record;
+      } catch { return record; }
+    },
+    tick() {
+      if (closed) return Promise.resolve();
+      if (!running) running = reconcile().finally(() => { running = null; });
+      return running;
+    },
+    async decorate(status) {
+      const expected = await current();
+      let remainingBytes = 24 * 1024;
+      const perRunBytes = Math.floor(remainingBytes / Math.max(1,(status.runs || []).filter(run => run.managed).length));
+      for (const run of status.runs || []) {
+        if (!run.managed) continue;
+        const local = run.actionAssociation, view = views.get(run.taskId);
+        // Durable caches alone are not authorization to disclose Action text.
+        run.actionAssociation = !expected ? { status: 'signed_out', binding: null, candidates: [], canCorrect: false } :
+          !view || view.auth !== expected ? { status: 'loading', binding: null, candidates: [], canCorrect: false } : {
+            status: view.error || local?.status || 'waiting_boundary',
+            binding: view.namespace && local?.namespace === view.namespace ? publicBinding(local.binding) : null,
+            candidates: (view.candidates || []).slice(0,5), canCorrect: !view.error,
+            retryOn: local?.retryOn || null, truncated: view.candidateTruncated || false,
+          };
+        let bytes = Buffer.byteLength(JSON.stringify(run.actionAssociation));
+        if (bytes > Math.min(remainingBytes,perRunBytes)) { run.actionAssociation.candidates = []; run.actionAssociation.truncated = true; bytes = Buffer.byteLength(JSON.stringify(run.actionAssociation)); }
+        if (bytes > Math.min(remainingBytes,perRunBytes) && run.actionAssociation.binding) {
+          const binding = run.actionAssociation.binding;
+          run.actionAssociation.binding = { taskId: binding.taskId, revision: binding.revision, origin: binding.origin, locked: binding.locked, relation: binding.relation, action: binding.action ? { id: binding.action.id, revision: binding.action.revision, title: binding.action.title.slice(0,40), status: binding.action.status, dueAt: binding.action.dueAt, timeZone: binding.action.timeZone } : null };
+          bytes = Buffer.byteLength(JSON.stringify(run.actionAssociation));
+        }
+        remainingBytes = Math.max(0,remainingBytes - bytes);
+      }
+      return status;
+    },
+    correct(command) {
+      return enqueue(async () => {
+        const expected = await current(), record = await fresh(command);
+        if (!expected) throw new ActionAssociationApiError('signed_out');
+        if (!record) throw new ActionAssociationApiError('invalid_request');
+        await sync(record, expected, true, false);
+        const view = views.get(command.taskId);
+        if (!await valid(expected) || !view?.namespace || view.error) throw new ActionAssociationApiError(view?.error || 'unavailable');
+        if (command.action === 'session_action_refresh') { view.nextRefresh = 0; return; }
+        const latest = await fresh(command), binding = latest?.run.managed.actionAssociation?.binding;
+        if ((binding?.revision ?? null) !== command.expectedBindingRevision) throw new ActionAssociationApiError('conflict');
+        const selected = command.action === 'session_action_select' ? view.snapshot?.candidates.find(item => item.id === command.actionId) || (!view.snapshot && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(command.actionId || '') ? { id: command.actionId, revision: null } : null) : null;
+        if (command.action !== 'session_action_unlink' && !selected) throw new ActionAssociationApiError('invalid_request');
+        const envelope = await api.saveBinding(command.taskId, {
+          expectedRevision: command.expectedBindingRevision, contextRevision: view.contextRevision,
+          candidateRevision: view.snapshot?.candidateRevision || null, origin: 'user', actionId: selected?.id || null,
+          actionRevision: selected?.revision || null, relation: selected ? 'part_of' : null,
+          coveredWork: latest.run.managed.sessionUnderstanding?.objective || latest.run.objective,
+          reason: selected ? 'Selected by the user.' : 'Unlinked by the user.', evidence: [],
+        }, { signal: abort.signal });
+        if (namespaceFor(webOrigin, envelope.scope) !== view.namespace) throw new ActionAssociationApiError('account_changed');
+        await importEnvelope(latest, envelope, expected, true);
+        view.error = null; view.nextRefresh = 0;
+      });
+    },
+    async close() { closed = true; abort.abort(); await Promise.allSettled([serial, running]); views.clear(); },
+  };
+}

package/src/session-supervision/action-association.js

@@ -0,0 +1,114 @@
+import { randomUUID } from 'node:crypto';
+import { listRecords, updateRecord, TERMINAL } from '../codex-plugins/simy/hooks/delivery-loop.mjs';
+import { associationSignals, associationRevision } from '../codex-plugins/simy/hooks/action-association.mjs';
+export { associationSignals, associationRevision, associationContract, validateAssociationResult } from '../codex-plugins/simy/hooks/action-association.mjs';
+
+function stable(run) {
+  return run?.managed && (run.state === 'active' || run.state === 'recovery_required' && run.recoveryCause === 'session_supervision' && run.managed.autoRecovery === true) && !TERMINAL.has(run.state) && run.managed.phase === 'active' && !run.managed.resumeLease && (!run.managed.handoff || run.managed.handoff.status === 'received') && !run.managed.pendingApproval && !run.managed.approvedAction && !run.managed.providerWarning && !run.managed.executionUncertain && (!run.managed.executionAttempt || run.managed.executionAttempt.phase === 'checkpointed');
+}
+function restoreAssociationWork(run, saved) {
+  const managed = run.managed;
+  managed.phase = saved.phase; managed.plan = saved.plan; managed.decision = saved.decision;
+  run.nextStep = saved.nextStep; run.checkpoint = saved.checkpoint;
+  if (run.state === saved.state) run.reason = saved.reason;
+  if (run.state === 'recovery_required' && run.recoveryCause === 'provider_error' && !managed.providerWarning && !managed.attempts?.at(-1)?.restorationUnverified && run.failures < run.maxFailures) {
+    run.state = saved.state; run.reason = saved.reason; run.recoveryCause = saved.recoveryCause; run.blocker = saved.blocker; managed.autoRecovery = saved.autoRecovery;
+  }
+  managed.awaitingAssociationHook = false;
+}
+export async function queueActionAssociation({ root, provider, session, taskId, expectedRevision, candidates, candidateRevision, scope, namespace = null, remoteBinding = null, now = Date.now() }) {
+  return updateRecord(root, provider, session, record => {
+    const run = record?.run, managed = run?.managed;
+    if (!managed || managed.taskId !== taskId || run.revision !== expectedRevision) return record;
+    if (!stable(run) || now >= run.deadline || run.continuations >= run.maxContinuations) {
+      if (!managed.actionAssociation?.job && !managed.actionAssociation?.outbox && !managed.actionAssociation?.manualOverride) managed.actionAssociation = { ...managed.actionAssociation, status: 'waiting_boundary', retryOn: 'original_session_safe_boundary', updatedAt: now };
+      return record;
+    }
+    if (managed.actionAssociation?.manualOverride && !managed.actionAssociation.namespace) return record;
+    if (managed.actionAssociation?.namespace !== namespace) managed.actionAssociation = { status: 'unavailable', namespace };
+    if (managed.actionAssociation.manualOverride || managed.actionAssociation.binding?.locked) return record;
+    if (remoteBinding && managed.actionAssociation.binding?.revision > remoteBinding.revision) return record;
+    if (remoteBinding?.taskId === taskId) { managed.actionAssociation.binding = remoteBinding; managed.actionAssociation.manualOverride = remoteBinding.locked === true; managed.actionAssociation.status = remoteBinding.action ? 'bound' : 'unlinked'; if (remoteBinding.action && remoteBinding.contextRevision === associationSignals(managed.sessionUnderstanding)?.revision) return record; }
+    if (managed.actionAssociation?.manualOverride || managed.actionAssociation?.job || managed.actionAssociation?.outbox) return record;
+    const signals = associationSignals(managed.sessionUnderstanding);
+    if (!signals || !Array.isArray(candidates) || candidates.length > 10 || !candidateRevision || !scope) return record;
+    const key = associationRevision({ context: signals, candidateRevision, scope, namespace });
+    if (managed.actionAssociation?.cacheKey === key) return record;
+    const job = { id: randomUUID(), taskId, provider, session, runRevision: run.revision, understandingRevision: managed.understandingRevision, context: signals, candidates, candidateRevision, scope, namespace, cacheKey: key,
+      saved: { phase: managed.phase, plan: managed.plan, decision: managed.decision, nextStep: run.nextStep, state: run.state, reason: run.reason, checkpoint: run.checkpoint, recoveryCause: run.recoveryCause, blocker: run.blocker, autoRecovery: managed.autoRecovery }, createdAt: now };
+    managed.actionAssociation = { ...managed.actionAssociation, status: candidates.length ? 'assessing' : 'no_match', namespace, cacheKey: key, ...(candidates.length ? { job } : {}) };
+    if (!candidates.length) return record;
+    managed.phase = 'action_association';
+    managed.decision = { id: job.id, outcome: 'proceed', action: { kind: 'read', scope: 'task', summary: 'Compare scoped Action candidates with the original user request' } };
+    run.nextStep = managed.decision.action.summary;
+    if (managed.capability === 'live_hook') managed.awaitingAssociationHook = true;
+    return record;
+  });
+}
+export async function importActionBinding({ root, provider, session, taskId, namespace, binding = null, unavailable = false, userCorrection = false, now = Date.now() }) {
+  return updateRecord(root, provider, session, record => {
+    const run = record?.run, managed = run?.managed;
+    if (managed?.taskId !== taskId || managed.handoff && managed.handoff.status !== 'received') return record;
+    const previous = managed.actionAssociation || {};
+    if (previous.namespace && previous.namespace !== namespace && previous.job && managed.resumeLease) { previous.namespace = namespace; previous.binding = null; previous.status = 'unavailable'; previous.invalidated = true; delete previous.outbox; return record; }
+    if (userCorrection && previous.job && !managed.resumeLease) {
+      const saved = previous.job.saved;
+      restoreAssociationWork(run, saved);
+      delete previous.job;
+    }
+    if (binding && binding.taskId !== taskId) throw new Error('Remote binding task differs.');
+    const association = previous.namespace && previous.namespace !== namespace ? {} : previous;
+    association.namespace = namespace;
+    if (binding && association.binding?.revision > binding.revision) return record;
+    if (binding) {
+      association.binding = binding; association.manualOverride = binding.locked === true;
+      association.status = binding.action ? 'bound' : 'unlinked';
+      if (userCorrection || binding.locked) delete association.outbox;
+    } else if (unavailable) { association.binding = null; association.status = 'unavailable'; delete association.outbox; }
+    else { association.binding = null; association.manualOverride = false; if (!association.job && !association.outbox) association.status = 'waiting_boundary'; }
+    association.updatedAt = now; managed.actionAssociation = association;
+    return record;
+  });
+}
+export const correctActionAssociation = options => importActionBinding({ ...options, userCorrection: true });
+export async function pendingAssociationTasks(root) {
+  return (await listRecords(root)).filter(record => stable(record.run) && !record.run.managed.actionAssociation?.manualOverride && !record.run.managed.actionAssociation?.job && !record.run.managed.actionAssociation?.outbox && associationSignals(record.run.managed.sessionUnderstanding));
+}
+
+export function actionCandidateRequest(record) {
+  const context = associationSignals(record?.run?.managed?.sessionUnderstanding);
+  return context ? { taskId: record.run.managed.taskId, context, limit: 10 } : null;
+}
+export async function prepareActionAssociation({ root, record, snapshot, webOrigin, now = Date.now() }) {
+  const request = actionCandidateRequest(record);
+  if (!request || snapshot?.schemaVersion !== 1 || snapshot.taskId !== request.taskId || snapshot.contextRevision !== request.context.revision || !snapshot.scope?.organizationId || !snapshot.scope?.userId) return null;
+  if (!Array.isArray(snapshot.candidates) || snapshot.candidates.length > 10 || new Set(snapshot.candidates.map(item => item.id)).size !== snapshot.candidates.length) return null;
+  for (const item of snapshot.candidates) {
+    if (typeof item.id !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(item.id) || typeof item.revision !== 'string' || item.revision.length > 200 || typeof item.title !== 'string' || item.title.length > 500 || typeof item.description === 'string' && item.description.length > 2000 || !Array.isArray(item.evidence) || item.evidence.length > 10 || new Set(item.evidence.map(fact => fact.ref)).size !== item.evidence.length || item.evidence.some(fact => typeof fact.ref !== 'string' || fact.ref.length > 200 || !['goal','deliverable','project','source'].includes(fact.kind) || typeof fact.text !== 'string' || fact.text.length > 2000)) return null;
+  }
+  const namespace = JSON.stringify([new URL(webOrigin).origin,snapshot.scope.organizationId,snapshot.scope.userId]);
+  return queueActionAssociation({ root, provider: record.provider, session: record.session, taskId: request.taskId, expectedRevision: record.run.revision,
+    candidates: snapshot.candidates, candidateRevision: snapshot.candidateRevision, scope: snapshot.scope, namespace, remoteBinding: snapshot.binding, now });
+}
+export async function settleActionAssociation({ root, provider, session, taskId, outboxId, namespace, binding = null, unavailable = false, now = Date.now() }) {
+  return updateRecord(root, provider, session, record => {
+    const association = record?.run?.managed?.actionAssociation;
+    if (record?.run?.managed?.taskId !== taskId || association?.outbox?.id !== outboxId || association.outbox.namespace !== namespace || record.run.managed.handoff && record.run.managed.handoff.status !== 'received') return record;
+    if (binding && binding.taskId === taskId) {
+      association.binding = binding; association.manualOverride = binding.locked === true;
+      association.status = binding.action ? 'bound' : 'unlinked'; delete association.outbox;
+    } else if (unavailable) { association.status = 'unavailable'; association.binding = null; delete association.outbox; }
+    association.updatedAt = now;
+    return record;
+  });
+}
+export async function cancelActionAssociation({ root, provider, session, taskId, now = Date.now() }) {
+  return updateRecord(root, provider, session, record => {
+    const run = record?.run, managed = run?.managed, association = managed?.actionAssociation;
+    if (managed?.taskId !== taskId || managed.resumeLease || !association?.job) return record;
+    const saved = association.job.saved;
+    restoreAssociationWork(run, saved);
+    managed.awaitingAssociationHook = false; association.status = 'unavailable'; delete association.job; association.updatedAt = now;
+    return record;
+  });
+}

package/src/session-supervision/analysis-manager.js

@@ -0,0 +1,187 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { lstat, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { analyzeContinuation } from './continuation-analysis.js';
+
+const BACKFILL_LIMIT = 10;
+const MAX_CACHE_ENTRIES = 2000;
+const RESULT_STATES = new Set(['continue', 'no_action', 'needs_user', 'waiting', 'uncertain']);
+const keyOf = candidate => `${candidate.provider}:${candidate.session}`;
+const activityOf = candidate => Number.isFinite(candidate.lastActivityAt) ? candidate.lastActivityAt : 0;
+export const continuationAnalysisRevision = candidate => createHash('sha256')
+  .update(JSON.stringify([candidate.provider, candidate.session, candidate.cwd, activityOf(candidate)]))
+  .digest('hex');
+const eligible = candidate => candidate.capabilities?.canAnalyze === true &&
+  ['unmanaged', 'monitor'].includes(candidate.binding?.mode || 'unmanaged');
+
+// Recommendations are metadata only. This worker never enrolls a conversation
+// or dispatches its task; the normal managed bootstrap still checks context.
+export async function createContinuationAnalysisManager({ root, analyze = analyzeContinuation,
+  now = Date.now, onChange = () => {}, timeoutMs = 120_000 } = {}) {
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  if ((await lstat(root)).isSymbolicLink()) throw new Error('Invalid session analysis cache.');
+  const path = join(root, 'cache.json');
+  let document, cacheInfo;
+  try {
+    cacheInfo = await lstat(path);
+    if (!cacheInfo.isFile() || cacheInfo.isSymbolicLink() || cacheInfo.size > 4 * 1024 * 1024) throw new Error('Invalid session analysis cache.');
+    document = JSON.parse(await readFile(path, 'utf8'));
+    const pairs = list => Array.isArray(list) && list.every(pair => Array.isArray(pair) && pair.length === 2 && typeof pair[0] === 'string' && pair[1] && typeof pair[1] === 'object');
+    if (document.schemaVersion !== 1 || typeof document.initialized !== 'boolean' || !pairs(document.known) || !pairs(document.entries) ||
+      !Number.isFinite(document.baselineAt) || document.entries.some(([, entry]) => !/^[a-f0-9]{64}$/.test(entry.revision) ||
+        !['queued', 'analyzing', 'failed', ...RESULT_STATES].includes(entry.result?.state))) throw new Error('Invalid session analysis cache.');
+  } catch (error) {
+    if (error.code !== 'ENOENT') {
+      if (!cacheInfo?.isFile() || cacheInfo.isSymbolicLink()) throw error;
+      // Keep corrupt metadata recoverable and avoid treating all history as a
+      // new cohort. Manual analysis and genuinely new messages still work.
+      await rename(path, `${path}.unreadable-${randomUUID()}`);
+    }
+    document = { schemaVersion: 1, baselineAt: now(), initialized: error.code !== 'ENOENT', known: [], entries: [] };
+  }
+  const known = new Map(document.known.slice(-MAX_CACHE_ENTRIES));
+  const entries = new Map(document.entries.slice(-MAX_CACHE_ENTRIES));
+  const candidates = new Map();
+  for (const [key, entry] of entries) {
+    if (entry.result?.state === 'analyzing') entry.result = { state: 'queued' };
+  }
+  let serial = Promise.resolve(), draining = null, closed = false, controller = null;
+  const exclusive = fn => {
+    const next = serial.then(fn);
+    serial = next.catch(() => {});
+    return next;
+  };
+  const persist = async () => {
+    for (const map of [known, entries]) while (map.size > MAX_CACHE_ENTRIES) map.delete(map.keys().next().value);
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+      await writeFile(temporary, JSON.stringify({ ...document, known: [...known], entries: [...entries] }) + '\n', { mode: 0o600 });
+      await rename(temporary, path);
+    } finally { await rm(temporary, { force: true }); }
+  };
+  const changed = () => { void Promise.resolve().then(onChange).catch(() => {}); };
+  const enqueue = (candidate, force = false) => {
+    const key = keyOf(candidate), revision = continuationAnalysisRevision(candidate);
+    const entry = entries.get(key);
+    if (entry?.revision === revision && (['queued', 'analyzing'].includes(entry.result?.state) ||
+      !force && !['failed', 'uncertain'].includes(entry.result?.state))) return false;
+    entries.delete(key);
+    entries.set(key, { revision, result: { state: 'queued' } });
+    return true;
+  };
+  const startDrain = () => {
+    if (closed || draining) return;
+    draining = (async () => {
+      while (!closed) {
+        const selected = await exclusive(async () => {
+          if (closed) return null;
+          for (const [key, entry] of entries) {
+            const candidate = candidates.get(key);
+            if (entry.result?.state !== 'queued' || !candidate || !eligible(candidate) || entry.revision !== continuationAnalysisRevision(candidate)) continue;
+            entry.result = { state: 'analyzing' };
+            await persist(); changed();
+            return { key, revision: entry.revision, candidate };
+          }
+          return null;
+        });
+        if (!selected || closed) break;
+        controller = new AbortController();
+        const signal = controller.signal;
+        const timeout = setTimeout(() => controller?.abort(), timeoutMs);
+        timeout.unref?.();
+        let aborted;
+        const cancellation = new Promise((_, reject) => {
+          aborted = () => reject(new Error('Session analysis cancelled.'));
+          signal.addEventListener('abort', aborted, { once: true });
+        });
+        let result, inference;
+        try {
+          inference = Promise.resolve(analyze(selected.candidate, { signal }));
+          result = await Promise.race([inference, cancellation]);
+          if (!RESULT_STATES.has(result?.state) || typeof result.reason !== 'string' ||
+            (result.state === 'continue' && (!result.objective || !result.remaining?.length || !result.nextAction || !result.basis?.some(item => item.role === 'user')))) {
+            throw new Error('Invalid session analysis result.');
+          }
+        } catch {
+          result = { state: 'failed', reason: 'The conversation could not be analyzed. Retry when its provider is available.' };
+        } finally {
+          // Provider cancellation includes its process-exit receipt and scratch
+          // cleanup. Do not start the next job or update runtime before it ends.
+          if (signal.aborted) await inference?.catch(() => {});
+          clearTimeout(timeout); signal.removeEventListener('abort', aborted); controller = null;
+        }
+        await exclusive(async () => {
+          const current = candidates.get(selected.key), entry = entries.get(selected.key);
+          if (closed) return;
+          if (!current || !eligible(current) || continuationAnalysisRevision(current) !== selected.revision || entry?.revision !== selected.revision) {
+            if (entry?.revision === selected.revision && entry.result?.state === 'analyzing') {
+              entry.result = { state: 'queued' }; await persist(); changed();
+            }
+            return;
+          }
+          entries.set(selected.key, { revision: selected.revision, result: { ...result, analyzedAt: now() } });
+          await persist(); changed();
+        });
+      }
+    })().catch(() => {}).finally(() => {
+      draining = null;
+      if (!closed && [...entries].some(([key, entry]) => entry.result?.state === 'queued' &&
+        candidates.has(key) && eligible(candidates.get(key)) && entry.revision === continuationAnalysisRevision(candidates.get(key)))) startDrain();
+    });
+  };
+  return {
+    async update(sessions) {
+      await exclusive(async () => {
+        if (closed) return;
+        candidates.clear();
+        for (const candidate of sessions) candidates.set(keyOf(candidate), candidate);
+        const sorted = [...candidates.values()].sort((a, b) => activityOf(b) - activityOf(a) || keyOf(a).localeCompare(keyOf(b)));
+        const backfill = document.initialized ? new Set() : new Set(sorted.slice(0, BACKFILL_LIMIT).map(keyOf));
+        let dirty = !document.initialized;
+        for (const candidate of sorted) {
+          const key = keyOf(candidate), revision = continuationAnalysisRevision(candidate), previous = known.get(key);
+          const active = activityOf(candidate);
+          const newActivity = document.initialized && (previous ? active > previous.activity : active > document.baselineAt);
+          if (eligible(candidate) && (backfill.has(key) || newActivity)) dirty = enqueue(candidate) || dirty;
+          if (previous?.revision !== revision) {
+            known.delete(key); known.set(key, { revision, activity: active }); dirty = true;
+          }
+        }
+        // Empty discovery during provider startup must not consume backfill.
+        if (sorted.length) document.initialized = true;
+        if (dirty) await persist();
+      });
+      startDrain();
+    },
+    project(candidate) {
+      const revision = continuationAnalysisRevision(candidate), entry = entries.get(keyOf(candidate));
+      return { ...candidate, analysis: entry?.revision === revision ? { ...entry.result, revision } : { state: 'unanalysed', revision } };
+    },
+    async request(candidate) {
+      if (!candidate || !eligible(candidate)) throw new Error('This conversation cannot be analyzed.');
+      await exclusive(async () => {
+        if (closed) throw new Error('Session analysis is unavailable.');
+        candidates.set(keyOf(candidate), candidate);
+        if (enqueue(candidate, true)) { await persist(); changed(); }
+      });
+      startDrain();
+    },
+    async invalidate(candidate) {
+      await exclusive(async () => {
+        if (closed) throw new Error('Session analysis is unavailable.');
+        entries.delete(keyOf(candidate));
+        candidates.set(keyOf(candidate), candidate);
+        enqueue(candidate); await persist(); changed();
+      });
+      startDrain();
+    },
+    requireRecommendation(candidate) {
+      if (closed) throw new Error('Session analysis is unavailable.');
+      const analysis = this.project(candidate).analysis;
+      if (!eligible(candidate) || analysis.state !== 'continue') throw new Error('Analyze this conversation before continuing; it needs a current recommendation.');
+      return analysis;
+    },
+    async whenIdle() { do { await serial; await draining; } while (draining); await serial; },
+    async close() { closed = true; controller?.abort(); await this.whenIdle(); },
+  };
+}