@clossys/launcher 0.3.1 → 0.4.0

package/dist/observe-repository.js

@@ -0,0 +1,1367 @@
+// Observing one local clone as a RepositoryObservation (RFC apply-approved-plan
+// §7 V4 and V7, issue #1178): the read side of the apply planner. It reports
+// the committed head of a clean clone, as the clone's object database stores
+// it, whose origin is the repository the inventory id names, and nothing else. The clone's working tree is never
+// read: every byte comes from a git object at the head commit, so an edit that
+// is not committed, or a file that is ignored, is not observed.
+//
+// The clone is untrusted content, and the rule is: this repository's own object
+// database and refs are read through git plumbing, never the working tree and
+// never an alternate object store, `commondir` or submodule repository;
+// anything unusual is refused, not interpreted. Its `.git/config` is read as
+// data, never executed, and refused unless every key is one a plain clone
+// carries; a clone that names an alternate object store, or holds a split
+// index's shared file (git rewrites its mtime on every index read), is refused;
+// only then does a git command run inside it, with every hook, filesystem
+// monitor and pager switched off. git inside the clone reads no configuration but the
+// vetted `.git/config` and fixed `-c` overrides: the system and global
+// configuration and the environment's configuration variables are pinned or
+// removed. What the object database holds is trusted to match its ids, as the
+// clone's object database stores it. The committed
+// tree is listed, and a submodule refused, before any command that reads the
+// working tree runs, and none of those considers a submodule. The origin's tip
+// is asked with `git ls-remote`, which writes no ref and no object, from a
+// directory outside the clone. It performs no write to the clone, and none
+// anywhere except one empty scratch directory under the system temporary
+// directory, removed before it returns. The clone is not locked, and the checks
+// are not repeated after the reads: a process that changes the clone in
+// between goes unnoticed, which changes nothing reported, since every byte is
+// an object at the remote tip's commit (see the README's declared limits).
+//
+// Anything that cannot be established is a skip with a reason id, never a
+// guess. A skip is `violated` when the clone is what it must not be (dirty,
+// on another branch, behind or ahead of the origin, hostile), and
+// `indeterminate` when this module could not tell. It never throws for what a
+// repository contains; a port that throws is a skip too.
+import { spawnSync } from "node:child_process";
+import { accessSync, constants, lstatSync, mkdtempSync, readdirSync, realpathSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { delimiter, dirname, isAbsolute, join } from "node:path";
+import { PACKAGE_SCOPE } from "./generated/package-scope.generated.js";
+import { LEDGER_PATH, SKILLS_MANIFEST_PATH, TEMPLATE_PATHS, compareCodeUnits, compareTuples, contentDigest, matchesPathPattern } from "./change-set-contract.js";
+import { parseGitHubRemote } from "./core.js";
+import { sameRepository } from "./identity.js";
+import { readInstalledLedger } from "./ledger-contract.js";
+import { isUnreadable, readLockfile } from "./lockfile-readers.js";
+import { loadContract } from "./plan-contract.js";
+import { wouldViolateRootEntries } from "./root-entries.js";
+import { editReleaseAgeExemption } from "./release-age-edit.js";
+import { isSupportedStarterVersion } from "./setup-templates.js";
+/** Every reason an observation is skipped, with the verdict it carries. */
+const SKIPS = {
+    "clone-missing": "indeterminate",
+    "clone-unreadable": "indeterminate",
+    "id-owner-unknown": "indeterminate",
+    "remote-tip-unreadable": "indeterminate",
+    "node-id-unavailable": "indeterminate",
+    "visibility-unavailable": "indeterminate",
+    "tree-too-large": "indeterminate",
+    "submodule-present": "indeterminate",
+    "manifest-unreadable": "indeterminate",
+    "lockfile-ambiguous": "indeterminate",
+    "package-manager-unknown": "indeterminate",
+    "lockfile-unreadable": "indeterminate",
+    "release-age-surface-invalid": "indeterminate",
+    "agents-link-unreportable": "indeterminate",
+    "observation-too-large": "indeterminate",
+    "case-variant-owned-path": "indeterminate",
+    "ledger-unreadable": "indeterminate",
+    "profile-ambiguous": "indeterminate",
+    "invalid-id": "violated",
+    "clone-config-unsafe": "violated",
+    "origin-mismatch": "violated",
+    "not-on-default-branch": "violated",
+    "remote-tip-mismatch": "violated",
+    "working-tree-dirty": "violated",
+    "package-manager-conflict": "violated",
+};
+/** Ends the observation with a skip; caught in observeRepository() and nowhere else. */
+class Refusal extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+    }
+}
+function refuse(reason) {
+    throw new Refusal(reason);
+}
+const KIB = 1024;
+const MIB = 1024 * KIB;
+const GIT_TIMEOUT_MS = 60_000;
+const SMALL_OUTPUT = MIB;
+const MAX_TREE_BYTES = 64 * MIB;
+const MAX_TREE_ENTRIES = 200_000;
+const MAX_BLOB_BYTES = 4 * MIB;
+const MAX_LOCKFILE_BYTES = 32 * MIB;
+const MAX_READ_BYTES = 64 * MIB;
+const MAX_OWNED_FILES = 5000;
+const MAX_JSON_DEPTH = 256;
+const ID_PATTERN = /^(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?\/)?(?!\.\.?$)[A-Za-z0-9._-]+$/u;
+const OWNER_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/u;
+const NODE_ID_PATTERN = /^[A-Za-z0-9_=+/-]+$/u;
+const OBJECT_ID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/u;
+const BRANCH_SHAPE = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/u;
+const INTEGRITY = /^sha512-[A-Za-z0-9+/]{86}==$/u;
+const EXACT_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/u;
+const PACKAGE_MANAGER_FIELD = /^(npm|pnpm|yarn)@\S+$/u;
+const AGENTS_LINK = /^\.agents(?:\/skills(?:\/clossys-[^/\\\u0000-\u001f]+)?)?$/u;
+const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const SHA256_HEX = /^[0-9a-f]{64}$/u;
+const CONTROL = /[\u0000-\u001f\u007f]/u;
+const LOCKFILES = [
+    { name: "package-lock.json", manager: "npm" },
+    { name: "pnpm-lock.yaml", manager: "pnpm" },
+    { name: "yarn.lock", manager: "yarn" },
+];
+/** Lockfiles of managers this module does not read: their presence makes the package manager ambiguous. */
+const OTHER_LOCKFILES = ["npm-shrinkwrap.json", "bun.lock", "bun.lockb"];
+const RELEASE_AGE_SURFACES = [
+    { surface: "pnpm-workspace", path: "pnpm-workspace.yaml" },
+    { surface: "yarnrc", path: ".yarnrc.yml" },
+    { surface: "npmrc", path: ".npmrc" },
+];
+const DISCOVERY = [".claude/skills", ".cursor/skills"];
+const PROFILE_ROOTS = ["clossys", ".agents", ".claude", ".cursor"];
+/** The roots a setup set adds beside them: its workflows and scripts, and its Starter request. */
+const SETUP_PROFILE_ROOTS = [".github", ".starter"];
+const NPMRC_PATH = ".npmrc";
+const PNPM_WORKSPACE_PATH = "pnpm-workspace.yaml";
+const PROFILE_NAMES = new Set(["repository-profile.json", "repository-declaration.json"]);
+const PROFILE_FIRST = "governance/repository-profile.json";
+const PROFILE_SKIPPED_DIRECTORIES = new Set([".git", "node_modules", "dist", "build", ".next", "coverage", ".turbo", ".cache"]);
+const STARTER = `${PACKAGE_SCOPE.scope}/starter`;
+// ---- git ------------------------------------------------------------------
+const GIT_OPTIONS = [
+    "-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null", "-c", "core.pager=cat", "-c", "core.untrackedCache=false", "-c", "protocol.ext.allow=never", "--no-pager",
+];
+/** Variables that would point git at another repository, object store or configuration than the clone's own. */
+const GIT_REMOVED_ENV = [
+    "GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_OBJECT_DIRECTORY", "GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_COMMON_DIR", "GIT_NAMESPACE", "GIT_REPLACE_REF_BASE", "GIT_GRAFT_FILE",
+    "GIT_SHALLOW_FILE", "GIT_CONFIG_PARAMETERS", "GIT_CONFIG_SYSTEM", "GIT_ATTR_SOURCE", "GIT_EXTERNAL_DIFF",
+];
+/**
+ * The configuration variables `git ls-remote` alone receives: `GIT_CONFIG_COUNT`
+ * and the numbered key and value variables it reads. They are the operator's own
+ * environment, the same trust as the global git config file `ls-remote` keeps,
+ * and they cannot loosen a fixed `-c` override or `GIT_ALLOW_PROTOCOL`, which
+ * both win over them.
+ */
+const GIT_COUNTED_CONFIG_ENV = /^GIT_CONFIG_(?:COUNT|(?:KEY|VALUE)_.*)$/iu;
+/** git's own test switches (`GIT_TEST_SPLIT_INDEX` forces a split index on an index write, for one): never passed on to any git command. */
+const GIT_TEST_ENV = /^GIT_TEST_/iu;
+/** The transports a fetch may use when the default origin parser named the origin: exactly the two GitHub serves. */
+const REMOTE_PROTOCOLS = "https:ssh";
+/**
+ * The git executable as an absolute path, found once per PATH value among the
+ * entries that are absolute and not empty. An empty entry, or a relative one,
+ * would search the directory git runs in, and for a command run inside the
+ * clone that directory is the repository's own content.
+ */
+let resolvedGit = null;
+function gitBinary() {
+    const searched = process.env.PATH ?? process.env.Path ?? "";
+    if (resolvedGit !== null && resolvedGit.searched === searched)
+        return resolvedGit.binary;
+    const name = process.platform === "win32" ? "git.exe" : "git";
+    let binary = null;
+    for (const directory of searched.split(delimiter)) {
+        if (directory === "" || !isAbsolute(directory))
+            continue;
+        const candidate = join(directory, name);
+        try {
+            if (!statSync(candidate).isFile())
+                continue;
+            accessSync(candidate, constants.X_OK);
+            binary = candidate;
+            break;
+        }
+        catch {
+            continue;
+        }
+    }
+    resolvedGit = { searched, binary };
+    return binary;
+}
+/**
+ * git inside the clone reads no configuration but the vetted `.git/config` and
+ * fixed `-c` overrides: the system and global configuration are switched off,
+ * and every other source the environment names is removed
+ * (`GIT_CONFIG_COUNT` and its numbered key and value variables,
+ * `GIT_CONFIG_PARAMETERS`, `GIT_CONFIG_SYSTEM`). `ls-remote`, which runs outside
+ * the clone, keeps the operator's global and system git config files
+ * (credential helpers, proxy) and is given `GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_n`
+ * and `GIT_CONFIG_VALUE_n`, so an origin that needs credentials supplied through
+ * them is observed; `GIT_CONFIG_PARAMETERS` (git's own encoding of `-c` for its
+ * children, not an interface) and `GIT_CONFIG_SYSTEM` are not forwarded to it,
+ * and an origin that needs either is skipped as `remote-tip-unreadable`. git's
+ * `GIT_TEST_*` switches reach no command.
+ */
+function gitEnvironment(cwd, protocols, remote) {
+    const env = { ...process.env };
+    for (const name of GIT_REMOVED_ENV)
+        delete env[name];
+    for (const name of Object.keys(env)) {
+        if (GIT_TEST_ENV.test(name) || (!remote && GIT_COUNTED_CONFIG_ENV.test(name)))
+            delete env[name];
+    }
+    return {
+        ...env,
+        ...(remote ? {} : { GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null" }),
+        GIT_TERMINAL_PROMPT: "0",
+        GIT_OPTIONAL_LOCKS: "0",
+        GIT_NO_REPLACE_OBJECTS: "1",
+        GIT_NO_LAZY_FETCH: "1",
+        GIT_PAGER: "cat",
+        GIT_ALLOW_PROTOCOL: protocols,
+        // A repository above `cwd` is never discovered: a directory beside the clone cannot stand in for it.
+        GIT_CEILING_DIRECTORIES: dirname(cwd),
+        LC_ALL: "C",
+    };
+}
+function git(cwd, args, maxBuffer = SMALL_OUTPUT, protocols = REMOTE_PROTOCOLS, remote = false) {
+    const binary = gitBinary();
+    if (binary === null)
+        return { status: -1, stdout: Buffer.alloc(0), overflow: false };
+    const run = spawnSync(binary, [...GIT_OPTIONS, ...args], {
+        cwd,
+        env: gitEnvironment(cwd, protocols, remote),
+        shell: false,
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: GIT_TIMEOUT_MS,
+        maxBuffer,
+        encoding: "buffer",
+        windowsHide: true,
+    });
+    const overflow = run.error?.code === "ENOBUFS";
+    return { status: run.error === undefined ? (run.status ?? -1) : -1, stdout: run.stdout ?? Buffer.alloc(0), overflow };
+}
+function gitText(cwd, args) {
+    const run = git(cwd, args);
+    return run.status === 0 && !run.overflow ? run.stdout.toString("utf8") : null;
+}
+// ---- the id and the clone ---------------------------------------------------
+function checkId(id, hubOwner) {
+    if (!ID_PATTERN.test(id))
+        refuse("invalid-id");
+    if (!id.includes("/") && (hubOwner === undefined || !OWNER_PATTERN.test(hubOwner)))
+        refuse("id-owner-unknown");
+}
+/** The clone's real path, once it is a real directory holding a real `.git` directory of its own, with an object database of its own. */
+function locateClone(clone) {
+    const stat = statOf(clone, "clone-missing");
+    if (!stat.isDirectory())
+        refuse("clone-unreadable");
+    const gitDir = join(clone, ".git");
+    if (!statOf(gitDir, "clone-unreadable").isDirectory())
+        refuse("clone-unreadable");
+    // A regular config file, and no `commondir` redirecting git to another directory's configuration.
+    if (!statOf(join(gitDir, "config"), "clone-unreadable").isFile())
+        refuse("clone-unreadable");
+    if (isPresent(join(gitDir, "commondir")))
+        refuse("clone-unreadable");
+    // Objects that are the clone's own: a real directory, and no list of other stores to read from.
+    if (!statOf(join(gitDir, "objects"), "clone-unreadable").isDirectory())
+        refuse("clone-unreadable");
+    for (const name of ["alternates", "http-alternates"])
+        if (isPresent(join(gitDir, "objects", "info", name)))
+            refuse("clone-config-unsafe");
+    // A split index: git freshens the shared file's mtime on every index read, which would be a write to the clone.
+    if (holdsSharedIndex(gitDir))
+        refuse("clone-config-unsafe");
+    try {
+        return realpathSync(clone);
+    }
+    catch {
+        return refuse("clone-unreadable");
+    }
+}
+/** Whether the git directory holds a `sharedindex.*` entry of any type, by listing it: no shell glob, and no git command. */
+function holdsSharedIndex(gitDir) {
+    try {
+        return readdirSync(gitDir).some((name) => name.toLowerCase().startsWith("sharedindex."));
+    }
+    catch {
+        return refuse("clone-unreadable");
+    }
+}
+/** Whether anything, of any type, is at `path`; an error other than absence is a refusal. */
+function isPresent(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch (cause) {
+        const code = cause.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return false;
+        return refuse("clone-unreadable");
+    }
+}
+function statOf(path, absent) {
+    try {
+        const stat = lstatSync(path);
+        if (stat.isSymbolicLink())
+            refuse("clone-unreadable");
+        return stat;
+    }
+    catch (cause) {
+        if (cause instanceof Refusal)
+            throw cause;
+        const code = cause.code;
+        return refuse(code === "ENOENT" || code === "ENOTDIR" ? absent : "clone-unreadable");
+    }
+}
+const CONFIG_CORE = new Set(["repositoryformatversion", "filemode", "bare", "logallrefupdates", "ignorecase", "precomposeunicode", "symlinks"]);
+const CONFIG_REMOTE = new Set(["url", "fetch", "gh-resolved"]);
+const CONFIG_BRANCH = new Set(["remote", "merge", "rebase", "vscode-merge-base", "github-pr-owner-number"]);
+const CONFIG_USER = new Set(["name", "email"]);
+function readConfig(clone, neutral) {
+    const run = git(neutral, ["config", "--file", join(clone, ".git", "config"), "--no-includes", "--list", "-z"]);
+    if (run.status !== 0 || run.overflow)
+        return refuse("clone-unreadable");
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(run.stdout);
+    }
+    catch {
+        return refuse("clone-config-unsafe");
+    }
+    const records = text.split("\0");
+    if (records.pop() !== "")
+        return refuse("clone-unreadable");
+    return records.map((record) => {
+        const newline = record.indexOf("\n");
+        return newline === -1 ? { key: record, value: null } : { key: record.slice(0, newline), value: record.slice(newline + 1) };
+    });
+}
+/** Whether a key is one a plain clone carries. What is not recognised is refused: the set of keys that run something is unbounded. */
+function isPlainCloneKey({ key, value }) {
+    const first = key.indexOf(".");
+    const last = key.lastIndexOf(".");
+    if (first < 1 || last === key.length - 1)
+        return false;
+    const section = key.slice(0, first).toLowerCase();
+    const variable = key.slice(last + 1).toLowerCase();
+    const subsection = first === last ? null : key.slice(first + 1, last);
+    if (section === "core") {
+        if (subsection !== null || !CONFIG_CORE.has(variable))
+            return false;
+        if (variable === "repositoryformatversion")
+            return value === "0";
+        if (variable === "bare")
+            return value === "false";
+        return true;
+    }
+    if (section === "user")
+        return subsection === null && CONFIG_USER.has(variable);
+    if (subsection === null || subsection === "")
+        return false;
+    if (section === "remote")
+        return CONFIG_REMOTE.has(variable);
+    if (section === "branch")
+        return CONFIG_BRANCH.has(variable);
+    return false;
+}
+function checkConfig(entries) {
+    if (!entries.every(isPlainCloneKey))
+        refuse("clone-config-unsafe");
+}
+// ---- origin and the remote tip -------------------------------------------------
+function originUrl(entries) {
+    const urls = entries.filter((entry) => entry.key === "remote.origin.url");
+    const only = urls.length === 1 ? urls[0].value : null;
+    // git would read a value that is padded or holds a control character as a different URL than the mapper judged.
+    if (only === null || only === "" || only !== only.trim() || CONTROL.test(only))
+        return refuse("origin-mismatch");
+    return only;
+}
+/** The exact forms of a GitHub origin: https, scp-style ssh and `ssh://`, with an owner and a name and nothing more. */
+const GITHUB_HTTPS = /^https:\/\/github\.com\/([^/?#@:\s]+)\/([^/?#@:\s]+)$/u;
+const GITHUB_SSH = /^(?:git@github\.com:|ssh:\/\/git@github\.com\/)([^/?#@:\s]+)\/([^/?#@:\s]+)$/u;
+/** An origin URL as `owner/name` when it is exactly an https or ssh GitHub URL; any other scheme, host, port, user, extra path, query or fragment is null. */
+export function defaultOriginId(url) {
+    const match = GITHUB_HTTPS.exec(url) ?? GITHUB_SSH.exec(url);
+    if (match === null)
+        return null;
+    const parsed = parseGitHubRemote(`https://github.com/${match[1]}/${match[2]}`);
+    return parsed === null ? null : `${parsed.owner}/${parsed.repository}`;
+}
+function checkOrigin(url, id, hubOwner, originId) {
+    let named;
+    try {
+        named = originId(url);
+    }
+    catch {
+        return refuse("origin-mismatch");
+    }
+    if (typeof named !== "string" || !ID_PATTERN.test(named) || !named.includes("/") || !sameRepository(named, id, hubOwner))
+        refuse("origin-mismatch");
+}
+function safeBranch(branch) {
+    if (!BRANCH_SHAPE.test(branch) || /[:+*]/u.test(branch))
+        return false;
+    return !branch.includes("..") && !branch.includes("//") && !branch.endsWith("/") && !branch.includes(".lock");
+}
+/** The origin's default branch and its tip, from `git ls-remote`: it writes no ref and no object anywhere. */
+function remoteTip(url, neutral, protocols) {
+    const run = git(neutral, ["ls-remote", "--symref", "--", url, "HEAD"], SMALL_OUTPUT, protocols, true);
+    if (run.status !== 0 || run.overflow)
+        return refuse("remote-tip-unreadable");
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(run.stdout);
+    }
+    catch {
+        return refuse("remote-tip-unreadable");
+    }
+    const symrefs = [];
+    const oids = [];
+    for (const line of text.split("\n")) {
+        if (line === "")
+            continue;
+        const symref = /^ref: (\S+)\t(\S+)$/u.exec(line);
+        const oid = /^([0-9a-f]+)\t(\S+)$/u.exec(line);
+        if (symref !== null) {
+            if (symref[2] === "HEAD")
+                symrefs.push(symref[1]);
+        }
+        else if (oid !== null) {
+            if (oid[2] === "HEAD")
+                oids.push(oid[1]);
+        }
+        else
+            return refuse("remote-tip-unreadable");
+    }
+    const target = symrefs.length === 1 ? symrefs[0] : "";
+    const branch = target.startsWith("refs/heads/") ? target.slice("refs/heads/".length) : "";
+    const tip = oids.length === 1 ? oids[0] : "";
+    if (!safeBranch(branch) || !OBJECT_ID.test(tip))
+        return refuse("remote-tip-unreadable");
+    return { branch, oid: tip };
+}
+// ---- the local clone against the remote tip ----------------------------------------
+/** git's own view of the clone: its work tree is `clone`, its git directory is `clone/.git`, and it is not bare. Runs only after the configuration passed. */
+function checkRepositoryShape(clone) {
+    const text = gitText(clone, ["rev-parse", "--show-toplevel", "--is-bare-repository", "--absolute-git-dir"]);
+    const lines = text === null ? [] : text.split("\n");
+    if (lines.length !== 4 || lines[3] !== "")
+        return refuse("clone-unreadable");
+    try {
+        if (realpathSync(lines[0]) !== clone || lines[1] !== "false" || realpathSync(lines[2]) !== join(clone, ".git"))
+            refuse("clone-unreadable");
+    }
+    catch (cause) {
+        if (cause instanceof Refusal)
+            throw cause;
+        refuse("clone-unreadable");
+    }
+}
+function checkHead(clone, tip) {
+    const symbolic = git(clone, ["symbolic-ref", "-q", "HEAD"]);
+    if (symbolic.status === 1)
+        refuse("not-on-default-branch");
+    if (symbolic.status !== 0 || symbolic.overflow)
+        refuse("clone-unreadable");
+    if (symbolic.stdout.toString("utf8").trim() !== `refs/heads/${tip.branch}`)
+        refuse("not-on-default-branch");
+    const head = git(clone, ["rev-parse", "--verify", "-q", `refs/heads/${tip.branch}^{commit}`]);
+    const local = head.status === 0 && !head.overflow ? head.stdout.toString("utf8").trim() : "";
+    if (!OBJECT_ID.test(local))
+        refuse("clone-unreadable");
+    if (local !== tip.oid)
+        refuse("remote-tip-mismatch");
+}
+/**
+ * The index, read as data: no entry is a submodule, and none carries a flag
+ * that hides an edit from `git status` (skip-worktree, assume-unchanged) or is
+ * unmerged. Reads the index file only, and neither the working tree nor a
+ * submodule.
+ */
+function checkIndex(clone) {
+    const run = git(clone, ["ls-files", "-v", "-s", "-z"], MAX_TREE_BYTES);
+    if (run.overflow)
+        refuse("tree-too-large");
+    if (run.status !== 0)
+        refuse("clone-unreadable");
+    let submodule = false;
+    let hidden = false;
+    let position = 0;
+    while (position < run.stdout.length) {
+        let end = run.stdout.indexOf(0, position);
+        if (end === -1)
+            end = run.stdout.length;
+        const record = run.stdout.subarray(position, end);
+        position = end + 1;
+        const tab = record.indexOf(9);
+        const header = tab === -1 ? null : INDEX_HEADER.exec(record.subarray(0, tab).toString("latin1"));
+        if (header === null)
+            return refuse("clone-unreadable");
+        const [, tag, mode, stage] = header;
+        if (mode === "160000")
+            submodule = true;
+        // `H` is a cached entry with nothing hidden; anything else is a flag that keeps status from looking.
+        if (tag !== "H" || stage !== "0")
+            hidden = true;
+    }
+    if (submodule)
+        refuse("submodule-present");
+    if (hidden)
+        refuse("working-tree-dirty");
+}
+const INDEX_HEADER = /^(\S) (\d{6}) (?:[0-9a-f]{40}|[0-9a-f]{64}) (\d)$/u;
+/** Runs after the tree was listed and checkIndex refused a submodule: it never considers one, since git would open its own repository and read its configuration. */
+function checkClean(clone) {
+    const run = git(clone, ["status", "--porcelain=v1", "-z", "--untracked-files=all", "--ignore-submodules=all"], 16 * MIB);
+    // Output past the bound is output: a status that long is not clean.
+    if (run.overflow || (run.status === 0 && run.stdout.length > 0))
+        refuse("working-tree-dirty");
+    if (run.status !== 0)
+        refuse("clone-unreadable");
+}
+// ---- ports ---------------------------------------------------------------------------
+async function readPorts(id, ports) {
+    let nodeId;
+    try {
+        nodeId = await ports.nodeId(id);
+    }
+    catch {
+        return refuse("node-id-unavailable");
+    }
+    if (typeof nodeId !== "string" || !NODE_ID_PATTERN.test(nodeId))
+        return refuse("node-id-unavailable");
+    let visibility;
+    try {
+        visibility = await ports.visibility(id);
+    }
+    catch {
+        return refuse("visibility-unavailable");
+    }
+    if (visibility !== "private" && visibility !== "internal" && visibility !== "public")
+        return refuse("visibility-unavailable");
+    return { nodeId, visibility };
+}
+const LS_TREE_HEADER = /^(\d{6}) (blob|commit) ([0-9a-f]{40}|[0-9a-f]{64}) +(\d+|-)$/u;
+const REGULAR_MODES = new Set(["100644", "100755"]);
+function isRegular(entry) {
+    return entry !== null && REGULAR_MODES.has(entry.mode);
+}
+function listTree(clone, commit) {
+    const run = git(clone, ["ls-tree", "-r", "-z", "-l", "--full-tree", commit], MAX_TREE_BYTES);
+    if (run.overflow)
+        return refuse("tree-too-large");
+    if (run.status !== 0)
+        return refuse("clone-unreadable");
+    const entries = [];
+    const root = { children: new Map(), entry: null };
+    const out = run.stdout;
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    let submodule = false;
+    let position = 0;
+    while (position < out.length) {
+        let end = out.indexOf(0, position);
+        if (end === -1)
+            end = out.length;
+        if (entries.length >= MAX_TREE_ENTRIES)
+            return refuse("tree-too-large");
+        const record = out.subarray(position, end);
+        position = end + 1;
+        const tab = record.indexOf(9);
+        const header = tab === -1 ? null : LS_TREE_HEADER.exec(record.subarray(0, tab).toString("latin1"));
+        if (header === null)
+            return refuse("clone-unreadable");
+        const [, mode, type, oid, size] = header;
+        let path;
+        try {
+            path = decoder.decode(record.subarray(tab + 1));
+        }
+        catch {
+            return refuse("clone-unreadable");
+        }
+        if (mode === "160000" && type === "commit") {
+            submodule = true;
+            entries.push({ path, mode, oid, size: 0 });
+            continue;
+        }
+        if (type !== "blob" || size === "-" || (mode !== "100644" && mode !== "100755" && mode !== "120000"))
+            return refuse("clone-unreadable");
+        const entry = { path, mode, oid, size: Number(size) };
+        insertEntry(root, entry);
+        entries.push(entry);
+    }
+    if (submodule)
+        return refuse("submodule-present");
+    return { entries, root };
+}
+function insertEntry(root, entry) {
+    let node = root;
+    for (const segment of entry.path.split("/")) {
+        // A file and a directory at one path, or one path twice, is a tree git would not have written.
+        if (node.entry !== null)
+            refuse("clone-unreadable");
+        let child = node.children.get(segment);
+        if (child === undefined) {
+            child = { children: new Map(), entry: null };
+            node.children.set(segment, child);
+        }
+        node = child;
+    }
+    if (node.entry !== null || node.children.size > 0)
+        refuse("clone-unreadable");
+    node.entry = entry;
+}
+/** The node at exactly `path`, or null. */
+function nodeAt(tree, path) {
+    let node = tree.root;
+    for (const segment of path.split("/")) {
+        node = node.children.get(segment);
+        if (node === undefined)
+            return null;
+    }
+    return node;
+}
+function lookup(tree, path) {
+    const node = nodeAt(tree, path);
+    if (node === null)
+        return { kind: "absent" };
+    return isRegular(node.entry) ? { kind: "regular", entry: node.entry } : { kind: "other" };
+}
+// ---- letter case ------------------------------------------------------------------------------
+/**
+ * How a case-insensitive or normalising file system may read a name: each
+ * segment decomposed, case-folded through both cases, decomposed again, and
+ * without trailing dots and spaces.
+ */
+export function fold(path) {
+    return path
+        .split("/")
+        .map((segment) => {
+        const folded = segment.normalize("NFD").toLowerCase().toUpperCase().toLowerCase().normalize("NFD");
+        // A loop, not a pattern: `/[. ]+$/` retries from every dot or space of a long run.
+        let end = folded.length;
+        while (end > 0 && (folded[end - 1] === "." || folded[end - 1] === " "))
+            end -= 1;
+        return folded.slice(0, end);
+    })
+        .join("/");
+}
+/** The read of the packed contract that INTRODUCIBLE_ROOTS makes, kept whole: every path the apply flow may own. */
+const OWNED_PATTERNS = (() => {
+    const definitions = loadContract("repository-change-set.json").definitions;
+    const patterns = definitions?.ownedPattern?.allOf?.[1]?.enum;
+    if (!Array.isArray(patterns) || !patterns.every((entry) => typeof entry === "string"))
+        throw new Error("the packed change-set contract has no ownedPattern list");
+    return patterns;
+})();
+function patternSet(patterns) {
+    return {
+        patterns: patterns.map((pattern) => {
+            const segments = pattern.split("/");
+            return { pattern, first: segments[0], last: segments[segments.length - 1] };
+        }),
+    };
+}
+const OWNED = patternSet(OWNED_PATTERNS);
+const OWNED_FOLDED = patternSet(OWNED_PATTERNS.map(fold));
+/** Whether `path` matches any pattern; a literal first or last segment of a pattern is checked first, only to avoid matching every path against every pattern. */
+function matchesAny(path, set) {
+    const segments = path.split("/");
+    const last = segments[segments.length - 1];
+    return set.patterns.some(({ pattern, first, last: tail }) => {
+        if (first !== "**" && !first.includes("*") && first !== segments[0])
+            return false;
+        if (tail !== "**" && !tail.includes("*") && tail !== last)
+            return false;
+        return matchesPathPattern(path, pattern);
+    });
+}
+/** Whether `entry` is a link `linkedAgentsPaths` reports under its folded name, so it is reported there rather than refused here. */
+function isReportedAgentsLink(entry) {
+    if (entry.mode !== "120000")
+        return false;
+    const parts = fold(entry.path).split("/");
+    return parts.length === 3 && parts[0] === ".agents" && parts[1] === "skills" && parts[2].startsWith("clossys-");
+}
+/** Every file, link and (through its files) directory beneath `node`, and the node's own entry. */
+function entriesUnder(node) {
+    const found = [];
+    const stack = [node];
+    for (let next = stack.pop(); next !== undefined; next = stack.pop()) {
+        if (next.entry !== null)
+            found.push(next.entry);
+        stack.push(...next.children.values());
+    }
+    return found;
+}
+/**
+ * What the head holds at the flow's own paths, by exact spelling, whatever its
+ * type: a file or a link is listed, and a directory is listed by every file
+ * under it, so that the path reads as occupied and is never planned over. A path
+ * that is not the flow's own, but reads as one where letter case or a trailing
+ * dot is not told apart, is refused: a write to one could land on the other.
+ */
+function ownedEntries(tree) {
+    const owned = new Map();
+    const folded = new Set();
+    const stack = [];
+    for (const [name, node] of tree.root.children)
+        stack.push({ path: name, node, covered: false });
+    for (let item = stack.pop(); item !== undefined; item = stack.pop()) {
+        const { path, node } = item;
+        let covered = item.covered;
+        if (matchesAny(path, OWNED)) {
+            const key = fold(path);
+            if (folded.has(key))
+                refuse("case-variant-owned-path");
+            folded.add(key);
+            if (!covered)
+                for (const entry of entriesUnder(node))
+                    owned.set(entry.path, entry);
+            covered = true;
+        }
+        else if (matchesAny(fold(path), OWNED_FOLDED) && !(node.entry !== null && isReportedAgentsLink(node.entry)))
+            refuse("case-variant-owned-path");
+        for (const [name, child] of node.children)
+            stack.push({ path: `${path}/${name}`, node: child, covered });
+    }
+    return [...owned.values()].sort((left, right) => compareCodeUnits(left.path, right.path));
+}
+/** Root names whose case variants are refused: the roots the flow adds, and the two it writes into. */
+const CASE_GUARDED_ROOTS = [...PROFILE_ROOTS, ".github", ".starter"];
+/**
+ * Two root entries that differ only by letter case (or by normalisation form or a
+ * trailing dot) are one name on a file system that does not tell them apart, and
+ * a variant of a root the flow adds stands in for it in every check that looks
+ * for the root by name. The roots the flow adds are refused for any spelling but
+ * their own; `.github` and `.starter` only when two spellings are present.
+ */
+function checkRootNames(tree) {
+    const spellings = new Map();
+    for (const name of tree.root.children.keys()) {
+        const key = fold(name);
+        const held = spellings.get(key);
+        if (held === undefined)
+            spellings.set(key, [name]);
+        else
+            held.push(name);
+    }
+    for (const root of CASE_GUARDED_ROOTS) {
+        const names = spellings.get(fold(root)) ?? [];
+        if (names.length > 1 || (PROFILE_ROOTS.includes(root) && names.length === 1 && names[0] !== root))
+            refuse("case-variant-owned-path");
+    }
+}
+/** Every node whose path is `segments` when each name is folded, with the spelling it has: a directory may have several spellings at once. */
+function variantsAt(tree, segments) {
+    let level = [{ name: "", node: tree.root }];
+    for (const segment of segments) {
+        const wanted = fold(segment);
+        const next = [];
+        for (const { node } of level)
+            for (const [name, child] of node.children)
+                if (fold(name) === wanted)
+                    next.push({ name, node: child });
+        level = next;
+    }
+    return level;
+}
+/** Whether a node, or a node above it along `segments` under any spelling, is a symbolic link. */
+function anySymlinkOnPath(tree, segments) {
+    for (let length = 1; length <= segments.length; length += 1) {
+        if (variantsAt(tree, segments.slice(0, length)).some(({ node }) => node.entry?.mode === "120000"))
+            return true;
+    }
+    return false;
+}
+// ---- blobs ------------------------------------------------------------------------------------
+/** Reads blobs of the committed tree by object id, each path once, within the total the observation may read. */
+class BlobReader {
+    clone;
+    cache = new Map();
+    total = 0;
+    constructor(clone) {
+        this.clone = clone;
+    }
+    /** The blob's exact bytes; `over` is the skip when it is larger than `cap`. */
+    read(entry, cap, over) {
+        const cached = this.cache.get(entry.path);
+        if (cached !== undefined)
+            return cached;
+        if (entry.size > cap)
+            refuse(over);
+        if (this.total + entry.size > MAX_READ_BYTES)
+            refuse("observation-too-large");
+        const run = git(this.clone, ["cat-file", "blob", entry.oid], entry.size + 1);
+        // The listed size and the bytes must agree, or the object is not the one the tree named.
+        if (run.status !== 0 || run.overflow || run.stdout.length !== entry.size)
+            refuse("clone-unreadable");
+        this.total += entry.size;
+        this.cache.set(entry.path, run.stdout);
+        return run.stdout;
+    }
+}
+/**
+ * The digest of a file's bytes exactly as materialize computes one: the bytes
+ * are read as UTF-8 text, a sequence that is not UTF-8 becoming U+FFFD, and that
+ * text is hashed (`readFileSync(path, "utf8")` on disk, `git show` decoded as
+ * UTF-8 on a ref, and the same for a link's target). Hashing the raw bytes would
+ * give a different digest for a file that is not UTF-8.
+ */
+function digestOf(bytes) {
+    return contentDigest(bytes.toString("utf8"));
+}
+// ---- strict JSON ------------------------------------------------------------------------------
+/** UTF-8 text, or null. A byte order mark is kept as U+FEFF, which strict JSON refuses. */
+function decodeUtf8(bytes) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether `text` is JSON with no object that repeats a key, at any depth
+ * (keys compared after decoding their escapes). JSON.parse takes the last of
+ * two equal keys, so it alone would read a document another reader reads
+ * differently.
+ */
+function isStrictJson(text) {
+    let at = 0;
+    const number = /-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/uy;
+    const space = () => {
+        while (at < text.length && (text[at] === " " || text[at] === "\t" || text[at] === "\n" || text[at] === "\r"))
+            at += 1;
+    };
+    const string = () => {
+        if (text[at] !== '"')
+            return null;
+        const start = at;
+        at += 1;
+        while (at < text.length) {
+            const code = text.charCodeAt(at);
+            if (code === 0x22) {
+                at += 1;
+                return JSON.parse(text.slice(start, at));
+            }
+            if (code < 0x20)
+                return null;
+            if (code !== 0x5c) {
+                at += 1;
+                continue;
+            }
+            const escape = text[at + 1];
+            if (escape === "u") {
+                if (!/^[0-9a-fA-F]{4}$/u.test(text.slice(at + 2, at + 6)))
+                    return null;
+                at += 6;
+            }
+            else if (escape !== undefined && '"\\/bfnrt'.includes(escape))
+                at += 2;
+            else
+                return null;
+        }
+        return null;
+    };
+    const value = (depth) => {
+        if (depth > MAX_JSON_DEPTH)
+            return false;
+        space();
+        const start = text[at];
+        if (start === "{") {
+            at += 1;
+            space();
+            if (text[at] === "}") {
+                at += 1;
+                return true;
+            }
+            const seen = new Set();
+            for (;;) {
+                space();
+                const key = string();
+                if (key === null || seen.has(key))
+                    return false;
+                seen.add(key);
+                space();
+                if (text[at] !== ":")
+                    return false;
+                at += 1;
+                if (!value(depth + 1))
+                    return false;
+                space();
+                if (text[at] === ",")
+                    at += 1;
+                else if (text[at] === "}") {
+                    at += 1;
+                    return true;
+                }
+                else
+                    return false;
+            }
+        }
+        if (start === "[") {
+            at += 1;
+            space();
+            if (text[at] === "]") {
+                at += 1;
+                return true;
+            }
+            for (;;) {
+                if (!value(depth + 1))
+                    return false;
+                space();
+                if (text[at] === ",")
+                    at += 1;
+                else if (text[at] === "]") {
+                    at += 1;
+                    return true;
+                }
+                else
+                    return false;
+            }
+        }
+        if (start === '"')
+            return string() !== null;
+        for (const literal of ["true", "false", "null"]) {
+            if (text.startsWith(literal, at)) {
+                at += literal.length;
+                return true;
+            }
+        }
+        number.lastIndex = at;
+        const match = number.exec(text);
+        if (match === null)
+            return false;
+        at += match[0].length;
+        return true;
+    };
+    if (!value(0))
+        return false;
+    space();
+    return at === text.length;
+}
+/** The JSON a file holds, or null when it is not UTF-8 text without a byte order mark, holds a repeated key, or is not JSON. */
+function parseStrictJson(bytes) {
+    const text = decodeUtf8(bytes);
+    if (text === null || !isStrictJson(text))
+        return null;
+    try {
+        return { text, value: JSON.parse(text) };
+    }
+    catch {
+        return null;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const PLACEMENTS = ["dependencies", "devDependencies"];
+function readManifest(entry, reader) {
+    const parsed = parseStrictJson(reader.read(entry, MAX_BLOB_BYTES, "manifest-unreadable"));
+    if (parsed === null || !isRecord(parsed.value))
+        return refuse("manifest-unreadable");
+    const manifest = parsed.value;
+    const entries = [];
+    for (const placement of PLACEMENTS) {
+        if (!Object.hasOwn(manifest, placement))
+            continue;
+        const map = manifest[placement];
+        if (!isRecord(map))
+            return refuse("manifest-unreadable");
+        const rows = [];
+        for (const [name, value] of Object.entries(map)) {
+            if (typeof value !== "string")
+                return refuse("manifest-unreadable");
+            rows.push({ placement, name, value });
+        }
+        entries.push(...rows.sort((left, right) => compareCodeUnits(left.name, right.name)));
+    }
+    let declared;
+    if (Object.hasOwn(manifest, "packageManager")) {
+        const field = manifest.packageManager;
+        const match = typeof field === "string" ? PACKAGE_MANAGER_FIELD.exec(field) : null;
+        declared = match === null ? null : match[1];
+    }
+    return { entries, declared };
+}
+/** The lockfile files present at the root, in any spelling, and whether a lockfile of a manager this module does not read is. */
+function rootLockfiles(tree) {
+    return {
+        known: LOCKFILES.filter((lockfile) => variantsAt(tree, [lockfile.name]).length > 0),
+        other: OTHER_LOCKFILES.some((name) => variantsAt(tree, [name]).length > 0),
+    };
+}
+/**
+ * The Starter the lockfile locks must have a lockfile row of that name and
+ * version: not an `npm:` alias, not another package installed under its name,
+ * and not a tarball of another package. Anything else is a lockfile this module
+ * does not interpret. The host and the integrity are the planner's to check.
+ */
+function checkStarterIdentity(view, row, manifest) {
+    const locked = view.entries.find((candidate) => candidate.key === (view.format === "npm" ? `node_modules/${STARTER}` : `${STARTER}@${row.version}`));
+    const written = manifest?.entries.find((candidate) => candidate.placement === row.placement && candidate.name === row.name);
+    const named = locked !== undefined && !locked.link && locked.name === STARTER && locked.installedName === STARTER && locked.version === row.version;
+    const fetched = locked?.tarball == null || locked.tarball.endsWith(`/${STARTER}/-/starter-${row.version}.tgz`);
+    const aliased = row.specifier.startsWith("npm:") || (written !== undefined && written.value !== row.specifier);
+    if (!named || !fetched || aliased)
+        refuse("lockfile-unreadable");
+}
+function lockedPackagesOf(entry, format, reader, manifest) {
+    const text = decodeUtf8(reader.read(entry, MAX_LOCKFILE_BYTES, "lockfile-unreadable"));
+    if (text === null)
+        return refuse("lockfile-unreadable");
+    let view;
+    try {
+        view = readLockfile(format, text);
+    }
+    catch {
+        return refuse("lockfile-unreadable");
+    }
+    if (isUnreadable(view))
+        return refuse("lockfile-unreadable");
+    const seen = new Map();
+    for (const row of view.root) {
+        if ((row.placement !== "dependencies" && row.placement !== "devDependencies") || row.version === null || row.link)
+            continue;
+        if (row.integrity === null || !INTEGRITY.test(row.integrity))
+            continue;
+        if (row.name === STARTER)
+            checkStarterIdentity(view, row, manifest);
+        const key = `${row.name}\0${row.version}`;
+        const held = seen.get(key);
+        // One name and version with two integrity values is a lockfile that says two things.
+        if (held !== undefined && held.integrity !== row.integrity)
+            return refuse("lockfile-unreadable");
+        seen.set(key, { name: row.name, version: row.version, integrity: row.integrity });
+    }
+    return [...seen.values()].sort((left, right) => compareTuples([left.name, left.version], [right.name, right.version]));
+}
+function readPackageState(tree, manifest, reader) {
+    const { known, other } = rootLockfiles(tree);
+    if (manifest === null) {
+        if (known.length > 0 || other)
+            return refuse("package-manager-conflict");
+        return { packageManager: "none", lockfile: "none", lockedPackages: [] };
+    }
+    if (known.length > 1 || other)
+        return refuse("lockfile-ambiguous");
+    const lockfile = known[0];
+    if (lockfile === undefined) {
+        // Nothing but the package.json field decides, and it is not guessed.
+        if (manifest.declared === undefined || manifest.declared === null)
+            return refuse("package-manager-unknown");
+        return { packageManager: manifest.declared, lockfile: "none", lockedPackages: [] };
+    }
+    if (manifest.declared === null)
+        return refuse("package-manager-unknown");
+    if (manifest.declared !== undefined && manifest.declared !== lockfile.manager)
+        return refuse("package-manager-conflict");
+    const found = lookup(tree, lockfile.name);
+    if (found.kind !== "regular" || lockfile.manager === "yarn")
+        return refuse("lockfile-unreadable");
+    return { packageManager: lockfile.manager, lockfile: lockfile.name, lockedPackages: lockedPackagesOf(found.entry, lockfile.manager, reader, manifest) };
+}
+// ---- the other fields ----------------------------------------------------------------------------
+function readReleaseAgeSurfaces(tree) {
+    const found = [];
+    for (const { surface, path } of RELEASE_AGE_SURFACES) {
+        const variants = variantsAt(tree, [path]);
+        if (variants.length === 0)
+            continue;
+        const only = variants[0];
+        if (variants.length > 1 || only.name !== path || !isRegular(only.node.entry))
+            refuse("release-age-surface-invalid");
+        found.push({ surface, path });
+    }
+    return found.sort((left, right) => compareTuples([left.surface, left.path], [right.surface, right.path]));
+}
+/**
+ * Whether a workflow of the repository's own is at the head: a regular file
+ * directly in `.github/workflows`, spelled exactly so (GitHub reads no other
+ * spelling), that is not a `clossys-` file.
+ */
+function hasConsumerCi(tree) {
+    const workflows = nodeAt(tree, ".github/workflows");
+    if (workflows === null)
+        return false;
+    for (const [name, child] of workflows.children) {
+        if (isRegular(child.entry) && /\.ya?ml$/iu.test(name) && !fold(name).startsWith("clossys-"))
+            return true;
+    }
+    return false;
+}
+function readSymlinkedSkillRoots(tree) {
+    return DISCOVERY.filter((root) => anySymlinkOnPath(tree, root.split("/")));
+}
+function readLinkedAgentsPaths(tree) {
+    const linked = new Set();
+    if (anySymlinkOnPath(tree, [".agents"]))
+        linked.add(".agents");
+    if (variantsAt(tree, [".agents", "skills"]).some(({ node }) => node.entry?.mode === "120000"))
+        linked.add(".agents/skills");
+    for (const { node } of variantsAt(tree, [".agents", "skills"])) {
+        for (const [name, child] of node.children) {
+            const folded = fold(name);
+            if (child.entry?.mode === "120000" && folded.startsWith("clossys-"))
+                linked.add(`.agents/skills/${folded}`);
+        }
+    }
+    const paths = [...linked].sort(compareCodeUnits);
+    if (!paths.every((path) => AGENTS_LINK.test(path)))
+        refuse("agents-link-unreportable");
+    return paths;
+}
+function readOwnedFiles(owned, reader) {
+    if (owned.length > MAX_OWNED_FILES)
+        refuse("observation-too-large");
+    const lockfileNames = new Set(LOCKFILES.map((lockfile) => lockfile.name));
+    return owned.map((entry) => ({ path: entry.path, sha256: digestOf(reader.read(entry, lockfileNames.has(entry.path) ? MAX_LOCKFILE_BYTES : MAX_BLOB_BYTES, "observation-too-large")) }));
+}
+function readLedger(tree, reader) {
+    const found = lookup(tree, LEDGER_PATH);
+    if (found.kind === "absent")
+        return null;
+    if (found.kind === "other")
+        return refuse("ledger-unreadable");
+    return new Uint8Array(reader.read(found.entry, MAX_BLOB_BYTES, "observation-too-large"));
+}
+/** The composed-skill manifest's entries, or null when it is absent or is not exactly the shape the flow writes. */
+function readSkillsManifest(tree, reader) {
+    const found = lookup(tree, SKILLS_MANIFEST_PATH);
+    if (found.kind !== "regular")
+        return null;
+    const parsed = parseStrictJson(reader.read(found.entry, MAX_BLOB_BYTES, "observation-too-large"));
+    const document = parsed?.value;
+    if (!isRecord(document) || Object.keys(document).length !== 2 || document.schemaVersion !== 1 || !Array.isArray(document.skills))
+        return null;
+    const skills = [];
+    for (const skill of document.skills) {
+        if (!isRecord(skill) || !hasExactKeys(skill, ["name", "source", "sha256", "version"]))
+            return null;
+        const { name, source, sha256, version } = skill;
+        if (typeof name !== "string" || !SKILL_NAME.test(name) || typeof source !== "string" || typeof version !== "string")
+            return null;
+        if (typeof sha256 !== "string" || !SHA256_HEX.test(sha256) || skills.some((held) => held.name === name))
+            return null;
+        skills.push({ name, sha256 });
+    }
+    return skills.sort((left, right) => compareCodeUnits(left.name, right.name));
+}
+function hasExactKeys(record, keys) {
+    const own = Object.keys(record);
+    return own.length === keys.length && keys.every((key) => Object.hasOwn(record, key));
+}
+/**
+ * The Controller repository profile: the one Controller would locate, its path, and what a set that adds the four roots would break in
+ * it. `setupRoots` are the roots a setup set adds beside them, when the repository is in its setup phase.
+ */
+function readProfile(tree, reader, setupRoots) {
+    const path = locateProfile(tree);
+    if (path === null)
+        return { profile: null, text: null };
+    const unparseable = { profile: { path, rootVocabulary: "unparseable", undeclaredRoots: [], prohibitedRoots: [] }, text: null };
+    const entry = nodeAt(tree, path).entry;
+    if (entry.size > MAX_BLOB_BYTES)
+        return unparseable;
+    const parsed = parseStrictJson(reader.read(entry, MAX_BLOB_BYTES, "observation-too-large"));
+    if (parsed === null)
+        return unparseable;
+    // checkRootNames() refused every spelling but the exact one, so exact presence is presence.
+    const introduced = [...PROFILE_ROOTS, ...setupRoots].filter((root) => !tree.root.children.has(root));
+    const verdict = wouldViolateRootEntries(parsed.value, introduced);
+    if (verdict.verdict === "indeterminate")
+        return unparseable;
+    if (verdict.verdict === "satisfied")
+        return { profile: { path, rootVocabulary: verdict.vocabulary, undeclaredRoots: [], prohibitedRoots: [] }, text: null };
+    return {
+        profile: { path, rootVocabulary: "checked", undeclaredRoots: [...verdict.undeclared], prohibitedRoots: [...verdict.prohibited] },
+        text: verdict.undeclared.length > 0 ? parsed.text : null,
+    };
+}
+/** The path of the profile Controller would locate: `governance/` first, otherwise the one candidate in the tree; null for none. */
+function locateProfile(tree) {
+    const first = lookup(tree, PROFILE_FIRST);
+    if (first.kind === "regular")
+        return PROFILE_FIRST;
+    if (first.kind === "other")
+        return refuse("profile-ambiguous");
+    const candidates = tree.entries.filter((entry) => {
+        const segments = entry.path.split("/");
+        if (!PROFILE_NAMES.has(segments[segments.length - 1]))
+            return false;
+        if (segments.slice(0, -1).some((directory) => PROFILE_SKIPPED_DIRECTORIES.has(directory)))
+            return false;
+        return !entry.path.startsWith(".github/workflows/");
+    });
+    if (candidates.length > 1 || (candidates.length === 1 && !isRegular(candidates[0])))
+        return refuse("profile-ambiguous");
+    return candidates[0]?.path ?? null;
+}
+/** `apply` only when the base carries every proof of an earlier set; any doubt is `setup`. */
+function readPhase(tree, ledger, manifest, locked) {
+    if (ledger === null)
+        return "setup";
+    let readable;
+    try {
+        readable = readInstalledLedger(ledger) !== null;
+    }
+    catch {
+        readable = false;
+    }
+    if (!readable)
+        return "setup";
+    if (!Object.values(TEMPLATE_PATHS).every((paths) => paths.every((path) => lookup(tree, path).kind === "regular")))
+        return "setup";
+    const starters = manifest.filter((entry) => entry.name === STARTER);
+    const version = starters.length === 1 ? starters[0].value : "";
+    // The pin must also be one the setup templates support, or the request they wrote could not have named it.
+    if (!EXACT_VERSION.test(version) || !isSupportedStarterVersion(version))
+        return "setup";
+    return locked.some((pkg) => pkg.name === STARTER && pkg.version === version) ? "apply" : "setup";
+}
+/** The exact text of a regular file at the root, or null when it is absent, not a regular file, or not UTF-8. */
+function readSurfaceText(tree, reader, path) {
+    const found = lookup(tree, path);
+    return found.kind === "regular" ? decodeUtf8(reader.read(found.entry, MAX_BLOB_BYTES, "observation-too-large")) : null;
+}
+/** `files` with the .npmrc's digest added when it is there: a pnpm setup reads it, though the flow never writes it. */
+function withNpmrc(files, tree, reader) {
+    const found = lookup(tree, NPMRC_PATH);
+    if (found.kind !== "regular")
+        return files;
+    return [...files, { path: NPMRC_PATH, sha256: digestOf(reader.read(found.entry, MAX_BLOB_BYTES, "observation-too-large")) }].sort((left, right) => compareCodeUnits(left.path, right.path));
+}
+/**
+ * The root names a setup set adds beyond the four every set adds: the two directories its templates go in, and, for a pnpm
+ * repository with no workspace file, that file when the exemption edit will create it (a conflicting .npmrc refuses the edit, and
+ * then nothing creates it).
+ */
+function setupRoots(tree, packageManager, npmrcText) {
+    const roots = [...SETUP_PROFILE_ROOTS];
+    if (packageManager === "pnpm" && !tree.root.children.has(PNPM_WORKSPACE_PATH) && editReleaseAgeExemption({ surface: "pnpm-workspace", text: null, npmrc: npmrcText }).kind === "edited") {
+        roots.push(PNPM_WORKSPACE_PATH);
+    }
+    return roots;
+}
+/** Everything read from the committed tree, which is the tree at the head commit. */
+function readCommittedHead(clone, tree) {
+    checkRootNames(tree);
+    const owned = ownedEntries(tree);
+    const reader = new BlobReader(clone);
+    const packageJson = lookup(tree, "package.json");
+    if (packageJson.kind === "other")
+        refuse("manifest-unreadable");
+    const manifest = packageJson.kind === "regular" ? readManifest(packageJson.entry, reader) : null;
+    const packages = readPackageState(tree, manifest, reader);
+    const releaseAgeSurfaces = readReleaseAgeSurfaces(tree);
+    const linkedAgentsPaths = readLinkedAgentsPaths(tree);
+    const files = withNpmrc(readOwnedFiles(owned, reader), tree, reader);
+    const ledger = readLedger(tree, reader);
+    const skillsManifest = readSkillsManifest(tree, reader);
+    const manifestEntries = manifest?.entries ?? [];
+    const phase = readPhase(tree, ledger, manifestEntries, packages.lockedPackages);
+    const pnpmWorkspaceText = readSurfaceText(tree, reader, PNPM_WORKSPACE_PATH);
+    const npmrcText = readSurfaceText(tree, reader, NPMRC_PATH);
+    const { profile, text } = readProfile(tree, reader, phase === "setup" ? setupRoots(tree, packages.packageManager, npmrcText) : []);
+    return {
+        phase,
+        packageManager: packages.packageManager,
+        lockfile: packages.lockfile,
+        releaseAgeSurfaces,
+        consumerCi: hasConsumerCi(tree),
+        symlinkedSkillRoots: readSymlinkedSkillRoots(tree),
+        repositoryProfile: profile,
+        linkedAgentsPaths,
+        files,
+        manifestEntries,
+        lockedPackages: packages.lockedPackages,
+        ledger,
+        skillsManifest,
+        repositoryProfileText: text,
+        pnpmWorkspaceText,
+        npmrcText,
+    };
+}
+/**
+ * Observes one clone: the committed head of a clean clone whose origin is the
+ * repository `id` names, or the reason it cannot be observed. Nothing in the
+ * clone is written or executed, and its working tree is not read.
+ */
+export async function observeRepository(input) {
+    const { id, hubOwner, ports } = input;
+    let neutral = null;
+    try {
+        checkId(id, hubOwner);
+        // Objects from a store the clone does not own are refused, as the alternates file that names one is.
+        if ((process.env.GIT_ALTERNATE_OBJECT_DIRECTORIES ?? "") !== "")
+            refuse("clone-unreadable");
+        const clone = locateClone(input.clone);
+        // A directory of its own, outside the clone, for the commands that must not see any repository's configuration.
+        neutral = mkdtempSync(join(tmpdir(), "observe-repository-"));
+        const config = readConfig(clone, neutral);
+        checkConfig(config);
+        checkRepositoryShape(clone);
+        const url = originUrl(config);
+        checkOrigin(url, id, hubOwner, ports.originId ?? defaultOriginId);
+        // The file transport is only for an origin the caller's own mapper named: a local path is never what the default parser names.
+        const tip = remoteTip(url, neutral, ports.originId === undefined ? REMOTE_PROTOCOLS : `${REMOTE_PROTOCOLS}:file`);
+        checkHead(clone, tip);
+        // The object database first: the head tree is listed, and a submodule refused, before any command reads the working tree.
+        const tree = listTree(clone, tip.oid);
+        checkIndex(clone);
+        checkClean(clone);
+        const { nodeId, visibility } = await readPorts(id, ports);
+        const head = readCommittedHead(clone, tree);
+        return { id, nodeId, visibility, defaultBranch: tip.branch, baseCommit: tip.oid, ...head };
+    }
+    catch (cause) {
+        // Anything that is not a named refusal is still not an observation.
+        const reason = cause instanceof Refusal ? cause.reason : "clone-unreadable";
+        return { id, skipped: reason, verdict: SKIPS[reason] };
+    }
+    finally {
+        if (neutral !== null)
+            rmSync(neutral, { recursive: true, force: true });
+    }
+}
+// ---- the committed files, for a caller that writes them elsewhere -------------------------------
+/** The most files a caller may be handed; a tree with more is refused as `tree-too-large`. */
+const MAX_COMMITTED_FILES = 20_000;
+/**
+ * Every file of the tree at `commit`, read as observeRepository() reads a tree: the clone is vetted the same way (a real
+ * `.git` of its own, a `.git/config` of plain keys only, no alternate object store), and then only `ls-tree` and `cat-file` run,
+ * at that commit. Nothing is checked out and no index, ref or worktree is written; the working tree is never read. A submodule,
+ * more than a fixed number of files, or more than the observation's read total is refused, and the reason is one fixed id.
+ */
+export function readCommittedFiles(cloneInput, commit) {
+    let neutral = null;
+    try {
+        if (!OBJECT_ID.test(commit))
+            refuse("clone-unreadable");
+        if ((process.env.GIT_ALTERNATE_OBJECT_DIRECTORIES ?? "") !== "")
+            refuse("clone-unreadable");
+        const clone = locateClone(cloneInput);
+        neutral = mkdtempSync(join(tmpdir(), "observe-repository-"));
+        checkConfig(readConfig(clone, neutral));
+        checkRepositoryShape(clone);
+        const named = git(clone, ["rev-parse", "--verify", "-q", `${commit}^{commit}`]);
+        if (named.status !== 0 || named.overflow || named.stdout.toString("utf8").trim() !== commit)
+            refuse("clone-unreadable");
+        const tree = listTree(clone, commit);
+        if (tree.entries.length > MAX_COMMITTED_FILES)
+            refuse("tree-too-large");
+        if (tree.entries.reduce((sum, entry) => sum + entry.size, 0) > MAX_READ_BYTES)
+            refuse("tree-too-large");
+        const reader = new BlobReader(clone);
+        const files = tree.entries.map((entry) => ({ path: entry.path, mode: entry.mode, bytes: reader.read(entry, MAX_READ_BYTES, "tree-too-large") }));
+        return { ok: true, files };
+    }
+    catch (cause) {
+        return { ok: false, reason: cause instanceof Refusal ? cause.reason : "clone-unreadable" };
+    }
+    finally {
+        if (neutral !== null)
+            rmSync(neutral, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=observe-repository.js.map