@ludi-uni/ludi-agent-kit 0.1.0

package/scripts/check-environment.ps1

@@ -0,0 +1,22 @@
+#requires -Version 7.0
+# Read-only environment check: which runtimes/tools this machine actually has. Never contacts a model.
+[CmdletBinding()] param()
+$ErrorActionPreference = 'Continue'
+function Probe([string]$Name, [scriptblock]$Cmd) {
+    $v = $null
+    try { $v = (& $Cmd 2>$null | Select-Object -First 1); if ($LASTEXITCODE -and $LASTEXITCODE -ne 0) { $v = $null } } catch { $v = $null }
+    [pscustomobject]@{ tool = $Name; present = [bool]$v; version = "$v".Trim() }
+}
+$rows = @(
+    Probe 'pwsh'    { pwsh --version }
+    Probe 'node'    { node --version }
+    Probe 'git'     { git --version }
+    Probe 'pi'      { pi --version }
+    Probe 'codex'   { codex --version }
+    Probe 'ffmpeg'  { ffmpeg -version }
+    Probe 'ffprobe' { ffprobe -version }
+    Probe 'winapp'  { winapp --version }
+)
+$agentDir = if ($env:PI_CODING_AGENT_DIR) { $env:PI_CODING_AGENT_DIR } else { Join-Path $env:USERPROFILE '.pi/agent' }
+$rows += [pscustomobject]@{ tool = 'pi agent dir'; present = (Test-Path $agentDir); version = $agentDir }
+$rows | Format-Table -AutoSize

package/scripts/context-pack.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+// Validate one Context Pack (.md or .json) and optionally print its JSON or canonical Markdown.
+// Usage: node scripts/context-pack.mjs <file> [--json|--md]
+import { readFileSync } from 'node:fs';
+import { parseContextPackMarkdown, validateContextPack, toMarkdown } from '../lib/context-pack.mjs';
+
+const [file, mode] = process.argv.slice(2);
+if (!file) { console.error('usage: context-pack.mjs <file.md|file.json> [--json|--md]'); process.exit(2); }
+const text = readFileSync(file, 'utf8');
+let pack;
+try { pack = file.toLowerCase().endsWith('.json') ? JSON.parse(text) : parseContextPackMarkdown(text); }
+catch (e) { console.error(e.message); process.exit(1); }
+const errors = validateContextPack(pack);
+if (errors.length) { console.error(errors.join('\n')); process.exit(1); }
+if (mode === '--json') console.log(JSON.stringify(pack, null, 2));
+else if (mode === '--md') console.log(toMarkdown(pack));
+else console.log(`PASS ${file}: ${pack.relevant_files.length} files, ${(pack.relevant_snippets ?? []).length} snippets`);

package/scripts/e2e-investigate-repro.mjs

@@ -0,0 +1,66 @@
+// Read-only reproduction for run-muf1egtr-d13d8a: a single investigate task on a
+// small fixture repo. Verifies (1) correct repo cwd, (2) cheap-code primary chain
+// order, (3) local fallback after a primary failure, (4) expired health marks
+// re-enter the candidate pool, (5) scout completion. No code changes.
+//   node scripts/e2e-investigate-repro.mjs
+import { mkdtempSync, cpSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import assert from 'node:assert/strict';
+import { loadRouting } from '../lib/routing.mjs';
+import { loadRegistry } from '../lib/registry.mjs';
+import { loadAgents } from '../lib/agents.mjs';
+import { loadPolicy, mergePolicy } from '../lib/orchestrator/policy.mjs';
+import { openStore } from '../lib/orchestrator/store.mjs';
+import { createHealthMonitor } from '../lib/orchestrator/health.mjs';
+import { createAgentRunner } from '../lib/orchestrator/runner.mjs';
+import { orchestrate, formatReport } from '../lib/orchestrator/orchestrator.mjs';
+import { createPiInvoker } from '../adapters/pi/lib/invoke.mjs';
+import { createPiSubagentRunner } from '../adapters/pi/lib/subagent.mjs';
+
+const kit = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const root = mkdtempSync(join(tmpdir(), 'ludi-repro-'));
+const repo = join(root, 'repo');
+const storePath = join(root, 'state.db');
+cpSync(join(kit, 'tests/fixtures/math-repo'), repo, { recursive: true });
+for (const args of [['init'], ['add', '-A'], ['-c', 'user.email=ludi@example.com', '-c', 'user.name=ludi', 'commit', '-m', 'fixture']]) {
+  const git = spawnSync('git', args, { cwd: repo, encoding: 'utf8' });
+  if (git.status !== 0) { console.error(git.stderr); process.exit(git.status ?? 1); }
+}
+
+const plan = [
+  { id: 't1', title: 'Investigate entrypoint and test command', goal: 'Read the repository and report: the main entrypoint and the exact test command. Do not edit files.', agent: 'scout', kind: 'investigate', capability: 'cheap-code', executionMode: 'subagent', dependencies: [], acceptance: ['the main entrypoint file is named', 'the exact test command is named'] },
+];
+
+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 } = loadAgents(join(kit, 'agents'), routing);
+const { policy } = loadPolicy(join(kit, 'orchestration/decision-policy.json'));
+const active = mergePolicy(policy, { limits: { max_retries: 1 }, agent_runtime: { max_runtime_ms: 300000, max_tool_calls: 25, max_turns: 8 } });
+const session = openStore(storePath);
+const health = createHealthMonitor({ session, policy: active });
+
+// (4) Seed an EXPIRED usage_exhausted mark on the cheap primary: it must not block candidacy.
+session.recordHealth({ provider: 'openai-codex', model: 'gpt-5.6-luna', state: 'usage_exhausted', reason: 'stale test mark', runId: '', ttlMs: -1000, now: new Date(Date.now() - 60_000).toISOString() });
+const staleSkip = session.activeHealth({ provider: 'openai-codex', model: 'gpt-5.6-luna', runId: 'probe', now: new Date().toISOString() });
+console.log('expired health mark active?', staleSkip ? `BUG still active until ${staleSkip.expiresAt}` : 'no (correctly ignored)');
+
+const runner = createAgentRunner({
+  invoke: createPiInvoker(), runSubagent: createPiSubagentRunner(), agents, routing, registry, repoRoot: repo, policy: active, health,
+  maxModelAttempts: active.limits.model_attempts_per_task,
+});
+try {
+  const result = await orchestrate({ request: 'Investigate only: identify the main entrypoint and the test command for this repo', plan, agents, routing, registry, policy: active, runner, repoRoot: repo, session, health });
+  writeFileSync(join(root, 'trace.json'), JSON.stringify(result, null, 2));
+  console.log(formatReport(result));
+  const steps = result.trace.filter(e => e.type === 'result').flatMap(e => e.steps ?? []);
+  console.log('MODEL STEPS:', JSON.stringify(steps.map(s => ({ backend: s.backend, modelId: s.modelId, skipped: !!s.skipped, ok: s.ok, reason: s.reason })), null, 2));
+  const t1 = result.tasks.find(t => t.id === 't1');
+  console.log('t1:', t1.status, '| summary:', String(t1.result?.summary ?? '').slice(0, 300));
+  if (result.status === 'completed') console.log('PASS: read-only investigate E2E');
+  else { console.log('FAIL: investigate did not complete'); process.exitCode = 1; }
+} finally {
+  session.close();
+}

package/scripts/model-maintenance-job.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// Phase 5 — scheduler-safe maintenance job entrypoint.
+//   observe -> dedupe -> catalog diff -> meaningful-change gate -> proposal ->
+//   maintenance preview -> optional live tiers -> notification decision -> sinks.
+// Quiet by default; writes only under adapters/<x>/out/. Never touches
+// model-catalog.json, routing.json, models*.json, settings.json, ~/.pi, credentials.
+//
+// Usage:
+//   node scripts/model-maintenance-job.mjs                          # diff store vs catalog, quiet exit if nothing meaningful
+//   node scripts/model-maintenance-job.mjs --source fixture --input announcements.json
+//   node scripts/model-maintenance-job.mjs --check-pi               # + pi --list-models availability
+//   node scripts/model-maintenance-job.mjs --check-qoder            # + qoder-models-cache.json priceFactor (free campaigns)
+//   node scripts/model-maintenance-job.mjs --check pi-cli,qoder-cache # generic observer list
+//   node scripts/model-maintenance-job.mjs --live                   # + real tier invocations (spends quota)
+//   node scripts/model-maintenance-job.mjs --shadow                 # observe only; no external notify unless --shadow-notify
+//   node scripts/model-maintenance-job.mjs --notify-command "node send.js"   # explicit external sink
+import { resolve, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadRouting } from '../lib/routing.mjs';
+import { loadRegistry } from '../lib/registry.mjs';
+import { loadAgents } from '../lib/agents.mjs';
+import { loadCatalog } from '../lib/maintenance.mjs';
+import { loadExecPolicy } from '../lib/maintenance-exec.mjs';
+import { runMaintenanceJob } from '../lib/job.mjs';
+
+const kit = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const args = process.argv.slice(2);
+const opt = (name, def) => { const i = args.indexOf(`--${name}`); return i >= 0 ? args[i + 1] : def; };
+const has = name => args.includes(`--${name}`);
+const adapter = opt('adapter', 'pi');
+const adapterDir = join(kit, 'adapters', adapter);
+const outDir = join(adapterDir, 'out');
+
+const routing = loadRouting(join(kit, 'routing/routing.json'));
+const { registry } = loadRegistry(join(adapterDir, 'models.json'), join(adapterDir, 'models.local.json'), routing);
+const { agents, errors } = loadAgents(join(kit, 'agents'), routing);
+if (errors.length) { console.error(errors.join('\n')); process.exit(1); }
+const catalog = loadCatalog(join(adapterDir, 'model-catalog.json'));
+const policy = loadExecPolicy(opt('policy', join(adapterDir, 'maintenance-policy.json')));
+
+let invoke = null;
+if (has('live')) {
+  const { createPiInvoker } = await import(`../adapters/${adapter}/lib/invoke.mjs`);
+  invoke = createPiInvoker();
+}
+
+const run = await runMaintenanceJob({
+  outDir, adapterDir, kit, catalog, routing, registry, agents, policy,
+  source: opt('source', null), input: opt('input', null),
+  checkPi: has('check-pi'), checkQoder: has('check-qoder'), check: opt('check', null), qoderCachePath: opt('qoder-cache', null), live: has('live'), invoke,
+  notifyCommand: opt('notify-command', null),
+  shadow: has('shadow'), shadowNotify: has('shadow-notify'),
+});
+
+if (run.status === 'skipped-locked') { console.log('maintenance job: skipped (another run holds the lock)'); process.exit(0); }
+if (run.status === 'error') { console.error(`maintenance job: error ${run.error}`); process.exit(1); }
+console.log(`maintenance job ${run.runId}: ${run.quiet ? `quiet (${run.verdict.quietReason})` : `${run.verdict.severity} — ${run.notification?.summary ?? ''}`}`);
+if (run.notification) console.log(`  notification: sent=${run.notification.sent} (${run.notification.dedupeReason})${run.budgetLimited ? ' [budgetLimited]' : ''}`);
+process.exit(run.quiet ? 0 : 2); // 2 = meaningful change pending human review (scheduler-friendly)

package/scripts/observe-models.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// Phase 4 — observation pipeline: external sources -> normalized observations ->
+// JSONL store -> catalog diff -> catalog proposal -> optional maintenance preview.
+// Dry-run only: writes exclusively to adapters/<x>/out/. Never touches
+// model-catalog.json, routing.json, models*.json, settings.json, ~/.pi, credentials.
+//
+// Usage:
+//   node scripts/observe-models.mjs --source manual --input observations.json
+//   node scripts/observe-models.mjs --source fixture --input announcements.json
+//   node scripts/observe-models.mjs --check-pi                 # pi --list-models availability
+//   node scripts/observe-models.mjs --check-qoder              # qoder-models-cache.json priceFactor (free campaigns)
+//   node scripts/observe-models.mjs --check pi-cli,qoder-cache  # generic observer list (same ids)
+//   node scripts/observe-models.mjs                            # diff store vs catalog (no new input)
+//   node scripts/observe-models.mjs --preview-maintenance      # + hypothetical catalog -> maintenance dry-run
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadRouting } from '../lib/routing.mjs';
+import { loadRegistry } from '../lib/registry.mjs';
+import { loadAgents } from '../lib/agents.mjs';
+import { loadCatalog } from '../lib/maintenance.mjs';
+import { ingestObservations, loadObservationStore, productionObservations } from '../lib/observe/observation.mjs';
+import { SOURCES } from '../lib/observe/sources.mjs';
+import { OBSERVERS, resolveRequestedObservers, runObservers } from '../lib/observe/observers.mjs';
+import { diffCatalog, buildCatalogProposal, applyProposalToCatalog } from '../lib/observe/differ.mjs';
+import { runMaintenancePlan, loadExecPolicy } from '../lib/maintenance-exec.mjs';
+
+const kit = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const args = process.argv.slice(2);
+const opt = (name, def) => { const i = args.indexOf(`--${name}`); return i >= 0 ? args[i + 1] : def; };
+const has = name => args.includes(`--${name}`);
+const adapter = opt('adapter', 'pi');
+const adapterDir = join(kit, 'adapters', adapter);
+const outDir = join(adapterDir, 'out');
+mkdirSync(outDir, { recursive: true });
+
+const catalog = loadCatalog(join(adapterDir, 'model-catalog.json'));
+const storePath = join(outDir, 'model-observations.jsonl');
+
+// 1. collect observations — an explicit --input file, plus any requested live
+// observers. Selection/execution is registry-driven (lib/observe/observers.mjs):
+// --check-pi/--check-qoder/--check <list> resolve to observer ids and run once
+// each, in order; one observer's failure never blocks the others.
+let fresh = [];
+if (opt('input', null)) {
+  const source = opt('source', 'manual');
+  const fn = SOURCES[source];
+  if (!fn) { console.error(`unknown --source "${source}"; expected ${Object.keys(SOURCES).join('|')}`); process.exit(1); }
+  fresh = fn(resolve(opt('input')));
+}
+const requested = resolveRequestedObservers({ checkPi: has('check-pi'), checkQoder: has('check-qoder'), check: opt('check', null) });
+if (requested.unknown.length) { console.error(`unknown observer id(s): ${requested.unknown.join(', ')}; known: ${Object.keys(OBSERVERS).join(', ')}`); process.exit(1); }
+if (requested.ids.length) {
+  const r = await runObservers(requested.ids, { catalog, outDir, observedAt: new Date().toISOString(), qoderCachePath: opt('qoder-cache', null) });
+  fresh.push(...r.observations);
+  for (const res of r.results) {
+    if (res.probeFailed) console.error(`${res.id}: ${res.metadata?.reason ?? 'probe failed'}; no observations ingested (unknown, not absent)`);
+    else if (res.metadata?.noTransition) console.log(`${res.id}: no transition; no observations ingested`);
+  }
+}
+
+// 2. ingest into the JSONL store (dedupe/stale handled inside)
+const ingest = fresh.length ? ingestObservations(storePath, fresh) : { stored: [], duplicates: [], stale: [], invalid: [] };
+const store = loadObservationStore(storePath);
+
+// 3. diff production observations against the catalog (test/fixture records are
+// stored for audit but excluded from real proposals)
+const prodObs = productionObservations(store.observations);
+const diff = diffCatalog(catalog, prodObs);
+const diffFile = join(outDir, 'catalog-diff.json');
+writeFileSync(diffFile, JSON.stringify(diff, null, 2) + '\n');
+
+// 4. proposal
+const proposal = buildCatalogProposal(catalog, diff, prodObs);
+const proposalFile = join(outDir, 'model-catalog.proposal.json');
+writeFileSync(proposalFile, JSON.stringify(proposal, null, 2) + '\n');
+
+// 5. optional: hypothetical catalog -> maintenance dry-run preview
+let previewFile = null;
+if (has('preview-maintenance')) {
+  const hypothetical = applyProposalToCatalog(catalog, proposal);
+  const routing = loadRouting(join(kit, 'routing/routing.json'));
+  const { registry } = loadRegistry(join(adapterDir, 'models.json'), join(adapterDir, 'models.local.json'), routing);
+  const { agents, errors } = loadAgents(join(kit, 'agents'), routing);
+  if (errors.length) { console.error(errors.join('\n')); process.exit(1); }
+  const policy = loadExecPolicy(join(adapterDir, 'maintenance-policy.json'));
+  const preview = runMaintenancePlan({ routing, registry, agents, catalog: hypothetical, events: [], policy });
+  preview.hypothetical = true;
+  preview.note = 'catalog proposal applied in memory only; model-catalog.json and routing.json unchanged';
+  previewFile = join(outDir, 'maintenance-preview.json');
+  writeFileSync(previewFile, JSON.stringify(preview, null, 2) + '\n');
+}
+
+console.log(`observe: ${fresh.length} fresh, stored ${ingest.stored.length}, dup ${ingest.duplicates.length}, stale ${ingest.stale.length}, invalid ${ingest.invalid.length}`);
+console.log(`  diff: ${diff.diffs.length} rows (${diff.diffs.filter(d => d.status === 'proposed').length} proposed, ${diff.diffs.filter(d => d.status === 'conflict').length} conflict) -> ${diffFile}`);
+console.log(`  proposal: +${proposal.additions.length} add, ${proposal.updates.length} update, ${proposal.deprecations.length} deprecate, ${proposal.conflicts.length} conflict -> ${proposalFile}`);
+if (previewFile) console.log(`  preview: ${previewFile} (hypothetical catalog; nothing applied)`);

package/scripts/orchestrate.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+// Orchestrate one high-level request, or resume a persisted run.
+// Usage:
+//   node scripts/orchestrate.mjs [--dry-run] [--planner rules|model] [--repo <dir>] [--apply]
+//                                [--policy <file>] [--store <db>] [--out <dir>] [--json] [--trace] "<request>"
+//   node scripts/orchestrate.mjs --list [--status <run-status>] [--store <db>]
+//   node scripts/orchestrate.mjs --decisions [--resume <run-id>] [--store <db>]
+//   node scripts/orchestrate.mjs --show <run-id> [--store <db>]
+//   node scripts/orchestrate.mjs --resume <run-id> [--answer <decision-id> "<text>"] [--store <db>] [--repo <dir>] [--apply]
+//   node scripts/orchestrate.mjs --prune [--older-than 7d] [--store <db>]        # delete terminal run history
+//   node scripts/orchestrate.mjs --delete <run-id> [--force] [--store <db>]     # preview, or delete with --force
+//   node scripts/orchestrate.mjs --clear [--force] [--include-active] [--store <db>]  # preview, or delete with --force
+// --dry-run plans and routes only. A real run is stored under .orchestration/state.db (or --store / LUDI_ORCHESTRATION_STORE).
+// Cleanup touches terminal runs only (completed/failed/cancelled with no pending decisions); --include-active
+// additionally removes running/waiting_for_user runs that have no pending decisions. Global decision memory,
+// protocol stats and global backend health are never deleted.
+import { resolve, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { loadRouting } from '../lib/routing.mjs';
+import { loadRegistry } from '../lib/registry.mjs';
+import { loadAgents } from '../lib/agents.mjs';
+import { loadPolicy } from '../lib/orchestrator/policy.mjs';
+import { dryRun, formatPlan } from '../lib/orchestrator/orchestrator.mjs';
+import {
+  defaultStorePath, loadOrchestrationContext, listOrchestrationRuns, pendingDecisions, showRun,
+  createRunHealth, createRunRunner, startOrchestration, resumeOrchestration, formatReport, formatRunList,
+  parseOlderThan, previewRunCleanup, pruneOrchestrationRuns, deleteOrchestrationRun, clearOrchestrationRuns,
+  formatCleanup,
+} from '../lib/orchestrator/api.mjs';
+import { createPiInvoker } from '../adapters/pi/lib/invoke.mjs';
+import { createPiSubagentRunner } from '../adapters/pi/lib/subagent.mjs';
+
+const kit = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const args = process.argv.slice(2);
+const VALUED = new Set(['planner', 'repo', 'policy', 'out', 'request', 'store', 'resume', 'status', 'show', 'delete', 'older-than']);
+const opts = {}, positional = [];
+opts.answers = [];
+for (let i = 0; i < args.length; i++) {
+  const a = args[i];
+  if (!a.startsWith('--')) { positional.push(a); continue; }
+  const name = a.slice(2);
+  if (name === 'answer') { opts.answers.push({ decisionId: args[++i], answer: args[++i] }); continue; }
+  opts[name] = VALUED.has(name) ? args[++i] : true;
+}
+const cleanupMode = !!(opts.prune || opts.delete || opts.clear);
+const request = opts.request ?? (opts.resume || opts.list || opts.decisions || opts.show || cleanupMode ? '' : positional.join(' '));
+const storePath = resolve(opts.store ?? defaultStorePath(kit));
+const usage = 'usage: orchestrate.mjs [--dry-run] [--planner rules|model] [--repo dir] [--apply] [--policy file] [--store db] [--out dir] [--json] [--trace] "<request>" | --list [--status] | --decisions [--resume id] | --show id | --resume id [--answer decision-id text] | --prune [--older-than 7d] | --delete id [--force] | --clear [--force] [--include-active]';
+if (!request && !opts.resume && !opts.list && !opts.decisions && !opts.show && !cleanupMode) { console.error(usage); process.exit(2); }
+// Cleanup flag validation.
+const cleanupFlags = [opts.prune && '--prune', opts.delete && '--delete', opts.clear && '--clear'].filter(Boolean);
+if (cleanupFlags.length > 1) { console.error(`cleanup modes are exclusive: ${cleanupFlags.join(' ')}`); process.exit(2); }
+if (opts['older-than'] && !opts.prune) { console.error('--older-than requires --prune'); process.exit(2); }
+if (opts['include-active'] && !opts.clear) { console.error('--include-active requires --clear'); process.exit(2); }
+if (opts.force && !opts.delete && !opts.clear) { console.error('--force requires --delete or --clear'); process.exit(2); }
+let olderThanMs = null;
+if (opts['older-than']) {
+  try { olderThanMs = parseOlderThan(opts['older-than']); }
+  catch (e) { console.error(e.message); process.exit(2); }
+}
+const planner = opts.planner ?? 'rules';
+if (!['rules', 'model'].includes(planner)) { console.error(`unknown planner "${planner}"`); process.exit(2); }
+
+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);
+if (errors.length) { console.error(errors.join('\n')); process.exit(1); }
+const { policy } = opts.policy
+  ? loadPolicy(join(kit, 'orchestration/decision-policy.json'), resolve(opts.policy))
+  : loadPolicy(join(kit, 'orchestration/decision-policy.json'), join(kit, 'orchestration/decision-policy.local.json'));
+const repoRoot = opts.repo ? resolve(opts.repo) : null;
+const outDir = resolve(opts.out ?? join(kit, 'adapters/pi/out/orchestrate'));
+
+if (opts['dry-run'] && !cleanupMode) {
+  const invoke = planner === 'model' ? createPiInvoker() : null;
+  const dry = await dryRun(request, { planner, agents, routing, registry, policy, invoke, cwd: repoRoot ?? process.cwd() });
+  console.log(opts.json ? JSON.stringify(dry, null, 2) : formatPlan(dry));
+  process.exitCode = dry.errors.length ? 1 : 0;
+} else {
+  const ctx = loadOrchestrationContext({
+    kit, storePath,
+    policyPath: opts.policy ? resolve(opts.policy) : null,
+    localPolicyPath: opts.policy ? null : join(kit, 'orchestration/decision-policy.local.json'),
+  });
+  if (ctx.errors.length) { console.error(ctx.errors.join('\n')); ctx.session.close(); process.exit(1); }
+  try {
+    if (opts.list) {
+      const rows = listOrchestrationRuns(ctx, { status: opts.status ?? null });
+      console.log(opts.json ? JSON.stringify(rows, null, 2) : formatRunList(rows));
+    } else if (opts.decisions) {
+      const rows = pendingDecisions(ctx, { runId: opts.resume ?? null });
+      console.log(opts.json ? JSON.stringify(rows, null, 2) : (rows.length ? rows.map(d => `${d.runId}  ${d.id}  [${d.taskId}] ${d.question}`).join('\n') : 'decisions: none'));
+    } else if (opts.show) {
+      const shown = showRun(ctx, opts.show);
+      console.log(opts.json ? JSON.stringify(shown, null, 2) : formatReport(shown));
+    } else if (opts.prune) {
+      try {
+        const result = opts['dry-run']
+          ? previewRunCleanup(ctx, { olderThan: new Date(Date.now() - (olderThanMs ?? 7 * 86_400_000)).toISOString() })
+          : pruneOrchestrationRuns(ctx, { olderThanMs });
+        console.log(opts.json ? JSON.stringify(result, null, 2) : formatCleanup(result, { verb: '削除', hint: '--prune' }));
+      } catch (e) { console.error(`整理できません: ${e.message}`); process.exitCode = 1; }
+    } else if (opts.delete) {
+      const id = opts.delete === true ? positional[0] : opts.delete;
+      if (!id || String(id).startsWith('--')) { console.error('--delete requires a run id'); process.exit(2); }
+      try {
+        const result = deleteOrchestrationRun(ctx, id, { force: !!opts.force });
+        console.log(opts.json ? JSON.stringify(result, null, 2) : `削除しました: ${result.id} (tasks:${result.deleted.tasks} decisions:${result.deleted.decisions} trace:${result.deleted.trace} health:${result.deleted.health})`);
+      } catch (e) { console.error(`削除できません: ${e.message}`); process.exitCode = 1; }
+    } else if (opts.clear) {
+      try {
+        const result = clearOrchestrationRuns(ctx, { force: !!opts.force, includeActive: !!opts['include-active'] });
+        console.log(opts.json ? JSON.stringify(result, null, 2) : formatCleanup(result, { verb: '削除' }));
+      } catch (e) { console.error(`整理できません: ${e.message}`); process.exitCode = 1; }
+    } else {
+      const health = createRunHealth(ctx);
+      const invoke = createPiInvoker();
+      const runner = createRunRunner(ctx, { invoke, runSubagent: createPiSubagentRunner(), repoRoot, outDir, apply: !!opts.apply, health });
+      const result = opts.resume
+        ? await resumeOrchestration(ctx, { runId: opts.resume, answers: opts.answers, repoRoot, runner, invoke, health })
+        : await startOrchestration(ctx, { request, repoRoot, planner, runner, invoke, health });
+      mkdirSync(outDir, { recursive: true });
+      const traceFile = join(outDir, 'orchestration-trace.json');
+      writeFileSync(traceFile, JSON.stringify(result, null, 2));
+      if (opts.json) console.log(JSON.stringify({ ...result, trace: opts.trace ? result.trace : undefined }, null, 2));
+      else {
+        console.log(formatReport(result));
+        console.log(`\nrun: ${result.runId}`);
+        if (opts.trace) console.log(`trace: ${traceFile}`);
+      }
+      process.exitCode = result.status === 'completed' ? 0 : 1;
+    }
+  } finally {
+    ctx.session.close();
+  }
+}

package/scripts/reevaluate-models.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// Periodic maintenance: re-evaluate capability -> backend -> model bindings when provider
+// conditions change (free campaign end, quota/rate-limit change, deprecation, price change,
+// new model added). Phase 2 adds execution tiers: monitor -> evaluate -> reconfigure,
+// each selecting a model under the cheapest-sufficient policy (free first, then cheapest
+// eligible cloud, then local fallback). This run is a dry-run decision layer: it selects
+// which model each tier WOULD use and records the rationale — no model is invoked.
+//
+// Reads routing.json, agents/, adapters/<x>/models.json + models.local.json,
+// model-catalog.json, maintenance-policy.json and an events file. Writes ONLY to
+// adapters/<x>/out/: model-maintenance.proposal.json (Phase 1 proposal) and
+// model-maintenance.run.json (per-tier selection + escalation audit). Never touches
+// ~/.pi, settings.json, models.json, models.local.json or routing.json.
+//
+// Usage:
+//   node scripts/reevaluate-models.mjs [--adapter pi] [--events <events.json>]
+//       [--availability-file <list.txt>] [--check-availability] [--margin <n>]
+//       [--policy <maintenance-policy.json>] [--live] [--stdout]
+//
+// --live: actually invoke the selected tier models through the pi CLI (spends quota).
+//   Without it the run is a pure dry-run decision layer. Even --live writes only
+//   out/ reports — never ~/.pi, settings.json, models*.json or routing.json.
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadRouting } from '../lib/routing.mjs';
+import { loadRegistry } from '../lib/registry.mjs';
+import { loadAgents } from '../lib/agents.mjs';
+import { loadCatalog, loadEvents, loadAvailabilityFile } from '../lib/maintenance.mjs';
+import { runMaintenancePlan, loadExecPolicy } from '../lib/maintenance-exec.mjs';
+
+const kit = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const args = process.argv.slice(2);
+const opt = (name, def) => { const i = args.indexOf(`--${name}`); return i >= 0 ? args[i + 1] : def; };
+const has = name => args.includes(`--${name}`);
+const adapter = opt('adapter', 'pi');
+const adapterDir = join(kit, 'adapters', adapter);
+
+const routing = loadRouting(join(kit, 'routing/routing.json'));
+const { registry, sources } = loadRegistry(join(adapterDir, 'models.json'), join(adapterDir, 'models.local.json'), routing);
+const { agents, errors } = loadAgents(join(kit, 'agents'), routing);
+if (errors.length) { console.error(errors.join('\n')); process.exit(1); }
+const catalog = loadCatalog(join(adapterDir, 'model-catalog.json'));
+const events = opt('events', null) ? loadEvents(resolve(opt('events'))) : [];
+const policy = loadExecPolicy(opt('policy', join(adapterDir, 'maintenance-policy.json')));
+
+let availability = null, availabilitySource = 'not-checked';
+if (has('check-availability')) {
+  availabilitySource = 'pi --list-models (failed)';
+  try {
+    const { fetchPiAvailability } = await import(`../adapters/${adapter}/lib/list-models.mjs`);
+    availability = fetchPiAvailability();
+    if (availability) availabilitySource = availability.source;
+  } catch { availability = null; }
+} else if (opt('availability-file', null)) {
+  availability = loadAvailabilityFile(resolve(opt('availability-file')));
+  availabilitySource = availability.source;
+}
+
+const margin = Number(opt('margin', NaN)) || undefined;
+let run;
+if (has('live')) {
+  const { createPiInvoker } = await import(`../adapters/${adapter}/lib/invoke.mjs`);
+  const { runMaintenanceLive } = await import('../lib/maintenance-runner.mjs');
+  const invoke = createPiInvoker();
+  run = await runMaintenanceLive({ routing, registry, agents, catalog, events, availability, policy, margin, invoke });
+} else {
+  run = runMaintenancePlan({ routing, registry, agents, catalog, events, availability, policy, margin });
+}
+run.adapter = adapter;
+run.inputs = { registrySources: sources, catalog: join(adapterDir, 'model-catalog.json'), policy: opt('policy', join(adapterDir, 'maintenance-policy.json')), events: opt('events', null), availabilitySource };
+run.apply = {
+  auto: false,
+  how: 'edit adapters/<x>/models.local.json per change.proposedModel, then re-run scripts/resolve-capabilities.mjs and merge out/settings.proposal.json into live settings.json',
+  never: ['~/.pi/agent/settings.json', 'adapters/*/models.json', 'adapters/*/models.local.json', 'routing/routing.json', 'provider credentials'],
+};
+
+const outDir = join(adapterDir, 'out');
+mkdirSync(outDir, { recursive: true });
+const runFile = join(outDir, 'model-maintenance.run.json');
+writeFileSync(runFile, JSON.stringify(run, null, 2) + '\n');
+let proposalFile = null;
+if (run.proposal) {
+  proposalFile = join(outDir, 'model-maintenance.proposal.json');
+  writeFileSync(proposalFile, JSON.stringify(run.proposal, null, 2) + '\n');
+}
+
+const tierSummary = run.tiers.map(t => `${t.role}:${t.selected?.model ?? 'none'}($${t.selected?.effectiveCostUsd ?? '?'})`).join(' -> ');
+console.log(`model-maintenance: ${run.outcome}; tiers ${tierSummary}; est decision cost $${run.estimatedDecisionCostUsd}`);
+console.log(`  run report -> ${runFile}${proposalFile ? `; proposal -> ${proposalFile}` : ''}`);
+if (run.escalation) console.log(`  escalation: ${run.escalation.sourceTier} -> ${run.escalation.targetTier}: ${run.escalation.escalationReason}`);
+if (run.invocations?.length) {
+  for (const inv of run.invocations) console.log(`  invoked ${inv.tier}: ${inv.selectedModel ?? 'none'}${inv.fallbackOccurred ? ' (fallback)' : ''}${inv.degradedToDeterministic ? ' [deterministic-only]' : ''}`);
+}
+if (has('stdout')) console.log(JSON.stringify(run, null, 2));

package/scripts/report-model-maintenance.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+// Phase 6 — calibration report: aggregate telemetry -> human-readable report +
+// deterministic warnings + counterfactuals + policy calibration proposal.
+// Read-only w.r.t. policy/catalog/routing; writes only out/ artifacts.
+//
+// Usage:
+//   node scripts/report-model-maintenance.mjs [--adapter pi] [--days 14] [--json]
+//   node scripts/report-model-maintenance.mjs --compact --days 30   # retention compaction
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadTelemetry, calibrationWarnings, counterfactuals, calibrationProposal, compactTelemetry } from '../lib/telemetry.mjs';
+import { loadExecPolicy } from '../lib/maintenance-exec.mjs';
+
+const kit = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const args = process.argv.slice(2);
+const opt = (name, def) => { const i = args.indexOf(`--${name}`); return i >= 0 ? args[i + 1] : def; };
+const has = name => args.includes(`--${name}`);
+const adapter = opt('adapter', 'pi');
+const adapterDir = join(kit, 'adapters', adapter);
+const outDir = join(adapterDir, 'out');
+const days = Number(opt('days', 14));
+const policy = loadExecPolicy(opt('policy', join(adapterDir, 'maintenance-policy.json')));
+
+if (has('compact')) {
+  const r = compactTelemetry(outDir, { days });
+  console.log(`retention: compacted ${r.compacted} old run(s), kept ${r.kept}`);
+}
+
+const t = loadTelemetry(outDir);
+const warnings = calibrationWarnings(t, policy);
+const cf = counterfactuals(t, 10);
+const cal = calibrationProposal(t, policy);
+mkdirSync(outDir, { recursive: true });
+const calFile = join(outDir, 'maintenance-policy.calibration.proposal.json');
+writeFileSync(calFile, JSON.stringify(cal, null, 2) + '\n');
+
+const pct = (a, b) => (b ? `${((a / b) * 100).toFixed(0)}%` : 'n/a');
+const avg = t.runs ? t.cost.totalUsd / t.runs : 0;
+const avgMargin = t.qualityMargins.length ? t.qualityMargins.reduce((a, b) => a + b, 0) / t.qualityMargins.length : null;
+const top = (obj, n = 5) => Object.entries(obj ?? {}).sort((a, b) => b[1] - a[1]).slice(0, n);
+
+const report = {
+  activity: { totalRuns: t.runs, quietRuns: t.quietRuns, quietRatio: pct(t.quietRuns, t.runs), meaningful: t.meaningfulRuns, notifications: t.notifications, deduped: t.dedupedNotifications, dedupeRate: pct(t.dedupedNotifications, t.notifications) },
+  cost: { totalUsd: +t.cost.totalUsd.toFixed(4), apiUsd: +t.cost.apiUsd.toFixed(4), localElectricityUsd: +t.cost.localElectricityUsd.toFixed(4), avgPerRun: +avg.toFixed(4), premiumInvocations: t.premiumInvocations, budgetLimited: t.budgetLimited },
+  routing: { invocations: t.invocations, fallbacks: t.fallbacks, localFallbacks: t.localFallbacks, topSelected: top(t.selectedModels), topRejected: top(t.rejectedReasons) },
+  quality: { avgQualityMargin: avgMargin === null ? null : +avgMargin.toFixed(1), borderlineSelections: t.borderline.length, insufficientData: t.insufficientData, degradedToDeterministic: t.degradedToDeterministic },
+  noise: { duplicateObservations: t.duplicateObservations, staleObservations: t.staleObservations, probeFailures: t.probeFailures, conflicts: t.conflicts, unchangedProposals: t.unchangedProposals },
+  escalation: { count: t.escalations.length, rate: pct(t.escalations.length, t.runs), reasons: t.escalations.slice(-5).map(e => e.reasons) },
+  warnings,
+  counterfactuals: cf,
+  calibration: { status: cal.status, file: calFile, proposals: cal.proposals?.length ?? 0 },
+};
+
+if (has('json')) { console.log(JSON.stringify(report, null, 2)); process.exit(0); }
+
+console.log(`=== Model maintenance calibration (${days}d window, ${t.runs} runs) ===`);
+console.log(`Activity : ${t.runs} runs, ${report.activity.quietRatio} quiet, ${t.meaningfulRuns} meaningful, ${t.notifications} notifications (${report.activity.dedupeRate} deduped)`);
+console.log(`Cost     : $${report.cost.totalUsd} total (api $${report.cost.apiUsd}, local $${report.cost.localElectricityUsd}), avg $${report.cost.avgPerRun}/run, premium x${t.premiumInvocations}, budgetLimited x${t.budgetLimited}`);
+console.log(`Routing  : invocations mon=${t.invocations.monitor} eval=${t.invocations.evaluate} rec=${t.invocations.reconfigure}; fallbacks ${t.fallbacks} (local ${t.localFallbacks})`);
+if (report.routing.topSelected.length) console.log(`           top models: ${report.routing.topSelected.map(([m, c]) => `${m}x${c}`).join(', ')}`);
+console.log(`Quality  : avg margin ${report.quality.avgQualityMargin ?? 'n/a'}, borderline ${t.borderline.length}, insufficient-data ${t.insufficientData}, degraded ${t.degradedToDeterministic}`);
+console.log(`Noise    : dup ${t.duplicateObservations}, stale ${t.staleObservations}, probe-fail ${t.probeFailures}, conflicts ${t.conflicts}`);
+console.log(`Escalation: ${t.escalations.length} (${report.escalation.rate} of runs)`);
+console.log(`Warnings : ${warnings.length ? warnings.map(w => `${w.kind}(${w.evidence})`).join('; ') : 'none'}`);
+console.log(`Calibration: ${cal.status}${cal.status === 'ok' ? ` -> ${cal.proposals.length} proposal(s) at ${calFile}` : ` (${cal.runs}/${cal.required.minRuns} runs, ${cal.meaningfulRuns}/${cal.required.minMeaningfulEvents} meaningful)`}`);
+if (cf.length) {
+  console.log('Counterfactual (latest):');
+  for (const c of cf.slice(-3)) console.log(`  ${c.tier}: ${c.actual.model} $${c.actual.estimatedCostUsd} q${c.actual.quality} | vs ${c.counterfactual.map(a => `${a.model} $${a.estimatedCostUsd} q${a.quality} [${a.verdict}]`).join(', ')}`);
+}

package/scripts/resolve-capabilities.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+// Resolve agents -> capabilities -> concrete pi models using models.json + models.local.json,
+// and render the pi-subagents settings proposal to adapters/pi/out/. Read-only w.r.t. ~/.pi.
+// Usage: node scripts/resolve-capabilities.mjs [--adapter pi] [--capability name] [--live-settings <path>]
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+import { loadRouting } from '../lib/routing.mjs';
+import { loadRegistry } from '../lib/registry.mjs';
+import { loadAgents } from '../lib/agents.mjs';
+import { resolveAgents, resolveCapability } from '../lib/resolve.mjs';
+
+const kit = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const args = process.argv.slice(2);
+const opt = (name, def) => { const i = args.indexOf(`--${name}`); return i >= 0 ? args[i + 1] : def; };
+const adapter = opt('adapter', 'pi');
+const adapterDir = join(kit, 'adapters', adapter);
+const routing = loadRouting(join(kit, 'routing/routing.json'));
+const { registry, sources } = loadRegistry(join(adapterDir, 'models.json'), join(adapterDir, 'models.local.json'), routing);
+const { agents, errors } = loadAgents(join(kit, 'agents'), routing);
+if (errors.length) { console.error(errors.join('\n')); process.exit(1); }
+
+const only = opt('capability', null);
+const out = { registrySources: sources, agents: only ? undefined : resolveAgents(agents, routing, registry), capability: only ? resolveCapability(routing, registry, only) : undefined };
+
+if (adapter === 'pi' && !only) {
+  const { buildSettingsProposal } = await import('../adapters/pi/lib/settings-proposal.mjs');
+  const agentDir = process.env.PI_CODING_AGENT_DIR || join(homedir(), '.pi', 'agent');
+  const livePath = opt('live-settings', join(agentDir, 'settings.json'));
+  const live = existsSync(livePath) ? JSON.parse(readFileSync(livePath, 'utf8')) : null;
+  const proposal = buildSettingsProposal(out.agents, { liveSettings: live });
+  const outDir = join(adapterDir, 'out');
+  mkdirSync(outDir, { recursive: true });
+  writeFileSync(join(outDir, 'settings.proposal.json'), JSON.stringify(proposal.proposal, null, 2) + '\n');
+  writeFileSync(join(outDir, 'capabilities.resolved.json'), JSON.stringify(out, null, 2) + '\n');
+  out.settingsProposal = { file: join(outDir, 'settings.proposal.json'), diffAgainst: live ? livePath : null, diff: proposal.diff, notes: proposal.notes, target: proposal.target };
+}
+console.log(JSON.stringify(out, null, 2));