terramend 0.2.0

package/dist/utils/rangeDiff.d.ts

@@ -0,0 +1,51 @@
+type ComputeIncrementalDiffParams = {
+    baseBranch: string;
+    beforeSha: string;
+    headSha: string;
+};
+/**
+ * computes the incremental diff between two versions of a PR using range-diff
+ * on virtual squash commits created via `git commit-tree`.
+ *
+ * each PR version is squashed into a single synthetic commit (merge-base → tip tree),
+ * then range-diff compares those two single-commit ranges. this:
+ * - isolates each version's net effect (base branch noise eliminated via per-version merge bases)
+ * - avoids commit-matching issues that raw range-diff has with rebases/squashes/reordering
+ * - creates only loose git objects, no branches or refs (unlike temp-branch squash approaches)
+ *
+ * unlike fetchAndFormatPrDiff/formatFilesWithLineNumbers, this output has no line numbers.
+ * range-diff compares *patches* (diffs-of-diffs), not file trees — its hunk headers are
+ * `@@ file.ts` breadcrumbs, not positional `@@ -X,Y +A,B @@` markers. reconstructing
+ * line numbers would require cross-referencing with the v2 diff or content-matching against
+ * file trees, both of which are fragile (duplicate lines, hunk boundary shifts after rebase).
+ * a structured interdiff approach (diff two parsed patches, compare only +/- keys via Myers)
+ * could approximate line numbers but loses semantic precision: range-diff understands patch
+ * structure natively (rename detection, hunk-aware matching, dual-prefix inner/outer changes),
+ * while flat key-sequence comparison can misalign duplicate lines and can't distinguish
+ * "new addition to the PR" from "existing code newly modified by the PR". range-diff is the
+ * right abstraction here — the incremental diff answers "how did the changeset evolve?",
+ * not "where in the file is this?", and forcing positional line numbers onto it would be
+ * semantically misleading.
+ *
+ * alternatives considered:
+ * - plain git diff (two-tree or three-dot): includes base branch changes, no PR isolation
+ * - patch-text diffing (interdiff / diff-of-diffs): fragile, hunk offset noise on rebase
+ * - range-diff on raw commit ranges: confused by commit reorganization across force-pushes
+ */
+export declare function computeIncrementalDiff(params: ComputeIncrementalDiffParams): string | null;
+/**
+ * transforms git range-diff output into a clean incremental diff.
+ *
+ * range-diff content lines have two prefix characters:
+ *   1st (outer): range-diff level — space (same in both), + (new only), - (old only)
+ *   2nd (inner): original diff level — space (context), + (added), - (removed)
+ *
+ * stripping the inner prefix produces a standard unified-diff-like output where
+ * +/- means "changed between PR versions" rather than "changed vs base branch".
+ *
+ * uses a streaming approach: a ring buffer of before-context lines is flushed when
+ * a change is hit, then afterCount lines of after-context are emitted directly.
+ * nearest preceding ## / @@ headers are force-included when outside the context window.
+ */
+export declare function postProcessRangeDiff(raw: string, contextLines?: number): string | null;
+export {};

package/dist/utils/remediationCommand.d.ts

@@ -0,0 +1,55 @@
+/**
+ * §3.12 Comment-command interface. A developer can scope a remediation run from
+ * a PR/issue comment that mentions the bot:
+ *
+ *   @terramend fix #3a9f1c2          → fix exactly one concern (by id or short id)
+ *   @terramend fix all high-severity → fix every concern at/above a severity
+ *   @terramend fix all               → fix everything (still bounded by max_prs)
+ *   @terramend fix main.tf           → fix one file's group
+ *
+ * §26 Propose, then let me steer — when a non-trivial finding has several
+ * genuinely distinct valid fixes, Remediate proposes 2–3 labelled strategies in
+ * a comment instead of guessing, and the reviewer picks one by replying:
+ *
+ *   @terramend fix #3a9f1c2 with strategy B   → apply strategy B to that concern
+ *   @terramend strategy 2                      → pick strategy 2 (concern from the thread)
+ *
+ * The parsing is pure + deterministic so the scoping doesn't depend on the
+ * model's reading of the comment. The Remediate mode applies the parsed scope
+ * (which group(s) to act on, and which strategy) instead of the default
+ * "highest-severity group, agent's-choice fix".
+ */
+export type RemediationCommand = {
+    kind: "concern";
+    concernRef: string;
+    strategy?: string;
+} | {
+    kind: "severity";
+    severity: Severity;
+} | {
+    kind: "file";
+    file: string;
+} | {
+    kind: "strategy";
+    strategy: string;
+} | {
+    kind: "all";
+};
+declare const SEVERITIES: readonly ["critical", "high", "medium", "low", "info"];
+type Severity = (typeof SEVERITIES)[number];
+/**
+ * §26 — the canonical phrasing the proposal comment must tell reviewers to reply
+ * with. Lives next to the parser that accepts it so the proposal template (in
+ * the Remediate prompt) and the parser can never drift apart. `<concern-id>` and
+ * `<A|B|C>` are placeholders the agent fills with the real id and the offered
+ * strategy labels.
+ */
+export declare const STRATEGY_REPLY_HINT = "@terramend fix #<concern-id> with strategy <A|B|C>";
+/**
+ * Parse a `@terramend fix …` command out of a comment body. Returns null when
+ * the body isn't a recognised fix command (the run then falls back to its
+ * default scope). Tolerant of surrounding prose — it scans for the mention then
+ * the `fix` verb and its argument.
+ */
+export declare function parseRemediationCommand(body: string | undefined): RemediationCommand | null;
+export {};

package/dist/utils/retry.d.ts

@@ -0,0 +1,13 @@
+export type RetryOptions = {
+    maxAttempts?: number;
+    delayMs?: number;
+    /**
+     * explicit delay schedule — one entry per retry (length N ⇒ N+1 attempts).
+     * when set, overrides `maxAttempts` and `delayMs`. e.g. `[1_000, 3_000]`
+     * means up to 3 attempts, sleeping 1s before retry 2 and 3s before retry 3.
+     */
+    delaysMs?: readonly number[];
+    shouldRetry?: (error: unknown) => boolean;
+    label?: string;
+};
+export declare function retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;

package/dist/utils/reviewCleanup.d.ts

@@ -0,0 +1,14 @@
+import type { ToolContext } from "#app/mcp/server";
+/**
+ * post-agent review lifecycle: runs after the agent exits (success or timeout).
+ *
+ * normally the agent handles new commits inline: create_pull_request_review
+ * detects HEAD movement and tells the agent to pull and review the delta.
+ * this dispatch is a safety net for cases where the agent couldn't handle
+ * it (timeout, error, etc).
+ *
+ * ordering matters: reportReviewNodeId marks this run "done" FIRST so push
+ * webhooks stop being suppressed by dedup. the HEAD check runs SECOND to
+ * catch any pushes that were suppressed while this run was in-flight.
+ */
+export declare function postReviewCleanup(ctx: ToolContext): Promise<void>;

package/dist/utils/run.d.ts

@@ -0,0 +1,9 @@
+import type { AgentResult } from "#app/agents/shared";
+import type { MainResult } from "#app/main";
+import type { ToolContext } from "#app/mcp/server";
+export interface HandleAgentResultParams {
+    result: AgentResult;
+    toolContext: ToolContext;
+    silent: boolean | undefined;
+}
+export declare function handleAgentResult(ctx: HandleAgentResultParams): Promise<MainResult>;

package/dist/utils/runContext.d.ts

@@ -0,0 +1,60 @@
+import type { PushPermission, ShellPermission } from "#app/external";
+import type { RepoContext } from "#app/utils/github";
+export interface Mode {
+    id: string;
+    name: string;
+    description: string;
+    prompt: string;
+}
+/**
+ * server-parsed TOC entry for `Repo.learnings`. depth is 1-6 (h1-h6),
+ * line numbers are 1-indexed against the raw body. computed by
+ * `parseLearningsHeadings` in `utils/learningsToc.ts` (server side) and
+ * shipped over the run-context JSON boundary; the canonical declaration
+ * lives there. duplicated here because the action runtime can't reach
+ * across into the proprietary root-level codebase, and the JSON wire
+ * means typecheck can't enforce shape equality across both sides.
+ */
+export interface LearningsHeading {
+    depth: 1 | 2 | 3 | 4 | 5 | 6;
+    title: string;
+    startLine: number;
+    endLine: number;
+}
+export interface RepoSettings {
+    model: string | null;
+    modes: Mode[];
+    setupScript: string | null;
+    postCheckoutScript: string | null;
+    prepushScript: string | null;
+    stopScript: string | null;
+    push: PushPermission;
+    shell: ShellPermission;
+    prApproveEnabled: boolean;
+    modeInstructions: Record<string, string>;
+    learnings: string | null;
+    learningsHeadings: LearningsHeading[];
+    envAllowlist: string | null;
+}
+/**
+ * Account-level billing plan. Orthogonal to repo-level OSS status. Mirrors
+ * the server's `AccountPlan` in `utils/billing.ts`. `"none"` = free tier,
+ * `"payg"` = card on file / pay-as-you-go.
+ */
+export type AccountPlan = "none" | "payg";
+export interface RunContext {
+    settings: RepoSettings;
+    apiToken: string;
+    oss: boolean;
+    plan: AccountPlan;
+}
+/**
+ * fetch run context from Terramend API
+ * returns settings + API token for subsequent calls
+ * returns defaults if fetch fails
+ */
+export declare function fetchRunContext(params: {
+    token: string;
+    repoContext: RepoContext;
+    oidcToken?: string | undefined;
+}): Promise<RunContext>;

package/dist/utils/runContextData.d.ts

@@ -0,0 +1,23 @@
+import type { Octokit } from "@octokit/rest";
+import { type OctokitWithPlugins } from "#app/utils/github";
+import { type AccountPlan, type RepoSettings } from "#app/utils/runContext";
+export interface RunContextData {
+    repo: {
+        owner: string;
+        name: string;
+        data: Awaited<ReturnType<Octokit["repos"]["get"]>>["data"];
+    };
+    repoSettings: RepoSettings;
+    apiToken: string;
+    oss: boolean;
+    plan: AccountPlan;
+}
+interface ResolveRunContextDataParams {
+    octokit: OctokitWithPlugins;
+    token: string;
+}
+/**
+ * initialize run context data: parse context, fetch repo info and settings
+ */
+export declare function resolveRunContextData(params: ResolveRunContextDataParams): Promise<RunContextData>;
+export {};

package/dist/utils/runErrorRenderer.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Classify + render the error thrown out of the main run try-block into a
+ * pair of user-facing markdown bodies — one for the GitHub Actions job
+ * summary tab, one for the PR progress comment.
+ *
+ * Classifications, in dispatch order (first match wins; the api-key
+ * branch additionally folds in the activity-timeout hang body as a
+ * sub-source so a hang masking an api-key error still surfaces the api-key
+ * CTA):
+ *
+ *   1. `BillingError` — either the proxy-token mint already threw one (402
+ *      handled inline) or the agent runtime surfaced an OpenRouter
+ *      "key budget exhausted" string mid-run. Both render via
+ *      `formatBillingErrorSummary` so the user sees actionable copy.
+ *
+ *   2. BYOK provider billing-exhausted (#835) — DeepSeek "Insufficient
+ *      Balance", Anthropic "credit balance is too low", OpenCode Zen
+ *      `CreditsError`, Gemini "spending cap". Checked before api-key auth
+ *      because billing-exhausted responses often carry 401 status codes
+ *      that `isApiKeyAuthError` would otherwise mis-classify.
+ *
+ *   3. API-key auth error — `isApiKeyAuthError` sniffs the raw error string
+ *      (or the activity-timeout hang body when present, since that's where
+ *      the underlying provider error often lands); `formatApiKeyErrorSummary`
+ *      renders provider + console-link copy.
+ *
+ *   4. ProviderModelNotFoundError — stale free-fallback model id no longer
+ *      in the OpenCode catalog; renders a nudge to add a BYOK key.
+ *
+ *   5. Activity-timeout hang — `errorMessage` starts with
+ *      `"activity timeout"` or `"agent still pending"` AND none of the
+ *      above matched. The harness keeps structured diagnostic state on
+ *      `toolState.agentDiagnostic`; `formatAgentHangBody` renders that into
+ *      the job summary. The PR comment instead collapses to a one-line
+ *      `**Run failed.** [View the logs →]` — the watchdog jargon, event
+ *      counts, and benign stderr tail are operator-grade detail that only
+ *      alarm the average user. The one exception is a hang masking billing
+ *      exhaustion (#778), where `formatAgentHangBody` emits an actionable
+ *      top-up CTA that the comment keeps verbatim.
+ *
+ *   6. Default — the job summary gets a plain-English lead sentence plus the
+ *      raw error in a fenced code block under the `### ❌ Terramend failed`
+ *      banner; the PR comment collapses to the same one-line logs link as
+ *      the hang case, since the raw internal string helps nobody on the PR.
+ *
+ * Net: the actionable classifications (billing, API-key, model-not-found)
+ * render identical bodies on both surfaces; the non-actionable ones (hang,
+ * generic) keep the forensics in the Actions job summary and show a calm
+ * one-liner in the PR comment, whose footer already carries Terramend
+ * branding + rerun links.
+ */
+import type { AgentDiagnostic } from "#app/utils/agentHangReport";
+export type RenderedRunError = {
+    summary: string;
+    comment: string;
+};
+export declare function renderRunError(input: {
+    errorMessage: string;
+    repo: {
+        owner: string;
+        name: string;
+    };
+    agentDiagnostic: AgentDiagnostic | undefined;
+}): RenderedRunError;

package/dist/utils/runLifecycle.d.ts

@@ -0,0 +1,86 @@
+/**
+ * End-of-run cleanup phases extracted out of `main.ts`. Three shapes:
+ *
+ *   - `persistRunArtifacts`: best-effort post-review cleanup + summary +
+ *     learnings persistence. Shared by both the success path and the
+ *     error-catch path; idempotent (each step has its own guard against
+ *     double-execution).
+ *
+ *   - `finalizeSuccessRun`: success-only — calls `persistRunArtifacts`
+ *     first, then surfaces harness-side failures in the progress comment,
+ *     deletes stranded progress comments, writes the GitHub Actions job
+ *     summary, and emits the structured output marker.
+ *
+ *   - `writeRunErrorOutputs`: error-only — writes the rendered error
+ *     summary to the Actions summary tab and mirrors it to the PR
+ *     progress comment. The catch path calls this and then
+ *     `persistRunArtifacts` separately so the rendered error lands before
+ *     the persistence calls, in case the latter throw.
+ *
+ * All three swallow their own non-fatal errors (`log.debug` or empty
+ * `catch {}`) so a cleanup failure can't flip an already-decided run
+ * outcome.
+ */
+import type { AgentResult } from "#app/agents/shared";
+import type { ToolContext } from "#app/mcp/server";
+import type { ToolState } from "#app/toolState";
+import { type RenderedRunError } from "#app/utils/runErrorRenderer";
+/**
+ * Best-effort cleanup shared by both run-end paths:
+ *   1. post-review cleanup (dispatch follow-up re-review on submitted reviews)
+ *   2. persist the agent-edited PR summary tmpfile
+ *   3. persist the agent-edited repo-level learnings tmpfile
+ *
+ * Each step is idempotent and swallows its own errors. Safe to call from
+ * both `main()`'s success path and its catch path.
+ */
+export declare function persistRunArtifacts(toolContext: ToolContext): Promise<void>;
+/**
+ * Run the success-path cleanup waterfall:
+ *
+ *   1. shared best-effort cleanup via `persistRunArtifacts`
+ *   2. when the harness returned `success=false` (e.g. unsubmitted-review
+ *      gate exhausted retries, stop-hook persistently failing), render via
+ *      `renderRunError` and surface the error in BOTH the progress comment
+ *      (rendered.comment) and the Actions job summary (rendered.summary,
+ *      prepended below in step 4) — same classifier as the catch path so
+ *      the user sees it instead of a deleted-comment void / empty summary
+ *      tab
+ *   3. when the run succeeded, some write landed (`wasUpdated`), but the
+ *      progress comment was never finalized via `report_progress`, delete
+ *      the stranded comment (abandoned checklist, or a substantive artifact
+ *      written via another MCP write tool that skipped report_progress). a
+ *      run where NO write landed keeps its comment for handleAgentResult to
+ *      salvage into — see the `wasUpdated` guard below and #868
+ *   4. write the GitHub Actions step summary (best-effort — a write
+ *      failure must not throw past this point because we'd hit the outer
+ *      catch and clobber any progress comment we just wrote)
+ *   5. emit the structured output marker for tests + workflow consumers
+ */
+export declare function finalizeSuccessRun(input: {
+    toolContext: ToolContext;
+    toolState: ToolState;
+    result: AgentResult;
+    repo: {
+        owner: string;
+        name: string;
+    };
+}): Promise<void>;
+/**
+ * Write the rendered error to the GitHub Actions job summary tab + mirror
+ * to the PR progress comment when one exists. Catch path only.
+ *
+ * `lastProgressBody` and the usage table are appended to the summary so the
+ * partial work the agent did before failing isn't lost.
+ *
+ * `createIfMissing: true` is symmetric with `finalizeSuccessRun` — silent
+ * triggers (IncrementalReview / pull_request_synchronize / auto-label) that
+ * throw past `finalizeSuccessRun` (e.g. timeout race kills the agent
+ * mid-billing-exhausted-retry) reach this catch path with no progress
+ * comment to update, and without `createIfMissing` the terminal error
+ * lands only in the GH job summary that most users never open. see #835.
+ */
+export declare function writeRunErrorOutputs(input: {
+    rendered: RenderedRunError;
+    toolState: ToolState;
+}): Promise<void>;

package/dist/utils/runStartupLog.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Startup log formatting for the resolver pipeline. Computes the
+ * "model / agent / push / shell / timeout" block that main.ts prints
+ * after resolving the agent + model + payload.
+ */
+import type { ResolvedPayload } from "#app/utils/payload";
+/**
+ * Emit the startup block ("» model / agent / push / shell / timeout") after
+ * the agent and model are resolved. Single side-effect; no return.
+ */
+export declare function logRunStartup(ctx: {
+    payload: ResolvedPayload;
+    resolvedModel: string | undefined;
+    agentName: string;
+}): void;

package/dist/utils/secrets.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Secret detection and env filtering utilities
+ *
+ * subprocess env filtering: default-deny allowlist model.
+ * only vars in the safe set or user allowlist are passed to child processes.
+ *
+ * log redaction: SENSITIVE_PATTERNS are used to identify secret values
+ * for redaction in logs and GHA masking (independent of subprocess filtering).
+ */
+export declare const SENSITIVE_PATTERNS: RegExp[];
+export declare function isSensitiveEnvName(key: string): boolean;
+export declare function setEnvAllowlist(raw: string): void;
+/** filter env vars using default-deny allowlist: safe set + user allowlist */
+export declare function filterEnv(): Record<string, string>;
+export type EnvMode = "restricted" | "inherit" | Record<string, string>;
+/**
+ * resolve env mode to actual env object
+ * - "restricted" (default): filterEnv() — only safe set + user allowlist
+ * - "inherit": full process.env
+ * - object: custom env merged with restricted base
+ */
+export declare function resolveEnv(mode: EnvMode | undefined): Record<string, string | undefined>;

package/dist/utils/setup.d.ts

@@ -0,0 +1,90 @@
+import type { ShellPermission } from "#app/external";
+import type { ToolState } from "#app/toolState";
+import type { OctokitWithPlugins } from "#app/utils/github";
+export interface SetupOptions {
+    tempDir: string;
+}
+/**
+ * Create a shared temp directory for the action
+ */
+export declare function createTempDirectory(): string;
+/**
+ * snapshot-and-delete the GHA runner's known credential leak surfaces inside
+ * `$RUNNER_TEMP` before the agent spawns. without this, a shell-capable agent
+ * can grep:
+ *   - `_runner_file_commands/set_output_*` for `core.setOutput('token', ghs_…)`
+ *     calls made by earlier composite-action steps (e.g.
+ *     terramend/terramend/get-installation-token);
+ *   - `<uuid>.sh` rendered step scripts whose `run: |` body embeds
+ *     `${{ steps.token.outputs.token }}` literally (GHA expands BEFORE writing);
+ *   - `git-credentials-*.config` written by `actions/checkout@v6` for the
+ *     workflow GITHUB_TOKEN.
+ *
+ * the running bash process already has its own `.sh` open via fd, so the
+ * unlink is safe — `unlink` removes the dirent, the kernel keeps reading.
+ *
+ * preserves every `_runner_file_commands/` file path the runner pre-allocated
+ * for OUR step — `$GITHUB_OUTPUT`, `$GITHUB_ENV`, `$GITHUB_PATH`,
+ * `$GITHUB_STATE`, `$GITHUB_STEP_SUMMARY`. those are read by the runner
+ * AFTER we exit (or by our own `post:` hook), and wiping them would break
+ * terramend's `result` output, `post:` state handoff, and job summary.
+ *
+ * silent no-op when `$RUNNER_TEMP` is unset (local dev, `pnpm dev:run`).
+ * per-file errors are tolerated — the runner may delete files between
+ * our readdir and our unlink.
+ */
+export declare function wipeRunnerLeakSurface(): void;
+/**
+ * Setup the test repository for running actions
+ */
+export declare function setupTestRepo(options: SetupOptions): void;
+/**
+ * remove any `[includeIf ...]` entries from the local git config so that
+ * actions/checkout-persisted credentials don't ride alongside ASKPASS-provided
+ * auth for subsequent git operations.
+ *
+ * SECURITY: git config subsection values can contain arbitrary characters
+ * including `$(...)` command substitutions, and `${IFS}` spacing tricks defeat
+ * naive split-on-space filtering. we read keys via the `-z` (null-terminated)
+ * output format and feed them to a spawn-array `git config --unset-all` so
+ * the shell never interpolates key contents — closing the RCE path that a
+ * string-interpolated `execSync(...)` would expose.
+ */
+export declare function removeIncludeIfEntries(repoDir: string): void;
+export interface GitContext {
+    gitToken: string;
+    owner: string;
+    name: string;
+    octokit: OctokitWithPlugins;
+    toolState: ToolState;
+    shell: ShellPermission;
+    postCheckoutScript: string | null;
+}
+export type SetupGitParams = GitContext;
+/**
+ * setup git configuration and authentication for the repository.
+ * - configures git identity (user.email, user.name)
+ * - sets up authentication via gitToken (minimal contents:write)
+ *
+ * gitToken is a minimal-permission token (contents + workflows) used for git operations.
+ * it is assumed to be potentially exfiltratable, so it has limited scope.
+ */
+export declare function setupGit(params: SetupGitParams): Promise<void>;
+/**
+ * snapshot the current HEAD as either a branch name (when on a named branch)
+ * or a literal SHA (when detached). used by setupGit to pin the run-entry
+ * position and by checkout_pr to compare the live HEAD against it.
+ *
+ * splitting the two cases is load-bearing: `git rev-parse --abbrev-ref HEAD`
+ * returns the sentinel string `"HEAD"` on detached entry — which is the
+ * default `actions/checkout` state for `pull_request` events. storing that
+ * raw string would make any future detached state (including a subagent's
+ * `git checkout --detach <sha>`) compare equal.
+ */
+export declare function captureInitialHead(repoDir: string): {
+    kind: "branch";
+    name: string;
+} | {
+    kind: "detached";
+    sha: string;
+};

package/dist/utils/shell.d.ts

@@ -0,0 +1,32 @@
+import { type EnvMode } from "#app/utils/secrets";
+interface ShellOptions {
+    cwd?: string;
+    encoding?: "utf-8" | "utf8" | "ascii" | "base64" | "base64url" | "hex" | "latin1" | "ucs-2" | "ucs2" | "utf16le";
+    log?: boolean;
+    /**
+     * env mode: "restricted" (default) filters secrets, "inherit" passes full env,
+     * or provide a custom env object (merged with restricted base)
+     */
+    env?: EnvMode;
+    onError?: (result: {
+        status: number;
+        stdout: string;
+        stderr: string;
+    }) => void;
+}
+/**
+ * Execute a shell command safely using spawnSync with argument arrays.
+ * Prevents shell injection by avoiding string interpolation in shell commands.
+ *
+ * SECURITY: by default, env vars are filtered to remove secrets (tokens, keys, passwords).
+ * this prevents malicious code (git hooks, npm scripts, etc.) from exfiltrating credentials.
+ * use env: "inherit" only when absolutely necessary.
+ *
+ * @param cmd - The command to execute
+ * @param args - Array of arguments to pass to the command
+ * @param options - Optional configuration (cwd, encoding, onError)
+ * @returns The trimmed stdout output
+ * @throws Error if command fails and no onError handler is provided
+ */
+export declare function $(cmd: string, args: string[], options?: ShellOptions): string;
+export {};

package/dist/utils/skills.d.ts

@@ -0,0 +1,10 @@
+/**
+ * write all bundled skills into the fake HOME so OpenCode / Claude Code discover
+ * them via their auto-scan directories.
+ *
+ * called once per agent run from each agent's `run()`. cheap (small file
+ * writes), no network, idempotent.
+ */
+export declare function installBundledSkills(params: {
+    home: string;
+}): void;

package/dist/utils/subprocess.d.ts

@@ -0,0 +1,80 @@
+import { type ChildProcess } from "node:child_process";
+export type TrackChildOptions = {
+    child: ChildProcess;
+    killGroup?: boolean;
+};
+export declare const SPAWN_TIMEOUT_CODE = "E_SPAWN_TIMEOUT";
+export declare const SPAWN_ACTIVITY_TIMEOUT_CODE = "E_SPAWN_ACTIVITY_TIMEOUT";
+export declare class SpawnTimeoutError extends Error {
+    readonly code: typeof SPAWN_TIMEOUT_CODE | typeof SPAWN_ACTIVITY_TIMEOUT_CODE;
+    constructor(message: string, code: typeof SPAWN_TIMEOUT_CODE | typeof SPAWN_ACTIVITY_TIMEOUT_CODE);
+}
+export type SignalHandler = (signal: NodeJS.Signals) => void;
+export declare function trackChild(options: TrackChildOptions): void;
+export declare function untrackChild(child: ChildProcess): void;
+export declare function setSignalHandler(handler: SignalHandler | null): void;
+export declare function killTrackedChildren(): void;
+/**
+ * Controls what the wrapper retains in memory across the child's lifetime
+ * for the post-hoc `SpawnResult.stdout` / `SpawnResult.stderr` snapshots.
+ *
+ * Streaming callbacks (`onStdout` / `onStderr`) fire regardless — `retain`
+ * only governs the buffered snapshot returned in `SpawnResult`.
+ *
+ * - `"tail"` (default): keep the last `maxRetainedBytes` UTF-16 code units
+ *   of each stream. Once the cap is exceeded, oldest bytes are sliced off
+ *   and the result is prefixed with a `... [N MiB truncated] ...` sentinel.
+ *   Right default for short-lived commands whose failure mode is in their
+ *   final output (git errors, install failures, hook scripts).
+ * - `"none"`: skip the buffer entirely. `SpawnResult.stdout` / `.stderr`
+ *   are empty strings. Use this for long-lived streaming agents that already
+ *   drain via `onStdout` / `onStderr` and never read the buffered snapshot.
+ *
+ * Default cap is 8 MiB — well below V8's ~1 GiB `kMaxLength` so `+= chunk`
+ * can never throw `RangeError: Invalid string length`.
+ */
+export type RetainMode = "tail" | "none";
+export declare const DEFAULT_MAX_RETAINED_BYTES: number;
+export interface SpawnOptions {
+    cmd: string;
+    args: string[];
+    env?: NodeJS.ProcessEnv;
+    input?: string;
+    timeout?: number;
+    activityTimeout?: number;
+    onActivityTimeout?: (() => void) | undefined;
+    cwd?: string;
+    stdio?: ("pipe" | "ignore" | "inherit")[];
+    onStdout?: (chunk: string) => void;
+    onStderr?: (chunk: string) => void;
+    killGroup?: boolean;
+    retain?: RetainMode;
+    maxRetainedBytes?: number;
+}
+/**
+ * Bounded string accumulator that keeps the tail of appended chunks.
+ * Once the cap is exceeded, oldest bytes are sliced off and `toString()`
+ * prefixes the survivors with a sentinel describing the elided byte count.
+ *
+ * Exported because long-lived agent runtimes (opencode, claude) also
+ * accumulate per-run narration strings independently of the spawn wrapper
+ * and need the same protection against V8's `kMaxLength`.
+ */
+export declare class TailBuffer {
+    private readonly cap;
+    private buffer;
+    private truncatedBytes;
+    constructor(cap: number);
+    append(chunk: string): void;
+    toString(): string;
+}
+export interface SpawnResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    durationMs: number;
+}
+/**
+ * Spawn a subprocess with streaming callbacks and buffered results
+ */
+export declare function spawn(options: SpawnOptions): Promise<SpawnResult>;