luciazero 2.4.2 → 2.5.0

package/README.md

@@ -2,29 +2,68 @@
   <img src="https://cdn.jsdelivr.net/gh/ohm41321/luciazero@37cb470e2b7c704ff32f3a46dbb125e312875960/docs/assets/lucia.png" width="220" alt="Lucia — Luciazero's mascot">
   <h1>Luciazero</h1>
   <p>
-    <strong>Evidence-first discipline for coding agents.</strong><br>
+    <strong>Make coding agents prove their work.</strong><br>
     <code>plan → change → verify → fix</code>
   </p>
   <p>
     <a href="https://www.npmjs.com/package/luciazero"><img src="https://img.shields.io/npm/v/luciazero" alt="npm version"></a>
+    <a href="https://www.npmjs.com/package/luciazero"><img src="https://img.shields.io/npm/dw/luciazero" alt="npm weekly downloads"></a>
     <a href="https://github.com/ohm41321/luciazero/actions/workflows/ci.yml"><img src="https://github.com/ohm41321/luciazero/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
+    <a href="https://github.com/ohm41321/luciazero/stargazers"><img src="https://img.shields.io/github/stars/ohm41321/luciazero?style=flat" alt="GitHub stars"></a>
+    <a href="https://github.com/ohm41321/luciazero/network/members"><img src="https://img.shields.io/github/forks/ohm41321/luciazero?style=flat" alt="GitHub forks"></a>
     <a href="https://github.com/ohm41321/luciazero/blob/main/LICENSE"><img src="https://img.shields.io/github/license/ohm41321/luciazero" alt="MIT license"></a>
   </p>
 </div>
 
 **English** · [ภาษาไทย](https://github.com/ohm41321/luciazero/blob/main/README.th.md)
 
-Luciazero is a lightweight discipline layer for coding agents. It works with
-Claude Code, Codex CLI, and compatible skill runtimes through plugin, CLI, or
-skills-only installs.
+<p align="center">
+  <strong>13 skills</strong> · <strong>Relay fixture 6/6</strong> · <strong>Claude + Codex</strong> · <strong>MIT</strong>
+</p>
+<p align="center"><sub>Relay 6/6 is a mechanical protocol check; behavioral results are reported separately.</sub></p>
+
+Luciazero is the verification and handoff layer for Claude Code, Codex CLI, and
+compatible skill runtimes. It helps agents prove tests, preserve scope, and
+move unfinished work with evidence.
 
 > Done is proven by a command, not by my judgment. If no verification command
 > exists, that is the first bug.
 
-It ships a compact [9-rule doctrine](https://github.com/ohm41321/luciazero/blob/main/claude/luciazero.md), 11 on-demand skills,
-verification hooks, a risk-routed reviewer, and an eval harness. It is designed
-to make completion claims auditable—not to replace an agent runtime or become an
-overnight orchestrator.
+Luciazero is for teams that want coding agents to prove work instead of merely
+report it. It helps prevent false-green verification and dropped scope,
+preserves lessons from repeated dead ends, and carries context across handoffs
+when `/lucia-relay` is used. It is a discipline layer, not an agent runtime.
+
+## Start in 30 seconds
+
+Choose the path that matches your agent, then start a new session:
+
+**Claude Code · full pack**
+
+```text
+/plugin marketplace add ohm41321/luciazero
+/plugin install luciazero@luciazero
+```
+
+Run `/luciazero:ready` in the new session.
+
+**Codex CLI · doctrine + skills**
+
+```bash
+npx luciazero codex
+```
+
+Run `$ready` in the new session.
+
+**Skills-only · any compatible agent**
+
+```bash
+npx skills add ohm41321/luciazero
+```
+
+Invoke the installed `ready` skill using your agent's syntax (for Codex CLI,
+use `$ready`). This path intentionally does not install the doctrine, reviewer,
+or hooks.
 
 ## See the loop
 
@@ -40,6 +79,65 @@ This GIF is driven by the shipped hooks, not a mockup:
 ✅ verify 3m   → the latest check passed three minutes ago
 ```
 
+Run the same shipped hook driver locally—no model or API is required:
+
+```bash
+bash docs/assets/statusline-demo.sh
+```
+
+For the cross-session handoff demo:
+
+```bash
+bash docs/assets/relay-demo.sh
+```
+
+Both scripts use throwaway directories and exercise the real implementation.
+
+## Let two agents hand work to each other
+
+**Agent Bus is beta, opt-in, and checkout only.** It does not come with
+`npx luciazero` and never starts during a normal npm, plugin, or skills-only
+install. After the one-time checkout setup, the ordinary path is one command
+in each agent window:
+
+```text
+window A                              window B
+$ lucia claude                       $ lucia codex
+
+task_create + message_send  ───────► queued durably in the local bus
+                             nudge ─► check your bus inbox (1 new task from claude)
+                                      message_ack + task_claim
+                                      work + verify
+                                      artifact_publish + task_complete
+result in the inbox          ◄─────── message_send
+```
+
+The daemon starts when the first `lucia` session needs it, each CLI receives
+an MCP configuration for that run only, and the user's central Claude or
+Codex configuration is not edited. Messages and task state stay in local
+SQLite; peer message text is never typed into another session's prompt. The
+proxy types only the daemon-built inbox notice after the provider is quiet.
+
+Try the shipped fake-provider demo—no model, login, or quota required:
+
+```bash
+bash docs/assets/agent-bus-demo.sh
+```
+
+To open real Claude Code and Codex sessions, first follow the one-time
+[checkout setup](docs/agent-bus.md#start-here), then run `lucia claude` and
+`lucia codex`. See the [Agent Bus guide](docs/agent-bus.md) for worktree
+ownership, `--no-nudge`, security boundaries, and cleanup.
+
+Inside the Bus workflow, the skill stops before risky work: delete, deploy,
+production access, spending, force-push, public-contract changes, and scope
+expansion need a single-use nonce you mint in your own terminal. No bus tool
+can create one, and a nonce put into a bus message, task, or artifact is
+scrubbed or refused ([approvals](docs/agent-bus.md#approvals)). This records
+approval provenance; it is not a host sandbox against another process running
+as you. The project trust boundary is in
+[SECURITY.md](https://github.com/ohm41321/luciazero/blob/main/SECURITY.md).
+
 ## What it protects
 
 | Failure mode | Mechanism |
@@ -110,7 +208,7 @@ cannot set one.
 npx skills add ohm41321/luciazero
 ```
 
-This installs the 11 skills: no doctrine, reviewer, or hooks.
+This installs the 13 skills: no doctrine, reviewer, or hooks.
 
 </details>
 
@@ -151,11 +249,13 @@ Other install channels use their own updater:
 
 ```bash
 claude plugin update luciazero@luciazero   # then run /reload-plugins
-npx skills update                          # review the scope prompt
+npx skills update                          # every installed skill in the selected scope
+npx skills update done -g                 # only the global "done" skill
 ```
 
 The skills command updates every installed skill in the selected scope, not
-only Luciazero; review its prompt before confirming.
+only Luciazero; review its prompt before confirming. Use the targeted form when
+you only want to refresh one skill.
 
 Claude Code can auto-update the plugin at startup: open `/plugin` →
 **Marketplaces** → **luciazero** → **Enable auto-update**. Third-party
@@ -164,7 +264,8 @@ GitHub **Watch → Custom → Releases**.
 
 ## Skills at a glance
 
-Run `/ready` first; the rest activate when their moment arrives.
+Invoke `ready` first (`/ready` for slash-based agents, `$ready` in Codex); the
+rest activate when their moment arrives.
 
 | Moment | Skill | Result |
 |---|---|---|
@@ -176,6 +277,8 @@ Run `/ready` first; the rest activate when their moment arrives.
 | Good and bad revisions are known | `/bisect` | Finds the first bad commit in a temporary worktree |
 | Before claiming completion | `/done` | Full verify, skeptic review, scope report |
 | Work must move elsewhere | `/lucia-relay` | Portable JSON + Markdown state with drift inspection |
+| Another agent's work is queued for you (beta) | `/lucia-bus` | Register, read the inbox, claim, work, publish the result through the local Agent Bus ([setup and demo](docs/agent-bus.md)) |
+| Want two agent sessions talking (beta) | `/lucia-chat` | Shows what is waiting, opens one window per agent, and optionally watches the conversation |
 | Optimizing performance | `/experiment` | Baseline, threshold, controlled measurement |
 | Reviewing local verify habits | `/discipline-report` | Time/project-filtered local outcome report |
 | After difficult work | `/retro` | Stores reusable lessons and disproved approaches |
@@ -191,21 +294,31 @@ separate passes.
 
 ## Evidence & limitations
 
+The measurements below are early and model/task-specific. The linked raw rows
+and methodology are the source of truth; they are not a promise of uplift on
+every repository or model.
+
 <!-- BEGIN GENERATED: benchmark-evidence -->
 
 ### Claude results
 
-Snapshot: 2026-08-11. All-criteria pass rate generated from checked-in raw rows:
+Snapshots: 2026-08-11 for Haiku and the Sonnet pilot, 2026-09-02 for Sonnet.
+All-criteria pass rate generated from checked-in raw rows:
 
-| Claude model | Luciazero | Bare | Difference |
-|---|---:|---:|---:|
-| Haiku†, 10 valid/task | 36/60 (60%) | 27/60 (45%) | +15pp |
-| Sonnet, 4–5 valid/task* | 25/27 (93%) | 16/26 (62%) | +31pp |
+| Claude model | Tasks | Luciazero | Bare | Difference |
+|---|---:|---:|---:|---:|
+| Haiku†, 10 valid/task | 6 | 36/60 (60%) | 27/60 (45%) | +15pp |
+| Sonnet (2026-08-11 pilot), 4–5 valid/task* | 6 | 25/27 (93%) | 16/26 (62%) | +31pp |
+| Sonnet, 5 valid/task | 10 | 39/50 (78%) | 23/50 (46%) | +32pp |
 
 The `Luciazero` arm installs the classic pack without hooks; it is not a clean
-doctrine-only ablation. *Sonnet is preliminary because eight invalid rows leave
-several arms at four valid runs. The previously stated `+37pp` top-up is retired
-because its replacement raw rows could not be recovered.
+doctrine-only ablation. Rows are not like-for-like: the 2026-09-02 Sonnet
+campaign adds four harder tasks that the 2026-08-11 campaigns never ran, so
+compare each row against its own bare arm rather than across models.
+*The Sonnet pilot stays preliminary because eight invalid rows leave several
+arms at four valid runs; the 2026-09-02 campaign supersedes it with five valid
+runs in every cell and no invalid rows. The previously stated `+37pp` top-up
+remains retired because its replacement raw rows could not be recovered.
 
 †Model provenance is incomplete for Haiku: only 70/140 rows encode model
 identity. The other 70 are attributed at campaign-file/report level and
@@ -232,6 +345,12 @@ only one run per arm per task. See the [full benchmark](https://github.com/ohm41
 - Node.js 18+ for the CLI and discipline report.
 - Bash for classic installers; Python 3.9+ for hooks and Lucia Relay
   (`install.sh --with-hooks` refuses anything older).
+- The Agent Bus daemon (beta, opt-in) needs Python 3.10+ and a checkout: it is
+  not in the npm payload and `npx luciazero` never starts it. From a checkout,
+  `./install.sh` adds the `luciazero-agentd` launcher to `~/.claude/bin`
+  (`LUCIAZERO_BIN_DIR` chooses another directory), and
+  `luciazero-agentd service install` runs the daemon under launchd or systemd
+  `--user`. macOS, Linux and WSL2 only. See [docs/agent-bus.md](docs/agent-bus.md).
 - Core installers, hooks, helpers, and graders are offline. Real behavioral
   evals invoke a model CLI and consume API credit or subscription quota.
 - Hooks run commands on your machine. Read them before enabling them.
@@ -273,6 +392,7 @@ More detail:
 - [Benchmark results and GPT plan](https://github.com/ohm41321/luciazero/blob/main/docs/benchmark.md)
 - [Raw campaign registry](https://github.com/ohm41321/luciazero/blob/main/eval/results/campaigns.json)
 - [Experiment log](https://github.com/ohm41321/luciazero/blob/main/docs/experiments.md)
+- [Launch kit](https://github.com/ohm41321/luciazero/blob/main/docs/launch-kit.md)
 - [Contributing](https://github.com/ohm41321/luciazero/blob/main/CONTRIBUTING.md)
 - [Publishing](https://github.com/ohm41321/luciazero/blob/main/docs/publishing.md)
 - [Changelog](https://github.com/ohm41321/luciazero/blob/main/CHANGELOG.md)

package/bin/bus.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+// `npx luciazero bus status [--json]`: show what is waiting on whom in the
+// local Agent Bus. Talks to the running luciazero-agentd over loopback with
+// the capability token; never starts a daemon and works without one
+// installed (it just reports that none is running).
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+function stateDir() {
+  const env = process.env.LUCIAZERO_AGENT_BUS_HOME;
+  return env ? env : path.join(os.homedir(), ".luciazero", "agent-bus");
+}
+
+// Peer-supplied strings never reach the terminal unfiltered.
+const clean = (value) => String(value).replace(/[\x00-\x1f\x7f-\x9f]/g, "?");
+
+function usage(code) {
+  const out = code === 0 ? console.log : console.error;
+  out("usage: luciazero bus status [--json]");
+  out("  Reads endpoint.json and token from " + stateDir() + " (LUCIAZERO_AGENT_BUS_HOME).");
+  process.exit(code);
+}
+
+async function status(json) {
+  const dir = stateDir();
+  let endpoint;
+  try {
+    endpoint = JSON.parse(fs.readFileSync(path.join(dir, "endpoint.json"), "utf8"));
+  } catch (err) {
+    console.error(`luciazero bus: no running daemon recorded in ${dir}`);
+    console.error("  the bus is an opt-in beta that ships only in a checkout, not with npx luciazero:");
+    console.error("  clone https://github.com/ohm41321/luciazero, run ./install.sh, then: lucia claude");
+    process.exit(2);
+  }
+  let token;
+  try {
+    token = fs.readFileSync(path.join(dir, "token"), "utf8").trim();
+  } catch (err) {
+    console.error(`luciazero bus: cannot read the capability token in ${dir}`);
+    process.exit(2);
+  }
+  const base = endpoint.url.replace(/\/mcp$/, "");
+  let response;
+  try {
+    response = await fetch(base + "/status", { headers: { Authorization: `Bearer ${token}` } });
+  } catch (err) {
+    console.error(`luciazero bus: daemon at ${endpoint.url} is not answering (${err.message})`);
+    process.exit(2);
+  }
+  if (!response.ok) {
+    console.error(`luciazero bus: daemon answered HTTP ${response.status}`);
+    process.exit(2);
+  }
+  const body = await response.json();
+  if (json) {
+    console.log(JSON.stringify(body, null, 2));
+    return;
+  }
+  const tasks = Object.entries(body.tasks).map(([k, v]) => `${clean(k)} ${Number(v)}`).join(", ");
+  console.log(`agent bus: ${clean(body.server.name)} ${clean(body.server.version)} since ${clean(body.server.started_at)}`);
+  console.log(`queued deliveries: ${Number(body.queued_deliveries)}   tasks: ${tasks}`);
+  for (const agent of body.agents) {
+    const wt = agent.worktree;
+    const where = wt ? `  on ${clean(wt.branch)}${wt.dirty ? " (dirty)" : ""}` : "";
+    // ADR 0004: an agent with no terminal binding says so on its own line.
+    const who = agent.binding ? `  ${clean(agent.binding.tty || "no tty")}` : "  unverified";
+    console.log(
+      `  ${clean(agent.id).padEnd(24)} ${clean(agent.provider).padEnd(7)} ${clean(agent.role).padEnd(14)} ` +
+      `inbox ${String(Number(agent.queued_deliveries)).padStart(3)}  claimed ${String(Number(agent.claimed_tasks)).padStart(3)}  seen ${clean(agent.last_seen_at)}${where}${who}`
+    );
+  }
+  for (const task of body.open_tasks) {
+    const needs = task.requires_worktree ? "  needs worktree" : "";
+    console.log(`  open task ${clean(task.id)}  p${Number(task.priority)}  ${clean(task.assigned_to || "unassigned")}: ${clean(task.title)}${needs}`);
+  }
+  const workers = Array.isArray(body.workers) ? body.workers : [];
+  for (const worker of workers) {
+    console.log(`  managed worker ${clean(worker.agent_id).padEnd(20)} ${clean(worker.provider).padEnd(7)} ${worker.enabled ? "enabled" : "paused"}`);
+  }
+  const running = Array.isArray(body.running_runs) ? body.running_runs : [];
+  for (const run of running) {
+    console.log(`  turn running    ${clean(run.agent_id).padEnd(20)} attempt ${Number(run.attempt)}  since ${clean(run.started_at)}`);
+  }
+  const stopped = Array.isArray(body.stopped_tasks) ? body.stopped_tasks : [];
+  for (const task of stopped) {
+    console.log(`  stopped task ${clean(task.id)}  spent its ${clean(task.dimension || "budget")} budget: ${clean(task.title)}`);
+  }
+  const unverified = Array.isArray(body.unverified_agents) ? body.unverified_agents : [];
+  if (unverified.length > 0) {
+    console.log(
+      `unverified: ${unverified.map(clean).join(", ")} (no terminal binding; these sessions act as whoever they claim to be)`
+    );
+  }
+  if (Number(body.approvals_pending) > 0) {
+    console.log(`approvals pending: ${Number(body.approvals_pending)} (unused nonces; each is bound to one task and operation)`);
+  }
+  if (body.queued_deliveries > 0 || body.tasks.open > 0) {
+    console.log("next: start the agent's session and run /lucia-bus (Codex: $lucia-bus)");
+  }
+}
+
+const args = process.argv.slice(2);
+if (args.length === 0 || args[0] === "--help" || args[0] === "-h") usage(args.length === 0 ? 64 : 0);
+if (args[0] !== "status") {
+  console.error(`luciazero bus: unknown subcommand '${args[0]}'`);
+  usage(64);
+}
+const extra = args.slice(1).filter((a) => a !== "--json");
+if (extra.length > 0) {
+  console.error(`luciazero bus: unknown option '${extra[0]}'`);
+  usage(64);
+}
+if (typeof fetch !== "function") {
+  console.error("luciazero bus: needs Node 18+ (global fetch)");
+  process.exit(1);
+}
+status(args.includes("--json")).catch((err) => {
+  console.error("luciazero bus: " + err.message);
+  process.exit(1);
+});

package/bin/luciazero-agentd

@@ -0,0 +1,107 @@
+#!/bin/sh
+# luciazero-agentd -- run the Agent Bus daemon from anywhere.
+# lucia -- the same program under a shorter name, installed as a second copy.
+#
+# luciazero-managed: agentd-launcher
+#
+# The daemon is a Python package that is neither on PATH nor pip-installed: it
+# lives in `agentd/` inside a checkout (ADR 0002 keeps it out of the npm
+# payload). This shim finds it from where the shim itself is, never from the
+# caller's working directory -- the working directory is meaningful to the
+# daemon, since `attach` records it as the session's, so this must not change
+# it the way `cd agentd && python3 -m luciazero_agentd` did.
+set -eu
+
+fail() { printf 'luciazero-agentd: %s\n' "$*" >&2; exit 127; }
+
+# Resolve this script through any symlinks. `readlink -f` is GNU-only, so the
+# loop is hand-rolled; every expansion is quoted, so a path with spaces (and
+# an installed copy reached through a symlink) resolves correctly.
+# The name typed, before any symlink is followed: `lucia` and
+# `luciazero-agentd` are one program, and only the messages that tell the user
+# what to type next need to know which name they are speaking under.
+argv0="$(basename "$0")"
+self="$0"
+hops=0
+while [ -L "$self" ]; do
+  hops=$((hops + 1))
+  [ "$hops" -le 40 ] || fail "symlink loop while resolving $0"
+  target="$(readlink "$self")"
+  case "$target" in
+    /*) self="$target" ;;
+    *) self="$(dirname "$self")/$target" ;;
+  esac
+done
+here="$(cd "$(dirname "$self")" && pwd -P)"
+
+config_dir="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
+home_file="${config_dir}/.luciazero-agentd-home"
+
+# Checkout layout wins over the recorded one: running `bin/luciazero-agentd`
+# out of a second clone must use that clone, not whichever one was installed.
+package_home=""
+if [ -n "${LUCIAZERO_AGENTD_HOME:-}" ]; then
+  package_home="${LUCIAZERO_AGENTD_HOME}"
+elif [ -d "${here}/../agentd/luciazero_agentd" ]; then
+  package_home="$(cd "${here}/.." && pwd -P)/agentd"
+elif [ -f "${home_file}" ]; then
+  package_home="$(cat "${home_file}")"
+fi
+
+if [ -z "${package_home}" ]; then
+  fail "cannot find the luciazero_agentd package.
+  It ships in a checkout of https://github.com/ohm41321/luciazero, not in the
+  npm package. Clone it and run ./install.sh from the checkout, or point
+  LUCIAZERO_AGENTD_HOME at its agentd/ directory."
+fi
+case "${package_home}" in
+  *"
+"*) fail "the package path contains a newline: ${package_home}" ;;
+esac
+if [ ! -d "${package_home}/luciazero_agentd" ]; then
+  fail "no luciazero_agentd package in ${package_home} (moved or deleted checkout?).
+  Re-run ./install.sh from the checkout, or set LUCIAZERO_AGENTD_HOME."
+fi
+
+# ADR 0002: try python3, then python, then the Windows launcher, and take the
+# first one that reports 3.10 or newer. A wrong pick here is worse than none:
+# the daemon would fail deep inside the package instead of at the door.
+usable() {
+  "$@" -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 10) else 1)' >/dev/null 2>&1
+}
+python=""
+for candidate in python3 python; do
+  if command -v "${candidate}" >/dev/null 2>&1 && usable "${candidate}"; then
+    python="${candidate}"
+    break
+  fi
+done
+if [ -z "${python}" ] && command -v py >/dev/null 2>&1 && usable py -3; then
+  python="py -3"
+fi
+[ -n "${python}" ] || fail "needs Python 3.10 or newer; tried python3, python and py -3"
+
+# The package path travels in an environment variable and is put on sys.path
+# by the interpreter itself. Two things this avoids, both of which let code
+# from the caller's working directory run instead of the daemon:
+#
+#   * PYTHONPATH is colon-separated, so a checkout at a path containing ":"
+#     would split into two entries, the tail of which resolves relative to the
+#     caller's directory.
+#   * `python -m pkg` puts the working directory FIRST on sys.path, ahead of
+#     PYTHONPATH, so a directory named luciazero_agentd next to the caller
+#     would shadow the real package.
+#
+# The variable is popped before the daemon does anything, so no provider
+# subprocess inherits it, and the -c program below is a fixed literal: nothing
+# a caller supplies is ever parsed as code.
+LUCIAZERO_AGENTD_PACKAGE="${package_home}"
+export LUCIAZERO_AGENTD_PACKAGE
+LUCIAZERO_ARGV0="${argv0}"
+export LUCIAZERO_ARGV0
+# ${python} is unquoted on purpose -- "py -3" is two words. The value is one of
+# this script's own literals, never anything a caller supplied.
+exec ${python} -c 'import os, sys, runpy
+sys.path = [entry for entry in sys.path if entry not in ("", ".", os.getcwd())]
+sys.path.insert(0, os.environ.pop("LUCIAZERO_AGENTD_PACKAGE"))
+runpy.run_module("luciazero_agentd", run_name="__main__", alter_sys=True)' "$@"

package/bin/luciazero.js

@@ -9,6 +9,7 @@
 //   npx luciazero discipline [options]       -> local stats report
 //   npx luciazero check-update [--json]       -> explicit npm version check
 //   npx luciazero update                      -> update detected classic installs
+//   npx luciazero bus status [--json]         -> Agent Bus queue summary (beta)
 const { spawnSync } = require("node:child_process");
 const path = require("node:path");
 
@@ -20,6 +21,7 @@ const ROUTES = {
   discipline: { runtime: process.execPath, script: "bin/discipline-report.js" },
   "check-update": { runtime: process.execPath, script: "bin/update.js", args: ["check"] },
   update: { runtime: process.execPath, script: "bin/update.js", args: ["update"] },
+  bus: { runtime: process.execPath, script: "bin/bus.js" },
 };
 
 const args = process.argv.slice(2);
@@ -28,7 +30,7 @@ if (args[0] && !args[0].startsWith("-")) {
   if (!Object.prototype.hasOwnProperty.call(ROUTES, args[0])) {
     console.error(
       `luciazero: unknown command '${args[0]}' ` +
-      "(install, codex, discipline, check-update, update, uninstall, uninstall-codex)"
+      "(install, codex, discipline, check-update, update, bus, uninstall, uninstall-codex)"
     );
     process.exit(64);
   }

package/install-codex.sh

@@ -19,6 +19,9 @@ CODEX_DIR="${CODEX_HOME:-$HOME/.codex}"
 AGENTS_MD="${CODEX_DIR}/AGENTS.md"
 START='<!-- luciazero:start -->'
 END='<!-- luciazero:end -->'
+# written inside the block, under the start marker, when the install had to add
+# a final newline to the user's content to make room for that marker
+ADDED_NL_MARK='<!-- luciazero:added-final-newline -->'
 MANAGED_DIR="${CODEX_DIR}/.luciazero-managed"
 BACKUP_DIR="${CODEX_DIR}/.luciazero-backups"
 
@@ -32,11 +35,18 @@ version_of() {
     "${SRC}/package.json" 2>/dev/null || true
 }
 
-# collision-proof backup path for $1 (two runs in the same second must not overwrite)
+# A free backup name for $1. Two runs in the same second must not overwrite
+# each other, and a name a symlink already holds is taken too: `-e` follows
+# the name and answers false for a symlink whose target is missing, which
+# would send the `cp` below straight through that symlink and out of the
+# config directory. This is a check, not a reservation -- the name is still
+# free to be taken between the test and the `cp` (roadmap R24). The
+# uninstaller's settings backup reserves its name with `O_CREAT | O_EXCL`
+# instead, which the shell has no portable equivalent for.
 bakpath() {
   B="$1.bak.$(date +%Y%m%d%H%M%S)"
   N=1
-  while [ -e "${B}" ]; do B="$1.bak.$(date +%Y%m%d%H%M%S).${N}"; N=$((N+1)); done
+  while [ -e "${B}" ] || [ -L "${B}" ]; do B="$1.bak.$(date +%Y%m%d%H%M%S).${N}"; N=$((N+1)); done
   printf '%s' "${B}"
 }
 
@@ -90,26 +100,108 @@ remove_legacy_tree() {
   fi
 }
 
+# Does $1 end in a newline? A last line without one is content like any other,
+# and `awk` cannot pass it through: print terminates every record it writes, so
+# a rewrite that goes through awk hands such a file back one byte longer.
+ends_with_newline() {
+  [ -s "$1" ] && [ -z "$(tail -c 1 "$1")" ]
+}
+
+# Write $1 with its marker block removed and every other byte kept, including a
+# last line that carries no newline.
+#
+# The newline directly above the start marker is removed with the block when
+# the block says the installer put it there. The install has to: a start marker
+# only counts on a line of its own, so a file whose last line was unterminated
+# needs one before the block can be appended. That newline is the installer's,
+# not the user's, and nothing in the finished file distinguishes it from a
+# newline the user typed -- so the installer records it, on the line under the
+# start marker, where the markers are its provenance exactly as they are the
+# blank line's. The record is honoured only while the block is still the last
+# thing in the file, which is where the install put it; a user who has moved
+# the block since has moved that newline into the middle of their own text,
+# where it is no longer provably ours and stays.
+strip_marker_block() {
+  if ends_with_newline "$1"; then SMB_SRC_NL=1; else SMB_SRC_NL=0; fi
+  awk -v s="${START}" -v e="${END}" -v mark="${ADDED_NL_MARK}" -v srcnl="${SMB_SRC_NL}" '
+    $0==s {inblock=1; head=1; blockend=NR; next}
+    $0==e {inblock=0; blockend=NR; next}
+    inblock {if (head && $0==mark) added=1; head=0; blockend=NR; next}
+    {n++; keep[n]=$0; lastkept=NR}
+    END {
+      chop = (added && n > 0 && blockend == NR)
+      for (i = 1; i <= n; i++) {
+        printf "%s", keep[i]
+        if (i < n) printf "\n"
+      }
+      if (n > 0 && !chop && !(lastkept == NR && srcnl == 0)) printf "\n"
+    }
+  ' "$1"
+}
+
+# Exactly one well-formed marker pair, or none at all. Anything else — a start
+# with no end, a second pair, a pair nested inside another — has no defined
+# meaning, and the awk rewrites below would answer it by dropping whatever
+# follows the opening marker. AGENTS.md is the user's file; an ambiguous one is
+# left exactly as it is, down to the byte, rather than repaired by guesswork.
+# Markers count only on a line of their own, which is what the rewrites match.
+marker_block_ok() {
+  MB_FILE="$1"
+  [ -f "${MB_FILE}" ] || return 0
+  MB_S="$(grep -cxF "${START}" "${MB_FILE}" || true)"
+  MB_E="$(grep -cxF "${END}" "${MB_FILE}" || true)"
+  [ "${MB_S}" = 0 ] && [ "${MB_E}" = 0 ] && return 0
+  if [ "${MB_S}" = 1 ] && [ "${MB_E}" = 1 ]; then
+    MB_SL="$(grep -nxF "${START}" "${MB_FILE}" | cut -d: -f1)"
+    MB_EL="$(grep -nxF "${END}" "${MB_FILE}" | cut -d: -f1)"
+    [ "${MB_SL}" -lt "${MB_EL}" ] && return 0
+  fi
+  return 1
+}
+
+if ! marker_block_ok "${AGENTS_MD}"; then
+  echo "AGENTS.md carries ambiguous Luciazero markers; nothing was installed" >&2
+  echo "  expected exactly one '${START}' ... '${END}' pair, on their own lines" >&2
+  echo "  fix ${AGENTS_MD} and run this again" >&2
+  exit 1
+fi
+
 echo "Installing into ${CODEX_DIR}"
 mkdir -p "${CODEX_DIR}/skills"
 
 # 1. doctrine as a marker block in global AGENTS.md (replaced in place on reinstall)
+#
+# This rewrite and the uninstaller's are exact inverses: it strips the marker
+# block and nothing else, and appends the block back with no separator of its
+# own. That is the whole of what makes a full cycle return AGENTS.md to its
+# original bytes.
+#
+# It used to write a blank separator above the start marker, and then trim
+# trailing blank lines here so that separator would not accumulate one line
+# per reinstall. The trim could not tell a blank line this installer had added
+# from one the user wrote, so it spent theirs to pay for ours: a file ending in
+# no blank line came back from a cycle one line longer, and one ending in
+# several came back shorter. The blank line that keeps the doctrine readable
+# now lives INSIDE the block, under the start marker, where the markers are its
+# provenance and the uninstaller takes it away without having to guess. The
+# newline this installer has to add to an unterminated last line is recorded in
+# the same place, for the same reason.
 TMP="$(mktemp)"
 if [ -f "${AGENTS_MD}" ]; then
   cp "${AGENTS_MD}" "$(bakpath "${AGENTS_MD}")"
-  # strip the old block AND trailing blank lines, so reinstalls do not
-  # accumulate one separator blank line per run
-  awk -v s="${START}" -v e="${END}" '
-    $0==s {inblock=1; next}
-    $0==e {inblock=0; next}
-    inblock {next}
-    NF {for (i=0; i<blank; i++) print ""; blank=0; print; next}
-    {blank++}
-  ' "${AGENTS_MD}" > "${TMP}"
+  strip_marker_block "${AGENTS_MD}" > "${TMP}"
 fi
+# A start marker counts only on a line of its own, so content whose last line
+# has no newline needs one before the block can follow it. That newline is the
+# only byte of the user's file this installer changes, and it is recorded under
+# the start marker so the uninstall takes it back with the block.
+if [ -s "${TMP}" ] && ! ends_with_newline "${TMP}"; then ADDED_NL=1; else ADDED_NL=0; fi
 {
-  if [ -s "${TMP}" ]; then cat "${TMP}"; echo; fi
+  if [ -s "${TMP}" ]; then cat "${TMP}"; fi
+  if [ "${ADDED_NL}" = 1 ]; then printf '\n'; fi
   echo "${START}"
+  if [ "${ADDED_NL}" = 1 ]; then echo "${ADDED_NL_MARK}"; fi
+  echo
   cat "${SRC}/claude/luciazero.md"
   echo "${END}"
 } > "${AGENTS_MD}"