opencode-swarm 7.152.1 → 7.153.1

package/dist/learning/provenance.d.ts

@@ -17,6 +17,7 @@
  * supply `producedAt` — callers that need determinism pass it explicitly.
  */
 import { z } from 'zod';
+import { type WriteAuthorityOrigin } from '../security/write-authority.js';
 /**
  * Hard cap on entries retained per reference class. Sorting happens before the
  * cap so truncation is deterministic rather than insertion-order dependent.
@@ -41,6 +42,12 @@ export declare const LearningProvenanceV1Schema: z.ZodObject<{
     writeOrigin: z.ZodObject<{
         sessionId: z.ZodOptional<z.ZodString>;
         agentRole: z.ZodOptional<z.ZodString>;
+        authority: z.ZodOptional<z.ZodEnum<{
+            critic_approved: "critic_approved";
+            autonomous: "autonomous";
+            optimizer_proposed: "optimizer_proposed";
+            human_approved: "human_approved";
+        }>>;
         producedAt: z.ZodISODateTime;
     }, z.core.$strict>;
 }, z.core.$strict>;
@@ -56,6 +63,7 @@ export interface LearningProvenanceV1 {
     writeOrigin: {
         sessionId?: string;
         agentRole?: string;
+        authority?: WriteAuthorityOrigin;
         producedAt: string;
     };
 }
@@ -72,6 +80,7 @@ export interface LearningProvenanceInput {
 export interface LearningWriteOriginInput {
     sessionId?: string;
     agentRole?: string;
+    authority?: WriteAuthorityOrigin;
     producedAt?: string;
 }
 /**

package/dist/observability/catalog.d.ts

@@ -1,7 +1,7 @@
 /**
  * The event catalog (issue #2029).
  *
- * Exactly 49 entries, matching the `TelemetryEvent` union at
+ * Exactly 50 entries, matching the `TelemetryEvent` union at
  * `src/telemetry.ts:15-131`. Thirty-eight predate the #2029 contract; the 39th is
  * `agent_conflict_detected` (previously emitted through a force-cast past the
  * type system), the 40th is `close_archive_result` (issue #2030 — the
@@ -16,9 +16,11 @@
  * `skill_usage_health` storage audit for the issue-#2038
  * `.swarm/skill-usage.jsonl` store and its authoritative pending sidecar,
  * the 48th is the bounded `core_events_health` storage audit for the
- * issue-#2039 `.swarm/events.jsonl` store, and the 49th is the bounded
+ * issue-#2039 `.swarm/events.jsonl` store, the 49th is the bounded
  * `shell_audit_health` storage audit for the issue-#2040
- * `.swarm/session/shell-audit.jsonl` security-audit store. These late additions are instances
+ * `.swarm/session/shell-audit.jsonl` security-audit store, and the 50th is
+ * the bounded `trajectory_health` storage audit for the issue-#2041
+ * `.swarm/trajectories/` PRM session store. These late additions are instances
  * of the defect class this contract exists to close: an event kind entering
  * the stream with no registration.
  *
@@ -73,7 +75,7 @@ export interface CatalogEntry {
     /**
      * Whether an event of this kind must carry `trace.parentSpanId`.
      *
-     * `false` for all 49 entries today, and that is a truthful statement about
+     * `false` for all 50 entries today, and that is a truthful statement about
      * the current system rather than a placeholder: no producer supplies a
      * parent span, so `createObservation` never sets one. Setting this to `true`
      * for a kind whose producer cannot supply a parent would make every

package/dist/prm/index.d.ts

@@ -26,7 +26,7 @@ import { formatCourseCorrectionForInjection, generateCourseCorrection } from './
 import { EscalationTracker } from './escalation';
 import { detectPatterns } from './pattern-detector';
 import { recordReplayEntry, startReplayRecording } from './replay';
-import { cleanupOldTrajectoryFiles, clearTrajectoryCache, getInMemoryTrajectory, readTrajectory } from './trajectory-store';
+import { clearTrajectoryCache, getInMemoryTrajectory, readTrajectoryWithCoverage, scheduleTrajectoryCleanup } from './trajectory-store';
 import type { PrmConfig } from './types';
 /**
  * Test-only dependency-injection seam — see `gitignore-warning.ts:_internals`.
@@ -38,12 +38,12 @@ import type { PrmConfig } from './types';
  */
 export declare const _internals: {
     getAgentSession: typeof getAgentSession;
-    readTrajectory: typeof readTrajectory;
+    readTrajectoryWithCoverage: typeof readTrajectoryWithCoverage;
     getInMemoryTrajectory: typeof getInMemoryTrajectory;
     detectPatterns: typeof detectPatterns;
     generateCourseCorrection: typeof generateCourseCorrection;
     formatCourseCorrectionForInjection: typeof formatCourseCorrectionForInjection;
-    cleanupOldTrajectoryFiles: typeof cleanupOldTrajectoryFiles;
+    scheduleTrajectoryCleanup: typeof scheduleTrajectoryCleanup;
     clearTrajectoryCache: typeof clearTrajectoryCache;
     recordReplayEntry: typeof recordReplayEntry;
     startReplayRecording: typeof startReplayRecording;

package/dist/prm/replay.d.ts

@@ -60,8 +60,25 @@ declare function sanitizeFilename(input: string): string;
  */
 export declare function startReplayRecording(sessionID: string, directory: string): Promise<string | null>;
 /**
- * Appends a ReplayEntry to the replay artifact file.
- * Non-blocking: errors are caught and logged, never thrown.
+ * Hard budgets for replay artifacts (issue #2041 Required 1 — the PRM budget
+ * set covers replays as well as trajectories). Replays are write-only
+ * best-effort diagnostics: at the cap, further entries for that artifact are
+ * skipped with a one-time warning rather than rotated (rotation would create
+ * unbounded sibling files, which is exactly what this cap exists to prevent).
+ * The 7-day age sweep + per-directory count cap in trajectory-store's
+ * `cleanupOldTrajectoryFiles` bound the directory as a whole.
+ */
+export declare const REPLAY_LIMITS: {
+    /** Per-artifact byte ceiling. */
+    readonly maxBytes: number;
+    /** Stat cadence per artifact (bytes are tracked in memory between stats). */
+    readonly checkIntervalEntries: 16;
+    /** Bound on tracked artifacts (Invariant 8). */
+    readonly maxTrackedArtifacts: 256;
+};
+/**
+ * Appends a ReplayEntry to the replay artifact file, enforcing the per-artifact
+ * byte cap. Non-blocking: errors are caught and logged, never thrown.
  *
  * @param artifactPath - Path to the replay artifact file
  * @param sessionID - Session identifier
@@ -72,5 +89,15 @@ export declare const _test_exports: {
     readonly isPathSafe: typeof isPathSafe;
     readonly isWithinReplaysDir: typeof isWithinReplaysDir;
     readonly sanitizeFilename: typeof sanitizeFilename;
+    readonly REPLAY_LIMITS: {
+        /** Per-artifact byte ceiling. */
+        readonly maxBytes: number;
+        /** Stat cadence per artifact (bytes are tracked in memory between stats). */
+        readonly checkIntervalEntries: 16;
+        /** Bound on tracked artifacts (Invariant 8). */
+        readonly maxTrackedArtifacts: 256;
+    };
+    /** Test isolation: drop per-artifact byte-cap bookkeeping. */
+    readonly resetReplayByteTracking: () => void;
 };
 export {};

package/dist/prm/trajectory-store.d.ts

@@ -1,40 +1,215 @@
 /**
- * TRAJECTORY STORE (Session-Level)
+ * TRAJECTORY STORE (Session-Level) — bounded (issue #2041)
  *
  * Per-session trajectory storage for PRM pattern detection.
- * Writes to .swarm/trajectories/{sessionId}.jsonl
+ * Writes to .swarm/trajectories/{sessionId}.jsonl (+ a small
+ * {sessionId}.jsonl.meta.json checkpoint and a transient {sessionId}.jsonl.lock).
+ *
+ * Bounded session-trajectory contract (mirrors the #2040 shell-audit store):
+ * - ONE knob, `maxLines`, governs BOTH the in-memory cache trim and the disk
+ *   compaction: over budget, the newest floor(maxLines/2) entries are retained
+ *   (the cache has always used exactly this rule — the disk now matches it).
+ * - The disk byte ceiling sessionMaxBytesFor(maxLines) is SOVEREIGN and is
+ *   enforced at APPEND time (the stat needed for torn-tail re-framing doubles
+ *   as the size probe): over ceiling, compaction runs before the append.
+ * - A line-count check runs every `checkIntervalAppends` appends (the only
+ *   part that needs a read; it is tail-bounded, never a whole-file read).
+ * - Readers (`readTrajectory`, `getCurrentStep`) read a bounded tail window and
+ *   disclose coverage; `getCurrentStep` also consults the atomically persisted
+ *   checkpoint so a restart never scans history to continue step numbering.
+ * - Crash semantics: compaction publishes via tmp+rename (a partial rewrite is
+ *   never visible); the checkpoint is written after the data rewrite under the
+ *   same lock, and merges `max(previous, observed)` so it can only ratchet UP.
+ *   Compaction keeps the NEWEST entries, so the global max step always survives
+ *   on disk — except when every retained line is corrupt, in which case the
+ *   checkpoint alone preserves step continuity (that is why it exists).
+ * - Two writers: an in-process per-key promise chain (same-process appends
+ *   never burn the cross-process retry budget) plus a per-file `.lock`
+ *   (wx existence create — the PID inside is diagnostic only, never
+ *   liveness-checked — stale-break, bounded retry). Lock exhaustion skips the
+ *   append with a warning — telemetry loss is preferred over file corruption
+ *   in this best-effort store — and is counted into `trajectory_health`.
  *
  * Coexists with task-level trajectory-logger.ts which writes to
- * .swarm/evidence/{taskId}/trajectory.jsonl for audit/evidence.
+ * .swarm/evidence/{taskId}/trajectory.jsonl for audit/evidence (bounded by its
+ * own write-side truncation; untouched by this contract).
  */
+import { telemetry } from '../telemetry';
 import type { TrajectoryEntry } from './types';
+/**
+ * Hard budgets for the bounded session-trajectory contract (issue #2041).
+ * Exported for tests and for the retention registry's documented contract.
+ */
+export declare const TRAJECTORY_LIMITS: {
+    /** Line-count compaction check cadence (append-path, amortized). */
+    readonly checkIntervalAppends: 25;
+    /** Tail-bounded read window for readTrajectoryWithCoverage. */
+    readonly readMaxBytes: number;
+    /** Tail-bounded read window for getCurrentStep (newest lines carry max step). */
+    readonly stepReadMaxBytes: number;
+    /** Tail-bounded input window for compaction (legacy files may be huge). */
+    readonly compactMaxBytes: number;
+    /** A JSONL line longer than this is shed as oversize (append skips it). */
+    readonly maxLineBytes: number;
+    /** Estimated bytes per entry used to derive the per-session byte ceiling. */
+    readonly estimatedLineBytes: 512;
+    /** Floor for the derived per-session byte ceiling. */
+    readonly minSessionMaxBytes: number;
+    /** Per-file cross-process lock: bounded retries, then skip + warn. */
+    readonly lockRetries: 20;
+    readonly lockRetryDelayMs: 5;
+    /** A lock older than this is considered crashed and broken. */
+    readonly lockStaleMs: number;
+    /** Per-directory session-file count cap (age-sweep backstop). */
+    readonly maxFilesPerDir: 200;
+    /** Unlinks per cleanup invocation (converges across runs). */
+    readonly maxDeletionsPerRun: 256;
+    /** Default age sweep horizon for trajectories/ and replays/. */
+    readonly defaultMaxAgeDays: 7;
+    /** Debounce for the lazily scheduled cleanup pass. */
+    readonly cleanupDebounceMs: number;
+    /** Cooldown for append_skip health events (lock-exhaust observability). */
+    readonly appendSkipEventCooldownMs: 60000;
+};
+/**
+ * Sovereign per-session disk byte ceiling, derived from the same `maxLines`
+ * knob that governs cache trimming and line-count compaction.
+ */
+export declare function sessionMaxBytesFor(maxLines: number): number;
+/** Test/DI seam — see `gitignore-warning.ts:_internals` for the convention. */
+export declare const _internals: {
+    telemetry: typeof telemetry;
+};
 /**
  * Returns cached trajectory entries for a session (empty array if not cached).
+ *
+ * @param sessionId - Session identifier
+ * @param directory - Workspace root that owns the session's trajectory file
  */
-export declare function getInMemoryTrajectory(sessionId: string): TrajectoryEntry[];
+export declare function getInMemoryTrajectory(sessionId: string, directory: string): TrajectoryEntry[];
 /**
  * Clears trajectory cache (for test isolation or session cleanup).
+ *
+ * With a sessionId but no directory, every root's entry for that session is
+ * cleared (suffix scan over the bounded map) — reset paths that legitimately
+ * lack a directory still release the cached window.
  */
 export declare function clearTrajectoryCache(sessionId?: string): void;
+interface TrajectoryCheckpoint {
+    version: 1;
+    highestStep: number;
+    droppedEntries: number;
+    /**
+     * Cumulative bytes discarded whole — chiefly the pre-window portion of an
+     * oversized file that a tail-bounded compaction rewrote away (shed
+     * windowed entries also contribute their bytes here, alongside their
+     * counts in droppedEntries: the two metrics are independent dimensions
+     * of the same loss). Without this, a compaction whose window kept every
+     * windowed entry (droppedEntries delta 0) would silently erase megabytes
+     * beyond the window while coverage still reported `complete`. Optional
+     * on READ for checkpoints written before this field existed.
+     */
+    droppedBytes?: number;
+    compactedAt: string;
+}
+/**
+ * Reads a session's persisted step checkpoint (null when absent/corrupt).
+ *
+ * Production consumers: `getCurrentStep` (restart continuity) and the consensus
+ * corpus's default PRM coverage signal (dropped-by-compaction disclosure).
+ */
+export declare function readTrajectoryCheckpoint(sessionId: string, directory: string): Promise<TrajectoryCheckpoint | null>;
+/**
+ * One bounded stat of a session's trajectory file (null when absent).
+ *
+ * Production consumer: the consensus corpus's default PRM coverage verdict —
+ * a file larger than the read window means the live bounded read was
+ * window-truncated, exactly matching `readTrajectoryWithCoverage`'s coverage
+ * semantics so the two paths cannot diverge (implementation-review round 1).
+ */
+export declare function trajectoryFileBytes(sessionId: string, directory: string): Promise<number | null>;
 /**
- * Appends a single TrajectoryEntry to the session's trajectory file.
+ * Appends a single TrajectoryEntry to the session's trajectory file, enforcing
+ * the bounded session-trajectory contract on disk as well as in memory.
  *
  * @param sessionId - Session identifier
  * @param entry - Trajectory entry to append
  * @param directory - Base directory (workspace root)
- * @param maxLines - Maximum lines before in-memory cache trimming (default 1000)
+ * @param maxLines - Line budget for BOTH the in-memory cache trim and disk
+ *   compaction (compaction retains the newest floor(maxLines/2) entries; the
+ *   derived byte ceiling sessionMaxBytesFor(maxLines) is sovereign)
  */
 export declare function appendTrajectoryEntry(sessionId: string, entry: TrajectoryEntry, directory: string, maxLines?: number): Promise<void>;
+export type TrajectoryCoverage = 'complete' | 'truncated' | 'empty';
+export interface TrajectoryReadWithCoverage {
+    entries: TrajectoryEntry[];
+    coverage: TrajectoryCoverage;
+    /** Entries removed by prior compactions (persisted checkpoint total). */
+    droppedByCompaction: number;
+    skippedMalformed: number;
+}
 /**
- * Reads all TrajectoryEntry records from a session's trajectory file.
+ * Tail-bounded read of a session's trajectory with explicit coverage
+ * disclosure (issue #2041 Required 3/4). Reads at most
+ * TRAJECTORY_LIMITS.readMaxBytes regardless of file size; the returned entries
+ * are the newest window in file order.
+ *
+ * `maxLines` is the SAME knob the append path uses: a cold read populates the
+ * in-memory cache trimmed to the configured budget, so a legacy pre-fix file
+ * cannot inflate the cache PRM pattern detection reads (review round 1).
+ */
+export declare function readTrajectoryWithCoverage(sessionId: string, directory: string, maxLines?: number): Promise<TrajectoryReadWithCoverage>;
+/**
+ * Reads the newest bounded window of TrajectoryEntry records from a session's
+ * trajectory file.
  *
  * @param sessionId - Session identifier
  * @param directory - Base directory (workspace root)
+ * @param maxLines - Optional cache-trim budget (same knob as the append path)
  * @returns Array of trajectory entries (empty array if file doesn't exist)
  */
-export declare function readTrajectory(sessionId: string, directory: string): Promise<TrajectoryEntry[]>;
+export declare function readTrajectory(sessionId: string, directory: string, maxLines?: number): Promise<TrajectoryEntry[]>;
 export declare const _test_exports: {
     readonly MAX_TRACKED_TRAJECTORY_SESSIONS: 500;
+    readonly TRAJECTORY_LIMITS: {
+        /** Line-count compaction check cadence (append-path, amortized). */
+        readonly checkIntervalAppends: 25;
+        /** Tail-bounded read window for readTrajectoryWithCoverage. */
+        readonly readMaxBytes: number;
+        /** Tail-bounded read window for getCurrentStep (newest lines carry max step). */
+        readonly stepReadMaxBytes: number;
+        /** Tail-bounded input window for compaction (legacy files may be huge). */
+        readonly compactMaxBytes: number;
+        /** A JSONL line longer than this is shed as oversize (append skips it). */
+        readonly maxLineBytes: number;
+        /** Estimated bytes per entry used to derive the per-session byte ceiling. */
+        readonly estimatedLineBytes: 512;
+        /** Floor for the derived per-session byte ceiling. */
+        readonly minSessionMaxBytes: number;
+        /** Per-file cross-process lock: bounded retries, then skip + warn. */
+        readonly lockRetries: 20;
+        readonly lockRetryDelayMs: 5;
+        /** A lock older than this is considered crashed and broken. */
+        readonly lockStaleMs: number;
+        /** Per-directory session-file count cap (age-sweep backstop). */
+        readonly maxFilesPerDir: 200;
+        /** Unlinks per cleanup invocation (converges across runs). */
+        readonly maxDeletionsPerRun: 256;
+        /** Default age sweep horizon for trajectories/ and replays/. */
+        readonly defaultMaxAgeDays: 7;
+        /** Debounce for the lazily scheduled cleanup pass. */
+        readonly cleanupDebounceMs: number;
+        /** Cooldown for append_skip health events (lock-exhaust observability). */
+        readonly appendSkipEventCooldownMs: 60000;
+    };
+    readonly sessionMaxBytesFor: typeof sessionMaxBytesFor;
+    readonly getCacheSize: () => number;
+    readonly getChainSize: () => number;
+    /** Test isolation: the cleanup debounce is module-global state. */
+    readonly resetCleanupDebounce: () => void;
+    /** Test isolation: lock-skip counters are module-global state. */
+    readonly resetLockSkipCounters: () => void;
+    readonly appendFileIsTorn: (filePath: string) => Promise<boolean>;
 };
 /**
  * Alias for readTrajectory - retrieves trajectory entries for a session.
@@ -44,17 +219,16 @@ export declare const _test_exports: {
  * @returns Array of trajectory entries
  */
 export declare function getTrajectoryForSession(sessionId: string, directory: string): Promise<TrajectoryEntry[]>;
-/**
- * Truncates the trajectory file to the newest half if lines exceed maxLines.
- *
- * @param sessionId - Session identifier
- * @param directory - Base directory (workspace root)
- * @param maxLines - Maximum number of lines to retain
- */
-export declare function truncateTrajectoryIfNeeded(sessionId: string, directory: string, maxLines: number): Promise<void>;
 /**
  * Returns the highest step number in the session's trajectory.
- * Used to determine the next step number when appending.
+ * Used to determine the next step number when appending — the production
+ * restart-seeding path in trajectory-logger.ts calls this before the first
+ * mint of a session so step numbers stay monotonic across process restarts.
+ *
+ * Bounded: reads at most TRAJECTORY_LIMITS.stepReadMaxBytes of the file
+ * (the newest lines carry the max step) and merges the atomically persisted
+ * checkpoint, so a restart never scans unbounded history — and the high-water
+ * mark survives even a fully-corrupt data file.
  *
  * @param sessionId - Session identifier
  * @param directory - Base directory (workspace root)
@@ -62,8 +236,24 @@ export declare function truncateTrajectoryIfNeeded(sessionId: string, directory:
  */
 export declare function getCurrentStep(sessionId: string, directory: string): Promise<number>;
 /**
- * Deletes trajectory and replay files older than maxAgeDays.
- * Runs against .swarm/trajectories/ and .swarm/replays/ directories.
- * Non-blocking: errors logged, not thrown.
+ * Debounced, fire-and-forget cleanup scheduling used by the PRM hook's
+ * once-per-session trigger. The plugin's post-resolution init pass calls
+ * `cleanupOldTrajectoryFiles` directly (the debounce must not suppress the
+ * startup sweep).
+ */
+export declare function scheduleTrajectoryCleanup(directory: string): void;
+/**
+ * Deletes aged trajectory and replay files, then enforces a per-directory
+ * session-file count cap (oldest-first) so a hostile or skewed mtime cannot
+ * grow `.swarm/trajectories/` or `.swarm/replays/` without bound. A session's
+ * `.meta.json` checkpoint is removed with its `.jsonl`; orphan checkpoints and
+ * stale atomic-write `*.tmp` leftovers age out on their own. Bounded to
+ * maxDeletionsPerRun unlinks per invocation (converges across runs); every
+ * failure is swallowed. Never touches `.swarm/evidence/` (task evidence is a
+ * different directory tree governed by its own contract).
+ *
+ * Replays and trajectories are independent artifacts sharing this sweep: no
+ * cross-linkage is enforced or implied.
  */
 export declare function cleanupOldTrajectoryFiles(directory: string, maxAgeDays?: number): Promise<void>;
+export {};

package/dist/sandbox/capability-probe.d.ts

@@ -9,6 +9,8 @@
  * Each probe is bounded to 2 seconds via AbortController to satisfy
  * Invariant 1 (plugin init is fast, bounded, fail-open).
  */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
 /** Possible sandbox status values. */
 export type SandboxStatus = 'enabled' | 'disabled' | 'unsupported';
 /**
@@ -20,6 +22,7 @@ export type SandboxStatus = 'enabled' | 'disabled' | 'unsupported';
  *   (issue #1778 H2).
  */
 export type SandboxStrength = 'strong' | 'advisory';
+export type SandboxDimensionStrength = 'real' | 'weak' | 'none';
 /** Result of a sandbox capability probe. */
 export interface SandboxCapability {
     /** Whether the sandbox mechanism is available. */
@@ -36,6 +39,37 @@ export interface SandboxCapability {
     /** Error message from the probe, if any. */
     error?: string;
 }
+export interface SandboxCapabilityV1 extends SandboxCapability {
+    v: 1;
+    filesystem: SandboxDimensionStrength;
+    network: SandboxDimensionStrength;
+    process: SandboxDimensionStrength;
+    effective: SandboxDimensionStrength;
+    reasons: string[];
+    identity: string;
+}
+export interface SandboxRequirements {
+    mode?: 'advisory' | 'required';
+    require_filesystem?: boolean;
+    require_network?: boolean;
+    require_process?: boolean;
+    network_mode?: 'off' | 'on';
+    network_allowlist?: readonly string[];
+    writable_roots?: readonly string[];
+}
+export declare function assessSandboxRequirements(capability: SandboxCapabilityV1, requirements: SandboxRequirements | undefined): {
+    satisfied: boolean;
+    missing: string[];
+};
+interface BehavioralEvidence {
+    filesystem: SandboxDimensionStrength;
+    network: SandboxDimensionStrength;
+    process: SandboxDimensionStrength;
+    reasons: string[];
+}
+declare function currentProbeSourceIdentity(platform: 'linux' | 'darwin' | 'win32'): string;
+declare function resolveWindowsCommandProcessorBinary(): string;
+declare function detectBehavioralEvidence(capability: SandboxCapability): BehavioralEvidence;
 /** Reset the session-lifetime capability cache. Test-only. */
 export declare function _resetCapabilityCache(): void;
 /**
@@ -56,6 +90,11 @@ declare function withProbeTimeout(cmd: string, args: string[], ms: number): Prom
  */
 export declare const _internals: {
     withProbeTimeout: typeof withProbeTimeout;
+    spawnSync: typeof spawnSync;
+    detectBehavioralEvidence: typeof detectBehavioralEvidence;
+    resolveWindowsCommandProcessorBinary: typeof resolveWindowsCommandProcessorBinary;
+    currentProbeSourceIdentity: typeof currentProbeSourceIdentity;
+    removeProbeTempRoot: typeof fs.rmSync;
 };
 /**
  * Detects the availability of OS-native sandbox mechanisms.
@@ -86,6 +125,6 @@ export declare class SandboxCapabilityProbe {
      *
      * @returns A promise that resolves to the sandbox capability result.
      */
-    detect(): Promise<SandboxCapability>;
+    detect(): Promise<SandboxCapabilityV1>;
 }
 export {};

package/dist/sandbox/executor.d.ts

@@ -4,6 +4,7 @@
  * Provides a unified interface for sandboxed shell command execution across
  * Linux (Bubblewrap), macOS (sandbox-exec), and Windows (restricted token/Low Integrity).
  */
+import { type SandboxCapabilityV1, type SandboxRequirements } from './capability-probe';
 /**
  * Error thrown when sandbox operations fail.
  */
@@ -11,6 +12,7 @@ export declare class SandboxError extends Error {
     readonly code: string;
     constructor(message: string, code: string);
 }
+export declare function normalizeSandboxMechanism(mechanism: string): string;
 /**
  * Validate that a string is a valid POSIX environment variable name.
  * POSIX env var names: [a-zA-Z_][a-zA-Z0-9_]*
@@ -43,13 +45,33 @@ export interface SandboxExecutor {
      * @returns The wrapped command string with sandbox prefix
      * @throws SandboxError if sandbox cannot wrap the command
      */
-    wrapCommand(command: string, scopePaths: string[], tempDir?: string, envOverrides?: Record<string, string | null>): string;
+    wrapCommand(command: string, scopePaths: string[], tempDir?: string, envOverrides?: Record<string, string | null>, policy?: SandboxPolicyOptions): string;
     /**
      * Get the environment variable overrides for this sandbox.
      * Returns a record of env vars to set/unset.
      */
     getEnvOverrides(): Record<string, string | null>;
 }
+export interface SandboxPolicyOptions {
+    network_mode?: 'off' | 'on';
+    network_allowlist?: readonly string[];
+    writable_roots?: readonly string[];
+}
+declare function detectSandboxCapability(): Promise<SandboxCapabilityV1>;
+export declare const _internals: {
+    detectSandboxCapability: typeof detectSandboxCapability;
+};
+export interface SandboxEnforcementAssessment {
+    capability: SandboxCapabilityV1;
+    requirements: Required<SandboxRequirements>;
+    policy: Required<SandboxPolicyOptions>;
+    satisfied: boolean;
+    missing: string[];
+    supported: boolean;
+    unsupported: string[];
+    cacheKey: string;
+}
+export declare function assessSandboxEnforcement(requirements: SandboxRequirements | undefined): Promise<SandboxEnforcementAssessment>;
 /**
  * Get the platform-appropriate sandbox executor.
  *
@@ -80,3 +102,6 @@ export declare function _getMacOSSandboxPolicyForTest(): boolean;
  * @internal
  */
 export declare function _resetExecutorCache(): void;
+/** @internal test seam */
+export declare function _resetSandboxAssessmentCache(): void;
+export {};

package/dist/sandbox/linux/bubblewrap-executor.d.ts

@@ -75,7 +75,9 @@ export declare class BubblewrapSandboxExecutor implements SandboxExecutor {
      * @returns A bwrap-wrapped command string ready for shell execution,
      *          or the raw command string when the sandbox is unavailable (passthrough mode)
      */
-    wrapCommand(command: string, scopePaths: string[], tempDir?: string, envOverrides?: Record<string, string | null>): string;
+    wrapCommand(command: string, scopePaths: string[], tempDir?: string, envOverrides?: Record<string, string | null>, policy?: {
+        network_mode?: 'off' | 'on';
+    }): string;
     /**
      * Return environment variable overrides required for the bubblewrap sandbox.
      *

package/dist/sandbox/macos/sandbox-exec-executor.d.ts

@@ -104,7 +104,9 @@ export declare class MacOSSandboxExecutor implements SandboxExecutor {
      * @returns A sandbox-exec wrapped command string ready for shell execution,
      *          or the raw command string when the sandbox is unavailable (passthrough mode)
      */
-    wrapCommand(command: string, scopePaths: string[], tempDir?: string, envOverrides?: Record<string, string | null>): string;
+    wrapCommand(command: string, scopePaths: string[], tempDir?: string, envOverrides?: Record<string, string | null>, _policy?: {
+        network_mode?: 'off' | 'on';
+    }): string;
     /**
      * Return environment variable overrides required for the macOS sandbox.
      *

package/dist/sandbox/skip-state.d.ts

@@ -0,0 +1,24 @@
+export interface SandboxWrapOutcome {
+    sessionID: string;
+    callID: string;
+    originalCommandHash: number;
+    finalCommandHash: number;
+    wrapped: boolean;
+    capabilityIdentity: string;
+    assessmentCacheKey: string;
+    reason: string;
+    originalCommand: string;
+    executorMechanism: string;
+    capabilityMechanism: string;
+}
+export declare function recordSandboxWrapOutcome(outcome: SandboxWrapOutcome): void;
+export declare function readSandboxWrapOutcome(sessionID: string, callID: string): SandboxWrapOutcome | null;
+export declare function clearSandboxWrapOutcome(sessionID: string, callID: string): void;
+export declare function getSandboxSkipSummary(sessionID?: string): {
+    count: number;
+    reasons: readonly string[];
+};
+/** @internal test seam */
+export declare function _resetSandboxWrapOutcomeState(): void;
+/** @internal test seam */
+export declare function _sandboxWrapOutcomeStateSize(): number;

package/dist/sandbox/win32/native-sandbox-executor.d.ts

@@ -37,7 +37,11 @@ export declare class NativeWindowsSandboxExecutor implements SandboxExecutor {
      *
      * When the runner is unavailable, falls back to the PowerShell wrapper.
      */
-    wrapCommand(command: string, scopePaths: string[], tempDir?: string, envOverrides?: Record<string, string | null>): string;
+    wrapCommand(command: string, scopePaths: string[], tempDir?: string, envOverrides?: Record<string, string | null>, policy?: {
+        network_mode?: 'off' | 'on';
+        network_allowlist?: readonly string[];
+        writable_roots?: readonly string[];
+    }): string;
     private _wrapWithRunner;
     getEnvOverrides(): Record<string, string | null>;
     /**

package/dist/security/command-classifier.d.ts

@@ -0,0 +1,22 @@
+export type CommandRiskCategory = 'catastrophic' | 'destructive' | 'unknown' | 'escalate' | 'safe';
+export interface CommandSegmentClassificationV1 {
+    segment: string;
+    category: CommandRiskCategory;
+    reason: string;
+    ruleId?: string;
+}
+export interface CommandClassificationV1 {
+    v: 1;
+    originalDigest: string;
+    aggregate: CommandRiskCategory;
+    ambiguous: boolean;
+    segments: readonly CommandSegmentClassificationV1[];
+}
+export interface SharedClassifierGuardrailBlockV1 {
+    ruleId: string;
+    category: Extract<CommandRiskCategory, 'catastrophic' | 'destructive'>;
+    destructiveCategory: string;
+    message: string;
+}
+export declare function getSharedClassifierGuardrailBlock(classification: Readonly<CommandClassificationV1>): Readonly<SharedClassifierGuardrailBlockV1> | null;
+export declare function classifyCommand(original: string): Readonly<CommandClassificationV1>;

package/dist/security/protected-input-integrity.d.ts

@@ -0,0 +1,19 @@
+export interface ProtectedManifestV1 {
+    v: 1;
+    root: string;
+    digest: string;
+    entries: readonly string[];
+}
+/** Snapshot a protected regular-file tree; ambiguity and budget exhaustion fail closed. */
+export declare function snapshotProtectedTree(root: string): Promise<ProtectedManifestV1>;
+export declare function verifyProtectedTree(before: ProtectedManifestV1): Promise<void>;
+/** Mandatory transaction wrapper for governed evaluators. Verification always runs. */
+export declare function withProtectedInputIntegrity<T>(root: string, operation: () => Promise<T>): Promise<T>;
+export interface ProtectedSetManifestV1 {
+    v: 1;
+    roots: readonly string[];
+    states: readonly (ProtectedManifestV1 | 'missing')[];
+}
+export declare function snapshotProtectedSet(roots: readonly string[]): Promise<ProtectedSetManifestV1>;
+export declare function verifyProtectedSet(before: ProtectedSetManifestV1): Promise<void>;
+export declare function withProtectedSetIntegrity<T>(roots: readonly string[], operation: () => Promise<T>): Promise<T>;