@aron98/load-lock 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aron98
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,116 @@
-# Temporary Holding Version
+# load-lock
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/aron98/load-lock/actions/workflows/ci.yml/badge.svg)](https://github.com/aron98/load-lock/actions/workflows/ci.yml)
+
+**A machine-wide heavy-work budget for parallel coding agents.**
+
+When several agents work side by side on one machine — separate sessions,
+repos, git worktrees, or harnesses (OpenCode, Codex CLI, Claude Code, ...) —
+their builds and test suites stomp on each other, thrash the caches, and
+starve each other's cores. load-lock gives them one shared counting
+semaphore: acquire a permit before heavy work, keep doing light work while
+queued, receive a FIFO offer when capacity frees, claim it, run, release.
+It is cooperative and advisory — no command wrapping, no automatic shell
+classification, no approval interruptions.
+
+```
+agent A (OpenCode)        agent B (Codex)         agent C (Claude Code)
+  acquire "cargo test"      acquire "npm test"      acquire "build docs"
+  granted ✓ runs            queued → keeps coding   queued → keeps coding
+  ...                       offer → claim ✓ runs    (misses window → paused)
+  release ✓                 release ✓               rejoin → offer → claim ✓
+```
+
+## Features
+
+- **One budget for the whole machine** — every client of any harness shares
+  one capacity pool regardless of repo/worktree/cwd. Default: pool `heavy`,
+  capacity 1; fully runtime-configurable by any agent via versioned CAS
+  updates (persisted with author + rationale).
+- **Atomic acquire-or-queue** — single daemon event loop; a release can
+  never slip between a failed check and queue registration.
+- **FIFO offers with opaque claim tokens** — outstanding offers reserve
+  capacity; expired offers pass capacity to the next waiter and pause the
+  absent request until it explicitly rejoins (no endless recycling).
+- **Real process-lifecycle cleanup** — permits attach to actual processes
+  (pid + process group + `/proc` start time, PID-reuse-safe). Background
+  jobs outliving the shell keep their permit until the whole group exits.
+  Never auto-expired merely for being old. Untracked work uses an honest,
+  documented heartbeat-lease tradeoff. Explicit release is always
+  available and idempotent.
+- **Crash-safe** — agent crashes release tracked permits on confirmed
+  process death; daemon restarts reconcile a journal against real liveness
+  and auto-respawn transparently.
+- **Honest notifications** — tool-boundary offer delivery everywhere; real
+  idle wakeup where the harness supports it (live-verified on OpenCode;
+  hook-based on Claude Code and Codex CLI); durable event ids for
+  reconnects. A notification never authorizes work — only `claim` does.
+- **Policy that actually reaches the model** — installed per harness via
+  its real mechanism (plugin context hook, SessionStart hooks incl.
+  compact matchers, global instruction files), plus a detailed skill/guide.
+- **Resource-aware** — `inspect_machine` reports cgroup/container CPU and
+  memory limits and current pressure; never assumes cores = capacity.
+
+## Quickstart
+
+```sh
+npm install -g @aron98/load-lock
+load-lock install --harness opencode     # or claude-code | codex | generic
+load-lock doctor
+```
+
+From then on, agents see the policy and tools automatically:
+OpenCode plugin (`load_lock_*` tools), Claude Code / Codex MCP tools
+(`mcp__load-lock__*`) plus session hooks. Any other MCP-capable harness can
+use the generic stdio server; plain shells use the CLI:
+
+```sh
+load-lock run --reason "nightly build" -- npm run build   # acquire→run→release
+load-lock status                                          # machine-wide view
+load-lock configure --capacity 2 --reason "16-core host" --author me
+```
+
+## Layout
+
+```
+src/core/       daemon + state machine + persistence + machine inspection
+src/mcp/        MCP stdio server (universal adapter)
+src/adapters/   OpenCode native plugin
+src/cli/        CLI incl. installer, hook handlers, run/wait helpers
+src/test/       32 tests: state machine, real multi-process daemon tests,
+                MCP integration, hook contracts, run helper
+demo/           reproducible 3-worktree demo (three agents, one pool)
+docs/           ARCHITECTURE / COMPATIBILITY / OPERATIONS / AGENT_GUIDE
+skills/         packaged skill
+```
+
+## Documentation
+
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — design, why a dedicated
+  service (vs WorkOS Airlock / mic-lock / flock wrappers), atomicity,
+  restart semantics, notification honesty, lifecycle tradeoffs.
+- [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md) — per-harness capability
+  matrix with implemented / contract-tested / proposed labels.
+- [docs/OPERATIONS.md](docs/OPERATIONS.md) — install, config,
+  troubleshooting, recovery, daemon lifecycle.
+- [docs/AGENT_GUIDE.md](docs/AGENT_GUIDE.md) — the playbook for agents.
+- [docs/ADAPTERS.md](docs/ADAPTERS.md) — how to write an adapter for a new
+  harness, using the published library surface.
+
+## Status
+
+- Core daemon/protocol/CLI: implemented, 32 automated tests passing
+  (multi-process daemons, real processes, restarts, races, expiry,
+  PID-reuse, subprocess survival).
+- OpenCode adapter: implemented and **live-verified** (tools, policy
+  injection, compaction-proof context hook, execution-boundary wakeup
+  with tokens, skill).
+- Claude Code + Codex CLI adapters: implemented, contract-tested against
+  documented hook JSON; not yet live-verified (harnesses not installed on
+  the verification machine).
+- Gemini CLI, Copilot CLI, Cursor, Cline, Roo Code, Goose, Aider:
+  researched; MCP fallback tier (Aider: manual CLI tier). See
+  COMPATIBILITY.md for the matrix.
+
+Linux-first; macOS works with documented liveness-check limitations;
+Windows would need a named-pipe transport adapter (planned, not built).

package/demo/demo.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# load-lock demo: three agents in three git worktrees compete for one
+# machine-wide heavy-work budget (capacity 1) while a shared daemon arbitrates.
+#
+# Fully scripted, reproducible, no network. Run:  bash demo/demo.sh
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+CLI=(node "$ROOT/dist/cli/main.js")
+DEMO="$(mktemp -d /tmp/opencode/ll-demo-XXXXXX)"
+
+cleanup() {
+  "${CLI[@]}" service stop >/dev/null 2>&1 || true
+  rm -rf "$DEMO"
+}
+trap cleanup EXIT
+
+say()  { printf '\n\033[1m==== %s ====\033[0m\n' "$*"; }
+line() { printf -- '---- %s\n' "$*"; }
+
+# Poll `load-lock status` (human output) until it matches $2, else fail.
+wait_for() {
+  local desc="$1" pattern="$2" i
+  for i in $(seq 1 150); do
+    if "${CLI[@]}" status 2>/dev/null | grep -qE "$pattern"; then return 0; fi
+    sleep 0.1
+  done
+  echo "TIMED OUT waiting for: $desc" >&2
+  "${CLI[@]}" status || true
+  exit 1
+}
+
+say "build"
+(cd "$ROOT" && npm run build --silent)
+
+say "workspace: git repo + 3 worktrees in $DEMO"
+git init -q "$DEMO/repo"
+git -C "$DEMO/repo" config user.email demo@load-lock
+git -C "$DEMO/repo" config user.name  demo
+echo 'fn main() { println!("heavy"); }' > "$DEMO/repo/main.rs"
+git -C "$DEMO/repo" add -A
+git -C "$DEMO/repo" commit -qm "init"
+for w in a b c; do
+  git -C "$DEMO/repo" worktree add -q "$DEMO/wt-$w" -b "wt-$w"
+done
+line "3 worktrees, one repo — 3 'agents' will share ONE budget regardless of checkout"
+
+# Isolated daemon for the demo (does not touch any real state).
+export LOAD_LOCK_STATE_DIR="$DEMO/state"
+export LOAD_LOCK_SOCKET="$DEMO/state/daemon.sock"
+
+say "start the shared daemon"
+"${CLI[@]}" service start
+
+say "machine inventory (what agents are told to reason with)"
+"${CLI[@]}" inspect --json | node -e '
+  let s=""; process.stdin.on("data", d => (s += d)).on("end", () => {
+    const j = JSON.parse(s);
+    console.log(`cpu: ${j.cpu.logicalCores} logical / ${j.cpu.effectiveCores} effective (${j.cpu.cgroupVersion})`);
+    console.log(`memory: ${(j.memory.totalBytes/2**30).toFixed(1)} GiB total / ${(j.memory.effectiveLimitBytes/2**30).toFixed(1)} GiB effective limit`);
+    console.log(`pressure: ${j.pressure.note}`);
+  });'
+
+say "configure: capacity 1, short claim window (2s) for a snappy demo"
+"${CLI[@]}" configure --capacity 1 --offer-timeout-ms 2000 \
+  --reason "demo: single heavy slot; short offer window to show expiry" --author "demo-operator" >/dev/null
+line "any agent may propose changes like this via configure (versioned CAS); the demo pins it"
+
+say "launch agent A (gets the only slot) — then B and C, which queue"
+(cd "$DEMO/wt-a" && exec node "$ROOT/demo/sim-agent.mjs" --role A --agent sim-a --label "A build (wt-a)") &
+PID_A=$!
+wait_for "A holds the only slot" '1/1 in use'
+(cd "$DEMO/wt-b" && exec node "$ROOT/demo/sim-agent.mjs" --role B --agent sim-b --label "B test (wt-b)") &
+PID_B=$!
+wait_for "B is queued" '1 queued'
+(cd "$DEMO/wt-c" && exec node "$ROOT/demo/sim-agent.mjs" --role C --agent sim-c --label "C build (wt-c)") &
+PID_C=$!
+wait_for "C is queued too" '2 queued'
+
+say "snapshot: one heavy job running, two agents queued (all in different worktrees)"
+"${CLI[@]}" status
+
+say "agents run on their own — watching the hand-off from A to B (strict FIFO)"
+wait_for "A released; B now holds the permit" 'held: B test'
+line "A finished its build; the daemon reserved the slot for the FIFO head (B) and made an offer"
+wait_for "B finished; C gets an offer — but C is busy and will miss it" 'held: C build|1 paused'
+line "C deliberately let its offer expire: the request is PAUSED, not recycled"
+wait_for "capacity back to idle (C paused, nobody holds)" '0/1 in use'
+"${CLI[@]}" status
+
+say "C rejoins when actually ready, claims, runs"
+wait_for "all three agents finished (capacity idle)" ': 0/1 in use'
+wait "$PID_A" "$PID_B" "$PID_C"
+
+say "final state"
+"${CLI[@]}" status
+"${CLI[@]}" get-config | node -e '
+  let s=""; process.stdin.on("data", d => (s += d)).on("end", () => {
+    const j = JSON.parse(s);
+    console.log(`config version ${j.config.version}; capacity(heavy)=${j.config.pools.heavy.capacity}; offer window ${j.config.offerTimeoutMs}ms`);
+    console.log("change history:");
+    for (const h of j.history) console.log(`  v${h.version} by ${h.author}: ${h.reason}`);
+  });'
+
+say "event log (durable identities — every grant, offer, claim, release)"
+"${CLI[@]}" events --json | node -e '
+  let s=""; process.stdin.on("data", d => (s += d)).on("end", () => {
+    const j = JSON.parse(s);
+    for (const ev of j.events) console.log(`  #${ev.id} ${ev.type.padEnd(13)} ${ev.entry?.agentLabel ?? ev.targetAgent ?? ""}`);
+  });'
+
+printf '\n\033[1mDemo complete:\033[0m capacity 1 was never exceeded; offers went out strictly in FIFO order;\nC missed its claim window, was paused (not endlessly recycled), and rejoined explicitly.\n'

package/demo/sim-agent.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+/**
+ * Simulated coding agent for the load-lock demo.
+ *
+ * Each instance is a separate OS process playing one agent from one harness,
+ * working inside one git worktree. It talks to the shared load-lock daemon
+ * exactly the way a scripted agent (e.g. aider, a shell-driven flow) would:
+ * via the `load-lock` CLI. Real agents would use MCP tools or the native
+ * OpenCode plugin instead — same daemon, same protocol, same FIFO.
+ *
+ * Usage (normally launched by demo.sh, not directly):
+ *   cd <worktree> && node sim-agent.mjs --role A --agent sim-a --label "A (wt-a)"
+ *
+ * Roles:
+ *   A — gets the permit immediately, runs heavy work, releases.
+ *   B — queues, does light work meanwhile, claims its FIFO offer, runs heavy work.
+ *   C — queues, deliberately MISSES its claim window (offer expires → paused),
+ *       then explicitly rejoins once actually ready, claims, runs heavy work.
+ */
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+
+const { values } = parseArgs({
+  options: {
+    role: { type: "string" },
+    agent: { type: "string" },
+    label: { type: "string" },
+  },
+});
+const role = values.role;
+const agent = values.agent;
+const label = values.label ?? agent;
+if (!role || !agent) {
+  console.error("sim-agent: --role and --agent are required");
+  process.exit(64);
+}
+
+const CLI = join(import.meta.dirname, "..", "dist", "cli", "main.js");
+
+/** Run the load-lock CLI; returns {code, stdout, stderr, json}. */
+function ll(args) {
+  const r = spawnSync(process.execPath, [CLI, ...args], { encoding: "utf8", timeout: 120_000 });
+  let json = null;
+  try {
+    json = JSON.parse(r.stdout);
+  } catch {
+    /* human output */
+  }
+  return { code: r.status, stdout: r.stdout, stderr: r.stderr, json };
+}
+
+const log = (msg) => console.log(`[${label}] ${msg}`);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const fail = (msg) => {
+  console.error(`[${label}] FATAL: ${msg}`);
+  process.exit(70);
+};
+
+const ACQ = ["acquire", "--agent", agent, "--label", label];
+
+/** Poll own pending offers until one appears (or bail after ~30s). */
+async function waitForOffer() {
+  for (let i = 0; i < 100; i++) {
+    const p = ll(["pending", "--agent", agent]);
+    const offer = p.json?.offers?.[0];
+    if (offer) return offer;
+    await sleep(300);
+  }
+  fail("no offer arrived within 30s");
+}
+
+// ---------------------------------------------------------------------- role A
+async function roleA() {
+  log("I need to run a heavy job: cargo build (simulated with `sleep 2`)");
+  const acq = ll([...ACQ, "--op-key", "build-wt-a", "--reason", "cargo build (simulated)"]);
+  if (acq.code !== 0 || acq.json?.state !== "granted") {
+    fail(`expected an immediate grant, got: ${acq.stdout.trim() || acq.stderr.trim()}`);
+  }
+  const permit = acq.json.entry.permitToken;
+  log(`capacity was free: permit granted immediately (${permit.slice(0, 12)}…). Starting heavy work.`);
+  const run = ll(["run", "--permit", permit, "--", "sleep", "2"]);
+  log(`heavy work finished (exit ${run.code}); the run helper released the permit with the job's outcome.`);
+}
+
+// ---------------------------------------------------------------------- role B
+async function roleB() {
+  log("I need to run a heavy job: cargo test (simulated with `sleep 1.5`)");
+  const acq = ll([...ACQ, "--op-key", "build-wt-b", "--reason", "cargo test (simulated)"]);
+  if (acq.json?.state !== "queued") fail(`expected to queue, got: ${acq.stdout.trim()}`);
+  log(
+    `machine is busy: registered in the FIFO queue at position ${acq.json.entry.position} ` +
+      `(request ${acq.json.entry.requestId.slice(0, 12)}…). No permit yet.`,
+  );
+  log("continuing useful LIGHT work meanwhile — no permit needed for these:");
+  for (let i = 1; i <= 3; i++) {
+    await sleep(400);
+    log(`  light work ${i}/3: grep TODOs in my worktree`);
+  }
+  log("blocking on my queued request (bounded wait; a real agent would just check pending at the next tool call)…");
+  const w = ll(["wait", "--id", acq.json.entry.requestId, "--agent", agent, "--timeout", "30000"]);
+  if (w.code !== 0) fail(`wait failed: ${w.stderr.trim() || w.stdout.trim()}`);
+  const permit = w.json.permit_token;
+  log(`FIFO offer arrived and was claimed (permit ${permit.slice(0, 12)}…). Starting heavy work.`);
+  const run = ll(["run", "--permit", permit, "--", "sleep", "1.5"]);
+  log(`heavy work finished (exit ${run.code}); permit released.`);
+}
+
+// ---------------------------------------------------------------------- role C
+async function roleC() {
+  log("I need to run a heavy job too: cargo build (simulated with `sleep 1`)");
+  const acq = ll([...ACQ, "--op-key", "build-wt-c", "--reason", "cargo build (simulated)"]);
+  if (acq.json?.state !== "queued") fail(`expected to queue, got: ${acq.stdout.trim()}`);
+  log(`machine is busy: queued at position ${acq.json.entry.position}. Doing light work while I wait.`);
+  const offer = await waitForOffer();
+  log(
+    `offer arrived (claim window ~2s, expires ${new Date(offer.offerExpiresAt).toISOString()}) ` +
+      "— but I'm mid-edit on a file; I will deliberately NOT claim it yet.",
+  );
+  await sleep(3200); // longer than the 2s claim window
+  const p = ll(["pending", "--agent", agent]);
+  const paused = p.json?.paused?.[0];
+  if (!paused) fail("expected my request to be PAUSED after missing the claim window");
+  log(
+    "claim window elapsed → my request is PAUSED (the machine did not wait for me; " +
+      "capacity moved on, and I am not endlessly recycled).",
+  );
+  log("I'm ready now — explicitly rejoining the queue.");
+  ll(["rejoin", "--id", acq.json.entry.requestId]);
+  const offer2 = await waitForOffer();
+  log(`re-offered (request retained its FIFO identity). Claiming now, before the window lapses.`);
+  const claim = ll(["claim", "--offer", offer2.offerToken]);
+  if (claim.code !== 0) fail(`claim failed: ${claim.stderr.trim() || claim.stdout.trim()}`);
+  const permit = claim.json.entry.permitToken;
+  log(`claimed (${permit.slice(0, 12)}…). Starting heavy work.`);
+  const run = ll(["run", "--permit", permit, "--", "sleep", "1"]);
+  log(`heavy work finished (exit ${run.code}); permit released.`);
+}
+
+// -------------------------------------------------------------------------------
+try {
+  if (role === "A") await roleA();
+  else if (role === "B") await roleB();
+  else if (role === "C") await roleC();
+  else fail(`unknown role "${role}"`);
+  log("done. ✅");
+} catch (e) {
+  fail(e?.stack ?? String(e));
+}

package/dist/adapters/opencode/plugin.d.ts

@@ -0,0 +1,18 @@
+/**
+ * load-lock native plugin for OpenCode V2.
+ *
+ * Installed to ~/.config/opencode/plugins/load-lock/ (see cli/install.ts).
+ * Provides:
+ *  - native tools in the `load_lock` namespace (acquire/claim/release/...)
+ *  - run_with_permit / job_status / job_stop: full execution lifecycle
+ *  - automatic policy injection on every model call via the session
+ *    "context" hook (compaction-proof by construction)
+ *  - idle wakeup: daemon watch -> ctx.session.synthetic when an offer
+ *    targets an OpenCode session
+ *  - automatic per-session heartbeats (untracked leases never lapse while
+ *    the OpenCode service lives; the model never has to remember)
+ *  - a registered skill with the detailed agent guide
+ */
+import { Plugin } from "@opencode/plugin";
+declare const _default: Plugin.Plugin;
+export default _default;