@aron98/load-lock 0.0.0-stage → 0.1.0

package/dist/core/sysinfo.d.ts

@@ -0,0 +1,2 @@
+import { InspectResult, MachineConfig } from "../shared/protocol.js";
+export declare function inspectMachine(config?: MachineConfig): InspectResult;

package/dist/core/sysinfo.js

@@ -0,0 +1,123 @@
+/**
+ * Machine resource inspection: CPUs, memory, cgroup v1/v2 limits, load.
+ *
+ * Design note (spec): "Report CPU + memory incl. cgroup/container limits;
+ * don't assume 2 cores = 2 jobs." `effectiveCores` and `effectiveLimitBytes`
+ * are the honest numbers agents should reason with; the `suggestion` string
+ * is advisory only — nothing here configures the lock automatically.
+ */
+import { readFileSync } from "node:fs";
+import os from "node:os";
+function readIfExists(path) {
+    try {
+        return readFileSync(path, "utf8").trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseUint(s) {
+    if (s === undefined)
+        return null;
+    const n = Number(s);
+    return Number.isFinite(n) && n >= 0 ? n : null;
+}
+function cgroupVersion() {
+    if (readIfExists("/sys/fs/cgroup/cgroup.controllers") !== undefined)
+        return "v2";
+    if (readIfExists("/sys/fs/cgroup/cpu/cpu.cfs_quota_us") !== undefined)
+        return "v1";
+    return "none";
+}
+function cgroupCpuLimit() {
+    if (cgroupVersion() === "v2") {
+        // "max 100000" or "200000 100000"
+        const s = readIfExists("/sys/fs/cgroup/cpu.max");
+        if (!s)
+            return { quota: null, period: null };
+        const [q, p] = s.split(/\s+/);
+        const period = parseUint(p);
+        if (q === "max")
+            return { quota: null, period };
+        const quota = parseUint(q);
+        return { quota, period: period ?? 100_000 };
+    }
+    if (cgroupVersion() === "v1") {
+        const quota = parseUint(readIfExists("/sys/fs/cgroup/cpu/cpu.cfs_quota_us"));
+        const period = parseUint(readIfExists("/sys/fs/cgroup/cpu/cpu.cfs_period_us"));
+        return { quota: quota && quota > 0 ? quota : null, period };
+    }
+    return { quota: null, period: null };
+}
+function cgroupMemoryLimit() {
+    const v = cgroupVersion();
+    if (v === "v2") {
+        const s = readIfExists("/sys/fs/cgroup/memory.max");
+        const u = readIfExists("/sys/fs/cgroup/memory.current");
+        return {
+            limit: s && s !== "max" ? parseUint(s) : null,
+            usage: parseUint(u),
+        };
+    }
+    if (v === "v1") {
+        const l = parseUint(readIfExists("/sys/fs/cgroup/memory/memory.limit_in_bytes"));
+        const u = parseUint(readIfExists("/sys/fs/cgroup/memory/memory.usage_in_bytes"));
+        // v1 reports a huge sentinel when unlimited
+        return { limit: l !== null && l < 1e15 ? l : null, usage: u };
+    }
+    return { limit: null, usage: null };
+}
+export function inspectMachine(config) {
+    const cpus = os.cpus();
+    const { quota, period } = cgroupCpuLimit();
+    const logical = cpus.length || 1;
+    let effectiveCores = logical;
+    if (quota !== null && period && period > 0) {
+        effectiveCores = Math.min(logical, Math.max(1, Math.floor(quota / period)));
+    }
+    const loadavg = os.loadavg();
+    const memTotal = os.totalmem();
+    const memAvailable = os.availableMemory ? os.availableMemory() : os.freemem();
+    const { limit: cgMemLimit, usage: cgMemUsage } = cgroupMemoryLimit();
+    const effectiveLimitBytes = cgMemLimit !== null ? Math.min(memTotal, cgMemLimit) : memTotal;
+    const loadPerCore = loadavg[0] / effectiveCores;
+    const memUsedFrac = cgMemUsage !== null && cgMemLimit ? cgMemUsage / cgMemLimit : 1 - memAvailable / memTotal;
+    const loadPressure = loadPerCore > 1.25 ? "high" : loadPerCore > 0.6 ? "moderate" : "low";
+    const memPressure = memUsedFrac > 0.85 ? "high" : memUsedFrac > 0.6 ? "moderate" : "low";
+    const pools = config?.pools ?? { heavy: { capacity: 1 } };
+    const totalCapacity = Object.values(pools).reduce((a, p) => a + p.capacity, 0);
+    const suggestion = `Machines vary: this one exposes ~${effectiveCores} effective core(s) and ~` +
+        `${(effectiveLimitBytes / 1024 ** 3).toFixed(1)} GiB effective memory (including container limits). ` +
+        `Current total lock capacity across pools is ${totalCapacity}. Judge heavy vs light by expected ` +
+        `CPU/memory/IO impact; adjust capacity via load-lock configure when warranted — this is a ` +
+        `cooperative budget, not an enforced one.`;
+    const cpu = {
+        logicalCores: logical,
+        model: cpus[0]?.model?.trim(),
+        loadavg: [loadavg[0], loadavg[1], loadavg[2]],
+        cgroupVersion: cgroupVersion(),
+        cgroupCpuQuota: quota,
+        cgroupCpuPeriod: period,
+        effectiveCores,
+        loadPerEffectiveCore: Number((loadPerCore).toFixed(2)),
+    };
+    const memory = {
+        totalBytes: memTotal,
+        availableBytes: memAvailable,
+        freeBytes: os.freemem(),
+        cgroupMemoryLimitBytes: cgMemLimit,
+        cgroupMemoryUsageBytes: cgMemUsage,
+        effectiveLimitBytes,
+    };
+    return {
+        cpu,
+        memory,
+        pressure: {
+            note: `1-min load per effective core: ${cpu.loadPerEffectiveCore} (${loadPressure}); ` +
+                `memory used ≈ ${(memUsedFrac * 100).toFixed(0)}% of effective limit (${memPressure}).`,
+            loadPressure,
+            memPressure,
+        },
+        loadLock: { pools, suggestion },
+    };
+}

package/dist/mcp/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/mcp/main.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+/** load-lock MCP stdio server entrypoint (harness-spawned). */
+import { runStdioMcp } from "./server.js";
+await runStdioMcp();

package/dist/mcp/server.d.ts

@@ -0,0 +1,27 @@
+/**
+ * load-lock MCP server (stdio) — the universal adapter for harnesses that
+ * speak MCP (Claude Code, Codex CLI, Gemini CLI, Copilot CLI, Cline, Roo,
+ * Goose, ...). Each harness session spawns one MCP server process; the
+ * process-scoped agent identity routes offers back through tool results and
+ * watch pushes.
+ *
+ * Notification honesty (see docs/COMPATIBILITY.md): MCP transports can
+ * surface server-initiated *messages*, but most harnesses do not inject them
+ * into the model's context. load-lock therefore relies on:
+ *   (a) tool-boundary delivery — every acquire/claim/release/... response
+ *       carries the agent's pending offers and queue positions;
+ *   (b) bounded blocking wait in acquire (waitMs);
+ *   (c) harness-specific idle wakeup (hooks/plugins) where verified.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { LLClient } from "../shared/client.js";
+export interface McpServerOptions {
+    client: LLClient;
+    serverName?: string;
+    /** Overridden by OpenCode's per-request session metadata when present. */
+    agentId?: string;
+}
+export declare function buildServer(opts: McpServerOptions): McpServer;
+export declare function runStdioMcp(opts?: {
+    agentId?: string;
+}): Promise<void>;

package/dist/mcp/server.js

@@ -0,0 +1,352 @@
+/**
+ * load-lock MCP server (stdio) — the universal adapter for harnesses that
+ * speak MCP (Claude Code, Codex CLI, Gemini CLI, Copilot CLI, Cline, Roo,
+ * Goose, ...). Each harness session spawns one MCP server process; the
+ * process-scoped agent identity routes offers back through tool results and
+ * watch pushes.
+ *
+ * Notification honesty (see docs/COMPATIBILITY.md): MCP transports can
+ * surface server-initiated *messages*, but most harnesses do not inject them
+ * into the model's context. load-lock therefore relies on:
+ *   (a) tool-boundary delivery — every acquire/claim/release/... response
+ *       carries the agent's pending offers and queue positions;
+ *   (b) bounded blocking wait in acquire (waitMs);
+ *   (c) harness-specific idle wakeup (hooks/plugins) where verified.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { spawn } from "node:child_process";
+import { LLClient } from "../shared/client.js";
+import { POLICY_BRIEF } from "../policy/text.js";
+const ACQUIRE_DESC = `Acquire a machine-wide permit before starting resource-intensive local work (full builds, test suites, big compiles/containers).
+
+Pass a short reason and a stable op_key identifying the pending operation (duplicate acquires for the same op_key return the existing request — do not invent a new key while one is live). Set wait_ms (default a few seconds) to block briefly for capacity instead of returning queued immediately; keep doing light work while queued. You will receive an offer to claim when capacity frees. Never start heavy work while merely queued.`;
+const CLAIM_DESC = `Claim an offered permit within its claim window (offers expire, default 30s, then capacity passes to the next waiter and your request pauses until you rejoin). Only a successful claim authorizes heavy work. After claiming you MUST begin execution within the start deadline (default 120s) — via run_with_permit (best: full process tracking incl. background jobs), attach_pid, or mark_started — or the permit is reclaimed automatically.`;
+const RELEASE_DESC = `Release a held permit immediately after the heavy work finishes — success, failure, or termination (idempotent: releasing twice is fine). A permit survives the tool call and session that acquired it; automatic cleanup releases it when a tracked job exits or, for untracked permits, when your adapter stops heartbeating — but do not rely on that: release as soon as the work is done.`;
+export function buildServer(opts) {
+    const client = opts.client;
+    const defaultAgent = opts.agentId ?? "agt_" + process.pid.toString(36) + Math.random().toString(36).slice(2, 8);
+    const server = new McpServer({ name: opts.serverName ?? "load-lock", version: "0.1.0" }, { instructions: POLICY_BRIEF });
+    const json = (v) => ({
+        content: [{ type: "text", text: JSON.stringify(v, null, 2) }],
+    });
+    const agentIdOf = (input) => input.agent_id?.trim() || defaultAgent;
+    server.registerTool("acquire", {
+        title: "Acquire heavy-work permit",
+        description: ACQUIRE_DESC,
+        inputSchema: {
+            reason: z.string().describe("Why you need the machine (shown to other agents, e.g. 'cargo test --all in worktree feat-x')"),
+            op_key: z.string().describe("Stable key for the pending operation (idempotency; e.g. 'wt-feat-x/cargo-test')"),
+            agent_id: z.string().optional().describe("Override agent identity (rarely needed)"),
+            wait_ms: z.number().int().optional().describe("Bounded blocking wait for capacity, clamped by config (default 0)"),
+            subscribe_if_busy: z.boolean().optional().describe("false = fail fast instead of queueing (default true)"),
+            pool: z.string().optional().describe("Resource pool (default 'heavy')"),
+        },
+    }, async (input) => {
+        const res = await client.request("acquire", {
+            pool: input.pool,
+            agentId: agentIdOf(input),
+            cwd: process.cwd(),
+            opKey: input.op_key,
+            reason: input.reason,
+            waitMs: input.wait_ms,
+            subscribeIfBusy: input.subscribe_if_busy,
+        });
+        const e = res.entry ?? {};
+        return json({
+            state: res.state,
+            request_id: e.requestId,
+            pool: e.pool ?? input.pool ?? "heavy",
+            queue_position: e.position,
+            offer_token: e.offerToken,
+            offer_expires_at: e.offerExpiresAt,
+            permit_token: e.permitToken,
+            start_deadline: e.startDeadline,
+            reason: e.reason,
+            next_action: res.state === "granted"
+                ? "You hold the permit. Start the heavy work now via run_with_permit (best), attach_pid, or mark_started; release when done."
+                : res.state === "offered"
+                    ? "You have a reserved offer: call claim(offer_token) NOW — it expires and capacity passes to the next waiter."
+                    : res.state === "queued"
+                        ? "Keep doing light work. Capacity will be offered to you in FIFO order; check pending() at tool boundaries or pass wait_ms next time."
+                        : "Your request was paused (offer expired or declined). Call rejoin(request_id) when ready to queue again.",
+            entry: res.entry,
+            pending: res.pending,
+        });
+    });
+    server.registerTool("claim", {
+        title: "Claim offered permit",
+        description: CLAIM_DESC,
+        inputSchema: { offer_token: z.string().describe("Token from your offer") },
+    }, async (input) => {
+        const res = await client.request("claim", { offerToken: input.offer_token });
+        const e = res.entry ?? {};
+        return json({
+            state: "held",
+            request_id: e.requestId,
+            permit_token: e.permitToken,
+            phase: e.phase,
+            start_deadline: e.startDeadline,
+            next_action: "Permit claimed. Begin the heavy work before the start deadline: run_with_permit (best), attach_pid, or mark_started. Release when finished.",
+            entry: res.entry,
+        });
+    });
+    server.registerTool("release", {
+        title: "Release permit",
+        description: RELEASE_DESC,
+        inputSchema: {
+            permit_token: z.string().describe("Token from acquire/claim"),
+            reason: z.string().optional().describe("Optional outcome note (e.g. 'tests passed')"),
+        },
+    }, async (input) => {
+        const res = await client.request("release", { permitToken: input.permit_token });
+        return json({
+            released_now: res.releasedNow,
+            request_id: res.entry?.requestId,
+            note: res.releasedNow ? "Permit released; queued agents will be offered capacity." : "Already released (idempotent).",
+        });
+    });
+    server.registerTool("cancel", {
+        title: "Cancel queued request",
+        description: "Cancel a queued/offered/paused request you no longer need. Held permits must be released instead.",
+        inputSchema: { request_id: z.string() },
+    }, async (input) => json(await client.request("cancel", { requestId: input.request_id })));
+    server.registerTool("decline", {
+        title: "Decline an offer",
+        description: "Explicitly decline an offered permit (e.g. you are mid light-work and will rejoin later). Capacity passes to the next waiter immediately.",
+        inputSchema: { offer_token: z.string() },
+    }, async (input) => json(await client.request("decline", { offerToken: input.offer_token })));
+    server.registerTool("rejoin", {
+        title: "Rejoin queue after pause",
+        description: "Rejoin the FIFO queue after your offer expired or you declined. Paused requests never auto-recycle — rejoining is your explicit choice.",
+        inputSchema: { request_id: z.string() },
+    }, async (input) => {
+        const res = await client.request("rejoin", { requestId: input.request_id });
+        return json({
+            state: res.state,
+            request_id: res.entry?.requestId,
+            queue_position: res.entry?.position,
+            offer_token: res.entry?.offerToken,
+            next_action: res.state === "offered"
+                ? "Capacity was free: you have a new offer — claim(offer_token) now."
+                : `Queued at position ${res.entry?.position ?? "?"}; continue light work.`,
+            entry: res.entry,
+        });
+    });
+    server.registerTool("pending", {
+        title: "Your offers/queue/permits",
+        description: "List your outstanding offers (claim these NOW — they expire), queue positions, paused and held requests.",
+        inputSchema: { agent_id: z.string().optional() },
+    }, async (input) => json(await client.request("pending", { agentId: agentIdOf(input) })));
+    server.registerTool("status", {
+        title: "Semaphore status",
+        description: "Machine-wide pool snapshot: capacity, holders, outstanding offers, FIFO queue, paused requests. Check this when deciding whether work is heavy vs light, or to see who is building.",
+        inputSchema: { pool: z.string().optional() },
+    }, async (input) => json(await client.request("status", input.pool ? { pool: input.pool } : {})));
+    server.registerTool("inspect_machine", {
+        title: "Inspect machine resources",
+        description: "Honest machine resources: effective CPU cores and memory INCLUDING cgroup/container limits, plus current pressure. Do not assume N logical cores = N parallel heavy jobs — quota-limited containers report fewer effective cores.",
+        inputSchema: {},
+    }, async () => json(await client.request("inspect", {})));
+    server.registerTool("get_config", {
+        title: "Read config",
+        description: "Current config: pools/capacity, offer timeout, heavy-work guidance, and change history with rationale.",
+        inputSchema: {},
+    }, async () => json(await client.request("get_config", {})));
+    server.registerTool("configure", {
+        title: "Update config (CAS)",
+        description: "Compare-and-swap config update so concurrent agents never silently overwrite each other. Read get_config, pass its version as expected_version, describe changes and a reason. Capacity decreases let current holders finish; increases admit queued requests immediately.",
+        inputSchema: {
+            expected_version: z.number().int(),
+            changes: z
+                .object({
+                pools: z.record(z.string(), z.object({ capacity: z.number().int() })).optional(),
+                offer_timeout_ms: z.number().int().optional(),
+                max_wait_ms: z.number().int().optional(),
+                start_timeout_ms: z.number().int().optional(),
+                untracked_lease_ms: z.number().int().optional(),
+                guidance: z
+                    .object({
+                    heavy_work_heuristic: z.string().optional(),
+                    notes: z.string().optional(),
+                    agent: z
+                        .object({ id: z.string(), parallelism: z.string().optional(), note: z.string().optional() })
+                        .optional(),
+                })
+                    .optional(),
+            }),
+            reason: z.string().describe("Why this change is right for this machine"),
+            author: z.string().describe("Who you are, e.g. 'opencode session abc123'"),
+        },
+    }, async (input) => json(await client.request("configure", {
+        expectedVersion: input.expected_version,
+        changes: {
+            ...input.changes,
+            offerTimeoutMs: input.changes.offer_timeout_ms,
+            maxWaitMs: input.changes.max_wait_ms,
+            startTimeoutMs: input.changes.start_timeout_ms,
+            untrackedLeaseMs: input.changes.untracked_lease_ms,
+            guidance: input.changes.guidance
+                ? {
+                    ...input.changes.guidance,
+                    heavyWorkHeuristic: input.changes.guidance.heavy_work_heuristic,
+                }
+                : undefined,
+        },
+        reason: input.reason,
+        author: input.author,
+    })));
+    server.registerTool("attach_pid", {
+        title: "Attach pid to permit",
+        description: "Associate a process you already started (e.g. a harness background task's shell) with your claimed permit. Atomic: fails if the permit was reclaimed. The permit is then released automatically when the process (and its process group) exits — including for background jobs. On Linux this is pid-reuse-safe via /proc start times. Prefer run_with_permit for full lifecycle ownership.",
+        inputSchema: { permit_token: z.string(), pid: z.number().int().positive() },
+    }, async (input) => json(await client.request("attach_pid", { permitToken: input.permit_token, pid: input.pid })));
+    server.registerTool("mark_started", {
+        title: "Mark execution started (untracked)",
+        description: "Tell load-lock you started the heavy work when you cannot associate a process (no run_with_permit, no attach_pid). The permit then runs on a heartbeat lease: this MCP server heartbeats automatically while your session lives; if your agent dies, the lease reclaims the permit. WEAKER GUARANTEE: if your process survives your dead session, another heavy job may overlap it. Prefer run_with_permit whenever possible.",
+        inputSchema: { permit_token: z.string() },
+    }, async (input) => json(await client.request("mark_started", { permitToken: input.permit_token })));
+    // ---- execution helper: owns the process lifecycle end-to-end ----------
+    const jobs = new Map();
+    server.registerTool("run_with_permit", {
+        title: "Run heavy command under permit",
+        description: "Run the heavy command you hold a permit for, with full lifecycle ownership: spawns the command in its own process group, atomically associates it with your claimed permit, returns a job_id immediately (background execution — do NOT release the permit merely because this returned), and auto-releases the permit when the job exits (success, failure, or kill). Survives this tool call and your session: if this server dies, the daemon still watches the job's process group. Poll job_status for completion and output.",
+        inputSchema: {
+            permit_token: z.string().describe("Permit token from acquire/claim"),
+            command: z.string().describe("Shell command to run (the heavy work you acquired the permit for — do not pass unrelated light commands)"),
+            cwd: z.string().optional().describe("Working directory (default: this server's cwd)"),
+        },
+    }, async (input) => {
+        const child = spawn(input.command, {
+            shell: true,
+            detached: true, // own process group => pgid === child.pid on Linux
+            cwd: input.cwd || process.cwd(),
+            env: process.env,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const job = {
+            id: "job_" + child.pid + "_" + Math.random().toString(36).slice(2, 8),
+            child,
+            permitToken: input.permit_token,
+            command: input.command,
+            startedAt: Date.now(),
+            exited: false,
+            exitCode: null,
+            output: [],
+        };
+        // Watch for exit BEFORE associating (no awaits in between): a job that
+        // exits instantly must not lose its exit event while we round-trip to
+        // the daemon, or the permit would never be auto-released.
+        const push = (buf) => {
+            job.output.push(buf.toString("utf8"));
+            if (job.output.length > 200)
+                job.output.shift();
+        };
+        child.stdout?.on("data", push);
+        child.stderr?.on("data", push);
+        child.on("exit", (code) => {
+            job.exited = true;
+            job.exitCode = code;
+            // Auto-release on completion: success, failure, or termination.
+            client
+                .request("release", { permitToken: job.permitToken, outcome: code === 0 ? "success" : "failure" })
+                .catch(() => {
+                /* already released/reclaimed — idempotent path */
+            });
+        });
+        // Atomic association; if the permit was reclaimed already, kill the job
+        // before it can do meaningful work and report the failure.
+        try {
+            await client.request("start_job", {
+                permitToken: input.permit_token,
+                pid: child.pid,
+                pgid: child.pid,
+            });
+        }
+        catch (err) {
+            try {
+                process.kill(-child.pid, "SIGKILL");
+            }
+            catch {
+                /* already gone */
+            }
+            return json({
+                error: `permit no longer startable (${err.message}); job killed before doing work; acquire again`,
+            });
+        }
+        jobs.set(job.id, job);
+        return json({
+            job_id: job.id,
+            pid: child.pid,
+            pgid: child.pid,
+            state: "running",
+            note: `Background job started under permit. Do NOT release the permit manually — it auto-releases when the job exits. Poll job_status(job_id) for completion; job_stop(job_id) to terminate.`,
+        });
+    });
+    server.registerTool("job_status", {
+        title: "Job status",
+        description: "Poll a job started with run_with_permit: running/exited, exit code, recent output. The permit auto-released when the job exited.",
+        inputSchema: { job_id: z.string() },
+    }, async (input) => {
+        const job = jobs.get(input.job_id);
+        if (!job)
+            return json({ error: `unknown job_id (jobs live in this MCP server process; it restarted if missing)` });
+        return json({
+            job_id: job.id,
+            command: job.command,
+            running: !job.exited,
+            exit_code: job.exitCode,
+            output_tail: job.output.slice(-20).join(""),
+        });
+    });
+    server.registerTool("job_stop", {
+        title: "Stop job",
+        description: "Terminate a job started with run_with_permit (SIGTERM to its process group, escalating to SIGKILL). The permit auto-releases once it exits.",
+        inputSchema: { job_id: z.string() },
+    }, async (input) => {
+        const job = jobs.get(input.job_id);
+        if (!job)
+            return json({ error: "unknown job_id" });
+        if (!job.exited) {
+            try {
+                process.kill(-job.child.pid, "SIGTERM");
+            }
+            catch {
+                /* already gone */
+            }
+            setTimeout(() => {
+                if (!job.exited) {
+                    try {
+                        process.kill(-job.child.pid, "SIGKILL");
+                    }
+                    catch {
+                        /* already gone */
+                    }
+                }
+            }, 5_000).unref?.();
+        }
+        return json({ job_id: job.id, stopping: true });
+    });
+    // Automatic adapter heartbeat: while this server process lives, untracked
+    // permits of this agent keep their lease; if the harness session dies, the
+    // lease lapses and the daemon reclaims. The model never has to remember.
+    const heartbeat = setInterval(() => {
+        void client.request("heartbeat", { agentId: defaultAgent }).catch(() => {
+            /* daemon unreachable; next tool call reconnects */
+        });
+    }, 30_000);
+    heartbeat.unref?.();
+    return server;
+}
+export async function runStdioMcp(opts = {}) {
+    const client = new LLClient();
+    await client.connect();
+    // Keep a watch subscription so the connection persists and the daemon sees
+    // liveness; offers are surfaced via tool results (tool-boundary delivery).
+    const server = buildServer({ client, agentId: opts.agentId });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Keep the process alive on the open stdio transport.
+    await new Promise(() => { });
+}

package/dist/policy/text.d.ts

@@ -0,0 +1,30 @@
+/**
+ * load-lock policy text. One source of truth, delivered through each
+ * harness's instruction mechanism:
+ *
+ *  - OpenCode plugin: injected via session "context" hook (every model call,
+ *    compaction-proof) + registered skill for detail.
+ *  - Claude Code: SessionStart hook stdout (matcher startup|resume|clear|compact|fork).
+ *  - Codex CLI: SessionStart/SubagentStart hook stdout (needs /hooks trust).
+ *  - MCP server: `instructions` field on every harness that surfaces it.
+ *
+ * Deliberately SHORT (spec: no noisy reminders). The detailed playbook lives
+ * in the skill / docs/AGENT_GUIDE.md.
+ */
+export declare const POLICY_BRIEF = "# load-lock: machine-wide heavy-work budget\n\nMultiple coding agents share this machine. Before resource-intensive local work\n(builds, test suites, bulky containers, big compiles), get a permit from the\nshared, machine-wide counting semaphore. While queued, keep doing useful light\nwork (reading, editing, searching, planning); you will be offered capacity.\n\nRules:\n1. Heavy vs light: judge by expected CPU/memory/IO cost for the whole machine.\n   A quick lint or single-file check is light. Full builds/tests are heavy.\n   When unsure, call the status tool \u2014 it shows current machine pressure.\n2. Immediately before starting heavy work: acquire a permit\n   (tool: load-lock acquire, CLI: load-lock acquire). Pass a short reason and\n   a stable op_key for the pending operation.\n3. If you are queued: keep working on light tasks. When you receive an offer\n   (in any load-lock tool result or a wakeup message), claim it promptly \u2014\n   offers expire (default 30s) and capacity passes to the next waiter.\n4. Start heavy work ONLY after acquire/claim succeeds. Never start heavy work\n   on a \"queued\" result; never treat a notification as authorization.\n5. Hold the permit until the heavy process actually finishes \u2014 including when\n   it runs in the background beyond this tool call or session. Optionally\n   attach its pid (load-lock attach_pid) so a dead process auto-releases.\n6. Release immediately when done (success or failure), and cancel queued\n   requests you no longer need.\n7. Capacity is a cooperative budget, not an enforced one. If the budget seems\n   wrong for this machine, check load-lock inspect_machine (real cores/memory,\n   including container limits) and adjust with configure (explain why). Don't\n   assume N cores = N parallel heavy jobs.\n\nDetailed guide: the \"load-lock\" skill or `load-lock agent-guide`.";
+export declare function policyWithContext(statusSummary: string, configSummary?: string): string;
+export declare function statusLine(st: {
+    pools: {
+        pool: string;
+        capacity: number;
+        used: number;
+        holders: {
+            agentLabel?: string;
+            reason: string;
+        }[];
+        queue: unknown[];
+    }[];
+    cpu?: {
+        effectiveCores?: number;
+    };
+}): string;

package/dist/policy/text.js

@@ -0,0 +1,58 @@
+/**
+ * load-lock policy text. One source of truth, delivered through each
+ * harness's instruction mechanism:
+ *
+ *  - OpenCode plugin: injected via session "context" hook (every model call,
+ *    compaction-proof) + registered skill for detail.
+ *  - Claude Code: SessionStart hook stdout (matcher startup|resume|clear|compact|fork).
+ *  - Codex CLI: SessionStart/SubagentStart hook stdout (needs /hooks trust).
+ *  - MCP server: `instructions` field on every harness that surfaces it.
+ *
+ * Deliberately SHORT (spec: no noisy reminders). The detailed playbook lives
+ * in the skill / docs/AGENT_GUIDE.md.
+ */
+export const POLICY_BRIEF = `# load-lock: machine-wide heavy-work budget
+
+Multiple coding agents share this machine. Before resource-intensive local work
+(builds, test suites, bulky containers, big compiles), get a permit from the
+shared, machine-wide counting semaphore. While queued, keep doing useful light
+work (reading, editing, searching, planning); you will be offered capacity.
+
+Rules:
+1. Heavy vs light: judge by expected CPU/memory/IO cost for the whole machine.
+   A quick lint or single-file check is light. Full builds/tests are heavy.
+   When unsure, call the status tool — it shows current machine pressure.
+2. Immediately before starting heavy work: acquire a permit
+   (tool: load-lock acquire, CLI: load-lock acquire). Pass a short reason and
+   a stable op_key for the pending operation.
+3. If you are queued: keep working on light tasks. When you receive an offer
+   (in any load-lock tool result or a wakeup message), claim it promptly —
+   offers expire (default 30s) and capacity passes to the next waiter.
+4. Start heavy work ONLY after acquire/claim succeeds. Never start heavy work
+   on a "queued" result; never treat a notification as authorization.
+5. Hold the permit until the heavy process actually finishes — including when
+   it runs in the background beyond this tool call or session. Optionally
+   attach its pid (load-lock attach_pid) so a dead process auto-releases.
+6. Release immediately when done (success or failure), and cancel queued
+   requests you no longer need.
+7. Capacity is a cooperative budget, not an enforced one. If the budget seems
+   wrong for this machine, check load-lock inspect_machine (real cores/memory,
+   including container limits) and adjust with configure (explain why). Don't
+   assume N cores = N parallel heavy jobs.
+
+Detailed guide: the "load-lock" skill or \`load-lock agent-guide\`.`;
+export function policyWithContext(statusSummary, configSummary) {
+    let s = POLICY_BRIEF + "\n\n";
+    s += statusSummary;
+    if (configSummary)
+        s += "\n" + configSummary;
+    return s;
+}
+export function statusLine(st) {
+    const parts = [];
+    for (const p of st.pools) {
+        const who = p.holders.map((h) => h.agentLabel || h.reason).join(", ");
+        parts.push(`pool "${p.pool}": ${p.used}/${p.capacity} in use (held+offers)${p.queue.length ? `, ${p.queue.length} queued` : ""}${who ? `, held by: ${who}` : ""}`);
+    }
+    return `load-lock status: ${parts.join("; ")}`;
+}

package/dist/shared/client.d.ts

@@ -0,0 +1,30 @@
+export interface ClientOptions {
+    socket?: string;
+    stateDir?: string;
+    spawnDaemon?: boolean;
+}
+export declare class LLClient {
+    private sock;
+    private nextId;
+    private pending;
+    private eventCb;
+    private buf;
+    private opts;
+    constructor(opts?: ClientOptions);
+    private socketPath;
+    private stateDirPath;
+    connect(): Promise<void>;
+    private tryConnect;
+    private attach;
+    private failAll;
+    private ensureSock;
+    /** Issue one RPC. Reconnects once if the connection was lost. */
+    request<T = any>(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<T>;
+    /** Subscribe to daemon events targeted at agentId (or "*" for all). */
+    watch(agentId: string, onEvent: (ev: Record<string, unknown>) => void): Promise<void>;
+    close(): void;
+}
+/** Idempotently ensure a daemon is running and listening on `sockPath`. */
+export declare function ensureDaemon(stateDir: string, sockPath: string): Promise<void>;
+/** One-shot helper: connect (auto-spawning), run fn, close. */
+export declare function withClient<T>(fn: (c: LLClient) => Promise<T>, opts?: ClientOptions): Promise<T>;