@cad0p/pi-steering 0.1.0

package/dist/internal/ref-text.js

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+/**
+ * Canonical stringification of a bash {@link CommandRef} for observer
+ * watch matching. Every call site must use this one implementation to
+ * avoid drift across observer-dispatch + speculative-entry synthesis.
+ *
+ * @internal — not part of the public pi-steering surface.
+ */
+import { getBasename, getCommandArgs } from "@cad0p/unbash-walker";
+/** Render a ref as `"{basename} {args joined by space}"`, trimmed. */
+export function refToText(ref) {
+    return `${getBasename(ref)} ${getCommandArgs(ref).join(" ")}`.trim();
+}
+//# sourceMappingURL=ref-text.js.map

package/dist/internal/ref-text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref-text.js","sourceRoot":"","sources":["../../src/internal/ref-text.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,uBAAuB;AAEvB;;;;;;GAMG;AAEH,OAAO,EAAmB,WAAW,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEpF,sEAAsE;AACtE,MAAM,UAAU,SAAS,CAAC,GAAe;IACvC,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,IAAI,cAAc,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;AACvE,CAAC"}

package/dist/internal/session-runtime.d.ts

@@ -0,0 +1,44 @@
+import { type EvaluatorHost, type EvaluatorRuntime } from "../evaluator.ts";
+import { type ObserverDispatcher } from "../observer-dispatcher.ts";
+import { type ResolvedPluginState } from "../plugin-merger.ts";
+import type { SteeringConfig, SteeringDiagnostic } from "../schema.ts";
+/**
+ * Run `buildConfig` then `resolvePlugins` over the raw layer list,
+ * short-circuiting before `resolvePlugins` if any merge-side
+ * diagnostic is error-class. Avoids double-emitting
+ * `tracker-name-collision` (O2 in INVARIANTS.md).
+ * `validateUserConfigNames` runs unconditionally so user-config name
+ * issues surface alongside merge errors.
+ */
+export declare function runMergerPipeline(layers: readonly SteeringConfig[], defaults: SteeringConfig | undefined, builtinTrackers: readonly string[]): {
+    merged: SteeringConfig;
+    resolved: ResolvedPluginState | null;
+    diagnostics: SteeringDiagnostic[];
+};
+/**
+ * Render a diagnostics array into a single multi-line message
+ * suitable for use as a thrown Error's `message`. See {@link
+ * SteeringDiagnostic} render-format matrix for the canonical shape;
+ * the `formatAggregatedDiagnostics: rule-based spec` describe block in
+ * `internal/session-runtime.test.ts` pins the rules.
+ */
+export declare function formatAggregatedDiagnostics(diagnostics: readonly SteeringDiagnostic[]): string;
+/**
+ * Single-line render of one diagnostic; see {@link SteeringDiagnostic}
+ * render-format matrix for the canonical contract.
+ */
+export declare function formatSingleLineDiagnostic(d: SteeringDiagnostic): string;
+/**
+ * Build the per-session evaluator + observer dispatcher from the walk-
+ * up config rooted at `cwd`. Honors `disableDefaults` via inner-wins
+ * peek before injecting `DEFAULT_*`. Throws on any error-class
+ * diagnostic and on warning-class diagnostics when
+ * `failOnWarnings !== false`; otherwise emits surviving warnings via
+ * `console.warn`. See {@link runMergerPipeline} for the merge contract
+ * and `finalizePluginState` for observer-drop.
+ */
+export declare function buildSessionRuntime(cwd: string, host: EvaluatorHost): Promise<{
+    evaluator: EvaluatorRuntime;
+    dispatcher: ObserverDispatcher;
+}>;
+//# sourceMappingURL=session-runtime.d.ts.map

package/dist/internal/session-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-runtime.d.ts","sourceRoot":"","sources":["../../src/internal/session-runtime.ts"],"names":[],"mappings":"AA+BA,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACtB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,KAAK,mBAAmB,EAGzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGvE;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,cAAc,EAAE,EACjC,QAAQ,EAAE,cAAc,GAAG,SAAS,EACpC,eAAe,EAAE,SAAS,MAAM,EAAE,GACjC;IACD,MAAM,EAAE,cAAc,CAAC;IACvB,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACrC,WAAW,EAAE,kBAAkB,EAAE,CAAC;CACnC,CA2BA;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,SAAS,kBAAkB,EAAE,GACzC,MAAM,CAWR;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAGxE;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC;IACT,SAAS,EAAE,gBAAgB,CAAC;IAC5B,UAAU,EAAE,kBAAkB,CAAC;CAChC,CAAC,CA2DD"}

package/dist/internal/session-runtime.js

@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+/**
+ * Internal module — not part of the package's public API.
+ *
+ * This module holds the wiring that the bridge factory in `index.ts`
+ * uses to spin up an evaluator + observer dispatcher from a walk-up
+ * steering config. It is intentionally NOT re-exported from
+ * `index.ts` or any other public entry point; consumers building
+ * their own extensions should go through `loadHarness` (subpath
+ * `@cad0p/pi-steering/testing`) or call `buildEvaluator` /
+ * `buildObserverDispatcher` directly.
+ *
+ * The runtime owns the strict-mode contract: diagnostics produced
+ * by the loader (per-layer import failures, dual-form coexistence,
+ * stray files, cross-layer + within-layer collisions) and by the
+ * plugin merger (predicate / observer / rule / extension-orphan /
+ * reserved-name / invalid-name diagnostics) are aggregated here.
+ * Any error-class diagnostic always escalates to a thrown error;
+ * warning-class diagnostics escalate when `failOnWarnings !== false`
+ * on the merged config (default: true). Otherwise warnings are
+ * emitted to `console.warn` for legacy fail-soft semantics.
+ *
+ * The bridge calls `buildSessionRuntime` once at extension factory
+ * time. A thrown factory propagates through pi's extension loader
+ * into pi's `[Extension issues]` diagnostic block (which survives
+ * `/reload`); the bridge does not catch.
+ */
+import { DEFAULT_PLUGINS, DEFAULT_RULES } from "../defaults.js";
+import { buildEvaluator, EVALUATOR_BUILTIN_TRACKERS, } from "../evaluator.js";
+import { buildConfig, loadConfigs, mergeBool } from "../loader.js";
+import { buildObserverDispatcher, } from "../observer-dispatcher.js";
+import { resolvePlugins, validateUserConfigNames, } from "../plugin-merger.js";
+import { finalizePluginState } from "./finalize-plugin-state.js";
+/**
+ * Run `buildConfig` then `resolvePlugins` over the raw layer list,
+ * short-circuiting before `resolvePlugins` if any merge-side
+ * diagnostic is error-class. Avoids double-emitting
+ * `tracker-name-collision` (O2 in INVARIANTS.md).
+ * `validateUserConfigNames` runs unconditionally so user-config name
+ * issues surface alongside merge errors.
+ */
+export function runMergerPipeline(layers, defaults, builtinTrackers) {
+    const { config: merged, diagnostics: mergeDiagnostics } = buildConfig(layers, defaults);
+    const userConfigNameDiagnostics = validateUserConfigNames(layers);
+    if (mergeDiagnostics.some((d) => d.type === "error")) {
+        return {
+            merged,
+            resolved: null,
+            diagnostics: [...mergeDiagnostics, ...userConfigNameDiagnostics],
+        };
+    }
+    const resolved = resolvePlugins(merged.plugins ?? [], merged, builtinTrackers);
+    return {
+        merged,
+        resolved,
+        diagnostics: [
+            ...mergeDiagnostics,
+            ...userConfigNameDiagnostics,
+            ...resolved.diagnostics,
+        ],
+    };
+}
+/**
+ * Render a diagnostics array into a single multi-line message
+ * suitable for use as a thrown Error's `message`. See {@link
+ * SteeringDiagnostic} render-format matrix for the canonical shape;
+ * the `formatAggregatedDiagnostics: rule-based spec` describe block in
+ * `internal/session-runtime.test.ts` pins the rules.
+ */
+export function formatAggregatedDiagnostics(diagnostics) {
+    const errors = diagnostics.filter((d) => d.type === "error");
+    const warnings = diagnostics.filter((d) => d.type === "warning");
+    const ordered = [...errors, ...warnings];
+    const count = ordered.length;
+    const noun = count === 1 ? "issue" : "issues";
+    const lines = ordered.map((d) => {
+        const pathPrefix = d.path !== undefined ? `${d.path}: ` : "";
+        return `  - [${d.type}] ${pathPrefix}${d.message}`;
+    });
+    return `${count} config ${noun}:\n${lines.join("\n")}`;
+}
+/**
+ * Single-line render of one diagnostic; see {@link SteeringDiagnostic}
+ * render-format matrix for the canonical contract.
+ */
+export function formatSingleLineDiagnostic(d) {
+    const pathPrefix = d.path !== undefined ? `${d.path}: ` : "";
+    return `[pi-steering] [${d.type}] ${pathPrefix}${d.message}`;
+}
+/**
+ * Build the per-session evaluator + observer dispatcher from the walk-
+ * up config rooted at `cwd`. Honors `disableDefaults` via inner-wins
+ * peek before injecting `DEFAULT_*`. Throws on any error-class
+ * diagnostic and on warning-class diagnostics when
+ * `failOnWarnings !== false`; otherwise emits surviving warnings via
+ * `console.warn`. See {@link runMergerPipeline} for the merge contract
+ * and `finalizePluginState` for observer-drop.
+ */
+export async function buildSessionRuntime(cwd, host) {
+    const aggregated = [];
+    const { layers: rawLayers, diagnostics: loaderDiagnostics } = await loadConfigs(cwd);
+    aggregated.push(...loaderDiagnostics);
+    const disableDefaults = mergeBool(rawLayers, "disableDefaults") === true;
+    const defaults = disableDefaults
+        ? undefined
+        : { rules: DEFAULT_RULES, plugins: DEFAULT_PLUGINS };
+    const { merged, resolved, diagnostics: mergeAndResolveDiagnostics, } = runMergerPipeline(rawLayers, defaults, EVALUATOR_BUILTIN_TRACKERS);
+    aggregated.push(...mergeAndResolveDiagnostics);
+    const failOnWarnings = merged.failOnWarnings;
+    const treatWarningsAsErrors = failOnWarnings !== false;
+    const hasError = aggregated.some((d) => d.type === "error");
+    const hasWarning = aggregated.some((d) => d.type === "warning");
+    if (hasError || (treatWarningsAsErrors && hasWarning)) {
+        throw new Error(formatAggregatedDiagnostics(aggregated));
+    }
+    if (hasWarning) {
+        for (const d of aggregated) {
+            console.warn(formatSingleLineDiagnostic(d));
+        }
+    }
+    if (resolved === null) {
+        throw new Error("internal: resolved null without error diagnostic");
+    }
+    const disabled = new Set(merged.disabledRules ?? []);
+    const filteredConfig = { ...merged };
+    if (merged.rules !== undefined) {
+        const kept = merged.rules.filter((r) => !disabled.has(r.name));
+        if (kept.length > 0)
+            filteredConfig.rules = kept;
+        else
+            delete filteredConfig.rules;
+    }
+    const { pluginKept, userKept } = finalizePluginState(filteredConfig.rules ?? [], resolved.rules, filteredConfig.observers ?? [], resolved.observers);
+    const filteredResolved = {
+        ...resolved,
+        observers: [...pluginKept],
+    };
+    const evaluator = buildEvaluator(filteredConfig, filteredResolved, host);
+    const dispatcher = buildObserverDispatcher(filteredResolved, userKept, host);
+    return { evaluator, dispatcher };
+}
+//# sourceMappingURL=session-runtime.js.map

package/dist/internal/session-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-runtime.js","sourceRoot":"","sources":["../../src/internal/session-runtime.ts"],"names":[],"mappings":"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"}

package/dist/internal/watch-matcher.d.ts

@@ -0,0 +1,56 @@
+import type { ObserverWatch, ToolResultEvent } from "../schema.ts";
+/**
+ * True if the observer's `watch` filter accepts this event. No watch
+ * → matches everything. Semantics per ADR "Observer schema":
+ *
+ *   - `toolName` — exact match against `event.toolName`.
+ *   - `inputMatches` — every declared key's Pattern must match against
+ *     `event.input[key]` if that key exists AND the value is a string.
+ *     Keys absent from the event's input (or non-string values) make
+ *     the whole filter fail — documented fail-closed choice: subset
+ *     checks don't silently pass when the expected field isn't present.
+ *   - `exitCode` — `"success"` → 0, `"failure"` → non-zero,
+ *     `"any"`/omitted → pass, numeric → exact match. `exitCode` is
+ *     sourced from the event's `exitCode` field (bash only via pi's
+ *     `details.exitCode` after projection to the schema shape); other
+ *     tool results leave it `undefined` and satisfy everything except
+ *     a numeric `exitCode:` (treated as "no match" — bash-specific
+ *     filter).
+ *
+ * Wrapper-aware command matching (ADR §12): when `inputMatches.command`
+ * is set AND the event is a bash event, the pattern matches if EITHER
+ * the raw outer `event.input.command` OR any extracted command ref
+ * text matches. So `sh -c 'brazil ws sync'` with pattern
+ * `/^brazil\s+ws\s+sync$/` fires the observer — the outer raw command
+ * starts with `sh`, but the walker-extracted ref `brazil ws sync` does
+ * hit the anchored pattern.
+ *
+ * Performance: when multiple observers share the same event (the
+ * production dispatch path), pass a memoizing `refTextsProvider` to
+ * parse the bash command once across observers. Standalone callers
+ * (e.g. `testObserver` evaluating one observer in isolation, or the
+ * evaluator's speculative-allow synthesizing one event per prior
+ * `&&` ref) can omit it — the default provider parses on demand.
+ */
+export declare function matchesWatch(watch: ObserverWatch | undefined, event: ToolResultEvent, refTextsProvider?: () => readonly string[] | null): boolean;
+/**
+ * Extract per-ref flattened text (basename + args joined with spaces)
+ * from a bash tool_result's outer command, mirroring the evaluator's
+ * `prepareBashState` text projection so observer watch patterns match
+ * the same strings rule patterns see for the same command.
+ *
+ * Returns `null` when the event isn't a bash tool_result, the raw
+ * command is missing/non-string, or the walker throws while parsing
+ * (hard-to-parse command — fall back to raw-only matching without
+ * blowing up dispatch). Unlike the evaluator we don't walk trackers:
+ * observers don't receive `walkerState`, so the parse+extract+expand
+ * stages suffice.
+ *
+ * Exported so the production dispatcher can memoize the parse across
+ * observers on the same event (see `dispatchEventInner`'s
+ * `getRefTexts` cache). Chain-aware speculative-allow already
+ * synthesizes one event per prior ref and doesn't need memoization —
+ * it calls {@link matchesWatch} without a provider.
+ */
+export declare function extractRefTextsForBash(event: ToolResultEvent): readonly string[] | null;
+//# sourceMappingURL=watch-matcher.d.ts.map

package/dist/internal/watch-matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-matcher.d.ts","sourceRoot":"","sources":["../../src/internal/watch-matcher.ts"],"names":[],"mappings":"AAwCA,OAAO,KAAK,EAAE,aAAa,EAAW,eAAe,EAAE,MAAM,cAAc,CAAC;AAG5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,aAAa,GAAG,SAAS,EAChC,KAAK,EAAE,eAAe,EACtB,gBAAgB,CAAC,EAAE,MAAM,SAAS,MAAM,EAAE,GAAG,IAAI,GAChD,OAAO,CA4BT;AAqCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,eAAe,GACrB,SAAS,MAAM,EAAE,GAAG,IAAI,CAmB1B"}

package/dist/internal/watch-matcher.js

@@ -0,0 +1,179 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+/**
+ * Shared observer-watch filter contract. Single source of truth for
+ * "does this observer's `watch` accept this tool_result event?"
+ *
+ * Used by BOTH:
+ *
+ *   - the observer-dispatcher (production fire path — decides which
+ *     observers see a concrete tool_result).
+ *   - the evaluator's `when.happened` tool_call-scope speculative-
+ *     allow (synthesizes a minimal successful bash event representing
+ *     "this prior `&&` ref is about to run and succeed", then asks
+ *     the same question).
+ *
+ * Co-locating the contract here retires a structural fragility PR #4
+ * reviewers caught three times: the speculative-allow path used to
+ * hand-roll a SUBSET of the watch filter (command-pattern only, then
+ * patched to also check toolName + exitCode). Each new `watch` field
+ * the dispatcher grew would create a fresh drift opportunity.
+ *
+ * Keeping both callers on this one function guarantees the two paths
+ * agree by construction. If the speculative-allow path wants to
+ * impose a STRICTER gate on top (e.g. "observer must declare
+ * `inputMatches.command`" — an authoring requirement to keep
+ * speculative-allow safe), it layers that gate before delegating to
+ * {@link matchesWatch} rather than re-implementing the filter body.
+ *
+ * Merge-observers helper lives in {@link ./merge-observers.ts} for the
+ * same single-source-of-truth reason. This file is its sibling on the
+ * watch-filter axis.
+ */
+import { expandWrapperCommands, extractAllCommandsFromAST, parse as parseBash, } from "@cad0p/unbash-walker";
+import { matchesPattern } from "../evaluator-internals/predicates.js";
+import { refToText } from "./ref-text.js";
+/**
+ * True if the observer's `watch` filter accepts this event. No watch
+ * → matches everything. Semantics per ADR "Observer schema":
+ *
+ *   - `toolName` — exact match against `event.toolName`.
+ *   - `inputMatches` — every declared key's Pattern must match against
+ *     `event.input[key]` if that key exists AND the value is a string.
+ *     Keys absent from the event's input (or non-string values) make
+ *     the whole filter fail — documented fail-closed choice: subset
+ *     checks don't silently pass when the expected field isn't present.
+ *   - `exitCode` — `"success"` → 0, `"failure"` → non-zero,
+ *     `"any"`/omitted → pass, numeric → exact match. `exitCode` is
+ *     sourced from the event's `exitCode` field (bash only via pi's
+ *     `details.exitCode` after projection to the schema shape); other
+ *     tool results leave it `undefined` and satisfy everything except
+ *     a numeric `exitCode:` (treated as "no match" — bash-specific
+ *     filter).
+ *
+ * Wrapper-aware command matching (ADR §12): when `inputMatches.command`
+ * is set AND the event is a bash event, the pattern matches if EITHER
+ * the raw outer `event.input.command` OR any extracted command ref
+ * text matches. So `sh -c 'brazil ws sync'` with pattern
+ * `/^brazil\s+ws\s+sync$/` fires the observer — the outer raw command
+ * starts with `sh`, but the walker-extracted ref `brazil ws sync` does
+ * hit the anchored pattern.
+ *
+ * Performance: when multiple observers share the same event (the
+ * production dispatch path), pass a memoizing `refTextsProvider` to
+ * parse the bash command once across observers. Standalone callers
+ * (e.g. `testObserver` evaluating one observer in isolation, or the
+ * evaluator's speculative-allow synthesizing one event per prior
+ * `&&` ref) can omit it — the default provider parses on demand.
+ */
+export function matchesWatch(watch, event, refTextsProvider) {
+    if (!watch)
+        return true;
+    if (watch.toolName !== undefined && watch.toolName !== event.toolName) {
+        return false;
+    }
+    if (watch.inputMatches) {
+        const rawInput = event.input;
+        const input = typeof rawInput === "object" && rawInput !== null
+            ? rawInput
+            : {};
+        const getRefTexts = refTextsProvider ?? (() => extractRefTextsForBash(event));
+        for (const [key, pat] of Object.entries(watch.inputMatches)) {
+            const value = input[key];
+            if (typeof value !== "string")
+                return false;
+            if (!matchesInputField(key, pat, value, event, getRefTexts)) {
+                return false;
+            }
+        }
+    }
+    if (watch.exitCode !== undefined && watch.exitCode !== "any") {
+        if (!matchesExitCode(event.exitCode, watch.exitCode))
+            return false;
+    }
+    return true;
+}
+/**
+ * Match a single `inputMatches` key/value against the event. `command`
+ * on a bash event is wrapper-aware per ADR §12 — the raw outer command
+ * OR any extracted ref text matches. All other keys (and `command` on
+ * non-bash events) keep the straight raw-string match the v0.0 engine
+ * shipped with.
+ *
+ * Share the evaluator's regex cache (module-scoped in `predicates.ts`)
+ * so observer `inputMatches` reuse the same compiled `RegExp` as
+ * equivalent rule patterns.
+ */
+function matchesInputField(key, pat, value, event, getRefTexts) {
+    if (matchesPattern(pat, value))
+        return true;
+    // Wrapper-aware fallback: only for `command` on bash events. Other
+    // fields (path, content, …) don't have wrapper analogues — a
+    // file-path pattern has nothing to do with bash AST refs, so
+    // leaving them on the raw-string path is both correct and a perf
+    // guard against needless parsing on non-bash events.
+    if (key !== "command" || event.toolName !== "bash")
+        return false;
+    const refTexts = getRefTexts();
+    if (refTexts === null)
+        return false;
+    for (const text of refTexts) {
+        if (matchesPattern(pat, text))
+            return true;
+    }
+    return false;
+}
+/**
+ * Extract per-ref flattened text (basename + args joined with spaces)
+ * from a bash tool_result's outer command, mirroring the evaluator's
+ * `prepareBashState` text projection so observer watch patterns match
+ * the same strings rule patterns see for the same command.
+ *
+ * Returns `null` when the event isn't a bash tool_result, the raw
+ * command is missing/non-string, or the walker throws while parsing
+ * (hard-to-parse command — fall back to raw-only matching without
+ * blowing up dispatch). Unlike the evaluator we don't walk trackers:
+ * observers don't receive `walkerState`, so the parse+extract+expand
+ * stages suffice.
+ *
+ * Exported so the production dispatcher can memoize the parse across
+ * observers on the same event (see `dispatchEventInner`'s
+ * `getRefTexts` cache). Chain-aware speculative-allow already
+ * synthesizes one event per prior ref and doesn't need memoization —
+ * it calls {@link matchesWatch} without a provider.
+ */
+export function extractRefTextsForBash(event) {
+    if (event.toolName !== "bash")
+        return null;
+    const input = typeof event.input === "object" && event.input !== null
+        ? event.input
+        : undefined;
+    const command = input?.command;
+    if (typeof command !== "string" || command.length === 0)
+        return null;
+    try {
+        const script = parseBash(command);
+        const extracted = extractAllCommandsFromAST(script, command);
+        const { commands: refs } = expandWrapperCommands(extracted);
+        return refs.map(refToText);
+    }
+    catch {
+        // Don't let a parse error take down dispatch — a malformed
+        // command still deserves a raw-match chance. Returning null
+        // (as opposed to []) skips ref matching entirely for this event.
+        return null;
+    }
+}
+function matchesExitCode(code, filter) {
+    if (typeof filter === "number") {
+        // Numeric filter requires a concrete code; no-code events (non-bash)
+        // never match a numeric filter.
+        return code === filter;
+    }
+    if (filter === "success")
+        return code === 0;
+    if (filter === "failure")
+        return code !== undefined && code !== 0;
+    return true;
+}
+//# sourceMappingURL=watch-matcher.js.map

package/dist/internal/watch-matcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-matcher.js","sourceRoot":"","sources":["../../src/internal/watch-matcher.ts"],"names":[],"mappings":"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"}

package/dist/loader.d.ts

@@ -0,0 +1,97 @@
+import type { SteeringConfig, SteeringDiagnostic } from "./schema.ts";
+/**
+ * Candidate file paths for a given directory's `.pi/steering/...` slot,
+ * in priority order. First existing file wins.
+ *
+ * Exported for tests — not part of the library's public API.
+ */
+export declare function configCandidates(dir: string): string[];
+/**
+ * Walk up from `cwd` to `$HOME` (inclusive, or to the filesystem root
+ * if HOME is unset / outside the cwd's ancestry), returning the list
+ * of directories INNER-FIRST — so `[cwd, cwd/parent, ..., HOME]`.
+ *
+ * Exported for tests.
+ */
+export declare function ancestorChain(cwd: string): string[];
+/**
+ * Find the config file (if any) for a single layer. Returns the
+ * resolved file path and a `layer-form-coexistence` diagnostic when
+ * both `.pi/steering/index.ts` and `.pi/steering.ts` coexist in the
+ * same directory (the directory form wins).
+ *
+ * Exported for tests.
+ */
+export declare function findConfigFile(dir: string): {
+    file: string | null;
+    diagnostic: SteeringDiagnostic | null;
+};
+/**
+ * Walk up from `cwd` collecting config layers. Returns INNER-FIRST
+ * (caller passes to {@link buildConfig}, which expects inner-first so
+ * early entries take precedence on collisions).
+ *
+ * Issues encountered along the way (per-layer import failure, dual
+ * form coexistence, stray non-`.ts` file under `.pi/steering/`)
+ * surface as structured {@link SteeringDiagnostic} entries on the
+ * returned object. The loader does not log to `console.warn` directly
+ * — the bridge runtime owns the policy decision (throw vs. log) once
+ * it has collected diagnostics from every source.
+ *
+ * @throws when Node is older than {@link MIN_NODE_MAJOR}.
+ */
+export declare function loadConfigs(cwd: string): Promise<{
+    layers: SteeringConfig[];
+    diagnostics: SteeringDiagnostic[];
+}>;
+/**
+ * Inner-wins boolean merge over walked-up layers. Walks left-to-right
+ * (inner-first); returns the first explicit boolean or `undefined`.
+ * Used by `buildConfig` and the session runtime for the inner-wins
+ * boolean fields. Internal — not in the package's `exports` surface.
+ */
+export declare function mergeBool(layers: readonly SteeringConfig[], key: "defaultNoOverride" | "disableDefaults" | "failOnWarnings"): boolean | undefined;
+/**
+ * Merge `layers` (inner-first) into a single effective
+ * {@link SteeringConfig}. An optional `defaults` config is treated as
+ * the OUTERMOST layer — its fields apply when no real layer specifies
+ * them, otherwise real layers override.
+ *
+ * Cross-layer plugin name collisions, within-layer rule + observer
+ * name collisions, and cross-layer tracker name collisions surface
+ * as structured {@link SteeringDiagnostic} entries on the returned
+ * object. Predicate-key + tracker-extension collisions are detected
+ * in `resolvePlugins`, not here — buildConfig handles cross-layer and
+ * within-layer name-collision shapes only.
+ */
+export declare function buildConfig(layers: readonly SteeringConfig[], defaults?: SteeringConfig): {
+    config: SteeringConfig;
+    diagnostics: SteeringDiagnostic[];
+};
+/**
+ * Convenience: load all layers for `cwd`, run the loader-side merge
+ * (`buildConfig`), then the plugin merger (`resolvePlugins`) with
+ * user-config rule + observer name validation between the two passes.
+ * Diagnostics from every surface flow into a single returned array,
+ * so an external embedder writing their own bridge or pre-flight
+ * check sees the SAME diagnostic stream the production runtime sees
+ * — no surface is silently skipped.
+ *
+ * Diagnostics return in declaration order; merge-side errors
+ * short-circuit `resolvePlugins` before its diagnostics are added.
+ *
+ * Production-strictness divergence: `loadSteeringConfig` does NOT
+ * apply the strict-mode `failOnWarnings` throw policy that
+ * `buildSessionRuntime` does. The function never throws on
+ * diagnostics; embedders apply their own throw + warning policy.
+ * See `failOnWarnings` on {@link SteeringConfig} for production-
+ * faithful pre-flight semantics.
+ *
+ * @throws when Node < {@link MIN_NODE_MAJOR} (propagated from
+ * `loadConfigs`).
+ */
+export declare function loadSteeringConfig(cwd: string, defaults?: SteeringConfig): Promise<{
+    config: SteeringConfig;
+    diagnostics: SteeringDiagnostic[];
+}>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAIV,cAAc,EACd,kBAAkB,EACnB,MAAM,aAAa,CAAC;AA+BrB;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAKtD;AA+BD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAenD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG;IAC3C,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,UAAU,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACvC,CAsBA;AAuED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACtD,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,WAAW,EAAE,kBAAkB,EAAE,CAAC;CACnC,CAAC,CA2CD;AAiJD;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,SAAS,cAAc,EAAE,EACjC,GAAG,EAAE,mBAAmB,GAAG,iBAAiB,GAAG,gBAAgB,GAC9D,OAAO,GAAG,SAAS,CAMrB;AAwCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,SAAS,cAAc,EAAE,EACjC,QAAQ,CAAC,EAAE,cAAc,GACxB;IAAE,MAAM,EAAE,cAAc,CAAC;IAAC,WAAW,EAAE,kBAAkB,EAAE,CAAA;CAAE,CA0C/D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,cAAc,GACxB,OAAO,CAAC;IAAE,MAAM,EAAE,cAAc,CAAC;IAAC,WAAW,EAAE,kBAAkB,EAAE,CAAA;CAAE,CAAC,CAWxE"}