@josfox/jos 4.1.0 → 5.0.0

package/src/commands/run.js

@@ -1,244 +1,194 @@
-/**
- * JOS RUN Command - Execute .jos artifacts
- * Complies with JOSFOXAI MAGIC contract
- * Integrity Strategy: Detached Manifest (.sig.json)
- * Format version v0.0.7 — Specification maturity v0.1.0 (Alpha)
- */
-
-const fs = require('fs');
-const path = require('path');
-const { execSync, spawn } = require('child_process');
-const crypto = require('crypto');
-
-// AURORA colors
-const C = {
-    reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
-    purple: '\x1b[38;5;135m', cyan: '\x1b[38;5;51m',
-    green: '\x1b[38;5;78m', red: '\x1b[38;5;196m',
-    yellow: '\x1b[38;5;220m', white: '\x1b[38;5;255m',
-    gray: '\x1b[38;5;245m', blue: '\x1b[38;5;39m'
-};
-
-// Witness Logging
-function logWitness(home, eventType, data) {
-    const runId = global.JOS_RUN_ID || new Date().toISOString().replace(/[:.]/g, '-');
-    global.JOS_RUN_ID = runId;
-
-    const runDir = path.join(home, 'runs', runId);
-    if (!fs.existsSync(runDir)) fs.mkdirSync(runDir, { recursive: true });
-
-    const event = {
-        timestamp: new Date().toISOString(),
-        type: `run:${eventType}`,
-        ...data
-    };
-
-    fs.appendFileSync(path.join(runDir, 'events.jsonl'), JSON.stringify(event) + '\n');
-}
-
-// Compute SHA-256 integrity
-function computeIntegrity(content) {
-    return crypto.createHash('sha256').update(content).digest('hex');
-}
-
-// Verify Integrity using Detached Manifest
-function verifyIntegrity(artifactPath, content, artifact) {
-    const integrityRef = artifact.security?.integrity_ref;
-    if (!integrityRef) return { valid: true, warning: "open (no integrity_ref)" };
-
-    const manifestPath = path.resolve(path.dirname(artifactPath), integrityRef);
-    if (!fs.existsSync(manifestPath)) {
-        return { valid: false, error: `Manifest not found at ${manifestPath}` };
-    }
-
-    let manifest;
-    try {
-        manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-    } catch (e) {
-        return { valid: false, error: "Invalid manifest JSON" };
-    }
-
-    const actualHash = computeIntegrity(content);
-    if (actualHash !== manifest.artifact_sha256) {
-        return {
-            valid: false,
-            error: `Hash mismatch. Expected: ${manifest.artifact_sha256.substring(0, 16)}..., Got: ${actualHash.substring(0, 16)}...`
-        };
-    }
-
-    return { valid: true, verified: true, hash: actualHash };
-}
-
-exports.execute = async (args, home) => {
-    const target = args[0];
-    const dryRun = args.includes('--dry-run');
-    const insecure = args.includes('--insecure');
-
-    if (args.includes('--help') || !target) {
-        console.log(`
-${C.purple}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C.reset}
-${C.bold}JOS RUN${C.reset} // Execute .jos artifacts
-${C.purple}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C.reset}
-
-${C.bold}Usage:${C.reset}
-  jos run <file.jos> [options]
-
-${C.bold}Options:${C.reset}
-  --flow <name>    Flow to execute (default: main)
-  --dry-run        Simulate without executing
-  --insecure       Skip integrity verification
-
-${C.bold}Example:${C.reset}
-  jos run orchestration.jos --flow publish_all --dry-run
-`);
-        return;
-    }
-
-    let artifactPath = path.resolve(target);
-    if (!fs.existsSync(artifactPath)) {
-        if (fs.existsSync(path.join(home, 'artifacts', target))) {
-            artifactPath = path.join(home, 'artifacts', target);
-        } else {
-            console.log(`${C.red}✖ Artifact not found:${C.reset} ${target}`);
-            process.exit(1);
-        }
-    }
-
-    const content = fs.readFileSync(artifactPath, 'utf8');
-    const artifact = JSON.parse(content);
-
-    // Init Witness
-    logWitness(home, 'start', { artifact: artifactPath, dryRun: dryRun });
-
-    // Header
-    console.log(`\n${C.purple}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C.reset}`);
-    console.log(`${C.cyan}${C.bold}JOS RUN${C.reset} // ${C.gray}JOSFOXAI MAGIC Runtime${C.reset}`);
-    console.log(`${C.purple}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C.reset}\n`);
-
-    // Mode indicator
-    if (dryRun) {
-        console.log(`${C.yellow}${C.bold}⚡ DRY RUN MODE${C.reset} ${C.gray}— No commands will be executed${C.reset}\n`);
-    }
-
-    // Artifact info
-    console.log(`${C.cyan}📦 Artifact:${C.reset} ${artifact.meta?.name || path.basename(artifactPath)}`);
-    console.log(`${C.cyan}📄 File:${C.reset} ${path.basename(artifactPath)}`);
-    console.log(`${C.cyan}🆔 ID:${C.reset} ${artifact.id_jos || 'N/A'}`);
-
-    // Integrity verification
-    if (!insecure) {
-        const integrity = verifyIntegrity(artifactPath, content, artifact);
-        if (!integrity.valid) {
-            console.log(`${C.cyan}🔐 Integrity:${C.reset} ${C.red}FAILED - ${integrity.error}${C.reset}`);
-            logWitness(home, 'integrity_failed', { error: integrity.error });
-            process.exit(1);
-        } else if (integrity.verified) {
-            console.log(`${C.cyan}🔐 Integrity:${C.reset} ${C.green}✓ Verified${C.reset} ${C.gray}(${integrity.hash.substring(0, 16)}...)${C.reset}`);
-            logWitness(home, 'integrity_verified', { hash: integrity.hash });
-        } else {
-            console.log(`${C.cyan}🔐 Integrity:${C.reset} ${C.yellow}⚠ ${integrity.warning}${C.reset}`);
-        }
-    } else {
-        console.log(`${C.cyan}🔐 Integrity:${C.reset} ${C.yellow}⚠ Skipped (--insecure)${C.reset}`);
-    }
-
-    // MAGIC validation
-    const hasMagic = artifact.intention && artifact.guardrails && artifact.capabilities;
-    console.log(`${C.cyan}✨ MAGIC:${C.reset} ${hasMagic ? C.green + '✓ Valid' : C.yellow + '⚠ Partial'}${C.reset}`);
-
-    // Intention
-    if (artifact.intention?.objective) {
-        console.log(`${C.cyan}🎯 Intention:${C.reset} ${artifact.intention.objective}`);
-    }
-
-    // Guardrails
-    if (artifact.guardrails?.avoid?.length > 0) {
-        console.log(`${C.cyan}🛡️ Guardrails:${C.reset} ${artifact.guardrails.avoid.join(', ')}`);
-    }
-
-    // Flow selection
-    const flowName = args.includes('--flow') ? args[args.indexOf('--flow') + 1] : 'main';
-    const flow = artifact.orchestration?.flows?.[flowName] ||
-        artifact.orchestration?.pipelines?.[flowName];
-
-    if (!flow) {
-        console.log(`\n${C.red}✖ Flow '${flowName}' not found.${C.reset}`);
-        const available = [
-            ...Object.keys(artifact.orchestration?.flows || {}),
-            ...Object.keys(artifact.orchestration?.pipelines || {})
-        ];
-        if (available.length > 0) {
-            console.log(`${C.gray}Available flows: ${available.join(', ')}${C.reset}`);
-        }
-        process.exit(1);
-    }
-
-    // Execution plan
-    console.log(`\n${C.cyan}▶ Flow:${C.reset} ${C.bold}${flowName}${C.reset}`);
-    if (flow.description) {
-        console.log(`${C.gray}  ${flow.description}${C.reset}`);
-    }
-    console.log(`${C.gray}  Steps: ${flow.steps?.join(' → ') || 'none'}${C.reset}\n`);
-
-    // Execute steps
-    let stepIndex = 0;
-    for (const stepName of flow.steps || []) {
-        stepIndex++;
-        const def = artifact.orchestration.definitions?.[stepName];
-
-        if (!def) {
-            console.log(`${C.red}  [${stepIndex}] ✖ ${stepName}: Definition not found${C.reset}`);
-            logWitness(home, 'step_error', { step: stepName, error: 'definition not found' });
-            continue;
-        }
-
-        logWitness(home, 'step_start', { step: stepName, type: def.type, index: stepIndex });
-
-        const typeIcon = def.type === 'shell' ? '⚡' : def.type === 'jos' ? '📦' : '●';
-
-        if (dryRun) {
-            console.log(`${C.yellow}  [${stepIndex}] ${typeIcon} ${stepName}${C.reset}`);
-            if (def.description) console.log(`${C.gray}      ${def.description}${C.reset}`);
-            if (def.type === 'shell') {
-                const cmdPreview = def.command.length > 60 ? def.command.substring(0, 60) + '...' : def.command;
-                console.log(`${C.dim}      $ ${cmdPreview}${C.reset}`);
-            } else if (def.type === 'jos') {
-                console.log(`${C.dim}      → ${def.artifact}${C.reset}`);
-            }
-            logWitness(home, 'step_dry_run', { step: stepName });
-            continue;
-        }
-
-        // Real execution
-        console.log(`${C.blue}  [${stepIndex}] ${typeIcon} ${stepName}...${C.reset}`);
-
-        try {
-            if (def.type === 'shell') {
-                execSync(def.command, { stdio: 'inherit' });
-                console.log(`${C.green}      ✓ Complete${C.reset}`);
-            } else if (def.type === 'jos') {
-                console.log(`${C.purple}      Running sub-artifact: ${def.artifact}${C.reset}`);
-                const subPath = path.resolve(path.dirname(artifactPath), def.artifact);
-                const binJos = process.argv[1];
-                execSync(`${process.execPath} "${binJos}" run "${subPath}" ${insecure ? '--insecure' : ''} --flow main`, {
-                    stdio: 'inherit'
-                });
-            }
-            logWitness(home, 'step_complete', { step: stepName, success: true });
-        } catch (e) {
-            console.log(`${C.red}      ✖ Failed: ${e.message}${C.reset}`);
-            logWitness(home, 'step_failed', { step: stepName, error: e.message });
-            logWitness(home, 'run_failed', { lastStep: stepName });
-            process.exit(1);
-        }
-    }
-
-    // Success
-    console.log(`\n${C.green}${C.bold}✓ ${dryRun ? 'Dry run complete' : 'Execution complete'}${C.reset}`);
-    if (artifact.intention?.success_criteria) {
-        console.log(`${C.gray}  Success criteria: ${artifact.intention.success_criteria}${C.reset}`);
-    }
-    console.log('');
-
-    logWitness(home, 'success', { dryRun: dryRun, stepsExecuted: stepIndex });
-};
+/**
+ * JOS RUN - Execute a .jos document through the jos-core kernel
+ * Accepts 2.0.0, 1.1.0, 1.0.0 and 0.0.7 documents (jos-core normalizes them).
+ * Exit codes: SPEC-2.0 section 7.1; 64 for command-line usage errors.
+ */
+'use strict';
+const path = require('path');
+const kernel = require('../kernel');
+const ui = require('../ui');
+const { RULE } = ui;
+const { parse, problem } = require('../args');
+const intention = require('../intention');
+
+// The options of `jos run`; each one passed to jos-core as is (SPEC-2.0 §5: flows, `use`, gates, data flow).
+const OPTIONS = {
+    '--json': false, '--dry-run': false,
+    '--flow': true, '--library': true, '--approve': 'many', '--input': true, '--with': true,
+};
+const USAGE = 'usage: jos run <file.jos | folder> [--json] [--dry-run] [--flow <name>] [--library <dir>] [--approve <step>]... [--input <json>] [--with <json>]';
+
+const CODE_MEANING = {
+    0: 'done', 1: 'not done', 2: 'invalid document', 3: 'blocked', 4: 'budget exceeded',
+    5: 'unexecutable', 124: 'timeout', 137: 'output limit or kill',
+};
+
+const HELP = (C) => `
+${C.purple}${RULE}${C.reset}
+${C.bold}JOS RUN${C.reset} // Execute .jos documents with jos-core
+${C.purple}${RULE}${C.reset}
+
+${C.bold}Usage:${C.reset}
+  jos run <file.jos | folder> [options]
+  jos run [options] -- <file.jos | folder>     (-- ends the options)
+
+  A .jos document runs in its own folder, not in the current directory.
+  A folder D with a .jos/ directory (D or D/.jos) runs D/.jos/manifest.jos in D;
+  a sealed folder is verified by its directory hash (SPEC-2.0 9.3).
+  A 0.0.7 document sealed by security.integrity_ref is verified against its
+  manifest before anything starts, --dry-run too: a mismatch is code 3.
+
+${C.bold}Options:${C.reset}
+  --json             Print the result object (SPEC-2.0 7.4) as JSON
+  --dry-run          All checks, no launch; prints the plan
+  --flow <name>      Run this flow of orchestration.flows (default: main, or the only one)
+  --library <dir>    Also resolve \`use\` references in this folder (after the .jos/ chain)
+  --approve <step>   Approve the human gate of <step> (repeat for several; nested: outer/step,
+                     second occurrence: step#2); without it the flow stops there, code 1
+  --input <json>     The run's input: \`input\` and \`last\` in the flow, a step's stdin
+  --with <json>      Slot values for a template run directly (SPEC-2.0 5.7)
+
+${C.bold}Files written:${C.reset}
+  jos-core keeps a ledger of each run (not of --dry-run): <run>/ledger.jsonl in .jos/replays/
+  of the nearest .jos/ folder with a manifest.jos above the document (or ~/.jos, if it has
+  one and there is no other); otherwise in ~/.jos/runs/.
+
+  After a run: jos runs, jos ledger verify <run_id>, jos meter <run_id>.
+
+${C.bold}Output:${C.reset}
+  Before it runs: the document's intention (objective, "Done when" criteria, avoid,
+  limit). After: each receipt with the verdict of each criterion, as jos-core
+  evaluated it, and "Intention met" or "Intention NOT met (code N: ...)".
+
+${C.bold}Exit codes:${C.reset}
+  0 done, 1 not done, 2 invalid, 3 blocked, 4 budget, 5 unexecutable,
+  124 timeout, 137 output limit, 64 usage
+
+${C.bold}Examples:${C.reset}
+  jos run hello.jos --dry-run
+  jos run ./my-project --json
+  jos run release.jos --approve build
+  jos run greet.jos --with '{"name":"Ana"}'
+`;
+
+exports.execute = async (args) => {
+    const err = ui.printer(process.stderr);
+    const { C } = err;
+    const { opts, files, help, error } = parse(args, OPTIONS);
+    if (help) {
+        const out = ui.printer(process.stdout);
+        out.text(HELP(out.C));
+        return 0;
+    }
+    if (error) {
+        err.fail('jos run: ' + problem(error));
+        if (error.option === '--insecure') err.hint('(removed in 5.0.0: jos-core checks integrity itself)');
+        err.hint(USAGE);
+        return 64;
+    }
+    if (files.length !== 1) {
+        err.fail('jos run: takes exactly one file');
+        err.hint(USAGE);
+        return 64;
+    }
+    const json = opts['--json'] === true;
+    const dryRun = opts['--dry-run'] === true;
+    const runOpts = {};
+    if (opts['--flow'] !== undefined) runOpts.flow = opts['--flow'];
+    if (opts['--library'] !== undefined) runOpts.library = path.resolve(opts['--library']);
+    if (opts['--approve'] !== undefined) runOpts.approvals = opts['--approve'];
+    for (const [flag, key] of [['--input', 'input'], ['--with', 'with']]) {
+        if (opts[flag] === undefined) continue;
+        try { runOpts[key] = JSON.parse(opts[flag]); } catch (e) {
+            err.fail('jos run: ' + flag + ' takes JSON', '(' + e.message + ')');
+            err.hint("example: " + flag + " '{\"name\":\"Ana\"}'");
+            return 64;
+        }
+    }
+
+    let k;
+    let core;
+    try { k = kernel.locate(); core = kernel.need(k, ['loadFileBytes']); } catch (e) { return kernel.fail(e); }
+    // SPEC-2.0 §9.1: a folder D (or D/.jos) runs its D/.jos/manifest.jos, in D; older kernels without documentPath get the path as given
+    const given = path.resolve(files[0]);
+    const file = typeof core.documentPath === 'function' ? core.documentPath(given) : given;
+    const base = path.basename(file) === 'manifest.jos' && path.basename(path.dirname(file)) === '.jos' ? path.dirname(path.dirname(file)) : path.dirname(file);
+
+    // The file is read once: the kernel hashes the same octets it parses (a 0.0.7 document sealed by
+    // security.integrity_ref is verified against them, jos-core 2.0.0-rc.8), so they travel with the document.
+    let doc = null;
+    let source = null;
+    let loadErrors = null;
+    try { ({ doc, bytes: source } = core.loadFileBytes(file)); } catch (e) {
+        if (!(e instanceof core.JosError)) throw e;
+        loadErrors = e.errors;
+    }
+
+    // Text mode: the header and the intention of the document go out before it runs (a long step, a server, a gate
+    // waiting: the person sees what was asked first); the receipts and the verdict after.
+    if (!json) {
+        err.header(`${C.cyan}JOS RUN`, 'jos-core ' + k.version);
+        if (dryRun) err.warn(`${C.bold}DRY RUN MODE${C.reset}${C.yellow}: no commands will be executed`);
+        err.field('File', file === path.join(base, '.jos', 'manifest.jos') ? path.join(path.basename(base), '.jos', 'manifest.jos') : path.basename(file));
+        const v = doc === null ? null : core.validate(doc);
+        if (v !== null && v.valid) intention.intention(err, v.document);
+    }
+
+    let result;
+    if (loadErrors) {
+        result = { ok: false, code: 2, run_id: core.josid.mint('run'), artifact: null, input_version: null, capability: null, receipts: [], output: null, duration_ms: 0, errors: loadErrors };
+        if (dryRun) { result.dry_run = true; delete result.ok; delete result.receipts; delete result.output; result.plan = null; }
+    } else {
+        // dir: the document's directory, as the kernel's own CLI passes it; for D/.jos/manifest.jos it is D/.jos, which is how
+        // the kernel recognizes a directory run and verifies the directory hash (SPEC-2.0 §9.3)
+        // folder: a folder D (or D/.jos) names its manifest, which the kernel requires to be of kind directory before
+        // any step, with the code and text of `jos validate D` (SPEC-2.0 §9.1; readiness rc.7 pass 5 F-19)
+        const folder = file !== given ? { folder: true } : {};
+        result = await core.run(doc, Object.assign({ cwd: base, dir: path.dirname(file), source, env: process.env, dryRun }, folder, runOpts));
+    }
+
+    if (json) {
+        ui.json(process.stdout, result);
+        return result.code;
+    }
+
+    if (result.artifact || result.input_version || result.capability) err.line();
+    if (result.artifact) err.field('ID', result.artifact);
+    if (result.input_version) err.field('Input version', result.input_version);
+    if (result.capability) err.field('Capability', `${result.capability.cap} ${C.gray}(${result.capability.trust})${C.reset}`);
+    if (result.integrity_ref) err.field('Integrity', `${C.green}✓${C.reset} verified by ${result.integrity_ref.manifest} ${C.gray}(0.0.7 integrity_ref, sha256 ${result.integrity_ref.sha256.slice(0, 12)}…, ${result.integrity_ref.eol})${C.reset}`);
+
+    if (result.plan) {
+        const p = result.plan;
+        err.line();
+        err.line(`${C.cyan}▶ Plan:${C.reset} ${C.bold}${p.engine}${C.reset}`);
+        if (Array.isArray(p.run)) err.cmd(p.run.join(' '));
+        else if (p.run) err.cmd(p.run);
+        if (p.limits) err.hint('limits: ' + JSON.stringify(p.limits));
+    }
+
+    if (result.ledger) err.field('Ledger', result.ledger);
+    if (result.output) {
+        if (result.output.stdout || result.output.stderr) err.line();
+        ui.data(process.stdout, result.output.stdout);
+        ui.data(process.stderr, result.output.stderr);
+    }
+    if (!dryRun && result.receipts.length) intention.verdict(err, result);
+
+    const detail = result.errors ? result.errors.join('; ') : (result.reason || result.unexecutable || '');
+    const meaning = CODE_MEANING[result.code] || 'error';
+    err.line();
+    if (result.code === 0) {
+        err.ok(`${C.bold}${dryRun ? 'Dry run complete' : 'Intention met'}`, `(code 0, ${result.run_id})`);
+    } else {
+        err.fail(`${C.bold}${dryRun ? 'Dry run refused' : 'Intention NOT met'} (code ${result.code}: ${meaning})`, `(${result.run_id})`);
+        if (detail) err.hint(detail);
+        if (result.waiting) {
+            const approvals = (runOpts.approvals || []).concat(result.waiting.step).map((a) => ' --approve ' + ui.shellArg(a)).join('');
+            const target = ui.shellArg(files[0]);
+            err.hint('To approve it: jos run ' + (files[0].startsWith('-') ? approvals.slice(1) + ' -- ' + target : target + approvals));
+        }
+    }
+    err.line();
+    return result.code;
+};

package/src/commands/runs.js

@@ -0,0 +1,102 @@
+/**
+ * JOS RUNS - lists the runs whose ledgers jos-core kept in ~/.jos/runs/ (runs of documents outside any .jos/ folder):
+ * id, document, exit code, start time and metered cost, newest first. Each ledger is verified by jos-core; one that
+ * does not verify is listed with the reason and nothing else. Read-only: it never creates ~/.jos.
+ * Exit codes: 0, 5 no kernel, 64 usage.
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const kernel = require('../kernel');
+const ledgers = require('../ledgers');
+const ui = require('../ui');
+const { RULE } = ui;
+const { parse, problem } = require('../args');
+
+const USAGE = 'usage: jos runs [--limit <n>] [--json]';
+const DEFAULT_LIMIT = 20;
+
+const HELP = (C) => `
+${C.purple}${RULE}${C.reset}
+${C.bold}JOS RUNS${C.reset} // The runs recorded in ~/.jos/runs
+${C.purple}${RULE}${C.reset}
+
+${C.bold}Usage:${C.reset}
+  jos runs [--limit <n>] [--json]
+
+  jos-core writes a ledger for every run (not --dry-run). Runs of documents inside a
+  folder with .jos/manifest.jos keep it in that folder's .jos/replays/; the others in
+  ~/.jos/runs/, which this command lists, newest first. Every ledger is verified;
+  the cost is the metered cost_usd, shown only when an engine reported one.
+
+${C.bold}Options:${C.reset}
+  --limit <n>   Show at most n runs (default ${DEFAULT_LIMIT}; 0 shows all)
+  --json        Print the list as JSON
+
+${C.bold}See also:${C.reset}
+  jos ledger verify <run_id>    jos meter <run_id>
+`;
+
+const CODE_MEANING = {
+    0: 'done', 1: 'not done', 2: 'invalid', 3: 'blocked', 4: 'budget', 5: 'unexecutable', 124: 'timeout', 137: 'output limit',
+};
+
+exports.execute = async (args, josHome) => {
+    const err = ui.printer(process.stderr);
+    const { opts, files, help, error } = parse(args, { '--json': false, '--limit': true });
+    if (help) {
+        const out = ui.printer(process.stdout);
+        out.text(HELP(out.C));
+        return 0;
+    }
+    const limit = opts['--limit'] === undefined ? DEFAULT_LIMIT : Number(opts['--limit']);
+    if (error || files.length || !Number.isInteger(limit) || limit < 0) {
+        err.fail('jos runs: ' + (error ? problem(error) : files.length ? 'takes no arguments' : '--limit takes a whole number, 0 or more'));
+        err.hint(USAGE);
+        return 64;
+    }
+
+    let core;
+    try { core = kernel.need(kernel.locate(), ['ledger.read', 'ledger.verify', 'ledger.meter']); } catch (e) { return kernel.fail(e); }
+    const dir = path.join(josHome, 'runs');
+    let names = [];
+    try { names = fs.readdirSync(dir); } catch (e) { /* no runs yet */ }
+    const ids = names.filter((n) => ledgers.RUN_ID.test(n) && fs.existsSync(path.join(dir, n, 'ledger.jsonl'))).sort().reverse();
+    const shownIds = limit === 0 ? ids : ids.slice(0, limit);
+    const rows = shownIds.map((id) => {
+        const file = path.join(dir, id, 'ledger.jsonl');
+        const r = ledgers.read(core, file);
+        const s = r.errors ? { ledger_ok: false, reason: r.errors.join('; '), started: null, document: null, artifact: null, code: null, cost_usd: null } : ledgers.summary(core, r.lines);
+        return Object.assign({ run: id, file }, s);
+    });
+
+    if (opts['--json']) {
+        ui.json(process.stdout, rows);
+        return 0;
+    }
+    const out = ui.printer(process.stdout);
+    const { C } = out;
+    out.header('JOS RUNS', dir);
+    if (!ids.length) {
+        out.line('  No runs recorded here yet.');
+        out.hint('Runs of documents outside a .jos/ folder land here. Try: jos start');
+        out.line();
+        return 0;
+    }
+    for (const r of rows) {
+        if (!r.ledger_ok) {
+            out.warn(r.run, '(ledger does not verify: ' + r.reason + ')');
+            continue;
+        }
+        const when = r.started === null ? '' : r.started.replace(/\.\d+Z$/, 'Z');
+        const meaning = r.code === null ? 'no code' : (CODE_MEANING[r.code] || 'error');
+        const mark = r.code === 0 ? `${C.green}✓${C.reset}` : `${C.red}✖${C.reset}`;
+        out.line(`${mark} ${C.bold}${r.run}${C.reset}  ${when}  code ${r.code === null ? '-' : r.code} ${C.gray}(${meaning})${C.reset}`);
+        out.hint((r.document === null ? '(no receipt)' : r.document) + (r.artifact === null ? '' : '  ' + r.artifact) + (r.cost_usd === null ? '' : '  ' + r.cost_usd + ' USD'));
+    }
+    if (shownIds.length < ids.length) out.hint('… and ' + (ids.length - shownIds.length) + ' more (--limit 0 shows all)');
+    out.line();
+    out.hint('Next: jos ledger verify <run_id>   jos meter <run_id>');
+    out.line();
+    return 0;
+};