approval-md 0.2.0 → 0.4.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.
  *
@@ -42,6 +58,14 @@
  * is never written to any envelope and no policy rule should name it.
  */
 export const GATE_SELF_CLASS = "gate.self";
+/**
+ * The class a write under `$HERMES_HOME/scripts/` takes (APRV-445): scheduling
+ * code that Hermes's cron runs later with no hook in front of it. Returned by
+ * {@link protectedPathClass} beside the organs, ranked with `policy.edit`, and
+ * deliberately not a {@link ProtectedPathClass}: it is a side effect an
+ * operator prices, not a surface of the gate itself.
+ */
+export const HERMES_SCHEDULED_SCRIPT_CLASS = "cron.manage";
 /**
  * The `policy.edit` sub-class namespace a `protected_paths` entry may route to
  * (APRV-266).
@@ -240,6 +264,109 @@ 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";
+            }
+        }
+        // Hermes Agent's equivalent (APRV-398), and the one whose organ lives in
+        // the USER HOME by design rather than in the repository. Hermes reads its
+        // configuration from `$HERMES_HOME` (default `~/.hermes`) and documents no
+        // project-local directory, so the paths below are the ones a real install
+        // carries: `config.yaml`, which is where the `hooks:` entries are written;
+        // `agent-hooks/`, which holds the scripts those entries run; and
+        // `shell-hooks-allowlist.json`, which records the operator's one-time TTY
+        // consent to a hook command and would let an agent pre-consent itself to a
+        // command of its own. Same property as `.cursor/hooks.json`: an agent that
+        // could write any of these could write itself out of the gate.
+        //
+        // NO NEW PATH GRAMMAR IS NEEDED FOR THE HOME CASE, and that is worth
+        // stating because it is the one thing about this entry that differs from
+        // the four above it. This loop walks EVERY segment of the candidate, so
+        // `.hermes/config.yaml`, `/Users/x/.hermes/config.yaml` and
+        // `~/.hermes/config.yaml` all match at whichever position `.hermes` sits
+        // in; the existing matchers were already position-agnostic and nothing was
+        // extended for this. What a home path does change is the CLASS a mere READ
+        // of one takes: `cat ~/.hermes/config.yaml` is a read of a path outside the
+        // gate root, so the read jail answers it as `read.file.out_of_scope`
+        // (human-only in this repository's policy) before this tier is consulted,
+        // while a WRITE to it is `policy.core` here. Both refuse under an agent;
+        // they refuse for different reasons, and `docs/hermes-hook.md` says so.
+        //
+        // The bare `.hermes` directory itself lands here, exactly as bare
+        // `.approval` and bare `.codex` do: `rm -rf ~/.hermes` removes the gate's
+        // own installation. Anything else under it is deliberately NOT listed —
+        // session state and transcripts are ordinary bookkeeping, and pricing those
+        // at a human's attention is the failure mode §11 asks to avoid, the same
+        // reasoning that keeps `.muse/worktrees/` out of the entry above.
+        //
+        // APRV-445 adds three rows from the Agent Village DATA-234 survey of Hermes
+        // v2026.9.24. `shell-hooks-allowlist.json.lock` is the allowlist's flock
+        // sidecar: an agent that makes it unwritable makes the gateway's consent
+        // write raise at start, so it is the allowlist's organ as much as the file
+        // is (matched by prefix, so the sidecar and the file are one row).
+        // `approval/` is where a hosted install keeps the hook's own configuration
+        // beside the harness. And `scripts/` is `cron.manage`, not an organ: Hermes
+        // runs a scheduled job's script from `$HERMES_HOME/scripts/` with no
+        // `pre_tool_call` at all, so WRITING one is scheduling code that will run
+        // ungated later, which is the same act as `cronjob_manage create` and is
+        // priced by the same policy line.
+        //
+        // `.env` (and `.env.*`) and `auth.json` are organs too, for WRITES (APRV-445
+        // refutation, B2). `isCredentialPath` makes a READ of them
+        // `account.credential`, but that tier is consulted for reads only, so before
+        // this a `write_file`, a `patch`, a `>>`, a `sed -i` or a `tee -a` onto
+        // `$HERMES_HOME/.env` classified as an ordinary `files.write.workspace` and
+        // ran unattended: and Hermes loads that file with `override=True` into every
+        // process it starts, which makes it the switch for the gate itself
+        // (`HERMES_ACCEPT_HOOKS`) as well as a secret store. Reads stay
+        // `account.credential`.
+        if (segment === ".hermes") {
+            // Recheck 3 (lows): a profile home, `.hermes/profiles/<p>/`, is a home of
+            // its own with the same organs, so its paths are judged one level down.
+            const next = segments[index + 1] === "profiles" && segments[index + 2] !== undefined
+                ? segments[index + 3]
+                : segments[index + 1];
+            if (next === undefined ||
+                next === "config.yaml" ||
+                next === "config.yml" ||
+                next === "agent-hooks" ||
+                next === "approval" ||
+                next === ".env" ||
+                next.startsWith(".env.") ||
+                next === "auth.json" ||
+                next.startsWith("shell-hooks-allowlist.json") ||
+                next.startsWith("hooks")) {
+                return "policy.core";
+            }
+            if (next === "scripts")
+                return HERMES_SCHEDULED_SCRIPT_CLASS;
+        }
         // Codex installs its hook through these configuration and script paths.
         if (segment === ".codex") {
             const next = segments[index + 1];
@@ -383,12 +510,34 @@ const CREDENTIAL_CLASS = "account.credential";
  * kin), which is the environment map holding the Telegram token, the vault
  * passphrase and the sampling secret.
  */
-function isCredentialPath(candidate) {
+export function isCredentialPath(candidate) {
     if (candidate.length === 0)
         return false;
     const segments = pathSegments(candidate);
     for (let index = 0; index < segments.length; index += 1) {
-        if (segments[index] !== ".approval")
+        const segment = segments[index];
+        // APRV-398. Hermes Agent's own home holds two files of credential material
+        // beside its configuration: `.env`, which is where its secrets go, and
+        // `auth.json`, which holds an OAuth grant. `$HERMES_HOME/config.yaml` and
+        // the hook paths beside it are `policy.core` (see `protectedPathClass`);
+        // these two are a different class for the reason `.approval/env` is, which
+        // is that what leaves the machine is the secret rather than the rule.
+        //
+        // Added by the task that taught this runtime about Hermes at all. A harness
+        // whose organ this codebase now recognises, whose credential files it did
+        // not, would be a Never-list item the classifier does not enforce — which is
+        // exactly the hole APRV-194 was filed for, one harness along.
+        if (segment === ".hermes") {
+            const next = segments[index + 1] === "profiles" && segments[index + 2] !== undefined
+                ? segments[index + 3]
+                : segments[index + 1];
+            if (next === ".env" || next?.startsWith(".env.") === true)
+                return true;
+            if (next === "auth.json")
+                return true;
+            continue;
+        }
+        if (segment !== ".approval")
             continue;
         const next = segments[index + 1];
         if (next === undefined)
@@ -472,6 +621,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?
@@ -552,6 +714,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 = [];
@@ -737,6 +926,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 = "";
@@ -760,7 +962,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;
         }
@@ -895,7 +1097,45 @@ function isTagRefspec(refspec) {
         return isTagRef(refspec);
     return isTagRef(refspec.slice(0, colon)) || isTagRef(refspec.slice(colon + 1));
 }
-/** `git push` — force, release, trunk and branch classes turn on flags and refspecs. */
+/**
+ * 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", "--mirror"])) {
@@ -906,29 +1146,45 @@ function refineGitPush(ctx) {
     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" };
     }
-    // A non-tag deletion, or a push with no refspec at all: the destination is
-    // either the trunk or unknown, and unknown resolves to the stricter class.
+    // `--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(" ") }),
+        };
     }
     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) {
         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;
@@ -955,6 +1211,223 @@ 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",
+    // APRV-398. `hermes` is the console script Hermes Agent installs, and the
+    // harness kind and the binary share one spelling, so the class reads
+    // `harness.launch.hermes` beside the `hermes` adapter and the `.hermes/`
+    // protected paths with no name mapping in between.
+    hermes: "hermes",
+};
+/**
+ * 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",
+    // APRV-398. Hermes Agent is a Python distribution, so a package runner is not
+    // how it is launched; the entries exist for the same reason the `muse` and
+    // `grok` ones do, which is that a spec this table does not know keeps
+    // whatever class the runner already had, and a spec it does know cannot be
+    // spelled around the direct row.
+    hermes: "hermes",
+    "hermes-agent": "hermes",
+};
+/**
+ * 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
@@ -998,6 +1471,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"]);
@@ -1103,6 +1613,429 @@ function refineSed(ctx) {
         ? { class: "files.write.workspace", rule: "sed-in-place" }
         : { class: "read.shell", rule: "sed-read" };
 }
+// ===========================================================================
+// Packaging and archives (APRV-397)
+// ===========================================================================
+/**
+ * The read-only packaging and archive tools, and the one rule they share.
+ *
+ * ## What was wrong
+ *
+ * A release verification is mostly reading: pack a tarball, list what is in it,
+ * unpack it somewhere disposable, hash a file, decode a base64 blob, ask a
+ * binary its version. Every one of those commands was `unclassified` until this
+ * task, so every one of them was DENIED, and the verifier that met the wall on
+ * 2026-09-20 did the work anyway by fetching the tarball with `curl` and
+ * parsing it in a script: a chain of network and interpreter calls in place of
+ * six readers. A gate that refuses the legible spelling and leaves the
+ * illegible one open has made the session less inspectable rather than safer.
+ *
+ * ## The one rule
+ *
+ * Each of these commands either reads what it names or writes into a
+ * destination it names, and the destination is in the text. So they are decided
+ * by the arithmetic {@link refineRm} already uses, hoisted into
+ * {@link scopedWrite}: a destination strictly under a scratch root the CALLER
+ * resolved is the agent's own space, a relative destination is the workspace,
+ * and an absolute path anywhere else, a `..` segment, or a value the text cannot
+ * read is out of scope.
+ *
+ * ## Why the out-of-scope answer is a class that already exists
+ *
+ * {@link OUT_OF_SCOPE_WRITE_CLASS} is `files.delete.out_of_scope`, which is
+ * what `rm` and `find -delete` already answer for a destructive file operation
+ * the text places outside the workspace. Minting `files.write.out_of_scope`
+ * instead would have been the one change here capable of loosening something: a
+ * class no policy names resolves by `defaults.autonomy` (SPEC.md §7), so in
+ * every deployment whose defaults are permissive a brand-new name arrives
+ * autonomous, while the existing class is held at `manual` by the reference
+ * policy and by this repository's. An extraction is also honestly described by
+ * it: unpacking an archive over a directory overwrites whatever it finds there,
+ * which is the destruction the class is about.
+ *
+ * The strictness this inherits is `rm`'s, and it is deliberate. An ABSOLUTE
+ * destination is out of scope even when it happens to sit inside the checkout,
+ * because this file holds no workspace root, and the read roots it does hold
+ * are a read notion that must not become a write authorization.
+ */
+const OUT_OF_SCOPE_WRITE_CLASS = "files.delete.out_of_scope";
+/** The one rule id every out-of-scope packaging destination reports. */
+const OUT_OF_SCOPE_WRITE_RULE = "packaging-write-out-of-scope";
+/**
+ * A destination a flag names, as a list {@link scopedWrite} can read.
+ *
+ * Three answers, and the third is the one worth naming: `[]` when the flag is
+ * absent (the command writes where it stands, which is the working directory),
+ * `[value]` when the flag names something the text can read, and `[null]` when
+ * the flag is PRESENT and its value is not in the words. The last is a refusal
+ * rather than an absence, because a flag present with nothing readable after it
+ * would otherwise be answered as "no destination named" and take the looser
+ * branch.
+ */
+function namedDestination(args, names) {
+    if (!hasFlag(args, names))
+        return [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        const equals = arg.indexOf("=");
+        const name = equals === -1 ? arg : arg.slice(0, equals);
+        if (!names.includes(name))
+            continue;
+        if (equals !== -1) {
+            const value = arg.slice(equals + 1);
+            return [value.length === 0 ? null : value];
+        }
+        const value = args[index + 1];
+        return [value === undefined || isFlag(value) ? null : value];
+    }
+    return [null];
+}
+/**
+ * The class of a write into destinations the command names (APRV-397).
+ *
+ * The same fail-closed branches {@link refineRm} has, in the same order,
+ * against the same roots: all-scratch loosens, and an unreadable destination, an
+ * absolute one, or a `..` segment is out of scope with the destination BOUND so
+ * an approver is told which path earned the class. An empty destination list is
+ * the working directory, which this file cannot see and must not guess at, so it
+ * takes the row's own workspace answer exactly as `rm` with no target does.
+ */
+function scopedWrite(ctx, destinations, rule) {
+    const named = destinations.filter((entry) => entry !== null);
+    if (named.length < destinations.length) {
+        return { class: OUT_OF_SCOPE_WRITE_CLASS, rule: OUT_OF_SCOPE_WRITE_RULE };
+    }
+    if (allTargetsAreScratch(named, ctx.context.scratchRoots ?? [])) {
+        return { class: "files.write.workspace", rule };
+    }
+    for (const destination of named) {
+        if (destination.startsWith("/") ||
+            pathSegments(destination).includes("..") ||
+            isUnknownValue(destination)) {
+            return { class: OUT_OF_SCOPE_WRITE_CLASS, rule: OUT_OF_SCOPE_WRITE_RULE, path: destination };
+        }
+    }
+    return { class: "files.write.workspace", rule };
+}
+/**
+ * An argv that asks a binary about itself: a version or a usage string.
+ *
+ * The harness table has its own copy of this idea ({@link HARNESS_PROBE_FLAGS})
+ * and keeps it, because a harness probe still EXECUTES a whole second agent's
+ * binary and is named in {@link CODE_EXECUTING_RULES} for that reason. This one
+ * is the package managers', where `npm --version` prints a string and starts
+ * nothing at all. `-v` is here and absent there: it is npm's version flag and
+ * nothing else's.
+ */
+const VERSION_PROBE_FLAGS = ["--version", "-v", "-V", "--help", "-h"];
+/** Is this argv nothing but probe flags? One word at minimum, so a bare binary is not a probe. */
+function isVersionProbe(args) {
+    return args.length > 0 && args.every((arg) => VERSION_PROBE_FLAGS.includes(arg));
+}
+/** Positionals, with the values of value-taking flags left out of the count. */
+function positionalsBesideValues(args, valueFlags) {
+    const out = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (isFlag(arg)) {
+            if (valueFlags.includes(arg))
+                index += 1;
+            continue;
+        }
+        out.push(arg);
+    }
+    return out;
+}
+/** `npm pack`'s flags whose value is a path or a workspace name, never a package spec. */
+const NPM_PACK_VALUE_FLAGS = ["--pack-destination", "--workspace", "-w"];
+/**
+ * Does this `npm pack` argument name something on disk rather than a registry
+ * package?
+ *
+ * A path, in the spellings npm accepts for one. Everything else is a package
+ * spec, which `npm pack` resolves by FETCHING it, and a value the text cannot
+ * read is a spec too: the looser reading of an unreadable argument is the one
+ * that lets a download through as a local pack.
+ */
+function isLocalPackSpec(spec) {
+    if (isUnknownValue(spec))
+        return false;
+    if (spec.startsWith(".") || spec.startsWith("/"))
+        return true;
+    return spec.includes("/") && !spec.startsWith("@");
+}
+/**
+ * `npm pack` — a tarball into the working directory, or into
+ * `--pack-destination`.
+ *
+ * Two answers beside the scoped write. A positional naming a REGISTRY package
+ * is `network.call`, because that spelling downloads the package before it packs
+ * it and the tarball it then writes is beside the point. And the write itself
+ * runs the package's own `prepack` and `prepare` scripts, which is why the rule
+ * id is in {@link CODE_EXECUTING_RULES}.
+ */
+function refineNpmPack(ctx) {
+    const specs = positionalsBesideValues(ctx.args, NPM_PACK_VALUE_FLAGS).slice(1);
+    if (specs.some((spec) => !isLocalPackSpec(spec))) {
+        return { class: "network.call", rule: "npm-pack-remote" };
+    }
+    return scopedWrite(ctx, namedDestination(ctx.args, ["--pack-destination"]), "npm-pack");
+}
+/**
+ * `npm init` — `package.json` into the working directory.
+ *
+ * No flag moves it, so there is no destination to scope and the answer is the
+ * workspace write the row declares. `npm init <pkg>` is a different act, since
+ * it downloads an initializer and runs it, which is `npm exec` wearing another
+ * name; it takes its own rule id and its seat in {@link CODE_EXECUTING_RULES}
+ * beside `npm-script`.
+ */
+function refineNpmInit(ctx) {
+    const initializer = positionalsBesideValues(ctx.args, ["--workspace", "-w"]).slice(1);
+    return initializer.length === 0
+        ? { class: "files.write.workspace", rule: "npm-init" }
+        : { class: "files.write.workspace", rule: "npm-init-create" };
+}
+/** `tar`'s long spellings of each mode, beside the one-letter ones. */
+const TAR_LIST_FLAGS = ["--list"];
+const TAR_EXTRACT_FLAGS = ["--extract", "--get"];
+const TAR_CREATE_FLAGS = [
+    "--create",
+    "--append",
+    "--update",
+    "--delete",
+    "--concatenate",
+    "--catenate",
+];
+/** The argv that ask `tar` about itself and open no archive at all. */
+const TAR_PROBE_FLAGS = ["--version", "--help", "--usage"];
+/**
+ * The mode letters `tar` was given, from the short bundles and the old-style
+ * first word.
+ *
+ * `tar xzf a.tgz` carries no dash at all, and it is the spelling most sessions
+ * write, so a rule that read only `-x` would answer the common form with a
+ * refusal. Only the FIRST word can be an old-style bundle, and a word is read as
+ * a bundle only when it is letters and nothing else: `-fa.tgz` is a glued
+ * filename, and a letter taken out of a filename is a mode the command never
+ * named. Dropping such a word costs a refusal (the mode becomes unreadable) and
+ * can never invent a read.
+ */
+function tarModeLetters(args) {
+    let letters = "";
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (/^-[A-Za-z]+$/u.test(arg))
+            letters += arg.slice(1);
+        else if (index === 0 && /^[A-Za-z]+$/u.test(arg))
+            letters += arg;
+    }
+    return letters;
+}
+/** The tar letters that consume the next word, which is what makes a bundle ambiguous. */
+const TAR_VALUE_LETTERS = ["f", "C"];
+/** The option letters of a tar word, or `null` when it is not a bundle of them. */
+function tarBundle(arg, index) {
+    if (/^-[A-Za-z]+$/u.test(arg))
+        return arg.slice(1);
+    if (index === 0 && /^[A-Za-z]+$/u.test(arg))
+        return arg;
+    return null;
+}
+/**
+ * The value a tar flag carries, in every spelling tar accepts for it.
+ *
+ * The glued bundle is the whole reason this exists rather than
+ * {@link namedDestination}: `tar -czf out.tgz src` names its archive with an
+ * `f` buried in `-czf`, which an exact-word flag match cannot see, and a rule
+ * that missed it would answer the commonest spelling of a create with the
+ * looser branch.
+ *
+ * One bundle carrying BOTH value-taking letters (`-xCf`) is `null`, which
+ * {@link scopedWrite} refuses: which of the following words feeds which letter
+ * depends on tar's own option order, so the destination is not in the text
+ * (SPEC.md §11.1, ambiguity resolves to the stricter class).
+ */
+function tarFlagValue(args, letter, longNames) {
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        const equals = arg.indexOf("=");
+        const name = equals === -1 ? arg : arg.slice(0, equals);
+        if (longNames.includes(name)) {
+            if (equals === -1) {
+                const next = args[index + 1];
+                return [next === undefined || isFlag(next) ? null : next];
+            }
+            const value = arg.slice(equals + 1);
+            return [value.length === 0 ? null : value];
+        }
+        const bundle = tarBundle(arg, index);
+        if (bundle === null || !bundle.includes(letter))
+            continue;
+        if (TAR_VALUE_LETTERS.filter((candidate) => bundle.includes(candidate)).length > 1) {
+            return [null];
+        }
+        const next = args[index + 1];
+        return [next === undefined || isFlag(next) ? null : next];
+    }
+    return [];
+}
+/**
+ * `tar` — a listing reads, an extraction writes where `-C` points, a creation
+ * writes the archive `-f` names.
+ *
+ * The write branch is checked FIRST and takes both destinations when one command
+ * names both modes, because `tar` resolves a contradictory mode by its own
+ * option order and the stricter reading is the one that assumes it writes.
+ *
+ * A mode the text does not carry is `opaque` rather than a guess, and that is
+ * the honest code for it: a `tar` whose mode is not in its words is a command
+ * whose effect is not in its words, which is what {@link OPAQUE_BINS} refuses
+ * for the same reason.
+ */
+function refineTar(ctx) {
+    const letters = tarModeLetters(ctx.args);
+    const extracting = letters.includes("x") || hasFlag(ctx.args, TAR_EXTRACT_FLAGS);
+    const creating = ["c", "r", "u", "A"].some((letter) => letters.includes(letter)) ||
+        hasFlag(ctx.args, TAR_CREATE_FLAGS);
+    if (extracting || creating) {
+        const destinations = [
+            ...(extracting ? tarFlagValue(ctx.args, "C", ["--directory"]) : []),
+            ...(creating ? tarFlagValue(ctx.args, "f", ["--file"]) : []),
+        ];
+        return scopedWrite(ctx, destinations, extracting ? "tar-extract" : "tar-create");
+    }
+    if (letters.includes("t") || hasFlag(ctx.args, TAR_LIST_FLAGS)) {
+        return { class: "read.shell", rule: "tar-list" };
+    }
+    if (ctx.args.length > 0 && ctx.args.every((arg) => TAR_PROBE_FLAGS.includes(arg))) {
+        return { class: "read.shell", rule: "tar-probe" };
+    }
+    return { opaque: "tar names no mode this classifier can read" };
+}
+/**
+ * `gunzip` — the stdout, test and list forms read; every other form REPLACES a
+ * file.
+ *
+ * The default is the trap: `gunzip pkg.tgz` removes `pkg.tgz` and leaves
+ * `pkg.tar` in its place, so the plain spelling is a write of the path it names.
+ * Three flags leave the disk alone: `-c`/`--stdout` decompresses to standard
+ * output, `-t`/`--test` checks the integrity of the archive, and `-l`/`--list`
+ * prints the compressed and uncompressed sizes, the ratio and the member name.
+ * A listing is the same kind of act as `tar -t` beside it and belongs in the
+ * same class. `-k` (`--keep`) is deliberately not a read: it spares the input
+ * and still creates the output.
+ */
+function refineGunzip(ctx) {
+    const reading = hasShortFlag(ctx.args, ["c", "t", "l"]) ||
+        hasFlag(ctx.args, ["--stdout", "--to-stdout", "--test", "--list"]);
+    return reading
+        ? { class: "read.shell", rule: "gunzip-read" }
+        : scopedWrite(ctx, ctx.positionals, "gunzip-write");
+}
+/** `base64` — a read of what it names, unless `-o` names a file to write. */
+function refineBase64(ctx) {
+    const destination = namedDestination(ctx.args, ["-o", "--output"]);
+    return destination.length === 0
+        ? { class: "read.shell", rule: "base64-read" }
+        : scopedWrite(ctx, destination, "base64-write");
+}
+/**
+ * `openssl`'s digest subcommands, and only those.
+ *
+ * The row names the digests rather than the binary, so `openssl enc`, `genrsa`,
+ * `req`, `rand` and `s_client` stay exactly as unclassified as they were. Each
+ * of those writes key material, encrypts, or opens a socket, and none of them is
+ * what a release verification runs; a row for the binary would have swept all of
+ * them into a read.
+ */
+const OPENSSL_DIGEST_SUBS = [
+    "dgst",
+    "md5",
+    "sha1",
+    "sha256",
+    "sha384",
+    "sha512",
+];
+/** `openssl dgst …` — a read of its named files, unless `-out` names one to write. */
+function refineOpensslDigest(ctx) {
+    const destination = namedDestination(ctx.args, ["-out"]);
+    return destination.length === 0
+        ? { class: "read.shell", rule: "openssl-digest" }
+        : scopedWrite(ctx, destination, "openssl-digest-out");
+}
+/**
+ * `git tag` — the listing forms read (APRV-397).
+ *
+ * APRV-305 gave the whole verb `release.publish`, which is right for the half
+ * of it that creates, moves, signs and deletes tags: a tag is the name a
+ * release was published under. It is wrong for the other half. `git tag -l` is
+ * a listing of local refs, and on 2026-09-20 it put a nine-minute question on a
+ * phone during a state check. Nothing about a listing reaches a registry, a
+ * remote or a consumer, and the class it takes is `read.shell`, the class every
+ * other reader of local repository metadata takes (`git log`, `git branch`,
+ * `git status`).
+ *
+ * The split is an ALLOWLIST of the flags that list, and that direction is the
+ * whole safety argument: a flag this rule has never heard of is a creation, so a
+ * future `git tag` option cannot arrive as a read by default. A positional is a
+ * TAG NAME, which creates one, unless `-l` is present and makes it a pattern.
+ * The shape mirrors {@link refineGitBranch}, which splits read and write halves
+ * of one verb for the same reason.
+ */
+const GIT_TAG_READ_FLAGS = [
+    "-l",
+    "--list",
+    "-n",
+    "-i",
+    "--ignore-case",
+    "--omit-empty",
+    "--column",
+    "--no-column",
+    "--color",
+    "--no-color",
+];
+/** Listing flags whose next word is a value rather than a tag name. */
+const GIT_TAG_READ_VALUE_FLAGS = [
+    "--contains",
+    "--no-contains",
+    "--points-at",
+    "--merged",
+    "--no-merged",
+    "--sort",
+    "--format",
+];
+function refineGitTag(ctx) {
+    const publish = { class: "release.publish", rule: "git-tag" };
+    const args = ctx.args.slice(1);
+    const names = [];
+    let listing = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!isFlag(arg)) {
+            names.push(arg);
+            continue;
+        }
+        const equals = arg.indexOf("=");
+        const name = equals === -1 ? arg : arg.slice(0, equals);
+        if (name === "-l" || name === "--list") {
+            listing = true;
+            continue;
+        }
+        if (GIT_TAG_READ_FLAGS.includes(name) || /^-n\d+$/u.test(arg))
+            continue;
+        if (GIT_TAG_READ_VALUE_FLAGS.includes(name)) {
+            if (equals === -1)
+                index += 1;
+            continue;
+        }
+        // Everything the allowlist does not name: a creation, a deletion, a
+        // signature, a force-move, and also a flag that did not exist when this rule
+        // was written.
+        return publish;
+    }
+    return names.length > 0 && !listing ? publish : { class: "read.shell", rule: "git-tag-read" };
+}
 /**
  * The methods a fetch may name and still be a read: GET, and HEAD, which is a
  * GET that discards the body. Everything else, including a method the
@@ -1427,12 +2360,28 @@ 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" };
     }
@@ -1454,6 +2403,19 @@ function refineApprovalVerb(positionals) {
             return { class: "policy.core", rule: "approval-log-checkpoint" };
         return null;
     }
+    // APRV-455. `channel relay` records gestures attributed to an EdgeOS account
+    // on the word of whoever holds a secret the LAUNCHER chose. An agent that
+    // could start one with a secret of its own, and post to it, would write
+    // records that read as transport-authenticated evidence from a person's
+    // session, which a Telegram listener cannot be made to do without the bot
+    // token. So starting it is the operator's ceremony: `policy.core`, held
+    // human-only by the reference policy, and the hook denies it with
+    // `hook-class-human-only`. A deployment starts it from its own launcher, as
+    // the store's user, outside any agent's hook. It mints no new class (SPEC.md
+    // §11.1 invariant 9).
+    if (verb === "channel" && sub === "relay") {
+        return { class: "policy.core", rule: "approval-channel-relay" };
+    }
     if (verb === "gate") {
         if (sub === "open")
             return { class: "policy.core", rule: "approval-gate-open" };
@@ -1461,6 +2423,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
@@ -1487,7 +2465,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
@@ -1500,7 +2478,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",
         });
@@ -1524,7 +2502,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,
     },
     {
@@ -1536,7 +2514,16 @@ export const COMMAND_RULES = [
     { id: "git-reset", bins: ["git"], subs: ["reset"], class: "vcs.commit.branch", emits: ["vcs.history.rewrite"], refine: refineGitReset },
     { id: "git-commit", bins: ["git"], subs: ["commit"], class: "vcs.commit.branch", emits: ["vcs.history.rewrite"], refine: refineGitCommit },
     { id: "git-branch", bins: ["git"], subs: ["branch"], class: "read.shell", emits: ["vcs.commit.branch"], refine: refineGitBranch },
-    { id: "git-tag", bins: ["git"], subs: ["tag"], class: "release.publish" },
+    // APRV-397 split the verb: the listing flags read, everything else publishes.
+    // See {@link refineGitTag} for why the split is an allowlist.
+    {
+        id: "git-tag",
+        bins: ["git"],
+        subs: ["tag"],
+        class: "release.publish",
+        emits: ["read.shell"],
+        refine: refineGitTag,
+    },
     { id: "git-clone", bins: ["git"], subs: ["clone"], class: "network.call" },
     {
         id: "git-write",
@@ -1618,7 +2605,30 @@ export const COMMAND_RULES = [
         refine: refineGh,
     },
     // -- package managers ----------------------------------------------------
+    // APRV-397. The probe row matches ONLY an argv that is nothing but version or
+    // help flags, which is what `probe` means and what keeps `npm doctor`,
+    // `npm cache clean` and every other subcommand this table does not name at the
+    // `unclassified` deny they have today. `npm version` is a different word and
+    // keeps its `release.publish` row below.
+    { id: "npm-version", bins: ["npm", "pnpm", "yarn", "bun"], class: "read.shell", probe: true },
     { id: "npm-publish", bins: ["npm", "pnpm", "yarn", "bun"], subs: ["publish", "version", "deprecate", "dist-tag", "unpublish"], class: "release.publish" },
+    // APRV-397: the two package-manager verbs that write into a directory they
+    // name rather than touching the registry or the lockfile.
+    {
+        id: "npm-pack",
+        bins: ["npm", "pnpm", "yarn", "bun"],
+        subs: ["pack"],
+        class: "files.write.workspace",
+        emits: [OUT_OF_SCOPE_WRITE_CLASS, "network.call"],
+        refine: refineNpmPack,
+    },
+    {
+        id: "npm-init",
+        bins: ["npm", "pnpm", "yarn", "bun"],
+        subs: ["init"],
+        class: "files.write.workspace",
+        refine: refineNpmInit,
+    },
     { id: "npm-install", bins: ["npm", "bun"], subs: ["install", "i", "add"], class: "deps.add", emits: ["deps.install"], refine: refineNpmInstall },
     { id: "yarn-add", bins: ["yarn", "pnpm"], subs: ["add"], class: "deps.add" },
     { id: "yarn-install", bins: ["yarn", "pnpm"], subs: ["install"], class: "deps.install" },
@@ -1649,8 +2659,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}.
@@ -1672,6 +2694,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",
@@ -1695,6 +2725,40 @@ export const COMMAND_RULES = [
         emits: ["files.delete.out_of_scope", "files.write.workspace"],
         refine: refineFind,
     },
+    // -- packaging and archives (APRV-397) -----------------------------------
+    // Four binaries a release verification cannot do without, each of which either
+    // reads what it names or writes into a destination it names. The section
+    // comment above {@link OUT_OF_SCOPE_WRITE_CLASS} holds the reasoning; these
+    // rows only say which binary reaches which refinement.
+    {
+        id: "tar",
+        bins: ["tar"],
+        class: "files.write.workspace",
+        emits: ["read.shell", OUT_OF_SCOPE_WRITE_CLASS],
+        refine: refineTar,
+    },
+    {
+        id: "gunzip",
+        bins: ["gunzip"],
+        class: "files.write.workspace",
+        emits: ["read.shell", OUT_OF_SCOPE_WRITE_CLASS],
+        refine: refineGunzip,
+    },
+    {
+        id: "base64",
+        bins: ["base64"],
+        class: "read.shell",
+        emits: ["files.write.workspace", OUT_OF_SCOPE_WRITE_CLASS],
+        refine: refineBase64,
+    },
+    {
+        id: "openssl-digest",
+        bins: ["openssl"],
+        subs: OPENSSL_DIGEST_SUBS,
+        class: "read.shell",
+        emits: ["files.write.workspace", OUT_OF_SCOPE_WRITE_CLASS],
+        refine: refineOpensslDigest,
+    },
     // -- network -------------------------------------------------------------
     // The HTTP clients split on their flags; the transports do not. What `ssh`,
     // `rsync` or `nc` will do at the far end is not written in the argv, so there
@@ -1830,9 +2894,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",
@@ -1854,6 +2926,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"],
@@ -1916,6 +3075,70 @@ function protectedRank(surface) {
     const index = PROTECTED_PRECEDENCE.indexOf(surface);
     return index === -1 ? PROTECTED_PRECEDENCE.indexOf("policy.edit") : index;
 }
+/**
+ * Is this word PROSE that merely spells a protected path, rather than a path?
+ * (APRV-409.)
+ *
+ * The incident: a `backlog task create` whose acceptance-criterion argument
+ * began with the literal text of a workflow path and continued into a sentence
+ * classified `policy.edit.ci`, sat the full hook wait on the gate and was
+ * denied on timeout. The command writes one task file and touches no workflow.
+ * {@link pathSegments} splits on slashes only, so a word whose leading segments
+ * are a protected DIRECTORY run prefix-matches whatever follows those slashes,
+ * sentence included. An exact-file entry does not, because it matches on the
+ * FINAL segment, which is why the same sentence beginning `CLAUDE.md` always
+ * classified as an ordinary workspace write.
+ *
+ * The test drawn here is the narrow one, and it is narrow in a stated way: the
+ * word is prose only when the protected match came ENTIRELY from a
+ * whitespace-free head. Concretely, all three hold:
+ *
+ * 1. the word contains whitespace at all;
+ * 2. the first of its segments carrying whitespace is not the first segment,
+ *    so there is a head in front of it;
+ * 3. that head, on its own, already classifies as the SAME surface the whole
+ *    word did.
+ *
+ * When (3) fails the word is kept, which is the fail-closed direction and is
+ * what keeps the shapes below unmoved:
+ *
+ * - `my notes/CLAUDE.md` and any other exact-file match at any depth: the match
+ *   needs the final segment, the head classifies as nothing, and the word keeps
+ *   `policy.edit`. A real file named with a space therefore stays protected.
+ * - `my notes/.github/workflows/x.yml`: whitespace BEFORE the protected run,
+ *   head `my notes` classifies as nothing, word unmoved.
+ * - every word with no whitespace at all, which is the whole ordinary universe
+ *   of paths: condition (1) fails before anything is computed.
+ *
+ * What does move is the one shape prose and a path share exactly: a
+ * directory-prefix match whose remainder carries whitespace. `cp x
+ * ".approval/my file.txt"` is a real path of that shape and now takes the
+ * command's own class. That is a deliberate trade and not an oversight —
+ * `my file.txt` and `ci.yml should not gate this task` are the same string
+ * shape, and no pure, disk-free rule tells them apart. A threshold on how much
+ * whitespace the remainder carries would have rescued the first, and it is
+ * rejected: a number here is folklore a second implementation has to guess at,
+ * and the conformance suite would be pinning it. The write itself is not
+ * unguarded: `core/protected-path-guard.ts` judges what a commit actually
+ * changed, from the log rather than from a session, and a `.approval/` file
+ * with no authorization record still fails the pull request.
+ *
+ * Pure and disk-free like the rest of this file: no resolution, no stat, no
+ * question about whether anything exists.
+ */
+function proseNamingProtectedPath(word, surface, protectedPaths) {
+    if (!/\s/u.test(word))
+        return false;
+    const segments = pathSegments(word);
+    const firstSpaced = segments.findIndex((segment) => /\s/u.test(segment));
+    // `-1` is a word whose whitespace survived no segment (nothing produces it
+    // today) and `0` is whitespace in or before the first segment: both leave no
+    // whitespace-free head to have matched, so both keep the word.
+    if (firstSpaced <= 0)
+        return false;
+    const head = segments.slice(0, firstSpaced).join("/");
+    return protectedPathClass(head, protectedPaths) === surface;
+}
 /**
  * The strictest protected surface named by these words, with the word itself.
  *
@@ -1926,13 +3149,22 @@ function protectedRank(surface) {
  * did and is what keeps a bare-string policy byte-identical: two routed paths
  * in one segment are two equally consequential surfaces, and the segment's
  * class names one of them while `ClassifiedSegment.path` names the word.
+ *
+ * `skipProse` turns on {@link proseNamingProtectedPath} (APRV-409) and is
+ * passed by the POSITIONAL scan alone. The other caller here is the
+ * write-redirection targets, whose words are paths by construction — the shell
+ * is about to create that file — and the same is true of the paths
+ * `core/apply-patch.ts` and the hook's file-tool pass hand to
+ * {@link protectedPathClass} directly. None of them is offered the skip.
  */
-function strictestProtected(words, protectedPaths) {
+function strictestProtected(words, protectedPaths, skipProse = false) {
     let best = null;
     for (const word of words) {
         const surface = protectedPathClass(word, protectedPaths);
         if (surface === null)
             continue;
+        if (skipProse && proseNamingProtectedPath(word, surface, protectedPaths))
+            continue;
         if (best === null || protectedRank(surface) < protectedRank(best.surface)) {
             best = { surface, path: word };
         }
@@ -1962,6 +3194,32 @@ export const CODE_EXECUTING_RULES = [
     "node-script",
     /** `npx`, `tsx`, `tsc`, `vitest`, `jest`, `make`, and kin. */
     "workspace-tool",
+    /**
+     * `npm pack` and `npm init <initializer>` (APRV-397).
+     *
+     * Both run code the runtime did not author, for different reasons. `npm pack`
+     * runs the package's own `prepack` and `prepare` scripts, which are files in
+     * the workspace an agent may have written a minute ago, exactly as `npm test`
+     * is. `npm init <pkg>` downloads an initializer and runs it, which is
+     * `npm exec` wearing another name. A bare `npm init` writes `package.json` and
+     * runs nothing, so it is absent.
+     */
+    "npm-pack",
+    "npm-init-create",
+    /**
+     * 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.
@@ -1988,8 +3246,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.)
@@ -2005,10 +3300,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);
@@ -2098,11 +3400,18 @@ function sandboxWrapper(words, start) {
     // can produce (`docs/sandboxed-exec.md`, and APRV-193's Linux follow-up).
     return null;
 }
-/** Find the first table row matching this binary and subcommand. */
-function matchRule(bin, sub) {
+/**
+ * Find the first table row matching this binary, subcommand and argv.
+ *
+ * The argv is read for one purpose only (APRV-397): a `probe` row matches an
+ * argv that is nothing but version or help flags, and no other row reads it.
+ */
+function matchRule(bin, sub, args) {
     for (const rule of COMMAND_RULES) {
         if (!rule.bins.includes(bin))
             continue;
+        if (rule.probe === true && !isVersionProbe(args))
+            continue;
         if (rule.subs !== undefined) {
             if (sub === null || !rule.subs.includes(sub))
                 continue;
@@ -2226,7 +3535,7 @@ function classifySegment(segment, protectedPaths, context) {
     if (credential !== null)
         return { ok: true, ...credential };
     const sub = positionals[0] ?? null;
-    const rule = matchRule(basename, sub);
+    const rule = matchRule(basename, sub, args);
     if (rule === null) {
         return {
             ok: false,
@@ -2250,14 +3559,25 @@ 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
     // direction-blind — a copy OUT of the policy directory is as gated as a copy
     // into it, because the classifier cannot tell which argument the binary will
     // treat as the destination and guessing would be the ungated direction.
+    //
+    // This is the ONE scan that skips prose (APRV-409, `skipProse`): a positional
+    // is whatever the author quoted, and an acceptance criterion that opens with
+    // a directory path is a sentence rather than a file. Redirection targets
+    // above, and the apply-patch and file-tool paths elsewhere, are paths by
+    // construction and are not offered the skip.
     if (!cls.startsWith("read.") && cls !== GATE_SELF_CLASS) {
-        const named = strictestProtected(positionals, protectedPaths);
+        const named = strictestProtected(positionals, protectedPaths, true);
         if (named !== null) {
             return { ok: true, class: named.surface, rule: "protected-path", path: named.path };
         }
@@ -2268,7 +3588,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.
@@ -2305,6 +3649,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 };
@@ -2336,6 +3704,43 @@ export function classifyCommand(command, protectedPaths = [], context = {}) {
  * `classifyCommand` answers `unparseable` for. Segments carrying no binary (a
  * bare assignment, a lone redirection) are omitted: they have no verb to show.
  */
+/**
+ * The paths each segment WRITES through a redirection, from the same parse
+ * (APRV-445). `<` is a read and is left out, as are the discard devices.
+ * `null` when the tokenizer refuses the string.
+ */
+export function commandSegmentWriteTargets(command) {
+    const lexed = lex(command);
+    if (!lexed.ok)
+        return null;
+    return lexed.segments.map((segment) => segment.redirects
+        .filter((redirect) => redirect.op !== "<")
+        .map((redirect) => redirect.target.text)
+        .filter((target) => !isDiscardTarget(target)));
+}
+export function commandSegmentShapes(command) {
+    const lexed = lex(command);
+    if (!lexed.ok)
+        return null;
+    return lexed.segments.map((segment) => {
+        const words = segment.words.map((word) => word.text);
+        let cursor = 0;
+        while (cursor < words.length && ASSIGNMENT.test(words[cursor]))
+            cursor += 1;
+        return {
+            text: segment.text,
+            bin: words[cursor] ?? null,
+            args: words.slice(cursor + 1),
+            writes: segment.redirects
+                .filter((redirect) => redirect.op !== "<")
+                .map((redirect) => redirect.target.text)
+                .filter((target) => !isDiscardTarget(target)),
+            reads: segment.redirects
+                .filter((redirect) => redirect.op === "<")
+                .map((redirect) => redirect.target.text),
+        };
+    });
+}
 export function commandSegmentWords(command) {
     const lexed = lex(command);
     if (!lexed.ok)