luciazero 2.4.3 → 2.5.1

package/README.md

@@ -18,7 +18,7 @@
 **English** · [ภาษาไทย](https://github.com/ohm41321/luciazero/blob/main/README.th.md)
 
 <p align="center">
-  <strong>11 skills</strong> · <strong>Relay fixture 6/6</strong> · <strong>Claude + Codex</strong> · <strong>MIT</strong>
+  <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>
 
@@ -93,6 +93,51 @@ 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 |
@@ -163,22 +208,38 @@ 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>
 
 <details>
 <summary><strong>Classic install · Claude Code or Codex CLI</strong></summary>
 
+Install the command globally once, without `sudo`:
+
 ```bash
-npx luciazero                 # Claude Code
-npx luciazero --with-hooks    # Claude Code + hooks/statusline; needs Python 3.9+
-npx luciazero codex           # Codex CLI
+npx luciazero@latest global-install
+```
 
-npx luciazero uninstall
-npx luciazero uninstall-codex
+This installs the CLI under `~/.local/npm` and, after confirmation, adds its
+bin directory to your zsh or bash PATH. Start a new shell, then use the global
+command from any directory:
+
+```bash
+luciazero                 # Claude Code
+luciazero --with-hooks    # Claude Code + hooks/statusline; needs Python 3.9+
+luciazero codex           # Codex CLI
+
+luciazero uninstall             # remove the Claude classic files
+luciazero uninstall-codex       # remove the Codex classic files
+luciazero global-status         # check the global command and PATH
+luciazero global-uninstall      # remove the command and its exact PATH block
 ```
 
+For a one-off install without keeping the command, `npx luciazero@latest`
+continues to work. Automation may pass `global-install --yes`; interactive use
+asks before installing the package and changing a shell startup file.
+
 Pick either plugin or classic for Claude Code so hooks are not wired twice.
 Classic installs support `--status`; Codex receives the doctrine and skills but
 not Claude-only hooks/statusline. Installers back up name collisions and remove
@@ -191,10 +252,13 @@ only exact Luciazero-managed copies on uninstall.
 Luciazero never changes classic or Codex files in the background.
 
 ```bash
-npx luciazero@latest check-update   # read-only; contacts npm only now
-npx luciazero@latest update         # updates every detected classic/Codex install
+luciazero check-update   # read-only; contacts npm only now
+luciazero update         # updates every detected classic/Codex install
 ```
 
+If you chose the one-off path, use the same commands through
+`npx luciazero@latest` instead.
+
 `update` preserves whether the Claude classic install uses hooks, repairs stale
 managed files, starts no fresh install when it cannot find one, and stops on a
 known newer version or malformed version metadata. Start a new agent session
@@ -232,6 +296,8 @@ 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 |
@@ -255,17 +321,23 @@ every repository or model.
 
 ### 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
@@ -292,6 +364,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.

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/global.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const readline = require("node:readline");
+const { spawnSync } = require("node:child_process");
+
+const START = "# luciazero:start global-npm-path";
+const END = "# luciazero:end global-npm-path";
+const BODY = `${START}\nexport PATH="$HOME/.local/npm/bin:$PATH"\n${END}\n`;
+
+function locations(env = process.env) {
+  const home = env.HOME || os.homedir();
+  if (!path.isAbsolute(home)) throw new Error("HOME must be an absolute path");
+  const shell = path.basename(env.SHELL || "");
+  const rcName = shell === "zsh" ? ".zshrc" : shell === "bash" ? ".bashrc" : null;
+  if (!rcName) throw new Error("supported shells are zsh and bash; set SHELL to the shell whose PATH should be updated");
+  return { home, prefix: path.join(home, ".local", "npm"), rc: path.join(home, rcName) };
+}
+
+function readRc(file) {
+  try {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`${file} is not a regular file; left untouched`);
+    return { text: fs.readFileSync(file, "utf8"), mode: stat.mode & 0o777 };
+  } catch (error) {
+    if (error.code === "ENOENT") return { text: "", mode: 0o600 };
+    throw error;
+  }
+}
+
+function nextRc(current, remove = false) {
+  const starts = current.split(START).length - 1;
+  const ends = current.split(END).length - 1;
+  if (starts !== ends || starts > 1) throw new Error("shell config has malformed Luciazero PATH markers; left untouched");
+  if (starts === 1) {
+    const begin = current.indexOf(START);
+    const finish = current.indexOf("\n", current.indexOf(END, begin));
+    const owned = current.slice(begin, finish < 0 ? current.length : finish + 1);
+    if (owned !== BODY) throw new Error("shell config has a customized Luciazero PATH block; left untouched");
+    if (remove) return current.slice(0, begin) + current.slice(begin + owned.length);
+    return current;
+  }
+  if (remove) return current;
+  const separator = current.length && !current.endsWith("\n") ? "\n" : "";
+  return current + separator + BODY;
+}
+
+function writeRc(file, text, mode) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const tmp = path.join(path.dirname(file), `.${path.basename(file)}.luciazero-${process.pid}-${Date.now()}`);
+  const fd = fs.openSync(tmp, "wx", mode);
+  try {
+    // open(2)'s requested mode is filtered by umask.  This is a replacement
+    // for an existing user file, so restore its exact permission bits before
+    // publishing the temporary file with rename(2).
+    fs.fchmodSync(fd, mode);
+    fs.writeFileSync(fd, text, "utf8");
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fs.renameSync(tmp, file);
+  } catch (error) {
+    try { fs.closeSync(fd); } catch {}
+    try { fs.unlinkSync(tmp); } catch {}
+    throw error;
+  }
+}
+
+function npm(args, env = process.env) {
+  const result = spawnSync("npm", args, { stdio: "inherit", env });
+  if (result.error) throw new Error(`could not run npm: ${result.error.message}`);
+  if (result.status !== 0) throw new Error(`npm exited ${result.status === null ? "without a status" : result.status}`);
+}
+
+function confirm(question) {
+  if (!process.stdin.isTTY) return Promise.resolve(false);
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => rl.question(`${question} [y/N] `, (answer) => {
+    rl.close();
+    resolve(/^y(?:es)?$/i.test(answer.trim()));
+  }));
+}
+
+async function install(args) {
+  if (args.includes("--help")) {
+    console.log("Usage: luciazero global-install [--yes]\nInstalls luciazero@latest under ~/.local/npm and adds its bin to PATH.");
+    return 0;
+  }
+  const unknown = args.filter((arg) => arg !== "--yes");
+  if (unknown.length) throw new Error(`unknown option: ${unknown[0]}`);
+  const place = locations();
+  const before = readRc(place.rc);
+  const after = nextRc(before.text);
+  if (!args.includes("--yes") && !await confirm(`Install luciazero@latest globally in ${place.prefix}?`)) {
+    console.error("global install cancelled; nothing changed");
+    return 1;
+  }
+  npm(["install", "--global", "--prefix", place.prefix, "luciazero@latest"]);
+  if (after !== before.text) {
+    try {
+      writeRc(place.rc, after, before.mode);
+    } catch (error) {
+      throw new Error(
+        `the package was installed, but PATH was not changed: ${error.message}. ` +
+        `Run ${path.join(place.prefix, "bin", "luciazero")} directly or retry global-install`
+      );
+    }
+  }
+  console.log(`luciazero installed globally in ${place.prefix}`);
+  console.log(`PATH recorded in ${place.rc}; start a new shell or source that file`);
+  return 0;
+}
+
+function status(args) {
+  if (args.includes("--help")) {
+    console.log("Usage: luciazero global-status\nChecks the user-owned global command and its shell PATH block.");
+    return 0;
+  }
+  if (args.length) throw new Error(`unknown option: ${args[0]}`);
+  const place = locations();
+  const command = path.join(place.prefix, "bin", "luciazero");
+  let commandOk = false;
+  try {
+    const commandStat = fs.statSync(command);
+    commandOk = commandStat.isFile() && Boolean(commandStat.mode & 0o111);
+  } catch {}
+  let pathOk = false;
+  try {
+    const current = readRc(place.rc).text;
+    pathOk = nextRc(current) === current;
+  } catch (error) {
+    console.error(`luciazero: ${error.message}`);
+    return 1;
+  }
+  if (!commandOk || !pathOk) {
+    if (!commandOk) console.error(`MISS  ${command}`);
+    if (!pathOk) console.error(`MISS  Luciazero PATH block in ${place.rc}`);
+    return 1;
+  }
+  console.log(`luciazero is installed globally in ${place.prefix}`);
+  console.log(`PATH is recorded in ${place.rc}`);
+  return 0;
+}
+
+async function uninstall(args) {
+  if (args.includes("--help")) {
+    console.log("Usage: luciazero global-uninstall [--yes]\nRemoves the global npm package and only Luciazero's exact PATH block.");
+    return 0;
+  }
+  const unknown = args.filter((arg) => arg !== "--yes");
+  if (unknown.length) throw new Error(`unknown option: ${unknown[0]}`);
+  const place = locations();
+  const before = readRc(place.rc);
+  const after = nextRc(before.text, true);
+  if (!args.includes("--yes") && !await confirm(`Uninstall global luciazero from ${place.prefix}?`)) {
+    console.error("global uninstall cancelled; nothing changed");
+    return 1;
+  }
+  npm(["uninstall", "--global", "--prefix", place.prefix, "luciazero"]);
+  if (after !== before.text) {
+    try {
+      writeRc(place.rc, after, before.mode);
+    } catch (error) {
+      throw new Error(
+        `the package was removed, but its PATH block remains in ${place.rc}: ${error.message}. ` +
+        `Remove only the lines from '${START}' through '${END}'`
+      );
+    }
+  }
+  console.log(`global luciazero removed from ${place.prefix}`);
+  return 0;
+}
+
+async function main(argv) {
+  const [command, ...args] = argv;
+  if (command === "install") return install(args);
+  if (command === "status") return status(args);
+  if (command === "uninstall") return uninstall(args);
+  throw new Error(`${command || "command"} is not implemented`);
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2)).then((code) => { process.exitCode = code; }).catch((error) => {
+    console.error(`luciazero: ${error.message}`);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = { BODY, locations, nextRc, readRc, writeRc };

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,8 @@
 //   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 global-install [--yes]       -> persistent user-owned CLI
+//   npx luciazero bus status [--json]         -> Agent Bus queue summary (beta)
 const { spawnSync } = require("node:child_process");
 const path = require("node:path");
 
@@ -20,6 +22,10 @@ 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"] },
+  "global-install": { runtime: process.execPath, script: "bin/global.js", args: ["install"] },
+  "global-status": { runtime: process.execPath, script: "bin/global.js", args: ["status"] },
+  "global-uninstall": { runtime: process.execPath, script: "bin/global.js", args: ["uninstall"] },
+  bus: { runtime: process.execPath, script: "bin/bus.js" },
 };
 
 const args = process.argv.slice(2);
@@ -28,7 +34,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, global-install, global-status, global-uninstall, bus, uninstall, uninstall-codex)"
     );
     process.exit(64);
   }