@nurix/nustack 0.23.9 → 0.23.11

package/dist/lib/agent/claudeHooks.js

@@ -2,11 +2,14 @@ import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import path from "node:path";
 const MANAGED_MARKER = "nustack:managed";
-const MANAGED_COMMAND = `nustack agent context # ${MANAGED_MARKER}`;
-function managedEntry() {
-    return { matcher: "", hooks: [{ type: "command", command: MANAGED_COMMAND }] };
+const SESSION_START_COMMAND = "nustack agent context";
+function managedEntry(matcher, command, options) {
+    const hook = { type: "command", command: `${command} # ${MANAGED_MARKER}` };
+    if (options.timeout !== undefined)
+        hook.timeout = options.timeout;
+    return { matcher, hooks: [hook] };
 }
-function isManagedEntry(entry) {
+function carriesMarker(entry) {
     if (entry === null || typeof entry !== "object")
         return false;
     const hooks = entry.hooks;
@@ -17,6 +20,12 @@ function isManagedEntry(entry) {
         typeof hook.command === "string" &&
         hook.command.includes(MANAGED_MARKER));
 }
+function isManagedEntry(entry, matcher) {
+    if (!carriesMarker(entry))
+        return false;
+    const entryMatcher = entry.matcher;
+    return (typeof entryMatcher === "string" ? entryMatcher : "") === matcher;
+}
 const DEFAULT_INDENT = 2;
 function detectIndent(raw) {
     const indented = /\n(\x20+)"/.exec(raw);
@@ -34,44 +43,55 @@ async function writeSettings(settingsPath, settings, indent) {
     await mkdir(path.dirname(settingsPath), { recursive: true });
     await writeFile(settingsPath, `${JSON.stringify(settings, null, indent)}\n`, "utf8");
 }
-export async function installSessionStartHook(settingsPath) {
+export async function installManagedHook(settingsPath, event, matcher, command, options = {}) {
     const { settings, indent } = await readSettings(settingsPath);
     const hooks = { ...(settings.hooks ?? {}) };
-    const sessionStart = Array.isArray(hooks.SessionStart) ? [...hooks.SessionStart] : [];
-    const existingIndex = sessionStart.findIndex(isManagedEntry);
-    const entry = managedEntry();
+    const entries = Array.isArray(hooks[event]) ? [...hooks[event]] : [];
+    const existingIndex = entries.findIndex((entry) => isManagedEntry(entry, matcher));
+    const entry = managedEntry(matcher, command, options);
     if (existingIndex !== -1) {
-        const current = sessionStart[existingIndex];
+        const current = entries[existingIndex];
         if (JSON.stringify(current) === JSON.stringify(entry)) {
             return { changed: false };
         }
-        sessionStart[existingIndex] = entry;
+        entries[existingIndex] = entry;
     }
     else {
-        sessionStart.push(entry);
+        entries.push(entry);
     }
-    hooks.SessionStart = sessionStart;
+    hooks[event] = entries;
     settings.hooks = hooks;
     await writeSettings(settingsPath, settings, indent);
     return { changed: true };
 }
-export async function removeSessionStartHook(settingsPath) {
+export async function removeManagedHook(settingsPath, event, matcher) {
     const { settings, indent } = await readSettings(settingsPath);
     const hooks = settings.hooks;
-    const sessionStart = hooks?.SessionStart;
-    if (!hooks || !Array.isArray(sessionStart))
+    const entries = hooks?.[event];
+    if (!hooks || !Array.isArray(entries))
         return { removed: false };
-    const filtered = sessionStart.filter((entry) => !isManagedEntry(entry));
-    if (filtered.length === sessionStart.length)
+    const filtered = entries.filter((entry) => !isManagedEntry(entry, matcher));
+    if (filtered.length === entries.length)
         return { removed: false };
     const nextHooks = { ...hooks };
     if (filtered.length > 0) {
-        nextHooks.SessionStart = filtered;
+        nextHooks[event] = filtered;
     }
     else {
-        delete nextHooks.SessionStart;
+        delete nextHooks[event];
     }
     settings.hooks = nextHooks;
     await writeSettings(settingsPath, settings, indent);
     return { removed: true };
 }
+export async function hasManagedHook(settingsPath, event, matcher) {
+    const { settings } = await readSettings(settingsPath);
+    const entries = settings.hooks?.[event];
+    return Array.isArray(entries) && entries.some((entry) => isManagedEntry(entry, matcher));
+}
+export async function installSessionStartHook(settingsPath) {
+    return installManagedHook(settingsPath, "SessionStart", "", SESSION_START_COMMAND);
+}
+export async function removeSessionStartHook(settingsPath) {
+    return removeManagedHook(settingsPath, "SessionStart", "");
+}

package/dist/lib/census/attribute.js

@@ -0,0 +1,120 @@
+import { classifyBashRead } from "../gate/bashRead.js";
+import { tokensOfLength } from "../gate/estimate.js";
+export const CENSUS_CATEGORIES = [
+    "Read full",
+    "Read ranged",
+    "Bash read",
+    "Bash other",
+    "Grep",
+    "Glob",
+    "Agent",
+    "WebFetch",
+    "other",
+];
+export const CENSUS_SCOPES = ["main", "sidechain"];
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function numberOf(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+export function categoryOf(name, input) {
+    const toolInput = isObject(input) ? input : {};
+    switch (name) {
+        case "Read":
+            return toolInput.offset == null && toolInput.limit == null ? "Read full" : "Read ranged";
+        case "Bash":
+            return typeof toolInput.command === "string" && classifyBashRead(toolInput.command) !== null
+                ? "Bash read"
+                : "Bash other";
+        case "Grep":
+        case "Glob":
+        case "WebFetch":
+            return name;
+        case "Agent":
+        case "Task":
+            return "Agent";
+        default:
+            return "other";
+    }
+}
+function resultLength(content) {
+    if (typeof content === "string")
+        return content.length;
+    if (!Array.isArray(content))
+        return 0;
+    let length = 0;
+    for (const block of content) {
+        if (isObject(block) && block.type === "text" && typeof block.text === "string")
+            length += block.text.length;
+    }
+    return length;
+}
+export async function attributeTranscript(lines, fileScope) {
+    const categoryByToolUse = new Map();
+    const seenCalls = new Set();
+    const pending = [];
+    const results = [];
+    let apiCalls = 0;
+    let contextTokens = 0;
+    let skippedLines = 0;
+    for await (const line of lines) {
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            skippedLines++;
+            continue;
+        }
+        if (!isObject(entry)) {
+            skippedLines++;
+            continue;
+        }
+        if (entry.type === "system" && entry.subtype === "compact_boundary") {
+            settle(pending, apiCalls, results);
+            continue;
+        }
+        const scope = fileScope === "sidechain" || entry.isSidechain === true ? "sidechain" : "main";
+        const message = isObject(entry.message) ? entry.message : undefined;
+        const content = Array.isArray(message?.content) ? message.content : [];
+        if (entry.type === "assistant" && message !== undefined) {
+            const messageId = typeof message.id === "string" ? message.id : undefined;
+            if (messageId === undefined || !seenCalls.has(messageId)) {
+                if (messageId !== undefined)
+                    seenCalls.add(messageId);
+                apiCalls++;
+                const usage = isObject(message.usage) ? message.usage : {};
+                contextTokens +=
+                    numberOf(usage.input_tokens) +
+                        numberOf(usage.cache_read_input_tokens) +
+                        numberOf(usage.cache_creation_input_tokens);
+            }
+            for (const block of content) {
+                if (isObject(block) && block.type === "tool_use" && typeof block.id === "string") {
+                    categoryByToolUse.set(block.id, categoryOf(block.name, block.input));
+                }
+            }
+            continue;
+        }
+        for (const block of content) {
+            if (!isObject(block) || block.type !== "tool_result")
+                continue;
+            const toolUseId = typeof block.tool_use_id === "string" ? block.tool_use_id : "";
+            pending.push({
+                category: categoryByToolUse.get(toolUseId) ?? "other",
+                scope,
+                tokens: tokensOfLength(resultLength(block.content)),
+                callsBefore: apiCalls,
+            });
+        }
+    }
+    settle(pending, apiCalls, results);
+    return { results, apiCalls, contextTokens, skippedLines };
+}
+function settle(pending, apiCalls, results) {
+    for (const { category, scope, tokens, callsBefore } of pending) {
+        results.push({ category, scope, tokens, weightedTokens: tokens * Math.max(1, apiCalls - callsBefore) });
+    }
+    pending.length = 0;
+}

package/dist/lib/census/report.js

@@ -0,0 +1,108 @@
+import { CENSUS_CATEGORIES, CENSUS_SCOPES } from "./attribute.js";
+export const CENSUS_THRESHOLD_CANDIDATES = [2_000, 4_000, 8_000, 16_000];
+export const CENSUS_KEEP_SHARE = 0.7;
+export const CENSUS_FALLBACK_THRESHOLD_TOKENS = 2_000;
+export const CENSUS_MIN_SESSIONS = 50;
+export const CENSUS_GATE_SHARE = 0.3;
+export const CENSUS_BASH_FIRST_SHARE = 0.15;
+export const CENSUS_VERDICTS = ["gate-as-designed", "gate-marginal", "bash-output-first"];
+const READ_CATEGORIES = ["Read full", "Read ranged", "Bash read"];
+export function recommendThreshold(candidates, sessions) {
+    if (sessions < CENSUS_MIN_SESSIONS)
+        return null;
+    const kept = candidates.filter((candidate) => candidate.shareAtOrAbove >= CENSUS_KEEP_SHARE).map((candidate) => candidate.tokens);
+    return kept.length === 0 ? CENSUS_FALLBACK_THRESHOLD_TOKENS : Math.max(...kept);
+}
+export function verdictOf(readsShare) {
+    if (readsShare >= CENSUS_GATE_SHARE)
+        return "gate-as-designed";
+    if (readsShare < CENSUS_BASH_FIRST_SHARE)
+        return "bash-output-first";
+    return "gate-marginal";
+}
+function ratio(part, whole) {
+    return whole > 0 ? part / whole : 0;
+}
+export class CensusAccumulator {
+    sessions = 0;
+    transcripts = 0;
+    sidechainTranscripts = 0;
+    skippedLines = 0;
+    contextTokens = 0;
+    rows = new Map();
+    fullReadWeighted = 0;
+    fullReadWeightedAtOrAbove = new Map(CENSUS_THRESHOLD_CANDIDATES.map((tokens) => [tokens, 0]));
+    constructor() {
+        for (const category of CENSUS_CATEGORIES) {
+            for (const scope of CENSUS_SCOPES) {
+                this.rows.set(`${category}|${scope}`, { category, scope, count: 0, tokens: 0, weightedTokens: 0 });
+            }
+        }
+    }
+    addSession() {
+        this.sessions++;
+    }
+    addTranscript(attribution, kind) {
+        if (kind === "main")
+            this.transcripts++;
+        else
+            this.sidechainTranscripts++;
+        this.skippedLines += attribution.skippedLines;
+        this.contextTokens += attribution.contextTokens;
+        for (const result of attribution.results) {
+            const row = this.rows.get(`${result.category}|${result.scope}`);
+            row.count++;
+            row.tokens += result.tokens;
+            row.weightedTokens += result.weightedTokens;
+            if (result.category !== "Read full")
+                continue;
+            this.fullReadWeighted += result.weightedTokens;
+            for (const candidate of CENSUS_THRESHOLD_CANDIDATES) {
+                if (result.tokens >= candidate) {
+                    this.fullReadWeightedAtOrAbove.set(candidate, this.fullReadWeightedAtOrAbove.get(candidate) + result.weightedTokens);
+                }
+            }
+        }
+    }
+    finish() {
+        const categories = [...this.rows.values()].map((row) => ({ ...row, share: ratio(row.weightedTokens, this.contextTokens) }));
+        const weightedOf = (names) => categories.filter((row) => names.includes(row.category)).reduce((sum, row) => sum + row.weightedTokens, 0);
+        const readsShare = ratio(weightedOf(READ_CATEGORIES), this.contextTokens);
+        const bashShare = ratio(weightedOf(["Bash other"]), this.contextTokens);
+        const thresholdCandidates = CENSUS_THRESHOLD_CANDIDATES.map((tokens) => ({
+            tokens,
+            shareAtOrAbove: ratio(this.fullReadWeightedAtOrAbove.get(tokens), this.fullReadWeighted),
+        }));
+        return {
+            sessions: this.sessions,
+            transcripts: this.transcripts,
+            sidechainTranscripts: this.sidechainTranscripts,
+            skippedLines: this.skippedLines,
+            categories,
+            readsShare,
+            bashShare,
+            thresholdCandidates,
+            recommendedThresholdTokens: recommendThreshold(thresholdCandidates, this.sessions),
+            verdict: verdictOf(readsShare),
+        };
+    }
+}
+function percent(value) {
+    return `${(value * 100).toFixed(1)}%`;
+}
+export function renderCensusText(report) {
+    const lines = [
+        `Token census: ${report.sessions} sessions, ${report.transcripts} transcripts, ${report.sidechainTranscripts} sub-agent transcripts, ${report.skippedLines} unreadable lines skipped.`,
+        "",
+        `${"category".padEnd(12)} ${"scope".padEnd(10)} ${"results".padStart(9)} ${"tokens".padStart(13)} ${"weighted".padStart(16)} ${"share".padStart(7)}`,
+    ];
+    for (const row of report.categories) {
+        if (row.count === 0)
+            continue;
+        lines.push(`${row.category.padEnd(12)} ${row.scope.padEnd(10)} ${String(row.count).padStart(9)} ${String(row.tokens).padStart(13)} ${String(row.weightedTokens).padStart(16)} ${percent(row.share).padStart(7)}`);
+    }
+    lines.push("", `Reads' share: ${percent(report.readsShare)} · Bash output share: ${percent(report.bashShare)}`, "Full-read weighted cost at or above each threshold:", ...report.thresholdCandidates.map((candidate) => `  ${String(candidate.tokens).padStart(6)} tokens: ${percent(candidate.shareAtOrAbove)}`), report.recommendedThresholdTokens === null
+        ? `Recommended threshold: withheld (fewer than ${CENSUS_MIN_SESSIONS} sessions).`
+        : `Recommended threshold: ${report.recommendedThresholdTokens} tokens.`, `Verdict: ${report.verdict}`);
+    return lines.join("\n");
+}

package/dist/lib/census/transcripts.js

@@ -0,0 +1,62 @@
+import { createReadStream } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { createInterface } from "node:readline";
+export function defaultTranscriptRoot() {
+    return path.join(os.homedir(), ".claude", "projects");
+}
+async function listDirectory(directory) {
+    try {
+        return await readdir(directory, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+}
+async function subagentTranscripts(projectDirectory, sessionId) {
+    const directory = path.join(projectDirectory, sessionId, "subagents");
+    const entries = await listDirectory(directory);
+    return entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
+        .map((entry) => path.join(directory, entry.name))
+        .sort();
+}
+export async function discoverSessions(options = {}) {
+    const root = options.root ?? defaultTranscriptRoot();
+    const sessions = [];
+    for (const project of await listDirectory(root)) {
+        if (!project.isDirectory())
+            continue;
+        const projectDirectory = path.join(root, project.name);
+        for (const entry of await listDirectory(projectDirectory)) {
+            if (!entry.isFile() || !entry.name.endsWith(".jsonl"))
+                continue;
+            const mainPath = path.join(projectDirectory, entry.name);
+            const modifiedAtMs = (await stat(mainPath)).mtimeMs;
+            if (options.sinceMs !== undefined && modifiedAtMs < options.sinceMs)
+                continue;
+            const sessionId = entry.name.slice(0, -".jsonl".length);
+            sessions.push({
+                sessionId,
+                mainPath,
+                sidechainPaths: await subagentTranscripts(projectDirectory, sessionId),
+                modifiedAtMs,
+            });
+        }
+    }
+    sessions.sort((a, b) => b.modifiedAtMs - a.modifiedAtMs || a.mainPath.localeCompare(b.mainPath));
+    return options.maxSessions === undefined ? sessions : sessions.slice(0, options.maxSessions);
+}
+export async function* readLines(file) {
+    const lines = createInterface({ input: createReadStream(file, { encoding: "utf8" }), crlfDelay: Infinity });
+    try {
+        for await (const line of lines) {
+            if (line.trim() !== "")
+                yield line;
+        }
+    }
+    finally {
+        lines.close();
+    }
+}

package/dist/lib/desktop_settings.js

@@ -1,11 +1,24 @@
 import { readFileSync } from "node:fs";
 import { desktopSettingsPath } from "./local_store/paths.js";
+export const GATE_THRESHOLD_TOKENS_MIN = 1_000;
+export const GATE_THRESHOLD_TOKENS_MAX = 200_000;
+export const DIGEST_BUDGET_MS_MIN = 5_000;
+export const DIGEST_BUDGET_MS_MAX = 300_000;
 const DEFAULT_PLACEMENT = "server";
 function placementOf(value) {
     return value === "device" || value === "server" ? value : DEFAULT_PLACEMENT;
 }
+function boundedIntegerOf(value, min, max) {
+    return typeof value === "number" && Number.isInteger(value) && value >= min && value <= max ? value : null;
+}
+function sectionOf(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
 export function readDesktopSettings() {
-    const defaults = { placement: { memory: DEFAULT_PLACEMENT, securityFindings: DEFAULT_PLACEMENT } };
+    const defaults = {
+        placement: { memory: DEFAULT_PLACEMENT, securityFindings: DEFAULT_PLACEMENT },
+        routing: { localReader: false, gateThresholdTokens: null, digestBudgetMs: null },
+    };
     let parsed;
     try {
         parsed = JSON.parse(readFileSync(desktopSettingsPath(), "utf8"));
@@ -19,5 +32,13 @@ export function readDesktopSettings() {
     if (file.schemaVersion !== 1)
         return defaults;
     const placement = file.placement && typeof file.placement === "object" ? file.placement : {};
-    return { placement: { memory: placementOf(placement.memory), securityFindings: placementOf(placement.securityFindings) } };
+    const routing = sectionOf(file.routing);
+    return {
+        placement: { memory: placementOf(placement.memory), securityFindings: placementOf(placement.securityFindings) },
+        routing: {
+            localReader: routing.localReader === true,
+            gateThresholdTokens: boundedIntegerOf(routing.gateThresholdTokens, GATE_THRESHOLD_TOKENS_MIN, GATE_THRESHOLD_TOKENS_MAX),
+            digestBudgetMs: boundedIntegerOf(routing.digestBudgetMs, DIGEST_BUDGET_MS_MIN, DIGEST_BUDGET_MS_MAX),
+        },
+    };
 }

package/dist/lib/gate/bashRead.js

@@ -0,0 +1,201 @@
+import { closeSync, openSync, readFileSync, readSync } from "node:fs";
+import { BINARY_PROBE_BYTES, isSkippedExtension, readLeadingLines, regularFileSize, tokensOfLength, } from "./estimate.js";
+export const BASH_DEFAULT_LINE_COUNT = 10;
+const COMPOUND_MARKERS = ["|", ";", "&&", "||", ">", "<", "`", "$(", "\n", "\r"];
+const WHOLE_FILE_COMMANDS = new Set(["cat", "less", "more"]);
+function splitWords(command) {
+    const words = [];
+    let current = "";
+    let hasWord = false;
+    let quote = null;
+    for (const character of command) {
+        if (quote !== null) {
+            if (character === quote)
+                quote = null;
+            else
+                current += character;
+            continue;
+        }
+        if (character === "'" || character === '"') {
+            quote = character;
+            hasWord = true;
+            continue;
+        }
+        if (/\s/.test(character)) {
+            if (hasWord)
+                words.push(current);
+            current = "";
+            hasWord = false;
+            continue;
+        }
+        current += character;
+        hasWord = true;
+    }
+    if (quote !== null)
+        return null;
+    if (hasWord)
+        words.push(current);
+    return words;
+}
+function basename(word) {
+    const slash = word.lastIndexOf("/");
+    return slash === -1 ? word : word.slice(slash + 1);
+}
+function positiveInteger(text) {
+    if (!/^\d+$/.test(text))
+        return null;
+    const value = Number.parseInt(text, 10);
+    return Number.isSafeInteger(value) ? value : null;
+}
+function classifyWholeFile(name, args) {
+    const operands = args.filter((arg) => !arg.startsWith("-") || arg === "-");
+    if (operands.length !== 1 || operands[0] === "-")
+        return null;
+    return { command: name, path: operands[0], range: { kind: "whole" } };
+}
+function classifyLineCount(name, args) {
+    let lines = BASH_DEFAULT_LINE_COUNT;
+    const operands = [];
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        let count;
+        if (arg === "-n") {
+            count = positiveInteger(args[++index] ?? "");
+        }
+        else if (arg.startsWith("--lines=")) {
+            count = positiveInteger(arg.slice("--lines=".length));
+        }
+        else if (/^-n\d+$/.test(arg)) {
+            count = positiveInteger(arg.slice(2));
+        }
+        else if (/^-\d+$/.test(arg)) {
+            count = positiveInteger(arg.slice(1));
+        }
+        else if (arg.startsWith("-") && arg !== "-") {
+            return null;
+        }
+        else {
+            operands.push(arg);
+            continue;
+        }
+        if (count === null)
+            return null;
+        lines = count;
+    }
+    if (operands.length !== 1 || operands[0] === "-")
+        return null;
+    return { command: name, path: operands[0], range: { kind: name, lines } };
+}
+function classifySed(args) {
+    let isQuiet = false;
+    const operands = [];
+    for (const arg of args) {
+        if (arg === "-n" || arg === "--quiet" || arg === "--silent")
+            isQuiet = true;
+        else if (arg.startsWith("-"))
+            return null;
+        else
+            operands.push(arg);
+    }
+    if (!isQuiet || operands.length !== 2)
+        return null;
+    const match = /^(\d+)(?:,(\d+))?p$/.exec(operands[0]);
+    if (match === null)
+        return null;
+    const start = positiveInteger(match[1]);
+    const end = match[2] === undefined ? start : positiveInteger(match[2]);
+    if (start === null || end === null || start < 1 || end < start)
+        return null;
+    return { command: "sed", path: operands[1], range: { kind: "lines", start, end } };
+}
+export function classifyBashRead(command) {
+    if (COMPOUND_MARKERS.some((marker) => command.includes(marker)))
+        return null;
+    const words = splitWords(command.trim());
+    if (words === null || words.length < 2)
+        return null;
+    const name = basename(words[0]);
+    const args = words.slice(1);
+    if (WHOLE_FILE_COMMANDS.has(name))
+        return classifyWholeFile(name, args);
+    if (name === "head" || name === "tail")
+        return classifyLineCount(name, args);
+    if (name === "sed")
+        return classifySed(args);
+    return null;
+}
+export const BASH_DEFAULT_MAX_OUTPUT_LENGTH = 30_000;
+export const BASH_MAX_OUTPUT_LENGTH_ENV = "BASH_MAX_OUTPUT_LENGTH";
+const TAIL_SCAN_MAX_BYTES = 32 * 1024 * 1024;
+export function bashMaxOutputLength(env = process.env) {
+    const text = env[BASH_MAX_OUTPUT_LENGTH_ENV]?.trim();
+    if (text !== undefined && /^\d+$/.test(text)) {
+        const value = Number.parseInt(text, 10);
+        if (value > 0)
+            return value;
+    }
+    return BASH_DEFAULT_MAX_OUTPUT_LENGTH;
+}
+function hasLeadingNul(file) {
+    const descriptor = openSync(file, "r");
+    try {
+        const probe = Buffer.alloc(BINARY_PROBE_BYTES);
+        const read = readSync(descriptor, probe, 0, BINARY_PROBE_BYTES, 0);
+        return probe.subarray(0, read).includes(0);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+function tailBytes(file, size, lines) {
+    if (size > TAIL_SCAN_MAX_BYTES)
+        return size;
+    const content = readFileSync(file);
+    let end = content.length;
+    if (end > 0 && content[end - 1] === 10)
+        end--;
+    let cursor = end;
+    let seen = 0;
+    while (cursor > 0) {
+        const newline = content.lastIndexOf(10, cursor - 1);
+        seen++;
+        if (newline === -1 || seen === lines) {
+            cursor = newline + 1;
+            break;
+        }
+        cursor = newline;
+    }
+    return content.length - cursor;
+}
+function printedBytes(file, size, range) {
+    switch (range.kind) {
+        case "whole":
+            return size;
+        case "head":
+            return readLeadingLines(file, range.lines).bytes;
+        case "tail":
+            return tailBytes(file, size, range.lines);
+        case "lines":
+            return readLeadingLines(file, range.end).bytes - readLeadingLines(file, range.start - 1).bytes;
+    }
+}
+export function assessBashRead(file, range, thresholdTokens, minimumThresholdTokens, env = process.env) {
+    const size = regularFileSize(file);
+    if (size === null)
+        return { decision: "pass", reason: "not-a-file", source: "stat", estimatedTokens: null };
+    if (isSkippedExtension(file))
+        return { decision: "pass", reason: "skipped-extension", source: "stat", estimatedTokens: null };
+    const capTokens = tokensOfLength(bashMaxOutputLength(env));
+    const upperBound = Math.min(tokensOfLength(size), capTokens);
+    if (upperBound < minimumThresholdTokens)
+        return { decision: "pass", reason: "under-threshold", source: "stat", estimatedTokens: null };
+    const threshold = thresholdTokens();
+    if (upperBound < threshold)
+        return { decision: "pass", reason: "under-threshold", source: "stat", estimatedTokens: null };
+    if (hasLeadingNul(file))
+        return { decision: "pass", reason: "binary", source: "read", estimatedTokens: null };
+    const estimatedTokens = Math.min(tokensOfLength(printedBytes(file, size, range)), capTokens);
+    if (estimatedTokens < threshold)
+        return { decision: "pass", reason: "under-threshold", source: "read", estimatedTokens };
+    return { decision: "gate", source: "read", estimatedTokens, thresholdTokens: threshold };
+}