@yagni-app/code 0.2.1 → 0.3.1

package/dist/extension/cmux/state.d.ts

@@ -0,0 +1,33 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+export interface PendingCompletion {
+    lastAssistantMessage?: string;
+    notificationType: string;
+    turnId: string;
+}
+export interface SessionState {
+    nextTurn: number;
+    activeTurnId?: string;
+    pendingCompletion?: PendingCompletion;
+    stopped: boolean;
+    lastPrompt?: string;
+    hasNamed?: boolean;
+}
+export interface PiExtensionContextSnapshot {
+    readonly sessionId: string | null;
+    readonly cwd: string;
+    readonly notifyWarning?: () => void;
+}
+export declare function firstString(...values: unknown[]): string | null;
+export declare function objectValue(value: unknown, keys: string[]): unknown;
+export declare function textFromContent(content: unknown): string | null;
+export declare function lastAssistantMessage(event: unknown): string | undefined;
+export declare function sessionIdFrom(ctx: ExtensionContext): string | null;
+export declare function cwdFrom(ctx: ExtensionContext): string;
+export declare function snapshotContext(ctx: ExtensionContext): PiExtensionContextSnapshot;
+export declare function stateFor(sessionStates: Map<string, SessionState>, sessionId: string): SessionState;
+export declare function beginTurn(sessionStates: Map<string, SessionState>, sessionId: string, event: unknown): string;
+export declare function currentTurnId(sessionStates: Map<string, SessionState>, sessionId: string, event: unknown): string;
+export declare function finishTurn(sessionStates: Map<string, SessionState>, sessionId: string, event: unknown): string;
+export declare function settleTurn(sessionStates: Map<string, SessionState>, sessionId: string): PendingCompletion | undefined;
+export declare function warn(ctx: PiExtensionContextSnapshot | null, message: string, details?: Record<string, unknown>, notifyUser?: boolean): void;
+//# sourceMappingURL=state.d.ts.map

package/dist/extension/cmux/state.js

@@ -0,0 +1,142 @@
+export function firstString(...values) {
+    for (const value of values) {
+        if (typeof value === "string" && value.trim().length > 0)
+            return value.trim();
+    }
+    return null;
+}
+export function objectValue(value, keys) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const typed = value;
+    for (const key of keys) {
+        if (typed[key] !== undefined && typed[key] !== null)
+            return typed[key];
+    }
+    return undefined;
+}
+export function textFromContent(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return null;
+    const parts = [];
+    for (const block of content) {
+        if (!block || typeof block !== "object")
+            continue;
+        const typed = block;
+        if (typed.type === "text" && typeof typed.text === "string")
+            parts.push(typed.text);
+    }
+    return parts.join("\n") || null;
+}
+export function lastAssistantMessage(event) {
+    const messagesValue = objectValue(event, ["messages"]);
+    const messages = Array.isArray(messagesValue) ? messagesValue : [];
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (!message || typeof message !== "object")
+            continue;
+        const typed = message;
+        if (typed.role !== "assistant")
+            continue;
+        const text = firstString(textFromContent(typed.content));
+        if (text)
+            return text;
+    }
+    return undefined;
+}
+export function sessionIdFrom(ctx) {
+    try {
+        return firstString(ctx.sessionManager?.getSessionId?.());
+    }
+    catch {
+        return null;
+    }
+}
+export function cwdFrom(ctx) {
+    try {
+        return firstString(ctx.cwd, process.cwd()) || process.cwd();
+    }
+    catch {
+        return process.cwd();
+    }
+}
+export function snapshotContext(ctx) {
+    if (!ctx || typeof ctx !== "object") {
+        return { sessionId: null, cwd: process.cwd() };
+    }
+    let notifyWarning;
+    try {
+        const ui = ctx.ui;
+        if (typeof ui?.notify === "function") {
+            notifyWarning = () => ui.notify?.("cmux integration warning — check the terminal for details", "warning");
+        }
+    }
+    catch { }
+    return { sessionId: sessionIdFrom(ctx), cwd: cwdFrom(ctx), notifyWarning };
+}
+export function stateFor(sessionStates, sessionId) {
+    let state = sessionStates.get(sessionId);
+    if (!state) {
+        state = { nextTurn: 0, stopped: false };
+        sessionStates.set(sessionId, state);
+    }
+    return state;
+}
+function eventTurnId(event) {
+    return firstString(objectValue(event, ["turn_id", "turnId", "turnID"]));
+}
+export function beginTurn(sessionStates, sessionId, event) {
+    const state = stateFor(sessionStates, sessionId);
+    const turnId = eventTurnId(event) || `${sessionId}:turn-${state.nextTurn + 1}`;
+    if (!eventTurnId(event))
+        state.nextTurn += 1;
+    state.activeTurnId = turnId;
+    state.pendingCompletion = undefined;
+    state.stopped = false;
+    return turnId;
+}
+export function currentTurnId(sessionStates, sessionId, event) {
+    const state = stateFor(sessionStates, sessionId);
+    const turnId = eventTurnId(event) || state.activeTurnId || `${sessionId}:turn-${state.nextTurn + 1}`;
+    if (!eventTurnId(event) && !state.activeTurnId)
+        state.nextTurn += 1;
+    return turnId;
+}
+export function finishTurn(sessionStates, sessionId, event) {
+    const state = stateFor(sessionStates, sessionId);
+    const turnId = eventTurnId(event) || state.activeTurnId || `${sessionId}:turn-${state.nextTurn + 1}`;
+    if (!eventTurnId(event) && !state.activeTurnId)
+        state.nextTurn += 1;
+    state.activeTurnId = undefined;
+    state.pendingCompletion = undefined;
+    state.stopped = true;
+    return turnId;
+}
+export function settleTurn(sessionStates, sessionId) {
+    const state = sessionStates.get(sessionId);
+    const completion = state?.pendingCompletion;
+    if (!state || !completion || state.stopped)
+        return undefined;
+    state.activeTurnId = undefined;
+    state.pendingCompletion = undefined;
+    state.stopped = true;
+    return completion;
+}
+export function warn(ctx, message, details = {}, notifyUser = false) {
+    const payload = { source: "yagni-cmux-bridge", level: "warning", message, ...details };
+    try {
+        console.warn(JSON.stringify(payload));
+    }
+    catch {
+        console.warn(`[yagni-cmux-bridge] ${message}`);
+    }
+    if (notifyUser) {
+        try {
+            ctx?.notifyWarning?.();
+        }
+        catch { }
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/extension/config.d.ts

@@ -72,13 +72,32 @@ export interface FetchCatalogOptions {
     getToken: () => string | undefined;
     fetchImpl?: typeof fetch;
 }
+/** Guardian storage tier for this workspace (YAG-510). */
+export type GuardianStorageTier = "off" | "hash" | "raw";
+/** The startup catalog response from GET /api/yagni-code/models. */
+export interface CatalogResult {
+    models: ModelEntry[];
+    /**
+     * Per-workspace Guardian kill switch (yagni_code.guardian). Fail-safe:
+     * only an explicit `false` from the backend disables the Guardian — a
+     * missing field (older backend) reads as enabled.
+     */
+    guardianEnabled: boolean;
+    /**
+     * Guardian event storage tier (YAG-510). Polarity is deliberately the
+     * OPPOSITE of guardianEnabled: only an explicit "hash" or "raw" turns
+     * storage on — a missing field (older backend) or unknown value reads as
+     * "off" (fail toward not sending).
+     */
+    guardianStorage: GuardianStorageTier;
+}
 /**
  * Fetch the YAGNI model catalog at startup.
  *
  * @throws an actionable Error (mentioning `yagni login`) on any non-2xx
  * response so the launcher can surface a clear re-authentication prompt.
  */
-export declare function fetchCatalog(opts: FetchCatalogOptions): Promise<ModelEntry[]>;
+export declare function fetchCatalog(opts: FetchCatalogOptions): Promise<CatalogResult>;
 /** The startup company brief returned by GET /api/yagni-code/context. */
 export interface ContextBrief {
     brief: string;
@@ -94,6 +113,12 @@ export interface ContextBrief {
         decisions: number;
         corrections: number;
     };
+    /**
+     * Active decisions scoped to the repo named on the request (additive, Run
+     * 7; absent without `?repo=`, on older backends, and on a count failure).
+     * The opt-in mining beat fires ONLY on an explicit 0.
+     */
+    repoDecisionCount?: number;
 }
 /**
  * Attribution headers for the model proxy (YAG-471). On the SERVER side these
@@ -156,11 +181,29 @@ export declare function isDriverCaller(env?: NodeJS.ProcessEnv): boolean;
  * sanitizing client-side is what keeps the attribution instead of losing it.
  */
 export declare function sanitizeCallerSegment(name: string, maxLength?: number): string;
+/**
+ * Attribution headers for the boot-time /context fetch. Extends
+ * {@link attributionHeaders} (session id + caller) with the surface the
+ * session is painting for (the desktop driver sets YAGNI_SURFACE=desktop;
+ * the terminal CLI sets nothing) and the shipping client version. The server
+ * uses these to emit its "YAGNI Code Session Started" analytics event —
+ * labels only on that side: a missing or malformed value can never fail the
+ * fetch, it just goes uncounted or unversioned.
+ */
+export declare function sessionTelemetryHeaders(env?: NodeJS.ProcessEnv): Record<string, string>;
 /** Options for {@link fetchContextBrief}. */
 export interface FetchContextBriefOptions {
     baseUrl: string;
     getToken: () => string | undefined;
     fetchImpl?: typeof fetch;
+    /** Env seam for the telemetry headers; defaults to process.env. */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * The session repo (`owner/name`), when resolvable. Rides as `?repo=` so
+     * the response can carry `repoDecisionCount` for the mining beat — no
+     * second round-trip at boot.
+     */
+    repo?: string;
 }
 /**
  * Fetch the workspace company brief at startup.

package/dist/extension/config.js

@@ -85,7 +85,13 @@ export async function fetchCatalog(opts) {
         throw new Error(`Failed to fetch YAGNI model catalog (HTTP ${res.status}). Run \`yagni login\` to re-authenticate.`);
     }
     const data = (await res.json());
-    return data.models;
+    return {
+        models: data.models,
+        guardianEnabled: data.guardianEnabled !== false,
+        guardianStorage: data.guardianStorage === "raw" || data.guardianStorage === "hash"
+            ? data.guardianStorage
+            : "off",
+    };
 }
 /** Shape-check for a caller label: mirrors the model proxy's own validation regex. */
 const CALLER_LABEL_RE = /^[a-z0-9][a-z0-9:_.-]{0,63}$/i;
@@ -129,8 +135,6 @@ export function attributionHeaders(env = process.env) {
         headers["x-yagni-run-id"] = runId;
     const caller = env.YAGNI_CALLER ?? "";
     headers["x-yagni-caller"] = CALLER_LABEL_RE.test(caller) ? caller : "driver";
-    if (env.YAGNI_BOOST === "1")
-        headers["x-yagni-boost"] = "1";
     return headers;
 }
 /**
@@ -173,6 +177,28 @@ export function sanitizeCallerSegment(name, maxLength = 64) {
     const trimmed = cleaned.slice(0, Math.max(0, maxLength));
     return trimmed || "agent";
 }
+/**
+ * Shape-check for a client version label (semver-ish; matches the server's
+ * own allowlist). A value that fails is dropped, never sent raw.
+ */
+const CLIENT_VERSION_RE = /^[0-9a-z][0-9a-z.+-]{0,31}$/i;
+/**
+ * Attribution headers for the boot-time /context fetch. Extends
+ * {@link attributionHeaders} (session id + caller) with the surface the
+ * session is painting for (the desktop driver sets YAGNI_SURFACE=desktop;
+ * the terminal CLI sets nothing) and the shipping client version. The server
+ * uses these to emit its "YAGNI Code Session Started" analytics event —
+ * labels only on that side: a missing or malformed value can never fail the
+ * fetch, it just goes uncounted or unversioned.
+ */
+export function sessionTelemetryHeaders(env = process.env) {
+    const headers = attributionHeaders(env);
+    headers["x-yagni-surface"] = env.YAGNI_SURFACE === "desktop" ? "desktop" : "cli";
+    const version = env.YAGNI_CODE_VERSION ?? "";
+    if (CLIENT_VERSION_RE.test(version))
+        headers["x-yagni-client-version"] = version;
+    return headers;
+}
 /**
  * Fetch the workspace company brief at startup.
  *
@@ -182,7 +208,14 @@ export function sanitizeCallerSegment(name, maxLength = 64) {
  */
 export async function fetchContextBrief(opts) {
     try {
-        const res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/context`, { method: "GET", headers: { authorization: `Bearer ${opts.getToken() ?? ""}` } }, { fetchImpl: opts.fetchImpl });
+        const query = opts.repo ? `?repo=${encodeURIComponent(opts.repo)}` : "";
+        const res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/context${query}`, {
+            method: "GET",
+            headers: {
+                authorization: `Bearer ${opts.getToken() ?? ""}`,
+                ...sessionTelemetryHeaders(opts.env),
+            },
+        }, { fetchImpl: opts.fetchImpl });
         if (!res.ok)
             return null;
         return (await res.json());

package/dist/extension/costHud.d.ts

@@ -52,7 +52,20 @@ export interface Headroom {
     remaining: number;
     unit: string;
 }
-export declare function formatCostLine(snap: CostSnapshot, headroom?: Headroom | null, advisorLine?: string, source?: string, boosted?: boolean): string;
+/**
+ * Render the /cost line. Pure, no em-dashes. `headroom` null means it was
+ * unavailable. `advisorLine` is the ask_advisor subtotal (empty when the session
+ * never escalated). `source`, when given, is parenthesized right after "Session
+ * usage", used to explicitly label this as the LOCAL, driver-only fallback when
+ * the server-authoritative spend fetch is unavailable (see
+ * {@link formatServerCostLines}, the preferred path).
+ *
+ * HONESTY NOTE: this counter can only see the DRIVER session, because it is fed
+ * by pi's `turn_end`. Work that runs in a child process — every /go stage, and
+ * every advisor consult — never emits a parent `turn_end`, so it is invisible
+ * here. The advisor subtotal is threaded in explicitly for exactly that reason.
+ */
+export declare function formatCostLine(snap: CostSnapshot, headroom?: Headroom | null, advisorLine?: string, source?: string): string;
 /**
  * One row of `GET /api/yagni-code/spend`'s per-caller x rate-tier breakdown.
  * Mirrored locally rather than importing `@yagni/shared`, since this extension
@@ -102,25 +115,15 @@ export declare const usd: (millicents: number) => string;
  * (joined with "\n").
  *
  * Line order: total spend, one line per rate tier (aggregated across callers,
- * sorted by spend descending), a boosted-spend subtotal per tier that has any
- * boosted rows, a live-toggle boost line (see below), the savings line (only
+ * sorted by spend descending), the savings line (only
  * when a counterfactual total resolved), an incomplete-counterfactual note,
  * an unbilled note, a dropped-run-ids note (carry-over from the /cost
  * re-review — see sessionRuns.ts's `droppedSessionRuns`), then headroom.
  *
  * `droppedRunCount` defaults to 0 (no note) so every existing direct caller
  * of this pure function keeps behaving identically without passing it.
- *
- * `boosted` (default false) is the LIVE client-side toggle from
- * `boostCommand.ts`'s `isBoosted()`, threaded in exactly like `advisorLine`
- * is for {@link formatCostLine}. It is independent of the per-tier "Boosted
- * (tier) spend" subtotal above: that subtotal only reflects server rows
- * carrying `x-yagni-boost`, which only `/go` children (and other spawned
- * processes) ever send — the driver's own turns never do (see
- * boostCommand.ts's KNOWN-asymmetry docblock). Without this flag, a session
- * that only chats while boosted would show no boost line at all.
  */
-export declare function formatServerCostLines(spend: SpendResponse, headroom?: Headroom | null, droppedRunCount?: number, boosted?: boolean): string;
+export declare function formatServerCostLines(spend: SpendResponse, headroom?: Headroom | null, droppedRunCount?: number): string;
 export interface RegisterCostDeps {
     /** Fetch remaining credit headroom; return null when unavailable. Fail-soft. */
     fetchHeadroom?: (signal?: AbortSignal) => Promise<Headroom | null>;
@@ -132,15 +135,6 @@ export interface RegisterCostDeps {
      * ordinary caller row.
      */
     advisorSubtotal?: () => string;
-    /**
-     * Whether the session is currently boosted to Peak (boostCommand.ts's
-     * `isBoosted()`, threaded in the same way as `advisorSubtotal`). Unlike
-     * `advisorSubtotal`, this is read on BOTH the server-authoritative and the
-     * local-fallback branch: the driver's own turns never carry a server-side
-     * boost marker (see boostCommand.ts's KNOWN-asymmetry docblock), so this is
-     * the only signal that would otherwise be missing from the server branch.
-     */
-    isBoosted?: () => boolean;
     /**
      * Fetch the server-authoritative session spend (YAG-383). Absent, throwing,
      * or resolving null all fall back to the local `turn_end` accumulator, with

package/dist/extension/costHud.js

@@ -75,21 +75,18 @@ const fmt = (n) => n.toLocaleString("en-US");
  * every advisor consult — never emits a parent `turn_end`, so it is invisible
  * here. The advisor subtotal is threaded in explicitly for exactly that reason.
  */
-/** The boost-active line appended to /cost, both branches (see boostCommand.ts's docblock for why). */
-const BOOST_LINE = "Boost is on. Driver turns bill at the peak tier.";
-export function formatCostLine(snap, headroom, advisorLine, source, boosted = false) {
+export function formatCostLine(snap, headroom, advisorLine, source) {
     const turns = `${snap.turns} turn${snap.turns === 1 ? "" : "s"}`;
     const cached = snap.cacheRead > 0 ? ` (${fmt(snap.cacheRead)} cached)` : "";
     const label = source ? `Session usage (${source})` : "Session usage";
     const base = `${label}: ${turns}, ${fmt(snap.input)} in / ${fmt(snap.output)} out tokens${cached}, ` +
         `$${snap.cost.toFixed(2)} this session.`;
     const advisor = advisorLine?.trim() ? ` ${advisorLine.trim()}` : "";
-    const boost = boosted ? ` ${BOOST_LINE}` : "";
     if (headroom)
-        return `${base}${advisor}${boost} Credit headroom: ${headroom.remaining} ${headroom.unit}.`;
+        return `${base}${advisor} Credit headroom: ${headroom.remaining} ${headroom.unit}.`;
     if (headroom === null)
-        return `${base}${advisor}${boost} Credit headroom unavailable right now.`;
-    return `${base}${advisor}${boost}`;
+        return `${base}${advisor} Credit headroom unavailable right now.`;
+    return `${base}${advisor}`;
 }
 /**
  * Millicents (1/1000 of a cent) -> dollars, 2 decimals. Guards against a
@@ -115,25 +112,15 @@ export const usd = (millicents) => {
  * (joined with "\n").
  *
  * Line order: total spend, one line per rate tier (aggregated across callers,
- * sorted by spend descending), a boosted-spend subtotal per tier that has any
- * boosted rows, a live-toggle boost line (see below), the savings line (only
+ * sorted by spend descending), the savings line (only
  * when a counterfactual total resolved), an incomplete-counterfactual note,
  * an unbilled note, a dropped-run-ids note (carry-over from the /cost
  * re-review — see sessionRuns.ts's `droppedSessionRuns`), then headroom.
  *
  * `droppedRunCount` defaults to 0 (no note) so every existing direct caller
  * of this pure function keeps behaving identically without passing it.
- *
- * `boosted` (default false) is the LIVE client-side toggle from
- * `boostCommand.ts`'s `isBoosted()`, threaded in exactly like `advisorLine`
- * is for {@link formatCostLine}. It is independent of the per-tier "Boosted
- * (tier) spend" subtotal above: that subtotal only reflects server rows
- * carrying `x-yagni-boost`, which only `/go` children (and other spawned
- * processes) ever send — the driver's own turns never do (see
- * boostCommand.ts's KNOWN-asymmetry docblock). Without this flag, a session
- * that only chats while boosted would show no boost line at all.
  */
-export function formatServerCostLines(spend, headroom, droppedRunCount = 0, boosted = false) {
+export function formatServerCostLines(spend, headroom, droppedRunCount = 0) {
     const lines = [`Session spend: $${usd(spend.totalSellMillicents)} (server).`];
     const tierTotals = new Map();
     for (const row of spend.rows) {
@@ -147,23 +134,6 @@ export function formatServerCostLines(spend, headroom, droppedRunCount = 0, boos
         const calls = `${fmt(agg.dispatches)} call${agg.dispatches === 1 ? "" : "s"}`;
         lines.push(`  ${tier}: $${usd(agg.sellMillicents)} over ${calls}.`);
     }
-    const boostTotals = new Map();
-    for (const row of spend.rows) {
-        if (!row.boost)
-            continue;
-        boostTotals.set(row.rateTier, (boostTotals.get(row.rateTier) ?? 0) + row.sellMillicents);
-    }
-    if (boostTotals.size > 0) {
-        for (const [tier] of tiersSorted) {
-            const tierBoosted = boostTotals.get(tier);
-            if (tierBoosted === undefined)
-                continue;
-            lines.push(`  Boosted (${tier}) spend: $${usd(tierBoosted)}.`);
-        }
-    }
-    if (boosted) {
-        lines.push(BOOST_LINE);
-    }
     // typeof guard (not just !== null): a network response is untyped at
     // runtime, and a stray string/boolean here must never sneak "NN%" into the
     // rendered line.
@@ -233,15 +203,6 @@ export function registerCostCommand(pi, deps = {}) {
                     : Promise.resolve(null),
             ]);
             const localSnap = acc.snapshot();
-            // Read fresh on every /cost call, both branches (see RegisterCostDeps's
-            // isBoosted doc comment for why the local fallback needs it too).
-            let boosted = false;
-            try {
-                boosted = deps.isBoosted?.() ?? false;
-            }
-            catch {
-                /* a diagnostic must never break /cost */
-            }
             // Quiet divergence check: both totals must be available, and it never
             // affects what the user sees. Scoped to `caller === "driver"` rows only
             // (like-for-like with the local `turn_end` accumulator, which can only
@@ -276,7 +237,7 @@ export function registerCostCommand(pi, deps = {}) {
                 catch {
                     /* a diagnostic must never break /cost */
                 }
-                await pi.sendUserMessage(formatServerCostLines(spend, headroom, dropped, boosted));
+                await pi.sendUserMessage(formatServerCostLines(spend, headroom, dropped));
                 return;
             }
             let advisorLine = "";
@@ -286,7 +247,7 @@ export function registerCostCommand(pi, deps = {}) {
             catch {
                 /* usage accounting must never break /cost */
             }
-            await pi.sendUserMessage(formatCostLine(localSnap, headroom, advisorLine, "local, driver only", boosted));
+            await pi.sendUserMessage(formatCostLine(localSnap, headroom, advisorLine, "local, driver only"));
         },
     });
 }

package/dist/extension/crashReport.js

@@ -125,8 +125,6 @@ export function makeCrashReporter(opts) {
             if (crashReportsDisabled(env))
                 return;
             const token = opts.getToken();
-            if (!token)
-                return;
             const sanitized = sanitizeCrashError(error, { env, repoRoot });
             const payload = {
                 client: isDesktopSurface() ? "desktop" : "cli",
@@ -148,7 +146,7 @@ export function makeCrashReporter(opts) {
                     method: "POST",
                     headers: {
                         "content-type": "application/json",
-                        authorization: `Bearer ${token}`,
+                        ...(token ? { authorization: `Bearer ${token}` } : {}),
                     },
                     body: JSON.stringify(payload),
                     signal: controller.signal,

package/dist/extension/execPolicy.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Exec policy engine — classifies bash commands via prefix rules + lightweight
+ * shell tokenization (YAG-504, restructured in YAG-510).
+ *
+ * Pure: no I/O, no network, no model. Loads at startup and classifies
+ * synchronously. The curated default set auto-allows read-only commands
+ * (ls, cat, rg, git status/log/diff), forbids destructive ones (rm -rf,
+ * git reset --hard, git push --force, pipe-to-shell), and prompts for the
+ * ambiguous middle band (npm install, git commit, curl, …).
+ *
+ * The `prompt` band is what the Guardian arbitrates — see guardian.ts.
+ *
+ * Classification composes three signals and takes the STRICTEST:
+ *   1. prefix-rule matching on every segment (newlines, ;, &&, ||, | split);
+ *   2. a construct floor — commands using redirects, substitution, or
+ *      background & can never be auto-allowed (floor: prompt);
+ *   3. dangerScan — a best-effort sweep of command-substitution inner text
+ *      ($(...) and backticks, including inside double quotes) against the
+ *      FORBIDDEN rules only. Danger anywhere upgrades to forbidden; the scan
+ *      can never make anything more permissive.
+ * This is the codex two-parser lesson: fail closed to prove safety, scan
+ * best-effort to prove danger. A forbidden match must win even when the
+ * command also carries constructs (`rm -rf / &` is forbidden, not prompt).
+ *
+ * Command words are matched through a leading-token strip (env assignments,
+ * sudo/env/command wrappers, shell reserved words, a leading backslash) and
+ * basename normalization (/bin/rm → rm) — both applied ASYMMETRICALLY: they
+ * can make a command land on forbidden/prompt rules, but a stripped or
+ * path-prefixed command is never auto-allowed (`sudo ls` and `./ls` stay in
+ * the prompt band; an attacker-named local `./rm` binary must not ride the
+ * allow list, and `/bin/ls` pays the same price by design).
+ *
+ * Tokenization is a lightweight inline parser — not shell-quote — because the
+ * extension is bundled into @yagni-app/code's dist (a file copy, not a real
+ * bundler), and external dependencies aren't resolvable from the bundled path.
+ */
+export type TokenEntry = string | {
+    op: "pipe" | "and" | "or" | "semi" | "substitution";
+} | {
+    op: "redirect";
+    direction: "out";
+    fd: "stdout" | "stderr";
+    target: string;
+    append: boolean;
+} | {
+    op: "redirect";
+    direction: "in";
+} | {
+    op: "background";
+};
+/**
+ * Parse a shell command string into tokens and control operators.
+ *
+ * Handles:
+ * - Single and double quoted strings (preserves spaces inside)
+ * - Control operators: |, &&, ||, ;, and newlines (a newline separates
+ *   commands exactly like `;` — treating it as whitespace let multiline
+ *   commands smuggle anything behind an allow-listed first line)
+ * - `#` comments (start-of-word to end-of-line, outside quotes)
+ * - Shell constructs we flag as unanalyzable: $(), backticks (INCLUDING
+ *   inside double quotes — bash executes those), >, <, background &
+ * - Redirect metadata: stdout/stderr redirects carry fd + target so that
+ *   safe redirects (2>/dev/null, 2>&1) can be distinguished from unsafe ones
+ *   (> file.txt). Stdin redirects (<, <<) carry no metadata — they always
+ *   floor. Background & emits a distinct `background` op (not `semi`) so
+ *   hasUnhandledConstructs can always catch it.
+ *
+ * Does NOT handle: variable expansion, glob patterns, heredocs beyond the
+ * redirect flag, nested subshells beyond depth tracking. Commands using
+ * those are classified as "prompt" at minimum (construct floor).
+ */
+export declare function shellParse(command: string): TokenEntry[];
+/**
+ * Extract the inner text of every command substitution — $(...) and
+ * backticks — respecting single-quote literalness and backslash escapes.
+ * Includes substitutions inside double quotes (bash executes those).
+ * Best-effort, used ONLY by dangerScan to prove danger, never safety.
+ */
+export declare function extractSubstitutions(command: string): string[];
+export type ExecDecision = "allow" | "prompt" | "forbidden";
+export interface PrefixRule {
+    /** Ordered tokens; a string[] element means alternatives (any match). */
+    pattern: (string | string[])[];
+    decision: ExecDecision;
+    justification: string;
+    /**
+     * Escape hatch for allow rules whose command has a mutating flag: if any
+     * token AFTER the matched prefix equals one of these (or, for entries ending
+     * in "*", starts with the part before the star), the rule does NOT match and
+     * evaluation falls through to later rules (usually landing in the prompt
+     * band). Example: sed is read-only except with -i/--in-place.
+     */
+    unlessTokens?: string[];
+    /**
+     * Position-independent flag requirement: the rule matches only when, in
+     * addition to the pattern prefix, at least one token AFTER the prefix
+     * matches an entry (same "*"-suffix glob convention as unlessTokens).
+     * Used by forbidden rules to catch permuted flags: `git push origin
+     * --force` and `rm x -rf` place the dangerous flag after positional args,
+     * where exact-position patterns never see it.
+     */
+    flagsAnywhere?: string[];
+    /** Positive test invocations (validated at load if present). */
+    match?: string[][];
+    /** Negative test invocations (validated at load if present). */
+    notMatch?: string[][];
+}
+export interface ExecPolicy {
+    rules: PrefixRule[];
+}
+export interface ExecClassification {
+    decision: ExecDecision;
+    justification: string;
+    matchedRule?: PrefixRule;
+}
+/**
+ * Parse a command string into tokens using our lightweight tokenizer. Returns
+ * string tokens only (control operators and constructs are filtered out —
+ * detected separately).
+ */
+export declare function tokenize(command: string): string[];
+/**
+ * Classify a full bash command string against the exec policy.
+ *
+ * Compound commands (pipes, &&, ||, ;, newlines) are split into segments and
+ * each is classified independently; the strictest decision wins (forbidden >
+ * prompt > allow). Commands with shell constructs (substitution, redirects,
+ * background &) have a floor of `prompt`, and their substitution inner text
+ * is danger-scanned against the forbidden rules. Pipe-to-shell is always
+ * forbidden.
+ */
+export declare function classifyCommand(command: string, policy: ExecPolicy): ExecClassification;
+/** Curated default rules — the shipped safety floor. */
+export declare const DEFAULT_EXEC_POLICY: ExecPolicy;
+//# sourceMappingURL=execPolicy.d.ts.map