kodelyth-ecc 2.24.11 → 2.29.0

package/scripts/memory/instinct-inject.js

@@ -0,0 +1,67 @@
+// scripts/memory/instinct-inject.js
+//
+// Consume the structured instinct store (scripts/memory/instincts.js) at session
+// start. That store is written by the correction-capture hook, but until now
+// nothing ever READ it — all of its confidence / decay / outcome machinery ran
+// and never influenced a single session. This module closes that loop: it picks
+// the high-confidence, non-stale instincts relevant to the current project and
+// formats them for injection into SessionStart context.
+//
+// Kept separate from session-start.js (which executes main() at import time) so
+// the selection logic can be unit-tested without running the whole hook.
+'use strict';
+
+const DEFAULT_MAX = 6;
+const DEFAULT_THRESHOLD = 0.7;
+
+// Pure selection + formatting. Given raw instinct records, keep the ones that
+// are non-stale, confident enough, and in scope for `projectPath`; rank by
+// confidence; cap at `max`; render as injectable markdown. No I/O — this is the
+// unit the tests exercise.
+function formatStructuredInstincts(instincts, { projectPath, max = DEFAULT_MAX, threshold = DEFAULT_THRESHOLD } = {}) {
+  const candidates = (Array.isArray(instincts) ? instincts : [])
+    .filter(i => i && typeof i.rule === 'string' && i.rule.trim())
+    .filter(i => !i.stale && (i.confidence || 0) >= threshold)
+    // Global instincts always apply; project-scoped ones only in their project.
+    // A record with no project_path is treated as unscoped (applies anywhere).
+    .filter(i => i.scope === 'global' || !i.project_path || i.project_path === projectPath);
+
+  if (candidates.length === 0) return '';
+
+  const ranked = candidates
+    .slice()
+    .sort((a, b) => (b.confidence || 0) - (a.confidence || 0))
+    .slice(0, max);
+
+  const lines = ranked.map(i => {
+    const scope = i.scope === 'project' ? 'project' : 'global';
+    const confidence = `${Math.round((i.confidence || 0) * 100)}%`;
+    return `- [${scope} ${confidence}] ${i.rule.trim()}`;
+  });
+
+  return `Learned instincts (from past corrections):\n${lines.join('\n')}`;
+}
+
+// Read the store and format. Never throws: the structured store must not be able
+// to break session start, so any failure degrades to injecting nothing.
+function summarizeStructuredInstincts(projectPath, { log = () => {} } = {}) {
+  try {
+    const store = require('./instincts');
+    const summary = formatStructuredInstincts(store.list(), { projectPath });
+    if (summary) {
+      const count = summary.split('\n').length - 1;
+      log(`[SessionStart] Injecting ${count} learned instinct(s) from the structured store`);
+    }
+    return summary;
+  } catch (err) {
+    log(`[SessionStart] Structured instinct injection skipped: ${err && err.message}`);
+    return '';
+  }
+}
+
+module.exports = {
+  formatStructuredInstincts,
+  summarizeStructuredInstincts,
+  DEFAULT_MAX,
+  DEFAULT_THRESHOLD,
+};

package/scripts/memory/pending.js

@@ -0,0 +1,125 @@
+// scripts/memory/pending.js
+//
+// The consent-respecting half of auto-capture. The Stop hook
+// (hooks/memory/capture-stop.js) already AUTO-EXTRACTS memory candidates from a
+// finished session and queues them to pending-review.jsonl — it never stores
+// them. But nothing ever read that queue or promoted it, so the candidates piled
+// up with no way to confirm them (the `/memory review-pending` the hook points at
+// did not exist). This module closes the loop while honouring the memory
+// protocol's rule: "never capture without explicit confirmation."
+//
+//   listPending()      — review what the session proposed
+//   promotePending(id) — the confirmation gate: store it (capture() redacts)
+//   discardPending(id) — throw it away
+//
+// Candidates are auto-collected; storing them is one explicit command. Nothing
+// enters the recall store silently.
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const safeFs = require('../lib/safe-fs.js');
+const store = require('./store.js');
+
+function pendingFile() {
+  return path.join(store.PATHS.dir, 'pending-review.jsonl');
+}
+
+// Stable id from content, so the same proposal queued across several sessions
+// folds to one entry and the user can reference it to confirm/discard.
+function candidateId(c) {
+  return crypto.createHash('sha256')
+    .update(`${(c && c.problem) || ''}::${(c && c.approach) || ''}`)
+    .digest('hex')
+    .slice(0, 8);
+}
+
+function readQueue() {
+  const f = pendingFile();
+  if (!fs.existsSync(f)) return [];
+  const out = [];
+  for (const line of fs.readFileSync(f, 'utf8').split('\n')) {
+    if (!line) continue;
+    let row; try { row = JSON.parse(line); } catch { continue; }
+    if (!row || !row.problem || !row.approach) continue;
+    out.push(row);
+  }
+  return out;
+}
+
+function writeQueue(rows) {
+  const f = pendingFile();
+  if (rows.length === 0) {
+    try { fs.unlinkSync(f); } catch { /* already gone */ }
+    return;
+  }
+  safeFs.replaceFilePreservingMode(f, rows.map(r => JSON.stringify(r)).join('\n') + '\n');
+}
+
+// Deduped view of the queue, newest first, each with its stable id.
+function listPending() {
+  const byId = new Map();
+  for (const c of readQueue()) {
+    const id = candidateId(c);
+    const prior = byId.get(id);
+    if (!prior || (c.queued_at || '') > (prior.queued_at || '')) {
+      byId.set(id, { ...c, id });
+    }
+  }
+  return [...byId.values()].sort((a, b) => (b.queued_at || '').localeCompare(a.queued_at || ''));
+}
+
+function countPending() {
+  return listPending().length;
+}
+
+function selectIds(selector) {
+  if (selector === 'all' || selector == null) return new Set(listPending().map(c => c.id));
+  const arr = Array.isArray(selector) ? selector : [selector];
+  return new Set(arr.map(String));
+}
+
+// The confirmation gate. Promotes the selected candidates into the recall store
+// via capture() — which redacts secrets — then removes them from the queue.
+// Returns the stored memories.
+function promotePending(selector = 'all') {
+  const ids = selectIds(selector);
+  const promotedContentIds = new Set();
+  const stored = [];
+  for (const c of listPending()) {
+    if (!ids.has(c.id)) continue;
+    stored.push(store.capture({
+      problem:  c.problem,
+      approach: c.approach,
+      tags:     c.tags || [],
+      project:  c.project_path || null,
+      language: c.language || null,
+      files:    c.files || [],
+      source:   'auto-confirmed',
+    }));
+    promotedContentIds.add(c.id); // c.id === candidateId(c)
+  }
+  const remaining = readQueue().filter(c => !promotedContentIds.has(candidateId(c)));
+  writeQueue(remaining);
+  return stored;
+}
+
+// Remove candidates from the queue without storing them. Returns the count removed.
+function discardPending(selector = 'all') {
+  const ids = selectIds(selector);
+  const discardContentIds = new Set(listPending().filter(c => ids.has(c.id)).map(c => c.id));
+  const before = readQueue();
+  const remaining = before.filter(c => !discardContentIds.has(candidateId(c)));
+  writeQueue(remaining);
+  return before.length - remaining.length;
+}
+
+module.exports = {
+  pendingFile,
+  candidateId,
+  listPending,
+  countPending,
+  promotePending,
+  discardPending,
+};

package/scripts/memory/project-id.js

@@ -0,0 +1,93 @@
+// scripts/memory/project-id.js
+//
+// One project-identity resolver for the memory subsystem. Memory used to key a
+// project by sha256(absolute path), while the observer keyed it by git remote —
+// so the moment you cloned, moved, or renamed a repo, its absolute path changed
+// and all of its memories orphaned (they were filed under the old path hash).
+//
+// This resolver is git-remote-first with a path fallback, and NORMALIZES the
+// remote so the same repo always hashes the same way regardless of protocol,
+// host form, .git suffix, embedded credentials, or trailing slash:
+//
+//   git@github.com:owner/repo.git     ─┐
+//   https://github.com/owner/repo/     ├─→  remote:github.com/owner/repo  → one id
+//   ssh://git@github.com/owner/repo    ─┘
+//
+// Backward compatibility is handled by read-both: new memories are written under
+// the git-remote id, but recall also matches the LEGACY path id, so memories
+// captured before this change are never lost. Zero deps, local only.
+'use strict';
+
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+
+function sha12(s) {
+  return crypto.createHash('sha256').update(String(s)).digest('hex').slice(0, 12);
+}
+
+function runGit(args, cwd) {
+  try {
+    const r = spawnSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    if (r.status !== 0) return '';
+    return (r.stdout || '').trim();
+  } catch {
+    return '';
+  }
+}
+
+// Strip `://user:pass@` so a credential-bearing remote and a clean one map to the
+// same project (and so a secret never ends up in a hash input we might log).
+function stripRemoteCredentials(url) {
+  if (!url) return '';
+  return String(url).replace(/:\/\/[^@]+@/, '://');
+}
+
+// Canonical form of a git remote URL — see the header for the shapes this folds
+// together. Returns '' for empty input.
+function normalizeRemote(url) {
+  let u = stripRemoteCredentials(url).trim();
+  if (!u) return '';
+  u = u.replace(/^[a-z][a-z0-9+.-]*:\/\//i, '');   // strip scheme://
+  u = u.replace(/^git@/i, '');                      // strip scp-style user
+  u = u.replace(/^([^/:]+):(?!\d)/, '$1/');         // host:owner/repo → host/owner/repo (scp form, not host:port)
+  u = u.replace(/\.git$/i, '');                     // drop a trailing .git
+  u = u.replace(/\/+$/, '');                        // drop trailing slashes
+  return u.toLowerCase();
+}
+
+// The legacy, path-only id the memory store used before this change. Kept so
+// memories captured under the old scheme are still found (read-both).
+function legacyPathId(projectRoot) {
+  return sha12(projectRoot);
+}
+
+// The canonical id for a project: git-remote-first (stable across clone/move),
+// path fallback (local-only repos, non-git directories).
+function resolveProjectId(projectRoot, { cwd } = {}) {
+  if (!projectRoot) return 'global';
+  const dir = cwd || projectRoot;
+  const remote = normalizeRemote(runGit(['remote', 'get-url', 'origin'], dir));
+  if (remote) return sha12('remote:' + remote);
+  return legacyPathId(projectRoot);
+}
+
+// Every id that should match this project when recalling: the canonical id AND
+// the legacy path id, de-duped. New memories are written under the first; old
+// ones are still found via the second. (When the repo has no remote the two are
+// identical and this collapses to one.)
+function matchingProjectIds(projectRoot, opts = {}) {
+  if (!projectRoot) return [];
+  const ids = new Set();
+  ids.add(resolveProjectId(projectRoot, opts));
+  ids.add(legacyPathId(projectRoot));
+  return [...ids];
+}
+
+module.exports = {
+  sha12,
+  stripRemoteCredentials,
+  normalizeRemote,
+  legacyPathId,
+  resolveProjectId,
+  matchingProjectIds,
+};

package/scripts/memory/store.js

@@ -19,6 +19,8 @@ const os   = require('os');
 const path = require('path');
 const crypto = require('crypto');
 const safeFs = require('../lib/safe-fs.js');
+const pid = require('./project-id.js');
+const { redact } = require('../lib/redact.js');
 
 // Auto-migrate legacy ~/.kodelyth/ → ~/.kodelythecc/ before we touch any path.
 try { require('../migrate-legacy').main(); } catch { /* best-effort */ }
@@ -27,11 +29,14 @@ const MEMORY_DIR = process.env.KODELYTH_MEMORY_DIR
   || path.join(os.homedir(), '.kodelythecc', 'memory');
 
 const PATHS = {
-  dir:       MEMORY_DIR,
-  log:       path.join(MEMORY_DIR, 'memories.jsonl'),
-  index:     path.join(MEMORY_DIR, 'index.json'),
-  patterns:  path.join(MEMORY_DIR, 'patterns.json'),
-  projects:  path.join(MEMORY_DIR, 'projects'),
+  dir:        MEMORY_DIR,
+  log:        path.join(MEMORY_DIR, 'memories.jsonl'),
+  index:      path.join(MEMORY_DIR, 'index.json'),
+  patterns:   path.join(MEMORY_DIR, 'patterns.json'),
+  projects:   path.join(MEMORY_DIR, 'projects'),
+  // Opt-in semantic layer only. Written when embeddings are enabled; absent and
+  // untouched on a default (BM25-only) install.
+  embeddings: path.join(MEMORY_DIR, 'embeddings.jsonl'),
 };
 
 // ── Stop words (English + common code noise) ─────────────────────────────────
@@ -208,6 +213,28 @@ function indexMemory(index, memory) {
  */
 const RELATIVE_SCORE_FLOOR = 0.25;
 
+// Rank fusion. BM25 decides RELEVANCE (and the floor below gates it); this only
+// reorders the survivors so that, among similarly-relevant memories, a recent and
+// proven one outranks an old or failed one. Pure function of one memory — the
+// BM25 `score`, the `captured_at` timestamp, and the `resolved` outcome — so it
+// is unit-tested directly.
+function fuseScore(m) {
+  const base = m.score || 0;
+  // Recency: up to +25% for a just-captured memory, decaying over ~90 days.
+  let recency = 1;
+  const t = Date.parse(m.captured_at || '');
+  if (!Number.isNaN(t)) {
+    const ageDays = Math.max(0, (Date.now() - t) / 86400000);
+    recency = 1 + 0.25 * Math.exp(-ageDays / 90);
+  }
+  // Outcome: an approach confirmed to work (resolved:true) is worth more; one
+  // that didn't stick (resolved:false) is worth less. Unknown stays neutral.
+  let outcome = 1;
+  if (m.resolved === true) outcome = 1.3;
+  else if (m.resolved === false) outcome = 0.6;
+  return base * recency * outcome;
+}
+
 function search(query, options = {}) {
   // minScore stays honoured when passed, so existing callers keep their exact
   // behaviour; only the default changes from an absolute floor to a relative one.
@@ -253,9 +280,15 @@ function search(query, options = {}) {
     .filter(Boolean);
 
   if (projectFilter) {
-    results = results.filter(m => m.project === projectFilter);
+    // projectFilter may be a single id or a list of ids (read-both: the current
+    // git-remote id plus the legacy path id). Match on membership either way.
+    const allowed = Array.isArray(projectFilter) ? new Set(projectFilter) : new Set([projectFilter]);
+    results = results.filter(m => allowed.has(m.project));
   }
 
+  // Re-rank the relevant survivors by the fused score (relevance × recency ×
+  // outcome), then trim. `score` (raw BM25) stays on each result for callers.
+  results.sort((a, b) => fuseScore(b) - fuseScore(a));
   return results.slice(0, limit);
 }
 
@@ -354,17 +387,23 @@ function capture({
   const memory = {
     id:          newMemoryId(),
     captured_at: new Date().toISOString(),
-    problem:     String(problem).slice(0, 500),
-    approach:    String(approach).slice(0, 2000),
+    // Redact credentials BEFORE storing. A memory is written to memories.jsonl,
+    // surfaced by recall, and injected into future sessions — so a leaked key in
+    // a captured problem/approach would otherwise persist and re-surface.
+    problem:     redact(String(problem)).slice(0, 500),
+    approach:    redact(String(approach)).slice(0, 2000),
     // The COUNT was capped but not the length of each tag, so a single
     // multi-megabyte tag was stored whole — bloating the log, the index, and
     // the memory block injected at session start. Bound both.
-    tags:        Array.from(new Set(tags.map(t => String(t).slice(0, 60)))).slice(0, 20),
-    project:     project ? projectHash(project) : null,
+    tags:        Array.from(new Set(tags.map(t => redact(String(t)).slice(0, 60)))).slice(0, 20),
+    // Git-remote-first id: the same repo keeps its memories across clone / move /
+    // rename, where the old sha256(path) scheme orphaned them. Legacy memories
+    // (path id) are still found via read-both in recallForProject().
+    project:     project ? pid.resolveProjectId(project) : null,
     project_path: project,
     language,
-    files:       files.slice(0, 20).map(f => String(f).slice(0, 500)),
-    gotchas:     gotchas.slice(0, 10).map(g => String(g).slice(0, 500)),
+    files:       files.slice(0, 20).map(f => redact(String(f)).slice(0, 500)),
+    gotchas:     gotchas.slice(0, 10).map(g => redact(String(g)).slice(0, 500)),
     source,
   };
   // Load the index BEFORE writing the row. If index.json is missing or invalid,
@@ -383,7 +422,9 @@ function recall(query, options = {}) {
 }
 
 function recallForProject(projectRoot, query, options = {}) {
-  const opts = { ...options, projectFilter: projectHash(projectRoot) };
+  // Read-both: match the current git-remote id AND the legacy path id, so
+  // memories captured under either scheme are found.
+  const opts = { ...options, projectFilter: pid.matchingProjectIds(projectRoot) };
   const results = search(query, opts);
   if (results.length >= (options.limit || 5)) return results;
   // Fall back to global memories if project-specific are sparse
@@ -525,6 +566,69 @@ function stats() {
   };
 }
 
+// ── Optional semantic layer (opt-in; a default install never touches this) ───
+// Embeddings live in a sidecar keyed by memory id, so memories.jsonl and its
+// BM25 index are byte-for-byte identical whether or not embeddings are enabled.
+
+function saveEmbedding(id, vec) {
+  if (!id || !Array.isArray(vec) || vec.length === 0) return false;
+  ensureDir(PATHS.dir);
+  fs.appendFileSync(PATHS.embeddings, JSON.stringify({ id, vec }) + '\n');
+  return true;
+}
+
+function loadEmbeddings(ids = null) {
+  if (!fs.existsSync(PATHS.embeddings)) return {};
+  const want = ids ? new Set(ids) : null;
+  const out = {};
+  for (const line of fs.readFileSync(PATHS.embeddings, 'utf8').split('\n')) {
+    if (!line) continue;
+    let row; try { row = JSON.parse(line); } catch { continue; }
+    if (!row || !row.id || !Array.isArray(row.vec)) continue;
+    if (want && !want.has(row.id)) continue;
+    out[row.id] = row.vec; // append-only; last write wins
+  }
+  return out;
+}
+
+// Capture a memory and, when embeddings are enabled AND a provider is available,
+// also store its embedding. Otherwise behaves exactly like the sync capture().
+async function captureWithEmbedding(args) {
+  const memory = capture(args);
+  try {
+    const provider = await require('./embeddings').getProvider();
+    if (provider) {
+      const vec = await provider.embed(`${memory.problem} ${memory.approach}`);
+      if (vec) saveEmbedding(memory.id, vec);
+    }
+  } catch { /* embeddings are best-effort — never fail a capture over them */ }
+  return memory;
+}
+
+// Hybrid recall: BM25 selects the relevant set (sync, as always), then — only
+// when embeddings are enabled and available — re-ranks that set by blending in
+// semantic similarity. With embeddings off/unavailable this returns exactly what
+// recall() returns.
+async function recallHybrid(query, options = {}) {
+  const limit = options.limit || 5;
+  // Pull a wider candidate pool so semantic similarity can promote a strong
+  // match that BM25 alone ranked just below the cut.
+  const base = search(query, { ...options, limit: limit * 4 });
+  if (base.length === 0) return base;
+  try {
+    const emb = require('./embeddings');
+    const provider = await emb.getProvider();
+    if (!provider) return base.slice(0, limit);
+    const queryVec = await provider.embed(query);
+    if (!queryVec) return base.slice(0, limit);
+    const vecById = loadEmbeddings(base.map(m => m.id));
+    const fused = emb.fuseHybrid(base, { queryVec, vecById, weight: options.semanticWeight });
+    return fused.map(({ _bm25norm, _semantic, _hybrid, ...m }) => m).slice(0, limit);
+  } catch {
+    return base.slice(0, limit); // any failure in the opt-in path degrades to BM25
+  }
+}
+
 module.exports = {
   PATHS,
   capture,
@@ -536,6 +640,12 @@ module.exports = {
   stats,
   tokenise,
   projectHash,
+  fuseScore,
+  // Opt-in semantic layer
+  saveEmbedding,
+  loadEmbeddings,
+  captureWithEmbedding,
+  recallHybrid,
   // Improvement C
   resolveMemory,
   findMemoriesForFile,

package/scripts/rtk/index.js

@@ -64,11 +64,51 @@ function detectInstalledTargets() {
   return targets;
 }
 
+// Guard against the `rtk` name collision. reachingforthejack/rtk (Rust Type Kit)
+// also ships a binary called `rtk`; wiring or measuring it as if it were Rust
+// Token Killer would be wrong and silent — ECC would patch hooks and read a
+// `gain` ledger that does not exist. Rust Token Killer is the only `rtk` with a
+// `gain` subcommand (the token-savings ledger ECC reads), so probing it
+// distinguishes the two with no side effects and without depending on exact
+// `--version` text. `rtk gain` is the documented signature command in RTK.md.
+//
+// The decision is a pure function of two probe results so it can be unit-tested
+// without spawning a binary:
+//   gainHelpOk — did `rtk gain --help` exit 0?
+//   helpText   — stdout of `rtk --help` (or '' if it failed)
+function looksLikeRealRtk({ gainHelpOk, helpText } = {}) {
+  if (gainHelpOk) return true;
+  const h = String(helpText || '');
+  // The token killer's help lists the `gain` command and calls itself an
+  // LLM-output proxy; Rust Type Kit's help does neither.
+  return /\bgain\b/.test(h) && /(LLM|token|proxy)/i.test(h);
+}
+
+function isRealRtk() {
+  let gainHelpOk = false;
+  try {
+    execFileSync('rtk', ['gain', '--help'], { stdio: 'ignore' });
+    gainHelpOk = true;
+  } catch { /* `gain` subcommand absent, or `rtk` not runnable */ }
+
+  let helpText = '';
+  if (!gainHelpOk) {
+    try {
+      helpText = execFileSync('rtk', ['--help'], {
+        encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+      });
+    } catch { /* no help available */ }
+  }
+  return looksLikeRealRtk({ gainHelpOk, helpText });
+}
+
 function isInstalled() {
   try {
     execFileSync('rtk', ['--version'], { stdio: 'ignore' });
-    return true;
   } catch { return false; }
+  // A binary named `rtk` exists — confirm it is Rust Token Killer, not the Rust
+  // Type Kit collision, before any caller wires or measures it.
+  return isRealRtk();
 }
 
 function getVersion() {
@@ -214,6 +254,8 @@ module.exports = {
   normalizeTarget,
   detectInstalledTargets,
   isInstalled,
+  isRealRtk,
+  looksLikeRealRtk,
   getVersion,
   install,
   enableFor,

package/scripts/super-agent/cli.js

@@ -0,0 +1,135 @@
+// scripts/super-agent/cli.js
+//
+// The driver surface for the super-agent orchestrator. Like the Arena CLI, this
+// does NOT run agents itself — it advances a tokenless state machine and tells
+// the driving LLM what to do next. The loop is:
+//
+//   super-agent start --goal "..."        → create a run, print the next action
+//   super-agent next <id>                 → print the next action (JSON)
+//   super-agent plan <id> --file p.json   → install the decomposed step DAG
+//   super-agent step <id> <step> --status done|failed [--branch b] [--tokens n]
+//   super-agent integrate <id> [--conflicts a,b] [--tokens n]
+//   super-agent verify <id> --passed|--failed [--detail "..."]
+//   super-agent status <id> | list
+//
+// The LLM performs each action with the existing primitives (blueprint to
+// decompose, the swarm to dispatch, the GAN loop to evaluate, git to integrate)
+// and reports back through the submit commands.
+'use strict';
+
+const fs = require('fs');
+const state = require('./state.js');
+const orch = require('./orchestrator.js');
+
+function parse(argv) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) { flags[key] = next; i++; }
+      else flags[key] = true;
+    } else positional.push(a);
+  }
+  return { positional, flags };
+}
+
+const out = (o) => process.stdout.write(JSON.stringify(o, null, 2) + '\n');
+const err = (m) => { process.stderr.write(`super-agent: ${m}\n`); process.exit(2); };
+
+function loadOr(id) {
+  if (!id) err('a run id is required');
+  if (!state.exists(id)) err(`no run ${id}`);
+  return state.load(id);
+}
+
+function main(argv) {
+  const { positional, flags } = parse(argv);
+  const cmd = positional[0];
+
+  switch (cmd) {
+    case 'start': {
+      const goal = flags.goal || positional.slice(1).join(' ');
+      if (!goal) err('usage: super-agent start --goal "<objective>" [--token-cap N] [--step-cap N] [--scope .]');
+      const run = state.createRun({
+        goal,
+        scope: flags.scope || '.',
+        limits: { tokenCap: Number(flags['token-cap']) || 0, stepCap: Number(flags['step-cap']) || 0 },
+      });
+      state.save(run);
+      out({ runId: run.id, next: orch.nextAction(run) });
+      return;
+    }
+    case 'next': {
+      out(orch.nextAction(loadOr(positional[1])));
+      return;
+    }
+    case 'plan': {
+      const run = loadOr(positional[1]);
+      if (!flags.file) err('usage: super-agent plan <id> --file <plan.json>  (JSON array of { id, description, deps, exitCriteria })');
+      let steps;
+      try { steps = JSON.parse(fs.readFileSync(flags.file, 'utf8')); }
+      catch (e) { err(`cannot read plan: ${e.message}`); }
+      orch.submitPlan(run, steps);
+      out({ ok: true, next: orch.nextAction(run) });
+      return;
+    }
+    case 'dispatch': {
+      // Mark the given steps in-progress (optional bookkeeping before running them).
+      const run = loadOr(positional[1]);
+      const ids = (flags.steps ? String(flags.steps).split(',') : positional.slice(2)).filter(Boolean);
+      orch.markDispatched(run, ids);
+      out({ ok: true, inProgress: ids });
+      return;
+    }
+    case 'step': {
+      const run = loadOr(positional[1]);
+      const stepId = positional[2];
+      if (!stepId) err('usage: super-agent step <id> <stepId> --status done|failed [--branch b] [--tokens n]');
+      orch.submitStepResult(run, stepId, {
+        status: flags.status === 'failed' ? 'failed' : 'done',
+        branch: flags.branch || null,
+        result: flags.result || null,
+        tokensSpent: Number(flags.tokens) || 0,
+      });
+      out({ ok: true, next: orch.nextAction(run) });
+      return;
+    }
+    case 'integrate': {
+      const run = loadOr(positional[1]);
+      const conflicts = flags.conflicts ? String(flags.conflicts).split(',').filter(Boolean) : [];
+      orch.submitIntegration(run, {
+        merged: conflicts.length === 0 && flags.merged !== false,
+        conflicts,
+        tokensSpent: Number(flags.tokens) || 0,
+      });
+      out({ ok: true, next: orch.nextAction(run) });
+      return;
+    }
+    case 'verify': {
+      const run = loadOr(positional[1]);
+      if (!flags.passed && !flags.failed) err('usage: super-agent verify <id> --passed | --failed [--detail "..."]');
+      orch.submitVerification(run, {
+        passed: !!flags.passed && !flags.failed,
+        detail: typeof flags.detail === 'string' ? flags.detail : '',
+        tokensSpent: Number(flags.tokens) || 0,
+      });
+      out({ ok: true, next: orch.nextAction(run) });
+      return;
+    }
+    case 'status': {
+      out(state.summarize(loadOr(positional[1])));
+      return;
+    }
+    case 'list': {
+      out(state.list().map(state.summarize));
+      return;
+    }
+    default:
+      err('commands: start | next | plan | dispatch | step | integrate | verify | status | list');
+  }
+}
+
+module.exports = { main, parse };