@agentsfleet/orly 0.10.14 → 0.11.0

package/src/install_loaders.test.ts

@@ -0,0 +1,203 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, symlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+import { cleanupTemporaryDirectories, git, gitOutput, newRepository, ROOT } from "./gates_test_support";
+import { install } from "./install";
+import { readConfig } from "./config";
+import { RulesModel } from "./model";
+
+afterEach(cleanupTemporaryDirectories);
+
+
+describe("installation loaders and hooks", () => {
+  test("an existing AGENTS.md survives byte for byte and orly lands beside it", async () => {
+    const model = await RulesModel.load(ROOT);
+    const repo = newRepository();
+    const theirs = "# Our house rules\n\nAlways run `go vet`. Never touch vendor/.\n";
+    await Bun.write(join(repo, "AGENTS.md"), theirs);
+    await Bun.write(join(repo, "m.go"), "package main\n");
+
+    const result = await install(model, { targetRoot: repo, force: false, installHooks: true, orlyVersion: "0.4.0" });
+
+    expect(result.ok).toBe(true);
+    expect(existsSync(join(repo, ".orly/AGENTS.md"))).toBe(true);
+    const host = await Bun.file(join(repo, "AGENTS.md")).text();
+    expect(host).toStartWith(theirs.trimEnd());
+    expect(host).toContain(".orly/AGENTS.md");
+    // Their file is theirs: orly owns only the block, never the whole file.
+    expect((await readConfig(repo))?.managed).not.toContain("AGENTS.md");
+  });
+
+  test("the orly pointer block is idempotent across repeated installs", async () => {
+    const model = await RulesModel.load(ROOT);
+    const repo = newRepository();
+    await Bun.write(join(repo, "AGENTS.md"), "# Ours\n");
+    await install(model, { targetRoot: repo, force: false, installHooks: true, orlyVersion: "0.4.0" });
+    const afterFirst = await Bun.file(join(repo, "AGENTS.md")).text();
+
+    const second = await install(model, { targetRoot: repo, force: false, installHooks: true, orlyVersion: "0.4.0" });
+
+    expect(second.ok).toBe(true);
+    expect(await Bun.file(join(repo, "AGENTS.md")).text()).toBe(afterFirst);
+    expect(afterFirst.split("<!-- orly:begin -->").length - 1).toBe(1);
+  });
+
+  // One layout everywhere, so `update` never asks which mode it is in and a
+  // repository that starts with no rules still has the file to put them in.
+  test("a repository with no AGENTS.md still gets both files", async () => {
+    const model = await RulesModel.load(ROOT);
+    const repo = newRepository();
+
+    await install(model, { targetRoot: repo, force: false, installHooks: true, orlyVersion: "0.4.0" });
+
+    expect(await Bun.file(join(repo, ".orly/AGENTS.md")).text()).toStartWith("> **Generated by `orly`.**");
+    const host = await Bun.file(join(repo, "AGENTS.md")).text();
+    expect(host).toContain(".orly/AGENTS.md");
+    expect(host).toContain("Write this repository's own rules below");
+    expect((await readConfig(repo))?.managed).not.toContain("AGENTS.md");
+  });
+
+  // Anything installed before the split holds orly's render under AGENTS.md.
+  // That content is generated, so replacing it with the stub loses nothing.
+  test("an unrecorded generated banner cannot authorize deleting repository content", async () => {
+    const model = await RulesModel.load(ROOT);
+    const repo = newRepository();
+    await Bun.write(join(repo, "AGENTS.md"), "> **Generated by `orly`.**\nold single-file layout\n");
+
+    await install(model, { targetRoot: repo, force: false, installHooks: true, orlyVersion: "0.4.0" });
+
+    const host = await Bun.file(join(repo, "AGENTS.md")).text();
+    expect(host).toContain("old single-file layout");
+    expect(host).toContain(".orly/AGENTS.md");
+    expect(await Bun.file(join(repo, ".orly/AGENTS.md")).text()).toStartWith("> **Generated by `orly`.**");
+  });
+
+  // Rule pages cite `AGENTS.md` meaning orly's rules — true only where they are
+  // authored. In a consumer that citation has to name the file orly wrote.
+  test("rule pages cite the file orly actually wrote, not the repository's", async () => {
+    const model = await RulesModel.load(ROOT);
+    const repo = newRepository();
+    await Bun.write(join(repo, "src/lib.rs"), "pub fn main() {}\n");
+
+    const result = await install(model, { targetRoot: repo, force: false, installHooks: true, orlyVersion: "0.4.0" });
+
+    expect(result.ok).toBe(true);
+    const rules = await Bun.file(join(repo, ".orly/docs/DOCUMENTATION_RULES.md")).text();
+    const parent = rules.match(/Parent:.*?\]\(([^)]+)\)/)?.[1];
+    expect(parent).toBeDefined();
+    expect(resolve(repo, ".orly/docs", parent!)).toBe(resolve(repo, ".orly/AGENTS.md"));
+  });
+
+  test("update rewrites orly's file and leaves the repository's own alone", async () => {
+    const model = await RulesModel.load(ROOT);
+    const repo = newRepository();
+    await Bun.write(join(repo, "AGENTS.md"), "# Ours\n");
+    await install(model, { targetRoot: repo, force: true, installHooks: true, orlyVersion: "0.4.0" });
+    await Bun.write(join(repo, ".orly/AGENTS.md"), "hand-edited\n");
+    const host = await Bun.file(join(repo, "AGENTS.md")).text();
+
+    const second = await install(model, { targetRoot: repo, force: true, installHooks: true, orlyVersion: "0.4.0" });
+
+    expect(second.ok).toBe(true);
+    expect(second.written).toContain(".orly/AGENTS.md");
+    expect(await Bun.file(join(repo, ".orly/AGENTS.md")).text()).toStartWith("> **Generated by `orly`.**");
+    expect(await Bun.file(join(repo, "AGENTS.md")).text()).toBe(host);
+  });
+
+  test("a hook orly did not write is refused, not clobbered", async () => {
+    const model = await RulesModel.load(ROOT);
+    const repo = newRepository();
+    const theirs = "#!/usr/bin/env bash\necho 'our precious hook'\n";
+    await Bun.write(join(repo, ".orly/hooks/pre-commit"), theirs);
+
+    const result = await install(model, { targetRoot: repo, force: false, installHooks: true, orlyVersion: "0.4.0" });
+
+    expect(result.ok).toBe(false);
+    expect(result.errors.map((error) => error.path)).toContain(".orly/hooks/pre-commit");
+    expect(await Bun.file(join(repo, ".orly/hooks/pre-commit")).text()).toBe(theirs);
+    // A refusal leaves no footprint: the managed files never landed either.
+    expect(existsSync(join(repo, "AGENTS.md"))).toBe(false);
+  });
+
+  test("generated_hooks_mark_telemetry_invocation", async () => {
+    const model = await RulesModel.load(ROOT);
+    const repo = newRepository();
+    await Bun.write(join(repo, ".orly/hooks/pre-commit"), "#!/usr/bin/env bash\necho 'ours'\n");
+
+    const result = await install(model, { targetRoot: repo, force: true, installHooks: true, orlyVersion: "0.4.0" });
+
+    expect(result.ok).toBe(true);
+    expect(await Bun.file(join(repo, ".orly/hooks/pre-commit")).text()).toContain("export ORLY_INVOCATION=hook");
+    expect(await Bun.file(join(repo, ".orly/hooks/pre-push")).text()).toContain("export ORLY_INVOCATION=hook");
+  });
+
+  test("--no-hooks installs the rules over an existing hook without touching it", async () => {
+    const model = await RulesModel.load(ROOT);
+    const repo = newRepository();
+    const theirs = "#!/usr/bin/env bash\necho 'ours'\n";
+    await Bun.write(join(repo, ".orly/hooks/pre-commit"), theirs);
+
+    const result = await install(model, { targetRoot: repo, force: false, installHooks: false, orlyVersion: "0.4.0" });
+
+    expect(result.ok).toBe(true);
+    expect(await Bun.file(join(repo, ".orly/hooks/pre-commit")).text()).toBe(theirs);
+    expect(existsSync(join(repo, "AGENTS.md"))).toBe(true);
+  });
+
+  test("refuses to retarget a hooksPath already claimed by something else", async () => {
+    const model = await RulesModel.load(ROOT);
+    const repo = newRepository();
+    git(repo, "config", "core.hooksPath", "some-other-tools-hooks");
+
+    const result = await install(model, { targetRoot: repo, force: false, installHooks: true, orlyVersion: "0.4.0" });
+
+    expect(result.ok).toBe(false);
+    expect(result.errors.some((error) => error.path === "core.hooksPath")).toBe(true);
+    expect(gitOutput(repo, "config", "--get", "core.hooksPath")).toBe("some-other-tools-hooks");
+    expect(existsSync(join(repo, "AGENTS.md"))).toBe(false);
+  });
+
+  test("--no-hooks proceeds even when hooksPath is claimed by something else", async () => {
+    const model = await RulesModel.load(ROOT);
+    const repo = newRepository();
+    git(repo, "config", "core.hooksPath", "some-other-tools-hooks");
+
+    const result = await install(model, { targetRoot: repo, force: false, installHooks: false, orlyVersion: "0.4.0" });
+
+    expect(result.ok).toBe(true);
+    expect(gitOutput(repo, "config", "--get", "core.hooksPath")).toBe("some-other-tools-hooks");
+  });
+
+  test("--force retargets a hooksPath claimed by something else", async () => {
+    const model = await RulesModel.load(ROOT);
+    const repo = newRepository();
+    git(repo, "config", "core.hooksPath", "some-other-tools-hooks");
+
+    const result = await install(model, { targetRoot: repo, force: true, installHooks: true, orlyVersion: "0.4.0" });
+
+    expect(result.ok).toBe(true);
+    expect(gitOutput(repo, "config", "--get", "core.hooksPath")).toBe(".orly/hooks");
+  });
+
+  test("re-running init after it already set hooksPath is not a claim by another tool", async () => {
+    const model = await RulesModel.load(ROOT);
+    const repo = newRepository();
+    await install(model, { targetRoot: repo, force: false, installHooks: true, orlyVersion: "0.4.0" });
+
+    const second = await install(model, { targetRoot: repo, force: false, installHooks: true, orlyVersion: "0.4.0" });
+
+    expect(second.ok).toBe(true);
+  });
+
+  // Adversarial review, reproduced: a repository the user cloned can commit a
+  // symlink at a path init would otherwise write to. mkdirSync/writeFile/
+  // rename all follow an existing symlink silently — without this refusal,
+  // every managed file materialises through it into wherever the symlink
+  // points, outside the repository entirely, with `ok: true` and no warning.
+  // Adversarial review found this: every other write was guarded, the pointer
+  // host was not, and it is the one write orly aims at a file it does not own.
+  // A committed `AGENTS.md -> ../outside/victim` carried the block out of the
+  // repository and reported a normal success.
+});

package/src/install_nested.test.ts

@@ -26,7 +26,7 @@ describe("install package location", () => {
     const result = await install(model, { targetRoot: repo, force: false, installHooks: false, orlyVersion: "0.5.0" });
 
     expect(result.ok).toBe(true);
-    expect(result.written).toContain("rules.md");
-    expect(await Bun.file(join(repo, "rules.md")).text()).toBe("fixture rules\n");
+    expect(result.written).toContain(".orly/rules.md");
+    expect(await Bun.file(join(repo, ".orly/rules.md")).text()).toBe("fixture rules\n");
   });
 });

package/src/install_packs.test.ts

@@ -8,8 +8,8 @@ import { RulesModel } from "./model";
 
 const SOURCE_EXTENSIONS = ["rs", "ts", "tsx", "js", "jsx", "py", "sh", "sql", "zig", "mdx"];
 const DESCRIPTION_BUDGET = 320;
-const RECORDER = "audits/doc-read.sh";
-const RECORDER_LIBRARY = "audits/rule-ledger-lib.sh";
+const RECORDER = ".orly/audits/doc-read.sh";
+const RECORDER_LIBRARY = ".orly/audits/rule-ledger-lib.sh";
 // Read from package.json rather than restated here: a hand-synced copy goes
 // stale at the next release and the test then proves an install at a version
 // that no longer ships.
@@ -18,6 +18,66 @@ const ENGINE_VERSION = (await Bun.file(join(ROOT, "package.json")).json()).versi
 afterEach(cleanupTemporaryDirectories);
 
 describe("opt-in pack selection", () => {
+  test("independent consumers keep their own database, build and documentation policies", async () => {
+    const model = await RulesModel.load(ROOT);
+    const repo = newRepository();
+    for (const extension of ["sql", "zig", "ts"]) {
+      await Bun.write(join(repo, `src/source.${extension}`), "\n");
+    }
+    await Bun.write(join(repo, ".orly/orly.json"), JSON.stringify({
+      schema_version: 1, packs: ["domain.http", "domain.changelog"],
+      commands: { conform: [["true"]], "verify.unit": [["true"]] },
+    }));
+    const result = await install(model, {
+      targetRoot: repo, force: false, installHooks: false, orlyVersion: ENGINE_VERSION,
+    });
+    expect(result.errors).toEqual([]);
+    expect(result.packs).not.toContain("product.agentsfleet");
+    expect(existsSync(join(repo, "VERSION"))).toBe(false);
+    const pages = [
+      "dispatch/lifecycle.md", "dispatch/write_sql.md", "dispatch/write_zig.md",
+      "dispatch/write_ts_adhere_bun.md", "dispatch/write_http.md",
+      "dispatch/write_changelog.md", "docs/SCHEMA_CONVENTIONS.md",
+      "docs/RELEASE_TEMPLATE.md", "docs/LOGGING_STANDARD.md",
+      "docs/REST_API_DESIGN_GUIDELINES.md",
+    ];
+    const installed = await Promise.all(pages.map((path) => Bun.file(join(repo, ".orly", path)).text()));
+    for (const content of installed) {
+      expect(content).not.toContain("playbooks/founding/");
+      expect(content).not.toContain("schema/embed.zig");
+      expect(content).not.toContain("src/cmd/common.zig");
+      expect(content).not.toContain("build_runner.zig");
+      expect(content).not.toContain("~/Projects/docs/");
+      expect(content).not.toContain("cat VERSION");
+    }
+    expect(installed[1]).toContain("Destructive changes require the owner's approval");
+    expect(installed[2]).toContain("declared platform matrix");
+    expect(installed[3]).toContain("repository's declared component library");
+    expect(installed[8]).toContain("repository's structured logger");
+    expect(installed[9]).toContain("canonical OpenAPI source");
+  });
+
+  test("explicit product selection retains its teardown guard and build graph", async () => {
+    const model = await RulesModel.load(ROOT);
+    const repo = newRepository();
+    await Bun.write(join(repo, "schema/example.sql"), "\n");
+    await Bun.write(join(repo, "src/example.zig"), "\n");
+    await Bun.write(join(repo, ".orly/orly.json"), JSON.stringify({
+      schema_version: 1, packs: ["product.agentsfleet"],
+      commands: { conform: [["true"]], "verify.unit": [["true"]] },
+    }));
+    const result = await install(model, {
+      targetRoot: repo, force: false, installHooks: false, orlyVersion: ENGINE_VERSION,
+    });
+    expect(result.errors).toEqual([]);
+    const sql = await Bun.file(join(repo, ".orly/dispatch/write_sql.md")).text();
+    const zig = await Bun.file(join(repo, ".orly/dispatch/write_zig.md")).text();
+    expect(sql).toContain("0.30.0");
+    expect(sql).toContain("schema/embed.zig");
+    expect(sql).toContain("**Forbidden:**");
+    expect(zig).toContain("build_runner.zig");
+  });
+
   // An opt-in pack may cite a file another opt-in pack owns, and every such
   // citation has to be gated by the pack that provides it. Ungated, the install
   // is refused for skipping rules the repository was never meant to take:
@@ -27,7 +87,7 @@ describe("opt-in pack selection", () => {
     const model = await RulesModel.load(ROOT);
     const repo = newRepository();
     for (const extension of SOURCE_EXTENSIONS) await Bun.write(join(repo, `src/source.${extension}`), "\n");
-    await Bun.write(join(repo, ".oracle/orly.json"), JSON.stringify({ schema_version: 1, orly_version: "", packs: ["product.agentsfleet"], commands: {}, managed: [] }));
+    await Bun.write(join(repo, ".orly/orly.json"), JSON.stringify({ schema_version: 1, orly_version: "", packs: ["product.agentsfleet"], commands: {}, managed: [] }));
 
     const result = await install(model, { targetRoot: repo, force: false, installHooks: true, orlyVersion: ENGINE_VERSION });
 
@@ -35,8 +95,8 @@ describe("opt-in pack selection", () => {
     expect(result.ok).toBe(true);
     expect(result.packs).toContain("product.agentsfleet");
     expect(result.packs).not.toContain("workflow.governance");
-    expect(existsSync(join(repo, "docs/EXECUTE_DOC_READS.md"))).toBe(true);
-    expect(existsSync(join(repo, "dispatch/edit_rules.md"))).toBe(false);
+    expect(existsSync(join(repo, ".orly/docs/EXECUTE_DOC_READS.md"))).toBe(true);
+    expect(existsSync(join(repo, ".orly/dispatch/edit_rules.md"))).toBe(false);
   });
 });
 
@@ -73,7 +133,7 @@ describe("the DOC READ recorder", () => {
   test("installs with the authoring pack and runs where it lands", async () => {
     const model = await RulesModel.load(ROOT);
     const repo = newRepository();
-    await Bun.write(join(repo, ".oracle/orly.json"), JSON.stringify({ schema_version: 1, orly_version: "", packs: [], commands: {}, managed: [] }));
+    await Bun.write(join(repo, ".orly/orly.json"), JSON.stringify({ schema_version: 1, orly_version: "", packs: [], commands: {}, managed: [] }));
 
     const result = await install(model, { targetRoot: repo, force: false, installHooks: true, orlyVersion: ENGINE_VERSION });
 

package/src/installation/hooks.ts

@@ -0,0 +1,63 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { UNSCOPED_ENVIRONMENT } from "../git_env";
+import { OrlyError } from "../model";
+import { HOOK_INVOCATION_ENV, HOOK_INVOCATION_VALUE } from "../telemetry";
+import type { RepoConfig } from "../config";
+import type { PlannedFile } from "./plan";
+
+export const HOOKS_DIRECTORY = ".orly/hooks";
+const HOOKS_PATH_KEY = "core.hooksPath";
+const GIT_CONFIG = "config";
+const PIPE_OUTPUT = "pipe";
+const HOOK_GATES = [["pre-commit", "work"], ["pre-push", "verify"]] as const;
+const EXECUTABLE_BITS = 0o111;
+
+export function plannedHooks(version: string): PlannedFile[] {
+  if (!/^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?$/.test(version)) throw new OrlyError("hook package version must be a release version");
+  return HOOK_GATES.map(([name, gate]) => ({ target: `${HOOKS_DIRECTORY}/${name}`, content: Buffer.from(hookScript(gate, version)), mode: "0755" }));
+}
+
+export function checkHooks(root: string, config: RepoConfig, force: boolean): void {
+  const existing = hooksPath(root);
+  if (existing === HOOKS_DIRECTORY || force) return;
+  const previous = existing ?? git(root, ["rev-parse", "--git-path", "hooks"]).stdout.toString().trim();
+  const directory = resolve(root, previous);
+  const managed = existing === ".githooks" && HOOK_GATES.every(([name]) => config.managed.includes(`${existing}/${name}`));
+  const ownerHook = existsSync(directory) && readdirSync(directory).some((name) => {
+    if (name.endsWith(".sample") || (managed && HOOK_GATES.some(([hook]) => hook === name))) return false;
+    const stat = statSync(join(directory, name));
+    return stat.isFile() && (stat.mode & EXECUTABLE_BITS) !== 0;
+  });
+  if ((!existing || managed) && !ownerHook) return;
+  throw new OrlyError(`${HOOKS_PATH_KEY} uses '${previous}' with repository hooks; use --no-hooks to preserve repository hooks, or explicitly --force to retarget`);
+}
+
+export function hooksPath(root: string): string | null {
+  const result = git(root, [GIT_CONFIG, "--get", HOOKS_PATH_KEY]);
+  if (result.exitCode === 1) return null;
+  if (result.exitCode !== 0) throw new OrlyError(`cannot read ${HOOKS_PATH_KEY}: ${result.stderr.toString().trim()}`);
+  return result.stdout.toString().trim();
+}
+
+export function configureHooks(root: string): void {
+  const result = git(root, [GIT_CONFIG, HOOKS_PATH_KEY, HOOKS_DIRECTORY]);
+  if (result.exitCode !== 0) throw new OrlyError(`cannot configure ${HOOKS_PATH_KEY}: ${result.stderr.toString().trim()}`);
+}
+
+function git(root: string, args: string[]) {
+  return Bun.spawnSync(["git", "-C", root, ...args], { env: UNSCOPED_ENVIRONMENT, stdout: PIPE_OUTPUT, stderr: PIPE_OUTPUT });
+}
+
+function hookScript(gate: string, version: string): string {
+  return [
+    "#!/usr/bin/env bash",
+    "# Generated by orly. Re-run the pinned bunx update to refresh.",
+    "set -euo pipefail",
+    "unset GIT_DIR GIT_INDEX_FILE GIT_WORK_TREE GIT_COMMON_DIR GIT_PREFIX \\",
+    "      GIT_OBJECT_DIRECTORY GIT_ALTERNATE_OBJECT_DIRECTORIES",
+    `export ${HOOK_INVOCATION_ENV}=${HOOK_INVOCATION_VALUE}`,
+    `exec bunx --bun @agentsfleet/orly@${version} gate ${gate}`,
+    "",
+  ].join("\n");
+}

package/src/installation/lock.test.ts

@@ -0,0 +1,97 @@
+import { afterEach, expect, test } from "bun:test";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { cleanupTemporaryDirectories, newRepository, ROOT } from "../gates_test_support";
+import { UNSCOPED_ENVIRONMENT } from "../git_env";
+import { installationLock } from "./lock";
+
+const LOCK_MODULE = join(ROOT, "src/installation/lock.ts");
+const LOCK_PATH = ".orly/install.lock";
+
+afterEach(cleanupTemporaryDirectories);
+
+function leaveStaleLock(root: string): void {
+  const result = Bun.spawnSync([process.execPath, "-e", `import {installationLock} from ${JSON.stringify(LOCK_MODULE)}; installationLock(process.argv[1]);`, root], {
+    env: UNSCOPED_ENVIRONMENT, stdout: "pipe", stderr: "pipe", timeout: 5000,
+  });
+  expect(result.exitCode, result.stderr.toString()).toBe(0);
+}
+
+test("stale cleanup cannot remove a lock acquired by another installer", () => {
+  const root = newRepository();
+  leaveStaleLock(root);
+  const actor = join(root, "actor.ts");
+  writeFileSync(actor, `import * as fs from "node:fs";
+import {join} from "node:path";
+import {installationLock} from ${JSON.stringify(LOCK_MODULE)};
+const root=Bun.argv[2];
+const release=installationLock(root);
+fs.writeFileSync(join(root,"ready"),String(process.pid));
+const until=performance.now()+5000;
+while(!fs.existsSync(join(root,"stop")) && performance.now()<until) await Bun.sleep(10);
+try {release();} catch(error) {console.error(String(error));}
+`);
+  const contender = join(root, "contender.ts");
+  writeFileSync(contender, `import * as fs from "node:fs";
+import {join} from "node:path";
+import {mock} from "bun:test";
+const root=Bun.argv[2];
+let other;
+let attempted=false;
+const unlink=fs.unlinkSync;
+mock.module("node:fs",()=>({...fs,unlinkSync(path) {
+  if(!attempted) {
+    attempted=true;
+    other=Bun.spawn([process.execPath,${JSON.stringify(actor)},root],{stdout:"pipe",stderr:"pipe"});
+    const until=performance.now()+3000;
+    while(!fs.existsSync(join(root,"ready")) && performance.now()<until) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)),0,0,10);
+    if(!fs.existsSync(join(root,"ready"))) throw new Error("contender did not reach acquisition");
+  }
+  unlink(path);
+}}));
+const {installationLock}=await import(${JSON.stringify(LOCK_MODULE)});
+let acquired=false;
+let release;
+try {release=installationLock(root);acquired=true;} catch {}
+console.log(JSON.stringify({acquired,otherAcquired:fs.existsSync(join(root,"ready")),attempted}));
+if(release) release();
+fs.writeFileSync(join(root,"stop"),"stop");
+if(other) await other.exited;
+`);
+  const result = Bun.spawnSync([process.execPath, contender, root], {
+    env: UNSCOPED_ENVIRONMENT, stdout: "pipe", stderr: "pipe", timeout: 10_000,
+  });
+  expect(result.exitCode, result.stderr.toString()).toBe(0);
+  const observed = JSON.parse(result.stdout.toString());
+  expect(observed.attempted).toBe(true);
+  expect(observed.otherAcquired).toBe(true);
+  expect(observed.acquired).toBe(false);
+  expect(existsSync(join(root, LOCK_PATH))).toBe(false);
+});
+
+test("a live owner excludes contenders and a released lock can be acquired again", () => {
+  const root = newRepository();
+  const release = installationLock(root);
+  expect(() => installationLock(root)).toThrow("another installation");
+  release();
+  installationLock(root)();
+  expect(existsSync(join(root, LOCK_PATH))).toBe(false);
+});
+
+test("a dead owner can be recovered without changing unrelated owner files", () => {
+  const root = newRepository();
+  const owner = join(root, "owner-note");
+  writeFileSync(owner, "owner data");
+  leaveStaleLock(root);
+  installationLock(root)();
+  expect(readFileSync(owner, "utf8")).toBe("owner data");
+  expect(existsSync(join(root, LOCK_PATH))).toBe(false);
+});
+
+test("an unrecognized lock file is preserved for owner inspection", () => {
+  const root = newRepository();
+  mkdirSync(join(root, ".orly"));
+  writeFileSync(join(root, LOCK_PATH), "owner data");
+  expect(() => installationLock(root)).toThrow("inspect it");
+  expect(readFileSync(join(root, LOCK_PATH), "utf8")).toBe("owner data");
+});

package/src/installation/lock.ts

@@ -0,0 +1,56 @@
+import { randomUUID } from "node:crypto";
+import { lstatSync, mkdirSync, readdirSync, readFileSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { assertWritableInside, OrlyError } from "../model";
+
+const LOCK = ".orly/install.lock";
+const ENCODING = "utf8";
+const OWNER_NAME = /^(\d+)\.[a-f0-9-]{36}$/;
+const INCOMPLETE = "installation lock is incomplete; inspect it before removing it";
+const PRIVATE_DIRECTORY_MODE = 0o700;
+const PRIVATE_FILE_MODE = 0o600;
+
+function isCode(error: unknown, code: string): boolean {
+  return error instanceof Error && "code" in error && error.code === code;
+}
+
+function recoverDeadOwner(root: string, path: string): void {
+  if (!lstatSync(path).isDirectory()) throw new OrlyError(INCOMPLETE);
+  const entries = readdirSync(path);
+  const owner = entries.length === 1 ? entries[0]! : "";
+  const match = OWNER_NAME.exec(owner);
+  if (!match) throw new OrlyError(INCOMPLETE);
+  const ownerPath = join(path, owner);
+  assertWritableInside(root, `${LOCK}/${owner}`, "installation lock owner");
+  const pid = Number(match[1]);
+  if (!Number.isSafeInteger(pid) || pid <= 0 || !lstatSync(ownerPath).isFile() || readFileSync(ownerPath, ENCODING) !== String(pid)) throw new OrlyError(INCOMPLETE);
+  try { process.kill(pid, 0); throw new OrlyError("another installation owns this repository"); }
+  catch (error) { if (!isCode(error, "ESRCH")) throw error; }
+  // A replacement owner has a different filename. Losing this exact removal
+  // race stops recovery before it can remove the replacement directory.
+  unlinkSync(ownerPath);
+  rmdirSync(path);
+}
+
+export function installationLock(root: string): () => void {
+  assertWritableInside(root, LOCK, "installation lock");
+  mkdirSync(join(root, ".orly"), { recursive: true });
+  const path = join(root, LOCK);
+  try { mkdirSync(path, { mode: PRIVATE_DIRECTORY_MODE }); }
+  catch (error) {
+    if (!isCode(error, "EEXIST")) throw error;
+    recoverDeadOwner(root, path);
+    mkdirSync(path, { mode: PRIVATE_DIRECTORY_MODE });
+  }
+  const ownerPath = join(path, `${process.pid}.${randomUUID()}`);
+  try { writeFileSync(ownerPath, String(process.pid), { flag: "wx", mode: PRIVATE_FILE_MODE }); }
+  catch (error) {
+    rmdirSync(path);
+    throw error;
+  }
+  return () => {
+    if (readFileSync(ownerPath, ENCODING) !== String(process.pid)) throw new OrlyError("installation lock ownership changed");
+    unlinkSync(ownerPath);
+    rmdirSync(path);
+  };
+}