opencode-swarm 7.150.0 → 7.151.1

package/dist/hooks/guardrails/audit-log.d.ts

@@ -2,22 +2,30 @@
  * Unified Guardrail Decision Audit Log
  *
  * Additive JSONL schema for guardrail decisions. Each append writes one
- * validated JSON line to the configured audit path under `.swarm/session/`.
+ * validated, redacted, size-bounded JSON line to the canonical
+ * `.swarm/session/shell-audit.jsonl` store (issue #2040). Persistence itself
+ * — locking, framing, retention, compaction — is owned by
+ * `./shell-audit-store.ts`; this module owns entry validation, write-time
+ * redaction/minimization, and line shaping.
  *
  * The existing shell audit entry shape is preserved byte-for-byte when
  * `type: 'shell'` is used (fields: ts, sessionID, agent, tool, command).
  *
- * Path redaction: there is no cross-cutting path-redaction helper in this
- * module today. Callers MAY pass a pre-redacted path via `redactPath(...)`
- * before constructing the entry; the module itself does not mutate path
- * strings beyond normalizing separators. Future hardening: add a shared
- * path-redaction utility and call it here.
+ * Write-time minimization (issue #2040 requirement 4/5):
+ * - Commands are redacted FIRST via `redactShellCommand` (secrets, home
+ *   paths) — redaction sees the full command — then truncated to
+ *   SHELL_AUDIT_LIMITS.maxCommandChars with an explicit `…[truncated]`
+ *   marker. Callers cannot opt out. Redacting first keeps the correlation
+ *   hash on the persisted form and minimizes secrets anywhere in the
+ *   command before any bytes are selected for persistence.
+ * - Paths are redacted via `redactPath`; free-text reasons embed
+ *   home-profile paths via `redactEmbeddedPaths`.
+ * - Typed command-bearing entries additionally persist `commandHash` (a
+ *   16-hex sha256 digest of the FINAL redacted command) so correlation and
+ *   duplicate detection survive without reversible content. Legacy
+ *   `shell` entries stay EXACTLY five fields (SC-119 pinned contract) and
+ *   never carry the hash.
  */
-import * as fs from 'node:fs/promises';
-export declare const _internals: {
-    mkdir: typeof fs.mkdir;
-    appendFile: typeof fs.appendFile;
-};
 /**
  * Discriminated union of guardrail decision types.
  *
@@ -86,29 +94,72 @@ export interface SandboxSkipDecision {
     skipReason: string;
 }
 export type GuardrailDecisionEntry = ShellDecision | FileWriteDecision | ScopeViolationDecision | DestructiveBlockDecision | SandboxWrapDecision | SandboxSkipDecision;
+/**
+ * Redaction/content class of every persisted audit field. SINGLE SOURCE OF
+ * TRUTH: the ratchet test (`tests/unit/hooks/shell-audit-field-classes.test.ts`)
+ * enumerates the union's fields against this map — adding a decision field
+ * without declaring its class fails CI. Classes:
+ *
+ * - `timestamp`          — ISO-8601 string, no free content.
+ * - `identifier`         — opaque session/agent/tool identity string.
+ * - `decision-type`      — closed enum discriminator.
+ * - `redacted-command`   — shell command text after truncation + redaction.
+ * - `redacted-path`      — filesystem path after home-profile redaction.
+ * - `enum`               — closed per-type classification string.
+ * - `free-text-redacted` — producer free text after bounded truncation +
+ *                          embedded-path redaction.
+ * - `content-hash`       — one-way digest of redacted content (correlation
+ *                          only; never rendered, never reversible).
+ */
+export type ShellAuditFieldClass = 'timestamp' | 'identifier' | 'decision-type' | 'redacted-command' | 'redacted-path' | 'enum' | 'free-text-redacted' | 'content-hash';
+export declare const SHELL_AUDIT_FIELD_CLASSES: Readonly<Record<string, ShellAuditFieldClass>>;
+/** 16-hex sha256 digest of the final redacted command — correlation without
+ *  reversible content. Deterministic: identical redacted commands hash
+ *  identically (issue #2040 edge-case: deterministic-enough-for-correlation). */
+export declare function hashRedactedCommand(redacted: string): string;
 /**
  * Best-effort path redaction for audit logs.
  *
  * Replaces leading home/profile segments with a tilde placeholder so
- * absolute paths do not leak user-specific directory names.
+ * absolute paths do not leak user-specific directory names (POSIX
+ * `/home/<name>`, macOS `/Users/<name>`, Windows drive profiles
+ * `C:\Users\<name>` case-insensitive, and UNC profile shares).
  *
- * This is intentionally minimal — callers remain responsible for
- * stripping any domain-specific secrets that may appear in path segments.
+ * This is intentionally minimal on non-home paths — ordinary project paths
+ * are diagnostic content and are preserved (over-redaction guards pin it).
  */
 export declare function redactPath(filePath: string): string;
+declare function redactEmbeddedPaths(text: string): string;
+export { redactEmbeddedPaths };
+/**
+ * Archive-boundary re-redaction (issue #2040 requirement 4 / review round
+ * F4): re-apply the CURRENT redaction policy to one persisted decision line
+ * before the close pipeline archives it. Legacy pre-#2040 lines written with
+ * weaker redaction are normalized here so no legacy record can bypass
+ * current policy in the archived cut. Parse-safe passthrough: an
+ * unparseable line is returned unchanged (the store's corrupt accounting
+ * owns it).
+ */
+export declare function redactDecisionLineForArchive(line: string): string;
 export interface AppendGuardrailDecisionOptions {
-    auditPath: string;
+    /** Project root; the store resolves `.swarm/session/shell-audit.jsonl`. */
+    directory: string;
     enabled: boolean;
 }
 /**
- * Append a validated guardrail decision entry to the JSONL audit log.
+ * Append a validated guardrail decision entry to the JSONL audit store.
  *
- * - Writes exactly one JSON line per call (`JSON.stringify(entry) + '\n'`).
  * - Skips silently when `enabled` is false.
  * - Skips malformed entries after debug logging; never throws.
- * - `.swarm/` containment is enforced by the caller-supplied `auditPath`.
+ * - Truncates + redacts content at line-shaping time (caller-independent
+ *   minimization); typed command entries carry a correlation hash.
+ * - Delegates persistence (lock, framing, retention, compaction) to the
+ *   bounded store; store failures (locked, oversize, I/O) are caught and
+ *   logged — audit failures NEVER block tool execution (issue #2040
+ *   requirement 6: a guardrail block still blocks when logging fails).
+ * - `.swarm/` containment is enforced by the store's path resolution.
  *
  * @param entry Decision entry to persist.
- * @param ctx Audit destination and enablement flag.
+ * @param ctx Audit destination (project root) and enablement flag.
  */
 export declare function appendGuardrailDecision(entry: GuardrailDecisionEntry, ctx: AppendGuardrailDecisionOptions): Promise<void>;

package/dist/hooks/guardrails/helpers.d.ts

@@ -33,6 +33,21 @@ export declare function hasTraversalSegments(filePath: string): boolean;
 export declare function isInDeclaredScope(filePath: string, scopeEntries: string[], cwd?: string): boolean;
 /**
  * Redacts sensitive values from a shell command string before audit logging.
- * Covers env-var assignments, CLI flags, Bearer/Basic auth, and -H header flags.
+ *
+ * Covers env-var assignments (POSIX/PowerShell `$env:`/cmd `set`), CLI flags
+ * (sensitive names, both `=`-joined and space-separated), Bearer/Basic auth,
+ * `-H` header flags, URL credentials (`scheme://user:pass@host`), well-known
+ * token VALUE shapes (OpenAI/GitHub/AWS/Slack/Google — content-based, so they
+ * fire regardless of the surrounding flag name), and long base64-like payload
+ * runs (≥80 chars with mixed case + digit — the encoded-wrapper/heredoc
+ * minimization class from issue #2040; plain hex SHAs and short payloads are
+ * deliberately NOT matched). Sensitive values are consumed through closing
+ * quotes when quoted (`KEY="two words"` redacts the whole value, not just the
+ * first word). UNC profile material (`\\server\share\user\…`) is minimized
+ * like the other home-profile families.
+ *
+ * Deterministic: identical inputs always redact identically (correlation via
+ * the audit `commandHash` relies on it). No pattern retains any reversible
+ * secret material.
  */
 export declare function redactShellCommand(cmd: string): string;

package/dist/hooks/guardrails/shell-audit-store.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Shell-audit bounded store — the single append seam and bounded store for
+ * `.swarm/session/shell-audit.jsonl` (issue #2040, Observability PR 12/23).
+ *
+ * HISTORY: the guardrail decision audit was a fire-and-forget append-only
+ * JSONL with NO byte/age/count ceiling, no locking, no torn-tail handling,
+ * and one whole-file reader (`/swarm guardrail-log` read the entire file
+ * before filtering) — unbounded growth and unbounded read memory in long
+ * sessions.
+ *
+ * NOW it is a BOUNDED single-file store in the `src/events/core-events.ts`
+ * (#2039) house pattern, with SECURITY-AUDIT retention defined separately
+ * from general events (issue #2040 requirement 1):
+ *
+ *   Line 1:  `swarm-shell-audit-manifest` header carrying the size-bounded
+ *            FOLDED aggregate (decisions compacted away: lifetime total,
+ *            per-type counts ≤16 keys + "other", corrupt/dropped counters).
+ *   Line 2+: raw decision JSONL — the RECENT retained window, byte-for-byte
+ *            preserved (the store never normalizes producer lines; legacy
+ *            5-field shell entries stay legacy).
+ *
+ * DECISION-CLASS PRIORITY (issue #2040 requirement 2):
+ *   - SECURITY class — every typed entry (file_write, scope_violation,
+ *     destructive_block, sandbox_wrap, sandbox_skip): never AGE-folded.
+ *   - ALLOWED class — legacy no-`type` shell entries: age-folded past
+ *     allowedAgeMaxMs and held to their own tighter count cap.
+ *   - The byte ceiling (activeMaxBytes) is SOVEREIGN over both classes:
+ *     when it binds, the oldest lines fold regardless of class, disclosed
+ *     via the folded per-type counts and shell_audit_health. Retention
+ *     NEVER alters guardrail authorization — this store is write-only
+ *     telemetry; enforcement decisions are computed and thrown by the
+ *     guardrail hooks independently of any append succeeding.
+ *
+ * CONCURRENCY: every write (append, fold, finalize) holds the exclusive
+ * `.swarm/session/shell-audit.lock` (`wx` create, stale-broken after
+ * 5 minutes) — there are no lockless writes.
+ *
+ * LEGACY MIGRATION: header-less files are read as-is (the manifest is
+ * stripped only when line 1 parses as one); the first throttled maintenance
+ * fold rewrites them manifest-first in bounded compactMaxBytes passes;
+ * close finalize drains to convergence. A crash mid-migration leaves either
+ * form, both readable.
+ *
+ * All functions are synchronous (house pattern). The `_internals` DI seam
+ * lets tests override filesystem operations and limits without `mock.module`
+ * (AGENTS.md invariant 7). State lives exclusively under `.swarm/session/`
+ * (invariant 4) — every function takes an explicit project-root `directory`.
+ * No `bun:` imports — Node-ESM-loadable (invariant 2).
+ */
+import * as fs from 'node:fs';
+export interface ShellAuditLimits {
+    /** Hard ceiling on the retained window (manifest line + decision lines). */
+    activeMaxBytes: number;
+    /** Hard ceiling on retained SECURITY-class (typed) decision lines. */
+    securityMaxEntries: number;
+    /** Hard ceiling on retained ALLOWED-class (legacy shell) decision lines. */
+    allowedMaxEntries: number;
+    /** ALLOWED-class retention age; older allowed decisions fold into the header. */
+    allowedAgeMaxMs: number;
+    /** Bounded fold work per maintenance pass (bytes of folded lines). */
+    compactMaxBytes: number;
+    /** Hard documented read bound for public reads, independent of history. */
+    readMaxBytes: number;
+    /** Appends between throttled maintenance checks. */
+    checkInterval: number;
+    /** Disk-pressure/failure warning cooldown. */
+    warnCooldownMs: number;
+    /** Upper bound for a serialized manifest header (single line). */
+    headerMaxBytes: number;
+    /** Serialized single-decision bound; larger appends fail with a typed error. */
+    maxLineBytes: number;
+    /** Raw command truncation bound applied at line-shaping time. */
+    maxCommandChars: number;
+    /** Free-text (reason) truncation bound applied at line-shaping time. */
+    maxReasonChars: number;
+    /**
+     * Hard bound on any single whole-file store read. A legacy header-less
+     * file larger than this migrates through the bounded STREAMING reader
+     * (chunked line folding) instead of being materialized whole (review
+     * round RC-2: the legacy path is exactly the file that lacks the
+     * activeMaxBytes ceiling).
+     */
+    migrationMaxBytes: number;
+}
+export declare const SHELL_AUDIT_LIMITS: ShellAuditLimits;
+export type ShellAuditDecisionClass = 'security' | 'allowed';
+/** Size-bounded folded aggregate persisted in the manifest header. FOLDED-ONLY:
+ *  decisions compacted/cut away from the retained window. Retained decisions
+ *  are NOT in here. Lifetime totals = folded + retained. */
+export interface ShellAuditFolded {
+    totalDecisions: number;
+    /** Per-discriminator counts, capped at 16 distinct keys + "other". */
+    byType: Record<string, number>;
+    corrupt: number;
+    dropped: number;
+    oldestTimestamp: string | null;
+    newestTimestamp: string | null;
+}
+export interface ShellAuditManifest {
+    v: 1;
+    type: 'swarm-shell-audit-manifest';
+    schemaVersion: number;
+    folded: ShellAuditFolded;
+    updatedAt: string;
+}
+export declare const _internals: {
+    readonly appendFileSync: typeof fs.appendFileSync;
+    readonly readFileSync: typeof fs.readFileSync;
+    readonly existsSync: typeof fs.existsSync;
+    readonly mkdirSync: typeof fs.mkdirSync;
+    readonly statSync: fs.StatSyncFn;
+    readonly renameSync: typeof fs.renameSync;
+    readonly writeFileSync: typeof fs.writeFileSync;
+    readonly unlinkSync: typeof fs.unlinkSync;
+    readonly openSync: typeof fs.openSync;
+    readonly closeSync: typeof fs.closeSync;
+    readonly readSync: typeof fs.readSync;
+    readonly now: () => number;
+    readonly limits: ShellAuditLimits;
+    readonly emitHealth: typeof emitShellAuditHealth;
+};
+export declare function shellAuditFilePath(directory: string): string;
+export type ShellAuditCoverage = 'complete' | 'truncated' | 'empty';
+/** The bounded view of the retained window. `text` is manifest-stripped
+ *  decision lines in append order (never starting mid-line). */
+export interface ShellAuditReadResult {
+    text: string;
+    truncated: boolean;
+    coverage: ShellAuditCoverage;
+}
+export interface ShellAuditStoreLock {
+    /** Release the lock (idempotent). */
+    release: () => void;
+}
+/**
+ * Acquire the exclusive store lock with a brief bounded retry, then run `fn`
+ * while holding it. Returns null when the lock stays contended for the whole
+ * retry window — callers map that onto their existing error contract (the
+ * audit append path is fail-open: catch + debug log, never block the tool).
+ */
+export declare function withShellAuditStoreLock<T>(directory: string, fn: () => T): T | null;
+/** Test seam (AGENTS.md invariant 7): reset module-scoped maintenance
+ *  counters between tests. Restore by calling in `afterEach`. */
+export declare function _resetMaintenanceCounters(): void;
+/**
+ * Bounded read of the retained window: the newest `readMaxBytes` of decision
+ * lines, manifest-stripped, in append order. `truncated` means older history
+ * exists beyond the read bound (a legacy header-less file larger than the
+ * bound, or a store mid-drain) — callers disclose it, never silently treat
+ * the window as complete history.
+ */
+export declare function readShellAuditTail(directory: string, maxBytes?: number): ShellAuditReadResult;
+/** Manifest folded summary via a header-only bounded read (null when the file
+ *  is absent or still header-less/legacy). */
+export declare function getShellAuditFoldedSummary(directory: string): ShellAuditFolded | null;
+/** Typed store-busy error — the audit append path maps it onto its existing
+ *  fail-open contract (catch + debug log; never block the tool call). */
+export declare const SHELL_AUDIT_STORE_LOCKED = "SHELL_AUDIT_STORE_LOCKED";
+export declare const SHELL_AUDIT_LINE_TOO_LARGE = "SHELL_AUDIT_LINE_TOO_LARGE";
+/**
+ * Append one serialized decision line to the store through the canonical
+ * seam. The caller (audit-log.ts) has already validated the entry shape and
+ * applied write-time redaction; this function owns framing, locking, and
+ * retention.
+ *
+ * - Holds the store lock for the write; re-establishes line framing when a
+ *   prior crash tore the tail (newline prefix).
+ * - First write on a fresh store is atomic (manifest + one line) so a crash
+ *   can never leave a torn header at line 1.
+ * - A legacy header-less file is appended to as-is; the throttled maintenance
+ *   pass migrates it manifest-first in bounded passes.
+ * - Runs throttled maintenance (bounded compaction / legacy drain) every
+ *   `checkInterval` appends, after the lock is released.
+ *
+ * Throws `SHELL_AUDIT_STORE_LOCKED` after bounded lock retry, or
+ * `SHELL_AUDIT_LINE_TOO_LARGE` for oversized lines — the audit append path
+ * catches both and logs non-fatally (logging failure never blocks a tool).
+ */
+export declare function appendShellAuditLineSync(directory: string, line: string): void;
+/** External compaction trigger. Fail-open. */
+export declare function compactShellAudit(directory: string): void;
+/**
+ * Close finalize (issue #2040 requirement 7): under one lock acquisition,
+ * drain any legacy header-less file to convergence and fold the remaining
+ * window into a defined, VALIDATED cut (the atomicReplace pre-rename
+ * validation), which `/swarm close` then archives as part of the session
+ * directory copy. Fail-open: never throws to the close pipeline. Releasing
+ * the lock also unlinks it, so a stale lock file is never archived.
+ *
+ * `options.lineTransform` (review round F4): when provided, every retained
+ * decision line is passed through it before the final validated rewrite —
+ * the close pipeline supplies the CURRENT redaction policy so a legacy
+ * record with weaker pre-#2040 redaction cannot bypass it in the archived
+ * cut ("re-redact at the archive boundary").
+ */
+export declare function finalizeShellAuditForClose(directory: string, options?: {
+    lineTransform?: (line: string) => string;
+}): void;
+declare function emitShellAuditHealth(directory: string, payload: {
+    trigger: 'compaction' | 'close';
+    accepted: number;
+    compacted: number;
+    retained: number;
+    dropped: number;
+    corrupt: number;
+    oldest: string | null;
+    newest: string | null;
+    bytes: number;
+    limitBytes: number;
+}): void;
+export {};

package/dist/hooks/guardrails/tool-before.d.ts

@@ -23,8 +23,6 @@ export interface ToolBeforeContext {
     precomputedAuthorityRules: Record<string, AgentRule>;
     /** Global deny prefixes — apply to all agents regardless of per-agent rules */
     universalDenyPrefixes: string[];
-    /** Shell audit log path */
-    shellAuditPath: string;
     /** Whether shell audit logging is enabled */
     shellAuditEnabled: boolean;
     /** Agents allowed to use bash/shell interpreter (undefined = all allowed) */