@de-otio/repo-aegis-core 0.2.0

package/src/trust-boundary.test.ts

@@ -0,0 +1,198 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, rmSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  computeTrustBoundary,
+  trustBoundariesOverlap,
+} from "./trust-boundary.js";
+import type { Registry, Engagement } from "./registry.js";
+
+let tmp: string;
+
+before(() => {
+  tmp = realpathSync(mkdtempSync(join(tmpdir(), "repo-aegis-tb-")));
+});
+
+after(() => {
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+function makeRepo(
+  name: string,
+  opts: { remote?: string; class?: string; engagements?: string[] } = {},
+): string {
+  const dir = join(tmp, name);
+  mkdirSync(dir);
+  execFileSync("git", ["init", "-q", "--initial-branch=main", dir], { stdio: "ignore" });
+  if (opts.remote) {
+    execFileSync("git", ["-C", dir, "config", "remote.origin.url", opts.remote], {
+      stdio: "ignore",
+    });
+  }
+  if (opts.class) {
+    execFileSync("git", ["-C", dir, "config", "repo-aegis.class", opts.class], {
+      stdio: "ignore",
+    });
+  }
+  for (const eng of opts.engagements ?? []) {
+    execFileSync("git", ["-C", dir, "config", "--add", "repo-aegis.engagement", eng], {
+      stdio: "ignore",
+    });
+  }
+  return dir;
+}
+
+function makeRegistry(
+  engagements: Engagement[],
+  personalOrgs: string[] = [],
+): Registry {
+  return {
+    engagements,
+    alwaysBlock: [],
+    personalOrgs,
+    schemaVersion: 2,
+  };
+}
+
+const E_ALPHA: Engagement = {
+  id: "alpha",
+  name: "Alpha",
+  markers: [],
+  githubOrgs: ["alpha-org", "alpha-mirror"],
+};
+const E_BETA: Engagement = {
+  id: "beta",
+  name: "Beta",
+  markers: [],
+  githubOrgs: ["beta-org"],
+};
+
+describe("computeTrustBoundary", () => {
+  it("derives orgs from a single allow'd engagement", () => {
+    const repo = makeRepo("ct-cust", {
+      remote: "git@github.com:alpha-org/foo.git",
+      class: "customer-coupled",
+      engagements: ["alpha"],
+    });
+    const reg = makeRegistry([E_ALPHA, E_BETA]);
+    const tb = computeTrustBoundary(repo, reg);
+    assert.deepEqual([...tb.orgs].sort(), ["alpha-mirror", "alpha-org"]);
+    assert.equal(tb.fromRemoteFallback, false);
+    assert.equal(tb.class, "customer-coupled");
+  });
+
+  it("union'd orgs across multiple allow'd engagements", () => {
+    const repo = makeRepo("ct-multi", {
+      remote: "git@github.com:alpha-org/x.git",
+      class: "customer-coupled",
+      engagements: ["alpha", "beta"],
+    });
+    const reg = makeRegistry([E_ALPHA, E_BETA]);
+    const tb = computeTrustBoundary(repo, reg);
+    assert.deepEqual([...tb.orgs].sort(), ["alpha-mirror", "alpha-org", "beta-org"]);
+  });
+
+  it("public-eligible picks up personalOrgs", () => {
+    const repo = makeRepo("ct-pub", {
+      remote: "git@github.com:de-otio/foo.git",
+      class: "public-eligible",
+    });
+    const reg = makeRegistry([E_ALPHA], ["de-otio", "personal2"]);
+    const tb = computeTrustBoundary(repo, reg);
+    assert.deepEqual([...tb.orgs].sort(), ["de-otio", "personal2"]);
+    assert.equal(tb.fromRemoteFallback, false);
+  });
+
+  it("falls back to the remote when classification is empty", () => {
+    const repo = makeRepo("ct-fallback", {
+      remote: "git@github.com:de-otio/foo.git",
+      // No class, no engagements: defaults to private-strict.
+    });
+    const reg = makeRegistry([E_ALPHA]);
+    const tb = computeTrustBoundary(repo, reg);
+    assert.deepEqual([...tb.orgs], ["de-otio"]);
+    assert.equal(tb.fromRemoteFallback, true);
+    assert.equal(tb.class, "private-strict");
+    assert.equal(tb.classExplicit, false);
+  });
+
+  it("returns an empty set when there's no remote and no classification", () => {
+    const repo = makeRepo("ct-bare");
+    const reg = makeRegistry([E_ALPHA]);
+    const tb = computeTrustBoundary(repo, reg);
+    assert.equal(tb.orgs.size, 0);
+    assert.equal(tb.fromRemoteFallback, false);
+  });
+
+  it("classification beats remote (forks)", () => {
+    // Repo's remote is the customer org but it's allow'd into the
+    // personal world (e.g. an internal mirror of an upstream).
+    const repo = makeRepo("ct-fork", {
+      remote: "git@github.com:alpha-org/x.git",
+      class: "public-eligible",
+    });
+    const reg = makeRegistry([E_ALPHA], ["de-otio"]);
+    const tb = computeTrustBoundary(repo, reg);
+    assert.deepEqual([...tb.orgs], ["de-otio"]);
+    assert.equal(tb.fromRemoteFallback, false);
+  });
+});
+
+describe("trustBoundariesOverlap", () => {
+  const reg = makeRegistry([E_ALPHA, E_BETA], ["de-otio"]);
+
+  it("returns true when both repos sit in the same engagement orgs", () => {
+    const a = makeRepo("ov-a", { class: "customer-coupled", engagements: ["alpha"] });
+    const b = makeRepo("ov-b", { class: "customer-coupled", engagements: ["alpha"] });
+    assert.ok(trustBoundariesOverlap(computeTrustBoundary(a, reg), computeTrustBoundary(b, reg)));
+  });
+
+  it("returns true when repos share at least one githubOrg via different engagements", () => {
+    // Engagement γ shares one org with α
+    const E_GAMMA: Engagement = {
+      id: "gamma",
+      name: "Gamma",
+      markers: [],
+      githubOrgs: ["alpha-mirror", "gamma-org"],
+    };
+    const reg2 = makeRegistry([E_ALPHA, E_GAMMA]);
+    const a = makeRepo("ov-shared-a", { class: "customer-coupled", engagements: ["alpha"] });
+    const b = makeRepo("ov-shared-b", { class: "customer-coupled", engagements: ["gamma"] });
+    assert.ok(trustBoundariesOverlap(computeTrustBoundary(a, reg2), computeTrustBoundary(b, reg2)));
+  });
+
+  it("returns false when engagements have disjoint orgs", () => {
+    const a = makeRepo("ov-x", { class: "customer-coupled", engagements: ["alpha"] });
+    const b = makeRepo("ov-y", { class: "customer-coupled", engagements: ["beta"] });
+    assert.ok(!trustBoundariesOverlap(computeTrustBoundary(a, reg), computeTrustBoundary(b, reg)));
+  });
+
+  it("returns false when one side is personal and the other customer-coupled", () => {
+    const a = makeRepo("ov-pers", {
+      remote: "git@github.com:de-otio/x.git",
+      class: "public-eligible",
+    });
+    const b = makeRepo("ov-cust", {
+      class: "customer-coupled",
+      engagements: ["alpha"],
+    });
+    assert.ok(!trustBoundariesOverlap(computeTrustBoundary(a, reg), computeTrustBoundary(b, reg)));
+  });
+
+  it("returns false when both sides have empty boundaries", () => {
+    const a = makeRepo("ov-empty-a");
+    const b = makeRepo("ov-empty-b");
+    assert.ok(!trustBoundariesOverlap(computeTrustBoundary(a, reg), computeTrustBoundary(b, reg)));
+  });
+
+  it("matches via remote fallback when neither repo is classified but they share an org", () => {
+    const a = makeRepo("ov-r-a", { remote: "git@github.com:de-otio/x.git" });
+    const b = makeRepo("ov-r-b", { remote: "git@github.com:de-otio/y.git" });
+    assert.ok(trustBoundariesOverlap(computeTrustBoundary(a, reg), computeTrustBoundary(b, reg)));
+  });
+});

package/src/trust-boundary.ts

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+//
+// Trust-boundary computation for the path-aware PostToolUse hook.
+//
+// Two working trees are in the same trust boundary if their derived
+// org sets overlap. The org set for a working tree is:
+//
+//   (engagements[*].githubOrgs of every engagement the repo is
+//    allow'd into)
+//   ∪ (personalOrgs, if class === public-eligible)
+//   ∪ (remote-origin org, if the above is empty)
+//
+// The classification is the source of truth (per design open question
+// #3): a fork's remote may belong to one org while the classification
+// declares the canonical engagement-org mapping. The remote is only
+// consulted as a last-resort fallback for completely unclassified repos.
+
+import { readRepoConfig, type RepoClass } from "./repo.js";
+import { type Registry } from "./registry.js";
+import { getRemoteOrg } from "./working-tree.js";
+
+export interface TrustBoundary {
+  /** Set of GitHub orgs that span this repo's trust boundary. */
+  orgs: Set<string>;
+  /**
+   * True when `orgs` came from the git remote because no
+   * classification could supply orgs. The hook surfaces this as
+   * `DEST_UNCLASSIFIED` when the destination tree is in this state.
+   */
+  fromRemoteFallback: boolean;
+  /** The repo's resolved class (private-strict if unclassified). */
+  class: RepoClass;
+  /** True if class came from explicit git config / `.repo-aegis.yml`. */
+  classExplicit: boolean;
+}
+
+/**
+ * Compute the trust boundary for a working tree against a registry.
+ *
+ * Reads `git config repo-aegis.class` / `.repo-aegis.yml` for the
+ * working tree (via {@link readRepoConfig}), pulls the relevant
+ * `githubOrgs` arrays out of the registry, and falls back to the
+ * remote URL only when the classification supplies no orgs.
+ */
+export function computeTrustBoundary(
+  workingTree: string,
+  registry: Registry,
+): TrustBoundary {
+  const repo = readRepoConfig(workingTree);
+  const orgs = new Set<string>();
+
+  // Engagement-derived orgs.
+  for (const engId of repo.engagements) {
+    const eng = registry.engagements.find(e => e.id === engId);
+    if (!eng) continue;
+    for (const org of eng.githubOrgs ?? []) {
+      orgs.add(org.toLowerCase());
+    }
+  }
+
+  // public-eligible repos sit on every personal org. The model says
+  // "this repo is not customer-coupled, so anything in personalOrgs
+  // is its peer."
+  if (repo.class === "public-eligible") {
+    for (const org of registry.personalOrgs ?? []) {
+      orgs.add(org.toLowerCase());
+    }
+  }
+
+  let fromRemoteFallback = false;
+  if (orgs.size === 0) {
+    const remoteOrg = getRemoteOrg(workingTree);
+    if (remoteOrg !== null) {
+      orgs.add(remoteOrg);
+      fromRemoteFallback = true;
+    }
+  }
+
+  return {
+    orgs,
+    fromRemoteFallback,
+    class: repo.class,
+    classExplicit: repo.classExplicit,
+  };
+}
+
+/**
+ * Two trust boundaries overlap iff their org sets share at least one
+ * element. Two empty sets do NOT overlap — that's the "neither side
+ * has any signal" case, which the policy layer treats as
+ * "scan-with-warning" rather than silently allowing.
+ */
+export function trustBoundariesOverlap(a: TrustBoundary, b: TrustBoundary): boolean {
+  if (a.orgs.size === 0 || b.orgs.size === 0) return false;
+  for (const o of a.orgs) if (b.orgs.has(o)) return true;
+  return false;
+}

package/src/types.ts

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+// Central type re-export. Every module in core defines its own types, but
+// downstream consumers (cli, scan) should import from `@de-otio/repo-aegis-core`
+// (which re-exports everything via index.ts). This file just makes sure the
+// canonical TypeScript types are aggregated in one place for ease of review.
+
+export type { Engagement, Registry, ResolveResult } from "./registry.js";
+export type { RepoClass, RepoConfig } from "./repo.js";
+export type { DenySet, DenySetFile, DenySetOptions } from "./deny-set.js";
+export type { ScanHit, SkippedFile, ScanOptions } from "./scan.js";
+export type { RenderOptions, RenderedFile, RenderResult } from "./render.js";
+export type { PatternValidationResult } from "./regex-safety.js";
+export type { RedactionMode } from "./redaction.js";
+
+/**
+ * Canonical JSON shape for a repo across every CLI subcommand's output.
+ * Consumers of repo-aegis (other tools, AI agents) parse this once and
+ * reuse across allow/deny/status/check.
+ *
+ * `engagements` is **deliberately a list of bare ids** (`string[]`), not
+ * a list of {@link EngagementJson}. RepoJson describes the per-repo
+ * configured membership recorded by `git config --get-all
+ * repo-aegis.engagement` — it is the *reference set*, not a hydrated view
+ * of registry state. Resolving an id to its registry entry (name, active
+ * flag) is the consumer's responsibility, and the canonical hydrated
+ * shape is {@link EngagementJson}, which appears as a sibling field on
+ * commands that perform that resolution (allow, deny, status). The two
+ * are intentionally distinct and must not be conflated.
+ */
+export interface RepoJson {
+  cwd: string;
+  isGitRepo: boolean;
+  class: import("./repo.js").RepoClass;
+  classExplicit: boolean;
+  engagements: string[];
+}
+
+/**
+ * Canonical JSON shape for an engagement reference in CLI output.
+ * Includes only the fields needed to identify and act on the engagement;
+ * full {@link Engagement} bodies (with markers) are never emitted to JSON
+ * outputs that flow through hook context.
+ *
+ * Relationship to {@link RepoJson}: `RepoJson.engagements` is `string[]`
+ * (the per-repo membership of bare ids); commands that hydrate those ids
+ * against the registry (e.g. `allow`, `deny`, `status`) emit a separate
+ * sibling field of type `EngagementJson` (or `EngagementJson[]`) with the
+ * resolved name + active flag. The shapes are not interchangeable.
+ */
+export interface EngagementJson {
+  id: string;
+  name: string;
+  active: boolean;
+}

package/src/working-tree.test.ts

@@ -0,0 +1,193 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  symlinkSync,
+  rmSync,
+  realpathSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  findEnclosingWorkingTree,
+  resolveGitDir,
+  getRemoteOrg,
+} from "./working-tree.js";
+
+let tmp: string;
+
+before(() => {
+  tmp = realpathSync(mkdtempSync(join(tmpdir(), "repo-aegis-wt-")));
+});
+
+after(() => {
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+function gitInit(dir: string): void {
+  execFileSync("git", ["init", "-q", "--initial-branch=main", dir], { stdio: "ignore" });
+}
+
+function gitConfig(dir: string, key: string, value: string): void {
+  execFileSync("git", ["-C", dir, "config", key, value], { stdio: "ignore" });
+}
+
+function commitNothing(dir: string): void {
+  // Need at least one commit before `git worktree add`.
+  gitConfig(dir, "user.email", "test@example.com");
+  gitConfig(dir, "user.name", "Test");
+  writeFileSync(join(dir, "README.md"), "x");
+  execFileSync("git", ["-C", dir, "add", "README.md"], { stdio: "ignore" });
+  execFileSync("git", ["-C", dir, "commit", "-q", "-m", "initial"], { stdio: "ignore" });
+}
+
+describe("findEnclosingWorkingTree", () => {
+  it("finds the enclosing working tree of a file in a regular repo", () => {
+    const repo = join(tmp, "regular");
+    mkdirSync(repo);
+    gitInit(repo);
+    const file = join(repo, "src", "foo.ts");
+    mkdirSync(join(repo, "src"));
+    writeFileSync(file, "x");
+    assert.equal(findEnclosingWorkingTree(file), repo);
+  });
+
+  it("finds the working tree from a nested subdirectory", () => {
+    const repo = join(tmp, "nested");
+    mkdirSync(repo);
+    gitInit(repo);
+    const deep = join(repo, "a", "b", "c");
+    mkdirSync(deep, { recursive: true });
+    const file = join(deep, "deep.ts");
+    writeFileSync(file, "x");
+    assert.equal(findEnclosingWorkingTree(file), repo);
+  });
+
+  it("returns the worktree (not the parent repo) for a git worktree", () => {
+    const main = join(tmp, "main-repo");
+    mkdirSync(main);
+    gitInit(main);
+    commitNothing(main);
+    const wt = join(tmp, "wt-feature");
+    execFileSync("git", ["-C", main, "worktree", "add", "-q", "-b", "feat", wt], {
+      stdio: "ignore",
+    });
+    const file = join(wt, "newfile.ts");
+    writeFileSync(file, "x");
+    assert.equal(findEnclosingWorkingTree(file), wt);
+  });
+
+  it("returns null for a path outside any git repo", () => {
+    const outside = join(tmp, "no-git");
+    mkdirSync(outside);
+    writeFileSync(join(outside, "loose.txt"), "x");
+    assert.equal(findEnclosingWorkingTree(join(outside, "loose.txt")), null);
+  });
+
+  it("follows symlinks (resolves to the destination's working tree)", () => {
+    const repo = join(tmp, "sym-target");
+    mkdirSync(repo);
+    gitInit(repo);
+    const target = join(repo, "real.ts");
+    writeFileSync(target, "x");
+    const linkDir = join(tmp, "sym-link");
+    mkdirSync(linkDir);
+    const link = join(linkDir, "alias.ts");
+    symlinkSync(target, link);
+    // Even though `link` lives outside `repo`, realpath resolves to
+    // inside `repo`, and that's what we apply rules to.
+    assert.equal(findEnclosingWorkingTree(link), repo);
+  });
+
+  it("works when the file does not yet exist (walks up to first existing ancestor)", () => {
+    const repo = join(tmp, "no-file");
+    mkdirSync(repo);
+    gitInit(repo);
+    const ghost = join(repo, "src", "not-yet.ts");
+    // Don't create the file or its dir.
+    assert.equal(findEnclosingWorkingTree(ghost), repo);
+  });
+});
+
+describe("resolveGitDir", () => {
+  it("returns <wt>/.git for a regular repo", () => {
+    const repo = join(tmp, "rgd-regular");
+    mkdirSync(repo);
+    gitInit(repo);
+    const gitDir = resolveGitDir(repo);
+    assert.equal(gitDir, join(repo, ".git"));
+  });
+
+  it("resolves the linked gitdir for a worktree", () => {
+    const main = join(tmp, "rgd-main");
+    mkdirSync(main);
+    gitInit(main);
+    commitNothing(main);
+    const wt = join(tmp, "rgd-wt");
+    execFileSync("git", ["-C", main, "worktree", "add", "-q", "-b", "feat", wt], {
+      stdio: "ignore",
+    });
+    const gitDir = resolveGitDir(wt);
+    assert.ok(gitDir !== null);
+    // Should point to <main>/.git/worktrees/<name>
+    assert.match(gitDir!, /worktrees/);
+  });
+
+  it("returns null when .git is missing", () => {
+    const dir = join(tmp, "rgd-bare");
+    mkdirSync(dir);
+    assert.equal(resolveGitDir(dir), null);
+  });
+});
+
+describe("getRemoteOrg", () => {
+  it("parses GitHub HTTPS URLs", () => {
+    const repo = join(tmp, "remote-https");
+    mkdirSync(repo);
+    gitInit(repo);
+    gitConfig(repo, "remote.origin.url", "https://github.com/Foo-Org/Bar.git");
+    assert.equal(getRemoteOrg(repo), "foo-org");
+  });
+
+  it("parses GitHub SSH URLs", () => {
+    const repo = join(tmp, "remote-ssh");
+    mkdirSync(repo);
+    gitInit(repo);
+    gitConfig(repo, "remote.origin.url", "git@github.com:de-otio/repo-aegis.git");
+    assert.equal(getRemoteOrg(repo), "de-otio");
+  });
+
+  it("parses ssh-config-alias URLs (`github.com-personal`)", () => {
+    const repo = join(tmp, "remote-alias");
+    mkdirSync(repo);
+    gitInit(repo);
+    gitConfig(repo, "remote.origin.url", "git@github.com-personal:de-otio/foo.git");
+    assert.equal(getRemoteOrg(repo), "de-otio");
+  });
+
+  it("returns null when there is no origin remote", () => {
+    const repo = join(tmp, "remote-none");
+    mkdirSync(repo);
+    gitInit(repo);
+    assert.equal(getRemoteOrg(repo), null);
+  });
+
+  it("returns null for a non-GitHub remote", () => {
+    const repo = join(tmp, "remote-non-gh");
+    mkdirSync(repo);
+    gitInit(repo);
+    gitConfig(repo, "remote.origin.url", "https://gitlab.com/x/y.git");
+    assert.equal(getRemoteOrg(repo), null);
+  });
+
+  it("returns null when the directory is not a working tree", () => {
+    const dir = join(tmp, "remote-bare");
+    mkdirSync(dir);
+    assert.equal(getRemoteOrg(dir), null);
+  });
+});

package/src/working-tree.ts

@@ -0,0 +1,130 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+//
+// Working-tree resolution for the path-aware PostToolUse hook.
+//
+// Given an arbitrary file path the agent just wrote, find the git
+// working tree it lives in (regular repo, worktree, or submodule), so
+// the hook can apply *that* repo's classification + deny set rather
+// than the launcher's cwd.
+//
+// Pure-ish: stat/realpath the path's ancestors; for org resolution,
+// shells out to `git config --file <wt>/.git/config` (or the worktree's
+// resolved gitdir/config). Total — never throws.
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { parseRemoteUrl } from "./remote-url.js";
+
+const MAX_ANCESTOR_HOPS = 64;
+
+/**
+ * Walk up from `startPath` until a directory containing `.git` (file or
+ * dir) is found. Returns the working tree root (the directory holding
+ * the `.git` entry), or `null` if none found within
+ * {@link MAX_ANCESTOR_HOPS} hops.
+ *
+ * Both git-worktree files (`.git` is a file containing `gitdir: ...`)
+ * and submodule `.git` files are recognised — the working tree is the
+ * directory containing the file in either case. The actual gitdir is
+ * resolved separately via {@link resolveGitDir}.
+ *
+ * `startPath` is realpath'd first to defeat symlink-tricks: a symlink
+ * inside repo A pointing to a file in repo B resolves to repo B, and
+ * the hook applies repo B's rules — not repo A's.
+ */
+export function findEnclosingWorkingTree(startPath: string): string | null {
+  let real: string;
+  try {
+    // Resolve as much of the path as exists. If the file itself doesn't
+    // exist (rare in PostToolUse — the write just happened — but
+    // possible if the file was concurrently removed), walk up to the
+    // first existing ancestor and realpath that.
+    real = realpathExisting(startPath);
+  } catch {
+    return null;
+  }
+
+  let cur = statSync(real).isDirectory() ? real : dirname(real);
+  for (let i = 0; i < MAX_ANCESTOR_HOPS; i++) {
+    const dotGit = join(cur, ".git");
+    if (existsSync(dotGit)) return cur;
+    const parent = dirname(cur);
+    if (parent === cur) return null;
+    cur = parent;
+  }
+  return null;
+}
+
+function realpathExisting(p: string): string {
+  let cur = resolve(p);
+  // Walk up until we find a path that exists (or hit /).
+  for (let i = 0; i < MAX_ANCESTOR_HOPS; i++) {
+    if (existsSync(cur)) return realpathSync(cur);
+    const parent = dirname(cur);
+    if (parent === cur) throw new Error("path has no existing ancestor");
+    cur = parent;
+  }
+  throw new Error("path has no existing ancestor within hop budget");
+}
+
+/**
+ * Given a working-tree root (from {@link findEnclosingWorkingTree}),
+ * return the absolute path of the actual git directory.
+ *
+ * - Regular repo: `<wt>/.git` is a directory; return that.
+ * - Worktree / submodule: `<wt>/.git` is a file with `gitdir: <path>`;
+ *   resolve `<path>` relative to `<wt>` and return the absolute form.
+ * - Anything else (`.git` missing, malformed `gitdir:` line): `null`.
+ *
+ * Used to find the right `config` file to read remotes from.
+ */
+export function resolveGitDir(workingTree: string): string | null {
+  const dotGit = join(workingTree, ".git");
+  if (!existsSync(dotGit)) return null;
+  const st = statSync(dotGit);
+  if (st.isDirectory()) return dotGit;
+  if (!st.isFile()) return null;
+
+  let body: string;
+  try {
+    body = readFileSync(dotGit, "utf8");
+  } catch {
+    return null;
+  }
+  // Format: `gitdir: <path>\n`. The path may be relative to the .git
+  // file's directory.
+  const m = /^gitdir:\s*(.+?)\s*$/m.exec(body);
+  if (!m || !m[1]) return null;
+  const target = m[1];
+  return resolve(workingTree, target);
+}
+
+/**
+ * Read `remote.origin.url` from the working tree's git config and
+ * return the GitHub org (lowercased), or `null` if no remote, the
+ * remote isn't GitHub, or anything fails.
+ *
+ * Total: never throws. Used by the hook to decide whether a
+ * cross-tree write stays inside one trust boundary.
+ */
+export function getRemoteOrg(workingTree: string): string | null {
+  const gitDir = resolveGitDir(workingTree);
+  if (gitDir === null) return null;
+  const configPath = join(gitDir, "config");
+  if (!existsSync(configPath)) return null;
+  let url: string;
+  try {
+    url = execFileSync(
+      "git",
+      ["config", "--file", configPath, "--get", "remote.origin.url"],
+      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
+    ).trim();
+  } catch {
+    return null;
+  }
+  if (url.length === 0) return null;
+  const parsed = parseRemoteUrl(url);
+  return parsed?.org ?? null;
+}