great-cto 3.46.2 → 3.48.0

package/board/scripts/lib/work-decisions.mjs

@@ -0,0 +1,33 @@
+/** Host-owned approval adapter. Ordinary resume never approves a proposal. */
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { readWorkTask, beginWork, finishWork, publicWorkTask } from './work-tasks.mjs';
+export function decisionCapabilities(task) {
+  const busy = task.operations.some(o => o.state === 'running');
+  return publicWorkTask(task).decisions.map(d => ({ ...d, capability: {
+    action: d.engine === 'codex' ? 'approve' : 'native_host',
+    enabled: !busy && !['stale', 'unverifiable'].includes(d.bindingState) && d.engine === 'codex' && task.managed !== false,
+    reason: d.bindingState === 'stale' ? 'Proposal receipt is stale; refresh it inside its host' : busy ? 'Operation owns this task' : d.engine === 'claude-code' ? 'Native permission and pipeline decisions stay inside the bound Claude session' : null,
+  } }));
+}
+export function approveWorkDecision({ root, taskId, decisionId, expectedRevision, operationId }, { execute = spawnSync, ...options } = {}) {
+  if (!Number.isInteger(expectedRevision) || expectedRevision < 1 || !/^[0-9a-f]{64}$/.test(decisionId || '')) throw Error('approval requires a decision identity and revision');
+  const task = readWorkTask(taskId, { ...options, root });
+  if (task.host !== 'codex') throw Error('native host approval has no remote capability; respond inside Claude');
+  const work = beginWork({ root, taskId, host: task.host, kind: 'approve', expectedRevision, operationId, data: { decisionId } }, options);
+  if (work.replay) return publicWorkTask(work.task);
+  try {
+    if (task.links.runs.length !== 1 || !(task.decisions || []).some(d => d.decisionId === decisionId)) throw Error('decision is missing, stale or ambiguous');
+    const controller = fileURLToPath(new URL('../codex-pipeline.mjs', import.meta.url));
+    const result = execute(process.execPath, [controller, 'approve-task', task.links.runs[0], '--decision', decisionId, '--operation', work.operation.operationId],
+      { encoding: 'utf8', env: { ...process.env, ...(options.store ? { GREAT_CTO_TASKS_DIR: options.store } : {}), GREAT_CTO_WORK_LEASE: work.lease.token } });
+    const code = result.error ? 2 : result.status ?? 2;
+    finishWork(taskId, work.operation.operationId, code, { ...options, root });
+    if (code !== 0) throw Error('host refused approval: ' + String(result.stderr || result.error?.message || 'inspect host state').trim().slice(0, 500));
+    return publicWorkTask(readWorkTask(taskId, { ...options, root }));
+  } catch (e) {
+    const latest = readWorkTask(taskId, { ...options, root });
+    if (latest.operations.find(o => o.operationId === work.operation.operationId)?.state === 'running') finishWork(taskId, work.operation.operationId, 2, { ...options, root });
+    throw e;
+  } finally { work.lease.release(); }
+}

package/board/scripts/lib/work-metrics.mjs

@@ -0,0 +1,31 @@
+/** Cohort measurements are evidence; they do not change authority or auto-approve. */
+const median = values => { const s = values.filter(Number.isFinite).sort((a,b) => a-b); return !s.length ? null : s.length % 2 ? s[(s.length-1)/2] : (s[s.length/2-1]+s[s.length/2])/2; };
+export function measureWork(tasks) {
+  const cohorts = [];
+  for (const host of ['claude-code', 'codex']) for (const intent of ['delivery', 'research']) {
+    const rows = tasks.filter(t => t.host === host && (t.intent || 'delivery') === intent);
+    const resumes = rows.flatMap(t => t.operations.filter(o => o.kind === 'resume' && o.state === 'host_returned'));
+    const known = resumes.filter(o => o.resume?.state && o.resume.state !== 'unobserved');
+    const reasons = {};
+    for (const t of rows) for (const [kind, count] of Object.entries(t.metrics?.interruptions || {})) reasons[kind] = (reasons[kind] || 0) + count;
+    const technical = Object.entries(reasons).filter(([kind]) => !['host_approval','native_pipeline_approval','native_permission_or_input'].includes(kind)).reduce((n, [,v]) => n+v, 0);
+    cohorts.push({ host, intent, tasks: rows.length, observedStarts: rows.filter(t => Number.isFinite(t.metrics?.timeToObservedStartMs)).length,
+      medianTimeToObservedStartMs: median(rows.map(t => t.metrics?.timeToObservedStartMs)), interruptions: reasons,
+      technicalInterruptionsPerTask: rows.length ? technical/rows.length : null, resumes: resumes.length, knownResumes: known.length,
+      progressedResumes: known.filter(o => o.resume.state === 'progressed').length,
+      resumeProgressRate: known.length ? known.filter(o => o.resume.state === 'progressed').length / known.length : null,
+      completed: rows.filter(t => t.phase === 'completed').length, blocked: rows.filter(t => t.phase === 'blocked').length,
+      verificationRework: rows.reduce((n,t) => n + (t.rework?.attempts || 0), 0) });
+  }
+  return { schemaVersion: 1, observation: 'task-stage-progress, not model latency or production defect rate', cohorts };
+}
+export function compareWork(current, baseline, { minTasks = 20, minKnownResumes = 5 } = {}) {
+  if (!Number.isInteger(minTasks) || minTasks < 1 || !Number.isInteger(minKnownResumes) || minKnownResumes < 1) throw Error('invalid comparison sample policy');
+  return { automaticAuthorityChanges: false, cohorts: current.cohorts.map(c => {
+    const b = baseline?.cohorts?.find(x => x.host === c.host && x.intent === c.intent);
+    const sufficient = !!b && c.tasks >= minTasks && b.tasks >= minTasks && c.knownResumes >= minKnownResumes && b.knownResumes >= minKnownResumes
+      && Number.isFinite(c.technicalInterruptionsPerTask) && Number.isFinite(b.technicalInterruptionsPerTask) && Number.isFinite(c.resumeProgressRate) && Number.isFinite(b.resumeProgressRate);
+    return { host: c.host, intent: c.intent, state: !sufficient ? 'insufficient_evidence' : c.technicalInterruptionsPerTask < b.technicalInterruptionsPerTask && c.resumeProgressRate >= b.resumeProgressRate ? 'candidate_for_review' : 'no_measured_improvement',
+      reason: !sufficient ? 'Matched host/intent baseline and known resume sample are required' : 'Measurement can recommend review; safety, defect evidence and authority still require separate decisions' };
+  }) };
+}

package/board/scripts/lib/work-outcomes.mjs

@@ -0,0 +1,78 @@
+/** Explicit operator attestations, bound to criteria, actual bytes and host state. */
+import { readFileSync, lstatSync, realpathSync } from 'node:fs';
+import { resolve, relative, isAbsolute, sep, join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { treeReceipt } from './receipt.mjs';
+import { codexRunStore } from './codex-host-state.mjs';
+import { assertExternal, readWorkTask, mutateWorkTask, beginWork, finishWork, publicWorkTask } from './work-tasks.mjs';
+const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+export function readOutcomeEvidence(root, file) {
+  const path = resolve(file); assertExternal(root, path);
+  const info = lstatSync(path);
+  if (!info.isFile() || info.isSymbolicLink() || (info.mode & 0o077) || info.size > 65536) throw Error('evidence must be an external private regular file (0600, <=64 KiB)');
+  const raw = readFileSync(path); return { document: JSON.parse(raw), digest: hash(raw) };
+}
+function artifact(root, path) {
+  if (typeof path !== 'string' || !path || isAbsolute(path) || path.split(/[\\/]/).includes('..') || path.includes('\\')) throw Error('invalid outcome artifact path');
+  const resolved = resolve(root, path), actual = realpathSync(resolved), rel = relative(root, actual);
+  if (actual !== resolved || !rel || rel === '..' || rel.startsWith('..' + sep) || isAbsolute(rel) || !lstatSync(actual).isFile()) throw Error('outcome artifact must be a project regular file without symlinks');
+  return { path, sha256: hash(readFileSync(actual)) };
+}
+export function assertHostSettled(task, { runsStore = codexRunStore() } = {}) {
+  if ((task.decisions || []).length || ['working', 'needs_decision', 'publishing', 'cancelled', 'blocked'].includes(task.phase)) throw Error('host state is not settled for acceptance');
+  if (task.host === 'claude-code') {
+    if (task.links.sessions.length !== 1 || (task.managed === false && !task.nativeSessionEnded)) throw Error('native session ownership is not settled');
+    return;
+  }
+  if (task.links.runs.length !== 1) throw Error('controlled run link is missing or ambiguous');
+  const id = task.links.runs[0], path = join(runsStore, id + '.json'), info = lstatSync(path);
+  if (info.isSymbolicLink() || (info.mode & 0o077)) throw Error('unsafe controlled run state');
+  const run = JSON.parse(readFileSync(path, 'utf8'));
+  if (run.id !== id || run.taskId !== task.taskId || run.root !== task.root || run.status !== 'done' || run.active || run.pending || run.wave?.status === 'running') throw Error('controlled run has not reached a settled terminal state');
+  if (run.release && (run.release.status !== 'verified' || run.release.smoke?.state !== 'passed')) throw Error('release has no verified publication/smoke evidence');
+}
+function verifyDocument(task, document) {
+  if (!document || document.taskId !== task.taskId || document.goal !== task.goal || document.revision !== task.revision
+    || document.kind !== (task.intent || 'delivery') || document.goalSatisfied !== true || !task.acceptance.length) throw Error('evidence must bind task, goal, revision, intent and explicit criteria');
+  if (!Array.isArray(document.criteria) || document.criteria.length !== task.acceptance.length
+    || document.criteria.some((c, i) => !c || c.index !== i || c.text !== task.acceptance[i] || c.state !== 'passed' || typeof c.evidence !== 'string' || !c.evidence.trim())) throw Error('each acceptance criterion needs ordered, explicit passing evidence');
+  if (!Array.isArray(document.artifacts) || !document.artifacts.length || new Set(document.artifacts.map(a => a?.path)).size !== document.artifacts.length) throw Error('unique outcome artifacts are required');
+  const artifacts = document.artifacts.map(a => {
+    const current = artifact(task.root, a.path);
+    if (a.sha256 !== current.sha256) throw Error('outcome artifact bytes do not match evidence');
+    if (task.intent === 'research' && !/^(docs|research|reports)\//.test(a.path)) throw Error('research outcomes contain reports, not implementation artifacts');
+    return current;
+  });
+  const receipt = treeReceipt(task.root);
+  if (!receipt) throw Error('outcome evidence requires a readable Git receipt');
+  return { kind: document.kind, state: 'verified', source: 'operator-attestation', evidenceDigest: hash(JSON.stringify(document)), receipt,
+    artifacts, criteria: document.criteria, verifiedAt: new Date().toISOString() };
+}
+export function applyOutcome({ root, taskId, kind, expectedRevision, operationId, evidenceFile }, options = {}) {
+  if (!['verify', 'complete'].includes(kind) || !Number.isInteger(expectedRevision)) throw Error('verify/complete require an explicit revision');
+  const task = readWorkTask(taskId, { ...options, root });
+  const evidence = kind === 'verify' ? readOutcomeEvidence(root, evidenceFile) : null;
+  const work = beginWork({ root, host: task.host, taskId, kind, expectedRevision, operationId,
+    data: evidence ? { evidenceDigest: evidence.digest } : null }, options);
+  if (work.replay) return publicWorkTask(work.task);
+  try {
+    assertHostSettled(task, options);
+    const current = readWorkTask(taskId, { ...options, root });
+    if (kind === 'verify') {
+      const outcome = verifyDocument(task, evidence.document);
+      mutateWorkTask(taskId, t => { t.outcome = outcome; t.phase = 'verified'; t.reason = 'Criteria and artifact identity recorded by explicit operator attestation'; }, { ...options, root });
+    } else {
+      const outcome = current.outcome;
+      if (current.phase !== 'verified' || outcome?.state !== 'verified' || !same(treeReceipt(root), outcome.receipt)) throw Error('verified outcome is missing or its tree receipt is stale');
+      for (const a of outcome.artifacts) if (artifact(task.root, a.path).sha256 !== a.sha256) throw Error('verified outcome artifact changed');
+      mutateWorkTask(taskId, t => { t.outcome.state = 'completed'; t.outcome.completedAt = new Date().toISOString(); t.phase = 'completed'; t.reason = 'Explicit completion of the verified requested outcome'; }, { ...options, root });
+    }
+    finishWork(taskId, work.operation.operationId, 0, { ...options, root });
+    return publicWorkTask(readWorkTask(taskId, { ...options, root }));
+  } catch (error) {
+    if (readWorkTask(taskId, { ...options, root }).operations.find(o => o.operationId === work.operation.operationId)?.state === 'running') finishWork(taskId, work.operation.operationId, 2, { ...options, root });
+    throw error;
+  }
+  finally { work.lease.release(); }
+}

package/board/scripts/lib/work-tasks.mjs

@@ -0,0 +1,302 @@
+/** Operator-owned intent and execution receipts, outside worker projects. */
+import { mkdirSync, readFileSync, writeFileSync, renameSync, readdirSync, realpathSync, rmSync, existsSync, lstatSync } from 'node:fs';
+import { join, resolve, relative, isAbsolute, sep, basename, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { treeReceipt } from './receipt.mjs';
+import { createHash, randomUUID } from 'node:crypto';
+
+export const workTaskStore = () => process.env.GREAT_CTO_TASKS_DIR || join(homedir(), '.great_cto', 'work-tasks');
+export const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const hosts = new Set(['codex', 'claude-code']);
+const digest = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+export const projectIdentity = root => 'project:' + createHash('sha256').update(realpathSync(root)).digest('hex');
+const canonical = root => realpathSync(root);
+const fileFor = (store, id) => { if (!UUID.test(id || '')) throw Error('invalid task UUID'); return join(store, `${id}.json`); };
+export function assertExternal(root, store) {
+  let actual = resolve(store), suffix = [];
+  while (!existsSync(actual)) { suffix.unshift(basename(actual)); actual = dirname(actual); }
+  actual = join(realpathSync(actual), ...suffix);
+  const rel = relative(canonical(root), actual);
+  if (!rel || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel))) throw Error('task store must be operator-owned outside the worker project');
+  if (existsSync(store) && lstatSync(store).isSymbolicLink()) throw Error('task store cannot be a symlink');
+}
+function ensureStore(root, store) { assertExternal(root, store); mkdirSync(store, { recursive: true, mode: 0o700 }); if (lstatSync(store).mode & 0o077) throw Error('task store permissions must be 0700'); }
+function validate(t) {
+  if (!t || t.schemaVersion !== 1 || !UUID.test(t.taskId) || !hosts.has(t.host) || typeof t.root !== 'string'
+    || typeof t.goal !== 'string' || !Array.isArray(t.acceptance) || t.acceptance.some(v => typeof v !== 'string')
+    || !Number.isInteger(t.revision) || t.revision < 1 || !Array.isArray(t.operations)
+    || t.operations.some(o => !o || !UUID.test(o.operationId) || typeof o.requestDigest !== 'string' || !['start', 'resume', 'approve', 'verify', 'complete'].includes(o.kind) || !['running', 'host_returned'].includes(o.state))
+    || !Array.isArray(t.links?.runs) || t.links.runs.some(id => !UUID.test(id))
+    || !Array.isArray(t.links?.sessions) || t.links.sessions.some(id => !UUID.test(id))
+    || !Array.isArray(t.links?.issues) || t.links.issues.some(id => typeof id !== 'string')
+    || !Array.isArray(t.observations) || !Array.isArray(t.evidence) || !t.metrics || typeof t.metrics.interruptions !== 'object'
+    || !['accepted', 'working', 'needs_decision', 'blocked', 'waiting', 'unknown', 'cancelled', 'verified', 'publishing', 'completed'].includes(t.phase)) throw Error('invalid task state');
+  if (t.intent !== undefined && !['delivery', 'research'].includes(t.intent)) throw Error('invalid task intent');
+  if (t.decisions !== undefined && (!Array.isArray(t.decisions) || t.decisions.some(d => !d || !/^[0-9a-f]{64}$/.test(d.decisionId) || !['codex', 'claude-code'].includes(d.engine)))) throw Error('invalid task decisions');
+  if (t.outcome && (!['research', 'delivery'].includes(t.outcome.kind) || !['verified', 'completed'].includes(t.outcome.state) || !Array.isArray(t.outcome.artifacts) || !Array.isArray(t.outcome.criteria))) throw Error('invalid task outcome');
+  return t;
+}
+export function readWorkTask(id, { store = workTaskStore(), root = null } = {}) {
+  const file = fileFor(store, id);
+  const info = lstatSync(file);
+  if (info.isSymbolicLink()) throw Error('task state cannot be a symlink');
+  if (info.mode & 0o077) throw Error('task state permissions must be 0600');
+  const t = validate(JSON.parse(readFileSync(file, 'utf8')));
+  if (t.taskId !== id || (root && canonical(t.root) !== canonical(root))) throw Error('task does not belong to this project');
+  return t;
+}
+export function listWorkTasks(root, { store = workTaskStore() } = {}) {
+  assertExternal(root, store);
+  if (existsSync(store) && (lstatSync(store).mode & 0o077)) throw Error('task store permissions must be 0700');
+  const projectRoot = canonical(root); let names;
+  try { names = readdirSync(store); } catch (e) { if (e.code === 'ENOENT') return { state: 'absent', tasks: [], unreadable: 0 }; throw e; }
+  const tasks = []; let unreadable = 0;
+  for (const name of names.filter(n => UUID.test(n.replace(/\.json$/, '')) && n.endsWith('.json')).sort()) {
+    try {
+      const t = readWorkTask(name.slice(0, -5), { store });
+      if (t.root === projectRoot) tasks.push(t);
+    } catch { unreadable++; }
+  }
+  return { state: unreadable ? 'degraded' : 'ok', tasks, unreadable };
+}
+function save(t, store) {
+  const file = fileFor(store, t.taskId), tmp = `${file}.${randomUUID()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(t, null, 2), { mode: 0o600 }); renameSync(tmp, file);
+}
+export function mutateWorkTask(id, fn, { store = workTaskStore(), root = null } = {}) {
+  const lock = `${fileFor(store, id)}.write-lock`; let acquired = false;
+  for (let i = 0; i < 10; i++) {
+    try { mkdirSync(lock, { mode: 0o700 }); acquired = true; break; }
+    catch (e) { if (e.code !== 'EEXIST') throw e; Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 15); }
+  }
+  if (!acquired) throw Error('task metadata is owned by another writer; inspect the write lock');
+  try {
+    const t = readWorkTask(id, { store, root });
+    if (fn(t) === false) return t;
+    t.revision++; t.updatedAt = new Date().toISOString(); save(t, store); return t;
+  } finally { rmSync(lock, { recursive: true }); }
+}
+
+export function acquireProjectLease(root, { store = workTaskStore(), reuseToken = null } = {}) {
+  root = canonical(root); ensureStore(root, store);
+  const dir = join(store, 'leases'); mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const lock = join(dir, digest(root) + '.lock');
+  if (reuseToken) {
+    const owner = JSON.parse(readFileSync(join(lock, 'owner.json'), 'utf8'));
+    if (owner.token !== reuseToken || owner.pid !== process.ppid || owner.projectId !== projectIdentity(root)) throw Error('invalid project lease handoff');
+    return { token: owner.token, release() {} };
+  }
+  try { mkdirSync(lock, { mode: 0o700 }); }
+  catch (e) { if (e.code === 'EEXIST') throw Error('project execution is already owned; inspect its lease before recovery'); throw e; }
+  const token = randomUUID();
+  try { writeFileSync(join(lock, 'owner.json'), JSON.stringify({ token, pid: process.pid, projectId: projectIdentity(root), acquiredAt: new Date().toISOString() }), { mode: 0o600 }); }
+  catch (e) { rmSync(lock, { recursive: true }); throw e; }
+  return { token, release() {
+    const owner = JSON.parse(readFileSync(join(lock, 'owner.json'), 'utf8'));
+    if (owner.token !== token || owner.pid !== process.pid) throw Error('project lease ownership changed');
+    rmSync(lock, { recursive: true });
+  } };
+}
+
+function newTaskRecord({ root, host, goal, acceptance = [], authority = null, intent = 'delivery', maxAttempts = 3 }) {
+  const now = new Date().toISOString();
+  return { schemaVersion: 1, taskId: randomUUID(), root, managed: true, projectId: projectIdentity(root), host,
+        goal: goal.trim(), acceptance: [...acceptance], authority, intent,
+        budget: { maxStageAttempts: host === 'codex' ? maxAttempts : null, authority: 'host-owned' },
+        stage: null, decisions: [], outcome: null, activity: [],
+        revision: 1, createdAt: now, updatedAt: now, phase: 'accepted', reason: null,
+        links: { runs: [], sessions: [], issues: [] }, operations: [], observations: [], evidence: [],
+        metrics: { firstObservedStartAt: null, timeToObservedStartMs: null, interruptions: {} } };
+}
+
+export function beginWork({ root, host, kind = 'start', goal = null, acceptance = [], authority = null,
+  taskId = null, operationId = randomUUID(), expectedRevision = null, intent = 'delivery', maxAttempts = 3, data = null }, { store = workTaskStore() } = {}) {
+  root = canonical(root);
+  if (!hosts.has(host) || !['start', 'resume', 'approve', 'verify', 'complete'].includes(kind) || !UUID.test(operationId)) throw Error('invalid work operation');
+  if (kind === 'start' && (typeof goal !== 'string' || !goal.trim() || !Array.isArray(acceptance) || acceptance.some(v => typeof v !== 'string' || !v.trim()))) throw Error('goal and acceptance must be explicit strings');
+  if (!['delivery', 'research'].includes(intent) || !Number.isInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > 5) throw Error('invalid intent or stage attempt budget');
+  const requestDigest = digest({ root, host, kind, goal, acceptance, authority, taskId, expectedRevision, intent, maxAttempts, data });
+  const legacyDigest = digest({ root, host, kind, goal, acceptance, authority, taskId, expectedRevision });
+  const matchesRequest = (t, op) => op.requestDigest === requestDigest || (t.intent == null && intent === 'delivery' && maxAttempts === 3 && data === null && op.requestDigest === legacyDigest);
+  const prior = listWorkTasks(root, { store });
+  if (prior.state === 'degraded') throw Error('task state is unreadable; selection is blocked');
+  for (const t of prior.tasks) {
+    const op = t.operations.find(o => o.operationId === operationId);
+    if (!op) continue;
+    if (!matchesRequest(t, op)) throw Error('idempotency key conflicts with another request');
+    return { task: t, operation: op, replay: true, lease: null };
+  }
+  const lease = acquireProjectLease(root, { store });
+  try {
+    const underLease = listWorkTasks(root, { store });
+    if (underLease.state === 'degraded') throw Error('task state is unreadable');
+    for (const t of underLease.tasks) {
+      const existing = t.operations.find(o => o.operationId === operationId);
+      if (existing) {
+        if (!matchesRequest(t, existing)) throw Error('idempotency key conflicts with another request');
+        lease.release(); return { task: t, operation: existing, replay: true, lease: null };
+      }
+    }
+    const now = new Date().toISOString(); let task;
+    if (kind !== 'start') {
+      task = readWorkTask(taskId, { store, root });
+      if (kind === 'resume' && task.managed === false) throw Error('observed native session has no managed ownership; resume inside its native host');
+      if (['cancelled', 'completed'].includes(task.phase)) throw Error('terminal task cannot resume');
+      if (task.operations.some(o => o.state === 'running')) throw Error('previous host operation is not reconciled; inspect it before resume');
+      if (task.host !== host) throw Error('task host cannot change during resume');
+      if (expectedRevision !== null && task.revision !== expectedRevision) throw Error('stale task revision; refresh before resume');
+    } else {
+      task = newTaskRecord({ root, host, goal, acceptance, authority, intent, maxAttempts });
+      save(task, store);
+    }
+    const operation = { operationId, requestDigest, kind, data, state: 'running', startedAt: now, finishedAt: null, exitCode: null,
+      baseline: kind === 'resume' ? (task.activity || []).map(a => a.id) : null };
+    task = mutateWorkTask(task.taskId, t => { t.operations.push(operation); }, { store, root });
+    return { task, operation, replay: false, lease };
+  } catch (e) { lease.release(); throw e; }
+}
+export function finishWork(taskId, operationId, exitCode, { store = workTaskStore(), root = null } = {}) {
+  return mutateWorkTask(taskId, t => {
+    const op = t.operations.find(o => o.operationId === operationId);
+    if (!op || op.state !== 'running') throw Error('operation is not running');
+    op.state = 'host_returned'; op.exitCode = exitCode; op.finishedAt = new Date().toISOString();
+    if (op.kind === 'resume') {
+      const advanced = (t.activity || []).filter(a => !(op.baseline || []).includes(a.id) && ['verified_stage', 'native_stage_result'].includes(a.kind));
+      op.resume = { state: advanced.length ? 'progressed' : t.phase === 'needs_decision' ? 'waiting_decision' : t.phase === 'blocked' ? 'blocked' : 'unobserved', evidence: advanced.map(a => a.id) };
+    }
+    // Host exit does not prove acceptance, and absence of hooks does not prove progress.
+    if (['start', 'resume'].includes(op.kind) && (!t.observations.length || (t.host === 'claude-code' && t.phase === 'working'))) { t.phase = exitCode === 0 ? 'unknown' : 'blocked'; t.reason = 'Host returned; no execution observation recorded'; }
+  }, { store, root });
+}
+export function linkWork(taskId, type, id, { store = workTaskStore(), root, host } = {}) {
+  if (!['runs', 'sessions', 'issues'].includes(type) || typeof id !== 'string' || !id) throw Error('invalid host link');
+  if (type !== 'issues' && !UUID.test(id)) throw Error('invalid execution UUID');
+  return mutateWorkTask(taskId, t => {
+    if (host && t.host !== host) throw Error('host link mismatch');
+    if (t.links[type].includes(id)) return false;
+    t.links[type].push(id);
+  }, { store, root });
+}
+function observe(t, { phase, reason = null, kind, at = new Date().toISOString() }) {
+  if (t.phase === phase && t.reason === reason && t.observations.at(-1)?.kind === kind) return false;
+  if (['verified', 'completed'].includes(t.phase)) { t.outcome = null; }
+  t.phase = phase; t.reason = reason; t.observations.push({ kind, phase, reason, at });
+  if (phase === 'working' && !t.metrics.firstObservedStartAt) {
+    t.metrics.firstObservedStartAt = at; t.metrics.timeToObservedStartMs = Math.max(0, Date.parse(at) - Date.parse(t.createdAt));
+  }
+  if (['needs_decision', 'blocked'].includes(phase) && kind !== 'native_session') t.metrics.interruptions[kind] = (t.metrics.interruptions[kind] || 0) + 1;
+}
+export function observeWorkRun(state, { store = workTaskStore() } = {}) {
+  if (!state.taskId) return null;
+  return mutateWorkTask(state.taskId, t => {
+    if (t.phase === 'completed') return false;
+    if (t.host !== 'codex' || !t.links.runs.includes(state.id)) throw Error('run is not linked to task');
+    let evidenceChanged = false;
+    const started = (state.attempts || []).find(a => a.startedAt)?.startedAt;
+    if (started && !t.metrics.firstObservedStartAt) {
+      evidenceChanged = true;
+      t.metrics.firstObservedStartAt = started; t.metrics.timeToObservedStartMs = Math.max(0, Date.parse(started) - Date.parse(t.createdAt));
+    }
+    const status = state.status;
+    const phase = ['blocked', 'manual-action', 'join-wait'].includes(status) ? 'blocked' : state.active || state.wave?.status === 'running' ? 'working'
+      : ['awaiting-gate', 'awaiting-release'].includes(status) ? 'needs_decision'
+      : status === 'blocked' || status === 'manual-action' || status === 'join-wait' ? 'blocked'
+      : status === 'done' ? 'waiting' : status === 'cancelled' ? 'cancelled' : 'accepted';
+    const reason = status === 'done' ? 'Run finished; acceptance evidence must still be recorded'
+      : state.reason || (phase === 'needs_decision' ? 'Host approval required' : null);
+    t.stage = state.active || state.pending?.role || state.queue?.[0] || null;
+    const nextDecisions = controlledDecisions(state);
+    evidenceChanged ||= JSON.stringify(nextDecisions) !== JSON.stringify(t.decisions || []);
+    t.decisions = nextDecisions;
+    t.activity ||= [];
+    for (const [role, r] of Object.entries(state.results || {})) {
+      if (r.verification?.state !== 'verified' || !r.digest || !r.receipt) continue;
+      const id = digest({ run: state.id, role, result: r.digest });
+      if (!t.activity.some(a => a.id === id)) { t.activity.push({ id, kind: 'verified_stage', role, at: r.at || new Date().toISOString() }); evidenceChanged = true; }
+    }
+    t.rework = { attempts: (state.attempts || []).filter(a => a.status === 'rework').length, maxStageAttempts: state.maxAttempts ?? null };
+    const nextEvidence = Object.entries(state.results || {}).map(([role, r]) => ({ role, verdict: r.verdict || null, verified: r.verification?.state === 'verified' }));
+    evidenceChanged ||= JSON.stringify(nextEvidence) !== JSON.stringify(t.evidence);
+    t.evidence = nextEvidence;
+    const observed = observe(t, { phase, reason, kind: phase === 'needs_decision' ? 'host_approval' : status === 'manual-action' ? 'manual_action' : 'controlled_run' });
+    return observed === false && !evidenceChanged ? false : undefined;
+  }, { store, root: state.root });
+}
+export function registerNativeStart(payload, { store = workTaskStore() } = {}) {
+  if (payload?.hook_event_name !== 'UserPromptSubmit' || !UUID.test(payload.session_id || '')) return null;
+  const match = String(payload.prompt || '').match(/^\/(?:great[-_]cto:)?(start|audit)\s+([\s\S]+)$/);
+  if (!match || !match[2].trim()) return null;
+  const root = canonical(payload.cwd), lease = acquireProjectLease(root, { store });
+  try {
+    const listing = listWorkTasks(root, { store });
+    if (listing.state === 'degraded') throw Error('task state is unreadable');
+    if (listing.tasks.some(t => !['completed', 'cancelled'].includes(t.phase) && t.links.sessions.includes(payload.session_id))) return null;
+    const task = newTaskRecord({ root, host: 'claude-code', goal: match[2], intent: match[1] === 'audit' ? 'research' : 'delivery',
+      authority: { mode: 'native-interactive', writeScope: null } });
+    task.managed = false; task.links.sessions.push(payload.session_id);
+    observe(task, { phase: 'working', kind: 'native_session' }); save(task, store); return task;
+  } finally { lease.release(); }
+}
+export function observeWorkSession(payload, { store = workTaskStore() } = {}) {
+  if (!UUID.test(payload?.session_id || '') || !payload.cwd) return null;
+  const listing = listWorkTasks(payload.cwd, { store });
+  if (listing.state === 'degraded') throw Error('task metadata is unreadable');
+  let tasks = listing.tasks.filter(t => t.host === 'claude-code' && !['completed', 'cancelled'].includes(t.phase) && t.links.sessions.includes(payload.session_id));
+  if (!tasks.length) { const registered = registerNativeStart(payload, { store }); if (registered) return registered; }
+  if (tasks.length !== 1) return null;
+  const event = payload.hook_event_name;
+  const phase = event === 'UserPromptSubmit' ? 'working' : event === 'Notification' ? 'needs_decision'
+    : ['Stop', 'SessionEnd'].includes(event) ? 'waiting' : null;
+  if (!phase) return null;
+  return mutateWorkTask(tasks[0].taskId, t => {
+    if (event === 'Notification') t.decisions = [{ decisionId: digest({ session: payload.session_id, notification: String(payload.message || ''), type: payload.notification_type || null }), engine: 'claude-code', kind: 'native_input', sessionId: payload.session_id, state: 'pending', action: 'native_host', label: 'Respond inside the linked Claude session' }];
+    else if (event === 'UserPromptSubmit') t.decisions = (t.decisions || []).filter(d => d.kind === 'pipeline_gate');
+    if (event === 'SessionEnd') t.nativeSessionEnded = true;
+    return observe(t, { phase: (t.decisions || []).length ? 'needs_decision' : phase,
+    reason: event === 'Notification' ? String(payload.message || 'Native host input required').slice(0, 300) : null,
+    kind: event === 'Notification' ? 'native_permission_or_input' : 'native_session' }); }, { store, root: payload.cwd });
+}
+export function publicWorkTask(t) {
+  return { schemaVersion: 1, taskId: t.taskId, projectId: t.projectId, managed: t.managed, host: t.host, goal: t.goal,
+    acceptance: t.acceptance, authority: t.authority, intent: t.intent || 'delivery', budget: t.budget || null, stage: t.stage || null,
+    decisions: (t.decisions || []).map(({ receipt, ...d }) => ({ ...d, ...(['pipeline_gate', 'gate', 'release'].includes(d.kind) ? { bindingState: !receipt ? (d.bindingState || 'unverifiable') : JSON.stringify(treeReceipt(t.root)) === JSON.stringify(receipt) ? 'current' : 'stale' } : {}) })), outcome: t.outcome ? { source: t.outcome.source, kind: t.outcome.kind, state: t.outcome.state, verifiedAt: t.outcome.verifiedAt, completedAt: t.outcome.completedAt || null, artifacts: t.outcome.artifacts, criteria: t.outcome.criteria } : null, rework: t.rework || null, revision: t.revision, phase: t.phase, reason: t.reason,
+    createdAt: t.createdAt, updatedAt: t.updatedAt, links: t.links, evidence: t.evidence, metrics: t.metrics,
+    operations: t.operations.map(({ operationId, kind, state, startedAt, finishedAt, exitCode, resume }) => ({ operationId, kind, state, startedAt, finishedAt, exitCode, ...(resume ? { resume } : {}) })) };
+}
+
+export function controlledDecisions(state) {
+  const pending = state.status === 'awaiting-release' ? state.release : state.pending;
+  if (!pending || !['awaiting-gate', 'awaiting-release'].includes(state.status)) return [];
+  const kind = state.status === 'awaiting-release' ? 'release' : 'gate';
+  const binding = digest({ run: state.id, kind, pending });
+  return [{ decisionId: binding, engine: 'codex', kind, runId: state.id, state: 'pending', action: 'host_approve',
+    receipt: pending.receipt || null,
+    label: kind === 'release' ? 'Approve the host release candidate' : 'Approve the host stage proposal',
+    gates: pending.gates || [], role: pending.role || 'devops', binding }];
+}
+
+/** Only the dispatcher's explicit session event may attach native stage evidence. */
+export function observeNativePipeline({ root, sessionId, agent, verdict, decisionKind, gates = [], receipt = null, recordDigest = null }, { store = workTaskStore() } = {}) {
+  if (!UUID.test(sessionId || '')) return null;
+  const listing = listWorkTasks(root, { store });
+  if (listing.state === 'degraded') throw Error('task metadata is unreadable');
+  const matches = listing.tasks.filter(t => t.host === 'claude-code' && !['completed', 'cancelled'].includes(t.phase) && t.links.sessions.includes(sessionId));
+  if (matches.length !== 1) return null;
+  return mutateWorkTask(matches[0].taskId, t => {
+    t.stage = agent; t.activity ||= [];
+    const eventId = digest({ sessionId, agent, recordDigest, receipt, decisionKind, gates });
+    if (t.activity.some(a => a.id === eventId)) return false;
+    t.activity.push({ id: eventId, kind: 'native_pipeline_event', role: agent, at: new Date().toISOString() });
+    if (decisionKind === 'rework') t.metrics.interruptions.native_rework = (t.metrics.interruptions.native_rework || 0) + 1;
+    if (receipt && JSON.stringify(treeReceipt(root)) === JSON.stringify(receipt) && recordDigest && ['next', 'done'].includes(decisionKind)) {
+      const id = digest({ sessionId, agent, recordDigest, receipt });
+      if (!t.activity.some(a => a.id === id)) t.activity.push({ id, kind: 'native_stage_result', role: agent, at: new Date().toISOString() });
+    }
+    t.evidence = [...t.evidence.filter(e => e.role !== agent), { role: agent, verdict, verified: false }];
+    t.decisions = decisionKind === 'gate' ? [{ decisionId: digest({ sessionId, agent, recordDigest, receipt, gates }),
+      engine: 'claude-code', kind: 'pipeline_gate', state: 'pending', receipt, sessionId, gates, role: agent, action: 'native_host',
+      label: 'Resolve the bound pipeline gate inside Claude; shared state does not approve it' }] : [];
+    const phase = decisionKind === 'gate' ? 'needs_decision' : ['blocked', 'route-pending'].includes(decisionKind) ? 'blocked' : decisionKind === 'done' ? 'waiting' : 'working';
+    observe(t, { phase, kind: decisionKind === 'gate' ? 'native_pipeline_approval' : decisionKind === 'rework' ? 'native_rework' : 'native_pipeline' });
+  }, { store, root });
+}

package/board/scripts/work-task.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/** Advanced operator contract behind `great-cto task work`; no new daily flow. */
+import { resolve } from 'node:path';
+import { listWorkTasks, readWorkTask } from './lib/work-tasks.mjs';
+import { approveWorkDecision, decisionCapabilities } from './lib/work-decisions.mjs';
+import { applyOutcome, readOutcomeEvidence } from './lib/work-outcomes.mjs';
+import { measureWork, compareWork } from './lib/work-metrics.mjs';
+const args = process.argv.slice(2), action = args.shift();
+try {
+  const supported = new Set(['--dir','--task','--decision','--revision','--operation','--evidence','--baseline']);
+  const opts = {};
+  for (let i = 0; i < args.length; i += 2) { if (!supported.has(args[i]) || !args[i+1] || args[i+1].startsWith('--') || opts[args[i]] !== undefined) throw Error('invalid or duplicate operator option'); opts[args[i]] = args[i+1]; }
+  const perAction = { metrics: ['--dir','--baseline'], decisions: ['--dir','--task'], approve: ['--dir','--task','--decision','--revision','--operation'], verify: ['--dir','--task','--revision','--operation','--evidence'], complete: ['--dir','--task','--revision','--operation'] };
+  if (perAction[action] && Object.keys(opts).some(k => !perAction[action].includes(k))) throw Error('option is not supported for this operation');
+  const root = resolve(opts['--dir'] || '.'), taskId = opts['--task'];
+  let result;
+  if (action === 'metrics') {
+    const listing = listWorkTasks(root); if (listing.state === 'degraded') throw Error('task source is degraded; measurements refused');
+    const current = measureWork(listing.tasks), baseline = opts['--baseline'] ? readOutcomeEvidence(root, opts['--baseline']).document : null;
+    result = { ...current, comparison: compareWork(current, baseline) };
+  } else if (action === 'decisions') result = decisionCapabilities(readWorkTask(taskId, { root }));
+  else if (action === 'approve') result = approveWorkDecision({ root, taskId, decisionId: opts['--decision'], expectedRevision: Number(opts['--revision']), operationId: opts['--operation'] });
+  else if (['verify','complete'].includes(action)) result = applyOutcome({ root, taskId, kind: action, expectedRevision: Number(opts['--revision']), operationId: opts['--operation'], evidenceFile: opts['--evidence'] });
+  else throw Error('usage: great-cto task work decisions|approve|verify|complete|metrics --dir PATH [--task UUID --revision N --operation UUID --decision ID --evidence EXTERNAL_FILE --baseline EXTERNAL_FILE]');
+  console.log(JSON.stringify(result, null, 2));
+} catch (e) { console.error('work-task: ' + e.message); process.exitCode = 2; }

package/dist/codex-host.js

@@ -6,8 +6,8 @@ import { spawnSync } from 'node:child_process';
 export function codexControllerCandidates(moduleUrl = import.meta.url) {
     const cliRoot = join(dirname(fileURLToPath(moduleUrl)), '..');
     return [
-        join(cliRoot, 'board', 'scripts', 'codex-pipeline.mjs'),
         join(cliRoot, '..', '..', 'scripts', 'codex-pipeline.mjs'),
+        join(cliRoot, 'board', 'scripts', 'codex-pipeline.mjs'),
     ];
 }
 export function runCodexHost(args, { exists = existsSync, spawn = spawnSync } = {}) {

package/dist/main.js

@@ -101,10 +101,12 @@ function parseArgs(argv) {
             args.noLlm = true;
         else if (a === "--host") {
             const v = argv[++i] ?? "";
+            args.hostInput = v;
             args.host = (v === "codex" || v === "claude-code") ? v : null;
         }
         else if (a.startsWith("--host=")) {
             const v = a.slice("--host=".length);
+            args.hostInput = v;
             args.host = (v === "codex" || v === "claude-code") ? v : null;
         }
         else if (a === "--bind")
@@ -158,11 +160,16 @@ function parseArgs(argv) {
             args.taskArgs = argv.slice(i + 1);
             break;
         }
+        else if (a === "run" || a === "status" || a === "resume") {
+            args.command = a;
+            args.taskArgs = argv.slice(i + 1);
+            break;
+        }
         // Slash-commands surfaced as CLI subcommands so users get a clear hint
         // instead of a confusing usage error. These work only in the chat plugin.
         else if (a === "start" || a === "audit" || a === "inbox" || a === "digest" ||
             a === "review" || a === "doctor" || a === "burn" || a === "save" ||
-            a === "resume" || a === "learn" || a === "agent" ||
+            a === "learn" || a === "agent" ||
             a === "rfc" || a === "release" || a === "ownership" ||
             a === "sec" || a === "poc" || a === "crystallize" ||
             a === "migrate") {
@@ -719,10 +726,34 @@ async function runUninstall(args) {
         warn(`${plan.keptVersions.length} plugin version(s) kept — a running session uses them; run uninstall again after closing it`);
     return r.failed.length ? 1 : 0;
 }
-function printHelp() {
+function printHelp(advanced = false) {
+    if (!advanced) {
+        log(`great-cto — describe the task, get a checked result
+
+Get started:
+  great-cto init
+
+Everyday use:
+  great-cto run "describe the task"
+  great-cto status
+  great-cto resume
+
+Default host: interactive Claude Code with the plugin loaded.
+For controlled Codex add --host codex; run also needs --allow src,tests,docs.
+Use --dir PATH to choose a project, --dry-run to preview, or run --help for options.
+Resume preserves pending decisions; it never approves them.
+
+Details:
+  great-cto board           Open the local dashboard
+  great-cto help --advanced All installation, runtime and operator commands`);
+        return;
+    }
     log(`${bold("great-cto")} — one-command install for the great_cto Claude Code plugin
 
 ${bold("Usage:")}
+  npx great-cto run "describe the task" [--host claude-code|codex] [--dir PATH]
+  npx great-cto status [RUN_UUID] [--host codex] [--json]
+  npx great-cto resume [RUN_UUID] [--host codex]
   npx great-cto install [options]    Same as init
   npx great-cto [init] [options]     Detect + bootstrap
   npx great-cto board [--port 3141] [--no-open]
@@ -731,6 +762,7 @@ ${bold("Usage:")}
   npx great-cto ci [path] [--no-archetype] [--no-budget]
   npx great-cto mcp [--sse --port N]
   npx great-cto adapt [--dry-run]
+  npx great-cto task work decisions|approve|verify|complete|metrics ...
   npx great-cto codex-host doctor|list|start|resume|status ...
   npx great-cto serve [--port 3142]
   npx great-cto upgrade [superpowers|beads]  Re-clone companions to latest tag + re-apply overlays
@@ -1528,7 +1560,7 @@ async function main() {
         await finish(exitCode);
     }
     if (args.command === "help") {
-        printHelp();
+        printHelp(rawArgv.includes('--advanced'));
         await finish(0);
     }
     if (args.command === "unknown") {
@@ -1622,6 +1654,10 @@ async function main() {
             await finish(2);
         }
     }
+    if (args.command === "task" && args.taskArgs?.[0] === "work") {
+        const { runWorkTask } = await import("./work-task.js");
+        await finish(runWorkTask(args.taskArgs.slice(1)));
+    }
     if (args.command === "task") {
         const { runTask } = await import("./worker.js");
         await finish(await runTask(args.taskArgs ?? []));
@@ -1634,6 +1670,11 @@ async function main() {
         const { runCodexHost } = await import('./codex-host.js');
         await finish(runCodexHost(args.taskArgs ?? []));
     }
+    if (args.command === "run" || args.command === "status" || args.command === "resume") {
+        const { runDaily } = await import('./run.js');
+        const dailyArgs = [...(args.hostInput !== undefined ? ['--host', args.hostInput] : []), ...(args.taskArgs ?? [])];
+        await finish(runDaily(args.command, dailyArgs, { cwd: args.dir }));
+    }
     if (args.command === "serve") {
         try {
             const { runServe } = await import("./serve.js");