vigiles 5.2.0 → 7.0.0

package/dist/core/bash-effects.d.ts

@@ -38,4 +38,16 @@ export declare function classifyBashCommand(command: string): BashEffect;
  * caller uses to decide "this Bash is provably an observation."
  */
 export declare function isReadOnlyBash(command: string): boolean;
+/**
+ * Extract the static argv of every simple command (CallExpr) in `command`, each
+ * as an array of literal words (dynamic / quoted-interpolated words are dropped).
+ * AST-backed, so a leaf nested in a pipeline, `&&`/`;`/`|`, a subshell, or a
+ * compound command is still found — the structural query a robust matcher needs
+ * (a regex over the raw string misses `cd x && git push`). Parse failure → [].
+ *
+ * This is the matching primitive a typed hook's `command.runs("git push")` is
+ * built on: it sees the real `git push` leaf however it's wrapped, which the
+ * native `Bash(git:*)` glob (issue #30519) and a hand-written `grep` both miss.
+ */
+export declare function leafCommands(command: string): string[][];
 //# sourceMappingURL=bash-effects.d.ts.map

package/dist/core/bash-effects.js

@@ -26,6 +26,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.classifyBashCommand = classifyBashCommand;
 exports.isReadOnlyBash = isReadOnlyBash;
+exports.leafCommands = leafCommands;
 // mvdan-sh is a CJS package (GopherJS build) with no bundled TypeScript types.
 // The project compiles to CommonJS (Node16, no "type":"module"), so plain
 // require() works and is the idiomatic pattern here (see linters.ts).
@@ -402,4 +403,34 @@ function classifyBashCommand(command) {
 function isReadOnlyBash(command) {
     return classifyBashCommand(command) === "read-only";
 }
+/**
+ * Extract the static argv of every simple command (CallExpr) in `command`, each
+ * as an array of literal words (dynamic / quoted-interpolated words are dropped).
+ * AST-backed, so a leaf nested in a pipeline, `&&`/`;`/`|`, a subshell, or a
+ * compound command is still found — the structural query a robust matcher needs
+ * (a regex over the raw string misses `cd x && git push`). Parse failure → [].
+ *
+ * This is the matching primitive a typed hook's `command.runs("git push")` is
+ * built on: it sees the real `git push` leaf however it's wrapped, which the
+ * native `Bash(git:*)` glob (issue #30519) and a hand-written `grep` both miss.
+ */
+function leafCommands(command) {
+    let file;
+    try {
+        file = sh.syntax.NewParser().Parse(command, "cmd.sh");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    sh.syntax.Walk(file, (node) => {
+        if (sh.syntax.NodeType(node) === "CallExpr" && node.Args) {
+            const argv = node.Args.map((w) => getLiteral(w)).filter((s) => s !== null);
+            if (argv.length > 0)
+                out.push(argv);
+        }
+        return true;
+    });
+    return out;
+}
 //# sourceMappingURL=bash-effects.js.map

package/dist/core/capability-diff.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Capability-diff — "did this change widen the agent's blast radius?" (moat #2).
+ *
+ * The whole-harness capability lattice ({@link HarnessCapabilities}, computed by
+ * `computeHarnessCapabilities`) is the set of effects an agent/harness can reach:
+ * read-only tools, side-effecting tools, unknown/MCP tools, and the loosest purity.
+ * Diffing two lattices (a PR's base vs head) yields a deterministic, model-free
+ * verdict: a change WIDENED the blast radius iff it adds a side-effecting or
+ * unknown/MCP tool, or loosens the purity floor. New read-only tools and removals
+ * are reported but are NOT a widening.
+ *
+ * Honesty / don't-cry-wolf: a widening is INFORMATIONAL by default (a PR comment),
+ * not an automatic failure — widening the surface is often intended. The CLI gates
+ * a non-zero exit behind an explicit `--fail-on-widen`. Pure + harness-agnostic
+ * (operates on the lattice, no dialect needed). See research/typed-spec-moat.md (#2).
+ */
+import type { HarnessCapabilities } from "./generate-harness.js";
+import type { PurityLevel } from "./effects.js";
+/** A purity move between two lattices (omitted when unchanged). */
+export interface PurityChange {
+    readonly from: PurityLevel;
+    readonly to: PurityLevel;
+    /** `widened` = loosened (pure→bounded→unrestricted); `narrowed` = tightened. */
+    readonly direction: "widened" | "narrowed";
+}
+export interface CapabilityDiff {
+    /** Side-effecting tools reachable AFTER but not before — the core blast-radius growth. */
+    readonly addedSideEffecting: readonly string[];
+    /** Unknown-effect (MCP / unrecognized) tools newly reachable — also widened reach. */
+    readonly addedUnknown: readonly string[];
+    /** Read-only tools newly reachable — benign (reported, NOT a widening). */
+    readonly addedReadOnly: readonly string[];
+    /** Tools reachable before but not after — a NARROWING (good; informational). */
+    readonly removed: readonly string[];
+    /** The purity move, or null when unchanged. */
+    readonly purity: PurityChange | null;
+    /** The verdict: did the blast radius GROW (new side-effecting/unknown, or purity loosened)? */
+    readonly widened: boolean;
+}
+/** Diff two capability lattices → what changed + the widened verdict. Pure. */
+export declare function diffCapabilities(before: HarnessCapabilities, after: HarnessCapabilities): CapabilityDiff;
+/** True when the diff carries no change at all (the common, quiet case). */
+export declare function isNoOpDiff(d: CapabilityDiff): boolean;
+/** Render a capability-diff as a PR-comment-style report (Markdown-friendly). */
+export declare function formatCapabilityDiff(d: CapabilityDiff): string;
+//# sourceMappingURL=capability-diff.d.ts.map

package/dist/core/capability-diff.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Capability-diff — "did this change widen the agent's blast radius?" (moat #2).
+ *
+ * The whole-harness capability lattice ({@link HarnessCapabilities}, computed by
+ * `computeHarnessCapabilities`) is the set of effects an agent/harness can reach:
+ * read-only tools, side-effecting tools, unknown/MCP tools, and the loosest purity.
+ * Diffing two lattices (a PR's base vs head) yields a deterministic, model-free
+ * verdict: a change WIDENED the blast radius iff it adds a side-effecting or
+ * unknown/MCP tool, or loosens the purity floor. New read-only tools and removals
+ * are reported but are NOT a widening.
+ *
+ * Honesty / don't-cry-wolf: a widening is INFORMATIONAL by default (a PR comment),
+ * not an automatic failure — widening the surface is often intended. The CLI gates
+ * a non-zero exit behind an explicit `--fail-on-widen`. Pure + harness-agnostic
+ * (operates on the lattice, no dialect needed). See research/typed-spec-moat.md (#2).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffCapabilities = diffCapabilities;
+exports.isNoOpDiff = isNoOpDiff;
+exports.formatCapabilityDiff = formatCapabilityDiff;
+const PURITY_RANK = {
+    pure: 0,
+    bounded: 1,
+    unrestricted: 2,
+};
+const addedIn = (before, after) => after.filter((x) => !before.includes(x));
+/** Diff two capability lattices → what changed + the widened verdict. Pure. */
+function diffCapabilities(before, after) {
+    const addedSideEffecting = addedIn(before.sideEffecting, after.sideEffecting);
+    const addedUnknown = addedIn(before.unknown, after.unknown);
+    const addedReadOnly = addedIn(before.readOnly, after.readOnly);
+    // A tool is "removed" if it was reachable in ANY bucket before and in NONE after.
+    const afterAll = new Set([
+        ...after.readOnly,
+        ...after.sideEffecting,
+        ...after.unknown,
+    ]);
+    const removed = [
+        ...before.readOnly,
+        ...before.sideEffecting,
+        ...before.unknown,
+    ].filter((x) => !afterAll.has(x));
+    const fromRank = PURITY_RANK[before.purity];
+    const toRank = PURITY_RANK[after.purity];
+    const purity = fromRank === toRank
+        ? null
+        : {
+            from: before.purity,
+            to: after.purity,
+            direction: toRank > fromRank ? "widened" : "narrowed",
+        };
+    const widened = addedSideEffecting.length > 0 ||
+        addedUnknown.length > 0 ||
+        purity?.direction === "widened";
+    return {
+        addedSideEffecting,
+        addedUnknown,
+        addedReadOnly,
+        removed,
+        purity,
+        widened,
+    };
+}
+/** True when the diff carries no change at all (the common, quiet case). */
+function isNoOpDiff(d) {
+    return (d.addedSideEffecting.length === 0 &&
+        d.addedUnknown.length === 0 &&
+        d.addedReadOnly.length === 0 &&
+        d.removed.length === 0 &&
+        d.purity === null);
+}
+/** Render a capability-diff as a PR-comment-style report (Markdown-friendly). */
+function formatCapabilityDiff(d) {
+    if (isNoOpDiff(d)) {
+        return "Capability surface unchanged — no blast-radius change.";
+    }
+    const lines = [
+        d.widened
+            ? "⚠️ Capability surface **WIDENED** — this change grows the agent's blast radius:"
+            : "Capability surface changed (no widening — narrowing / read-only only):",
+    ];
+    if (d.addedSideEffecting.length > 0)
+        lines.push(`  + side-effecting: ${d.addedSideEffecting.join(", ")}`);
+    if (d.addedUnknown.length > 0)
+        lines.push(`  + unknown/MCP: ${d.addedUnknown.join(", ")}`);
+    if (d.purity?.direction === "widened")
+        lines.push(`  + purity loosened: ${d.purity.from} → ${d.purity.to}`);
+    if (d.addedReadOnly.length > 0)
+        lines.push(`  · read-only added (benign): ${d.addedReadOnly.join(", ")}`);
+    if (d.removed.length > 0)
+        lines.push(`  − narrowed (removed): ${d.removed.join(", ")}`);
+    if (d.purity?.direction === "narrowed")
+        lines.push(`  − purity tightened: ${d.purity.from} → ${d.purity.to}`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=capability-diff.js.map

package/dist/core/compile.d.ts

@@ -25,7 +25,7 @@ export declare function verifyHash(content: string): {
  */
 /** @internal */ export declare function estimateTokens(text: string): number;
 export interface CompileError {
-    type: "stale-file" | "stale-command" | "stale-ref" | "invalid-rule" | "budget-exceeded" | "section-too-long" | "section-has-header" | "reserved-section-key" | "spec-name-mismatch" | "unknown-tool" | "invalid-railway" | "purity-violation" | "output-without-fork";
+    type: "stale-file" | "stale-command" | "stale-ref" | "invalid-rule" | "budget-exceeded" | "section-too-long" | "section-has-header" | "reserved-section-key" | "spec-name-mismatch" | "unknown-tool" | "invalid-railway" | "purity-violation" | "output-without-fork" | "effect-in-skill";
     message: string;
     path?: string;
 }

package/dist/core/compile.js

@@ -730,6 +730,20 @@ function compileSkill(spec, options = {}) {
                 "as a subagent, or drop `output`.",
         });
     }
+    // effect() is a SUBAGENT primitive. A deterministic effect REGION needs a
+    // structural call→return bracket to scope it; a default skill is spliced into
+    // the main conversation and has none (the dogfood that proved the model-emitted
+    // boundary is fragile — research/effect-boundary-design.md). A skill bounds its
+    // effects with a `purity` floor and promotes to `context:'fork'` (a subagent)
+    // when it must mutate.
+    if (collectSkillRefs(spec).some((f) => typeof f !== "string" && f._ref === "effect")) {
+        errors.push({
+            type: "effect-in-skill",
+            message: "effect() is a subagent primitive — a skill has no call→return boundary to " +
+                "scope an effect region. Declare a `purity` floor on the skill and use " +
+                "context:'fork' to run it as a subagent when it must mutate.",
+        });
+    }
     // purity floor check — the dialect is optional (callers that don't pass one
     // skip the check rather than crash; the CLI always passes it). An absent
     // tools list inherits ALL tools, so it's checked as the "*" wildcard (a

package/dist/core/generate-harness.d.ts

@@ -0,0 +1,187 @@
+/**
+ * vigiles generate-harness — emit ONE typed registry over the whole harness.
+ *
+ * The third generated artifact beside `generate-types` (`.d.ts`) and
+ * `generate-schema` (JSON Schema): a `harness.gen.ts` that imports every
+ * `*.spec.ts` in a directory, folds the agents into a `registry`, and asserts
+ * the cross-spec invariants at the TYPE level — so a single `tsc --noEmit`
+ * checks the WHOLE harness as one program (think TanStack's `routeTree.gen.ts`).
+ * See research/whole-harness-codegen.md for the design + the measured perf.
+ *
+ * The shipped scope (the first increment):
+ *  1. DANGLING `delegate` → a `tsc` error. Each `railway()` delegate target is a
+ *     name the generator reads at codegen time; the gen file emits one shallow
+ *     per-edge assertion (`KnownAgentName<"target", AgentName>` — O(N), no
+ *     recursion) that the target resolves to a real agent, else a `tsc` error
+ *     naming the dangling target + its railway.
+ *  2. DUPLICATE agent/skill NAMES → a generator error (this module returns a
+ *     `duplicate` diagnostic; the CLI exits non-zero). This is the O(N) JS check
+ *     the encoding rule mandates — a set-uniqueness MAPPED TYPE is the TS2589
+ *     wall (measured ≈ N=1000), so duplicates are NEVER a type.
+ *  3. The whole-harness CAPABILITY LATTICE: the UNION of every agent's
+ *     `effectSurface(tools, dialect)` — a generator-computed value + type, the
+ *     substrate the future repo-scale capability-diff reads.
+ *  4. CROSS-FILE TYPED COMPOSITION: when a `railway()` success-track step declares
+ *     what it `needs()`, the gen file emits one shallow per-pair assertion
+ *     (`Handoff<OkOf<typeof registry[producer]>, needs>` — O(N), no recursion)
+ *     that the PRIOR step's `result().ok` SUPPLIES it, so a cross-file handoff
+ *     mismatch (a missing field / wrong type) is a `tsc` error naming the field.
+ *     The repo-scale generalization of the per-file `pipe`/`Supplies` composition.
+ *     Scoped to the linear success track; recover/onError (which consume an `err`,
+ *     not the prior `ok`) are a noted follow-up.
+ *
+ * Harness-agnostic: the `dialect` (for the capability lattice) is INJECTED by
+ * the composition root (the CLI), never hard-coded — mirroring `compileAgent` /
+ * `scanPlugin`. The core stays free of any Claude-Code literal.
+ */
+import type { HarnessDialect } from "./dialect.js";
+import { type PurityLevel } from "./effects.js";
+/** One agent the harness defines (its registry-relevant facts). */
+export interface HarnessAgentEntry {
+    /** The agent's dispatch name — also a registry key + the dangling-check union. */
+    readonly name: string;
+    /** The agent's declared tool contract (used to compute its effect surface). */
+    readonly tools?: readonly string[];
+    /** The spec file this agent came from (for import + duplicate diagnostics). */
+    readonly file: string;
+}
+/** One delegate edge: a railway dispatches `target` (resolved against agents). */
+export interface HarnessDelegateEdge {
+    /** The railway / orchestrator the edge originates from (for the diagnostic). */
+    readonly from: string;
+    /** The delegate target name — must resolve to a known agent, else dangling. */
+    readonly target: string;
+}
+/**
+ * One CROSS-FILE handoff edge: a consecutive success-track pair where the
+ * CONSUMER (`to`) declares the input it `needs`, asserted against the PRODUCER
+ * (`from`, the prior step's agent) `result().ok` at the type level. The
+ * registry already imports each agent's `TypedAgentSpec`, so the generator reads
+ * the producer's `ok` shape off the registry (`OkOf<typeof registry[from]>`) and
+ * emits one shallow `Handoff<>` assertion per such pair (O(N), no recursion).
+ */
+export interface HarnessHandoffEdge {
+    /** The railway the edge originates from (for the diagnostic). */
+    readonly railway: string;
+    /** The PRODUCER agent name (the prior success-track step) — registry key. */
+    readonly from: string;
+    /** The CONSUMER agent name (this step) — names the failing edge. */
+    readonly to: string;
+    /** The consumer's declared input shape (`needs(...)`) — the literal emitted. */
+    readonly needs: Readonly<Record<string, string>>;
+}
+/** Everything the generator needs, already loaded (the pure-core input). */
+export interface HarnessModel {
+    readonly agents: readonly HarnessAgentEntry[];
+    readonly edges: readonly HarnessDelegateEdge[];
+    /**
+     * Cross-file handoff edges (consecutive success-track step pairs whose
+     * consumer declares `needs`). Optional + defaults to none, so an existing
+     * model with no handoffs generates exactly as before — backwards-compatible.
+     */
+    readonly handoffs?: readonly HarnessHandoffEdge[];
+}
+export interface GenerateHarnessOptions {
+    /** The dialect the capability lattice is computed against (injected). */
+    readonly dialect: HarnessDialect;
+    /**
+     * The module specifier the generated file imports `KnownAgentName` from.
+     * Defaults to the public package (`"vigiles/spec"`); the in-repo dogfood
+     * passes a relative path so the generated file resolves without the package.
+     */
+    readonly specImport?: string;
+    /** The directory the gen file will be written to (to relativize spec imports). */
+    readonly outDir: string;
+}
+/** A duplicate-name collision found at codegen time (the O(N) JS check). */
+export interface DuplicateNameDiagnostic {
+    readonly name: string;
+    readonly first: string;
+    readonly second: string;
+    /** A ready-to-print message. */
+    readonly message: string;
+}
+/** The whole-harness capability lattice — the union of every agent's surface. */
+export interface HarnessCapabilities {
+    /** Every read-only tool reachable anywhere in the harness (de-duped, sorted). */
+    readonly readOnly: readonly string[];
+    /** Every side-effecting tool reachable anywhere (de-duped, sorted). */
+    readonly sideEffecting: readonly string[];
+    /** Every unknown-effect tool (MCP / unrecognized) reachable anywhere. */
+    readonly unknown: readonly string[];
+    /** The harness-wide purity: the LOOSEST purity of any single agent. */
+    readonly purity: PurityLevel;
+}
+export interface GenerateHarnessResult {
+    /** The generated `harness.gen.ts` source (always produced — even on a dup, so
+     *  the caller can decide; the CLI gates the WRITE on `duplicate` being absent). */
+    readonly gen: string;
+    /** The computed capability lattice (also embedded in `gen`). */
+    readonly capabilities: HarnessCapabilities;
+    /** Set iff two agents declare the same name — the caller exits non-zero. */
+    readonly duplicate?: DuplicateNameDiagnostic;
+    /** The number of agents + edges folded in (for the CLI summary). */
+    readonly agentCount: number;
+    readonly edgeCount: number;
+    /** The number of cross-file handoff assertions emitted (for the CLI summary). */
+    readonly handoffCount: number;
+}
+/**
+ * Fold every agent's `effectSurface` into one harness-wide lattice: the union of
+ * each bucket and the loosest purity. An agent with no `tools` inherits all (a
+ * wildcard), so its surface is `unrestricted` — handled by `effectSurface` when
+ * we pass `["*"]`. O(N) over the agents; the per-agent legs are fixed-arity.
+ */
+export declare function computeHarnessCapabilities(agents: readonly HarnessAgentEntry[], dialect: HarnessDialect): HarnessCapabilities;
+/**
+ * Find the FIRST pair of agents that declare the same `name`. O(N) over the
+ * agents — the set-cardinality check the encoding rule says must live in the JS
+ * generator, never as an N×N mapped type (the measured TS2589 wall). Returns
+ * `undefined` when names are unique.
+ */
+export declare function findDuplicateName(agents: readonly HarnessAgentEntry[]): DuplicateNameDiagnostic | undefined;
+/**
+ * Generate the `harness.gen.ts` source over an already-loaded `HarnessModel`.
+ *
+ * Pure: no filesystem read, no spec loading — just string emission + the two
+ * O(N) computations (capability lattice + duplicate check). The fs/scan wrapper
+ * (`loadHarnessModel`) feeds this.
+ */
+export declare function generateHarness(model: HarnessModel, options: GenerateHarnessOptions): GenerateHarnessResult;
+/** A minimal shape of a loaded spec value (the fields the model reads). */
+interface LoadedSpecLike {
+    readonly _specType?: string;
+    readonly name?: string;
+    readonly tools?: readonly string[];
+    readonly steps?: readonly {
+        readonly agent?: string;
+        readonly needs?: Readonly<Record<string, string>>;
+    }[];
+    readonly onError?: {
+        readonly agent?: string;
+    };
+    readonly recover?: {
+        readonly step?: {
+            readonly agent?: string;
+        };
+    };
+}
+/** Discover every `*.spec.ts` directly under `dir` (non-recursive, sorted). */
+export declare function findHarnessSpecFiles(dir: string): string[];
+/**
+ * Build a `HarnessModel` from `dir`'s spec files using a caller-supplied
+ * `load(file) → value` (the CLI injects its `loadSpec`, so this stays
+ * fs/runtime-agnostic and unit-testable with fakes). Agents become registry
+ * entries; railways contribute delegate edges (steps + recover + onError).
+ */
+export declare function loadHarnessModel(dir: string, load: (absFile: string) => Promise<LoadedSpecLike | null>): Promise<HarnessModel>;
+/** Convenience: the gen file's basename, used by the CLI default out path. */
+export declare const HARNESS_GEN_FILENAME = "harness.gen.ts";
+/** Relative label for a path under cwd (CLI-only nicety; pure). */
+export declare function labelFor(cwd: string, abs: string): string;
+/** Read a spec file's raw text (helper exposed for callers that need the source). */
+export declare function readSpecSource(absFile: string): string;
+/** The directory a gen file at `outFile` lives in (helper for the CLI). */
+export declare function genOutDir(outFile: string): string;
+export {};
+//# sourceMappingURL=generate-harness.d.ts.map