@wrongstack/tools 0.284.1 → 0.286.0

package/README.md

@@ -42,6 +42,24 @@ pnpm add @wrongstack/tools @wrongstack/core
 | `fetch` | `auto` | no | SSRF-hardened (IPv4 + IPv6 private CIDR, redirect re-validation, http://-downgrade refused) |
 | `search` | `auto` | no | Web search via configured provider |
 
+### Browser
+
+First-party `browser_*` tools lazily launch Playwright Chromium and use isolated per-agent
+contexts. Observation tools are automatic; navigation, interaction, screenshot persistence,
+upload, and evaluation require confirmation where appropriate. See
+[browser automation](../../docs/browser-automation.md) for the lifecycle and security contract.
+Credential entry uses `browser_type.secretEnv` so audit records retain a placeholder rather than
+the secret value.
+
+### E2E discovery
+
+| Tool | Permission | Mutating | Notes |
+|------|------------|----------|-------|
+| `e2e_plan` | `auto` | no | Statically discovers Playwright/Cypress configs, servers, specs, and exact argv without evaluating project code |
+
+See [the browser-aware E2E runner guide](../../docs/e2e-runner.md). Process startup and test
+execution remain separate permission-gated steps.
+
 ### Project lifecycle
 
 | Tool | Permission | Notes |
@@ -87,6 +105,7 @@ const all = new ToolRegistry(builtinTools);
 - **`bash` / `exec` child env sanitized** to a fixed allowlist + secret-substring strip (`TOKEN` / `SECRET` / `PASSWORD` / `AUTH` / `BEARER` / `COOKIE` / `PRIVATE` / `KEY`). Opt-out via `WRONGSTACK_BASH_ENV_PASSTHROUGH=1`.
 - **`bash` POSIX process-group kill** with `SIGTERM → 800 ms → SIGKILL`. Runaway grandchildren can't survive the timeout.
 - **`fetch` SSRF defenses**: numeric CIDR checks for IPv4 (`10/8`, `127/8`, `169.254/16`, `100.64/10`, `224/4`, `240/4`, …) and 8-group-expanded IPv6 (including Node's compressed `::ffff:7f00:1` form for v4-mapped addresses). Redirect target re-validated on every hop. `http://` downgrade refused.
+- **`browser_*` isolation and SSRF defenses**: one context per agent/session, private-host and URL-credential rejection, guarded subrequests, disabled downloads, project-root-confined uploads, bounded/redacted evidence, and abort/run-disposal cleanup.
 - **`patch` diff-target validation**: every `+++` target post-strip is resolved against `projectRoot` before GNU patch sees the diff. `strip` clamped to `≥1`. Temp diff written to a `0700 mkdtemp` directory. Run with `LANG=C` / `LC_ALL=C`.
 - **`replace` / `grep` symlink-safe**: lstat + realpath + projectRoot revalidation; symlinks skipped, not followed.
 - **User-regex ReDoS guard** (`_regex.ts`): 512-char cap, nested-quantifier rejection (`(a+)+`, `(?:x+)*`), 64 KB subject-line cap. Applied to `grep`, `replace`, `logs`.

package/dist/_concurrency.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Bounded-concurrency async map.
+ *
+ * Runs `fn` over `items` with at most `limit` in-flight promises. Order of
+ * results matches input order. Errors reject the returned promise on the first
+ * failure — the remaining in-flight work is not awaited; this matches
+ * `Promise.all` semantics for callers that want fail-fast behavior.
+ *
+ * Lives here (rather than imported from `@wrongstack/bench`) because:
+ *   1. tools sits below bench in the dependency graph — bench is a consumer of
+ *      tools, never the other way around.
+ *   2. The semantics used by grep/glob are deliberately simple (fail-fast,
+ *      no cancellation, no progress) and don't need bench's richer options.
+ */
+export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]>;
+//# sourceMappingURL=_concurrency.d.ts.map

package/dist/_concurrency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_concurrency.d.ts","sourceRoot":"","sources":["../src/_concurrency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAC3C,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAC1B,OAAO,CAAC,CAAC,EAAE,CAAC,CAgBd"}

package/dist/_danger-detect.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Heuristic danger detection for `exec` tool commands.
+ *
+ * Layered on top of `BLOCKED_ARG_PATTERNS` (which is a hard-deny list for
+ * clear sandbox escapes) and `bash-kill-guard.ts` (which protects WrongStack
+ * itself from kill). This module assigns a danger level to a command/arg
+ * pair so the caller can decide whether to:
+ *
+ *   - 'safe'        → execute normally
+ *   - 'caution'     → execute and emit a warning line to the tool output
+ *   - 'destructive' → route through the existing confirm flow
+ *                     (`execTool.permission === 'confirm'`) instead of
+ *                     hard-deny, so the user can still proceed if intentional
+ *
+ * Design constraints:
+ *   - Deterministic: no randomness, no I/O, no time. Same input → same output.
+ *   - No LLM calls. Patterns are regex / exact-match.
+ *   - Per-rule `id` so config can override specific rules via
+ *     `tools.exec.danger.bypass`.
+ *   - Reasons are human-readable, joined with "; " for the confirm prompt.
+ *
+ * Caution rules are deliberately permissive — they execute and emit a
+ * warning rather than blocking. The rationale: many of these patterns
+ * (python -c, sudo) are part of legitimate dev workflows,
+ * so a hard deny would block too much. A warning gives the user a
+ * chance to notice "wait, I didn't mean to do that" without forcing
+ * them to add a config override for every script.
+ */
+export type DangerLevel = 'safe' | 'caution' | 'destructive';
+export interface DangerAssessment {
+    level: DangerLevel;
+    reasons: string[];
+    /** Stable id of the matched rule, for tests and config-override. */
+    matchedRule?: string;
+}
+/**
+ * Evaluate the danger level of a (cmd, args) pair.
+ *
+ * Returns 'safe' if no rule fires, otherwise the highest level among all
+ * matching rules. The 'matchedRule' field is the *last* rule that fired
+ * (stable, since rules are evaluated in declaration order).
+ *
+ * Optional `bypass` argument: a set of rule ids that should be SKIPPED
+ * even if they would otherwise match. Wired from
+ * `config.tools.exec.danger.bypass` (see `ExecDangerConfig` in
+ * `@wrongstack/core/src/types/config.ts`). Unknown ids are silently
+ * ignored — forward-compat: a rule added in a future version can be
+ * referenced before the user upgrades their config schema.
+ *
+ * This function is the single source of truth for danger classification;
+ * it is pure (no side effects) and unit-tested in `danger-detect.test.ts`.
+ */
+export declare function detectDanger(cmd: string, args: readonly string[], bypass?: ReadonlySet<string>): DangerAssessment;
+//# sourceMappingURL=_danger-detect.d.ts.map

package/dist/_danger-detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_danger-detect.d.ts","sourceRoot":"","sources":["../src/_danger-detect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,aAAa,CAAC;AAE7D,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA2TD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAC3B,gBAAgB,CAqBlB"}

package/dist/_edit-match.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Matching ladder for the `edit` tool.
+ *
+ * Models routinely hallucinate whitespace when reproducing code they read
+ * many turns ago: trailing spaces appear, indentation shifts by a level,
+ * tabs become spaces. A strict exact-match `old_string` fails on all of
+ * these even though the intended target is unambiguous. This module
+ * implements a graded fallback chain — each tier is strictly more permissive
+ * and strictly lower-confidence than the previous one:
+ *
+ *   1. `exact`                  — substring match (the classic behavior).
+ *   2. `trailing-whitespace`    — whole-line window match ignoring trailing
+ *                                 whitespace per line. Zero ambiguity risk
+ *                                 beyond exact (trailing blanks never carry
+ *                                 meaning in the languages we edit).
+ *   3. `whitespace-normalized`  — whole-line window match ignoring leading
+ *                                 AND trailing whitespace per line. The
+ *                                 replacement is re-indented to the file's
+ *                                 actual indentation.
+ *   4. `fuzzy`                  — block-anchor match: first and last lines
+ *                                 must match (trimmed), interior lines are
+ *                                 compared by Levenshtein similarity. Only a
+ *                                 single candidate with a clear margin over
+ *                                 the runner-up is accepted.
+ *
+ * The caller (edit.ts) enforces per-tier uniqueness, restricts `replace_all`
+ * to tiers 1–2, and surfaces the tier + confidence in the tool output so the
+ * model and the session log both see when a fallback fired.
+ */
+export type MatchTier = 'exact' | 'trailing-whitespace' | 'whitespace-normalized' | 'fuzzy';
+export interface LadderMatch {
+    /** Char offset (inclusive) of the match start in the LF-normalized file. */
+    start: number;
+    /** Char offset (exclusive) of the match end. */
+    end: number;
+    /** 1-based line number of the first matched line (for error messages). */
+    startLine: number;
+}
+export interface LadderResult {
+    tier: MatchTier;
+    matches: LadderMatch[];
+    /** Similarity score of the best candidate — only set for the fuzzy tier. */
+    score?: number | undefined;
+    /**
+     * Fuzzy tier only: true when two candidates scored within the ambiguity
+     * margin of each other, so no single target can be trusted. `matches`
+     * then contains the rival candidates for the error message.
+     */
+    ambiguous?: boolean | undefined;
+}
+/** Human-readable label per tier, used in notes and error messages. */
+export declare const TIER_LABEL: Record<MatchTier, string>;
+/** Confidence per tier, recorded in the tool output note. */
+export declare const TIER_CONFIDENCE: Record<MatchTier, 'exact' | 'high' | 'medium' | 'low'>;
+/**
+ * Walk the ladder and return the first tier that produces at least one
+ * match. Returns `undefined` when no tier matches.
+ */
+export declare function findLadderMatches(fileLf: string, oldLf: string): LadderResult | undefined;
+/** Normalized similarity in [0, 1]: 1 − levenshtein / max-length. */
+export declare function similarity(a: string, b: string): number;
+/** Leading whitespace (spaces/tabs) of the first non-empty line, or ''. */
+export declare function firstLineIndent(text: string): string;
+/**
+ * Shift `newLf` from the needle's indentation to the matched block's actual
+ * indentation. Only clean prefix relationships are adjusted (purely adding
+ * or removing leading whitespace); a tabs-vs-spaces mismatch is left alone
+ * rather than guessed at — the diff in the tool output makes the result
+ * visible either way.
+ */
+export declare function adjustIndent(newLf: string, fromIndent: string, toIndent: string): {
+    text: string;
+    adjusted: boolean;
+};
+/**
+ * Best-effort locator for the no-match error: find the window whose trimmed
+ * lines are most similar to the needle (cheap common-prefix scoring — this
+ * runs on the failure path where the needle by definition doesn't match, so
+ * precision matters less than never being slow). Returns the 1-based line
+ * and a short snippet the model can use to correct itself without re-reading.
+ */
+export declare function nearestMatchHint(fileLf: string, oldLf: string): {
+    line: number;
+    snippet: string;
+} | undefined;
+//# sourceMappingURL=_edit-match.d.ts.map

package/dist/_edit-match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_edit-match.d.ts","sourceRoot":"","sources":["../src/_edit-match.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,qBAAqB,GAAG,uBAAuB,GAAG,OAAO,CAAC;AAE5F,MAAM,WAAW,WAAW;IAC1B,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACjC;AAED,uEAAuE;AACvE,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAMhD,CAAC;AAEF,6DAA6D;AAC7D,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAKlF,CAAC;AAYF;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CA+BzF;AA6GD,qEAAqE;AACrE,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAUvD;AAyBD,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMpD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAkBrC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CA0B/C"}

package/dist/_env.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Re-exported from @wrongstack/core. This file exists for backward
+ * compatibility — tools/src/bash.ts and exec.ts import './_env.js'.
+ */
+export { buildChildEnv } from '@wrongstack/core';
+//# sourceMappingURL=_env.d.ts.map

package/dist/_env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_env.d.ts","sourceRoot":"","sources":["../src/_env.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/_fetch-guard.d.ts

@@ -0,0 +1,31 @@
+export declare const ALLOW_PRIVATE: boolean;
+type LookupCallback = (err: NodeJS.ErrnoException | null, address?: string | Array<{
+    address: string | undefined;
+    family: number;
+}>, family?: number | undefined) => void;
+/**
+ * DNS lookup used by the undici dispatcher below. It performs the SINGLE name
+ * resolution that the TCP connection actually uses, and rejects if any
+ * resolved address is private/loopback/link-local. Because the connection
+ * reuses exactly this result, there is no DNS-rebinding TOCTOU window between
+ * the security check and the connect — closing the gap the old code documented
+ * (validate with one dns.lookup, then let fetch re-resolve independently).
+ * TLS still validates the certificate against the hostname (SNI is set by
+ * undici from the URL), so pinning the IP does not weaken cert checking.
+ */
+export declare function guardedLookup(hostname: string, options: {
+    all?: boolean | undefined;
+    family?: number | undefined;
+}, callback: LookupCallback): void;
+/**
+ * SSRF-guarded fetch with manual, per-hop-revalidated redirects, exported so
+ * other builtin tools (e.g. `search`) get the same protections instead of a
+ * weaker `redirect: 'follow'`. Every hop is re-checked against private/loopback
+ * ranges and the connection is pinned to the validated IP via the undici
+ * dispatcher (no DNS-rebinding TOCTOU). `headers` defaults to the plain `fetch`
+ * tool's; callers may override (e.g. a browser User-Agent for search engines).
+ */
+export declare function guardedFetch(url: string, maxRedirects: number, signal: AbortSignal, headers?: Record<string, string>): Promise<Response>;
+export declare function assertNotPrivate(hostname: string): Promise<void>;
+export {};
+//# sourceMappingURL=_fetch-guard.d.ts.map

package/dist/_fetch-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_fetch-guard.d.ts","sourceRoot":"","sources":["../src/_fetch-guard.ts"],"names":[],"mappings":"AAoBA,eAAO,MAAM,aAAa,SAAwD,CAAC;AAUnF,KAAK,cAAc,GAAG,CACpB,GAAG,EAAE,MAAM,CAAC,cAAc,GAAG,IAAI,EACjC,OAAO,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,EACzE,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,KACxB,IAAI,CAAC;AAEV;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;IAAE,GAAG,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,EACnE,QAAQ,EAAE,cAAc,GACvB,IAAI,CAsCN;AAwCD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,WAAW,EACnB,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAG7B,GACA,OAAO,CAAC,QAAQ,CAAC,CAuDnB;AAED,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoDtE"}

package/dist/_output-spool.d.ts

@@ -0,0 +1,38 @@
+/** Directory for spooled command output (under the wstack global root). */
+export declare function toolOutputDir(): string;
+/** Reset module state — test hook (per-process sweep memo + nothing else). */
+export declare function _resetOutputSpoolForTests(): void;
+export interface SpoolInfo {
+    /** Absolute path of the spool file. */
+    path: string;
+    /** Total bytes of output produced (including what reached the file). */
+    bytes: number;
+    /** Bytes dropped due to disk backpressure (0 in the normal case). */
+    droppedBytes: number;
+}
+export interface OutputSpool {
+    /** Feed every raw output chunk. Never throws. */
+    write(text: string): void;
+    /**
+     * Close the file (if one was opened) and return its info, or null when the
+     * output never exceeded the threshold. Idempotent.
+     */
+    finalize(): SpoolInfo | null;
+}
+export interface CreateOutputSpoolOptions {
+    /** Tool name used in the spool filename (sanitized). */
+    tool: string;
+    /**
+     * Output size at which the spool activates. Should match the tool's
+     * in-memory cap so files are only created for output the model can't
+     * already see in full. Default 32 KB.
+     */
+    thresholdBytes?: number | undefined;
+}
+/**
+ * Render the marker line appended to a capped tool result. Kept in one place
+ * so every command tool phrases it identically (and tests can match it).
+ */
+export declare function spoolNote(info: SpoolInfo): string;
+export declare function createOutputSpool(opts: CreateOutputSpoolOptions): OutputSpool;
+//# sourceMappingURL=_output-spool.d.ts.map

package/dist/_output-spool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_output-spool.d.ts","sourceRoot":"","sources":["../src/_output-spool.ts"],"names":[],"mappings":"AAmCA,2EAA2E;AAC3E,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,8EAA8E;AAC9E,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAwBD,MAAM,WAAW,SAAS;IACxB,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;OAGG;IACH,QAAQ,IAAI,SAAS,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,wBAAwB;IACvC,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAIjD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,wBAAwB,GAAG,WAAW,CA+E7E"}

package/dist/_redact-command.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns a display-safe copy of `cmd` with sensitive flag values replaced by [REDACTED].
+ * The original string is unchanged; this is pure and has no side effects.
+ */
+export declare function redactCommand(cmd: string): string;
+//# sourceMappingURL=_redact-command.d.ts.map

package/dist/_redact-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_redact-command.d.ts","sourceRoot":"","sources":["../src/_redact-command.ts"],"names":[],"mappings":"AAmBA;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAoBjD"}

package/dist/_regex.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Compile a user-supplied regex with conservative bounds against ReDoS.
+ *
+ * Node's regex engine (V8) is backtracking-based and cannot interrupt a
+ * synchronous match — a pattern like `(a+)+$` against a sufficiently long
+ * line will pin a worker for seconds. The executor's outer `timeoutMs` only
+ * fires between async boundaries, so a long regex eval inside a sync loop
+ * is uninterruptible.
+ *
+ * We can't fully prevent ReDoS without an alternative engine (re2-wasm), but
+ * we can sharply limit the blast radius:
+ *
+ *  1. Cap pattern length — practically all legitimate user patterns are
+ *     under 256 characters. A 4 KB pattern is almost certainly malicious
+ *     or a copy-paste accident.
+ *  2. Reject patterns containing the most obvious super-linear structures.
+ *     This is a coarse filter (false-positives are likely; we accept that
+ *     for hostile-input contexts).
+ *
+ * Callers should additionally bound the *subject* length (e.g. by capping
+ * line size before matching).
+ */
+export interface CompileResult {
+    ok: true;
+    regex: RegExp;
+}
+export interface CompileFail {
+    ok: false;
+    reason: string;
+}
+export declare function compileUserRegex(pattern: string, flags: string): CompileResult | CompileFail;
+/**
+ * Truncate a subject line to a safe length for synchronous regex eval.
+ * The cap is conservative; tools that need exact-line matching against very
+ * long lines should use ripgrep externally rather than the native walker.
+ */
+export declare const MAX_SUBJECT_LEN: number;
+export declare function capSubject(line: string): string;
+//# sourceMappingURL=_regex.d.ts.map

package/dist/_regex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_regex.d.ts","sourceRoot":"","sources":["../src/_regex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAkBH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,IAAI,CAAC;IACT,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,WAAW,CA2B5F;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,QAAY,CAAC;AAEzC,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C"}

package/dist/_session-shell.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Session-shell resolution for Windows.
+ *
+ * `pickShell` (`_shell-pick.ts`) decides the shell *per command* — it inspects
+ * each command string and routes PowerShell-looking work to PowerShell, else
+ * `cmd.exe`. That keeps individual commands working, but it means the shell the
+ * model is *told* about (the system-prompt Environment block) and the shell that
+ * actually runs a given command can disagree, and a plain command like
+ * `git status` silently lands in `cmd.exe` while `Get-ChildItem` lands in
+ * PowerShell. The model has no stable target to write syntax for.
+ *
+ * This module resolves ONE shell for the whole session and pins it via the
+ * `WRONGSTACK_SHELL` env var. Because `WRONGSTACK_SHELL` is already the top
+ * precedence in `pickShell`, pinning it makes every command route to the same
+ * shell with zero changes to `bash.ts` — and the system-prompt builder can read
+ * the same env var to tell the model exactly which shell + syntax to use.
+ *
+ * Resolution (Windows only — POSIX has no fixed session shell here; `bash.ts`
+ * routes through `/bin/bash -c` and honours an explicit `WRONGSTACK_SHELL` as a
+ * binary path):
+ *   1. A valid user-set `WRONGSTACK_SHELL` (cmd | powershell | pwsh) wins and is
+ *      left untouched.
+ *   2. Otherwise prefer `pwsh` (PowerShell 7+) when `pwsh.exe` is on PATH.
+ *   3. Otherwise `powershell` (Windows PowerShell 5.1).
+ *   4. Otherwise `cmd` (only when no PowerShell is installed — effectively never
+ *      on a real Windows box).
+ *
+ * @see {@link ../../docs/configuration.md#windows-shell-selection-wrongstackshell}
+ */
+import type { BashShell } from './_shell-pick.js';
+/**
+ * Map a raw `WRONGSTACK_SHELL` value (which may carry a `.exe` suffix or odd
+ * casing) to a canonical {@link BashShell}, or `undefined` when it is unset /
+ * not a known shell. Mirrors the override parsing in `pickShell`.
+ */
+export declare function normalizeShell(value: string | undefined): BashShell | undefined;
+export interface ResolveSessionShellDeps {
+    /**
+     * Returns true when `bin` (e.g. `'pwsh.exe'`) resolves on PATH. Injectable so
+     * the resolver is unit-testable off-Windows; defaults to `resolveWin32Command`
+     * (which itself short-circuits to "not found" when `process.platform` is not
+     * win32).
+     */
+    hasBinary?: ((bin: string) => boolean) | undefined;
+}
+/**
+ * Pure decision: which single shell should the session use on `platform`?
+ * Returns `undefined` on non-win32 (no fixed session shell). Does not mutate
+ * anything.
+ */
+export declare function resolveSessionShell(platform: NodeJS.Platform, env: {
+    get(key: string): string | undefined;
+}, deps?: ResolveSessionShellDeps): BashShell | undefined;
+export interface EnsureSessionShellOptions {
+    /** Env to read/mutate. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv | undefined;
+    /** Platform override (tests). Defaults to `process.platform`. */
+    platform?: NodeJS.Platform | undefined;
+    /** Binary-presence probe (tests). Forwarded to {@link resolveSessionShell}. */
+    hasBinary?: ((bin: string) => boolean) | undefined;
+}
+/**
+ * Resolve the session shell and pin it into `WRONGSTACK_SHELL` so the bash tool
+ * and the system-prompt builder agree on one stable value. Idempotent:
+ *
+ *   - non-win32 → no-op, returns `undefined`.
+ *   - a valid user-set `WRONGSTACK_SHELL` → returned as-is, env left untouched.
+ *   - otherwise → resolves, writes the canonical value into the env, returns it.
+ *
+ * Call this once at process boot, before the system-prompt builder is built.
+ */
+export declare function ensureSessionShell(opts?: EnsureSessionShellOptions): BashShell | undefined;
+//# sourceMappingURL=_session-shell.d.ts.map

package/dist/_session-shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_session-shell.d.ts","sourceRoot":"","sources":["../src/_session-shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAGlD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAM/E;AAED,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;CACpD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,CAAC,QAAQ,EACzB,GAAG,EAAE;IAAE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;CAAE,EAC7C,IAAI,GAAE,uBAA4B,GACjC,SAAS,GAAG,SAAS,CAYvB;AAED,MAAM,WAAW,yBAAyB;IACxC,qDAAqD;IACrD,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,SAAS,CAAC;IACpC,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,GAAG,SAAS,CAAC;IACvC,+EAA+E;IAC/E,SAAS,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;CACpD;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,yBAA8B,GAAG,SAAS,GAAG,SAAS,CAa9F"}

package/dist/_shell-pick.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Shell picker for the `bash` tool on Windows.
+ *
+ * Historically the bash tool always fell back to `cmd.exe` on Windows — a
+ * reasonable default for the small set of POSIX-style commands the tool was
+ * built around (`echo`, `dir`, `cd`, `set`, etc.). That breaks when the
+ * caller emits PowerShell-style commands (e.g. Codex on Windows routinely
+ * emits `Get-Content`, `Get-ChildItem`, `Set-Location`, …), which `cmd.exe`
+ * rejects with "'Get-Content' is not recognized as an internal or external
+ * command, operable program or batch file." This module decides — purely from
+ * the command string and a few well-known env vars — which shell should run
+ * the command. It returns a tagged value; bash.ts does the actual spawn.
+ *
+ * The picker never spawns anything itself, so it is safe to unit-test in
+ * isolation. Shell *resolution* (finding the actual binary on PATH) lives in
+ * `_win32-resolve.ts` and runs at spawn time.
+ * @see {@link ../../docs/configuration.md#windows-shell-selection-wrongstackshell} for user-facing documentation of the WRONGSTACK_SHELL env var and auto-detection behavior.
+ *
+ * Selection precedence (Windows only):
+ *   1. `WRONGSTACK_SHELL` env var, if it names a known shell (cmd | powershell
+ *      | pwsh). This is the override for users who want a fixed shell.
+ *   2. Auto-detect: if the command "looks like" PowerShell — i.e. uses cmdlet
+ *      verb-noun syntax, $-variables, subexpressions, here-strings, etc. —
+ *      route to PowerShell. Prefers `pwsh` (PowerShell 7+) and falls back to
+ *      `powershell` (Windows PowerShell 5.1) at spawn time.
+ *   3. Default: `cmd.exe` (preserves legacy behavior).
+ *
+ * On non-Windows the picker is a no-op — bash.ts already routes through
+ * `/bin/bash -c`. We return `'cmd'` as a sentinel value that means "the
+ * platform default"; bash.ts maps it to the right binary.
+ *
+ * See docs/configuration.md § "Windows shell selection (WRONGSTACK_SHELL)" for
+ * user-facing documentation of the env var and auto-detection behaviour.
+ */
+export type BashShell = 'cmd' | 'powershell' | 'pwsh';
+/** Sentinel returned on POSIX — bash.ts maps this to `/bin/bash -c`. */
+export declare const POSIX_DEFAULT: BashShell;
+export interface PickShellEnv {
+    /** Read-only env view. Tests pass `{ get: (k) => process.env[k] }`. */
+    get(key: string): string | undefined;
+}
+/**
+ * Decide which shell should execute `command` on `platform`. Pure function —
+ * no I/O, no side effects, no exceptions (invalid input returns the default).
+ */
+export declare function pickShell(platform: NodeJS.Platform, command: string, env: PickShellEnv): BashShell;
+/**
+ * Heuristic PowerShell detector. Conservative on purpose — false positives
+ * route `cmd.exe` work into PowerShell (different parsing rules, different
+ * exit-code semantics, sometimes very different stdout), which is more
+ * disruptive than a single "command not recognized" error. We only return
+ * true for patterns that are unambiguously PowerShell.
+ *
+ * Detected patterns:
+ *   - cmdlet verb-noun syntax (`Get-`, `Set-`, `New-`, `Remove-`, `Add-`,
+ *     `Clear-`, `Copy-`, `Move-`, `Rename-`, `Test-`, `Update-`, `Write-`,
+ *     `Read-`, `Push-`, `Pop-`, `Invoke-`, `Start-`, `Stop-`, `Wait-`,
+ *     `Out-`, `Format-`, `Group-`, `Measure-`, `Compare-`, `Resolve-`,
+ *     `ConvertTo-`, `ConvertFrom-`, `Import-`, `Export-`, `Select-`,
+ *     `Where-`, `ForEach-`, `Sort-`, `Tee-`, `Split-`, `Join-`, `Limit-`,
+ *     `Skip-`, `Step-`, `Trace-`, `Debug-`, `Register-`, `Unregister-`,
+ *     `Enable-`, `Disable-`, `Restart-`, `Suspend-`, `Resume-`, `Save-`,
+ *     `Open-`, `Close-`, `Lock-`, `Unlock-`, `Mount-`, `Dismount-`,
+ *     `Enter-`, `Exit-`, `Use-`, `Show-`, `Hide-`, `Find-`, `Search-`,
+ *     `Watch-`, `Initialize-`, `Optimize-`, `Compress-`, `Expand-`,
+ *     `Convert-`, `Merge-`, `Checkpoint-`, `Undo-`, `Redo-`, `Approve-`,
+ *     `Deny-`, `Block-`, `Grant-`, `Revoke-`, `Assert-`, `Confirm-`,
+ *     `Resolve-`, `Wait-`, `Receive-`, `Send-`, `Connect-`, `Disconnect-`,
+ *     `Read-`, `Write-`).
+ *   - $-prefixed variables (`$env:`, `$foo`, `$script:bar`, `$_`).
+ *   - Subexpressions (`$(...)`).
+ *   - Here-strings (`@"…"@`, `@'…'@`).
+ *   - Splatting (`@(...)` at start of argument, `@{}` hash table).
+ *   - PowerShell-comparison operators (`-eq`, `-ne`, `-lt`, `-gt`, `-le`,
+ *     `-ge`, `-like`, `-notlike`, `-match`, `-notmatch`, `-contains`,
+ *     `-in`, `-and`, `-or`, `-not`, `-band`, `-bor`, `-bxor`,
+ *     `-replace`, `-split`, `-join`, `-is`, `-as`, `-f`).
+ *   - `.ps1` extension mentioned in the command.
+ *   - `&` call operator followed by a `$`-variable (`& $cmd ...`).
+ *   - Common PowerShell aliases that don't exist in cmd.exe: `gci`, `gi`,
+ *     `gp`, `sl`, `cd` is ambiguous (cmd.exe has `cd` too — skip), `ls`
+ *     ambiguous (cmd.exe does NOT have `ls`), `cat`, `cp`, `mv`, `rm`,
+ *     `echo` (echo is in cmd too), `gcm`, `gci`, `gps`, `ps`, `select`,
+ *     `where`, `?`, `%`.
+ *   - `#requires` directive at start of script.
+ *   - `param()` block at start of script.
+ *
+ *    The Windows-style path `C:\` alone is not a PowerShell tell — both
+ *    shells accept it. We only flip on PS-specific syntax.
+ *
+ * The function is case-insensitive and tolerates leading whitespace.
+ */
+export declare function looksLikePowerShell(command: string): boolean;
+/**
+ * Extended PowerShell detection — patterns that are unambiguous but less
+ * common than the verb-noun cmdlets caught by the first pass.
+ *
+ * Covers: -WhatIf / -Confirm / -ErrorAction flags, trailing `2>&1` in
+ * combination with other PS signals, `[type]` casts, Where/ForEach/
+ * Select-Object pipeline, PS comment blocks, Write-* output cmdlets,
+ * registry paths (HKLM:/HKCU:), -AsPlainText, -PipelineVariable.
+ */
+export declare function looksLikePowerShellExtended(command: string): boolean;
+/**
+ * Wrap a user command for execution via `pwsh -Command -` (stdin pipe).
+ *
+ * The wrapper addresses four reliability gaps in Windows PowerShell:
+ *
+ * 1. **Console output encoding**: PS 5.1 outputs in the system codepage
+ *    (often Windows-1252) which mojibakes non-ASCII. Setting
+ *    `[Console]::OutputEncoding = [System.Text.Encoding]::UTF8` at the
+ *    top of the script ensures UTF-8 output in both editions.
+ *
+ * 2. **Exit-code propagation**: Native commands (dotnet, npm, node, etc.)
+ *    set `$LASTEXITCODE`. Without explicit propagation, `pwsh -Command -`
+ *    exits 0 even when the native command failed. Running the command body
+ *    and then exiting with `$LASTEXITCODE` when it is numeric preserves native
+ *    exit codes without swallowing PowerShell output.
+ *
+ * 3. **Confirmation suppression**: `$ConfirmPreference='None'` suppresses
+ *    interactive confirmation prompts (e.g. `-Confirm` cmdlets) so scripts
+ *    don't block waiting for user input. `$WhatIfPreference=$false` ensures
+ *    commands actually RUN (not just print what they would do).
+ *
+ * Do not prefix the stdin script with a UTF-8 BOM. Some PowerShell builds do
+ * not strip it when reading `-Command -` and treat it as part of the first
+ * command name (`\uFEFF[Console]::OutputEncoding`), causing every wrapped
+ * command to fail before the user's script runs.
+ */
+export declare function wrapPowerShellScript(command: string): string;
+/**
+ * Return the argv prefix for a given shell. The bash tool passes a single
+ * command string and expects the shell to interpret it. cmd.exe uses
+ * `/c <cmd>`; PowerShell uses `-NoLogo -NoProfile -NonInteractive -Command -`
+ * and reads the script from stdin (the `-` at the end is the documented way
+ * to tell PowerShell "the script is on stdin, not as an argument"). Stdin
+ * pipe sidesteps the entire class of quoting bugs that arise from
+ * interpolating multi-line / single-quoted / dollar-sign-laden scripts into
+ * a `-Command "..."` string.
+ */
+export declare function shellArgs(shell: BashShell): string[];
+/**
+ * Post-failure diagnosis: when a Windows shell command exits non-zero, scan it
+ * for bash/POSIX idioms the shell does not accept and return a short, targeted
+ * hint (with the right replacement) so the model self-corrects on the next turn.
+ *
+ * Deliberately **failure-coupled** — the bash tool only calls this on a
+ * non-zero exit. That keeps it noise-free (PowerShell aliases `ls`/`cat`/`rm`
+ * succeed, so they never reach here) and side-steps shell-version nuance: `&&`
+ * works in PowerShell 7 and cmd.exe (so those commands succeed and are never
+ * flagged) but breaks in Windows PowerShell 5.1 (where the command fails and is
+ * flagged). Never mutates or blocks — advisory only.
+ *
+ * Returns `undefined` when nothing actionable is found (including any POSIX
+ * call — bash idioms are correct there).
+ */
+export declare function diagnoseBashism(command: string, shell: BashShell): string | undefined;
+//# sourceMappingURL=_shell-pick.d.ts.map

package/dist/_shell-pick.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_shell-pick.d.ts","sourceRoot":"","sources":["../src/_shell-pick.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,YAAY,GAAG,MAAM,CAAC;AAEtD,wEAAwE;AACxE,eAAO,MAAM,aAAa,EAAE,SAAiB,CAAC;AAE9C,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACtC;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ,EACzB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,YAAY,GAChB,SAAS,CAgBX;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CA2D5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAuCpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAU5D;AAyCD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,EAAE,CAKpD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAgDrF"}

package/dist/_spawn-stream.d.ts

@@ -0,0 +1,32 @@
+import type { ToolProgressEvent } from '@wrongstack/core';
+export interface SpawnStreamResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    truncated: boolean;
+    error?: string | undefined;
+    /** When the output exceeded maxBytes, the FULL output was spooled here. */
+    spoolPath?: string | undefined;
+    /** Total output bytes produced (only set when spooled). */
+    spoolBytes?: number | undefined;
+}
+export interface SpawnStreamOptions {
+    cmd: string;
+    args: string[];
+    cwd: string;
+    signal: AbortSignal;
+    maxBytes?: number | undefined;
+    /** Bytes of new stdout/stderr to accumulate before yielding a `partial_output` event. */
+    flushBytes?: number | undefined;
+    /** Maximum chunks to buffer before applying backpressure to the child. Default 500. */
+    maxQueueSize?: number | undefined;
+}
+/**
+ * Spawn a child process and yield `partial_output` progress events as
+ * stdout/stderr arrive (batched by byte threshold), then return the full
+ * buffered result. Shared between install/lint/format/typecheck/test/audit
+ * so the TUI live tail sees consistent progress regardless of which tool
+ * is running.
+ */
+export declare function spawnStream(opts: SpawnStreamOptions): AsyncGenerator<ToolProgressEvent, SpawnStreamResult>;
+//# sourceMappingURL=_spawn-stream.d.ts.map

package/dist/_spawn-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_spawn-stream.d.ts","sourceRoot":"","sources":["../src/_spawn-stream.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAS1D,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,WAAW,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,yFAAyF;IACzF,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,uFAAuF;IACvF,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED;;;;;;GAMG;AACH,wBAAuB,WAAW,CAChC,IAAI,EAAE,kBAAkB,GACvB,cAAc,CAAC,iBAAiB,EAAE,iBAAiB,CAAC,CAuNtD"}