harnery 0.46.0 → 0.47.0

package/dist/commands/computer.js

@@ -0,0 +1,509 @@
+// `computer`: opt-in desktop control through one pinned desktop driver
+// (ADR 0228). The driver adapter (src/lib/computer/cua.ts), host detection and
+// the cross-call desktop lease live in src/lib/computer/; this command owns
+// the config gate, flag parsing, lease policy for `call`, screenshot redaction,
+// rendering, and exit codes.
+//
+// Exit codes: 0 ok · 1 error (disabled, unsupported host, not installed,
+// driver failure; `call` propagates the driver's own exit code) · 3 the
+// desktop lease is held by another agent.
+import { hostname, userInfo } from "node:os";
+import { Command } from "commander";
+import { resolveCoordRoot, resolveOwner } from "../core/agents/coord-client.js";
+import { agentDisplayName, resolveShortName } from "../core/agents/state/activity-log.js";
+import { readComputerConfig } from "../core/config.js";
+/** Exit code for a desktop held by another agent. */
+export const EXIT_LEASE_HELD = 3;
+/** `call` waits this long for another agent's lease when nothing overrides it. */
+export const DEFAULT_CALL_WAIT_SECONDS = 30;
+/**
+ * Who is asking for the desktop: the coordinated agent when one is resolvable,
+ * else the calling OS user (`shell:<user>@<hostname>`, label `shell-<user>`), so
+ * separate shell invocations by the same person share one lease.
+ */
+export function resolveLeaseOwner() {
+    const root = resolveCoordRoot();
+    const id = resolveOwner();
+    if (id) {
+        return {
+            id,
+            label: root ? resolveShortName(root, id) : agentDisplayName(id),
+            ...(root ? { project: root } : {}),
+        };
+    }
+    const user = userInfo().username;
+    return {
+        id: `shell:${user}@${hostname()}`,
+        label: `shell-${user}`,
+        ...(root ? { project: root } : {}),
+    };
+}
+async function loadDefaultDeps() {
+    const [{ detectHost }, { cuaDriver }, { desktopLease, leaseDir, DEFAULT_LEASE_IDLE_MS }] = await Promise.all([
+        import("../lib/computer/host.js"),
+        import("../lib/computer/cua.js"),
+        import("../lib/computer/lease.js"),
+    ]);
+    return {
+        host: () => detectHost(),
+        driver: cuaDriver,
+        lease: desktopLease,
+        leaseDir,
+        defaultIdleMs: DEFAULT_LEASE_IDLE_MS,
+    };
+}
+/** Fill in every dependency the caller did not inject; driver modules load lazily. */
+async function resolveDeps(input) {
+    const needsDefaults = !input.host ||
+        !input.driver ||
+        !input.lease ||
+        !input.leaseDir ||
+        input.defaultIdleMs === undefined;
+    const defaults = needsDefaults ? await loadDefaultDeps() : undefined;
+    return {
+        emit: input.emit,
+        binName: input.binName,
+        host: input.host ?? defaults?.host,
+        driver: input.driver ?? defaults?.driver,
+        lease: input.lease ?? defaults?.lease,
+        leaseDir: input.leaseDir ?? defaults?.leaseDir,
+        defaultIdleMs: input.defaultIdleMs ?? defaults?.defaultIdleMs,
+        owner: input.owner ?? resolveLeaseOwner,
+        config: input.config ?? (() => readComputerConfig()),
+        writeStderr: input.writeStderr ?? ((text) => process.stderr.write(text)),
+        now: input.now ?? Date.now,
+    };
+}
+class ComputerError extends Error {
+    code;
+    exitCode;
+    hint;
+    constructor(code, message, exitCode = 1, hint) {
+        super(message);
+        this.code = code;
+        this.exitCode = exitCode;
+        this.hint = hint;
+    }
+}
+function enableHint() {
+    return 'Add `"computer": { "enabled": true }` to .harnery/config.jsonc to enable it for this project.';
+}
+function requireEnabled(deps) {
+    if (deps.config().enabled)
+        return;
+    throw new ComputerError("computer_disabled", `Computer use is off in this project. ${enableHint()}`);
+}
+function requireSupported(host) {
+    if (host.kind === "unsupported" || !host.desktopStateDir) {
+        throw new ComputerError("computer_unsupported_host", `Computer use is not available on this host: ${host.reason ?? "no supported desktop driver build"}`);
+    }
+    return host;
+}
+function requireInstalled(deps, host) {
+    const exe = deps.driver.installedExecutable(host);
+    if (exe)
+        return exe;
+    throw new ComputerError("computer_not_installed", `The pinned desktop driver (${deps.driver.id} ${deps.driver.version}) is not installed. Run \`${deps.binName} computer install --yes\`.`);
+}
+function leaseOptions(deps, host, waitMs = 0) {
+    const idleSeconds = deps.config().idle_seconds;
+    return {
+        dir: deps.leaseDir(host.desktopStateDir),
+        idleMs: idleSeconds !== undefined ? Math.round(idleSeconds * 1000) : deps.defaultIdleMs,
+        waitMs,
+        now: deps.now,
+    };
+}
+function expiresInSeconds(lease, nowMs) {
+    return Math.max(0, Math.ceil((Date.parse(lease.expires_at) - nowMs) / 1000));
+}
+function describeLease(lease, nowMs) {
+    return `${lease.owner_label} (generation ${lease.generation}, idle-expires in ${expiresInSeconds(lease, nowMs)}s)`;
+}
+function heldError(deps, holder) {
+    return new ComputerError("computer_lease_held", `Desktop is held by ${describeLease(holder, deps.now())}. Wait, or ask them to run \`${deps.binName} computer lease release\`.`, EXIT_LEASE_HELD);
+}
+function parseSeconds(raw, flag) {
+    if (raw === undefined)
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value < 0 || value > 3600) {
+        throw new ComputerError("computer_usage", `${flag} must be a number of seconds from 0 to 3600`);
+    }
+    return value;
+}
+function parseCallArgs(raw) {
+    if (raw === undefined || raw.trim() === "")
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new ComputerError("computer_usage", `Tool arguments must be JSON: ${err.message}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new ComputerError("computer_usage", "Tool arguments must be a JSON object.");
+    }
+    return parsed;
+}
+const PNG_B64_RE = /"([A-Za-z0-9_]*png_b64)"(\s*:\s*)"((?:[^"\\]|\\.)*)"/g;
+/**
+ * Replace inline base64 screenshots in driver output with a short note, so a
+ * single state read cannot flood the calling agent's context. Works on the raw
+ * text, so the driver's formatting survives.
+ */
+export function redactInlineScreenshots(stdout) {
+    return stdout.replace(PNG_B64_RE, (_match, key, sep, value) => `"${key}"${sep}"<omitted ${value.length} chars; pass screenshot_out_file or --keep-screenshot>"`);
+}
+function printDriverResult(deps, result, stdout = result.stdout) {
+    if (stdout)
+        emitLine(deps.emit, stdout);
+    if (result.stderr)
+        deps.writeStderr(result.stderr.endsWith("\n") ? result.stderr : `${result.stderr}\n`);
+    if (result.exitCode !== 0)
+        deps.emit.setExitCode(result.exitCode);
+}
+async function ensureDaemon(deps, host) {
+    const current = deps.driver.daemonStatus(host);
+    if (current.running)
+        return current;
+    const started = await deps.driver.startDaemon(host);
+    if (!started.running) {
+        throw new ComputerError("computer_daemon_failed", `The desktop driver daemon did not start${started.detail ? `: ${started.detail}` : "."}`);
+    }
+    return started;
+}
+/** Write human-readable text, ending it with exactly one newline. */
+function emitLine(emit, s) {
+    emit.text(s.endsWith("\n") ? s : `${s}\n`);
+}
+/** Run one action, turning a ComputerError (or any throw) into emit.error + exit code. */
+function guarded(input, body) {
+    return async (...args) => {
+        const deps = await resolveDeps(input);
+        try {
+            await body(deps, ...args);
+        }
+        catch (err) {
+            if (err instanceof ComputerError) {
+                deps.emit.error({
+                    code: err.code,
+                    message: err.message,
+                    ...(err.hint ? { hint: err.hint } : {}),
+                });
+                deps.emit.setExitCode(err.exitCode);
+                return;
+            }
+            deps.emit.error({ code: "computer_error", message: err.message ?? String(err) });
+            deps.emit.setExitCode(1);
+        }
+    };
+}
+/** Pull `{name, status, message}` checks out of the driver's health report, leniently. */
+function healthChecks(json) {
+    const source = Array.isArray(json)
+        ? json
+        : json && typeof json === "object"
+            ? json.checks
+            : undefined;
+    const toCheck = (name, value) => {
+        if (!value || typeof value !== "object")
+            return undefined;
+        const record = value;
+        const status = record.status ??
+            record.state ??
+            (record.ok === true ? "pass" : record.ok === false ? "fail" : undefined);
+        if (typeof status !== "string")
+            return undefined;
+        const message = record.message ?? record.detail;
+        return {
+            name: typeof record.name === "string" ? record.name : name,
+            status,
+            ...(typeof message === "string" ? { message } : {}),
+        };
+    };
+    if (Array.isArray(source)) {
+        const checks = source
+            .map((value, i) => toCheck(`check-${i + 1}`, value))
+            .filter((c) => c !== undefined);
+        return checks.length > 0 ? checks : undefined;
+    }
+    if (source && typeof source === "object") {
+        const checks = Object.entries(source)
+            .map(([name, value]) => toCheck(name, value))
+            .filter((c) => c !== undefined);
+        return checks.length > 0 ? checks : undefined;
+    }
+    return undefined;
+}
+// "skip" is a check that does not apply on this platform, not a failure.
+const PASSING = new Set(["pass", "passed", "ok", "healthy", "success", "skip", "skipped", "info"]);
+/**
+ * Build the `computer` command tree under `parent` (a fresh root when omitted)
+ * and return it. Tests pass fakes for host/driver/lease/owner/config.
+ */
+export function createComputerCommand(input, parent = new Command()) {
+    const bin = input.binName;
+    const computer = parent
+        .command("computer")
+        .description("Opt-in desktop control through a pinned desktop driver: install it, run its daemon, " +
+        "and call its tools while holding a desktop lease shared by every agent on this machine.")
+        .addHelpText("after", `\nEnable per project with "computer": { "enabled": true } in .harnery/config.jsonc.\n` +
+        `Exit codes: 0 ok · 1 error · ${EXIT_LEASE_HELD} desktop held by another agent.\n` +
+        `Start with \`${bin} computer status\`.`);
+    // ------------------------------------------------------------------ status
+    computer
+        .command("status")
+        .description("Show the host, pinned driver, install, daemon, desktop lease holder, and enabled flag.")
+        .option("--json", "Emit the status as JSON.")
+        .action(guarded(input, (deps, opts) => {
+        const config = deps.config();
+        const host = deps.host();
+        const supported = host.kind !== "unsupported" && Boolean(host.desktopStateDir);
+        const installed = supported ? (deps.driver.installedExecutable(host) ?? null) : null;
+        let daemon = null;
+        if (installed) {
+            try {
+                daemon = deps.driver.daemonStatus(host);
+            }
+            catch (err) {
+                daemon = { running: false, detail: err.message };
+            }
+        }
+        const lease = supported ? deps.lease.read(leaseOptions(deps, host)) : null;
+        const nowMs = deps.now();
+        if (opts.json) {
+            deps.emit.data({
+                enabled: config.enabled,
+                host: { kind: host.kind, ...(host.reason ? { reason: host.reason } : {}) },
+                driver: { id: deps.driver.id, version: deps.driver.version },
+                installed,
+                daemon,
+                lease: lease ? { ...lease, expires_in_seconds: expiresInSeconds(lease, nowMs) } : null,
+            });
+            return;
+        }
+        const lines = [
+            `enabled:   ${config.enabled ? "yes" : `no (${enableHint()})`}`,
+            `host:      ${host.kind}${host.reason ? ` (${host.reason})` : ""}`,
+            `driver:    ${deps.driver.id} ${deps.driver.version} (pinned)`,
+        ];
+        if (supported) {
+            lines.push(`installed: ${installed ?? "not installed"}`);
+            lines.push(`daemon:    ${daemon
+                ? daemon.running
+                    ? `running${daemon.pid !== undefined ? ` (pid ${daemon.pid})` : ""}`
+                    : `stopped${daemon.detail ? ` (${daemon.detail})` : ""}`
+                : "n/a"}`);
+            lines.push(`lease:     ${lease ? `held by ${describeLease(lease, nowMs)}` : "free"}`);
+        }
+        emitLine(deps.emit, lines.join("\n"));
+    }));
+    // ----------------------------------------------------------------- install
+    computer
+        .command("install")
+        .description("Preview the pinned driver install (URL, SHA-256, install dir, preference file); --yes downloads, verifies, and installs it.")
+        .option("--yes", "Apply the install. Without it, only the plan is shown.")
+        .option("--json", "Emit the plan or result as JSON.")
+        .action(guarded(input, async (deps, opts) => {
+        requireEnabled(deps);
+        const host = requireSupported(deps.host());
+        const plan = deps.driver.planInstall(host);
+        if (!opts.yes) {
+            if (opts.json) {
+                deps.emit.data({ applied: false, plan });
+                return;
+            }
+            emitLine(deps.emit, [
+                `${plan.alreadyInstalled ? "Already installed" : "Would install"}: ${plan.driver} ${plan.version} for ${plan.host}`,
+                `  url:          ${plan.artifact.url}`,
+                `  sha256:       ${plan.artifact.sha256}`,
+                `  install dir:  ${plan.installDir}`,
+                `  executable:   ${plan.executable}`,
+                `  preferences:  ${plan.preferenceFile} ${JSON.stringify(plan.preferences)}`,
+                plan.alreadyInstalled
+                    ? "Nothing to do."
+                    : `Re-run with --yes to install: \`${deps.binName} computer install --yes\`.`,
+            ].join("\n"));
+            return;
+        }
+        const result = await deps.driver.install(plan);
+        if (opts.json) {
+            deps.emit.data({ applied: true, result });
+            return;
+        }
+        emitLine(deps.emit, result.installed
+            ? `Installed ${result.driver} ${result.version} at ${result.executable}.\nStart it with \`${deps.binName} computer up\`.`
+            : `${result.driver} ${result.version} was already installed at ${result.executable}.`);
+    }));
+    // ---------------------------------------------------------------- up/down
+    computer
+        .command("up")
+        .description("Start the desktop driver daemon (unelevated) if it is not running.")
+        .action(guarded(input, async (deps) => {
+        requireEnabled(deps);
+        const host = requireSupported(deps.host());
+        requireInstalled(deps, host);
+        const status = await ensureDaemon(deps, host);
+        emitLine(deps.emit, `Daemon running${status.pid !== undefined ? ` (pid ${status.pid})` : ""}.`);
+    }));
+    computer
+        .command("down")
+        .description("Stop the desktop driver daemon.")
+        .action(guarded(input, (deps) => {
+        const host = requireSupported(deps.host());
+        requireInstalled(deps, host);
+        const status = deps.driver.stopDaemon(host);
+        emitLine(deps.emit, status.running ? `Daemon still running: ${status.detail}` : "Daemon stopped.");
+        if (status.running)
+            deps.emit.setExitCode(1);
+    }));
+    // ------------------------------------------------------------------ doctor
+    computer
+        .command("doctor")
+        .description("Run the driver's own health report; any non-passing check exits 1.")
+        .option("--json", "Emit the checks as JSON.")
+        .action(guarded(input, (deps, opts) => {
+        const host = requireSupported(deps.host());
+        requireInstalled(deps, host);
+        const result = deps.driver.health(host);
+        let json = result.json;
+        if (json === undefined) {
+            try {
+                json = JSON.parse(result.stdout);
+            }
+            catch {
+                json = undefined;
+            }
+        }
+        const checks = healthChecks(json);
+        const failing = checks?.filter((c) => !PASSING.has(c.status.toLowerCase())) ?? [];
+        const ok = result.exitCode === 0 && checks !== undefined && failing.length === 0;
+        if (opts.json) {
+            deps.emit.data({
+                ok,
+                exit_code: result.exitCode,
+                checks: checks ?? null,
+                report: json ?? result.stdout,
+            });
+        }
+        else if (checks) {
+            emitLine(deps.emit, checks
+                .map((c) => `${c.status.padEnd(6)} ${c.name}${c.message ? `: ${c.message}` : ""}`)
+                .join("\n"));
+        }
+        else {
+            if (result.stdout)
+                emitLine(deps.emit, result.stdout);
+            emitLine(deps.emit, "No structured checks in the driver's health report.");
+        }
+        if (result.stderr)
+            deps.writeStderr(result.stderr);
+        if (!ok)
+            deps.emit.setExitCode(1);
+    }));
+    // ---------------------------------------------------------- tools/describe
+    computer
+        .command("tools")
+        .description("List the driver's tools (name: description).")
+        .action(guarded(input, (deps) => {
+        const host = requireSupported(deps.host());
+        requireInstalled(deps, host);
+        printDriverResult(deps, deps.driver.listTools(host));
+    }));
+    computer
+        .command("describe <tool>")
+        .description("Show one tool's description and input schema.")
+        .action(guarded(input, (deps, tool) => {
+        const host = requireSupported(deps.host());
+        requireInstalled(deps, host);
+        printDriverResult(deps, deps.driver.describe(host, tool));
+    }));
+    // -------------------------------------------------------------------- call
+    computer
+        .command("call <tool> [json]")
+        .description("Call one driver tool with a JSON object of arguments, holding the desktop lease. " +
+        "`session` defaults to your agent name; inline base64 screenshots are redacted unless --keep-screenshot.")
+        .option("--wait <seconds>", "How long to wait for another agent's lease (default: config wait_seconds or 30).")
+        .option("--keep-screenshot", "Print inline base64 screenshots instead of redacting them.")
+        .action(guarded(input, async (deps, tool, rawJson, opts) => {
+        requireEnabled(deps);
+        const host = requireSupported(deps.host());
+        requireInstalled(deps, host);
+        const args = parseCallArgs(rawJson);
+        const waitSeconds = parseSeconds(opts.wait, "--wait") ??
+            deps.config().wait_seconds ??
+            DEFAULT_CALL_WAIT_SECONDS;
+        const owner = deps.owner();
+        if (!("session" in args))
+            args.session = owner.label;
+        const acquired = await deps.lease.acquire(owner, leaseOptions(deps, host, Math.round(waitSeconds * 1000)));
+        if (!acquired.ok)
+            throw heldError(deps, acquired.holder);
+        await ensureDaemon(deps, host);
+        const translated = deps.driver.translateArgsPaths(host, tool, args);
+        const result = deps.driver.call(host, tool, translated);
+        let stdout = deps.driver.translateResultPaths(host, result.stdout);
+        if (!opts.keepScreenshot)
+            stdout = redactInlineScreenshots(stdout);
+        printDriverResult(deps, result, stdout);
+    }));
+    // ------------------------------------------------------------------- lease
+    const lease = computer
+        .command("lease")
+        .description("Inspect, take, or release the desktop lease shared by every agent on this machine.");
+    lease
+        .command("status")
+        .description("Show the current desktop lease holder, or that the desktop is free.")
+        .option("--json", "Emit the lease as JSON (null when free).")
+        .action(guarded(input, (deps, opts) => {
+        const host = requireSupported(deps.host());
+        const current = deps.lease.read(leaseOptions(deps, host));
+        const nowMs = deps.now();
+        if (opts.json) {
+            deps.emit.data({
+                lease: current
+                    ? { ...current, expires_in_seconds: expiresInSeconds(current, nowMs) }
+                    : null,
+            });
+            return;
+        }
+        emitLine(deps.emit, current ? `held by ${describeLease(current, nowMs)}` : "free");
+    }));
+    lease
+        .command("acquire")
+        .description("Take (or refresh) the desktop lease for yourself without calling a tool.")
+        .option("--wait <seconds>", "How long to wait for another agent's lease (default 0).")
+        .action(guarded(input, async (deps, opts) => {
+        requireEnabled(deps);
+        const host = requireSupported(deps.host());
+        const waitSeconds = parseSeconds(opts.wait, "--wait") ?? 0;
+        const result = await deps.lease.acquire(deps.owner(), leaseOptions(deps, host, Math.round(waitSeconds * 1000)));
+        if (!result.ok)
+            throw heldError(deps, result.holder);
+        emitLine(deps.emit, `${result.fresh ? "Acquired" : "Refreshed"} the desktop lease: ${describeLease(result.lease, deps.now())}.`);
+    }));
+    lease
+        .command("release")
+        .description("Release the desktop lease if you hold it.")
+        .action(guarded(input, (deps) => {
+        const host = requireSupported(deps.host());
+        const owner = deps.owner();
+        const released = deps.lease.release(owner, leaseOptions(deps, host));
+        if (released) {
+            emitLine(deps.emit, `Released the desktop lease held by ${owner.label}.`);
+            return;
+        }
+        const current = deps.lease.read(leaseOptions(deps, host));
+        if (!current) {
+            emitLine(deps.emit, "The desktop was not leased.");
+            return;
+        }
+        throw new ComputerError("computer_lease_held", `Not released: the desktop is held by ${describeLease(current, deps.now())}, not ${owner.label}.`, EXIT_LEASE_HELD);
+    }));
+    return computer;
+}
+export function registerComputerCommand(program, emit, binName) {
+    createComputerCommand({ emit, binName }, program);
+}

package/dist/commands/docs.js

@@ -277,7 +277,9 @@ async function handleLint(opts) {
         error_count: errors.length,
         warning_count: warnings.length,
         cold_handoffs: cold,
-        violations,
+        // Errors first: a reader (or a truncated pipe) sees what blocks before
+        // thousands of advisory warnings.
+        violations: [...errors, ...warnings],
     });
     if (errors.length > 0)
         emit.setExitCode(1);

package/dist/commands/fetch.js

@@ -56,6 +56,17 @@ async function runFetch(url, opts, emit, context) {
         }
         headers[h.slice(0, idx).trim()] = h.slice(idx + 1).trim();
     }
+    // Caller headers only: the User-Agent above is ours, not the caller's.
+    if (context?.headerPolicy) {
+        const host = new URL(url).hostname;
+        for (const h of opts.header ?? []) {
+            const idx = h.indexOf(":");
+            const name = h.slice(0, idx).trim();
+            const verdict = context.headerPolicy(host, name, h.slice(idx + 1).trim());
+            if (!verdict.allow)
+                throw new Error(verdict.message);
+        }
+    }
     const jar = opts.cookies !== false
         ? new CookieJar({ path: opts.store ?? DEFAULT_STORE, source: "harn-fetch" })
         : null;
@@ -74,7 +85,6 @@ async function runFetch(url, opts, emit, context) {
             signal: ac.signal,
             extraHeaders: context?.extraHeaders,
             extraCookies: context?.extraCookies,
-            clientRedirects: context?.clientRedirects?.() || undefined,
             responseType: "bytes",
         });
     }

package/dist/commands/grep.d.ts

@@ -1,6 +1,55 @@
 import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.js";
 import { type SearchEngine } from "../lib/tools/ripgrep.js";
+/**
+ * `grep`: monorepo-aware code search. Prefers ripgrep (`rg`) when it is on
+ * PATH and falls back to GNU/BSD grep transparently — both engines are driven
+ * with equivalent flags and their output is parsed into the same envelope, so
+ * results are identical (pinned by tests/unit/grep-engine.test.ts).
+ * Smart default excludes (skip dist/.next/node_modules/.git/...), repo
+ * scoping (`--repo <name>` or `--all-repos`), language presets, file-level
+ * boolean composition (`--and` / `--without`), and context (`-C`/`-A`/`-B`).
+ *
+ * Engine selection: `HARNERY_GREP_ENGINE=rg|grep` forces one; otherwise `rg`
+ * is resolved (managed install, PATH, or opt-in auto-provision; see
+ * resolveEngine) and used when available. Repos are searched in parallel, and
+ * in `--all-repos` mode the parent scan prunes submodule directories so each
+ * match is attributed to exactly one repo.
+ *
+ * Output framing: content searches request the NUL filename delimiter
+ * (`--null` on both engines — the long spelling, because BSD grep repurposes
+ * `-Z` for decompression) so filename boundaries are never inferred from
+ * punctuation. Context lines are NOT requested from the engines: matches are
+ * selected (and budgeted) first, then context windows are materialized from
+ * one file read per selected file, which keeps `--limit` semantics exact and
+ * both engines byte-identical.
+ *
+ * Default behavior matches extended-regex semantics (`grep -E` / ripgrep's
+ * default). Use `-F` / `--literal` to pin to literal-string mode. Output is
+ * line-oriented `file:line:content` in TTY mode (context rows render
+ * grep-style as `file-line-content`); `--json` emits the full GrepResult
+ * envelope `{ pattern, mode, engine, and_patterns, without_patterns, repos,
+ * total_matches, total_files, truncated, elapsed_ms }`. Matches are sorted
+ * (file, then line) for stable output across runs and engines.
+ *
+ * Output and paging: a search shows every result row unless `--limit <n>`
+ * sets a page size, and clips each printed line to DEFAULT_MAX_COLUMNS
+ * characters (`--max-columns 0` turns clipping off). 500 columns keeps any
+ * hand-written source line and long prose lines while cutting minified or
+ * generated ones; on the v2 tune split a 300-column clip lost a claim that
+ * 500 kept, at about 8% more tokens than 300. There is
+ * no default row bound: on the context bench's v2 tune split, every default
+ * from 50 to 300 rows lost answer evidence that the unbounded search found
+ * (plan 2026-10-31_context-round-trips, Track D). When rows are left out, a count pass
+ * (the same search with `-c`, which prints one short row per file) supplies
+ * the totals, and the last line states how many matches and files were left
+ * out and the `--page <n>` that continues. Pages are cut from one global order
+ * (repo order, then file path, then line), so `--page 2` starts exactly where
+ * page 1 stopped, whichever engine ran. A content page is fetched by searching
+ * only the files that hold its rows.
+ */
+/** Characters kept per printed line unless --max-columns says otherwise. */
+export declare const DEFAULT_MAX_COLUMNS = 500;
 export type GrepEngine = SearchEngine;
 export interface GrepOpts {
     repo?: string;
@@ -18,6 +67,11 @@ export interface GrepOpts {
     beforeContext?: string;
     maxCount?: string;
     limit?: string;
+    /** 1-based page of `limit`-sized pages. */
+    page?: string;
+    /** Lift the default row bound (no paging). */
+    /** Characters kept per line; "0" disables clipping. */
+    maxColumns?: string;
     include?: string[];
     exclude?: string[];
     and?: string[];
@@ -33,6 +87,8 @@ export interface Match {
     text: string;
     /** "match" = primary result row (counts toward totals + --limit); "context" = free -C/-A/-B row. */
     kind: "match" | "context";
+    /** Characters removed from `text` by --max-columns clipping (absent when whole). */
+    clipped?: number;
 }
 export declare function registerGrepCommand(program: Command, emit: EmitContext, context?: HarneryProgramContext): void;
 export interface GrepResult {
@@ -47,9 +103,23 @@ export interface GrepResult {
         matches: Match[];
         truncated: boolean;
     }[];
+    /** Result rows shown on this page (context rows excluded). */
     total_matches: number;
+    /** Files with at least one shown row. */
     total_files: number;
+    /** More rows exist after this page. */
     truncated: boolean;
+    /** Page size; null without --limit. */
+    limit: number | null;
+    page: number;
+    /** Result rows / files the whole search found, across every page. */
+    available_matches: number;
+    available_files: number;
+    /** Rows / files the search found that this page does not show. */
+    omitted_matches: number;
+    omitted_files: number;
+    /** The --page value that continues, or null on the last page. */
+    next_page: number | null;
     elapsed_ms: number;
 }
 /** Exported for tests (not part of the package exports map). */
@@ -77,5 +147,7 @@ export declare class NulDecoder {
     flush(): Omit<Match, "repo" | "kind">[];
     private decodeRecord;
 }
+/** Exported for tests (not part of the package exports map). */
+export declare function renderResult(r: GrepResult, opts: GrepOpts): string;
 export {};
 //# sourceMappingURL=grep.d.ts.map

package/dist/commands/grep.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grep.d.ts","sourceRoot":"","sources":["../../src/commands/grep.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"grep.d.ts","sourceRoot":"","sources":["../../src/commands/grep.ts"],"names":[],"mappings":"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"}