@josfox/jos 4.1.0 → 5.0.0

package/src/commands/verify.js

@@ -1,98 +1,56 @@
-/**
- * JOS VERIFY Command - Self-Verification Suite
- * Implements "Dogfooding" strategy
- */
-
-const fs = require('fs');
-const path = require('path');
-const { spawnSync, execSync } = require('child_process');
-
-const C = {
-    reset: '\x1b[0m', bold: '\x1b[1m',
-    green: '\x1b[38;5;78m', red: '\x1b[38;5;196m',
-    cyan: '\x1b[38;5;51m', gray: '\x1b[38;5;245m',
-    yellow: '\x1b[38;5;220m'
-};
-
-exports.execute = async (args, home) => {
-    console.log(`\n${C.cyan}${C.bold}🦊 JOS Self-Verification${C.reset}\n`);
-
-    const binDir = path.join(__dirname, '..', '..', 'bin');
-    const binJos = path.join(binDir, 'jos');
-
-    // 1. PATH Injection (Crucial for Windows)
-    // We add the bin directory to the front of PATH so 'jos' resolves to our binary
-    const env = { ...process.env, CI: 'true' };
-    env.PATH = process.platform === 'win32'
-        ? `${binDir};${process.env.PATH}`
-        : `${binDir}:${process.env.PATH}`;
-
-    let failed = false;
-
-    // 2. Dogfooding: Run verification.jos
-    console.log(`${C.bold}1. Kernel Smoke Tests (verification.jos)${C.reset}`);
-    const verifyArtifact = path.join(__dirname, '..', '..', 'artifacts', 'verification.jos');
-
-    if (!fs.existsSync(verifyArtifact)) {
-        console.error(`${C.red}✖ Internal Error: verification.jos not found at ${verifyArtifact}${C.reset}`);
-        process.exit(1);
-    }
-
-    try {
-        // We defer to the 'run' command logic by spawning a child process
-        // This ensures identical execution environment to a real user run
-        const result = spawnSync(process.execPath, [binJos, 'run', verifyArtifact], {
-            encoding: 'utf8',
-            env,
-            stdio: 'inherit'
-        });
-
-        if (result.status !== 0) {
-            console.error(`\n${C.red}✖ Smoke tests failed (Exit Code: ${result.status})${C.reset}`);
-            failed = true;
-        } else {
-            console.log(`${C.green}✓ Smoke tests passed${C.reset}`);
-        }
-
-    } catch (e) {
-        console.error(`${C.red}✖ Execution failed: ${e.message}${C.reset}`);
-        failed = true;
-    }
-
-    // 3. Functional Test (Init + Validate)
-    console.log(`\n${C.bold}2. Functional Lifecycle (Init + Validate)${C.reset}`);
-    const TEST_ARTIFACT = 'native-test';
-    const TEST_FILE = `${TEST_ARTIFACT}.jos`;
-
-    // Cleanup
-    if (fs.existsSync(TEST_FILE)) fs.unlinkSync(TEST_FILE);
-
-    try {
-        console.log(`${C.gray}→ Initializing ${TEST_ARTIFACT}...${C.reset}`);
-        execSync(`"${process.execPath}" "${binJos}" init ${TEST_ARTIFACT} --pipeline`, { env, stdio: 'pipe' });
-
-        if (!fs.existsSync(TEST_FILE)) {
-            throw new Error('Artifact file not created');
-        }
-
-        console.log(`${C.gray}→ Validating artifact...${C.reset}`);
-        execSync(`"${process.execPath}" "${binJos}" validate ${TEST_FILE}`, { env, stdio: 'pipe' });
-
-        console.log(`${C.green}✓ Lifecycle tests passed${C.reset}`);
-
-    } catch (e) {
-        console.error(`${C.red}✖ Functional test failed: ${e.message}${C.reset}`);
-        failed = true;
-    } finally {
-        if (fs.existsSync(TEST_FILE)) fs.unlinkSync(TEST_FILE);
-    }
-
-    console.log(`\n${C.gray}----------------------------------------${C.reset}`);
-    if (failed) {
-        console.log(`${C.red}${C.bold}❌ VERIFICATION FAILED${C.reset}`);
-        process.exit(1);
-    } else {
-        console.log(`${C.green}${C.bold}✅ SYSTEM HEALTHY${C.reset}`);
-        process.exit(0);
-    }
-};
+/**
+ * JOS VERIFY - Self-check: runs the embedded examples/hello.jos through jos-core
+ * Exit 0 when the kernel returns ok, 1 otherwise, 5 when no kernel is found.
+ *
+ * The check is hermetic: hello.jos is copied to a fresh temporary directory, which is also the HOME the kernel sees, so
+ * no `.jos/` chain of the user or of the folder where jos is installed applies, and the ledger of the run lands in that
+ * directory. The directory is removed at the end: verify leaves nothing in ~/.jos or anywhere else.
+ */
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const pkg = require('../../package.json');
+const kernel = require('../kernel');
+const ui = require('../ui');
+
+const HELLO = path.join(__dirname, '..', '..', 'examples', 'hello.jos');
+
+exports.execute = async () => {
+    const out = ui.printer(process.stdout);
+    const { C } = out;
+
+    let k;
+    try { k = kernel.locate(); } catch (e) { return kernel.fail(e); }
+    const core = k.core;
+    out.header('JOS VERIFY', `jos ${pkg.version} | jos-core ${k.version} (${k.source})`);
+
+    out.line(`${C.bold}1. Kernel smoke test (examples/hello.jos)${C.reset}`);
+    let failed = false;
+    let tmp = null;
+    try {
+        tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'jos-verify-'));
+        const file = path.join(tmp, 'hello.jos');
+        fs.copyFileSync(HELLO, file);
+        // read once and run with the octets, as jos run does (jos-core 2.0.0-rc.8 verifies a 0.0.7 integrity_ref on them)
+        const { doc, bytes } = core.loadFileBytes(file);
+        const r = await core.run(doc, { cwd: tmp, dir: tmp, home: tmp, source: bytes, env: process.env });
+        if (r.ok === true && r.code === 0) {
+            out.ok('ok', `${r.artifact} (${r.duration_ms} ms)`);
+        } else {
+            out.fail(`not ok (code ${r.code})`, r.errors ? r.errors.join('; ') : '');
+            failed = true;
+        }
+    } catch (e) {
+        out.fail(e.message);
+        failed = true;
+    } finally {
+        if (tmp) fs.rmSync(tmp, { recursive: true, force: true });
+    }
+
+    out.line();
+    if (failed) out.fail(`${C.bold}VERIFICATION FAILED`);
+    else out.ok(`${C.bold}SYSTEM HEALTHY`);
+    out.line();
+    return failed ? 1 : 0;
+};

package/src/commands/version.js

@@ -0,0 +1,23 @@
+/**
+ * JOS VERSION - host version and the jos-core kernel it found
+ * Two plain lines (scripts read them): `jos <version>` and `jos-core <version> (<source>: <file>)`; with color on a
+ * terminal the location is gray. Without a kernel the second line is `jos-core not found` and the exit code is 0.
+ */
+'use strict';
+const pkg = require('../../package.json');
+const kernel = require('../kernel');
+const ui = require('../ui');
+
+exports.execute = async () => {
+    const out = ui.printer(process.stdout);
+    const { C } = out;
+    out.line('jos ' + pkg.version);
+    try {
+        const k = kernel.locate();
+        out.line('jos-core ' + k.version + ` ${C.gray}(` + k.source + ': ' + k.file + `)${C.reset}`);
+    } catch (e) {
+        if (!(e instanceof kernel.KernelNotFound)) throw e;
+        out.line('jos-core not found');
+    }
+    return 0;
+};

package/src/intention.js

@@ -0,0 +1,114 @@
+'use strict';
+// The intention of a document and the verdict of a run, in words, for `jos run` and `jos validate` (text mode only;
+// `--json` is the kernel's result unchanged). The intention comes from the document as jos-core normalized it
+// (intention.objective, intention.success_criteria, guardrails.avoid and guardrails.limit); the verdict comes only
+// from the receipts the kernel returned (criteria[].check / verdict / detail): the host evaluates nothing itself.
+
+const ONE_LINE = 160;
+
+const isObj = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
+const q = (s) => JSON.stringify(s);
+
+function oneLine(s) {
+    const t = s.replace(/\s+/g, ' ').trim();
+    return t.length > ONE_LINE ? t.slice(0, ONE_LINE - 1) + '…' : t;
+}
+
+// A declared success criterion as a short phrase: "exit 0", 'stdout contains "x"', "all of (exit 0; stderr is empty)".
+// Criteria come from a document jos-core validated, so each object has the one key its schema allows.
+const short = (h) => h.replace(/^sha256:/, '').slice(0, 12) + '…';
+function describe(c) {
+    if (typeof c === 'string') return oneLine(c) + ' (descriptive)';
+    const k = Object.keys(c)[0];
+    const v = c[k];
+    switch (k) {
+        case 'exit': return 'exit ' + v;
+        case 'stdout_contains': return 'stdout contains ' + q(v);
+        case 'stdout_matches': return 'stdout matches /' + v + '/';
+        case 'stderr_empty': return 'stderr is empty';
+        case 'file_exists': return 'file ' + q(v) + ' exists';
+        case 'file_sha256': return 'file ' + q(v.path) + ' has sha256 ' + short(v.hash);
+        case 'sha256': return 'output has sha256 ' + short(v);
+        case 'json_schema': return 'output validates against a JSON Schema';
+        case 'judge': return 'a judge engine grades it: ' + oneLine(v.rubric);
+        case 'all': case 'any': return k + ' of (' + v.map(describe).join('; ') + ')';
+        case 'not': return 'not (' + describe(v) + ')';
+        default: return k + ' ' + q(v);
+    }
+}
+
+const LIMIT_WORDS = { seconds: ' s', output_bytes: ' output bytes per stream', tokens: ' tokens', retries: ' retries' };
+function limitText(limit) {
+    return Object.keys(limit).map((k) => {
+        if (k === 'cost_usd') return limit[k] + ' USD';
+        if (Object.prototype.hasOwnProperty.call(LIMIT_WORDS, k)) return limit[k] + LIMIT_WORDS[k];
+        return k + ' ' + q(limit[k]);
+    }).join(', ');
+}
+
+// "Intention:", "Done when:", and when declared "Avoid:" and "Limit:", for the normalized document `doc`.
+function intention(p, doc) {
+    const { C } = p;
+    const it = isObj(doc.intention) ? doc.intention : {};
+    const g = isObj(doc.guardrails) ? doc.guardrails : {};
+    p.line();
+    p.line(`${C.bold}Intention:${C.reset} ` + (typeof it.objective === 'string' && it.objective.trim() ? oneLine(it.objective) : `${C.gray}not declared${C.reset}`));
+    const criteria = it.success_criteria === undefined ? [] : [].concat(it.success_criteria);
+    if (!criteria.length) p.line(`${C.bold}Done when:${C.reset} ${C.gray}not declared${C.reset}`);
+    else {
+        p.line(`${C.bold}Done when:${C.reset}`);
+        for (const c of criteria) p.item(describe(c));
+    }
+    if (Array.isArray(g.avoid) && g.avoid.length) p.line(`${C.bold}Avoid:${C.reset} ` + g.avoid.map(q).join(', '));
+    if (isObj(g.limit) && Object.keys(g.limit).length) p.line(`${C.bold}Limit:${C.reset} ` + limitText(g.limit));
+}
+
+// "Inferred:": the `inferred` section of jos-core (2.0.0-rc.8) for a valid document, one line per JSON Pointer in the
+// kernel's order: what the kernel applies that the document does not write (value and source, SPEC section or jos-core
+// default, and its note), and, flagged with ⚠, what the document does not declare.
+function inferred(p, section) {
+    const { C } = p;
+    const keys = Object.keys(section);
+    p.line();
+    if (!keys.length) {
+        p.line(`${C.bold}Inferred:${C.reset} ${C.gray}nothing (the document writes every member jos-core applies)${C.reset}`);
+        return;
+    }
+    p.line(`${C.bold}Inferred:${C.reset} ${C.gray}(applied by jos-core, not written in the document)${C.reset}`);
+    for (const k of keys) {
+        const e = section[k];
+        const note = e.note ? ` ${C.gray}— ${oneLine(e.note)}${C.reset}` : '';
+        if (e.source === 'not declared') p.line(`  ${C.yellow}⚠ ${k}: not declared${C.reset}` + note);
+        else p.item(k + (Object.prototype.hasOwnProperty.call(e, 'value') ? ' = ' + oneLine(JSON.stringify(e.value)) : '') + ` ${C.gray}(${e.source})${C.reset}` + note);
+    }
+}
+
+// One line per criterion verdict of a receipt, indented by depth; combinators list their items below them.
+function criteriaLines(p, list, depth) {
+    const { C } = p;
+    const pad = '  '.repeat(depth);
+    for (const c of list) {
+        const sign = c.verdict === 'pass' ? `${C.green}✓` : c.verdict === 'fail' ? `${C.red}✖` : `${C.gray}•`;
+        const note = c.verdict === 'descriptive' ? ' (descriptive, recorded only)' : '';
+        p.line(`${pad}${sign} ${c.check}${C.reset}${C.gray}: ${c.detail}${note}${C.reset}`);
+        if (Array.isArray(c.items)) criteriaLines(p, c.items, depth + 1);
+    }
+}
+
+// "Verdict:": per receipt (each step of a flow, then the flow itself) its code and the verdict of each criterion.
+// The caller passes a result with at least one receipt.
+function verdict(p, result) {
+    const { C } = p;
+    p.line();
+    p.line(`${C.bold}Verdict:${C.reset}`);
+    for (const r of result.receipts) {
+        const mark = r.ok ? `${C.green}✓` : `${C.red}✖`;
+        const label = r.flow ? r.step + ' (flow ' + r.flow + ')' : r.step;
+        p.line(`  ${C.blue}[${r.attempt}] ${label}${C.reset} ${mark} code ${r.code}${C.reset}` + (r.reason ? ` ${C.gray}${r.reason}${C.reset}` : ''));
+        const list = r.criteria || [];
+        if (list.length) criteriaLines(p, list, 2);
+        else p.line(`    ${C.gray}no criterion evaluated${C.reset}`);
+    }
+}
+
+module.exports = { describe, limitText, oneLine, intention, inferred, verdict };

package/src/kernel.js

@@ -0,0 +1,69 @@
+'use strict';
+// Locates the jos-core reference kernel. No network.
+//   1. the installed dependency @josfox/jos-core
+//   2. ../../../kernel/js/jos-core.js (monorepo checkout)
+//   3. otherwise a clear error; hosts map it to exit code 5 (SPEC-2.0 section 7.1).
+
+const fs = require('fs');
+const path = require('path');
+const ui = require('./ui');
+
+const MONOREPO_PATH = path.resolve(__dirname, '..', '..', '..', 'kernel', 'js', 'jos-core.js');
+
+class KernelNotFound extends Error {}
+
+let cached = null;
+
+function locate() {
+    if (cached) return cached;
+    let file = null;
+    let source = null;
+    try {
+        file = require.resolve('@josfox/jos-core');
+        source = 'dependency';
+    } catch (e) {
+        if (e.code !== 'MODULE_NOT_FOUND') throw e;
+    }
+    if (!file && fs.existsSync(MONOREPO_PATH)) {
+        file = MONOREPO_PATH;
+        source = 'monorepo';
+    }
+    if (!file) {
+        throw new KernelNotFound(
+            'jos-core not found. Install @josfox/jos-core next to @josfox/jos, ' +
+            'or run from a checkout that contains kernel/js/jos-core.js.');
+    }
+    let core;
+    try {
+        core = require(file);
+    } catch (e) {
+        throw new KernelNotFound('jos-core at ' + file + ' failed to load: ' + e.message);
+    }
+    for (const fn of ['validate', 'run', 'loadFile']) {
+        if (typeof core[fn] !== 'function') {
+            throw new KernelNotFound('jos-core at ' + file + ' does not export ' + fn + '()');
+        }
+    }
+    cached = { core, version: core.VERSION, file, source };
+    return cached;
+}
+
+// The kernel's core when it has every function in names ('validate', 'ledger.verify', ...); otherwise KernelNotFound
+// naming the first one missing (an older jos-core), which a command turns into exit 5 with fail().
+function need(k, names) {
+    for (const n of names) {
+        let v = k.core;
+        for (const part of n.split('.')) v = v === null || v === undefined ? undefined : v[part];
+        if (typeof v !== 'function') throw new KernelNotFound('jos-core ' + k.version + ' at ' + k.file + ' does not export ' + n + '()');
+    }
+    return k.core;
+}
+
+// Prints the error and returns exit code 5, for use as `return kernel.fail(e)`.
+function fail(e) {
+    if (!(e instanceof KernelNotFound)) throw e;
+    ui.printer(process.stderr).fail('jos: ' + e.message);
+    return 5;
+}
+
+module.exports = { locate, need, fail, KernelNotFound, MONOREPO_PATH };

package/src/ledgers.js

@@ -0,0 +1,57 @@
+'use strict';
+// Run ledgers for `jos ledger verify`, `jos meter` and `jos runs`: thin calls into the ledger API of jos-core
+// (Ledger 0.1.0: find, read, verify, meter). Read-only: nothing here writes, creates ~/.jos or runs a document.
+const fs = require('fs');
+const path = require('path');
+
+// A run id as jos-core mints it (`run_` + a ULID); anything else must be the path of a ledger.
+const RUN_ID = /^run_[0-9A-Za-z]{1,64}$/;
+
+const isFile = (p) => { try { return fs.statSync(p).isFile(); } catch (e) { return false; } };
+const isDir = (p) => { try { return fs.statSync(p).isDirectory(); } catch (e) { return false; } };
+
+// Where the ledger of `ref` is: { file } for a ledger file, a run folder holding ledger.jsonl, or a run id that
+// jos-core finds (.jos/replays/ of the folders above the current directory, then ~/.jos/runs/); { error: 'usage' }
+// when ref is neither a path nor a run id; { error: 'missing' } when no ledger of that run exists.
+function locate(core, ref, josHome) {
+    if (isFile(ref)) return { file: path.resolve(ref) };
+    if (isDir(ref) && isFile(path.join(ref, 'ledger.jsonl'))) return { file: path.resolve(ref, 'ledger.jsonl') };
+    if (!RUN_ID.test(ref)) return { error: 'usage' };
+    const file = core.ledger.find(ref, { home: path.dirname(josHome) });
+    return file === null ? { error: 'missing' } : { file };
+}
+
+// The lines of a ledger file, or { errors } when it cannot be read (a JosError of the kernel).
+function read(core, file) {
+    try { return { lines: core.ledger.read(file) }; } catch (e) {
+        if (!(e instanceof core.JosError)) throw e;
+        return { errors: e.errors };
+    }
+}
+
+// What a listing shows of one run, from its ledger lines: whether the ledger verifies and, only when it does, when the
+// run started, the document (the name on its top-level receipt, the last one, and the art_ it admitted), its exit code
+// and its metered cost (null when no engine reported one). A ledger that does not verify says only why.
+const str = (x) => (typeof x === 'string' ? x : null);
+const obj = (x) => (x !== null && typeof x === 'object' ? x : {});
+function summary(core, lines) {
+    const v = core.ledger.verify(lines, {});
+    if (!v.ok) return { ledger_ok: false, reason: v.reason, started: null, document: null, artifact: null, code: null, cost_usd: null };
+    const entries = lines.map((l) => JSON.parse(l));
+    const m = core.ledger.meter(lines);
+    const receipts = entries.filter((e) => e.kind === 'receipt');
+    const top = receipts.length ? obj(receipts[receipts.length - 1].body) : {};
+    return {
+        ledger_ok: true, reason: null, started: str(entries[0].ts), document: str(top.step),
+        artifact: str(obj(entries[entries.length - 1].body).artifact), code: typeof m.code === 'number' ? m.code : null, cost_usd: m.cost_usd,
+    };
+}
+
+// The text after a failed lookup, for the printer of a command.
+function explainMissing(err, cmd, ref, josHome) {
+    err.fail('jos ' + cmd + ': no ledger for ' + ref);
+    err.hint('searched .jos/replays/ of the folders above ' + process.cwd() + ' and ' + path.join(josHome, 'runs'));
+    err.hint('list the runs with: jos runs');
+}
+
+module.exports = { RUN_ID, locate, read, summary, explainMissing };

package/src/mcp-guide.js

@@ -0,0 +1,138 @@
+/**
+ * What a person reads about `jos serve --mcp`: the help screen (`jos serve --help`, stdout) and the notice the server
+ * prints on stderr when its stdin is a terminal (a person, not an MCP client). Both name the tools with one line each,
+ * what a client cannot do, and how to connect this very bin/jos, with its absolute path resolved at run time.
+ * Nothing here writes to the JSON-RPC channel; every line goes through a printer of ui.js (STYLE.md).
+ */
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const ui = require('./ui');
+
+const BIN = path.resolve(__dirname, '..', 'bin', 'jos');
+const SECURITY = path.resolve(__dirname, '..', 'SECURITY-MCP.md');
+
+// One line per tool of src/mcp.js (test/mcp.test.js checks that every tool has one and that no extra one is listed).
+const USES = {
+    list_files: 'list the files and folders of a directory under the root (recursive to depth 3)',
+    read_file: 'read a regular file under the root (at most 10 MB)',
+    search_files: 'find files under the root by a glob on the name (* and ?; 100 matches, depth 5)',
+    read_markdown: 'read a Markdown file under the root, with its line count',
+    list_modules: 'list the modules in ~/.jos/modules and whether ~/.jos/modules.json enables them',
+    list_processes: 'list the runs recorded in ~/.jos/runs/*/report.json',
+    hot_reload: 'read ~/.jos/modules.json again and report the enabled and disabled modules',
+    write_file: 'create or overwrite a file under the root, never under ~/.jos',
+    run_command: 'run a program with an argv (no shell) in a folder under the root; each one shown on stderr',
+};
+const FLAG = { write_file: '--allow-write', run_command: '--allow-shell' };
+
+// What --allow-shell grants, said the same way in the help screen, the notice and SECURITY-MCP.md (review OAI-RC6-05).
+const SHELL_RISK = '--allow-shell grants local code execution with your user privileges: a program it runs can read ' +
+    'your secrets (~/.jos/secrets, ~/.ssh, cloud keys) outside the MCP tools and their denials. Do not give it to an ' +
+    'untrusted agent without an external sandbox (a container or a virtual machine).';
+
+const CANNOT = [
+    'reach a file outside the root (real paths, symlinks resolved, device and inode compared)',
+    'read, list, search or write ~/.jos/secrets, nor any .master or vault.json under ~/.jos',
+    'write a file without --allow-write, nor under ~/.jos with it',
+    'run a program without --allow-shell (with it the program runs as you and could read ~/.jos/secrets)',
+];
+
+// The absolute path of a `jos` on PATH that is this bin/jos (an npm install), or null.
+function onPath(env) {
+    const self = fs.realpathSync(BIN);
+    for (const dir of String(env.PATH || '').split(path.delimiter)) {
+        if (!path.isAbsolute(dir)) continue;
+        const p = path.join(dir, 'jos');
+        try { if (fs.realpathSync(p) === self) return p; } catch (e) { /* not there */ }
+    }
+    return null;
+}
+
+// How to connect this server, read-only, with `root` as its root: Claude Code, then Claude Desktop / Cursor.
+function connect(p, root, env) {
+    const { C } = p;
+    const args = [BIN, 'serve', '--mcp', '--root', root];
+    p.line(`${C.bold}Connect it${C.reset} ${C.gray}(read-only, root ${root})${C.reset}`);
+    const home = os.homedir();
+    if (home === root || home.startsWith(root.endsWith(path.sep) ? root : root + path.sep)) {
+        p.warn('This root is your home directory or contains it: put a project folder after --root before you copy these.');
+    }
+    p.line(`  ${C.white}Claude Code:${C.reset}`);
+    p.cmd('claude mcp add jos -- node ' + args.map(ui.shellArg).join(' '));
+    const installed = onPath(env);
+    if (installed) p.cmd('claude mcp add jos -- jos ' + args.slice(1).map(ui.shellArg).join(' ') + `${C.reset}   ${C.gray}(jos on PATH: ${installed})`);
+    p.cmd('claude mcp remove jos' + `${C.reset}   ${C.gray}(to remove it)`);
+    p.line(`  ${C.white}Claude Desktop${C.reset} ${C.gray}(claude_desktop_config.json)${C.reset} ${C.white}or Cursor${C.reset} ${C.gray}(.cursor/mcp.json):${C.reset}`);
+    const block = JSON.stringify({ mcpServers: { jos: { command: 'node', args } } }, null, 2);
+    for (const l of block.split('\n')) p.line('    ' + l);
+    p.hint('If the client cannot find node, put its absolute path in "command": ' + process.execPath);
+    p.hint('Add --allow-write or --allow-shell to the arguments only if the client needs them (SECURITY-MCP.md).');
+}
+
+function tools(p, names, marked) {
+    const w = Math.max(...names.map((n) => n.length));
+    for (const n of names) {
+        p.item(`${p.C.cyan}${n.padEnd(w)}${p.C.reset}  ${USES[n]}` + (marked && FLAG[n] ? ` ${p.C.yellow}(only with ${FLAG[n]})${p.C.reset}` : ''));
+    }
+}
+
+// `jos serve --help`. names: every tool of src/mcp.js, the gated ones included; root: the root it would serve.
+function help(stream, names, root, env) {
+    const p = ui.printer(stream);
+    const { C } = p;
+    p.header('JOS SERVE', 'MCP server over stdio (Model Context Protocol)');
+    p.text(`${C.bold}Usage:${C.reset}
+  jos serve --mcp [--root <dir>] [--allow-write] [--allow-shell]
+
+${C.bold}Options:${C.reset}
+  --mcp           Start as MCP server (stdio JSON-RPC mode); read-only by default
+  --root <dir>    The one directory the client may reach (default: the working
+                  directory). Without it the server refuses to start in "/", in
+                  your home directory or in any directory that contains it.
+  --allow-write   Also offer write_file (inside the root, never under ~/.jos)
+  --allow-shell   Also offer run_command: the client runs any program as you, with
+                  an argv and no shell (announced on stderr; variables named like a
+                  secret of the vault are dropped from its environment). This is
+                  local code execution with your privileges: never for an
+                  untrusted agent without an external sandbox
+  --help, -h      Show this help
+
+`);
+    p.line(`${C.bold}Tools an MCP client gets:${C.reset}`);
+    tools(p, names, true);
+    p.line();
+    p.line(`${C.bold}What an MCP client cannot do:${C.reset}`);
+    for (const c of CANNOT) p.item(c);
+    p.warn(SHELL_RISK);
+    p.hint('The module tools read ~/.jos/modules.json, ~/.jos/modules and ~/.jos/runs only.');
+    p.hint('Details: ' + SECURITY);
+    p.line();
+    connect(p, root, env);
+    p.line();
+    p.hint('The HTTP file explorer is disabled until F3.');
+    p.line();
+}
+
+// The notice on stderr when stdin is a terminal. p: a printer on stderr; names: the tools this server offers.
+function notice(p, context, names) {
+    const { C } = p;
+    p.header('JOS SERVE', 'MCP server on stdio, waiting for a client');
+    p.warn('This is an MCP server: it reads JSON-RPC 2.0 on stdin and answers on stdout.');
+    p.hint('An MCP client starts this command and talks to it; typing here is not needed.');
+    p.line();
+    p.field('Root', context.root);
+    const on = [context.allowWrite && 'write_file (--allow-write)', context.allowShell && 'run_command (--allow-shell)'].filter(Boolean);
+    p.field('Mode', on.length ? `read-only plus ${C.yellow}${on.join(', ')}${C.reset}` : 'read-only');
+    p.field('Denied', '~/.jos/secrets, and any .master or vault.json under ~/.jos');
+    if (context.allowShell) p.warn(SHELL_RISK);
+    p.line();
+    p.line(`${C.bold}Tools:${C.reset}`);
+    tools(p, names, false);
+    p.line();
+    connect(p, context.root, context.env);
+    p.line();
+}
+
+module.exports = { help, notice, USES, BIN, onPath, SHELL_RISK };