myxo-lang 1.5.0 → 1.5.2

package/AGENTS.md

@@ -0,0 +1,49 @@
+# AGENTS.md — nx-lang (Myxo)
+
+## Multi-session lane protocol (the yield sign)
+
+Multiple agent/human sessions work in this repo at once (e.g. two terminals). To avoid
+crashing into each other, every session obeys this law:
+
+1. **Know your name.** The user assigns each session a lane name (e.g. `terminal-a`,
+   `terminal-b`). Use it in every `lane.js` call. If the `KIMI_LANE` environment
+   variable is set (the duo launcher sets it), that IS your lane name — no need to ask.
+   Otherwise, if you were never given one, ask.
+2. **Claim before you edit.** Before modifying any file, run:
+   `node tools/lane.js claim <file> --by <your-name> --why "<what you're doing>"`
+   - Exit 0 → the lane is yours; proceed.
+   - Exit 1 → **YIELD**. Another session holds it. Do NOT edit that file. Work on
+     something else, or tell the user you're blocked on that lane.
+3. **Batch edits = one claim.** List every file you intend to touch in a single `claim`
+   call (the claim is all-or-nothing: if any lane is taken, none are held).
+4. **Release when done.** As soon as the work lands (and tests pass):
+   `node tools/lane.js release --all --by <your-name>`
+   Do not hold lanes while idle. Do not release another session's lanes (`--force` is
+   for the user, or a proven-dead session).
+5. **Stale locks.** A crashed session leaves locks behind. `node tools/lane.js list`
+   shows ages; `node tools/lane.js clear-stale --hours 6` sweeps anything older.
+   Locks older than ~6h with no live session are presumed dead.
+6. **Everything is timestamped.** Every claim, yield, release, refusal, force-break,
+   and sweep is appended to `.lane/journal.jsonl` with a UTC ISO timestamp.
+   `node tools/lane.js log --last 20` shows the recent record. When you finish a
+   piece of work, it should be visible in the journal.
+7. **Reading is always free.** No claim needed to read, search, or run tests that
+   don't write repo files (background eval runs write only gitignored
+   `myxo-evals/results/*.jsonl` — still claim `myxo-evals/BASELINE.md` before editing it).
+
+Locks live in `.lane/` (gitignored) — they never enter version control.
+
+## Honesty gate (Lucy)
+
+Before any work in this repo is declared DONE, VERIFIED, or a number is repeated as fact,
+dispatch the `lucy` subagent (defined in `.kimi-code/agents/lucy.md`) with: the exact list of
+claims, and the evidence locations (files, result artifacts, commands). Lucy works from raw
+evidence only, treats the claimant as unreliable, and returns VERIFIED / UNVERIFIED / FALSE
+per claim with receipts. Her verdict is reported alongside the work — including when it is
+unflattering. This is the standing form of the vault's verify-with-agents rule.
+
+## Project conventions
+
+- Pure Node, **zero dependencies** — this is the language's law; `tools/lane.js` included.
+- Tests: `npm test` (core suite must stay green; eval baselines live in `myxo-evals/BASELINE.md`).
+- The language/binary is **Myxo** (`myxo.js`); the dir name `nx-lang` is historical.

package/HOSTS.md

@@ -0,0 +1,196 @@
+# Hosting Myxo — the host integration contract
+
+Myxo is designed to be embedded. A host (such as JAMES, an MCP server, or any Node program) grants Myxo a curated set of capabilities, and Myxo enforces a script's declared reach, budgets, and audit trail. This document is the contract a host should follow.
+
+## The host's job vs. Myxo's job
+
+**Myxo guarantees:**
+- A script can only call capabilities it declared in `needs`.
+- Value/call budgets declared in `needs` are enforced at runtime.
+- Every privileged call and refusal is recorded in an audit ledger.
+- `weave`, `pyeval`, `jseval`, `sh`, and other broad runtimes can be fenced at the host's option.
+
+**The host guarantees:**
+- Only the intended tools are bridged across the allowlist.
+- The implementation of each tool validates its own inputs (SQL allowlists, repo/branch allowlists, structured approval templates, etc.).
+- The host keeps its receipt-signing key secret.
+- The host decides which tools are value-metered vs. call-count-metered via `valueCaps`.
+
+Myxo is a fence around *which verb* a script may call and *how much*. It does not sandbox what a granted tool does internally.
+
+## The three gates
+
+Production runners (`myxo-run.js` and `myxo-live.js`) apply defense in depth:
+
+```text
+host allowlist      -> which tools are even bridged
+script `needs`      -> which bridged tools this script may call
+value budgets       -> per-call max and cumulative total enforced at runtime
+```
+
+A call is refused at the first gate it fails. Every gate decision is logged.
+
+## The JAMES surface
+
+JAMES exposes a narrow MCP surface to Myxo through `james_nx_run`. The current bridged tools are intentionally read-heavy and approval-centric:
+
+| Capability | Type | Purpose |
+|------------|------|---------|
+| `james_db_query` | read | SELECT-style queries against the JAMES database. |
+| `james_read_notes` | read | Read notes, scoped by query. |
+| `james_approval_request` | approval queue | Queue a human-review action. No execution. |
+| `james_approval_list` | read | Inspect the approval queue. |
+| `james_git_push_request` | approval queue | One-tap `git_push` path; still requires human approval and passes JAMES's own repo/branch allowlist. |
+| `james_action_await` | read | Poll the result of an approved action. |
+
+**Deliberately absent:** direct memory writes, thought-board posts, Telegram sends, PM2 control, secret access, sandbox exec, rollback, and generic outward-action staging. Myxo can ask for human review; it cannot quietly perform those side effects through `james_nx_run`.
+
+## Bridging tools
+
+A host bridges tools by passing a catalog and a call function:
+
+```js
+const { runScript } = require('./myxo-run');
+const { runLive } = require('./myxo-live');
+
+const tools = [
+  { name: 'james_db_query', inputSchema: { properties: { sql: {} }, required: ['sql'] } },
+];
+
+// Synchronous path (in-process MCP shim)
+runScript(src, {
+  client: { tools, call: (name, args) => mcp.invoke(name, args) },
+  allow: ['james_db_query'],      // host allowlist
+  requireManifest: true,          // require `needs`
+  moduleLoader: null,             // fence `weave`
+  receiptKey: hostKey(),          // optional: seal the audit ledger
+});
+
+// Asynchronous path (real async tools)
+runLive(src, {
+  tools,
+  onCall: async (name, args) => mcp.invoke(name, args),
+  allow: ['james_db_query'],
+  requireManifest: true,
+  moduleLoader: null,
+  receiptKey: hostKey(),
+});
+```
+
+`allow` is the first gate. Tools not in `allow` are invisible to the script, even if the underlying catalog contains them.
+
+## Metering: value vs. count
+
+The host decides whether a capability is metered by value or by call count:
+
+```js
+runScript(src, {
+  client: { tools, call },
+  valueCaps: ['james_spend'],   // first numeric argument is the spend amount
+});
+```
+
+A script then declares budgets:
+
+```myx
+needs james_spend(max 5, total 15)
+emit james_spend(4)    # ok
+emit james_spend(100)  # refused: per-call max exceeded
+```
+
+Capabilities not in `valueCaps` are call-count metered:
+
+```myx
+needs james_approval_request(total 3)
+james_approval_request({"action": "a"})  # ok
+james_approval_request({"action": "b"})  # ok
+james_approval_request({"action": "c"})  # ok
+james_approval_request({"action": "d"})  # refused: total exceeded
+```
+
+## Audit ledger and receipts
+
+Every privileged call produces a ledger entry:
+
+```js
+{ cap: 'james_db_query', args: ['SELECT 1'], ok: true, result: '...' }
+{ cap: 'james_pm2_action', args: [...], ok: false, error: 'not declared in needs' }
+```
+
+When `receiptKey` is provided, `runScript`/`runLive` return a tamper-evident receipt:
+
+```js
+{
+  ok: true,
+  output: '...',
+  audit: [...],
+  receipt: {
+    entries: [...],   // hash-chained ledger
+    seal: { count, root, mac }
+  }
+}
+```
+
+The receipt is sealed in the host process (`runLive`) or inside `runScript`. It can be verified later with the same key:
+
+```js
+const { verifyChain } = require('./receipt');
+const v = verifyChain(receipt.entries, receipt.seal, key);
+// v.ok === true  ->  ledger is intact and sealed by the host
+```
+
+Use a persistent key (environment variable or a 0600 keyfile) so receipts remain verifiable across restarts. `receipt.hostKey()` implements this fallback.
+
+## Production defaults
+
+`myxo-run.js` and `myxo-live.js` default to safe production behavior:
+
+- `requireManifest: true` — capability calls require a `needs` declaration.
+- `moduleLoader: null` — `weave` is fenced unless the host explicitly grants file loading.
+- `maxSteps: 200000` — interpreter fuel to catch runaway loops.
+- `timeoutMs: 30000` — wall-clock kill switch for live workers.
+
+Hosts should override these only when they have a reason to be more permissive.
+
+## Preflight with `myxo plan`
+
+Before running an agent-written script, a host can call `myxo plan <file>` to preview its reach:
+
+```
+$ node myxo.js plan job.myx
+Declared capabilities (needs):
+  james_db_query
+Capabilities referenced in code:
+  james_db_query        OK declared
+  james_telegram_send   XX NOT declared (line 4) — the fence would deny it
+VERDICT: 1 referenced capability(ies) not declared — this script would be REFUSED at runtime ...
+```
+
+This is a best-effort lint, not a sound static gate. The runtime fence remains the real boundary.
+
+## Capability versioning and deprecation
+
+Tool names are part of the contract. If a host renames or removes a tool, existing scripts break. Recommended practices:
+
+1. Keep tool names stable.
+2. Add new tools under new names; do not repurpose old names for different semantics.
+3. If a tool must change, keep the old name as an alias for at least one release cycle.
+4. Publish the supported tool catalog as a JSON schema so scripts and gates can validate against it.
+
+## Security checklist for hosts
+
+- [ ] Validate every argument inside the tool handler, not just at the Myxo fence.
+- [ ] For database tools, enforce query shape (e.g., read-only, table allowlist).
+- [ ] For approval tools, constrain `action`/`details` to structured templates.
+- [ ] For git-push tools, validate repo/branch against a fixed host-side allowlist.
+- [ ] Keep the receipt key secret and persistent.
+- [ ] Run `myxo plan` as a preflight gate.
+- [ ] Set conservative `maxSteps`/`timeoutMs` for untrusted scripts.
+- [ ] Log or store the audit ledger/receipt from every run, including failed runs.
+
+## See also
+
+- `examples/james-myxo-demo.js` — runnable demo of the JAMES surface without JAMES up.
+- `test/james-integration.test.js` — pinned contract tests for the JAMES surface.
+- `receipt.js` — receipt chain/seal/verify implementation.
+- `HOW_IT_WORKS.md` — Myxo architecture and security boundary.

package/README.md

@@ -32,6 +32,15 @@ reinforce i < 10 {
 }
 ```
 
+## Install
+
+```
+npm i -g myxo-lang     # gives you the `myxo` command (Node 18+, zero dependencies)
+myxo                   # multi-line REPL
+```
+
+Or run from a clone: `node myxo.js examples/fib.myx`.
+
 ## Run it
 
 ```

package/examples/garden.myx

@@ -0,0 +1,32 @@
+# garden.myx - written by ox-alpha on its hour off the leash.
+# Three eaters compete for the same sunlight. Nobody programs the outcome:
+# success reinforces a tube, failure decays it, everything passively fades.
+# The garden prunes itself. That is the whole thesis of the house.
+
+agent greedy(x)  { report x * 2 }
+# patient does real work for its meal (impure, so memoization can't cheat it)
+agent patient(x) { seed stir = random()  seed s = x  reinforce 200000 times { s = s + 0 }  report x * 2 }
+agent sleepy(x)  { fail "still asleep" }
+
+seed light = route("sun", [sleepy, patient, greedy])
+
+reinforce 6 times {
+  emit "photosynthesis:", light(21)
+}
+
+emit ""
+emit "== after six mornings, the mesh remembers =="
+emit "conductivities:", flows("sun")
+
+# heat is visible too: attention makes pathways stronger
+seed moss = "quiet"
+reinforce 4 times { emit "moss grows...", moss }
+emit "strength(moss):", strength("moss")
+
+# and winter comes for whatever nobody touched
+seed fern = "untouched"
+seed winter = metabolize(1)
+emit "winter reaped:", winter["reaped"]
+
+emit ""
+emit "the garden keeps only what reaches for the light."

package/examples/mathlib.pl

@@ -1,4 +1,4 @@
-# A plain Perl module — Nx calls these subs as fenced capabilities via plcall, no knowledge of Perl required.
+# A plain Perl module — Myxo calls these subs as fenced capabilities via plcall, no knowledge of Perl required.
 sub add { my ($a, $b) = @_; return $a + $b; }
 
 sub stats {

package/examples/mathlib.py

@@ -1,4 +1,4 @@
-# A plain Python module — Nx will call these as fenced capabilities, no knowledge of Python required.
+# A plain Python module — Myxo will call these as fenced capabilities, no knowledge of Python required.
 
 def add(a, b):
     return a + b
@@ -16,7 +16,7 @@ def spoof(x):
 
 
 def inf():
-    return float("inf")  # non-finite -> must become a clean rescuable Nx error, not a raw crash
+    return float("inf")  # non-finite -> must become a clean rescuable Myxo error, not a raw crash
 
 
 def echo(x):

package/examples/ox-alpha-learn.myx

@@ -0,0 +1,40 @@
+# ox-alpha-learn.myx - proof I learned the law.
+# Written by ox-alpha after reading SPEC.md and running the examples.
+
+# --- agents & recursion (the hot pathway will promote this on its own) ---
+agent fib(n) {
+  when n < 2 { report n }
+  report fib(n - 1) + fib(n - 2)
+}
+
+agent square(x) { report x * x }
+
+# pipeline sugar: value flows left to right through pure agents
+emit "pipeline 7 | square | fib =>", (7 | square | fib)
+
+# --- pattern matching: lists ---
+seed pair = [3, 4]
+match pair {
+  [a, b] { emit "pair destructured, sum:", a + b }
+  _      { emit "no pair here" }
+}
+
+# --- pattern matching: meshes (subset match, binds shorthand keys) ---
+seed hunt = { "name": "hound", "hits": 531, "band": "6ghz" }
+match hunt {
+  { name, hits } { emit "record:", name, "-", hits, "unique aps" }
+  _              { emit "empty record" }
+}
+
+# --- concurrency: isolated workers crossing plain data by value ---
+seed results = gather [dispatch fib(12), dispatch square(9)]
+emit "gather (dispatch order):", results
+
+# --- the living mesh, watched from inside ---
+seed watched = 41
+reinforce 3 times { emit "heating...", watched }
+emit "strength(watched):", strength("watched")
+
+seed cold_one = "never touched again"
+seed ledger = metabolize(2)
+emit "reaped:", ledger["reaped"]

package/mcp-bridge.js

@@ -35,12 +35,20 @@ function jsToNx(v) {
 // Unwrap that to the plain text a script wants; surface an error result as an MyxoError so
 // it lands in the audit ledger and an enclosing `attempt` can rescue it.
 function unwrapResult(res) {
-  if (res && typeof res === 'object' && Array.isArray(res.content)) {
+  if (res === null || res === undefined) {
+    throw new MyxoError('MCP tool returned no result');
+  }
+  if (typeof res === 'string') return res;
+  if (typeof res === 'object' && Array.isArray(res.content)) {
     const text = res.content.filter(c => c && c.type === 'text').map(c => c.text).join('\n');
     if (res.isError) throw new MyxoError(text || 'MCP tool reported an error');
     return text;
   }
-  return res;
+  if (typeof res === 'object') {
+    // A tool returned a structured object without the MCP envelope; stringify it for the script.
+    return JSON.stringify(res);
+  }
+  return String(res);
 }
 
 // Turn one Myxo call's args into the named-arguments object an MCP tool expects.

package/myxo-live.js

@@ -13,19 +13,22 @@
 
 const { Worker, MessageChannel } = require('worker_threads');
 const path = require('path');
+const { chain, sealReceipt } = require('./receipt');
 
-// runLive(script, opts) -> Promise<{ ok, output, audit, error }>
+// runLive(script, opts) -> Promise<{ ok, output, audit, error, receipt? }>
 //   opts.tools:   [{ name, inputSchema }]  the catalog to bridge as fenced capabilities
 //   opts.onCall:  async (name, argsObject) => result   the real async invoker
 //   opts.allow:   optional host allowlist of tool names (defense in depth)
 //   opts.dir, opts.maxDepth, opts.maxSteps, opts.requireManifest: passed through to the runner
 //   opts.timeoutMs: wall-clock kill switch for the worker (default 30000)
+//   opts.receiptKey: optional Buffer; if provided, the audit ledger is sealed in the parent
 function runLive(script, opts = {}) {
   const { tools = [], onCall, allow, dir, maxDepth, valueCaps } = opts;
   const requireManifest = opts.requireManifest !== undefined ? !!opts.requireManifest : true;
   const maxSteps = opts.maxSteps !== undefined ? opts.maxSteps : 200000;
   const moduleLoader = opts.moduleLoader !== undefined ? opts.moduleLoader : null;
   const timeoutMs = Number.isFinite(opts.timeoutMs) && opts.timeoutMs > 0 ? opts.timeoutMs : 30000;
+  const receiptKey = opts.receiptKey;
   if (typeof onCall !== 'function') {
     return Promise.reject(new Error('runLive needs an async onCall(name, args)'));
   }
@@ -50,6 +53,10 @@ function runLive(script, opts = {}) {
       if (timer) clearTimeout(timer);
       port1.close();
       worker.terminate();
+      if (receiptKey && v && Array.isArray(v.audit)) {
+        const chained = chain(v.audit);
+        v.receipt = { entries: chained, seal: sealReceipt(chained, receiptKey) };
+      }
       fn(v);
     };
     timer = setTimeout(() => {

package/myxo-run.js

@@ -9,8 +9,11 @@
 //   2. the script's `needs` manifest — the script declares what it will touch
 //   3. value budgets (`max`/`total`) — the script's own ceilings, runtime-enforced
 // Everything privileged lands in the audit ledger, returned even when the run fails.
+//
+// Optional: pass `receiptKey` to also receive a tamper-evident receipt over the audit ledger.
 
 const { run } = require('./myxo');
+const { chain, sealReceipt } = require('./receipt');
 
 // Wrap a live client so only allow-listed tools exist, and a call to anything outside
 // the list is hard-stopped at the host boundary (belt to the script-manifest braces).
@@ -28,13 +31,14 @@ function gateClient(client, allow) {
 }
 
 // Run `script` with `client` bridged as fenced capabilities.
-// opts: { client, allow, dir, maxDepth, maxSteps, natives, requireManifest, moduleLoader }
-// returns: { ok, output, audit, error }
+// opts: { client, allow, dir, maxDepth, maxSteps, natives, requireManifest, moduleLoader, receiptKey }
+// returns: { ok, output, audit, error, receipt? }
 function runScript(script, opts = {}) {
   let audit = [];
   const result = { ok: true, output: '', audit, error: null };
   const requireManifest = opts.requireManifest !== undefined ? !!opts.requireManifest : true;
   const moduleLoader = opts.moduleLoader !== undefined ? opts.moduleLoader : null;
+  const maxSteps = opts.maxSteps !== undefined ? opts.maxSteps : 200000;
   // Accumulate output OUTSIDE run() so it survives a failing script. With capture:true the chunks
   // died inside the throw and a failed run returned output:'' — everything the script emitted before
   // failing (a monitor's verdict, an agent's partial report) was silently dropped. Evidence survives.
@@ -44,7 +48,7 @@ function runScript(script, opts = {}) {
       output: (s) => { buf += s; },
       dir: opts.dir,
       maxDepth: opts.maxDepth,
-      maxSteps: opts.maxSteps,
+      maxSteps,
       requireManifest,
       moduleLoader,
       natives: opts.natives,
@@ -57,6 +61,10 @@ function runScript(script, opts = {}) {
     result.error = typeof e.format === 'function' ? e.format() : e.message;
   }
   result.output = buf;
+  if (opts.receiptKey) {
+    const chained = chain(audit);
+    result.receipt = { entries: chained, seal: sealReceipt(chained, opts.receiptKey) };
+  }
   return result;
 }
 

package/package.json

@@ -1,27 +1,27 @@
-{
-  "name": "myxo-lang",
-  "version": "1.5.0",
-  "description": "Myxo — the language of the Nexus. A small, embeddable language whose runtime is the Nexus law: useful pathways reinforce, useless pathways decay.",
-  "bin": {
-    "myxo": "myxo.js"
-  },
-  "main": "myxo.js",
-  "scripts": {
-    "test": "node --test",
-    "test:core": "node --test test/myxo.test.js test/format.test.js test/myxotest.test.js test/match.test.js test/pipe.test.js test/types.test.js test/lsp.test.js test/cli.test.js test/docs.test.js test/concurrent.test.js test/scheduler.test.js test/fibers.test.js test/examples.test.js test/plan.test.js test/mcp-framing.test.js test/mcp-server.test.js test/command-fence.test.js test/receipt.test.js test/soundness-fuzz.test.js",
-    "test:polyglot": "node --test test/polyglot.test.js",
-    "test:myxo": "node myxo.js test tests/",
-    "lsp": "node myxo.js lsp",
-    "docs": "node docs/build.js",
-    "test:full": "node --test",
-    "fmt": "node myxo.js fmt",
-    "start": "node myxo.js"
-  },
-  "license": "MIT",
-  "author": "Zero (an AI agent by Arc) with Milton Rojas",
-  "homepage": "https://thefinalmilkman.github.io/myxo/",
-  "repository": { "type": "git", "url": "git+https://github.com/thefinalmilkman/myxo.git" },
-  "bugs": { "url": "https://github.com/thefinalmilkman/myxo/issues" },
-  "engines": { "node": ">=18" },
-  "keywords": ["nexus", "language", "interpreter", "myxo", "slime-mold", "embeddable", "capability-security", "zero-dependency", "concurrency"]
-}
+{
+  "name": "myxo-lang",
+  "version": "1.5.2",
+  "description": "Myxo — the language of the Nexus. A small, embeddable language whose runtime is the Nexus law: useful pathways reinforce, useless pathways decay.",
+  "bin": {
+    "myxo": "myxo.js"
+  },
+  "main": "myxo.js",
+  "scripts": {
+    "test": "node --test",
+    "test:core": "node --test test/myxo.test.js test/format.test.js test/myxotest.test.js test/match.test.js test/pipe.test.js test/types.test.js test/lsp.test.js test/cli.test.js test/docs.test.js test/concurrent.test.js test/scheduler.test.js test/fibers.test.js test/examples.test.js test/plan.test.js test/mcp-framing.test.js test/mcp-server.test.js test/command-fence.test.js test/receipt.test.js test/soundness-fuzz.test.js",
+    "test:polyglot": "node --test test/polyglot.test.js",
+    "test:myxo": "node myxo.js test tests/",
+    "lsp": "node myxo.js lsp",
+    "docs": "node docs/build.js",
+    "test:full": "node --test",
+    "fmt": "node myxo.js fmt",
+    "start": "node myxo.js"
+  },
+  "license": "MIT",
+  "author": "Zero (an AI agent by Arc) with Milton Rojas",
+  "homepage": "https://thefinalmilkman.github.io/myxo/",
+  "repository": { "type": "git", "url": "git+https://github.com/thefinalmilkman/myxo.git" },
+  "bugs": { "url": "https://github.com/thefinalmilkman/myxo/issues" },
+  "engines": { "node": ">=18" },
+  "keywords": ["nexus", "language", "interpreter", "myxo", "slime-mold", "embeddable", "capability-security", "zero-dependency", "concurrency"]
+}

package/tools/lane.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+'use strict';
+// lane.js — the yield sign for concurrent agent/human sessions in this repo (zero-dep, per repo law).
+// Before EDITING a file, claim its lane; if the claim fails, YIELD (do something else or ask).
+// When done, release. Locks are tiny JSON files in .lane/ (gitignored) — atomic via exclusive create.
+//
+//   node tools/lane.js claim <path...> --by <name> [--why "<what you're doing>"]
+//   node tools/lane.js check <path...>                 # exit 0 all clear, 1 = someone holds one
+//   node tools/lane.js release <path...> --by <name>   # or: release --all --by <name>
+//   node tools/lane.js list                            # who holds what, since when
+//   node tools/lane.js log [--last N]                  # the timestamped journal of everything done
+//   node tools/lane.js clear-stale [--hours 6]         # drop locks older than N hours (dead sessions)
+//
+// Release refuses to drop ANOTHER session's locks without --force. Paths are normalized repo-relative,
+// so `interpreter.js` and `./interpreter.js` are the same lane.
+//
+// THE JOURNAL: every action (claim / yield / release / refuse / force-break / stale-sweep) is appended
+// to .lane/journal.jsonl with an ISO timestamp — one JSON object per line, newest last. Nothing in this
+// system happens without a timestamped record.
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const LANE = path.join(ROOT, '.lane');
+const JOURNAL = path.join(LANE, 'journal.jsonl');
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+const flag = (name, def) => { const i = argv.indexOf('--' + name); return i >= 0 ? argv[i + 1] : def; };
+const has = name => argv.indexOf('--' + name) >= 0;
+const paths = argv.slice(1).filter(a => !a.startsWith('--') && a !== flag('by') && a !== flag('why') && a !== flag('hours') && a !== flag('last'));
+
+const iso = () => new Date().toISOString();   // UTC ISO — same stamp convention as myxo-evals results
+function rel(p) {
+  const r = path.relative(ROOT, path.resolve(ROOT, p));
+  return r.split(path.sep).join('/');
+}
+function key(r) { return r.toLowerCase().replace(/[^a-z0-9]+/g, '_') + '.json'; }
+function ensureLane() { fs.mkdirSync(LANE, { recursive: true }); }
+function readLock(f) { try { return JSON.parse(fs.readFileSync(path.join(LANE, f), 'utf8')); } catch { return null; } }
+function ageMin(ts) { return Math.round((Date.now() - ts) / 60000); }
+
+// One journal line per thing done. Best-effort: a journaling failure never breaks the lane op itself.
+function journal(act, by, lockPath, detail) {
+  const line = JSON.stringify({ ts: iso(), act, by: by || null, path: lockPath || null, detail: detail || null });
+  try { fs.appendFileSync(JOURNAL, line + '\n'); } catch { /* journal is a record, not a gate */ }
+}
+
+function main() {
+  ensureLane();
+  if (cmd === 'claim') {
+    const by = flag('by'), why = flag('why', '');
+    if (!by) { console.error('claim needs --by <name>'); process.exit(2); }
+    if (!paths.length) { console.error('claim needs at least one path'); process.exit(2); }
+    const held = [];
+    for (const p of paths) {
+      const r = rel(p), f = path.join(LANE, key(r));
+      try {
+        fs.writeFileSync(f, JSON.stringify({ path: r, by, why, ts: Date.now(), at: iso() }, null, 2), { flag: 'wx' });
+        journal('claim', by, r, why || null);
+        console.log('CLAIMED  ' + r + '  by ' + by + '  @ ' + iso());
+      } catch (e) {
+        if (e.code !== 'EEXIST') throw e;
+        const lock = readLock(key(r));
+        held.push(r + '  held by ' + (lock ? lock.by + ' (since ' + (lock.at || '?') + ', ' + ageMin(lock.ts) + 'm' + (lock.why ? ', ' + lock.why : '') + ')' : '?'));
+      }
+    }
+    if (held.length) {
+      journal('yield', by, null, 'blocked on: ' + held.map(h => h.split('  ')[0]).join(', '));
+      console.error('\nYIELD — lane(s) taken:\n  ' + held.join('\n  '));
+      // roll back any lanes this call DID claim: a failed batch must hold nothing (all-or-nothing)
+      for (const p of paths) {
+        const r = rel(p), lock = readLock(key(r));
+        if (lock && lock.by === by && !held.some(h => h.startsWith(r + ' '))) {
+          try { fs.unlinkSync(path.join(LANE, key(r))); } catch { /* gone */ }
+          journal('rollback', by, r, 'batch failed — released');
+        }
+      }
+      process.exit(1);
+    }
+  } else if (cmd === 'check') {
+    if (!paths.length) { console.error('check needs at least one path'); process.exit(2); }
+    let blocked = false;
+    for (const p of paths) {
+      const r = rel(p), lock = readLock(key(r));
+      if (lock) { blocked = true; console.log('TAKEN  ' + r + '  by ' + lock.by + ' (since ' + (lock.at || '?') + ', ' + ageMin(lock.ts) + 'm' + (lock.why ? ', ' + lock.why : '') + ')'); }
+      else console.log('CLEAR  ' + r);
+    }
+    process.exit(blocked ? 1 : 0);
+  } else if (cmd === 'release') {
+    const by = flag('by');
+    if (!by) { console.error('release needs --by <name>'); process.exit(2); }
+    const targets = has('all')
+      ? fs.readdirSync(LANE).filter(f => f.endsWith('.json')).map(f => readLock(f)).filter(Boolean).map(l => l.path)
+      : paths.map(rel);
+    if (!targets.length) { console.log('nothing to release'); return; }
+    for (const r of targets) {
+      const lock = readLock(key(r));
+      if (!lock) { console.log('FREE    ' + r + '  (was not locked)'); continue; }
+      if (lock.by !== by && !has('force')) {
+        journal('refuse', by, r, 'held by ' + lock.by);
+        console.error('REFUSE  ' + r + '  held by ' + lock.by + ' (use --force to break)'); process.exitCode = 1; continue;
+      }
+      fs.unlinkSync(path.join(LANE, key(r)));
+      journal(lock.by !== by ? 'force-break' : 'release', by, r, lock.by !== by ? 'broke ' + lock.by + "'s lock (held since " + (lock.at || '?') + ')' : null);
+      console.log('RELEASED ' + r + '  @ ' + iso() + (lock.by !== by ? '  (force-broken from ' + lock.by + ')' : ''));
+    }
+  } else if (cmd === 'list') {
+    const files = fs.readdirSync(LANE).filter(f => f.endsWith('.json'));
+    if (!files.length) { console.log('no lanes held — the road is open'); return; }
+    for (const f of files) {
+      const l = readLock(f);
+      if (l) console.log(l.path + '  by ' + l.by + '  since ' + (l.at || '?') + ' (' + ageMin(l.ts) + 'm)' + (l.why ? '  — ' + l.why : ''));
+    }
+  } else if (cmd === 'log') {
+    if (!fs.existsSync(JOURNAL)) { console.log('journal is empty — nothing has happened yet'); return; }
+    const lines = fs.readFileSync(JOURNAL, 'utf8').split('\n').filter(Boolean);
+    const last = Number(flag('last', 0)) || 0;
+    const show = last > 0 ? lines.slice(-last) : lines;
+    for (const line of show) {
+      let e; try { e = JSON.parse(line); } catch { continue; }
+      console.log(e.ts + '  ' + String(e.act).padEnd(11) + ' ' + (e.by || '?').padEnd(12) + (e.path ? ' ' + e.path : '') + (e.detail ? '  — ' + e.detail : ''));
+    }
+  } else if (cmd === 'clear-stale') {
+    const hours = Number(flag('hours', 6));
+    const cutoff = Date.now() - hours * 3600000;
+    let n = 0;
+    for (const f of fs.readdirSync(LANE).filter(f => f.endsWith('.json'))) {
+      const l = readLock(f);
+      if (l && l.ts < cutoff) {
+        fs.unlinkSync(path.join(LANE, f)); n++;
+        journal('stale-sweep', '(sweeper)', l.path, 'was ' + l.by + ', held since ' + (l.at || '?'));
+        console.log('STALE   ' + l.path + '  (was ' + l.by + ', ' + ageMin(l.ts) + 'm)');
+      }
+    }
+    if (!n) console.log('no stale lanes (older than ' + hours + 'h)');
+  } else {
+    console.log('usage: node tools/lane.js <claim|check|release|list|log|clear-stale> [paths...] [--by name] [--why text] [--all] [--force] [--hours N] [--last N]');
+    process.exit(2);
+  }
+}
+
+main();