@awak-app/simy-cli 0.6.23 → 0.6.26

package/src/session-supervision/purpose-candidate.js

@@ -0,0 +1,44 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { randomUUID } from 'node:crypto';
+import { mkdir, realpath } from 'node:fs/promises';
+import { join, relative, isAbsolute } from 'node:path';
+import { workspaceIdentity } from './purpose-verification.js';
+const exec=promisify(execFile);
+
+// A candidate never applies itself to the original. Arbitrary user/provider
+// writers do not participate in our lease, so a check-then-copy is not a CAS.
+export async function preparePurposeCandidate(record, { root, authorize, signal, execute=exec } = {}) {
+  const original=await realpath(record.run.executionCwd || record.cwd);
+  await authorize();signal?.throwIfAborted();
+  await execute('git',['rev-parse','--show-toplevel'],{cwd:original,signal,timeout:5000}).then(({stdout})=>{
+    if (stdout.trim()!==original) throw new Error('Candidate requires the task repository root.');
+  });
+  const parent=join(original,'.simy-purpose-candidates');
+  await authorize();signal?.throwIfAborted();
+  await mkdir(parent,{recursive:true,mode:0o700});
+  if(await realpath(parent)!==parent) throw new Error('Candidate root changed to a symlink.');
+  const gitIdentity=async()=>{const {stdout}=await execute('git',['rev-parse','HEAD','--symbolic-full-name','HEAD'],{cwd:original,signal,timeout:5000,maxBuffer:4096});return stdout.trim();};
+  const identity=await gitIdentity(), revision=identity.split('\n')[0];
+  if(!/^[a-f0-9]{40}$/.test(revision)) throw new Error('Candidate base revision unavailable.');
+  const before=await workspaceIdentity(original,parent,undefined,{signal});
+  const {stdout:patch}=await execute('git',['diff','--binary',revision],{cwd:original,signal,timeout:10000,maxBuffer:8*1024*1024});
+  // Untracked paths are not silently lost: any untracked source is a capability
+  // gap until a safe snapshot mechanism can include it with provenance.
+  const {stdout:untracked}=await execute('git',['ls-files','--others','--exclude-standard'],{cwd:original,signal,timeout:5000,maxBuffer:1024*1024});
+  if(untracked.trim().split('\n').some(path=>path && !path.startsWith('.simy-purpose-candidates/'))) throw new Error('Untracked task files require an explicit snapshot before candidate execution.');
+  if(identity!==await gitIdentity() || before!==await workspaceIdentity(original,parent,undefined,{signal})) throw new Error('Original changed during candidate snapshot.');
+  const directory=join(parent,randomUUID());
+  await authorize();signal?.throwIfAborted();
+  await execute('git',['worktree','add','--detach',directory,revision],{cwd:original,signal,timeout:10000,maxBuffer:4096});
+  if(await realpath(directory)!==directory || isAbsolute(relative(parent,directory)) || relative(parent,directory).startsWith('..')) throw new Error('Candidate directory identity changed.');
+  // Only tracked working differences enter this isolated checkout. A failed
+  // apply leaves the candidate retained and cannot overwrite original work.
+  await authorize();signal?.throwIfAborted();
+  if(patch) await new Promise((resolve,reject)=>{
+    const child=execFile('git',['apply','--binary','-'],{cwd:directory,signal,timeout:10000,maxBuffer:4096},error=>error?reject(error):resolve());
+    child.stdin.end(patch);
+  });
+  await authorize();signal?.throwIfAborted();
+  return {id:directory.split('/').at(-1),directory,original,sourceDigest:before,baseRevision:revision,sourceGitIdentity:identity,status:'ready',application:'exclusive_or_CAS_required',createdAt:Date.now()};
+}

package/src/session-supervision/purpose-instruction.js

@@ -0,0 +1,47 @@
+import { selectiveRuleReview, applicableRuleIds } from '../codex-plugins/simy/hooks/purpose-rule-policy.mjs';
+import { searchInstruction } from '../codex-plugins/simy/hooks/purpose-search.mjs';
+import { createHash } from 'node:crypto';
+import { readFile, readdir } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { purposeContract, llmDecisionInstruction } from '../codex-plugins/simy/hooks/purpose-cycle.mjs';
+import { CORE_CONTROL_IDS } from '../codex-plugins/simy/hooks/purpose-rule-review.mjs';
+const root = new URL('../orchestrator/delivery/', import.meta.url);
+// The existing packaged workflow and references remain the source of truth.
+// Index all sections; do not curate away inconvenient rules or claim execution.
+export async function loadPurposeRuleSet() {
+  const files = ['WORKFLOW.md', '../../workflow-reporting.md', ...(await readdir(new URL('references/', root))).filter(name => name.endsWith('.md')).sort().map(name => `references/${name}`)];
+  const rules = [];
+  const sources = [['llm-first-decision-policy', llmDecisionInstruction]];
+  for (const file of files) {
+    const content = await readFile(new URL(file, root), 'utf8');
+    sources.push([file, content]);
+    let fenced = false;
+    for (const [index, line] of content.split('\n').entries()) {
+      if (/^\s*```/.test(line)) { fenced = !fenced; continue; }
+      if (fenced || !/^#{1,4}\s+/.test(line)) continue;
+      const title = line.replace(/^#+\s+/, '');
+      const id = createHash('sha256').update(`${file}\0${title}`).digest('hex').slice(0, 12);
+      rules.push({ id, title, file, line: index + 1 });
+    }
+  }
+  const catalogFile = 'controls/harness-controls.json';
+  const content = await readFile(new URL(catalogFile, root), 'utf8');
+  const catalog = JSON.parse(content);
+  if (catalog.schemaVersion !== 1 || catalog.controls?.length !== 102 || catalog.controls.some((rule, index) =>
+    rule.id !== `HC-${String(index + 1).padStart(2, '0')}` || !rule.title || !rule.acceptance)) throw new Error('Historical control catalog is incomplete.');
+  sources.push([catalogFile, content]);
+  rules.push(...catalog.controls.map(rule => ({ id: rule.id, title: rule.title, file: catalogFile,
+    acceptance: rule.acceptance, acceptanceDetails: rule.acceptanceDetails, group: rule.group,
+    implementationOwner: rule.owner, machineValidator: 'captured_evidence_reference_coverage', semanticValidator: 'independent_domain_review', recoveryAction: 'acquire_missing_evidence_or_repair_owner',
+    provenance: `${catalog.source.repository}@${catalog.source.revision}:${catalog.source.files[0].path}:${rule.sourceLine}`, enforcement: 'independent_domain_review', decisionGuidance: 'Apply as a critique lens after LLM judgment; reversible choices are delegated to AI. Preserve independent evidence and actual authority.' })));
+  if (!rules.length || new Set(rules.map(rule => rule.id)).size !== rules.length) throw new Error('Purpose rule index is empty or ambiguous.');
+  return { digest: createHash('sha256').update(JSON.stringify(sources)).digest('hex'), rules };
+}
+export async function buildPurposeInstruction(managed, { reviewer = false } = {}) {
+  if (!managed?.purpose?.enabled) return '';
+  const ruleSet = await loadPurposeRuleSet();
+  if (ruleSet.digest !== managed.purpose.ruleDigest) throw Object.assign(new Error('Purpose workflow changed; refresh its rule inventory before dispatch.'), { code: 'purpose_rules_changed' });
+  if (reviewer && selectiveRuleReview(managed)) return `${llmDecisionInstruction}\nIndependently verify the original acceptance criteria and applicable canonical obligations from actual evidence. Consult the inventory as needed after forming an LLM judgment; do not enumerate every ID or impose core controls as universal checklist gates. Report only rules actually evaluated; omitted inventory entries are not passed or not_applicable. Known applicable obligations ${JSON.stringify(applicableRuleIds(managed))} must be independently assessed and cannot be discarded by worker claims. Do not copy worker dispositions as proof. Failed, unavailable or missing evidence remains unverified with a concrete acquisition/repair finding. No unrelated rule coverage obligation is implied.\nruleSet: ${JSON.stringify(ruleSet.rules.map(rule => ({ ...rule, path: fileURLToPath(new URL(rule.file, root)) })))}`;
+  if (reviewer) return `${llmDecisionInstruction}\nCanonical rule inventory. Review applicability and evidence for EVERY ID, including HC-01 through HC-102; these controls are requirements, not proof that their mechanisms exist. Read the referenced sections and acceptance details as needed. User instructions retain priority. Do not impose unrelated development/release controls on other task types. Core controls ${CORE_CONTROL_IDS.join(', ')} apply to every autonomous task; inspect their actual bounded behavior, including conditional duties whose trigger did not occur, rather than marking the entire control not_applicable. Return rules:[{id,evidenceRefs:[{ref,target,observation}],status:"satisfied|failed|unverified|not_applicable",basis:"inspected evidence or specific applicability reason"}]. Keep basis concise with source locators; stored receipts are limited to 160 UTF-8 bytes and basisTruncated means re-read the original evidence. Never copy worker dispositions as independent proof. Missing capability is unverified and requires an acquisition/repair finding, not a human certification request.\nruleSet: ${JSON.stringify(ruleSet.rules.map(rule => ({ ...rule, path: fileURLToPath(new URL(rule.file, root)) })))}`;
+  return `${purposeContract(managed)}\n${searchInstruction(managed)}\nForm a grounded candidate judgment with LLM reasoning first; consult the applicable canonical rule sections using read tools to challenge that judgment before its effects. This ruleSet is authoritative workflow material; user instructions retain priority. ${selectiveRuleReview(managed) ? "Review applicable rules and known obligations only; do not require full inventory coverage." : "Use the purpose contract for full initial rule coverage and changed dispositions on subsequent search turns."} Missing sources or unavailable tools remain unverified; do not fabricate coverage. Repository AGENTS.md and explicit user constraints also apply.\nruleSet: ${JSON.stringify(ruleSet.rules.map(rule => ({ ...rule, path: fileURLToPath(new URL(rule.file, root)) })))}\nPrior rule dispositions (provider reported, re-evaluate applicability): ${JSON.stringify(managed.purpose.version === 2 ? managed.purpose.lastReview?.rules || [] : [])}\nLast purpose review (provider reported): ${JSON.stringify(managed.purpose.lastReview ? { gap: managed.purpose.lastReview.gap, hypothesis: managed.purpose.lastReview.hypothesis, noChangeAssessment: managed.purpose.lastReview.noChangeAssessment, observations: managed.purpose.lastReview.observations, unresolvedRules: managed.purpose.lastReview.rules.filter(rule => ['failed', 'unverified'].includes(rule.status)) } : null)}\nRecovery context: ${JSON.stringify(managed.purpose.lastRecovery || null)}`;
+}

package/src/session-supervision/purpose-observer.js

@@ -0,0 +1,172 @@
+import { lookup } from 'node:dns/promises';
+import { request as httpsRequest } from 'node:https';
+import { BlockList } from 'node:net';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { createHash } from 'node:crypto';
+import { evidenceExcerpt } from '../codex-plugins/simy/hooks/purpose-evidence.mjs';
+const exec = promisify(execFile);
+const failure = (code, message) => Object.assign(new Error(message), { code });
+const blocked = new BlockList();
+for (const [address, prefix] of [['0.0.0.0',8],['10.0.0.0',8],['100.64.0.0',10],['127.0.0.0',8],['169.254.0.0',16],['172.16.0.0',12],['192.0.0.0',24],['192.0.2.0',24],['192.168.0.0',16],['198.18.0.0',15],['198.51.100.0',24],['203.0.113.0',24],['224.0.0.0',4],['240.0.0.0',4]]) blocked.addSubnet(address, prefix);
+
+export function normalizeObservation(value) {
+  if (!value || typeof value !== 'object') throw new Error('Observation recipe required.');
+  let fields;
+  if (value.fields !== undefined) {
+    if (!Array.isArray(value.fields) || !value.fields.length || value.fields.length > 4 || new Set(value.fields).size !== value.fields.length ||
+        value.fields.some(field => typeof field !== 'string' || !field.startsWith('/') || field.length > 200 || /~(?![01])/u.test(field))) throw failure('unsupported_recipe', 'Use up to four JSON pointers to required result fields.');
+    fields = { fields: value.fields };
+  }
+  if (value.type === 'https_get') {
+    const url = new URL(value.url);
+    if (url.protocol !== 'https:' || url.port && url.port !== '443' || url.username || url.password || url.search || url.hash || url.href.length > 2000) throw new Error('Public observation requires HTTPS without credentials, query or fragment.');
+    return { type: value.type, url: url.href, ...fields };
+  }
+  if (value.type === 'github_repository' && typeof value.path === 'string' && !value.path.split('/').some(part => ['.', '..'].includes(part)) &&
+      /^repos\/[\w.-]+\/[\w.-]+\/(?:pulls\/[1-9]\d*(?:\/files)?|issues\/[1-9]\d*|actions\/runs\/[1-9]\d*|commits\/[a-f0-9]{7,40}\/(?:check-runs|status))$/.test(value.path)) return { type: value.type, path: value.path, ...fields };
+  throw new Error('Unsupported observation; use a public HTTPS result or a current-repository GitHub read endpoint.');
+}
+
+export async function readPublicResult(url, { signal, resolve = lookup, request = httpsRequest } = {}) {
+  const target = new URL(normalizeObservation({ type: 'https_get', url }).url);
+  const addresses = await new Promise((done, fail) => {
+    const aborted = () => finish(signal.reason || new Error('Observation cancelled.'));
+    const timer = setTimeout(() => finish(new Error('Observation DNS timed out.')), 5000);
+    const finish = (error, value) => { clearTimeout(timer); signal?.removeEventListener('abort', aborted); error ? fail(error) : done(value); };
+    signal?.addEventListener('abort', aborted, { once: true });
+    if (signal?.aborted) return aborted();
+    Promise.resolve().then(() => resolve(target.hostname, { family: 4, all: true })).then(value => finish(null, value), finish);
+  });
+  signal?.throwIfAborted();
+  if (!addresses.length || addresses.some(item => blocked.check(item.address, 'ipv4'))) throw failure('non_public_target', 'Non-public observation target.');
+  // Pin the validated address. Redirects are observations, never followed to a
+  // new authority; no cookies, credentials, request body or worker headers.
+  return new Promise((resolveResult, reject) => {
+    const req = request(target, { method: 'GET', signal, family: 4,
+      lookup: (_host, options, callback) => callback(null, ...(options.all ? [[addresses[0]]] : [addresses[0].address, 4])),
+      headers: { accept: 'application/json,text/plain,text/html', 'accept-encoding': 'identity', 'user-agent': 'SIMY-read-only-observer' } }, response => {
+      const chunks = []; let size = 0;
+      response.on('data', chunk => { size += chunk.length; if (size > 1024 * 1024) req.destroy(new Error('Observation exceeds one MiB.')); else chunks.push(chunk); });
+      response.on('error', reject);
+      response.on('end', () => resolveResult({ status: response.statusCode, body: Buffer.concat(chunks).toString('utf8'), etag: typeof response.headers?.etag === 'string' ? response.headers.etag : null }));
+    });
+    const deadline = setTimeout(() => req.destroy(new Error('Observation timed out.')), 15_000);
+    req.on('close', () => clearTimeout(deadline));
+    req.on('error', reject); req.end();
+  });
+}
+
+export async function repositoryIdentity(cwd, { signal, execute = exec } = {}) {
+  const { stdout: remote } = await execute('git', ['remote', 'get-url', 'origin'], { cwd, signal, timeout: 5000, maxBuffer: 4096 });
+  const match = remote.trim().match(/^(?:git@github\.com:|https:\/\/github\.com\/)([\w.-]+)\/([\w.-]+?)(?:\.git)?$/);
+  if (!match) throw new Error('No supported repository origin.');
+  return `${match[1]}/${match[2]}`;
+}
+
+export async function readRepositoryResult(path, { cwd, signal, repository, execute = exec, publicRead = readPublicResult } = {}) {
+  path = normalizeObservation({ type: 'github_repository', path }).path;
+  if (!repository || !/^[\w.-]+\/[\w.-]+$/.test(repository) || !path.startsWith(`repos/${repository}/`) ||
+      await repositoryIdentity(cwd, {signal,execute}) !== repository) throw failure('repository_scope', 'Observation is outside the controller-enrolled repository.');
+  try {
+    const { stdout } = await execute('gh', ['api', '--hostname', 'github.com', '--method', 'GET', path], { cwd, signal, timeout: 20_000, maxBuffer: 1024 * 1024 });
+    return { status: 200, body: stdout };
+  } catch (error) {
+    // A missing optional CLI still permits a public read of the same resource.
+    // Never discover credentials or broaden the enrolled repository scope.
+    if (error.code !== 'ENOENT') throw error;
+    return publicRead(`https://api.github.com/${path}`, { signal });
+  }
+}
+
+function resultExcerpt(body, fields) {
+  if (!fields) return evidenceExcerpt(body, 1000);
+  let parsed;
+  try { parsed = JSON.parse(body); } catch { throw failure('invalid_json', 'Required result fields need a JSON response.'); }
+  // Resolve only own properties, with no evaluation or inherited-property access.
+  // Bound each field separately so a large first value cannot hide later results.
+  const selected = fields.map(path => {
+    let value = parsed, found = true;
+    for (const key of path.slice(1).split('/').map(part => part.replace(/~1/g, '/').replace(/~0/g, '~'))) {
+      if (!value || typeof value !== 'object' || !Object.hasOwn(value, key)) { found = false; break; }
+      value = value[key];
+    }
+    // Include the path in redaction: selecting a credential value must not
+    // remove the sensitive key which normally triggers redaction.
+    return { path, found, ...(found ? { value: evidenceExcerpt({ [path]: value }, 500) } : {}) };
+  });
+  return evidenceExcerpt({ selected }, 4000);
+}
+
+const httpOutcome = status => status >= 200 && status < 300 ? 'success' : status === 404 ? 'not_found' :
+  [401, 403].includes(status) ? 'authentication_or_permission' : status === 429 ? 'rate_limit' :
+    status >= 300 && status < 400 ? 'redirect' : status >= 500 ? 'server_error' : 'http_error';
+
+export async function collectPurposeObservations(managed, { cwd, signal, authorize, publicRead = readPublicResult, repositoryRead = readRepositoryResult, now, clock, networkAllowed = false } = {}) {
+  const completedAt = clock || (now === undefined ? Date.now : () => now);
+  now ??= completedAt();
+  const ledger = managed.purpose.evidence;
+  const findings = (ledger?.findings || []).filter(item => item.status === 'open' && item.observation)
+    .map(finding => { let recipe, invalid = false; try { recipe = normalizeObservation(finding.observation); } catch { recipe = { type: 'unsupported', findingId: finding.id }; invalid = true; } const id = createHash('sha256').update(JSON.stringify(invalid ? finding.observation : recipe)).digest('hex'); const prior = ledger.observationAttempts?.[id] || ledger.observations?.findLast(item => item.id === id); return { finding, recipe, id, prior, invalid }; })
+    .filter(item => item && (!item.prior || now - item.prior.at >= (item.prior.status === 'observed' ? 60_000 : 300_000)))
+    .sort((a, b) => (a.prior?.at || 0) - (b.prior?.at || 0)).slice(0, 4);
+  const receipts = [];
+  for (const {finding, recipe, id, invalid} of findings) {
+    if (receipts.some(item => item.id === id)) continue;
+    await authorize(); signal?.throwIfAborted();
+    const startedAt = completedAt();
+    let receipt;
+    try {
+      if (invalid) throw failure('unsupported_recipe', 'Unsupported observation recipe.');
+      if (!networkAllowed) throw failure('network_disabled', 'Original provider does not allow network access.');
+      const result = recipe.type === 'https_get' ? await publicRead(recipe.url, { signal }) : await repositoryRead(recipe.path, { cwd, signal, repository: ledger.baseline?.repository });
+      receipt = { id, findingId: finding.id, recipe, source: 'controller_read_only_observer', status: 'observed', httpStatus: result.status, outcome: httpOutcome(result.status),
+        digest: createHash('sha256').update(result.body).digest('hex'), observation: resultExcerpt(result.body, result.status >= 200 && result.status < 300 ? recipe.fields : null), startedAt, at: completedAt(), targetRevision: result.revision || null, etag: result.etag || null };
+    } catch (error) {
+      signal?.throwIfAborted();
+      const outcome = ['unsupported_recipe', 'network_disabled', 'non_public_target', 'repository_scope', 'invalid_json', 'ENOTFOUND', 'EAI_AGAIN', 'ECONNREFUSED', 'ETIMEDOUT', 'ENOENT'].includes(error.code) ? error.code : 'read_failed';
+      receipt = { id, findingId: finding.id, recipe, source: 'controller_read_only_observer', status: 'unavailable', startedAt, at: completedAt(),
+        outcome,
+        reason: 'The scoped read failed. Investigate the endpoint or choose another supported observation; no permission was granted and no write was attempted.' };
+    }
+    await authorize(); receipts.push(receipt);
+  }
+  return receipts;
+}
+
+// A long independent review must not repeatedly expire its own starting
+// evidence. Re-read the same recipes under the same authority before settling.
+export async function refreshPurposeObservations(managed, prior, { collect = collectPurposeObservations, ...options } = {}) {
+  const selected = new Map();
+  for (const item of prior) if (item.source === 'controller_read_only_observer' && item.status === 'observed' && item.httpStatus >= 200 && item.httpStatus < 300) {
+    if (!selected.has(item.id) || selected.get(item.id).at <= item.at) selected.set(item.id, item);
+  }
+  const sources = [...selected.values()];
+  const observations = [];
+  for (let start = 0; start < Math.min(sources.length, 20); start += 4) {
+    const evidence = { ...managed.purpose.evidence, observations: [], observationAttempts: {},
+      findings: sources.slice(start, start + 4).map(item => ({ id: item.findingId, status: 'open', observation: item.recipe })) };
+    observations.push(...await collect({ ...managed, purpose: { ...managed.purpose, evidence } }, options));
+  }
+  const comparable = item => {
+    if (!item || item.status !== 'observed' || item.httpStatus < 200 || item.httpStatus >= 300) return null;
+    if (item.recipe?.fields && !item.observation?.truncated && !item.observation?.redacted) {
+      try {
+        const values = JSON.parse(item.observation.text).selected;
+        if (Array.isArray(values) && values.length === item.recipe.fields.length && values.every(row => row.found === false || row.value && !row.value.truncated && !row.value.redacted)) return JSON.stringify([item.httpStatus, values]);
+      } catch { /* Incomplete projections require the full-response identity. */ }
+    }
+    return /^[a-f0-9]{64}$/.test(item.digest) ? `${item.httpStatus}:${item.digest}` : null;
+  };
+  for (const after of observations) {
+    const before = sources.find(item => item.id === after.id);
+    if (before && comparable(before) && comparable(before) === comparable(after)) {
+      after.revalidation = { priorAt: before.at, priorDigest: before.digest, comparedAt: after.at, unchanged: true };
+    }
+  }
+  const times = observations.map(item => item.at);
+  return { observations, window: { source: 'controller_refresh_batch', startedAt: times.length ? Math.min(...observations.map(item => item.startedAt ?? item.at)) : null, finishedAt: times.length ? Math.max(...times) : null }, temporalSkewMs: times.length ? Math.max(...times) - Math.min(...times) : 0, atomic: false, changed: sources.length > 20 || sources.some(before => {
+    const after = observations.find(item => item.id === before.id);
+    return !comparable(before) || comparable(before) !== comparable(after);
+  }) };
+}

package/src/session-supervision/purpose-recovery.js

@@ -0,0 +1,264 @@
+import { preparePurposeCandidate } from './purpose-candidate.js';
+import { requireProviderLink } from '../provider-links.js';
+import { searchEnabled, purposeFailureMode } from '../codex-plugins/simy/hooks/purpose-search.mjs';
+import { createHash } from 'node:crypto';
+import { listRecords, readRecord, updateRecord, automaticContinuationAllowed, queuePurposeDiagnosis, queuePurposeVerification } from '../codex-plugins/simy/hooks/delivery-loop.mjs';
+import { openCodexAppServer, readCodexSession, observeCodexAuthentication } from './codex-app-server.js';
+import { realpath } from 'node:fs/promises';
+import { loadPurposeRuleSet } from './purpose-instruction.js';
+import { purposeEnabled } from '../codex-plugins/simy/hooks/purpose-cycle.mjs';
+import { upgradeAutonomousRecord, upgradeEligible } from './autonomous-upgrade.js';
+import { effectiveAcceptanceCriteria } from '../codex-plugins/simy/hooks/acceptance-policy.mjs';
+
+export async function observePurposeTurn(record, { openClient = openCodexAppServer } = {}) {
+  const client = await openClient();
+  try {
+    const metadata = await readCodexSession(client, record.session);
+    if (await realpath(metadata.cwd) !== record.cwd || metadata.model !== record.run.managed.resumeModel) return { state: 'unknown' };
+    const result = await client.request('thread/turns/list', { threadId: record.session, limit: 1, sortDirection: 'desc', itemsView: 'summary' });
+    const turn = result?.data?.[0];
+    if (!turn?.id || !['completed', 'failed', 'interrupted', 'inProgress'].includes(turn.status)) return { state: 'unknown' };
+    return { state: turn.status === 'inProgress' ? 'running' : 'idle', turnId: turn.id, status: turn.status };
+  } finally { await client.close(); }
+}
+
+export async function observeUpgradeMetadata(record, { openClient = openCodexAppServer } = {}) {
+  const client = await openClient();
+  try {
+    const meta = await readCodexSession(client, record.session);
+    let isRunning = meta.isRunning;
+    if (isRunning === undefined) {
+      const latest = await client.request('thread/turns/list', { threadId: record.session, limit: 1, sortDirection: 'desc', itemsView: 'summary' });
+      const turn = latest?.data?.[0];
+      if (turn?.id && ['completed', 'failed', 'interrupted', 'inProgress'].includes(turn.status)) isRunning = turn.status === 'inProgress';
+    }
+    return { session: record.session, cwd: await realpath(meta.cwd), model: meta.model, isRunning };
+  }
+  finally { await client.close(); }
+}
+
+export async function reconcilePurposeTasks({ root, signal, prepareCandidate = preparePurposeCandidate, now = Date.now(), observeTurn = observePurposeTurn, observeAuthentication = observeCodexAuthentication, readRecords = () => listRecords(root), observeMetadata = observeUpgradeMetadata }) {
+  let rules;
+  const deferred = [];
+
+  for (let record of await readRecords()) {
+    try {
+    let run = record.run;
+    if (upgradeEligible(record) && (run.managed.controllerContractVersion !== 2 || run.state === 'paused' || run.state === 'verification_pending')) {
+      let metadata, migrationLink;
+      try { migrationLink = await requireProviderLink({ root, provider: record.provider }); metadata = await observeMetadata(record); }
+      catch { metadata = null; }
+      if (metadata) {
+        rules ||= await loadPurposeRuleSet();
+        record = await updateRecord(root, record.provider, record.session, async current => {
+          await requireProviderLink({ root, provider: record.provider, expectedEpoch: migrationLink.epoch });
+          if (current?.run?.id !== run.id || current.run.revision !== run.revision || current.run.state !== run.state || current.autoContinueEpoch !== record.autoContinueEpoch) return current;
+          upgradeAutonomousRecord(current, { rules, now, metadata }); return current;
+        });
+        run = record.run;
+      }
+    }
+    // Existing ON consent enables the new diagnosis mode without renewing any
+    // task identity, acceptance condition, permission, budget or active lease.
+    if (record.provider === 'codex' && record.autoContinue === true && automaticContinuationAllowed(record) &&
+        run?.managed?.resumeChannel === 'codex_app_server' && (!run.managed.purpose || run.managed.purpose.failureBudgetMode !== purposeFailureMode(record)) &&
+        ['active', 'blocked', 'recovery_required', 'verification_pending'].includes(run.state) && !run.managed.resumeLease) {
+      let migrationLink;
+      try { migrationLink = await requireProviderLink({ root, provider: record.provider }); } catch { continue; }
+      rules ||= await loadPurposeRuleSet();
+      record = await updateRecord(root, record.provider, record.session, async current => {
+        try { await requireProviderLink({ root, provider: record.provider, expectedEpoch: migrationLink.epoch }); } catch { return current; }
+        if (current?.run?.id !== run.id || current.run.revision !== run.revision || current.run.state !== run.state ||
+            current.autoContinue !== true || current.autoContinueEpoch !== record.autoContinueEpoch || !automaticContinuationAllowed(current) ||
+            current.run.managed.resumeLease) return current;
+        current.run.managed.purpose = { ...current.run.managed.purpose, enabled: true, version: 2, decisionPolicy: 'llm-first-hc102', failureBudgetMode: purposeFailureMode(current),
+          ruleDigest: rules.digest, ruleIds: rules.rules.map(rule => rule.id), recoveries: current.run.managed.purpose?.recoveries || [] };
+        return current;
+      });
+      run = record?.run;
+    }
+    if (!purposeEnabled(run) || run.managed.resumeChannel !== 'codex_app_server') continue;
+    if (!automaticContinuationAllowed(record)) continue;
+    let link;
+    try { link = await requireProviderLink({ root, provider: record.provider }); } catch { continue; }
+    const authorized = async () => {
+      await requireProviderLink({ root, provider: record.provider, expectedEpoch: link.epoch });
+      const latest = await readRecord(root, record.provider, record.session);
+      if (!latest || !automaticContinuationAllowed(latest) || latest.run?.id !== run.id || latest.autoContinueEpoch !== record.autoContinueEpoch || ['paused', 'stopped'].includes(latest.run.state)) throw new Error('Purpose observation authorization changed.');
+    };
+    const observe = async read => { await authorized(); const result = await read(); await authorized(); return result; };
+    const persist = mutate => updateRecord(root, record.provider, record.session, async current => {
+      try { await requireProviderLink({ root, provider: record.provider, expectedEpoch: link.epoch }); } catch { return current; }
+      if (!current || !automaticContinuationAllowed(current) || current.autoContinueEpoch !== record.autoContinueEpoch) return current;
+      return mutate(current);
+    });
+    rules ||= await loadPurposeRuleSet();
+    if (run.managed.purpose.ruleDigest !== rules.digest && run.state !== 'auto_resuming') {
+      record = await persist(current => {
+        if (!purposeEnabled(current?.run) || current.run.state === 'auto_resuming') return current;
+        current.run.managed.purpose.ruleDigest = rules.digest;
+        current.run.managed.purpose.ruleIds = rules.rules.map(rule => rule.id);
+        delete current.run.managed.purpose.lastReview;
+        if (current.run.managed.purpose.search) delete current.run.managed.purpose.search.review;
+        if (current.run.state === 'verification_pending') queuePurposeDiagnosis(current.run,
+          'Canonical controls changed. Recheck affected obligations against the existing result without repeating completed effects or asking for human rule certification.', `rules:${rules.digest}`, now);
+        return current;
+      });
+      run = record.run;
+    }
+    if (run.managed.purpose.nativeBoundary && !run.managed.resumeLease && now >= (run.managed.purpose.nativeObservedAt || 0) + 60_000) {
+      let native;try {native=await observe(()=>observeTurn(record));} catch {native={state:'unknown'};}
+      await persist(current=>{
+        if(current?.run?.id !== run.id || current.run.revision !== run.revision) return current;
+        const purpose=current.run.managed.purpose;purpose.nativeObservedAt=now;purpose.nativeObservation=native;
+        if(native.status==='completed' && native.turnId===purpose.nativeBoundary?.turnId && purpose.nativeBoundary.state!=='writer_completed_requires_verification') {
+          purpose.nativeBoundary={...purpose.nativeBoundary,state:'writer_completed_requires_verification',writer:'completed',completedTurnId:native.turnId,observedAt:now};
+          queuePurposeVerification(current.run,'Original pending turn completed; independently inspect its actual result and reconcile effects without replaying the operation.',now);
+        } else if (native.status==='completed' && native.turnId && native.turnId!==purpose.nativeBoundary?.turnId && native.turnId!==purpose.lastOwnedTurnId) {delete purpose.nativeBoundary;current.run.managed.nativeWait=null;purpose.nextSearchAt=0;}
+        return current;
+      });
+      record=await readRecord(root,record.provider,record.session);run=record.run;
+    }
+    if (searchEnabled(run.managed) && run.managed.purpose.nativeBoundary && run.state==='blocked' && !run.managed.resumeLease &&
+        ['local_edit','local_test'].includes(run.managed.decision?.action.kind) && run.managed.decision.nativeIsolationEligible === true && !run.managed.rejectedActionOverflow && !run.managed.rejectedActionDigests?.includes(createHash('sha256').update(JSON.stringify(run.managed.decision.action)).digest('hex')) &&
+        run.managed.plan?.alternatives.find(row=>row.id===run.managed.decision.selectedOptionId)?.independent &&
+        (!run.managed.purpose.candidate || run.managed.purpose.candidate.status==='ready' && run.managed.purpose.candidate.purposeRevision===run.managed.purpose.evidence.purposeRevision) && now >= (run.managed.purpose.nextCandidateAt || 0)) {
+      let candidate;
+      try {
+        const authorizeCandidate=async()=>{
+          await authorized();
+          const sandbox=run.managed.providerSandbox;
+          if(!['workspaceWrite','dangerFullAccess'].includes(sandbox?.type)) throw new Error('Original local write permission unavailable.');
+          const client=await openCodexAppServer();
+          try {const result=await client.request('config/read',{cwd:record.cwd,includeLayers:false});
+            if(!['workspace-write','danger-full-access'].includes(result?.config?.sandbox_mode)) throw new Error('Current provider write permission unavailable.');
+          } finally {await client.close();}
+        };
+        if(run.managed.purpose.candidate){
+          await authorizeCandidate();signal?.throwIfAborted();
+          candidate=run.managed.purpose.candidate;
+        } else candidate=await prepareCandidate(record,{root,signal,authorize:authorizeCandidate});
+      } catch { /* Retain native wait and investigate the missing isolation capability. */ }
+      await persist(current=>{
+        if(current?.run?.id!==run.id || current.run.revision!==run.revision || current.run.state!=='blocked') return current;
+        current.run.managed.purpose.nextCandidateAt=now+60000;
+        if(!candidate){current.run.managed.purpose.candidateGap='An authorized stable Git snapshot/current sandbox could not be confirmed. Continue read-only diagnosis.';return current;}
+        current.run.managed.purpose.candidate={...candidate,decisionId:current.run.managed.decision.id,purposeRevision:current.run.managed.purpose.evidence.purposeRevision};
+        if(!current.run.managed.purpose.evidence.units.some(unit=>unit.id===`candidate-apply:${candidate.id}:revision:${current.run.managed.purpose.evidence.purposeRevision}`)) current.run.managed.purpose.evidence.units.push({id:`candidate-apply:${candidate.id}:revision:${current.run.managed.purpose.evidence.purposeRevision}`,required:true,criterionIds:current.run.managed.acceptanceCriteria.map(row=>row.id),
+          dependsOn:[],readResources:[candidate.directory],writeResources:[candidate.original],requiredCapabilities:['exclusive_or_CAS_application'],requiredPermissions:['task'],
+          status:'waiting',evidenceRefs:[],purposeRevision:current.run.managed.purpose.evidence.purposeRevision});
+        current.run.managed.decision.outcome='execute';current.run.managed.pendingApproval=null;current.run.managed.autoRecovery=true;
+        current.run.state='recovery_required';current.run.recoveryCause='session_supervision';current.run.managed.nextAttemptAt=now;
+        return current;
+      });
+      continue;
+    }
+    // An active writer is handled exclusively by the provider lock/watchdog.
+    // Never use elapsed silence alone to assume the provider has exited.
+    let obstacle = null;
+    if (run.state === 'blocked' && run.blockerSource === 'connection' && run.managed.authenticationWait) {
+      if (now < run.managed.authenticationWait.nextCheckAt || now >= run.deadline) continue;
+      let authentication;
+      try { authentication = await observe(() => observeAuthentication()); } catch { authentication = 'unknown'; }
+      await persist(current => {
+        if (current?.run?.id !== run.id || current.run.state !== 'blocked' || current.run.revision !== run.revision || current.run.updatedAt !== run.updatedAt) return current;
+        current.run.managed.authenticationWait.nextCheckAt = now + 60_000;
+        if (authentication === 'available') {
+          const queued = queuePurposeDiagnosis(current.run, 'Configured provider login is available again. Inspect the original purpose and any interrupted action before choosing authorized work.', `authentication-restored:${run.managed.authenticationWait.since}`, now);
+          if (queued) delete current.run.managed.authenticationWait;
+        }
+        return current;
+      });
+      continue;
+    }
+    if (run.state === 'active' && !run.managed.resumeLease && now >= (run.managed.purpose.lastObservedAt || 0) + 60_000) {
+      let observed;
+      try { observed = await observe(() => observeTurn(record)); } catch { observed = { state: 'unavailable' }; }
+      await persist(current => {
+        if (current?.run?.id !== run.id || current.run.state !== 'active' || current.run.revision !== run.revision) return current;
+        current.run.managed.purpose.lastObservedAt = now;
+        current.run.managed.purpose.observationState = observed.state;
+        return current;
+      });
+      if (observed.state === 'idle') obstacle = { type: 'idle_without_checkpoint', detail: observed.turnId };
+    } else if (run.state === 'blocked' && ['missing_information', 'authorization', 'external_dependency'].includes(run.blocker)) {
+      if (run.blockerSource === 'provider' || run.managed.attempts?.at(-1)?.errorCode === 'provider_approval') {
+        if (now < (run.managed.purpose.lastObservedAt || 0) + 60_000) continue;
+        let observed;
+        try { observed = await observe(() => observeTurn(record)); } catch { observed = { state: 'unavailable' }; }
+        await persist(current => {
+          if (current?.run?.id !== run.id || current.run.state !== 'blocked' || current.run.revision !== run.revision) return current;
+          current.run.managed.purpose.lastObservedAt = now;
+          current.run.managed.purpose.observationState = observed.state;
+          if (!current.run.managed.nativeWait?.turnId && observed.turnId) current.run.managed.nativeWait = { turnId: observed.turnId, observedAt: now };
+          return current;
+        });
+        // A failed/interrupted owned turn or merely elapsed time is not a user
+        // answer. A subsequent completed original turn permits diagnosis only.
+        if (run.managed.nativeWait?.turnId && observed.status === 'completed' && observed.turnId !== run.managed.nativeWait.turnId) {
+          await persist(current => {
+            if (current?.run?.id === run.id && current.run.revision === run.revision) {
+              current.run.managed.nativeWait = null;
+              delete current.run.managed.purpose.nativeBoundary;
+            }
+            return current;
+          });
+          run.managed.nativeWait = null;
+          delete run.managed.purpose.nativeBoundary;
+          obstacle = { type: 'native_wait_updated', detail: observed.turnId };
+        } else if (searchEnabled(run.managed)) {
+          obstacle = { type: 'native_wait_diagnosis', detail: run.managed.nativeWait?.turnId || 'writer_unknown' };
+        } else continue;
+      } else if (now >= (run.managed.purpose.lastObservedAt || 0) + 60_000) {
+        let observed;
+        try { observed = await observe(() => observeTurn(record)); } catch { observed = { state: 'unavailable' }; }
+        const previousTurn = run.managed.purpose.lastObservedTurnId || run.managed.purpose.lastOwnedTurnId;
+        await persist(current => {
+          if (current?.run?.id !== run.id || current.run.state !== 'blocked' || current.run.revision !== run.revision) return current;
+          current.run.managed.purpose.lastObservedAt = now;
+          current.run.managed.purpose.observationState = observed.state;
+          if (observed.status === 'completed') current.run.managed.purpose.lastObservedTurnId = observed.turnId;
+          return current;
+        });
+        // A fresh completed original-chat turn can contain an answer or new
+        // evidence. It permits research, not automatic permission approval.
+        // Never treat our own diagnostic checkpoint as an external update.
+        if (previousTurn && observed.status === 'completed' && observed.turnId !== previousTurn &&
+            observed.turnId !== run.managed.purpose.lastOwnedTurnId) obstacle = { type: 'original_context_updated', detail: observed.turnId };
+      }
+
+      if (!obstacle && run.blocker === 'external_dependency' && now < Math.max((run.managed.dependencyWait?.createdAt || run.updatedAt) + 60_000, run.managed.purpose.nextDependencyCheckAt || 0)) continue;
+      obstacle ||= { type: run.blocker, detail: run.managed.understandingQuestion?.text || run.managed.userQuestion ||
+        run.managed.dependencyWait?.condition || run.managed.pendingApproval?.summary || run.reason };
+    } else if (run.state === 'verification_pending') {
+      if (searchEnabled(run.managed) && (run.managed.purpose.search?.review?.passed || run.managed.purpose.search?.review?.needsHuman) && effectiveAcceptanceCriteria(run.managed).filter(c => !run.managed.verified[c.id]).every(c => c.check.type === 'manual')) continue;
+      obstacle = { type: 'verification', detail: run.managed.acceptanceCriteria.filter(c => !run.managed.verified[c.id]).map(c => c.id).join(',') };
+    } else if (run.state === 'recovery_required' && ['provider_error', 'process_exit', 'shutdown_cancelled', 'interrupted_owner'].includes(run.recoveryCause) &&
+        !run.managed.autoRecovery && now >= run.updatedAt + 15_000) {
+      const code = run.managed.attempts?.at(-1)?.errorCode;
+      if (code && !['checkpoint', 'checkpoint_rejected', 'closed', 'timeout', 'unavailable', 'turn_failed', 'provider_error', ...(searchEnabled(run.managed) ? ['permission_narrowed', 'manual_provider_action', 'unsupported'] : [])].includes(code)) continue;
+      obstacle = { type: 'execution_error', detail: code || run.recoveryCause };
+    }
+    if (!obstacle) continue;
+    const key = createHash('sha256').update(JSON.stringify([run.managed.verifiedRevision, obstacle, obstacle.type === 'external_dependency' ? run.managed.purpose.dependencyChecks || 0 : null])).digest('hex');
+    await persist(current => {
+      if (current?.run?.id !== run.id || current.run.revision !== run.revision || current.run.state !== run.state || current.run.updatedAt !== run.updatedAt) return current;
+      if (searchEnabled(current.run.managed) && ['original_context_updated', 'native_wait_updated'].includes(obstacle.type)) current.run.managed.purpose.nextSearchAt = 0;
+      const queued = queuePurposeDiagnosis(current.run,
+        `Reassess the original purpose after ${obstacle.type}: ${obstacle.detail}. Gather evidence before deciding that a person is needed. Preserve unresolved approvals/dependencies; choose independent work or a safe alternative where possible.`, key, now);
+      if (queued && obstacle.type === 'external_dependency') {
+        const purpose = current.run.managed.purpose;
+        purpose.dependencyChecks = (purpose.dependencyChecks || 0) + 1;
+        purpose.nextDependencyCheckAt = now + Math.min(15 * 60_000, 60_000 * 2 ** Math.min(4, purpose.dependencyChecks));
+      }
+      return current;
+    });
+    } catch (error) {
+      if (!/^Delivery state (?:is busy; retry the command\.|lock owner is unavailable; inspect the lock before retrying\.)$/.test(error.message)) throw error;
+      // One unavailable record cannot prevent independent conversations from
+      // progressing. Never delete or reclaim an ambiguous writer lock.
+      deferred.push({ provider: record.provider, session: record.session, reason: 'record_busy' });
+    }
+  }
+  return { deferred };
+}