approval-md 0.1.0 → 0.3.0

package/dist/src/core/command-class.js

@@ -32,7 +32,23 @@
  * Self-reported text is never read. The hook passes the command only; the
  * harness's `description` field is authored by the very agent being gated
  * (SPEC.md §11.1: self-reported fields never reduce scrutiny).
+ *
+ * Two imports, and both are pure in exactly the same way this file is: no disk,
+ * no clock, no environment, no dependencies.
+ *
+ * `core/read-scope.ts` (APRV-347) holds the read-side path arithmetic, so the
+ * hook and the policy explainer can ask the same questions this file asks, of
+ * the same table, rather than each growing a copy of it.
+ *
+ * `core/policy-match.ts` (APRV-354) is imported for ONE name, the
+ * `harness.launch.` prefix. The classifier emits the family and two enforcement
+ * paths refuse a member of it that no policy rule names, so the three have to
+ * agree on what the family is; a second spelling of the prefix would close one
+ * of those doors and leave the other open. The import is type-safe in the
+ * dependency sense as well: `policy-match.ts` itself imports only types.
  */
+import { HARNESS_LAUNCH_PREFIX } from "./policy-match.js";
+import { READ_OUT_OF_SCOPE_CLASS, isUnreadableTarget, readTargetVerdict, readTargetsOf, } from "./read-scope.js";
 /**
  * The pass-through pseudo-class for the gate's own CLI.
  *
@@ -240,6 +256,46 @@ export function protectedPathClass(candidate, extra = []) {
             if (next === "hooks.json" || next === "hooks" || next === "agents")
                 return "policy.core";
         }
+        // Grok Build's equivalent: `.grok/hooks/*.json` is where its PreToolUse
+        // entries are installed, and the scripts beside them are what those
+        // entries run. Same property as `.cursor/hooks.json` above and for the
+        // same reason (APRV-243): an agent that could write those could write
+        // itself out of the gate. Grok also READS `.claude/settings.json` and
+        // `.cursor/hooks.json` for compatibility, and both are already here.
+        if (segment === ".grok") {
+            const next = segments[index + 1];
+            if (next === "hooks.json" || next === "hooks")
+                return "policy.core";
+        }
+        // Muse Code's equivalent, OBSERVED rather than guessed (APRV-350): the live
+        // probe on muse-bin-1.3.0-R3233.1 established that the installed build reads
+        // `.muse/hooks.json` in the project, and that it rejects a malformed one
+        // loudly at startup. `settings` is listed beside it because Meta documents
+        // user-level hooks inside a `settings.json` `hooks` block, so a
+        // project-level copy would be the same organ under a second name; it never
+        // fired in the probe, and an entry for a file Muse does not read is INERT,
+        // while a missing entry for one it does read would be the hole.
+        //
+        // `worktrees` is deliberately NOT here. Muse keeps its own worktree state
+        // under `.muse/worktrees/`, which is ordinary workspace content: making it
+        // `policy.core` would price routine session bookkeeping at a human's
+        // attention, which is the failure mode §11 asks to avoid.
+        if (segment === ".muse") {
+            const next = segments[index + 1];
+            if (next === "hooks.json" || next === "hooks" || next?.startsWith("settings")) {
+                return "policy.core";
+            }
+        }
+        // Codex installs its hook through these configuration and script paths.
+        if (segment === ".codex") {
+            const next = segments[index + 1];
+            if (next === undefined ||
+                next === "config.toml" ||
+                next === "hooks.json" ||
+                next === "hooks" ||
+                segments.slice(index + 1).includes(".."))
+                return "policy.core";
+        }
     }
     // 3. The policy's own routed entries (APRV-266), above the built-in
     //    `policy.edit` set so a routing can re-label one of those paths, and
@@ -462,6 +518,19 @@ export const NON_SECRET_ENV_NAMES = [
     "APPROVAL_MD",
     "APPROVAL_HOME",
     "APPROVAL_DIR",
+    /**
+     * Where the per-machine bot-ownership registry lives (APRV-390).
+     *
+     * A DIRECTORY PATH, and the same kind of thing `APPROVAL_HOME` and
+     * `APPROVAL_DIR` already are. It holds no secret and opens nothing: the file
+     * it points at carries bot ids, usernames and instance directories, all of
+     * which `.approval/env` carries in the open, and nothing reads it to widen a
+     * permission. Passed through because a child `approval` verb must resolve the
+     * SAME registry as its parent — a child that silently fell back to the
+     * platform default would answer "which instance owns this bot?" from a
+     * different file than the process that asked it.
+     */
+    "APPROVAL_STATE_DIR",
 ];
 /**
  * Does this bare variable name name credential material?
@@ -542,6 +611,33 @@ const OPERATOR_CHARS = new Set(["&", "|", ";", "(", ")", "<", ">", "\n"]);
  * Not understood, on purpose: parameter expansion values. `$VAR` and `${VAR}`
  * are kept verbatim in the word text, and every rule that reads a path or a
  * refspec treats a word containing `$` as unknown, which resolves stricter.
+ *
+ * ## Quoted text is DATA, and that is a contract (APRV-353)
+ *
+ * The command boundary this tokenizer honours is the shell's own. A quoted
+ * argument is ONE word to the shell, so nothing inside it is an operator, a
+ * redirection, a segment separator or a command name here either:
+ *
+ * - single-quoted text is wholly inert, every byte of it, `$` and backtick
+ *   included;
+ * - double-quoted text is inert too, with the two exceptions the shell itself
+ *   makes — `$(…)` and backticks, which it expands before the command runs and
+ *   which therefore keep the class they have anywhere else (a substitution is
+ *   classified recursively, a backtick is `opaque`);
+ * - adjacent quoted and unquoted runs concatenate into one word (`'a'"b"c`),
+ *   and a backslash escape is applied where the shell applies it;
+ * - UNQUOTED operators split exactly as they always did, and quoting that does
+ *   not balance is {@link LexResult} `ok: false` — `unparseable`, a refusal —
+ *   rather than a guess at what the writer meant.
+ *
+ * This is stated rather than merely true because the failure it prevents is
+ * silent and one-directional. A backlog note that says the word `bash`, carries
+ * an angle-bracketed placeholder, a pipe or a semicolon is prose about work; a
+ * tokenizer that read it as syntax would refuse an ordinary workspace write and
+ * push its author toward rewording the record of what they did, which is the
+ * audit cost SPEC.md §11 exists to protect. Every printable ASCII character is
+ * covered in both quote styles by `tests/command-class-quoting.test.ts`, so an
+ * edit that loses the property fails there rather than in someone's notes.
  */
 function lex(command) {
     const segments = [];
@@ -727,6 +823,19 @@ function lex(command) {
     flush(command.length);
     return { ok: true, segments };
 }
+/**
+ * The refusal detail for a backtick the shell would expand inside a
+ * double-quoted argument (APRV-353).
+ *
+ * Same code (`opaque`), same verdict (deny), more use: double quotes are what
+ * an author reaches for when the text carries an apostrophe, and a note that
+ * quotes a command in backticks is then legal shell that really does run
+ * something. The refusal names the spelling that is inert, because a refusal a
+ * reader cannot act on costs the same attention as one they can (SPEC.md §11.1:
+ * refusals are machine-readable and distinct — the code stays the machine's
+ * half, this is the human's).
+ */
+const QUOTED_BACKTICK_OPAQUE = "backtick command substitution inside a double-quoted argument, which the shell expands; single quotes make the same text literal";
 /** Scan a double-quoted string starting at the opening quote. */
 function readDoubleQuoted(command, start) {
     let text = "";
@@ -750,7 +859,7 @@ function readDoubleQuoted(command, start) {
             const close = command.indexOf("`", index + 1);
             if (close === -1)
                 return null;
-            opaque = "backtick command substitution";
+            opaque = QUOTED_BACKTICK_OPAQUE;
             index = close;
             continue;
         }
@@ -868,35 +977,111 @@ function hasShortFlag(args, letters) {
 function isUnknownValue(word) {
     return word.includes("$") || word.includes("*") || word.includes("?") || word.startsWith("~");
 }
-/** `git push` — the three push classes turn on flags and refspecs. */
+/** A bare release tag: the conventional `v` plus a semantic-version-shaped value. */
+const V_PREFIXED_SEMVER = /^v(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u;
+/** Does one side of a push refspec explicitly name a tag? */
+function isTagRef(name) {
+    if (name.startsWith("refs/tags/"))
+        return true;
+    if (name.startsWith("refs/heads/"))
+        return false;
+    return V_PREFIXED_SEMVER.test(name);
+}
+/** Does either source or destination of this refspec explicitly name a tag? */
+function isTagRefspec(refspec) {
+    const colon = refspec.indexOf(":");
+    if (colon === -1)
+        return isTagRef(refspec);
+    return isTagRef(refspec.slice(0, colon)) || isTagRef(refspec.slice(colon + 1));
+}
+/**
+ * Deleting a remote ref: its own class, never the trunk-push one (APRV-352).
+ *
+ * A `git push` that deletes refs was `vcs.push.main` until now, which reads as
+ * "this reaches the trunk" and in a repository that samples trunk pushes
+ * retrospectively means an irreversible removal proceeds unasked and is looked
+ * at afterwards. It is not the same act. A push adds commits somebody can still
+ * see; a deletion removes the only name an unmerged branch had, and the
+ * reflog that could find it again lives on a server nobody in the session can
+ * reach. The two belong on separate policy lines, and a policy that wants them
+ * on one can still write `vcs.*`.
+ *
+ * Distinct from `vcs.history.rewrite` as well, which guards SHARED history: a
+ * force push moves a ref other people have already built on. That class stays
+ * exactly where it was, above this one, so a force push that also deletes is
+ * still a rewrite.
+ */
+const REF_DELETE_CLASS = "vcs.ref.delete";
+/**
+ * The ref a deleting refspec names, or `null` when the refspec deletes nothing.
+ *
+ * `:dst` (empty source) is the deletion git documents; `src:` (empty
+ * destination) is the spelling the classifier has always treated as one too,
+ * and it keeps doing so rather than being narrowed here. The non-empty side is
+ * the name worth showing an approver either way.
+ */
+function deletedRef(refspec) {
+    const colon = refspec.indexOf(":");
+    if (colon === -1)
+        return null;
+    const source = refspec.slice(0, colon);
+    const destination = refspec.slice(colon + 1);
+    if (destination.length === 0)
+        return source.length === 0 ? refspec : source;
+    if (source.length === 0)
+        return destination;
+    return null;
+}
+/** `git push` — force, release, deletion, trunk and branch turn on flags and refspecs. */
 function refineGitPush(ctx) {
     const args = ctx.args.slice(1);
-    if (hasFlag(args, ["--force", "-f", "--force-with-lease", "--force-if-includes"])) {
+    if (hasFlag(args, ["--force", "-f", "--force-with-lease", "--force-if-includes", "--mirror"])) {
         return { class: "vcs.history.rewrite", rule: "git-push-force" };
     }
     const positionals = args.filter((arg) => !isFlag(arg));
-    // A deletion, or a push with no refspec at all: the destination is either the
-    // trunk or unknown, and unknown resolves to the stricter class.
+    const refspecs = positionals.slice(1);
+    if (refspecs.some((refspec) => refspec.startsWith("+"))) {
+        return { class: "vcs.history.rewrite", rule: "git-push-force" };
+    }
+    // The tag check stays ABOVE the deletion check, deliberately. A tag is the
+    // name a release was published under, and this repository's policy prices
+    // `release.publish` accordingly; deleting one is a release act whichever
+    // spelling removes it. Moving the deletion check up would re-label
+    // `git push origin :refs/tags/v1.2.3` and a bulk form that mixes a tag in,
+    // and APRV-352 asks for a class for branch deletions, not a loosening of the
+    // tag surface.
+    if (hasFlag(args, ["--tags", "--follow-tags"]) ||
+        refspecs.some(isTagRefspec) ||
+        refspecs.some((word, index) => word === "tag" && index + 1 < refspecs.length)) {
+        return { class: "release.publish", rule: "git-push-tag" };
+    }
+    // `--delete` / `-d`: every refspec after the remote is a ref being removed.
+    // A `--delete` naming no ref at all is a git error, and it stays in this
+    // class with nothing bound rather than falling through to a push class: an
+    // invocation whose targets cannot be read is the one that least deserves the
+    // looser answer.
     if (hasFlag(args, ["--delete", "-d"])) {
-        return { class: "vcs.push.main", rule: "git-push-delete" };
+        return {
+            class: REF_DELETE_CLASS,
+            rule: "git-ref-delete",
+            ...(refspecs.length === 0 ? {} : { path: refspecs.join(" ") }),
+        };
     }
-    const refspecs = positionals.slice(1);
     if (refspecs.length === 0) {
         return { class: "vcs.push.main", rule: "git-push-implicit" };
     }
+    // The colon-refspec spellings, which need no flag: `:refs/heads/x`, `:x`, and
+    // a bulk form mixing several. ONE deleting refspec makes the whole command a
+    // deletion, because the command's effect is the union of its refspecs and the
+    // destructive half is the half a person is being asked about.
+    const deleted = refspecs.map(deletedRef).filter((ref) => ref !== null);
+    if (deleted.length > 0) {
+        return { class: REF_DELETE_CLASS, rule: "git-ref-delete", path: deleted.join(" ") };
+    }
     let sawMain = false;
     for (const refspec of refspecs) {
-        if (refspec.startsWith("+")) {
-            return { class: "vcs.history.rewrite", rule: "git-push-force" };
-        }
         const colon = refspec.indexOf(":");
         const destination = colon === -1 ? refspec : refspec.slice(colon + 1);
-        // `:branch` (empty source) and `src:` (empty destination) both delete a
-        // remote ref. A deletion is destructive whatever it names, so it takes the
-        // stricter class rather than the branch one.
-        if (destination.length === 0 || (colon !== -1 && refspec.slice(0, colon).length === 0)) {
-            return { class: "vcs.push.main", rule: "git-push-delete" };
-        }
         if (isUnknownValue(destination)) {
             sawMain = true;
             continue;
@@ -923,6 +1108,211 @@ function refineGitPush(ctx) {
  * Everything that is not provably scratch keeps the old class.
  */
 const SCRATCH_DELETE_CLASS = "files.delete.scratch";
+// ---------------------------------------------------------------------------
+// Agent harnesses (APRV-354)
+// ---------------------------------------------------------------------------
+/**
+ * Launching an agent harness is its own class family, `harness.launch.NAME`.
+ *
+ * Until this, a command whose first word was `codex`, `muse`, `grok`, `claude`
+ * or `cursor-agent` was `unclassified`: denied, which is fail closed and also
+ * blunt. It told an approver nothing, it gave a human no class to grant through
+ * the ordinary manual path, and it meant a lane could not so much as read a
+ * harness version without going around the gate. The family fixes the second
+ * half without touching the first: an unknown class still falls to
+ * `defaults.autonomy`, so a project that adopts nothing is exactly where it was.
+ *
+ * ## The laundering hazard, which is why this is a class and not a table row
+ *
+ * A launched harness runs its own tools OUTSIDE this gate unless that harness's
+ * own adapter is installed and attested. So a grant of `harness.launch.codex`
+ * authorizes the LAUNCH and nothing the launched session then does — every
+ * file it writes, every command it runs and every request it makes happens
+ * where this runtime cannot see it. A policy that made the family autonomous
+ * would have written itself out of the gate in one line, which is why SPEC.md
+ * §7 says the family is never inferred autonomous and why the reference
+ * proposal holds it at `manual`. The blessed Codex entry point is the confined
+ * `approval codex start` (APRV-325.3), which keeps its own class.
+ *
+ * ## Muse, which carries a second hazard
+ *
+ * A Muse Code model id ending `-contributor` trades price for permission to
+ * train on prompts and completions, so running one over real code shares that
+ * code. Carter has ruled that Muse must never run with a Contributor model
+ * selected. The classifier cannot enforce that — the model is a self-reported
+ * argument, and a session may select one in its own UI where no command line
+ * shows it — so it does the one thing a classifier honestly can: it BINDS the
+ * `--model` value where it appears and gives a contributor value its own rule
+ * id, so a prompt and a policy can both see it. This may only ever RAISE
+ * scrutiny. A `-standard` id, or no `--model` at all, returns the ordinary rule
+ * id and changes nothing, because a self-reported field that could lower
+ * scrutiny is a field an agent would learn to write (SPEC.md §11.1 invariant 4).
+ *
+ * ## Where the family's name lives
+ *
+ * {@link HARNESS_LAUNCH_PREFIX} is `core/policy-match.ts`'s, not this file's,
+ * and is imported rather than repeated. Two enforcement paths refuse a launch
+ * that no policy rule names (`harnessLaunchNeedsRule`), and a second spelling of
+ * the prefix is the shape of bug that closes one of those doors and leaves the
+ * other open.
+ */
+/** The rule id prefix, so a reader can tell a launch row from a probe. */
+const HARNESS_LAUNCH_RULE_PREFIX = "harness-launch-";
+/**
+ * Harness binaries, by BASENAME, to the name their class carries.
+ *
+ * Basenames, because that is what {@link classifySegment} derives before any
+ * rule sees a command, and it is what makes `/opt/homebrew/bin/codex`,
+ * `~/.local/bin/muse` and `$HOME/.local/bin/muse` all land here without this
+ * table knowing anything about where a binary lives. A spelling the basename
+ * derivation cannot see through — `$MUSE_BIN`, a wrapper script of another
+ * name — is `unclassified`, which is the answer it had before and the answer it
+ * should keep.
+ *
+ * `cursor-agent` carries the name `cursor` so the class reads
+ * `harness.launch.cursor` beside the `cursor` adapter and the `.cursor/`
+ * protected paths. `gemini` is deliberately absent: APRV-354 names five
+ * harnesses, `gemini update` keeps its `deps.upgrade` row above this one, and a
+ * bare `gemini` stays `unclassified` until somebody makes that its own decision.
+ */
+const HARNESS_BINS = {
+    codex: "codex",
+    muse: "muse",
+    grok: "grok",
+    claude: "claude",
+    "cursor-agent": "cursor",
+};
+/**
+ * Package specs a package runner may name, EXACTLY, to the same harness names.
+ *
+ * Exact, and the exactness is the rule: `npx codex-helper` is not a codex
+ * launch, and a substring match that said it was would let any package whose
+ * name happens to contain a harness's take a class it did not earn. A spec this
+ * table does not know keeps whatever class the runner already had.
+ */
+const HARNESS_PACKAGES = {
+    codex: "codex",
+    "@openai/codex": "codex",
+    claude: "claude",
+    "@anthropic-ai/claude-code": "claude",
+    "cursor-agent": "cursor",
+    muse: "muse",
+    grok: "grok",
+};
+/**
+ * Argv that starts nothing: a version or help probe.
+ *
+ * A probe prints a string and exits, so it is a read, and reading a harness's
+ * own version is exactly what a session needs to be able to do without a
+ * prompt. `help` counts only as the WHOLE argv: `codex help` prints usage,
+ * while `codex help me refactor this` is a session.
+ */
+const HARNESS_PROBE_FLAGS = ["--version", "-V", "--help", "-h"];
+/** The probe's rule id and class. A probe starts no session, so it reads. */
+const HARNESS_PROBE_RULE = "harness-probe";
+const HARNESS_PROBE_CLASS = "read.shell";
+/** The rule id a Muse launch takes when its `--model` names a Contributor model. */
+const MUSE_CONTRIBUTOR_RULE = "harness-launch-muse-contributor";
+/**
+ * The suffix that marks a Muse model as training on what it is shown.
+ *
+ * Exported since APRV-350 so the hook adapter's contributor guard and this
+ * classifier's `harness.launch.muse` refinement test the SAME mark. Two
+ * spellings of "which models are unsafe" would drift, and the direction they
+ * drift in is the one where a launch is refused and a tool call is not.
+ */
+export const CONTRIBUTOR_SUFFIX = "-contributor";
+/** The `--model` value in either spelling, or `null` when none is written. */
+function harnessModel(args) {
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--model") {
+            const value = args[index + 1];
+            return value === undefined || isFlag(value) ? null : value;
+        }
+        if (arg.startsWith("--model="))
+            return arg.slice("--model=".length);
+    }
+    return null;
+}
+/**
+ * The harness a package spec names, version suffix stripped, or `null`.
+ *
+ * `@openai/codex@0.152.1` is the scoped case the split has to get right: the
+ * `@` that opens a scope is not the `@` that opens a version.
+ */
+function harnessPackage(spec) {
+    const at = spec.startsWith("@") ? spec.indexOf("@", 1) : spec.indexOf("@");
+    const bare = at === -1 ? spec : spec.slice(0, at);
+    return HARNESS_PACKAGES[bare] ?? null;
+}
+/**
+ * One harness invocation, given its name and the argv that follows its identity.
+ *
+ * Shared by the direct rows and the package-runner refinement, so a launch
+ * spelled `npx @openai/codex exec` answers exactly as `codex exec` does. The
+ * argv is bound to `path`: the segment's own `text` carries the command as
+ * written, and `path` carries the part the class is ABOUT, which is what lets a
+ * channel name it without re-parsing the line.
+ */
+function harnessRefinement(name, args) {
+    if (args.length === 1 &&
+        (HARNESS_PROBE_FLAGS.includes(args[0]) || args[0] === "help")) {
+        return { class: HARNESS_PROBE_CLASS, rule: HARNESS_PROBE_RULE };
+    }
+    // Anything else is a session. A probe flag beside other arguments is NOT a
+    // probe here: the classifier cannot know which of the two the binary will
+    // honour, and the stricter reading of an ambiguous harness invocation is the
+    // one that assumes a session started.
+    const model = name === "muse" ? harnessModel(args) : null;
+    const contributor = model !== null && model.toLowerCase().endsWith(CONTRIBUTOR_SUFFIX);
+    return {
+        class: `${HARNESS_LAUNCH_PREFIX}${name}`,
+        rule: contributor ? MUSE_CONTRIBUTOR_RULE : `${HARNESS_LAUNCH_RULE_PREFIX}${name}`,
+        ...(args.length === 0 ? {} : { path: args.join(" ") }),
+    };
+}
+/** `codex …`, `muse …`, `grok …`, `claude …`, `cursor-agent …`. */
+function refineHarness(ctx) {
+    const name = HARNESS_BINS[ctx.bin];
+    // Unreachable through the table, which matches on these basenames; a defensive
+    // arm rather than a silent wrong class if a row is ever edited apart from the
+    // table it is generated from.
+    if (name === undefined) {
+        return { opaque: `${ctx.bin} is an agent harness this table cannot name` };
+    }
+    return harnessRefinement(name, ctx.args);
+}
+/**
+ * `npx`, `tsx`, `tsc`, … — unchanged, except a package runner naming a harness.
+ *
+ * `npx @openai/codex` starts the same session `codex` starts, and before this
+ * it was `files.write.workspace`: the looser of the two answers, reachable by
+ * typing four extra characters. The refinement is deliberately narrow — only
+ * `npx`, only an EXACT package spec, and everything else returns the row's own
+ * answer byte for byte, which is what keeps this from being a widening of the
+ * workspace-tool row.
+ */
+function refineWorkspaceTool(ctx) {
+    const unchanged = { class: "files.write.workspace", rule: "workspace-tool" };
+    if (ctx.bin !== "npx")
+        return unchanged;
+    const index = ctx.args.findIndex((arg) => !isFlag(arg));
+    if (index === -1)
+        return unchanged;
+    const name = harnessPackage(ctx.args[index]);
+    if (name === null)
+        return unchanged;
+    return harnessRefinement(name, ctx.args.slice(index + 1));
+}
+/** The five generated harness rows, one per binary, sharing one refinement. */
+const HARNESS_RULES = Object.entries(HARNESS_BINS).map(([bin, name]) => ({
+    id: `${HARNESS_LAUNCH_RULE_PREFIX}${name}`,
+    bins: [bin],
+    class: `${HARNESS_LAUNCH_PREFIX}${name}`,
+    emits: [HARNESS_PROBE_CLASS],
+    refine: refineHarness,
+}));
 /**
  * Is `candidate` a STRICT descendant of `root`? Both are compared by path
  * segment, so `/private/tmpfoo` is not under `/private/tmp` and a root is never
@@ -966,6 +1356,43 @@ function allTargetsAreScratch(targets, roots) {
     }
     return true;
 }
+// ===========================================================================
+// Read scope (read.file.out_of_scope, APRV-347)
+// ===========================================================================
+/** The rule id for a read whose ABSOLUTE target sits outside every root. */
+export const READ_OUT_OF_SCOPE_RULE = "read-out-of-scope";
+/** The rule id for a read target whose expansion the text cannot show. */
+export const READ_UNREADABLE_TARGET_RULE = "read-unreadable-path";
+/**
+ * The first target of this read command that the TEXT places outside every
+ * root, or `null` when nothing here settles it.
+ *
+ * `null` covers three different situations on purpose, and all three are
+ * handed on rather than decided: the binary is not a scoped reader, every
+ * target is provably inside a root, or a target is relative (or carries `..`)
+ * and therefore means nothing without a working directory. The last of those
+ * is the common case, and it is why the hook's second pass exists.
+ */
+function escapedReadTarget(bin, positionals, args, roots) {
+    const targets = readTargetsOf(bin, positionals, args);
+    if (targets === null)
+        return null;
+    for (const target of targets) {
+        switch (readTargetVerdict(target, roots)) {
+            case "out-of-scope":
+                return {
+                    path: target,
+                    rule: isUnreadableTarget(target)
+                        ? READ_UNREADABLE_TARGET_RULE
+                        : READ_OUT_OF_SCOPE_RULE,
+                };
+            case "in-scope":
+            case "needs-disk":
+                break;
+        }
+    }
+    return null;
+}
 /** `rm` — everything outside the workspace, and every unreadable path, is manual. */
 function refineRm(ctx) {
     const recursive = hasFlag(ctx.args, ["--recursive"]) || hasShortFlag(ctx.args, ["r", "R"]);
@@ -1395,12 +1822,31 @@ function isGateEntrypoint(path) {
  * ritual reached the approver's phone as `policy.edit` over a protected path —
  * true, and useless. Classified by name it arrives as what it is.
  *
- * `positionals` is read rather than `args`, so a flag between the words cannot
- * hide the verb: `approval --json log sync` is the same invocation.
+ * `policy attest --path` (APRV-338) is the newest member and the one that reads
+ * a FLAG, because the flag is what changes the act. Without it the verb attests
+ * the policy file or a gate organ, which are records about the gate's own
+ * configuration; with it the verb ratifies protected TEXT, and that record is
+ * what resolves SPEC.md's pending-sign-off suffix. An agent able to write one
+ * could ratify its own amendments, so it is classified where the rest of the
+ * gate's ceremonies are: `policy.core`, which this repository's policy holds
+ * human-only, so the hook denies it with `hook-class-human-only` before the
+ * verb's own `actor-not-human` refusal is ever reached. It mints no new class
+ * (§11.1 invariant 9): `policy.core` already exists and is already in the row's
+ * `emits`.
+ *
+ * `positionals` is read rather than `args` for the verb words, so a flag between
+ * them cannot hide the verb: `approval --json log sync` is the same invocation.
+ * `args` is read only where a flag is the act, as it is above.
  */
-function refineApprovalVerb(positionals) {
+function refineApprovalVerb(positionals, args = []) {
     const verb = positionals[0];
     const sub = positionals[1];
+    if (verb === "policy" && sub === "attest" && hasFlag(args, ["--path"])) {
+        return { class: "policy.core", rule: "approval-policy-signoff" };
+    }
+    if (verb === "quickstart") {
+        return { class: "policy.core", rule: "approval-quickstart" };
+    }
     if (verb === "log") {
         if (sub === "sync")
             return { class: "log.sync", rule: "approval-log-sync" };
@@ -1426,6 +1872,22 @@ function refineApprovalVerb(positionals) {
             return { class: "policy.core", rule: "approval-gate-close" };
         return null;
     }
+    // APRV-343. `policy apply` WRITES `APPROVAL.md`, which is the one file in this
+    // repository nothing but a human's own hand may change: an agent that could
+    // run it could widen the policy that governs it and then attest the result
+    // through the amendment the verb goes on to run. Classified where the file
+    // already is (`policy.core`, human-only in the reference policy), so the hook
+    // denies it with `hook-class-human-only`, behind the verb's own
+    // `apply-agent-actor` refusal. It mints no new class (SPEC.md §11.1 invariant
+    // 9): `policy.core` already exists and already covers the policy's machinery.
+    //
+    // The other `policy` subcommands stay pass-through. `check` and `test` read,
+    // `attest` and `amend` refuse a non-human actor in code and collect a human's
+    // tap through a channel when an agent runs them, which is the widening
+    // APRV-109 deliberately made — and neither of them writes the policy file.
+    if (verb === "policy" && sub === "apply") {
+        return { class: "policy.core", rule: "approval-policy-apply" };
+    }
     // APRV-257. `setup checkpoint` MINTS the key `log checkpoint` signs with, so
     // an agent that could run it could mint a key, store it, and vouch for a
     // chain it had just written — the mechanism defeated at its source rather
@@ -1452,7 +1914,7 @@ function refineApprovalVerb(positionals) {
  * two log verbs keeps the pass-through class and the row's own rule id.
  */
 function refineApproval(ctx) {
-    return refineApprovalVerb(ctx.positionals) ?? { class: GATE_SELF_CLASS, rule: "approval" };
+    return (refineApprovalVerb(ctx.positionals, ctx.args) ?? { class: GATE_SELF_CLASS, rule: "approval" });
 }
 /**
  * `node` — an inline script is opaque, the gate's own entry point is
@@ -1465,7 +1927,7 @@ function refineNode(ctx) {
     if (script !== undefined && isGateEntrypoint(script)) {
         // `node cli.js log sync` is `approval log sync` spelled the long way, and
         // it must classify identically or the classification is a spelling test.
-        return (refineApprovalVerb(ctx.positionals.slice(1)) ?? {
+        return (refineApprovalVerb(ctx.positionals.slice(1), ctx.args) ?? {
             class: GATE_SELF_CLASS,
             rule: "node-approval-cli",
         });
@@ -1489,7 +1951,7 @@ export const COMMAND_RULES = [
         bins: ["git"],
         subs: ["push"],
         class: "vcs.push.main",
-        emits: ["vcs.push.branch", "vcs.push.main", "vcs.history.rewrite"],
+        emits: ["vcs.push.branch", "vcs.push.main", "vcs.history.rewrite", "vcs.ref.delete"],
         refine: refineGitPush,
     },
     {
@@ -1614,8 +2076,20 @@ export const COMMAND_RULES = [
     // harness unattended. `uca` matches with ANY arguments, `--dry-run` included:
     // the classifier reads text, cannot know which flags the script honours, and
     // the strictest reading of an updater is that it updates.
+    //
+    // APRV-354 answers the other half of that sentence: the launch rows below now
+    // name what a bare `claude` or `codex …` is. This row stays ABOVE them on
+    // purpose, so `codex update` and `claude update` keep `deps.upgrade` — an
+    // upgrade swaps the binary that hosts the hook, which is the stricter of the
+    // two readings and the class they already had.
     { id: "harness-update", bins: ["claude", "codex", "gemini"], subs: ["update"], class: "deps.upgrade" },
     { id: "harness-updater", bins: ["uca"], class: "deps.upgrade" },
+    // -- agent harness launch (APRV-354) --------------------------------------
+    // Generated from {@link HARNESS_BINS}, one row per binary, all sharing
+    // {@link refineHarness}. Below `harness-update` so an upgrade keeps its
+    // class; above the workspace tools so a package-runner spelling is the only
+    // one that has to be refined rather than matched.
+    ...HARNESS_RULES,
     // -- workspace tools -----------------------------------------------------
     // APRV-193: three of the rules below hand control to code the runtime did not
     // author, and they are named in {@link CODE_EXECUTING_RULES}.
@@ -1637,6 +2111,14 @@ export const COMMAND_RULES = [
         id: "workspace-tool",
         bins: ["npx", "tsx", "ts-node", "tsc", "oxlint", "eslint", "prettier", "vitest", "jest", "backlog", "make"],
         class: "files.write.workspace",
+        // APRV-354: only `npx` naming a harness package changes; see
+        // {@link refineWorkspaceTool}, which returns this row's own answer for
+        // every other binary and every other package.
+        emits: [
+            HARNESS_PROBE_CLASS,
+            ...Object.values(HARNESS_PACKAGES).map((name) => `${HARNESS_LAUNCH_PREFIX}${name}`),
+        ],
+        refine: refineWorkspaceTool,
     },
     {
         id: "workspace-write",
@@ -1795,9 +2277,17 @@ function refineGh(ctx) {
  * Binaries whose effect lives in a string this classifier will not interpret.
  *
  * A second parser for the same text is a second answer waiting to disagree with
- * the shell's, so these refuse instead. `bash -c "…"`, `eval`, `xargs` and the
- * `-e` interpreters can express anything at all; `sudo` and `env` re-launch
+ * the shell's, so these refuse instead. `eval`, `xargs` and the `-e`
+ * interpreters can express anything at all; `sudo` and `env` re-launch
  * something else with different authority.
+ *
+ * ONE NARROW EXCEPTION since APRV-380, and it is a narrowing of this rule
+ * rather than a hole in it: a segment that is EXACTLY a known shell, one
+ * inline-script flag and one script word is classified by the script, through
+ * this same classifier. No second parser is written and the text is not read a
+ * second way. {@link loginShellScript} states the shape and the reasoning, and
+ * everything outside it — including the same shell with a script file, or a
+ * shell nested inside an unwrapped script — is refused here exactly as before.
  */
 const OPAQUE_BINS = {
     bash: "runs a shell script",
@@ -1819,6 +2309,93 @@ const OPAQUE_BINS = {
     timeout: "runs another command under a timer",
     time: "runs another command under a timer",
 };
+/**
+ * The shells {@link loginShellScript} will unwrap: the six in
+ * {@link OPAQUE_BINS} that run a script.
+ *
+ * The other opaque binaries stay opaque under every shape. `eval`, `xargs` and
+ * the `-e` interpreters build their text from somewhere this file cannot see;
+ * `sudo`, `doas`, `env`, `nohup`, `exec`, `source`, `.`, `watch`, `timeout` and
+ * `time` re-launch something else, with different authority or under a timer,
+ * and what they re-launch is an argv rather than a script.
+ */
+const UNWRAPPABLE_SHELLS = new Set([
+    "bash",
+    "sh",
+    "zsh",
+    "dash",
+    "ksh",
+    "fish",
+]);
+/**
+ * The inline-script flags a wrapper may carry: `-c`, with any run of `l` and
+ * `i` before it (APRV-380).
+ *
+ * `-lc` is the shape the 2026-09-18 probe recorded on every Codex exec request.
+ * `c` must be LAST, because that is the letter that takes the next word as its
+ * argument, and a combination where it is not last is one whose reading depends
+ * on the shell's own option parser. That is a shape this rule declines to guess
+ * at, so it stays opaque.
+ */
+const INLINE_SCRIPT_FLAG = /^-[li]*c$/u;
+/**
+ * The script a LOGIN-SHELL WRAPPER runs, when the segment is exactly one
+ * (APRV-380), or `null`.
+ *
+ * ## Why this is not the second parser the table above refuses
+ *
+ * {@link OPAQUE_BINS} states the position this narrows: a second parser for the
+ * same text is a second answer waiting to disagree with the shell's. The hazard
+ * that names is reading shell text a SECOND WAY. This is not that. When the
+ * argv is exactly `[shell, -lc, script]` and nothing else, the script is the
+ * text a Claude Code `Bash` call hands this classifier directly, and what
+ * happens to it here is what happens to that: the same lexer, the same segment
+ * rules, the same table. No new parser is written, and the text is not read a
+ * second way — it is read the first way, by the only reader there is.
+ *
+ * ## The line, and it is exact
+ *
+ * Three words, no more: a known shell, one inline-script flag, one script. Any
+ * of these keeps the wrapper opaque, because each is a shape whose effect
+ * depends on something the argv alone does not say:
+ *
+ * - extra words (a script FILE, `--`, an option this rule does not model);
+ * - an assignment prefix, which changes the environment the script runs in;
+ * - a redirection on the wrapper, which is the outer shell's and not the
+ *   script's;
+ * - a substitution in any of the three words, whose effect happens before the
+ *   shell even starts;
+ * - a nested shell inside the script, refused by {@link ClassifierContext} when
+ *   the recursion runs (the inner classification unwraps nothing).
+ *
+ * The BINDING does not move. `cli/hook.ts` binds the outer command and argv
+ * exactly as APRV-362 built them; what this changes is only which text is
+ * classified, and the classes are additional evidence about bytes that are
+ * bound elsewhere and unchanged.
+ */
+export function loginShellScript(segment) {
+    if (segment.opaque !== null)
+        return null;
+    if (segment.redirects.length > 0)
+        return null;
+    if (segment.words.length !== 3)
+        return null;
+    const [shell, flag, script] = segment.words;
+    if (shell.substitutions.length > 0)
+        return null;
+    if (flag.substitutions.length > 0)
+        return null;
+    if (script.substitutions.length > 0)
+        return null;
+    const base = pathSegments(shell.text).slice(-1)[0] ?? shell.text;
+    if (!UNWRAPPABLE_SHELLS.has(base))
+        return null;
+    if (!INLINE_SCRIPT_FLAG.test(flag.text))
+        return null;
+    // An empty script runs nothing, and `classifyCommand` answers `unclassified`
+    // for an empty command. Leaving it wrapped keeps that answer the wrapper's.
+    return script.text.trim().length === 0 ? null : script.text;
+}
 /** Interpreters that are opaque only when handed inline source. */
 const INLINE_SOURCE_BINS = {
     python: ["-c"],
@@ -1927,6 +2504,20 @@ export const CODE_EXECUTING_RULES = [
     "node-script",
     /** `npx`, `tsx`, `tsc`, `vitest`, `jest`, `make`, and kin. */
     "workspace-tool",
+    /**
+     * Launching an agent harness, and probing one (APRV-354).
+     *
+     * Every spelling is here, the probe included. A launch hands control to a
+     * whole second agent, which is the most complete form of "code the runtime
+     * did not author"; a probe still executes the same binary. The list is
+     * matched against a segment's RULE, so the generated launch ids and the two
+     * ids a refinement can return on its own — the probe and the Muse
+     * contributor id — all have to be named, or `npx @openai/codex` would have
+     * quietly stopped requiring a sandbox by gaining a better class.
+     */
+    ...HARNESS_RULES.map((rule) => rule.id),
+    HARNESS_PROBE_RULE,
+    MUSE_CONTRIBUTOR_RULE,
 ];
 /**
  * Every class the table can emit, for docs and for the dogfood test.
@@ -1953,8 +2544,45 @@ export const CLASSIFIER_CLASSES = (() => {
     seen.add(CREDENTIAL_CLASS);
     seen.add("files.write.workspace");
     seen.add("read.shell");
+    // APRV-347: emitted from `classifySegment`'s tail rather than from a row of
+    // the table, because it is a refinement of `read.shell` against roots the
+    // CALLER resolved and no binary implies it on its own.
+    seen.add(READ_OUT_OF_SCOPE_CLASS);
     return [...seen].sort();
 })();
+/**
+ * The class the DAEMON's own cadence advance is gated as (APRV-382).
+ *
+ * The sub-class exists because the policy grammar has no actor condition and
+ * this repository wanted one: an advance publishes records the log already
+ * holds, so the daemon may make it unattended, while the same act from a
+ * session in a worktree or a human terminal stays supervised. Two classes are
+ * how that is written down, and which of them a cycle asks under is decided by
+ * `core/advance-cycle.ts` from the running process, never from an argument.
+ *
+ * NO COMMAND SPELLS IT, on purpose. `approval log advance` classifies
+ * `log.advance` whoever types it, so the looser line is unreachable from a
+ * shell an agent can drive: it is reached only from inside the daemon process,
+ * which an agent cannot become without a `gate.self` command this policy holds
+ * at the manual default.
+ */
+export const ADVANCE_DAEMON_CLASS = "log.advance.daemon";
+/**
+ * Classes this RUNTIME emits for its own gated actions, which no command spells.
+ *
+ * Separate from {@link CLASSIFIER_CLASSES}, which is the binary table's own set
+ * and is what `docs/claude-code-hook.md` documents row by row. A class here is
+ * emitted by a runtime cycle that registers and requests it directly — the
+ * daemon's advance is the first — so a policy declaring it is declaring a line
+ * that CAN fire, and the reachability check `core/policy-expectations.ts` runs
+ * at the amendment ceremony must say so. Without this list that ceremony would
+ * refuse the line `unreachable`, which is a true statement about the command
+ * classifier and a false one about the runtime.
+ *
+ * Adding a name here is a claim that some path in this codebase asks the gate
+ * for that class, and widening it is a reviewable diff.
+ */
+export const RUNTIME_CLASSES = [ADVANCE_DAEMON_CLASS];
 /**
  * Can the classifier emit `actionClass` for a project whose policy carries
  * these `protected_paths`? (APRV-266.)
@@ -1970,10 +2598,17 @@ export const CLASSIFIER_CLASSES = (() => {
  * A routed name is reachable exactly when some entry routes to it. A
  * `policy.edit.spec` rule in a policy whose `protected_paths` routes nothing to
  * it is a line that will never fire, and saying so is the whole point.
+ *
+ * {@link RUNTIME_CLASSES} is the third answer (APRV-382): a class no command
+ * spells and a runtime cycle asks for directly is reachable in every project,
+ * with no policy entry needed, because the path that emits it is in this
+ * codebase rather than in the operator's file.
  */
 export function emittableClass(actionClass, protectedPaths = []) {
     if (CLASSIFIER_CLASSES.includes(actionClass))
         return true;
+    if (RUNTIME_CLASSES.includes(actionClass))
+        return true;
     if (!POLICY_EDIT_SUBCLASS.test(actionClass))
         return false;
     return protectedPaths.some((entry) => parseProtectedEntry(entry)?.routed === actionClass);
@@ -2215,6 +2850,11 @@ function classifySegment(segment, protectedPaths, context) {
     }
     let cls = refined === null ? rule.class : refined.class;
     let ruleId = refined === null ? rule.id : refined.rule;
+    // The value a refinement bound, when one did (APRV-352). Same field and same
+    // meaning as the protected-path binding above: the words the classifier
+    // matched, verbatim, so an approver is told WHICH refs a deletion names
+    // rather than being handed a class and left to re-read the command.
+    const boundPath = refined !== null && "path" in refined ? refined.path : undefined;
     // A protected path anywhere in an effectful segment takes that path's class:
     // the command is editing the gate, whatever else it is doing. Every
     // positional is scanned, source and destination alike, so `cp` stays
@@ -2233,7 +2873,31 @@ function classifySegment(segment, protectedPaths, context) {
         cls = "files.write.workspace";
         ruleId = "redirect-write";
     }
-    return { ok: true, class: cls, rule: ruleId, ...(sandbox === null ? {} : { sandbox }) };
+    // APRV-347, last because it is the narrowest: a read whose target the TEXT
+    // places outside every root the caller named. Only `read.shell` is scoped —
+    // `read.web` reaches no file, and a segment that has already taken a
+    // protected, credential or write class is not a read at all. The relative
+    // and symlinked cases are deliberately NOT decided here; they are left at
+    // `read.shell` for the hook's disk pass, which tightens and never loosens.
+    if (cls === "read.shell" && (context.readRoots ?? []).length > 0) {
+        const escaped = escapedReadTarget(basename, positionals, args, context.readRoots ?? []);
+        if (escaped !== null) {
+            return {
+                ok: true,
+                class: READ_OUT_OF_SCOPE_CLASS,
+                rule: escaped.rule,
+                path: escaped.path,
+                ...(sandbox === null ? {} : { sandbox }),
+            };
+        }
+    }
+    return {
+        ok: true,
+        class: cls,
+        rule: ruleId,
+        ...(boundPath === undefined ? {} : { path: boundPath }),
+        ...(sandbox === null ? {} : { sandbox }),
+    };
 }
 /**
  * Classify a shell command line into the classes it would produce.
@@ -2270,6 +2934,30 @@ export function classifyCommand(command, protectedPaths = [], context = {}) {
     const segments = [];
     const classes = [];
     for (const segment of lexed.segments) {
+        // APRV-380. A LOGIN-SHELL WRAPPER is classified by the script it runs.
+        // `loginShellScript` states the exact shape and why this is not the second
+        // parser `OPAQUE_BINS` refuses; the inner classification is run with
+        // `unwrapShell: false`, so a shell nested inside the script stays opaque
+        // and the recursion is one level deep by construction.
+        const script = context.unwrapShell === false ? null : loginShellScript(segment);
+        if (script !== null) {
+            const inner = classifyCommand(script, protectedPaths, { ...context, unwrapShell: false });
+            if (!inner.ok) {
+                // The refusal is the INNER one, reported against the inner segment: an
+                // operator told `hook-opaque` for `zsh` learns nothing, and one told
+                // which part of their script could not be read can rewrite it.
+                return inner;
+            }
+            // Spliced rather than collapsed into one segment: a script is a command
+            // line and its parts have their own classes, which is the thing a
+            // one-class answer would lose.
+            for (const found of inner.segments) {
+                segments.push(found);
+                if (!classes.includes(found.class))
+                    classes.push(found.class);
+            }
+            continue;
+        }
         const outcome = classifySegment(segment, protectedPaths, context);
         if (!outcome.ok) {
             return { ok: false, code: outcome.code, segment: segment.text, detail: outcome.detail };