polydeukes 0.6.0 → 0.7.1

package/dist/covenant/run-covenant.js

@@ -0,0 +1,164 @@
+/**
+ * `runCovenant` — the covenant execution wrapper.
+ *
+ * Calls an in-process judge thunk the assembly has already bound its payload and options
+ * into, translates the thunk's exit-code equivalent by policy (1 → blocking 2), writes the
+ * break reason to stderr, and appends exactly one telemetry record per call via
+ * {@link appendRecordFailOpen} (the core's fail-open wrapper around its sole collector —
+ * no local logger). {@link translateExitCode} is pure.
+ */
+import { appendRecordFailOpen, EXIT_BREAK_BLOCKING, EXIT_BREAK_NON_BLOCKING, EXIT_UPHOLD, } from '@polydeukes/core';
+/**
+ * How many witness elements one break contributes to a telemetry row. A relation over a
+ * large file can return thousands, and the row is one line — the true count rides beside
+ * the truncated list rather than being lost with it.
+ */
+const WITNESSES_PER_BREAK = 8;
+/**
+ * How many characters of one witness value the row keeps. A witness over a bare `source`
+ * step is the whole file, and the row is one line — the value is cut with its true length
+ * beside it rather than dropped.
+ */
+const WITNESS_VALUE_CHARS = 200;
+/** A witness whose serialized value fits the row; a longer one is cut and says so. */
+function boundedWitness(witness) {
+    const serialized = JSON.stringify(witness.value);
+    if (serialized === undefined || serialized.length <= WITNESS_VALUE_CHARS)
+        return witness;
+    return {
+        ...witness,
+        value: serialized.slice(0, WITNESS_VALUE_CHARS),
+        truncated: serialized.length,
+    };
+}
+/**
+ * Serialize a body's breaks into the row's fifth field: id, capped witnesses, true total —
+ * or nothing when a value cannot be serialized. Telemetry is fail-open, so a witness
+ * carrying a value `JSON.stringify` refuses costs the row its fifth field, never the verdict.
+ */
+function serializeWitnesses(breaks) {
+    try {
+        return JSON.stringify(breaks.map((entry) => ({
+            id: entry.id,
+            witnesses: entry.witnesses.slice(0, WITNESSES_PER_BREAK).map(boundedWitness),
+            total: entry.witnesses.length,
+        })));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Translate a body outcome into the wrapper verdict and telemetry event (pure).
+ *
+ * `bodyExitCode === 0` (uphold) passes; every other outcome — a break report (`1`), the
+ * body's own fail-closed (`2`), any uninterpretable code (`3+`), or a body that answered
+ * nothing interpretable (`null`) — is fail-closed to the blocking `2` / `blocked`. The
+ * unconditional 1→2 translation lives here, isolated, so it has one place to evolve in.
+ *
+ * `enforce` relaxes ONLY the verdict cell: under `advise` a break report (`1`) becomes
+ * `0` / `advised` — recorded, not blocking. Every unjudgeable outcome (`2`, `3+`, `null`)
+ * stays `2` / `blocked` regardless of level.
+ */
+export function translateExitCode(bodyExitCode, enforce = 'block') {
+    if (bodyExitCode === EXIT_UPHOLD) {
+        return { exitCode: EXIT_UPHOLD, event: 'passed' };
+    }
+    if (enforce === 'advise' && bodyExitCode === EXIT_BREAK_NON_BLOCKING) {
+        return { exitCode: EXIT_UPHOLD, event: 'advised' };
+    }
+    return { exitCode: EXIT_BREAK_BLOCKING, event: 'blocked' };
+}
+/**
+ * Run the judge thunk and normalize what it answers.
+ *
+ * A throw is the body-crash cell, so crash isolation is this try/catch. A resolution that
+ * is not the outcome shape (a stale dist answering an older contract) is uninterpretable
+ * and lands in the same cell: `null` routes to the translation table's fail-closed row
+ * without that table learning a new code.
+ */
+async function runBody(body) {
+    let outcome;
+    try {
+        outcome = await body();
+    }
+    catch {
+        return { exitCode: EXIT_BREAK_BLOCKING };
+    }
+    if (typeof outcome !== 'object' || outcome === null) {
+        return { exitCode: EXIT_BREAK_BLOCKING };
+    }
+    return outcome;
+}
+/** Turn a pure judge's verdict into the outcome a thunk answers. */
+export function outcomeFromVerdict(verdict) {
+    return verdict.upheld
+        ? { exitCode: EXIT_UPHOLD }
+        : { exitCode: EXIT_BREAK_NON_BLOCKING, reason: verdict.reason };
+}
+/** The unjudgeable outcome: a misassembly or an input no judge could read (`2`, no reason). */
+export const UNJUDGEABLE_OUTCOME = { exitCode: EXIT_BREAK_BLOCKING };
+/** Consult the valve, counting a throw as closed — an uncertain valve never opens. */
+function witnessOpens(witness) {
+    try {
+        return witness() === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Run a covenant body through the wrapper.
+ *
+ * The order is judge → translate → valve: the body always runs, and only a `blocked`
+ * translation has anything for the valve to relax into `0` / `witnessed`. Whatever that
+ * leaves is recorded ONCE — one call, one row — so a witnessed break never leaves a
+ * `blocked` row beside its `witnessed` one.
+ *
+ * The break reason goes to stderr whenever the thunk carried one, whatever the level and
+ * whatever the final event: gating it on the verdict would leave `advised` mute and the
+ * valve silent about what it opened.
+ *
+ * A body that answers `skipped` evaluated no relation, so it never reaches the translation
+ * table or the valve: the row says so and the call upholds.
+ *
+ * Resolves with the wrapper's final `exitCode` (`0` or `2`) and the telemetry `event` that
+ * was recorded. The event is surfaced rather than left to callers: the valve is impure, so
+ * recomputing the event would consult it a second time. Logging is fail-open
+ * via {@link appendRecordFailOpen}: a telemetry failure never alters the verdict and never
+ * throws. The gate closes; the measurement stays open.
+ */
+export async function runCovenant(spec) {
+    const outcome = await runBody(spec.body);
+    // A code the outcome does not carry as a number is uninterpretable, and `null` is the
+    // table's existing cell for exactly that — no new row in translateExitCode.
+    const bodyExitCode = typeof outcome.exitCode === 'number' ? outcome.exitCode : null;
+    if (typeof outcome.reason === 'string' && outcome.reason !== '') {
+        process.stderr.write(`${outcome.reason}\n`);
+    }
+    // A skip token beside a non-zero code is a body contradicting itself; the break wins, so a
+    // verdict is never downgraded by a stray token.
+    if (outcome.skipped !== undefined && bodyExitCode === EXIT_UPHOLD) {
+        appendRecordFailOpen(spec.telemetryPath, {
+            event: 'skipped',
+            label: spec.label,
+            subject: spec.subject ?? '-',
+            reason: outcome.skipped,
+        });
+        return { exitCode: EXIT_UPHOLD, event: 'skipped' };
+    }
+    const verdict = translateExitCode(bodyExitCode, spec.enforce);
+    const { exitCode, event } = verdict.event === 'blocked' && spec.witness !== undefined && witnessOpens(spec.witness)
+        ? { exitCode: EXIT_UPHOLD, event: 'witnessed' }
+        : verdict;
+    const serialized = Array.isArray(outcome.witnesses)
+        ? serializeWitnesses(outcome.witnesses)
+        : undefined;
+    appendRecordFailOpen(spec.telemetryPath, {
+        event,
+        label: spec.label,
+        subject: spec.subject ?? '-',
+        ...(serialized !== undefined && { witnesses: serialized }),
+    });
+    return { exitCode, event };
+}

package/dist/covenant/self-mod.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `judgeSelfModification` — the self-mod meta-covenant's pure judge (zero I/O).
+ *
+ * Breaks when a *mutating* tool call (a `name` exactly equal to an injected entry of
+ * `mutatingToolNames`) targets a protected path. The target is read from the call's own
+ * nested `fileChange` evidence when it carries one, and only otherwise from an `args`
+ * mention traversal. It judges only its own axis: a non-mutating tool call that merely
+ * mentions a protected path is upheld — that path belongs to the Bash meta-covenant, and
+ * run-all co-existence depends on this boundary. Tool names and paths are injected values,
+ * never source literals.
+ */
+import type { CovenantInput, CovenantVerdict } from '@polydeukes/core';
+import type { CovenantRegistration, MetaCovenantRegistration } from './dispatch.ts';
+/**
+ * `SelfModificationSpec` — the injected axes of the judge.
+ *
+ * `protectedPaths` are literal path strings; `mutatingToolNames` are the tool names that
+ * count as mutating. Empty-string entries in either list are ignored (an unguarded `''`
+ * would match every path / every tool).
+ */
+export type SelfModificationSpec = {
+    protectedPaths: string[];
+    mutatingToolNames: string[];
+};
+/**
+ * Judge a {@link CovenantInput} against the self-mod spec (pure).
+ *
+ * A call whose `name` is a non-empty `mutatingToolNames` entry is judged on its proven
+ * `fileChange` target when it carries one ({@link pathMatchesProtected} segment semantics,
+ * every kind including `delete`), and otherwise on an `args` mention traversal at any
+ * depth. Evidence, when attached, must be the call's complete mutation-target set.
+ *
+ * @param input - The call set to judge
+ * @param spec - Protected paths and mutating tool names; empty strings are ignored
+ * @returns A break naming the tool and the proven or mentioned path, or an uphold
+ */
+export declare function judgeSelfModification(input: CovenantInput, spec: SelfModificationSpec): CovenantVerdict;
+/**
+ * `SelfModRegistrationSpec` — the assembly values baked into the registration. The call
+ * set is not among them: the dispatcher supplies it to the judge at call time, so one
+ * built registration serves every payload.
+ */
+export type SelfModRegistrationSpec = {
+    protectedPaths: string[];
+    mutatingToolNames: string[];
+    witness?: CovenantRegistration['witness'];
+};
+/**
+ * Build the self-mod registration. Routing stays path mention; the judgment is the thunk.
+ *
+ * The misassembly gate lives at the thunk's entry: zero valid entries in either list would
+ * make {@link judgeSelfModification} uphold every call, so it answers the unjudgeable
+ * outcome instead, which no enforce level softens.
+ */
+export declare function selfModRegistration(spec: SelfModRegistrationSpec): MetaCovenantRegistration;

package/dist/covenant/self-mod.js

@@ -0,0 +1,84 @@
+/**
+ * `judgeSelfModification` — the self-mod meta-covenant's pure judge (zero I/O).
+ *
+ * Breaks when a *mutating* tool call (a `name` exactly equal to an injected entry of
+ * `mutatingToolNames`) targets a protected path. The target is read from the call's own
+ * nested `fileChange` evidence when it carries one, and only otherwise from an `args`
+ * mention traversal. It judges only its own axis: a non-mutating tool call that merely
+ * mentions a protected path is upheld — that path belongs to the Bash meta-covenant, and
+ * run-all co-existence depends on this boundary. Tool names and paths are injected values,
+ * never source literals.
+ */
+import { mentionsPath, pathMatchesProtected, provenChangePath } from './mention.js';
+import { outcomeFromVerdict, UNJUDGEABLE_OUTCOME } from './run-covenant.js';
+/**
+ * Judge a {@link CovenantInput} against the self-mod spec (pure).
+ *
+ * A call whose `name` is a non-empty `mutatingToolNames` entry is judged on its proven
+ * `fileChange` target when it carries one ({@link pathMatchesProtected} segment semantics,
+ * every kind including `delete`), and otherwise on an `args` mention traversal at any
+ * depth. Evidence, when attached, must be the call's complete mutation-target set.
+ *
+ * @param input - The call set to judge
+ * @param spec - Protected paths and mutating tool names; empty strings are ignored
+ * @returns A break naming the tool and the proven or mentioned path, or an uphold
+ */
+export function judgeSelfModification(input, spec) {
+    const mutatingNames = spec.mutatingToolNames.filter((name) => name !== '');
+    const protectedPaths = spec.protectedPaths.filter((path) => path !== '');
+    for (const call of input.toolCalls) {
+        if (!mutatingNames.includes(call.name)) {
+            continue;
+        }
+        const changePath = provenChangePath(call);
+        if (changePath !== null) {
+            if (protectedPaths.some((path) => pathMatchesProtected(changePath, path))) {
+                return {
+                    upheld: false,
+                    reason: `${call.name} would modify protected path ${changePath}`,
+                };
+            }
+            continue;
+        }
+        const mentioned = protectedPaths.find((path) => mentionsPath(call.args, path));
+        if (mentioned !== undefined) {
+            return {
+                upheld: false,
+                reason: `${call.name} would modify protected path ${mentioned}`,
+            };
+        }
+    }
+    return { upheld: true };
+}
+/**
+ * Build the self-mod registration. Routing stays path mention; the judgment is the thunk.
+ *
+ * The misassembly gate lives at the thunk's entry: zero valid entries in either list would
+ * make {@link judgeSelfModification} uphold every call, so it answers the unjudgeable
+ * outcome instead, which no enforce level softens.
+ */
+export function selfModRegistration(spec) {
+    const judgeSpec = {
+        protectedPaths: spec.protectedPaths,
+        mutatingToolNames: spec.mutatingToolNames,
+    };
+    return {
+        label: 'self-mod',
+        protectedPaths: spec.protectedPaths,
+        body: async (input) => {
+            if (judgeSpec.protectedPaths.filter((path) => path !== '').length === 0 ||
+                judgeSpec.mutatingToolNames.filter((name) => name !== '').length === 0) {
+                return UNJUDGEABLE_OUTCOME;
+            }
+            try {
+                return outcomeFromVerdict(judgeSelfModification(input, judgeSpec));
+            }
+            catch {
+                // Structurally unjudgeable input that passed parseInput (which validates the
+                // collection shapes, not the element ones): cannot judge means block.
+                return UNJUDGEABLE_OUTCOME;
+            }
+        },
+        ...(spec.witness !== undefined ? { witness: spec.witness } : {}),
+    };
+}

package/dist/covenant/shell-evidence.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Shell-evidence derivation — one command line in, computed writes plus a reasoned
+ * unjudgeable list out.
+ *
+ * Pure: no disk read, no spawn. `create`/`modify` discrimination and the append composition
+ * need a pre-state, which belongs to the judged body; this layer answers only what the
+ * command text itself decides.
+ *
+ * The enumerated forms below ARE the contract — a form none of them names is unjudgeable,
+ * never a confident guess. An uncomputable write whose target is known carries that path,
+ * so the compiler can route it to the discipline whose scope covers it; a write whose
+ * target is unknowable carries none. A command with no mutation signal at all leaves both
+ * lists empty: recording a line per read would drown the log it feeds.
+ */
+/** A computed write: the target, the exact bytes written, and the redirect direction. */
+export type ShellChange = {
+    path: string;
+    content: string;
+    mode: 'truncate' | 'append';
+};
+/** A detected write that cannot be computed; `path` is present only when the target is known. */
+export type ShellUnjudgeable = {
+    path?: string;
+    reason: string;
+};
+/** The derivation of one command line: computed writes and detected-but-uncomputable ones. */
+export type ShellDerivation = {
+    evidence: ShellChange[];
+    unjudgeable: ShellUnjudgeable[];
+};
+/**
+ * Derive the file changes one shell command line proves.
+ *
+ * Never throws: a span the tokenizer could not read is exactly where a quiet pass would
+ * hide, so each one answers an unjudgeable entry carrying its reason — and the commands
+ * around it still contribute their real evidence.
+ */
+export declare function deriveShellChanges(commandLine: string): ShellDerivation;

package/dist/covenant/shell-evidence.js

@@ -0,0 +1,247 @@
+/**
+ * Shell-evidence derivation — one command line in, computed writes plus a reasoned
+ * unjudgeable list out.
+ *
+ * Pure: no disk read, no spawn. `create`/`modify` discrimination and the append composition
+ * need a pre-state, which belongs to the judged body; this layer answers only what the
+ * command text itself decides.
+ *
+ * The enumerated forms below ARE the contract — a form none of them names is unjudgeable,
+ * never a confident guess. An uncomputable write whose target is known carries that path,
+ * so the compiler can route it to the discipline whose scope covers it; a write whose
+ * target is unknowable carries none. A command with no mutation signal at all leaves both
+ * lists empty: recording a line per read would drown the log it feeds.
+ */
+import { commandNameWord, isNestedShellCommand, tokenizeCommandLine, } from './bash-line.js';
+import { commandBasename, isFdReference, redirectWriteRule, sedInPlaceRule, teeRule, } from './mutation-rules.js';
+import { DEFAULT_READ_ONLY_COMMANDS } from './shell-mod.js';
+// A command that moves the working directory makes every relative target on the line
+// ambiguous — resolving it against a guessed base is exactly the approximation this layer
+// refuses to make.
+const DIRECTORY_CHANGE_COMMANDS = new Set(['cd', 'pushd', 'popd']);
+// The redirect spellings that carry stdout — the only stream whose bytes this layer can
+// compute. Every member is load-bearing: `1>` IS `>` by fd, and `>|`/`1>|` are write
+// operators the tokenizer emits and the detection rules grade by the `>` they contain.
+// Dropping any of them files a computable write as `does not carry stdout`, so the evidence
+// axis would refuse a write the judging axis already accepted.
+const STDOUT_WRITE_OPERATORS = new Set(['>', '>>', '>|', '1>', '1>>', '1>|']);
+// Rules that detect a write with no redirect. The redirect rule is consulted separately,
+// for its fd-reference boundary (`2>&1` is neither a write nor a signal).
+const DETECTION_RULES = [teeRule, sedInPlaceRule];
+/** True when the command's leading words match a read-only allowlist entry's sequence. */
+function isReadOnlyHead(command) {
+    return DEFAULT_READ_ONLY_COMMANDS.some((entry) => entry.split(' ').every((entryWord, k) => {
+        const word = command.words[k];
+        if (word === undefined || word.opaque)
+            return false;
+        // The first word is compared by basename (`/bin/cat` is still `cat`), later ones verbatim.
+        return (k === 0 ? commandBasename(word) : word.text) === entryWord;
+    }));
+}
+/**
+ * The write-direction redirects of a command. The redirect rule owns the fd-reference
+ * boundary, so its detections are the SSOT for what counts as a write; an opaque target
+ * keeps its redirect (the rule stays silent on unknowable values, but the write signal
+ * is real).
+ */
+function writeRedirects(command) {
+    const detected = new Set(redirectWriteRule.detect(command).map((target) => target.path));
+    return command.redirects.filter((redirect) => redirect.operator.includes('>') &&
+        // An fd duplication is never a write, even when its digit equals another write's
+        // filename (`> 1 2>&1`) — without this the digit re-admits it via `detected`.
+        !(redirect.operator.endsWith('>&') && isFdReference(redirect.target.text)) &&
+        (redirect.target.opaque || detected.has(redirect.target.text)));
+}
+/** The path a target text names, or the reason this layer cannot know it. */
+function resolveTarget(text, opaque, movesDirectory) {
+    if (opaque)
+        return { reason: `write target ${text} is opaque` };
+    // `~` is never expanded here — the same contract the path-notation judge keeps.
+    if (text.startsWith('~'))
+        return { reason: `write target ${text} is home-relative` };
+    if (movesDirectory && !text.startsWith('/')) {
+        return { reason: `relative write target ${text} beside a directory change` };
+    }
+    return { path: text };
+}
+/** File an unjudgeable entry for a target, carrying its path only when one is known. */
+function fileTarget(target, reason) {
+    return 'path' in target ? { path: target.path, reason } : { reason: target.reason };
+}
+/** The bytes an `echo` writes: its arguments joined, plus the newline echo appends. */
+function echoContent(command) {
+    const args = command.words.slice(1);
+    // Flag semantics (`-n`, `-e`) are not computed — the first argument decides, so a later
+    // dash-argument is ordinary content.
+    if (args[0]?.text.startsWith('-'))
+        return { reason: 'echo flag semantics are not computed' };
+    if (args.some((word) => word.opaque))
+        return { reason: 'an echo argument is opaque' };
+    return { content: `${args.map((word) => word.text).join(' ')}\n` };
+}
+/** The bytes a command copying its stdin writes (heredoc, herestring, or a file read). */
+function stdinContent(command, reads) {
+    const first = command.words[0];
+    // Only a bare `cat` copies stdin to the redirect verbatim; anything else transforms it.
+    if (first === undefined || first.opaque || command.words.length > 1) {
+        return { reason: 'stdin is transformed by the command, not copied verbatim' };
+    }
+    if (commandBasename(first) !== 'cat') {
+        return { reason: `stdin of ${first.text} is not copied verbatim` };
+    }
+    const heredocs = command.heredocs ?? [];
+    if (heredocs.length + reads.length > 1)
+        return { reason: 'more than one stdin source' };
+    const heredoc = heredocs[0];
+    if (heredoc !== undefined) {
+        // Backslash joins the escape set: in an unquoted heredoc bash processes `\` too
+        // (a trailing one is a line continuation), so captured bytes would be fiction.
+        if (!heredoc.literal && /[$`\\]/.test(heredoc.body)) {
+            return { reason: 'an unquoted heredoc body carries an expansion or escape' };
+        }
+        return { content: heredoc.body };
+    }
+    const read = reads[0];
+    if (read === undefined)
+        return { reason: 'no stdin source to read' };
+    if (read.operator !== '<<<')
+        return { reason: `stdin comes from file ${read.target.text}` };
+    if (read.target.opaque)
+        return { reason: 'the herestring is opaque' };
+    return { content: `${read.target.text}\n` };
+}
+/** The bytes one command writes to its stdout redirect. */
+function computeContent(command) {
+    // With no command word the redirection still runs and nothing writes into it.
+    if (command.words.length === 0)
+        return { content: '' };
+    const reads = command.redirects.filter((redirect) => !redirect.operator.includes('>'));
+    if (reads.length > 0 || (command.heredocs?.length ?? 0) > 0) {
+        return stdinContent(command, reads);
+    }
+    const first = command.words[0];
+    if (first === undefined || first.opaque)
+        return { reason: 'the writing command is opaque' };
+    if (commandBasename(first) !== 'echo') {
+        return { reason: `the output of ${first.text} is not computable` };
+    }
+    return echoContent(command);
+}
+/** Derive one command's write redirects into evidence or unjudgeable entries. */
+function deriveWrites(command, writes, movesDirectory, derivation) {
+    // Two writes on one command mean two results, and computing either alone is wrong.
+    if (writes.length > 1) {
+        for (const redirect of writes) {
+            const target = resolveTarget(redirect.target.text, redirect.target.opaque, movesDirectory);
+            derivation.unjudgeable.push(fileTarget(target, 'the command carries more than one write'));
+        }
+        return;
+    }
+    const redirect = writes[0];
+    if (redirect === undefined)
+        return;
+    const target = resolveTarget(redirect.target.text, redirect.target.opaque, movesDirectory);
+    if (!('path' in target)) {
+        derivation.unjudgeable.push({ reason: target.reason });
+        return;
+    }
+    // Only stdout carries the content this layer can compute; `2>`/`&>` carry streams it cannot.
+    if (!STDOUT_WRITE_OPERATORS.has(redirect.operator)) {
+        derivation.unjudgeable.push({
+            path: target.path,
+            reason: `redirect ${redirect.operator} does not carry stdout`,
+        });
+        return;
+    }
+    const content = computeContent(command);
+    if ('reason' in content) {
+        derivation.unjudgeable.push({ path: target.path, reason: content.reason });
+        return;
+    }
+    derivation.evidence.push({
+        path: target.path,
+        content: content.content,
+        mode: redirect.operator.endsWith('>>') ? 'append' : 'truncate',
+    });
+}
+/**
+ * True when a word carries subshell group syntax. `(`/`)` are ordinary word characters
+ * to this tokenizer, so the grouping — and any `cd` inside it — is structurally
+ * invisible: a reinterpretation boundary this layer refuses to parse into.
+ */
+function hasSubshellMarker(command) {
+    return command.words.some((word) => word.text.startsWith('(') || word.text.endsWith(')'));
+}
+/** Derive one simple command, top to bottom — the first matching case answers. */
+function deriveCommand(command, movesDirectory, derivation) {
+    const first = command.words[0];
+    // A nested shell re-parses its arguments: a reinterpretation boundary, never parsed into.
+    // Read past any leading assignment, or `FOO=1 bash -c …` files nothing at all.
+    const name = commandNameWord(command);
+    if (name !== undefined && isNestedShellCommand(commandBasename(name))) {
+        derivation.unjudgeable.push({ reason: `nested shell execution: ${name.text}` });
+        return;
+    }
+    if (hasSubshellMarker(command)) {
+        const grouped = writeRedirects(command);
+        if (grouped.length === 0) {
+            derivation.unjudgeable.push({ reason: 'subshell group syntax is not parsed here' });
+            return;
+        }
+        for (const redirect of grouped) {
+            const target = resolveTarget(redirect.target.text, redirect.target.opaque, movesDirectory);
+            derivation.unjudgeable.push(fileTarget(target, 'subshell group syntax is not parsed here'));
+        }
+        return;
+    }
+    // A write redirect and a rule-detected write can ride ONE command (`sed -i f > log`,
+    // `… | tee f > /dev/null`) — each files its own row; an early return on either side
+    // would swallow the other.
+    const writes = writeRedirects(command);
+    deriveWrites(command, writes, movesDirectory, derivation);
+    const detected = DETECTION_RULES.flatMap((rule) => rule.detect(command));
+    for (const mutation of detected) {
+        const target = resolveTarget(mutation.path, false, movesDirectory);
+        derivation.unjudgeable.push(fileTarget(target, `${mutation.rule} writes content this layer does not compute`));
+    }
+    if (writes.length > 0 || detected.length > 0)
+        return;
+    // Nothing detected, but an opaque token under a command that is not proven read-only
+    // could still write — the signal remains even where the rules stay silent. Without that
+    // allowlist gate every read over a glob would file a line (the volume defence).
+    if (command.words.some((word) => word.opaque) && !isReadOnlyHead(command)) {
+        derivation.unjudgeable.push({
+            reason: `opaque token under ${first?.text ?? 'a command'} that is not proven read-only`,
+        });
+    }
+}
+/**
+ * Derive the file changes one shell command line proves.
+ *
+ * Never throws: a span the tokenizer could not read is exactly where a quiet pass would
+ * hide, so each one answers an unjudgeable entry carrying its reason — and the commands
+ * around it still contribute their real evidence.
+ */
+export function deriveShellChanges(commandLine) {
+    const result = tokenizeCommandLine(commandLine);
+    // A directory change is line-scoped and order-blind: a write before it is as ambiguous
+    // as one after, since only execution decides which base each relative target resolves to.
+    const movesDirectory = result.commands.some((command) => {
+        // Read past leading assignments, like `deriveCommand` — `FOO=1 cd sub` moves the directory
+        // exactly as `cd sub` does. Missing it is not a silent skip: every relative target on
+        // the line would then be resolved against the repo root and filed as CONFIDENT evidence
+        // for a path the command never touched.
+        const name = commandNameWord(command);
+        return (name !== undefined && !name.opaque && DIRECTORY_CHANGE_COMMANDS.has(commandBasename(name)));
+    });
+    // A line with any unread span files at least one entry, whatever the commands around it
+    // derive: that row is the telemetry the shell axis contracts for, and a partial success
+    // that swallowed it would be a call passing unrecorded.
+    const derivation = {
+        evidence: [],
+        unjudgeable: result.unread.map((span) => ({ reason: span.reason })),
+    };
+    for (const command of result.commands)
+        deriveCommand(command, movesDirectory, derivation);
+    return derivation;
+}

package/dist/covenant/shell-mod.d.ts

@@ -0,0 +1,84 @@
+/**
+ * `judgeShellModification` — the shell-mod meta-covenant's pure judge (zero I/O).
+ *
+ * Analyzes the command-line strings of *shell* tool calls (names and arg keys are injected
+ * values, never source literals) per simple command: the fixed detection rules catch writes
+ * to a protected path, undecidable structures (opaque mentions, opaque write targets) fail
+ * closed, the read-only allowlist absolves proven reads, and every other protected-path
+ * mention breaks — "mention + unproven = block". It judges only its own axis: a non-shell
+ * tool call is upheld, since the tool axis belongs to the self-mod meta-covenant and
+ * run-all co-existence depends on that boundary.
+ */
+import type { CovenantInput, CovenantVerdict } from '@polydeukes/core';
+import { type SimpleCommand } from './bash-line.ts';
+import type { CovenantRegistration, MetaCovenantRegistration } from './dispatch.ts';
+/**
+ * `ShellModificationSpec` — the injected axes of the judge.
+ *
+ * `protectedPaths` are literal path strings; `shellToolNames` are the tool names whose
+ * calls carry shell lines; `commandArgNames` are the `args` keys those lines live under;
+ * `readOnlyCommands` are allowlist entries — space-separated word sequences (`'cat'`,
+ * `'git diff'`). Empty-string entries in every list are ignored (an unguarded `''` would
+ * match every path / tool / arg / command).
+ */
+export type ShellModificationSpec = {
+    protectedPaths: string[];
+    shellToolNames: string[];
+    commandArgNames: string[];
+    readOnlyCommands: string[];
+};
+/**
+ * Commands proven read-only by shell semantics — the default allowlist. An entry is a
+ * leading word sequence; multi-word entries exist because a bare command name (`git`) can
+ * front mutating subcommands. Omission errs toward friction, never a hole.
+ *
+ * An entry must have no way to write a file through its own arguments, since the allowlist
+ * vouches for the command head while `matchesReadOnlyEntry` never inspects trailing argv.
+ * That is why `git diff`/`git log`/`git show` are absent: all accept `--output=<file>`, a
+ * redirect-free truncating write. `git status`/`git grep` reject `--output`, so they stay.
+ */
+export declare const DEFAULT_READ_ONLY_COMMANDS: string[];
+/**
+ * True when the command's leading words match the allowlist entry's word sequence. Exported
+ * so the transcript judge's allowlist clause absolves reads by this exact comparison instead
+ * of a fork that could drift from it.
+ */
+export declare function matchesReadOnlyEntry(command: SimpleCommand, entry: string[]): boolean;
+/**
+ * Judge a {@link CovenantInput} against the shell-mod spec (pure).
+ *
+ * For each `toolCalls[i]` whose `name` exactly equals a non-empty `shellToolNames` entry,
+ * every string value under a non-empty `commandArgNames` key is analyzed as a shell line;
+ * a shell call with zero such strings breaks (a misassembled arg name must not degrade
+ * into universal uphold). A span the tokenizer could not read breaks iff the dequoted span —
+ * or one of its shell-metacharacter fragments — mentions a protected path, and is answered
+ * before the commands so that a mention only the span can see is named as one. Non-shell
+ * calls, `subagentSpawns`, and `userMessages` are never judged.
+ */
+export declare function judgeShellModification(input: CovenantInput, spec: ShellModificationSpec): CovenantVerdict;
+/**
+ * `ShellModRegistrationSpec` — the assembly values baked into the registration. The call
+ * set is not among them: the dispatcher supplies it to the judge at call time.
+ * `readOnlyCommands` REPLACES {@link DEFAULT_READ_ONLY_COMMANDS} when given — no merge,
+ * since an assembly wanting to extend the default spreads the constant.
+ */
+export type ShellModRegistrationSpec = {
+    protectedPaths: string[];
+    shellTools: string[];
+    /**
+     * The `args` keys shell lines live under. ABSENT is the empty surface, which the thunk's
+     * entry gate refuses — naming no command arg would otherwise uphold every call.
+     */
+    commandArgs?: string[];
+    readOnlyCommands?: string[];
+    witness?: CovenantRegistration['witness'];
+};
+/**
+ * Build the shell-mod registration. Routing stays path mention; the judgment is the thunk.
+ *
+ * The misassembly gate lives at the thunk's entry: zero valid entries in any of the three
+ * required lists would make {@link judgeShellModification} uphold every call, so it answers
+ * the unjudgeable outcome instead, which no enforce level softens. The allowlist is exempt
+ * — empty just means stricter.
+ */
+export declare function shellModRegistration(spec: ShellModRegistrationSpec): MetaCovenantRegistration;