@ludi-uni/ludi-agent-kit 0.1.0

package/lib/orchestrator/activity.mjs

@@ -0,0 +1,249 @@
+// Public run-activity snapshots for external clients (pi-web, future UIs). The tracker keeps a
+// live in-memory view of one client's runs and writes an ATOMIC public JSON snapshot per client
+// under <kit>/.orchestration/activity/clients/<kind>-<sessionId>.json. The store remains the
+// source of truth; this file is a projection that other processes can tail without SQLite.
+//
+// Event policy: orchestration-level events (plan/round/result/retry/escalation/…), invocation
+// lifecycle (start/end), tool calls, turn-cap extensions and fallbacks are SIGNIFICANT — they are
+// also the events the orchestrator persists to the run trace. High-frequency per-turn progress
+// updates only refresh the in-memory snapshot + written file, never the trace.
+import { mkdirSync, writeFileSync, renameSync, readFileSync, existsSync, rmSync } from 'node:fs';
+import { join, basename, dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+export const ACTIVITY_VERSION = 1;
+
+/** Events that matter for history: persisted to the run trace by the orchestrator. */
+export const SIGNIFICANT_EVENT_TYPES = new Set([
+  'invocation-start', 'invocation-end', 'invocation-tool', 'invocation-extension', 'candidate-changed',
+]);
+
+/** High-frequency progress events: live snapshot only, never the trace. */
+export const HIGH_FREQUENCY_EVENT_TYPES = new Set(['invocation-turn', 'invocation-tool-completed']);
+
+const safeSegment = s => String(s ?? '').replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '') || 'unknown';
+const invocationKey = (runId, taskId, invocationId) => JSON.stringify([runId, taskId, invocationId]);
+
+/** clientContext -> canonical snapshot file name, e.g. pi-web-<canonicalPiUUID>.json */
+export function activityFileName(clientContext) {
+  return `${safeSegment(clientContext?.kind)}-${safeSegment(clientContext?.sessionId)}.json`;
+}
+
+export function clientKeyOf(clientContext) {
+  return JSON.stringify([clientContext?.kind ?? '', clientContext?.sessionId ?? '']);
+}
+
+/** Publish a complete document without exposing partial JSON to readers. On Windows a
+ * reader may briefly hold the destination without FILE_SHARE_DELETE, causing EPERM.
+ * Retry only those sharing violations; never remove the old snapshot first. */
+export function publishActivitySnapshot(file, doc, {
+  rename = renameSync,
+  wait = ms => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms),
+  windows = process.platform === 'win32',
+} = {}) {
+  const dir = dirname(file);
+  mkdirSync(dir, { recursive: true });
+  const tmp = join(dir, `.${randomBytes(4).toString('hex')}.tmp`);
+  try {
+    writeFileSync(tmp, JSON.stringify(doc, null, 2));
+    for (let attempt = 0; ; attempt++) {
+      try { rename(tmp, file); return; }
+      catch (error) {
+        if (!windows || !['EPERM', 'EACCES', 'EBUSY'].includes(error.code) || attempt >= 5) throw error;
+        wait([10, 20, 40, 80, 160][attempt]);
+      }
+    }
+  } finally {
+    // A failed rename must not accumulate temporary files on every turn.
+    try { rmSync(tmp, { force: true }); } catch { /* temporary file may itself be locked */ }
+  }
+}
+
+/** Drop raw payloads: only bounded, non-secret fields may leave the process. */
+export function sanitizeInvocationEvent(type, data = {}) {
+  const out = { type };
+  const copy = k => { if (data[k] != null) out[k] = typeof data[k] === 'string' ? data[k].slice(0, 500) : data[k]; };
+  for (const k of ['runId', 'taskId', 'invocationId', 'agent', 'capability', 'modelId', 'backend', 'provider', 'turn', 'turnCap', 'turnsUsed', 'turnLimit', 'toolCalls', 'extensionsGranted', 'oldLimit', 'newLimit', 'fromModel', 'toModel', 'from', 'to', 'reason', 'status', 'at']) copy(k);
+  if (data.tool) {
+    const file = data.tool.file ? basename(String(data.tool.file).replace(/\\/g, '/')).slice(0, 100) : '';
+    out.tool = { name: String(data.tool.name ?? 'tool').slice(0, 80), ...(file ? { file } : {}) };
+  }
+  if (data.childSessionId) out.childSessionId = String(data.childSessionId);
+  return out;
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.kit kit root; snapshots go to <kit>/.orchestration/activity/clients/
+ * @param {object} [o.clientContext] { kind, sessionId } — generic; the extension injects the
+ *   authoritative pi session id for kind 'pi-web'.
+ */
+export function createActivityTracker({ kit, clientContext = null, now = () => new Date().toISOString() } = {}) {
+  const dir = kit ? join(kit, '.orchestration', 'activity', 'clients') : null;
+  const file = dir && clientContext?.sessionId ? join(dir, activityFileName(clientContext)) : null;
+  const runs = new Map();       // runId -> live activity object
+  const bindings = new Map();   // clientKey -> runId (a client sees the runs it started)
+  const listeners = new Map();  // runId -> Set<listener>
+  const invocations = new Map();// invocationKey -> invocation record
+  const startedAt = new Map();
+  let snapshotWarningShown = false;
+
+  const notify = runId => {
+    const activity = runs.get(runId);
+    for (const fn of listeners.get(runId) ?? []) {
+      try { fn(structuredClone(activity)); } catch { /* listener must not break the run */ }
+    }
+  };
+
+  const writeSnapshot = () => {
+    if (!file) return;
+    const runList = [...bindings.values()].map(id => runs.get(id)).filter(Boolean);
+    const latest = runList.at(-1) ?? null;
+    const doc = {
+      version: ACTIVITY_VERSION,
+      clientContext: clientContext ? { kind: clientContext.kind, sessionId: clientContext.sessionId } : null,
+      runId: latest?.runId ?? null,
+      repoRoot: latest?.repoRoot ?? null,
+      startedAt: latest ? startedAt.get(latest.runId) : null,
+      activity: latest ? { ...structuredClone(latest), updatedAt: now() } : null,
+    };
+    try {
+      publishActivitySnapshot(file, doc);
+      snapshotWarningShown = false;
+    } catch (error) {
+      // The public projection is optional: a sharing violation must not abort
+      // the authoritative SQLite run or turn a successful task into a failure.
+      if (!snapshotWarningShown) console.warn(`activity snapshot unavailable (${error.code ?? 'write error'}); the run remains persisted`);
+      snapshotWarningShown = true;
+    }
+  };
+
+  const ensureRun = runId => {
+    if (!runs.has(runId)) {
+      runs.set(runId, { runId, state: 'running', completedTasks: 0, totalTasks: 0, activeAgents: 0, tasks: [], activeInvocations: [], updatedAt: now() });
+    }
+    return runs.get(runId);
+  };
+
+  const tracker = {
+    file,
+    clientContext,
+
+    /** Bind this client to a run the moment the run exists. */
+    bindRun({ runId, repoRoot = null }) {
+      if (!runId) return;
+      const a = ensureRun(runId);
+      if (!startedAt.has(runId)) startedAt.set(runId, now());
+      a.repoRoot = repoRoot ?? a.repoRoot;
+      if (clientContext?.sessionId) bindings.set(clientKeyOf(clientContext), runId);
+      notify(runId);
+      writeSnapshot();
+    },
+
+    /**
+     * Feed one event. `persist` tells the orchestrator whether this type belongs in the
+     * durable trace (significant) or only in the live snapshot (high-frequency turns).
+     */
+    emit(type, data = {}) {
+      const runId = data.runId;
+      const persist = SIGNIFICANT_EVENT_TYPES.has(type);
+      if (!runId) return { persist };
+      const a = ensureRun(runId);
+      const e = sanitizeInvocationEvent(type, data);
+      if (type === 'candidate-changed' || type === 'fallback') {
+        const task = a.tasks.find(t => t.taskId === data.taskId);
+        if (task) {
+          task.fallbackFrom = e.fromModel ?? e.from;
+          task.fallbackTo = e.toModel ?? e.to;
+          if (e.toModel) task.modelId = e.toModel;
+          if (e.to) task.capability = e.to;
+        }
+        a.recentEvent = type;
+      }
+      if (type === 'invocation-start') {
+        invocations.set(invocationKey(runId, data.taskId, data.invocationId), e);
+      } else if (type === 'invocation-end') {
+        invocations.delete(invocationKey(runId, data.taskId, data.invocationId));
+      } else if ((HIGH_FREQUENCY_EVENT_TYPES.has(type) || SIGNIFICANT_EVENT_TYPES.has(type)) && data.invocationId) {
+        const key = invocationKey(runId, data.taskId, data.invocationId);
+        const previous = invocations.get(key);
+        if (previous) {
+          const next = { ...previous, ...e };
+          if (e.turn !== undefined) next.turnsUsed = e.turn;
+          if (e.turnCap !== undefined) next.turnLimit = e.turnCap;
+          if (e.newLimit !== undefined) next.turnLimit = e.newLimit;
+          if (type === 'invocation-tool' && e.tool) next.recentTools = [...(previous.recentTools ?? []), { tool: e.tool.name, ...(e.tool.file ? { summary: e.tool.file } : {}) }].slice(-5);
+          invocations.set(key, next);
+        }
+      }
+      a.activeInvocations = [...invocations.values()].filter(i => i.runId === runId);
+      a.activeAgents = a.activeInvocations.length || a.tasks.filter(t => t.state === 'running').length;
+      a.updatedAt = now();
+      notify(runId);
+      writeSnapshot();
+      return { persist };
+    },
+
+    /** Sync the task-level projection after a store update. */
+    syncTasks({ runId, tasks = [], state = null }) {
+      const a = ensureRun(runId);
+      a.tasks = tasks.map(t => {
+        const live = a.activeInvocations.find(i => i.taskId === t.id);
+        return { taskId: t.id, title: t.title, agent: t.assignedAgent, capability: t.capability,
+          modelId: live?.modelId ?? t.modelId, state: t.status, attempts: t.attempts ?? 0,
+          ...(a.tasks.find(x => x.taskId === t.id)?.fallbackFrom ? {
+            fallbackFrom: a.tasks.find(x => x.taskId === t.id).fallbackFrom,
+            fallbackTo: a.tasks.find(x => x.taskId === t.id).fallbackTo,
+          } : {}),
+          ...(live?.turnsUsed != null ? { turnsUsed: live.turnsUsed } : {}),
+          ...(live?.turnLimit != null ? { turnLimit: live.turnLimit } : {}),
+          ...(live?.toolCalls != null ? { toolCalls: live.toolCalls } : {}),
+          ...(live?.recentTools?.length ? { recentTools: live.recentTools } : {}) };
+      });
+      a.totalTasks = a.tasks.length;
+      a.completedTasks = a.tasks.filter(t => t.state === 'completed').length;
+      a.activeAgents = a.activeInvocations.length || a.tasks.filter(t => t.state === 'running').length;
+      if (state) a.state = state;
+      a.updatedAt = now();
+      notify(runId);
+      writeSnapshot();
+    },
+
+    getRunActivity(runId) {
+      const a = runs.get(runId);
+      if (a) return structuredClone(a);
+      const snapshot = file ? readActivitySnapshot(file) : null;
+      return snapshot?.runId === runId ? snapshot.activity ?? null : null;
+    },
+
+    getRunActivityByClient(kind, sessionId) {
+      if (clientKeyOf({ kind, sessionId }) !== clientKeyOf(clientContext)) return null;
+      const runId = bindings.get(clientKeyOf({ kind, sessionId }));
+      if (runId) return tracker.getRunActivity(runId);
+      const snapshot = file ? readActivitySnapshot(file) : null;
+      return snapshot?.clientContext?.kind === kind && snapshot?.clientContext?.sessionId === sessionId ? snapshot.activity ?? null : null;
+    },
+
+    /** Stop live subscriptions when a run terminates; keep its final snapshot. */
+    finishRun(runId) {
+      for (const key of invocations.keys()) if (JSON.parse(key)[0] === runId) invocations.delete(key);
+      const a = runs.get(runId);
+      if (a) { a.activeInvocations = []; a.activeAgents = 0; a.updatedAt = now(); notify(runId); writeSnapshot(); }
+      listeners.delete(runId);
+    },
+
+    /** listener(activity) on every significant change. Returns an unsubscribe fn. */
+    subscribeRunActivity(runId, listener) {
+      if (!listeners.has(runId)) listeners.set(runId, new Set());
+      listeners.get(runId).add(listener);
+      return () => listeners.get(runId)?.delete(listener);
+    },
+  };
+  return tracker;
+}
+
+/** Read a published client snapshot (for tools / tests). Returns null when absent. */
+export function readActivitySnapshot(path) {
+  if (!existsSync(path)) return null;
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; }
+}

package/lib/orchestrator/api.mjs

@@ -0,0 +1,151 @@
+// Programmatic boundary for the CLI and the pi extension. No SQL and no provider-specific imports:
+// the caller supplies `invoke` / `runner`. Natural-language UI can call these functions later.
+import { join } from 'node:path';
+import { loadRouting } from '../routing.mjs';
+import { loadRegistry } from '../registry.mjs';
+import { loadAgents } from '../agents.mjs';
+import { loadPolicy } from './policy.mjs';
+import { openStore } from './store.mjs';
+import { createHealthMonitor } from './health.mjs';
+import { createAgentRunner } from './runner.mjs';
+import { orchestrate, formatReport, formatRunList, toEscalation } from './orchestrator.mjs';
+import { createActivityTracker } from './activity.mjs';
+
+export function defaultStorePath(kit, env = process.env) {
+  return env.LUDI_ORCHESTRATION_STORE || join(kit, '.orchestration', 'state.db');
+}
+
+export function loadOrchestrationContext({ kit, storePath, policyPath = null, localPolicyPath = null, clientContext = null }) {
+  const routing = loadRouting(join(kit, 'routing/routing.json'));
+  const { registry } = loadRegistry(join(kit, 'adapters/pi/models.json'), join(kit, 'adapters/pi/models.local.json'), routing);
+  const { agents, errors } = loadAgents(join(kit, 'agents'), routing);
+  const base = join(kit, 'orchestration/decision-policy.json');
+  const { policy } = loadPolicy(base, policyPath ?? localPolicyPath);
+  const session = openStore(storePath);
+  const activity = createActivityTracker({ kit, clientContext });
+  return { kit, routing, registry, agents, errors, policy, session, storePath, clientContext, activity };
+}
+
+/** Public live activity for one run (in-memory projection; null when unknown). */
+export function getRunActivity(ctx, runId) {
+  return ctx.activity?.getRunActivity(runId) ?? null;
+}
+
+/** Public live activity addressed by owning client ({ kind, sessionId }). */
+export function getRunActivityByClient(ctx, kind, sessionId) {
+  return ctx.activity?.getRunActivityByClient(kind, sessionId) ?? null;
+}
+
+/** Subscribe to activity updates for one run. Returns an unsubscribe function. */
+export function subscribeRunActivity(ctx, runId, listener) {
+  return ctx.activity?.subscribeRunActivity(runId, listener) ?? (() => {});
+}
+
+export function listOrchestrationRuns(ctx, { status = null } = {}) {
+  return ctx.session.listRuns(status ? { status } : {});
+}
+
+export function pendingDecisions(ctx, { runId = null } = {}) {
+  const runs = runId ? [ctx.session.getRun(runId)].filter(Boolean) : ctx.session.listRuns({ status: 'waiting_for_user' });
+  const out = [];
+  for (const run of runs) {
+    const id = run.id;
+    for (const d of ctx.session.listDecisions(id, 'pending')) out.push(d);
+  }
+  return out;
+}
+
+export function showRun(ctx, runId) {
+  const run = ctx.session.getRun(runId);
+  if (!run) throw new Error(`run not found: ${runId}`);
+  const tasks = ctx.session.loadTasks(runId);
+  const pending = ctx.session.listDecisions(runId, 'pending');
+  const status = run.status === 'waiting_for_user' ? 'needs-user' : run.status === 'completed' ? 'completed' : 'incomplete';
+  return {
+    status, runStatus: run.status, runId, request: run.request, planner: run.planner, rounds: run.round,
+    errors: [], tasks, autoDecisions: run.counters.autoDecisions ?? [], escalations: pending.map(toEscalation),
+    unresolved: run.counters.unresolved ?? [], limitsHit: run.counters.limitsHit ?? [], trace: ctx.session.loadTrace(runId),
+  };
+}
+
+export function answerOrchestration(ctx, { runId, decisionId, answer }) {
+  return ctx.session.answerDecision({ runId, decisionId, answer, scopeKey: ctx.session.getRun(runId)?.scopeKey });
+}
+
+const DURATION_UNITS = { m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 };
+
+/** Parse a duration like "30m", "12h", "7d", "2w" into milliseconds. Throws on bad input. */
+export function parseOlderThan(text) {
+  const m = /^(\d+)\s*([mhdw])$/i.exec(String(text ?? '').trim());
+  if (!m) throw new Error(`invalid --older-than "${text}" (examples: 30m, 12h, 7d, 2w)`);
+  const ms = Number(m[1]) * DURATION_UNITS[m[2].toLowerCase()];
+  if (!Number.isSafeInteger(ms) || ms <= 0) throw new Error(`invalid --older-than "${text}"`);
+  return ms;
+}
+
+/** Read-only preview of what a cleanup would delete. Never writes. */
+export function previewRunCleanup(ctx, { olderThan = null, includeActive = false } = {}) {
+  return ctx.session.previewRuns({ olderThan, includeActive });
+}
+
+/** Delete terminal runs older than `olderThanMs` (null = all terminal). One transaction. */
+export function pruneOrchestrationRuns(ctx, { olderThanMs = 7 * 86_400_000 } = {}) {
+  const cutoff = new Date(Date.now() - (olderThanMs ?? 7 * 86_400_000)).toISOString();
+  return ctx.session.pruneRuns({ olderThan: cutoff });
+}
+
+/** Delete one run's history. The store refuses active/resumable runs. */
+export function deleteOrchestrationRun(ctx, runId, { force = false } = {}) {
+  return ctx.session.deleteRun(runId, { force });
+}
+
+/** force=false previews; force=true deletes all terminal runs (includeActive additionally removes active ones). */
+export function clearOrchestrationRuns(ctx, { force = false, includeActive = false } = {}) {
+  return ctx.session.clearRuns({ force, includeActive });
+}
+
+const cleanupLine = r => `${r.id}  ${r.status}  tasks:${r.counts.tasks} decisions:${r.counts.decisions} trace:${r.counts.trace}  ${r.updatedAt}  ${String(r.request).replace(/\s+/g, ' ').slice(0, 60)}`;
+
+/** Concise Japanese summary of a cleanup preview or executed cleanup. */
+export function formatCleanup(result, { verb = '削除', hint = '--force' } = {}) {
+  const lines = [];
+  if (!result.runs.length || (result.totals.runs === 0 && !result.skipped.length)) return '削除対象のランはありません';
+  const head = result.executed ? `${verb}しました` : `削除対象（プレビュー）`;
+  lines.push(`${head}: ${result.totals.runs} ラン (terminal:${result.totals.terminal} active/resumable:${result.totals.active}; tasks:${result.totals.tasks} decisions:${result.totals.decisions} trace:${result.totals.trace} health:${result.totals.health})`);
+  lines.push(`内訳: completed ${result.runs.filter(r => r.deletable && r.status === 'completed').length}, failed ${result.runs.filter(r => r.deletable && r.status === 'failed').length}, cancelled ${result.runs.filter(r => r.deletable && r.status === 'cancelled').length}, active保持 ${result.skipped.filter(s => /active|resumable/.test(s.reason)).length}`);
+  lines.push(`更新日時: ${result.totals.oldest ?? 'なし'} ～ ${result.totals.newest ?? 'なし'}`);
+  for (const r of result.runs.filter(x => x.deletable)) lines.push(`  ${cleanupLine(r)}`);
+  if (result.skipped.length) {
+    lines.push(`スキップ: ${result.skipped.length} ラン`);
+    for (const s of result.skipped) lines.push(`  ${s.id}  ${s.reason}`);
+  }
+  if (!result.executed) lines.push(`実行するには ${hint} を指定してください`);
+  return lines.join('\n');
+}
+
+export function createRunHealth(ctx) {
+  return createHealthMonitor({ session: ctx.session, policy: ctx.policy });
+}
+
+export function createRunRunner(ctx, { invoke, runSubagent = null, repoRoot, outDir, apply = false, health }) {
+  return createAgentRunner({
+    invoke, runSubagent, agents: ctx.agents, routing: ctx.routing, registry: ctx.registry, repoRoot, outDir, health, policy: ctx.policy, session: ctx.session,
+    maxModelAttempts: ctx.policy.limits.model_attempts_per_task, pipelineAgents: apply ? ['coder'] : [],
+  });
+}
+
+export async function startOrchestration(ctx, { request, repoRoot = null, planner = 'rules', plan = null, runner, invoke = null, health = null, projectStore }) {
+  return orchestrate({
+    request, planner, plan, agents: ctx.agents, routing: ctx.routing, registry: ctx.registry, policy: ctx.policy,
+    runner, invoke, repoRoot, session: ctx.session, health, projectStore, activity: ctx.activity,
+  });
+}
+
+export async function resumeOrchestration(ctx, { runId, answers = [], repoRoot = null, runner, invoke = null, health = null, projectStore }) {
+  return orchestrate({
+    request: '', resumeRunId: runId, answers, agents: ctx.agents, routing: ctx.routing, registry: ctx.registry,
+    policy: ctx.policy, runner, invoke, repoRoot, session: ctx.session, health, projectStore, activity: ctx.activity,
+  });
+}
+
+export { formatReport, formatRunList };

package/lib/orchestrator/contract.mjs

@@ -0,0 +1,68 @@
+// Task contract handed to a worker. The result block stays compatible with the Phase 1 evaluator.
+import { accessOf } from './permissions.mjs';
+
+export const RESULT_STATUSES = ['completed', 'failed', 'blocked', 'needs_decision'];
+
+export function forbiddenActions() {
+  return [
+    'git push', 'npm publish or any package publish', 'deployment or production mutation',
+    'git reset, git checkout --, git clean, or git stash', 'deleting files outside dist/build/coverage/node_modules',
+    'changing credentials or user configuration', 'network calls',
+  ];
+}
+
+export function buildTaskContract(task, { dependencyResults = [], survey = null, access = null, workspace = null } = {}) {
+  const rights = access ?? { filesystem: 'read', shell: 'false', git: 'none', network: false };
+  const lines = [
+    'TASK', task.title, '',
+    'GOAL', task.goal, '',
+    'CONTEXT',
+  ];
+  if (dependencyResults.length) {
+    for (const d of dependencyResults) {
+      lines.push(`- ${d.id} (${d.agent}): ${d.title}`, String(d.summary ?? '').slice(0, 2000));
+      if (d.filesChanged?.length) lines.push(`  files: ${d.filesChanged.join(', ')}`);
+    }
+  } else lines.push('No completed dependencies.');
+  if (task.attemptsLog?.length) {
+    lines.push('', 'PREVIOUS_ATTEMPTS');
+    for (const a of task.attemptsLog) {
+      lines.push(`- attempt ${a.attempt} [${a.failureClass}]: ${(a.reasons ?? []).join('; ') || a.summary || ''}`);
+      if (a.filesChanged?.length) lines.push(`  changed: ${a.filesChanged.join(', ')}`);
+      if (a.verification?.length) lines.push(`  verification: ${JSON.stringify(a.verification).slice(0, 800)}`);
+    }
+  }
+  lines.push('', 'WORKSPACE', `path: ${workspace?.path ?? '(unspecified)'}`, `repository: ${workspace?.repository ?? '(unspecified)'}`, 'Change files only inside this workspace. Do not reset, checkout, or stash existing changes.');
+  lines.push('', 'ACCEPTANCE_CRITERIA');
+  (task.acceptance?.length ? task.acceptance : ['the goal is achieved and verified']).forEach((a, i) => lines.push(`- A${i + 1}: ${a}`));
+  if (task.outputs?.length) lines.push('', 'REQUIRED_OUTPUTS', ...task.outputs.map(o => `- ${o}`));
+  lines.push('', 'ALLOWED_ACTIONS', `filesystem: ${rights.filesystem}`, `shell: ${rights.shell}`, `git: ${rights.git}`, `network: ${rights.network}`);
+  if (rights.shell !== 'false') lines.push('Run commands only through ludi_exec. Tests, lint, build, git status, and git diff are allowed when your shell access says so.');
+  lines.push('', 'FORBIDDEN_ACTIONS', ...forbiddenActions().map(f => `- ${f}`));
+  if (task.decisions?.length) lines.push('', 'DECISIONS_ALREADY_MADE', ...task.decisions.map(d => `- ${d.question} -> ${d.choice} (${d.reason})`));
+  if (task.feedback?.length) lines.push('', 'RETRY_FEEDBACK', ...task.feedback.map(f => `- ${f}`));
+  if (survey) {
+    lines.push('', 'REPOSITORY_FILES', ...survey.files.map(f => `- ${f.path} (${f.size} B)`));
+    lines.push('', 'FILE_CONTENTS', ...survey.inline.map(f => `### \`${f.path}\`\n\`\`\`\n${f.content}\n\`\`\``));
+  }
+  lines.push('', 'EXPECTED_RESULT_FORMAT',
+    'Your reply MUST end with exactly one fenced ```json result block. A reply without it is rejected as malformed regardless of how good the prose is.',
+    'Do not ask the user anything. If you need a choice, return status "needs_decision" or "blocked" and a decisions array.',
+    'Required block (the LAST thing in your reply):',
+    '```json',
+    '{"status":"completed|failed|blocked|needs_decision","summary":"...","filesChanged":[],"commandsRun":[],',
+    ' "verification":[{"command":"...","result":"pass|fail|skipped"}],',
+    ' "acceptance":[{"id":"A1","met":true,"evidence":"..."}],',
+    ' "remainingIssues":[{"summary":"...","blocking":false}],"decisions":[],"newTasks":[]}',
+    '```',
+    'status "completed" requires evidence for every acceptance id. A claim without a command, diff, or file reference is not evidence.',
+    '',
+    'LANGUAGE',
+    'Write natural-language values (summary, evidence, remainingIssues, decisions, newTasks) in Japanese unless the user requested another language.',
+    'Keep all JSON keys, enum values (completed/failed/blocked/needs_decision/pass/fail/skipped), file paths, commands and identifiers in English/exact form — never translate them.');
+  return lines.join('\n');
+}
+
+export function accessForPrompt(agent) {
+  return accessOf(agent);
+}

package/lib/orchestrator/escalation.mjs

@@ -0,0 +1,84 @@
+// Escalation gate: resolve a sub-agent's decision request without the user whenever policy allows.
+// Order: hard gate -> current-run decision -> persistent decision memory -> single option ->
+//        reversible -> low risk -> project policy -> small experiment -> escalate to user.
+// Hard gate is always first, so a remembered answer never authorizes an irreversible action.
+import { ESCALATION_FLAGS } from './policy.mjs';
+
+const LEVEL = { none: 0, low: 0, medium: 1, high: 2 };
+const level = v => LEVEL[v] ?? 1;
+
+export const decisionKey = d => String(d.key ?? d.question ?? '').trim().toLowerCase();
+
+/** Flags that force user escalation: declared by the agent, derived from numbers, or matched by policy keywords. */
+export function escalationFlags(decision, policy) {
+  const dp = policy.decision_policy;
+  const found = new Set((decision.flags ?? []).filter(f => ESCALATION_FLAGS.includes(f)));
+  for (const o of decision.options ?? []) {
+    for (const f of o.flags ?? []) if (ESCALATION_FLAGS.includes(f)) found.add(f);
+    if (typeof o.costUsd === 'number' && o.costUsd >= dp.high_cost_threshold_usd) found.add('high_cost');
+    if (typeof o.estimatedWeeks === 'number' && o.estimatedWeeks >= dp.major_direction_change_weeks) found.add('major_direction_change');
+  }
+  const text = [decision.question, ...(decision.options ?? []).map(o => o.summary)].join('\n').toLowerCase();
+  for (const [flag, words] of Object.entries(dp.escalation_keywords ?? {})) if (words.some(w => text.includes(w.toLowerCase()))) found.add(flag);
+  return [...found].filter(f => dp.escalation[f] !== false);
+}
+
+function policyScore(o, dp) {
+  let s = 0;
+  if (dp.prefer_existing_assets && o.usesExistingAssets === true) s += 1;
+  if (dp.prefer_maintainability && o.maintainability) s += { high: 1, medium: 0, low: -1 }[o.maintainability] ?? 0;
+  if (dp.prefer_reversible_actions && o.reversible === true) s += 1;
+  return s;
+}
+
+function best(options, score) {
+  let top = null, topScore = -Infinity, tie = false;
+  for (const o of options) {
+    const s = score(o);
+    if (s > topScore) { top = o; topScore = s; tie = false; } else if (s === topScore) tie = true;
+  }
+  return { option: top, tie };
+}
+
+/**
+ * @returns {{ action: 'decide'|'experiment'|'escalate', step: string, optionId?: string, reason: string, flags: string[], experiment?: object }}
+ */
+export function evaluateDecision(decision, { policy, decisionLog = [], memory = [] }) {
+  const dp = policy.decision_policy;
+  const options = Array.isArray(decision.options) ? decision.options.filter(o => o && o.id) : [];
+  const key = decisionKey(decision);
+  const flags = escalationFlags(decision, policy);
+  const out = (action, step, reason, extra = {}) => ({ action, step, reason, flags, key, question: decision.question, ...extra });
+
+  if (flags.length) return out('escalate', 'hard-gate', `requires user: ${flags.join(', ')}`);
+
+  const prior = decisionLog.find(e => e.key === key && e.action === 'decide');
+  if (prior && options.some(o => o.id === prior.optionId)) return out('decide', 'context', `already decided earlier in this run (${prior.step})`, { optionId: prior.optionId });
+  const remembered = memory.find(m => m.key === key && options.some(o => o.id === m.decision?.optionId));
+  if (remembered) return out('decide', 'memory', `persistent decision memory (${remembered.scope})`, { optionId: remembered.decision.optionId, memoryId: remembered.id, scope: remembered.scope });
+  if (options.length === 1) return out('decide', 'context', 'only one viable option', { optionId: options[0].id });
+  if (!options.length) return out('escalate', 'no-options', 'decision request has no options to choose from');
+
+  const full = o => (o.id === decision.recommended ? 2 : 0) + policyScore(o, dp) - level(o.risk) - level(o.cost);
+  const reversible = decision.reversible === true || options.every(o => o.reversible === true);
+  if (reversible && dp.default_behavior.reversible_decision === 'auto') {
+    return out('decide', 'reversible', 'reversible decision; chose the best-scoring option', { optionId: best(options, full).option.id });
+  }
+  const lowRisk = options.filter(o => o.risk === 'low' && level(o.cost ?? 'low') === 0);
+  if (lowRisk.length && dp.default_behavior.low_risk_decision === 'auto') {
+    return out('decide', 'low-risk', 'low cost and low risk option available', { optionId: best(lowRisk, full).option.id });
+  }
+  const byPolicy = best(options, o => policyScore(o, dp));
+  if (!byPolicy.tie && policyScore(byPolicy.option, dp) > 0) {
+    return out('decide', 'policy', 'project policy (existing assets / maintainability / reversibility) prefers one option', { optionId: byPolicy.option.id });
+  }
+  const limit = dp.poc.prefer_if_estimated_hours_lte;
+  const triedExperiment = decisionLog.some(e => e.key === key && e.action === 'experiment');
+  const hours = decision.experiment?.estimatedHours ?? Math.max(...options.map(o => o.estimatedHours ?? Infinity));
+  if (!triedExperiment && Number.isFinite(hours) && hours <= limit) {
+    return out('experiment', 'experiment', `a small experiment (~${hours}h <= ${limit}h) can settle it`, {
+      experiment: { goal: decision.experiment?.goal ?? `Compare options for "${decision.question}": ${options.map(o => `${o.id} (${o.summary ?? ''})`).join('; ')}. Recommend one with evidence.`, agent: decision.experiment?.agent, estimatedHours: hours },
+    });
+  }
+  return out('escalate', 'unresolved', triedExperiment ? 'experiment already ran and the choice is still open' : 'not reversible, not low risk, and policy does not discriminate');
+}

package/lib/orchestrator/evaluator.mjs

@@ -0,0 +1,92 @@
+// ResultEvaluator: a task succeeds only with a structured result whose status is "completed",
+// a non-empty summary, every required output present, and every acceptance criterion met with evidence.
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { dangerousCommands } from './shell-policy.mjs';
+
+const isBlocking = i => i?.blocking === true || ['high', 'critical', 'blocking'].includes(String(i?.severity ?? '').toLowerCase());
+
+// Issues that mean "the work itself cannot proceed safely" — these still fail
+// or gate even on investigation. Advisory findings (open questions, multiple
+// valid directions, repo observations) are the deliverable of an investigation,
+// not a failure.
+const SAFETY_RE = /destructive|overwrite|uncommitted|conflict|mutually exclusive|不可逆|破壊|上書き|衝突|排他|未コミット.*(上書き|破壊|衝突)|overwrite.*uncommitted/i;
+const DECISION_RE = /choose|select|which|pick|decide|ambiguous|unclear|不明|未定|未指定|選択|判断|どちら|いずれ|候補|option/i;
+
+/** Classify a blocking issue: 'safety' gates the run, 'decision' needs user input, 'advisory' is a note. */
+export function classifyBlockingIssue(issue) {
+  const text = `${issue?.summary ?? ''} ${issue?.detail ?? ''}`;
+  if (SAFETY_RE.test(text)) return 'safety';
+  if (DECISION_RE.test(text)) return 'decision';
+  return 'advisory';
+}
+
+/** @returns {{ verdict: 'success'|'failure'|'blocked', reasons: string[], decisions: object[], newTasks: object[], blockingIssues: object[] }} */
+export function evaluateResult(task, run, { repoRoot = null } = {}) {
+  const out = (verdict, reasons, extra = {}) => ({ verdict, reasons, decisions: [], newTasks: [], blockingIssues: [], ...extra });
+  if (!run?.ok) {
+    // A runner-level decision request (e.g. dirty-worktree safety gate) bypasses
+    // the structured-result check — it never reached the model.
+    if (run?.decision) return out('blocked', [run.error ?? 'decision required'], { decisions: [run.decision] });
+    return out('failure', [`agent run failed: ${run?.error ?? 'unknown error'}`]);
+  }
+  if (!run.structured) return out('failure', ['no structured result block; a bare completion claim is not accepted']);
+  const r = run.result;
+  const newTasks = r.newTasks ?? [];
+  if (r.status === 'blocked') {
+    return r.decisions?.length ? out('blocked', ['agent needs a decision'], { decisions: r.decisions, newTasks }) : out('failure', ['agent reported blocked without a decision request']);
+  }
+  const reasons = [];
+  if (r.status === 'failed') reasons.push(`agent reported failure: ${r.summary || 'no summary'}`);
+  if (!r.summary?.trim()) reasons.push('summary is empty');
+  if (repoRoot) for (const o of task.outputs ?? []) if (!existsSync(resolve(repoRoot, o))) reasons.push(`required output missing: ${o}`);
+  const criteria = task.acceptance?.length ? task.acceptance : ['the goal is achieved and verified'];
+  criteria.forEach((c, i) => {
+    const id = `A${i + 1}`;
+    const entry = (r.acceptance ?? []).find(a => a?.id === id);
+    if (!entry) reasons.push(`acceptance ${id} not reported (${c})`);
+    else if (entry.met !== true) reasons.push(`acceptance ${id} not met (${c})${entry.evidence ? `: ${entry.evidence}` : ''}`);
+    else if (!String(entry.evidence ?? '').trim()) reasons.push(`acceptance ${id} claimed without evidence`);
+  });
+  const denied = dangerousCommands(r.commandsRun, { shell: 'true', network: false });
+  if (denied.length) {
+    return out('blocked', denied.map(d => `command refused: ${d.command} (${d.reason})`), {
+      decisions: denied.map(d => ({ key: `shell:${d.command}`, question: `Run \`${d.command}\`?`, flags: d.flags ?? ['destructive_action'], options: [{ id: 'no', summary: 'do not run it', reversible: true }, { id: 'yes', summary: d.command, reversible: false, flags: d.flags ?? ['destructive_action'] }] })),
+      newTasks,
+    });
+  }
+  const changes = run.worktree?.agentChanges ?? [];
+  if (task.kind === 'implement' && run.worktree?.before?.source && !changes.length && r.status === 'completed') reasons.push('no file changes detected against the workspace baseline');
+  if (changes.some(c => String(c.path).includes('..'))) reasons.push('change escaped the workspace');
+  const blockingIssues = (r.remainingIssues ?? []).filter(isBlocking);
+  // A review's job is to report blocking issues; for other tasks they mean the work is not done —
+  // EXCEPT investigations, where reporting open questions / multiple valid directions IS the work.
+  if (blockingIssues.length && task.kind !== 'review') {
+    if (task.kind === 'investigate') {
+      // Safety issues still gate; decision-shaped issues become a user decision;
+      // advisory issues are the deliverable and do not fail the task.
+      const safety = blockingIssues.filter(i => classifyBlockingIssue(i) === 'safety');
+      const decisionIssues = blockingIssues.filter(i => classifyBlockingIssue(i) === 'decision');
+      if (safety.length) {
+        reasons.push(...safety.map(i => `blocking issue: ${i.summary}`));
+      } else if (decisionIssues.length && r.status === 'completed') {
+        // Investigation surfaced a genuine either/or choice -> needs_decision, not failure.
+        return out('blocked', decisionIssues.map(i => `blocking issue: ${i.summary}`), {
+          decisions: decisionIssues.map(i => ({
+            key: `investigate:${i.summary}`,
+            question: i.summary,
+            flags: i.flags ?? [],
+            options: i.options ?? [{ id: 'proceed', summary: 'proceed with the recommended interpretation', reversible: true }, { id: 'clarify', summary: 'ask the user to clarify', reversible: true }],
+            recommended: i.recommended,
+          })),
+          newTasks,
+        });
+      }
+      // advisory blockingIssues fall through to success
+    } else {
+      reasons.push(...blockingIssues.map(i => `blocking issue: ${i.summary}`));
+    }
+  }
+  if (reasons.length) return out('failure', reasons, { newTasks });
+  return out('success', [], { newTasks, blockingIssues });
+}