approval-md 0.3.0 → 0.4.0

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

@@ -58,6 +58,14 @@ import { READ_OUT_OF_SCOPE_CLASS, isUnreadableTarget, readTargetVerdict, readTar
  * 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).
@@ -286,6 +294,79 @@ export function protectedPathClass(candidate, extra = []) {
                 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];
@@ -429,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)
@@ -1181,6 +1284,11 @@ const HARNESS_BINS = {
     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.
@@ -1198,6 +1306,13 @@ const HARNESS_PACKAGES = {
     "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.
@@ -1498,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
@@ -1865,6 +2403,19 @@ function refineApprovalVerb(positionals, args = []) {
             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" };
@@ -1963,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",
@@ -2045,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" },
@@ -2142,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
@@ -2458,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.
  *
@@ -2468,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 };
         }
@@ -2504,6 +3194,18 @@ 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).
      *
@@ -2698,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;
@@ -2826,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,
@@ -2861,8 +3570,14 @@ function classifySegment(segment, protectedPaths, context) {
     // 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 };
         }
@@ -2989,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)