dsh-dlp 0.1.0 → 0.2.0

package/lib/guard.js

@@ -27,7 +27,7 @@
  * @module dsh-dlp/guard
  */
 import { DENY_SEVERITY, scanSync, severityRank } from "./detectors.js";
-import { isEgressCapable, matchPathArgument, pathArguments, pathCandidates } from "./paths.js";
+import { isEgressCapable, matchPathArgument, pathArguments, pathCandidates, rulesForTool } from "./paths.js";
 import { nestedStrings } from "./redaction.js";
 /**
  * Denial text for a credential-path match.
@@ -57,20 +57,23 @@ function secretArgumentReason(toolName, ruleIds, hashes) {
  * Credential paths are denied for every tool, not only readers: a shell that
  * can `cat` a key can also copy it. Only path-typed arguments are tested —
  * running the table over every string matches file content and denies writing
- * a `.gitignore` that mentions `.env`. Argument secrets are denied only for
- * egress-capable tools, because denying a local editor for holding the text it
- * was asked to write would break ordinary work without closing an exfiltration
- * path.
+ * a `.gitignore` that mentions `.env`. The one exception is a `writes-only`
+ * rule, which a tool classified read-only is exempt from; that is how
+ * `$DSH_HOME` stays readable while every write to it is denied. Argument
+ * secrets are denied only for egress-capable tools, because denying a local
+ * editor for holding the text it was asked to write would break ordinary work
+ * without closing an exfiltration path.
  * @param exec - the pending call as the guard stage sees it.
  * @param policy - the effective policy after the tighten-only merge.
  * @param hasher - mints the keyed hashes quoted in a denial reason.
  * @returns the denial, or `undefined` to abstain.
  */
 export function evaluateGuard(exec, policy, hasher) {
+    const rules = rulesForTool(exec.name, policy.credentialPathRules);
     for (const argument of pathArguments(exec.arguments)) {
         const candidates = argument.shell ? pathCandidates(argument.text) : [argument.text];
         for (const candidate of candidates) {
-            const rule = matchPathArgument(candidate, policy.credentialPathRules);
+            const rule = matchPathArgument(candidate, rules);
             if (rule === undefined)
                 continue;
             const hash = hasher.hash(candidate);

package/lib/home.js

@@ -0,0 +1,37 @@
+/**
+ * Where the harness keeps its state, and where this plugin's audit sink lands
+ * by default.
+ *
+ * Its own module so the `dsh-dlp report` command can resolve the sink without
+ * importing the plugin: `policy.ts` pulls in `@secretlint/core`, `js-yaml` and
+ * the schema library, none of which a reader of a JSONL file needs.
+ * @module dsh-dlp/home
+ */
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+/**
+ * File name the bundle patch gives the audit sink under the harness home.
+ * `cordis.patch.yml` spells the same name; a deployment that sets `auditLog`
+ * itself must tell `dsh-dlp report` where it put it.
+ */
+export const DEFAULT_AUDIT_LOG_NAME = 'dsh-dlp.audit.jsonl';
+/**
+ * Resolve the harness home the same way the harness does: `$DSH_HOME` when it
+ * is set to something other than whitespace, otherwise `~/.dsh`. Read here
+ * rather than through `@deepseek-ai/dsh-home-paths` to keep the plugin's
+ * runtime imports to the ones a profile is guaranteed to resolve.
+ * @param env - environment consulted for `DSH_HOME`; defaults to `process.env`.
+ * @returns the absolute harness home.
+ */
+export function resolveDshHome(env = process.env) {
+    const configured = env['DSH_HOME'];
+    return resolve(configured !== undefined && configured.trim().length > 0 ? configured : join(homedir(), '.dsh'));
+}
+/**
+ * Where the audit sink sits when the deployment did not name one.
+ * @param env - environment consulted for `DSH_HOME`; defaults to `process.env`.
+ * @returns the absolute path the bundle patch configures.
+ */
+export function defaultAuditLog(env = process.env) {
+    return join(resolveDshHome(env), DEFAULT_AUDIT_LOG_NAME);
+}

package/lib/index.js

@@ -69,6 +69,21 @@ export function loadOrCreateKey(path) {
     writeFileSync(path, created, { mode: 0o600 });
     return created;
 }
+/**
+ * Report a plugin fault on both the deployment's logger and `process.stderr`.
+ *
+ * `ctx.logger`'s default exporter is an in-memory 1000-entry ring buffer and
+ * no shipped bundle mounts a console exporter, so a message that goes only to
+ * the logger is invisible on a stock install — which is what an invalid policy
+ * file and a failed audit write were. `process.stderr` is what the headless
+ * runner itself writes to.
+ * @param ctx - the plugin's context, used for its logger.
+ * @param message - the whole line to report; never carries a matched value.
+ */
+function report(ctx, message) {
+    ctx.logger.error(message);
+    process.stderr.write(`${message}\n`);
+}
 /**
  * Load the repo-local policy tier, if the deployment named one.
  *
@@ -77,7 +92,7 @@ export function loadOrCreateKey(path) {
  * well-formed: the recommended `policyFile` is workspace-relative, so failing
  * the mount would refuse to start `dsh` in every repository without one, and
  * would let a hostile repository disable the plugin by shipping a broken file.
- * @param ctx - the plugin's context, used only for its logger.
+ * @param ctx - the plugin's context, used only to report a bad file.
  * @param policyFile - the configured path, or `undefined` when the deployment named none.
  * @returns the validated policy, or `undefined` when there is none to apply.
  */
@@ -91,7 +106,7 @@ function loadConfiguredPolicy(ctx, policyFile) {
         case 'loaded':
             return load.policy;
         case 'invalid':
-            ctx.logger.error(`dsh-dlp: ignoring the repo-local policy at ${policyFile}: ${load.problem}`);
+            report(ctx, `dsh-dlp: ignoring the repo-local policy at ${policyFile}: ${load.problem}`);
             return undefined;
         /* v8 ignore next 4 -- unreachable while `RepoPolicyLoad` stays closed; the arm exists so adding a variant fails the build. */
         default: {
@@ -110,7 +125,7 @@ export function apply(ctx, config) {
     const hasher = new SpanHasher(loadOrCreateKey(config.redactionKeyFile));
     const correlator = new CallCorrelator();
     const sink = new AuditSink(config.auditLog, (error) => {
-        ctx.logger.error(`dsh-dlp: audit sink write failed: ${String(error)}`);
+        report(ctx, `dsh-dlp: audit sink write failed: ${String(error)}`);
     });
     /** Identity every audit record carries; the session-log envelope carries none of it. */
     const identity = (exec) => {
@@ -169,11 +184,20 @@ export function apply(ctx, config) {
     }
     if (policy.resultRedaction) {
         ctx.on('tools/post-execute', async (exec, result, next) => {
-            const redacted = await redactDecision(await next(), result, policy, hasher);
+            // The live definition, so a schema the deployment's own tool declares is
+            // read from the registry rather than assumed. `exec.agent` is the scope
+            // key: a scoped tool shadows a global one of the same name.
+            const outputSchema = ctx.tools.get(exec.name, exec.agent)?.output.schema;
+            const redacted = await redactDecision(await next(), result, policy, hasher, outputSchema);
+            const indicators = Object.keys(redacted.indicators).length > 0
+                ? { unicode: redacted.indicators }
+                : {};
             // A truncated scan is recorded even with nothing found: without a record
             // an operator cannot tell "this result was clean" from "this result was
-            // only partly examined".
-            if (redacted.spans.length > 0 || redacted.truncatedScan) {
+            // only partly examined". An invisible-character run is recorded on the
+            // same terms, because the `report` classes are never replaced and the
+            // count is the only trace they leave.
+            if (redacted.spans.length > 0 || redacted.truncatedScan || Object.keys(indicators).length > 0) {
                 sink.write({
                     v: RECORD_VERSION,
                     time: new Date().toISOString(),
@@ -182,6 +206,7 @@ export function apply(ctx, config) {
                     ...identity(exec),
                     spans: redacted.spans,
                     ...redacted.truncatedScan ? { truncatedScan: true } : {},
+                    ...indicators,
                 });
             }
             return redacted.decision;

package/lib/paths.js

@@ -225,3 +225,41 @@ export function isEgressCapable(toolName, extraEgressTools = new Set()) {
         return true;
     return !LOCAL_TOOLS.has(toolName);
 }
+/**
+ * Tools that can only look: they query the filesystem, the language server,
+ * the session store or a running job, and have no operation that changes
+ * anything.
+ *
+ * A `writes-only` rule is lifted for these names and for no others. Every
+ * shell, `run_code`, every editor, every `mcp__*` tool and any tool this build
+ * has never heard of stays on the deny side, so a new tool is denied until it
+ * is classified — the same default as {@link LOCAL_TOOLS}, in the same
+ * direction.
+ */
+export const READ_ONLY_TOOLS = new Set([
+    'read', 'read_image', 'glob', 'grep', 'lsp',
+    'session_search', 'session_trace',
+    'session_event_read', 'session_event_search', 'session_event_trace',
+    'list_agents', 'job_list', 'job_output',
+    'terminal_list', 'terminal_read',
+    'get_goal',
+]);
+/**
+ * Whether a tool is known to be incapable of changing anything.
+ * @param toolName - the executing tool's registered name.
+ * @returns `true` only for a name in {@link READ_ONLY_TOOLS}.
+ */
+export function isReadOnlyTool(toolName) {
+    return READ_ONLY_TOOLS.has(toolName);
+}
+/**
+ * The credential-path rules one tool is judged against.
+ * @param toolName - the executing tool's registered name.
+ * @param rules - the effective rule table.
+ * @returns every rule, minus the `writes-only` ones for a read-only tool.
+ */
+export function rulesForTool(toolName, rules) {
+    if (!isReadOnlyTool(toolName))
+        return rules;
+    return rules.filter(rule => rule.enforcement !== 'writes-only');
+}

package/lib/policy.js

@@ -15,11 +15,11 @@
  * @module dsh-dlp/policy
  */
 import { readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join, resolve } from 'node:path';
+import { resolve } from 'node:path';
 import { JSON_SCHEMA, load } from 'js-yaml';
 import z from '@deepseek-ai/schemastery';
 import { SYNC_RULES, severityRank } from "./detectors.js";
+import { resolveDshHome } from "./home.js";
 import { CREDENTIAL_PATH_RULES } from "./paths.js";
 export const Config = z.object({
     auditLog: z.string().required(),
@@ -216,36 +216,35 @@ function escapePattern(literal) {
     return literal.replace(/[.*+?^${}()|[\]\\]/g, String.raw `\$&`);
 }
 /**
- * Deny rules protecting this plugin's own state.
+ * Deny rules protecting this plugin's own state and the harness home.
  *
  * Every one of these is known at mount: the key file whose bytes make a
  * placeholder hash keyed rather than a bare digest, the append-only sink that
  * is the only evidence a decision happened, and the harness home holding the
  * provider credentials, the session logs and the profiles that decide which
  * plugins load at all.
+ *
+ * The harness home is split. **Writing** anywhere under it is denied for every
+ * tool: a prompt-injected agent editing a profile's `cordis.yml` mounts an
+ * arbitrary plugin. **Reading** it is denied only where the contents are
+ * credentials — `.credentials.yaml`, `.env` and `*.key` are already in the
+ * built-in table, and the session logs get a rule here. Everything else under
+ * that directory is the installed plugin tree and the profile manifests, which
+ * a user debugging a plugin has every reason to read; a blanket read denial
+ * there was unoverridable and was the plugin's most likely uninstall reason.
  * @param config - the deployment-controlled configuration.
  * @param dshHome - the resolved harness home.
  * @returns rules appended after the built-in table.
  */
 function selfProtectionRules(config, dshHome) {
+    const home = escapePattern(resolve(dshHome));
     return [
         { id: 'dsh-dlp/path-own-redaction-key', version: 1, pattern: new RegExp(`^${escapePattern(resolve(config.redactionKeyFile))}$`, 'i') },
         { id: 'dsh-dlp/path-own-audit-log', version: 1, pattern: new RegExp(`^${escapePattern(resolve(config.auditLog))}$`, 'i') },
-        { id: 'dsh-dlp/path-dsh-home', version: 1, pattern: new RegExp(`^${escapePattern(resolve(dshHome))}(/|$)`, 'i') },
+        { id: 'dsh-dlp/path-dsh-sessions', version: 1, pattern: new RegExp(`^${home}/sessions(/|$)`, 'i') },
+        { id: 'dsh-dlp/path-dsh-home', version: 2, enforcement: 'writes-only', pattern: new RegExp(`^${home}(/|$)`, 'i') },
     ];
 }
-/**
- * Resolve the harness home the same way the harness does: `$DSH_HOME` when it
- * is set to something other than whitespace, otherwise `~/.dsh`. Read here
- * rather than through `@deepseek-ai/dsh-home-paths` to keep the plugin's
- * runtime imports to the ones a profile is guaranteed to resolve.
- * @param env - environment consulted for `DSH_HOME`; defaults to `process.env`.
- * @returns the absolute harness home.
- */
-export function resolveDshHome(env = process.env) {
-    const configured = env['DSH_HOME'];
-    return resolve(configured !== undefined && configured.trim().length > 0 ? configured : join(homedir(), '.dsh'));
-}
 /**
  * Merge the deployment config with an optional repo-local policy.
  * @param config - the deployment-controlled configuration.

package/lib/redaction.js

@@ -80,7 +80,15 @@ function expand(text, start, end) {
 /** Detections merged into non-overlapping regions, each attributed to its strictest rule. */
 function mergeSpans(text, detections) {
     const expanded = detections
-        .map(detection => ({ ...detection, ...expand(text, detection.start, detection.end) }))
+        .map(({ ruleId, ruleVersion, severity, exact, start, end }) => ({
+        ruleId,
+        ruleVersion,
+        severity,
+        // An exact detection covers precisely what must go: widening an
+        // invisible character to its delimiters would delete the visible word
+        // around it.
+        ...exact === true ? { start, end } : expand(text, start, end),
+    }))
         .sort((left, right) => left.start - right.start || left.end - right.end);
     const merged = [];
     for (const candidate of expanded) {

package/lib/results.js

@@ -10,9 +10,10 @@
  * whole rule set applies here and not in the guard.
  * @module dsh-dlp/results
  */
-import { DENY_SEVERITY, scanAll, scanSync, severityRank, } from "./detectors.js";
+import { DENY_SEVERITY, countUnicodeIndicators, scanAll, scanSync, severityRank, } from "./detectors.js";
 import { isEgressCapable } from "./paths.js";
 import { nestedStrings, redactContent, redactJson } from "./redaction.js";
+import { redactionBreaksSchema } from "./schema.js";
 /**
  * Separator the strings of one result are rendered with before the
  * cross-string scan. A newline is what the reader of a tool result sees
@@ -38,7 +39,7 @@ const RENDER_SEPARATOR = '\n';
  * is scanned depend on the same accident.
  * @param strings - every string that will be redacted, in render order.
  * @param policy - the effective policy.
- * @returns a memoized lookup and whether tier 2 saw less than the whole rendering.
+ * @returns a memoized lookup, the invisible-character counts, and whether tier 2 saw less than the whole rendering.
  */
 async function prepareScan(strings, policy) {
     const rendered = strings.join(RENDER_SEPARATOR);
@@ -69,7 +70,7 @@ async function prepareScan(strings, policy) {
         }
     }
     /* v8 ignore next -- every string handed to the walkers was collected for this memo. */
-    return { scan: text => memo.get(text) ?? [], truncated };
+    return { scan: text => memo.get(text) ?? [], truncated, indicators: countUnicodeIndicators(rendered) };
 }
 /** Text carried by a content array's text blocks. */
 function contentStrings(blocks) {
@@ -123,10 +124,11 @@ function withheldFeedback(spans) {
  *   carries a secret, or a value that still scans dirty after redaction.
  *   Blocking replaces the whole result, which is the only way to drop `meta`.
  *
- * Replacing the value can fail: the placeholder is re-validated against the
- * tool's `output.schema`, and a schema that constrains the string rejects it,
- * which the registry reports as a `ToolOutputError`. A failed call is the
- * intended outcome there — see README.md.
+ * Replacing the value is re-validated by the registry against the tool's
+ * `output.schema`, and a schema that pins the redacted string rejects it. That
+ * surfaces as a `ToolOutputError` naming a validation failure, which tells the
+ * model nothing it can act on, so the schema is checked here first and the
+ * result is withheld with this plugin's own explanation instead.
  *
  * A downstream `accept{content}` over a dirty value is overruled by the value
  * arm, which discards that listener's presentation choice. Keeping it would
@@ -136,9 +138,10 @@ function withheldFeedback(spans) {
  * @param result - the dispatch outcome the waterfall was called with.
  * @param policy - the effective policy.
  * @param hasher - mints each span's keyed hash.
+ * @param outputSchema - the executing tool's declared output schema, when one could be resolved.
  * @returns the decision to return, the spans replaced, and scan completeness.
  */
-export async function redactDecision(decision, result, policy, hasher) {
+export async function redactDecision(decision, result, policy, hasher, outputSchema) {
     if (decision.kind === 'block') {
         const prepared = await prepareScan(contentStrings(decision.feedback), policy);
         const redacted = redactContent(decision.feedback, prepared.scan, hasher);
@@ -146,6 +149,7 @@ export async function redactDecision(decision, result, policy, hasher) {
             decision: redacted.changed ? { ...decision, feedback: redacted.content } : decision,
             spans: redacted.spans,
             truncatedScan: prepared.truncated,
+            indicators: prepared.indicators,
         };
     }
     const replacedValue = Object.hasOwn(decision, 'value') ? decision.value : undefined;
@@ -164,6 +168,14 @@ export async function redactDecision(decision, result, policy, hasher) {
     const dirty = (strings) => strings.some(text => prepared.scan(text).length > 0);
     if (value !== undefined && dirty(nestedStrings(value))) {
         const redacted = redactJson(value, prepared.scan, hasher);
+        if (redactionBreaksSchema(outputSchema, value, redacted.value)) {
+            return {
+                decision: { kind: 'block', feedback: withheldFeedback(redacted.spans) },
+                spans: redacted.spans,
+                truncatedScan: prepared.truncated,
+                indicators: prepared.indicators,
+            };
+        }
         const remaining = nestedStrings(redacted.value);
         const residual = await prepareScan(remaining, policy);
         if (remaining.some(text => residual.scan(text).length > 0)) {
@@ -171,12 +183,14 @@ export async function redactDecision(decision, result, policy, hasher) {
                 decision: { kind: 'block', feedback: withheldFeedback(redacted.spans) },
                 spans: redacted.spans,
                 truncatedScan: prepared.truncated || residual.truncated,
+                indicators: prepared.indicators,
             };
         }
         return {
             decision: { kind: 'accept', value: redacted.value, ...contexts },
             spans: redacted.spans,
             truncatedScan: prepared.truncated,
+            indicators: prepared.indicators,
         };
     }
     // The value is clean, so the durable result is clean unless `meta` — which
@@ -187,17 +201,19 @@ export async function redactDecision(decision, result, policy, hasher) {
             decision: { kind: 'block', feedback: withheldFeedback(spans) },
             spans,
             truncatedScan: prepared.truncated,
+            indicators: prepared.indicators,
         };
     }
     const blocks = replacedContent ?? result.content;
     const redacted = redactContent(blocks, prepared.scan, hasher);
     if (!redacted.changed) {
-        return { decision, spans: [], truncatedScan: prepared.truncated };
+        return { decision, spans: [], truncatedScan: prepared.truncated, indicators: prepared.indicators };
     }
     return {
         decision: { kind: 'accept', content: redacted.content, ...contexts },
         spans: redacted.spans,
         truncatedScan: prepared.truncated,
+        indicators: prepared.indicators,
     };
 }
 /**

package/lib/schema.js

@@ -0,0 +1,99 @@
+/**
+ * Whether a redacted value still satisfies the tool's declared `output.schema`.
+ *
+ * Replacing a canonical value makes the registry re-validate it, so a schema
+ * that pins the redacted string turns a redaction into a `ToolOutputError` the
+ * model cannot act on. Asking the question first lets the listener withhold
+ * the result with its own explanation instead.
+ *
+ * This is a re-implementation of the harness's own check rather than a call
+ * into it: every harness type this package uses is imported with `import
+ * type`, so nothing from `@deepseek-ai/dsh-*` is emitted as a runtime import
+ * and the plugin resolves from a profile directory that has none of them
+ * installed. The enforced subset is small — `type`, `oneOf`, `properties`,
+ * `required`, `additionalProperties`, `items`, `enum`, `const` — and the
+ * caller guards against any disagreement by checking the *original* value
+ * first: a value this module rejects before redaction means the answer cannot
+ * be trusted, and the redaction proceeds as it did before.
+ * @module dsh-dlp/schema
+ */
+/** Whether a value is a plain JSON object rather than an array or a null. */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Whether a scalar passes the node's `enum` and `const` constraints. */
+function allowsScalar(node, value) {
+    if (node.enum !== undefined && !node.enum.includes(value))
+        return false;
+    return node.const === undefined || value === node.const;
+}
+/** Whether every declared property of an object node is satisfied. */
+function satisfiesObject(node, value) {
+    const properties = node.properties ?? {};
+    for (const key of node.required ?? []) {
+        if (!Object.hasOwn(value, key) || value[key] === undefined)
+            return false;
+    }
+    if (node.additionalProperties === false) {
+        for (const key of Object.keys(value)) {
+            if (!Object.hasOwn(properties, key))
+                return false;
+        }
+    }
+    return Object.entries(properties).every(([key, child]) => !Object.hasOwn(value, key) || value[key] === undefined || satisfiesJsonSchema(child, value[key]));
+}
+/**
+ * Whether one value satisfies one schema node.
+ * @param node - a node of the tool's declared output schema.
+ * @param value - the candidate value.
+ * @returns `true` when the registry's own validation would accept it.
+ */
+export function satisfiesJsonSchema(node, value) {
+    if (node.oneOf !== undefined) {
+        return node.oneOf.filter(branch => satisfiesJsonSchema(branch, value)).length === 1;
+    }
+    switch (node.type) {
+        case undefined:
+            return true;
+        case 'object':
+            return isRecord(value) && satisfiesObject(node, value);
+        case 'array': {
+            const items = node.items;
+            return Array.isArray(value) && (items === undefined || value.every(item => satisfiesJsonSchema(items, item)));
+        }
+        case 'string':
+            return typeof value === 'string' && allowsScalar(node, value);
+        case 'number':
+            return typeof value === 'number' && Number.isFinite(value) && allowsScalar(node, value);
+        case 'integer':
+            return typeof value === 'number' && Number.isInteger(value) && allowsScalar(node, value);
+        case 'boolean':
+            return typeof value === 'boolean' && allowsScalar(node, value);
+        case 'null':
+            return value === null && allowsScalar(node, value);
+        /* v8 ignore next 4 -- unreachable while `JsonSchemaType` stays closed; the arm exists so adding a type fails the build. */
+        default: {
+            const unhandled = node.type;
+            throw new TypeError(`dsh-dlp: unhandled JSON schema type ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+/**
+ * Whether replacing a value with its redacted copy would fail the tool's
+ * output validation.
+ *
+ * A schema this module already rejects for the original value is one it does
+ * not model correctly, so the answer is `false` and the registry decides — the
+ * check can withhold a result, and it must never do so on its own confusion.
+ * @param schema - the tool's declared output schema, when one could be resolved.
+ * @param original - the value the tool produced.
+ * @param redacted - the value the redaction pass produced.
+ * @returns `true` only when the original validates and the redacted one does not.
+ */
+export function redactionBreaksSchema(schema, original, redacted) {
+    if (schema === undefined)
+        return false;
+    if (!satisfiesJsonSchema(schema, original))
+        return false;
+    return !satisfiesJsonSchema(schema, redacted);
+}

package/lib/types/cli.d.ts

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * `dsh-dlp report` — read this plugin's audit JSONL and say what it decided.
+ *
+ * The sink is the only evidence a decision happened, and nothing read it: a
+ * user could not answer "what did this block today?". This command reads the
+ * file directly and imports nothing from the harness, so it runs wherever the
+ * package is installed, with no profile and no `dsh` on the path.
+ *
+ * The file is a durable boundary — written by an older version of this
+ * package, appended to under crash — so every line is parsed defensively and a
+ * line that is not a record is counted rather than trusted.
+ * @module dsh-dlp/cli
+ */
+/** One line of the audit file, after the fields this command reads are checked. */
+export interface ReportRecord {
+    /** Epoch milliseconds parsed from the record's ISO time. */
+    readonly time: number;
+    readonly kind: string;
+    readonly tool?: string;
+    readonly sessionId?: string;
+    /** Rule ids named by the record's spans, without repeats. */
+    readonly ruleIds: readonly string[];
+    /** Invisible-character runs by rule id. */
+    readonly unicode: Readonly<Record<string, number>>;
+}
+/**
+ * Parse one JSONL line into the fields this command reports on.
+ * @param line - one line of the audit file.
+ * @returns the record, or `undefined` when the line is not one.
+ */
+export declare function parseRecord(line: string): ReportRecord | undefined;
+/** What `report` was asked for. */
+export interface ReportOptions {
+    readonly log: string;
+    /** Epoch milliseconds; records before it are left out. */
+    readonly since?: number;
+    readonly session?: string;
+    /** Keep only the decisions that let the call through. */
+    readonly wouldHave: boolean;
+}
+/** The outcome of reading the command line. */
+export type Invocation = {
+    readonly kind: 'report';
+    readonly options: ReportOptions;
+} | {
+    readonly kind: 'help';
+} | {
+    readonly kind: 'error';
+    readonly message: string;
+};
+/** Text printed for `--help` and alongside a usage error. */
+export declare const USAGE: string;
+/**
+ * Read `--since`: an ISO timestamp, or a span back from now.
+ * @param value - the argument as written.
+ * @param now - epoch milliseconds a relative span counts back from.
+ * @returns epoch milliseconds, or `undefined` when the value is neither.
+ */
+export declare function parseSince(value: string, now: number): number | undefined;
+/**
+ * Read the command line.
+ * @param argv - arguments after the program name.
+ * @param env - environment used for the default sink path.
+ * @param now - epoch milliseconds a relative `--since` counts back from.
+ * @returns what to run, or the usage error to print.
+ */
+export declare function parseArguments(argv: readonly string[], env: NodeJS.ProcessEnv, now: number): Invocation;
+/** Outcome of reading the audit file. */
+export type AuditFileRead = 
+/** No file at that path: nothing has been recorded, or the sink is elsewhere. */
+{
+    readonly kind: 'absent';
+} | {
+    readonly kind: 'unreadable';
+    readonly problem: string;
+} | {
+    readonly kind: 'read';
+    readonly records: readonly ReportRecord[];
+    /** Lines that were not records; a torn final append is the expected cause. */
+    readonly unreadable: number;
+};
+/**
+ * Read and parse the audit file.
+ * @param path - the file to read.
+ * @returns its records, its absence, or the problem to print.
+ */
+export declare function readAuditFile(path: string): AuditFileRead;
+/**
+ * Render the report.
+ * @param records - every record the file yielded.
+ * @param unreadable - how many of its lines were not records.
+ * @param options - the filters the invocation asked for.
+ * @returns the lines to print.
+ */
+export declare function formatReport(records: readonly ReportRecord[], unreadable: number, options: ReportOptions): string[];
+/**
+ * Run one invocation.
+ * @param argv - arguments after the program name.
+ * @param write - receives each line of output.
+ * @param fail - receives each line of error output.
+ * @param env - environment used for the default sink path.
+ * @param now - epoch milliseconds a relative `--since` counts back from.
+ * @returns the process exit code.
+ */
+export declare function main(argv: readonly string[], write: (line: string) => void, fail: (line: string) => void, env?: NodeJS.ProcessEnv, now?: number): number;
+//# sourceMappingURL=cli.d.ts.map