@peac/cli 0.13.4 → 0.14.1

package/dist/lib/capture.d.ts

@@ -0,0 +1,118 @@
+/**
+ * CLI subprocess capture.
+ *
+ * Implements the bounded-capture wrapper used by `peac observe command`
+ * and `peac record command`. Hard implementation invariants:
+ *
+ *   - Spawn discipline: `spawn(prog, args, { shell: false })`
+ *     exclusively. NEVER `exec()`. The wrapper does NOT synthesize
+ *     shell syntax or rewrite the command. `--shell-mode` is
+ *     acknowledgement only.
+ *   - Streaming capture: `node:crypto.createHash` updated chunk-by-chunk.
+ *     Byte counter incremented chunk-by-chunk. Bounded sample buffer
+ *     is the ONLY buffer retained, and ONLY when raw capture is
+ *     double-opted-in. Full streams NEVER held in memory.
+ *   - Stdin: `--capture-stdin-mode` controls BOTH whether the wrapper
+ *     pipes parent stdin to the child AND what the wrapper records.
+ *     `none` (default) closes child stdin and does NOT read parent stdin.
+ *     The stdin pump must terminate when the child exits even if the
+ *     parent stream is still open.
+ *   - Timeout: `--timeout-ms` / `--kill-grace-ms` cascade SIGTERM then
+ *     SIGKILL; the record IS still emitted. The nested SIGKILL timer
+ *     is cleared on child close so it cannot keep the event loop alive.
+ *   - Signal exit codes follow POSIX `128 + signal-num`: SIGINT=130,
+ *     SIGTERM=143, SIGKILL=137; unknown signals fall back to 128.
+ *   - Stdin pumping is listener-based (event handlers attached to the
+ *     parent stream and child stdin). Backpressure pauses the parent
+ *     until child stdin emits 'drain'. The pump is reliably abortable
+ *     via an external AbortSignal even if the parent stream stays
+ *     open and idle, and removes ONLY pump-owned listeners on cleanup
+ *     (the parent is caller-owned).
+ */
+import type { Readable } from 'node:stream';
+/**
+ * Thrown by `captureCommand` when the child process fails to spawn
+ * (missing binary, ENOENT, EACCES, etc.). Node emits the `'error'`
+ * event in this case and never emits `'spawn'`/`'close'` -- without
+ * explicit handling the wrapper would hang waiting for `'close'`.
+ */
+export declare class CliSpawnFailedError extends Error {
+    readonly cause?: unknown | undefined;
+    readonly code = "cli.spawn_failed";
+    constructor(message: string, cause?: unknown | undefined);
+}
+export type StdinMode = 'none' | 'length-only' | 'hashed';
+export type CaptureMode = 'hashed' | 'redacted' | 'raw';
+export interface CaptureOptions {
+    /** Resolved program path (passed verbatim to `spawn`). */
+    program: string;
+    /** Argv tail (passed verbatim to `spawn`; never wrapped in a shell). */
+    args: string[];
+    /** Working directory for the child (passed to `spawn`); not the recorded cwd. */
+    cwd: string;
+    /**
+     * Environment passed to the child. REQUIRED. Callers (the
+     * pipeline / pure handler) must construct the env explicitly so
+     * the env source is auditable; this function does NOT silently
+     * fall back to `process.env`.
+     */
+    env: NodeJS.ProcessEnv;
+    stdinMode: StdinMode;
+    /**
+     * Whether raw sample emission is enabled (requires `--capture-mode raw`
+     * AND `--unsafe-allow-raw-capture`). When false, no `sample_base64` is
+     * retained for stdout / stderr and the bounded sample buffer stays
+     * empty even though the streams are still hashed and counted.
+     */
+    rawCaptureEnabled: boolean;
+    /** Bounded sample cap for stdout (raw mode only). */
+    stdoutSampleBytes: number;
+    /** Bounded sample cap for stderr (raw mode only). */
+    stderrSampleBytes: number;
+    /** Wrapper timeout (ms). After this, the wrapper sends SIGTERM. */
+    timeoutMs: number;
+    /** SIGTERM-to-SIGKILL grace (ms). */
+    killGraceMs: number;
+    /**
+     * Optional readable from which to source parent stdin. Defaults to
+     * `process.stdin`. Tests inject a custom stream.
+     */
+    parentStdin?: Readable;
+}
+export interface StreamCaptureRef {
+    length: number;
+    /** sha256 hex digest with the canonical `sha256:` prefix. */
+    sha256: string;
+    truncated: boolean;
+    /** Present only when raw capture is enabled and the secret-scan does not suppress it. */
+    sample_base64?: string;
+}
+export interface StdinCaptureRef {
+    mode: StdinMode;
+    length?: number;
+    sha256?: string;
+    truncated?: boolean;
+}
+export interface CaptureResult {
+    exitCode: number;
+    /** OS-reported child exit signal. Distinct from `terminationSignal`. */
+    signal: string | null;
+    /** True when the wrapper sent termination signals due to `--timeout-ms` elapsing. */
+    timedOut: boolean;
+    /** Signal sent BY THE WRAPPER after timeout. */
+    terminationSignal: string | null;
+    startedAt: string;
+    finishedAt: string;
+    durationMs: number;
+    stdout: StreamCaptureRef;
+    stderr: StreamCaptureRef;
+    stdin: StdinCaptureRef;
+}
+export declare function exitCodeForSignal(signal: string | null | undefined): number;
+/**
+ * Run the bounded-capture wrapper. The promise resolves when the child
+ * exits OR is killed by the wrapper after timeout; it does NOT reject
+ * on non-zero exit; the record IS still emitted regardless of child exit code.
+ */
+export declare function captureCommand(opts: CaptureOptions): Promise<CaptureResult>;
+//# sourceMappingURL=capture.d.ts.map

package/dist/lib/capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../../src/lib/capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAY,MAAM,aAAa,CAAC;AAEtD;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAI1C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO;IAH1B,QAAQ,CAAC,IAAI,sBAAsB;gBAEjC,OAAO,EAAE,MAAM,EACN,KAAK,CAAC,EAAE,OAAO,YAAA;CAK3B;AAED,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,aAAa,GAAG,QAAQ,CAAC;AAC1D,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,UAAU,GAAG,KAAK,CAAC;AAyCxD,MAAM,WAAW,cAAc;IAC7B,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,iFAAiF;IACjF,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,SAAS,EAAE,SAAS,CAAC;IACrB;;;;;OAKG;IACH,iBAAiB,EAAE,OAAO,CAAC;IAC3B,qDAAqD;IACrD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,WAAW,CAAC,EAAE,QAAQ,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,yFAAyF;IACzF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,qFAAqF;IACrF,QAAQ,EAAE,OAAO,CAAC;IAClB,gDAAgD;IAChD,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,gBAAgB,CAAC;IACzB,MAAM,EAAE,gBAAgB,CAAC;IACzB,KAAK,EAAE,eAAe,CAAC;CACxB;AAsBD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAG3E;AAsND;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAgJjF"}

package/dist/lib/cli-limits.d.ts

@@ -0,0 +1,49 @@
+/**
+ * CLI capture limits and security defaults.
+ *
+ * Centralizes the bounded-capture caps and security-default constants
+ * used by `peac observe command` and `peac record command`. Mirrored
+ * (but enforced separately) by the Zod ranges in
+ * `@peac/schema/src/extensions/cli-execution.ts`; keep both sides in
+ * sync when changing.
+ *
+ * All values are POSIX-first. Windows behavior is not guaranteed by
+ * the current CLI carrier profile; see `docs/specs/CLI-CARRIER-PROFILE.md`.
+ */
+/** Bounded-capture caps. */
+export declare const CLI_LIMITS: {
+    /** Default max bytes retained in the stdout sample buffer (raw mode only). */
+    readonly defaultStdoutSampleBytes: 16384;
+    /** Default max bytes retained in the stderr sample buffer (raw mode only). */
+    readonly defaultStderrSampleBytes: 16384;
+    /** Hard ceiling for the stdout / stderr sample buffer (raw mode only). */
+    readonly maxStdoutSampleBytes: 65536;
+    readonly maxStderrSampleBytes: 65536;
+    /** Default max bytes recorded in argv (raw mode only). */
+    readonly defaultArgvCaptureBytes: 4096;
+    /** Hard ceiling for argv bytes (raw mode only). */
+    readonly maxArgvCaptureBytes: 16384;
+    /** Hard ceiling for env entry count (deny-by-default; allowlist <= this). */
+    readonly maxEnvEntries: 32;
+    /** Default wrapper timeout (10 minutes). */
+    readonly defaultTimeoutMs: 600000;
+    /** Wrapper timeout hard ceiling (24 hours). */
+    readonly maxTimeoutMs: 86400000;
+    /** Wrapper timeout floor (1 ms). */
+    readonly minTimeoutMs: 1;
+    /** Default SIGTERM-to-SIGKILL grace (5 seconds). */
+    readonly defaultKillGraceMs: 5000;
+    /** SIGTERM-to-SIGKILL grace hard ceiling (60 seconds). */
+    readonly maxKillGraceMs: 60000;
+    /** SIGTERM-to-SIGKILL grace floor. */
+    readonly minKillGraceMs: 0;
+};
+/**
+ * Shell binaries that, when detected as the program basename, REQUIRE
+ * the explicit `--shell-mode` acknowledgement. PEAC NEVER synthesizes
+ * shell syntax; the wrapper is an observer, not a shell orchestrator.
+ */
+export declare const SHELL_BINARY_BASENAMES: Set<string>;
+/** Returns true when the resolved program basename is a known shell binary. */
+export declare function isShellBinary(programBasename: string): boolean;
+//# sourceMappingURL=cli-limits.d.ts.map

package/dist/lib/cli-limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-limits.d.ts","sourceRoot":"","sources":["../../src/lib/cli-limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,4BAA4B;AAC5B,eAAO,MAAM,UAAU;IACrB,8EAA8E;;IAE9E,8EAA8E;;IAE9E,0EAA0E;;;IAI1E,0DAA0D;;IAE1D,mDAAmD;;IAGnD,6EAA6E;;IAG7E,4CAA4C;;IAE5C,+CAA+C;;IAE/C,oCAAoC;;IAGpC,oDAAoD;;IAEpD,0DAA0D;;IAE1D,sCAAsC;;CAE9B,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,aAQjC,CAAC;AAEH,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAE9D"}

package/dist/lib/command-option-validation.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Shared command-option validation for `observe command` and
+ * `record command`. Single source of truth for:
+ *
+ *   - numeric flag range / NaN-safe checks
+ *   - env-allowlist key grammar + byte cap
+ *   - record-only digest / opaque-ref preflights
+ *   - raw capture / raw env / secret-scan unsafe-flag pairing
+ *   - shell-binary detection acknowledgement
+ *   - raw argv per-token cap
+ *
+ * Both commands consume `validateCoreCommandOptions` so their
+ * preflight semantics never drift. Record-command additionally calls
+ * `validateSigningOptions` for the signing-input mutex and canonical
+ * issuer URL check.
+ */
+import type { ArgvMode, CwdMode, BinaryPathMode, EnvMode, StdinMode, ExitCodeMode, ExecutionMode } from './observation-builder.js';
+/**
+ * Stable error codes shared by observe command and record command. The
+ * subcommands re-export the relevant subset under their own
+ * `OBSERVE_COMMAND_ERROR_CODES` / `RECORD_COMMAND_ERROR_CODES` for
+ * call-site clarity; both names point at these strings.
+ */
+export declare const COMMAND_OPTION_ERROR_CODES: {
+    readonly programRequired: "cli.program_required";
+    readonly unsafeFlagRequired: "cli.unsafe_flag_required";
+    readonly secretScanDisableRequiresUnsafeFlag: "cli.secret_scan_disable_requires_unsafe_flag";
+    readonly shellModeRequired: "cli.shell_mode_required";
+    readonly argvTokenTooLong: "cli.argv_token_too_long";
+    readonly outOfRange: "cli.out_of_range";
+    readonly invalidPolicyDigest: "cli.invalid_policy_digest";
+    readonly invalidConfigDigest: "cli.invalid_config_digest";
+    readonly invalidApprovalRef: "cli.invalid_approval_ref";
+    readonly invalidEnvKey: "cli.invalid_env_key";
+    readonly signingInputRequired: "cli.signing_input_required";
+    readonly signingInputConflict: "cli.signing_input_conflict";
+    readonly issuerIdRequired: "cli.issuer_id_required";
+    readonly issuerIdInvalid: "cli.issuer_id_invalid";
+};
+export interface ValidationFailure {
+    code: string;
+    message: string;
+}
+/** Common option shape both subcommands share (no signing fields). */
+export interface CoreCommandOptions {
+    captureMode: ArgvMode;
+    unsafeAllowRawCapture: boolean;
+    captureStdinMode: StdinMode;
+    captureStdoutBytes: number;
+    captureStderrBytes: number;
+    captureArgvBytes: number;
+    envAllow: string[];
+    envMode: EnvMode;
+    unsafeAllowRawEnv: boolean;
+    captureCwdMode: CwdMode;
+    captureBinaryPath: BinaryPathMode;
+    secretScan: boolean;
+    unsafeDisableSecretScan: boolean;
+    policyDigest?: string;
+    configDigest?: string;
+    approvalRef?: string;
+    executionMode: ExecutionMode;
+    shellMode: boolean;
+    timeoutMs: number;
+    killGraceMs: number;
+    exitCodeMode: ExitCodeMode;
+}
+/** Signing-input shape consumed by record command. */
+export interface SigningOptions {
+    issuerKey?: string;
+    issuerId?: string;
+    unsafeEphemeralKey: boolean;
+}
+/** True iff `n` is a finite, in-range integer (rejects NaN, Infinity, floats). */
+export declare function isValidIntInRange(n: unknown, min: number, max: number): boolean;
+/** UTF-8 byte length of a string. */
+export declare function utf8Bytes(s: string): number;
+/** Platform-agnostic basename -- strips both `/` and `\`. */
+export declare function basenameAny(p: string): string;
+/**
+ * Validate flags shared by observe command and record command. Returns
+ * an array of failures; empty when the options + child argv are
+ * acceptable. Caller surfaces failures to stderr and exits 2 BEFORE
+ * spawning the child.
+ */
+export declare function validateCoreCommandOptions(opts: CoreCommandOptions, childArgv: string[]): ValidationFailure[];
+/**
+ * Validate signing-input flags consumed by record command. Enforces
+ * mutex (--issuer-key XOR --unsafe-ephemeral-key), required
+ * --issuer-id, and canonical-issuer-URL form. Caller appends these
+ * failures to the core failures and exits 2 BEFORE running the child.
+ */
+export declare function validateSigningOptions(opts: SigningOptions): ValidationFailure[];
+//# sourceMappingURL=command-option-validation.d.ts.map

package/dist/lib/command-option-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-option-validation.d.ts","sourceRoot":"","sources":["../../src/lib/command-option-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EACV,QAAQ,EACR,OAAO,EACP,cAAc,EACd,OAAO,EACP,SAAS,EACT,YAAY,EACZ,aAAa,EACd,MAAM,0BAA0B,CAAC;AAElC;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;CAgB7B,CAAC;AAEX,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,sEAAsE;AACtE,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,QAAQ,CAAC;IACtB,qBAAqB,EAAE,OAAO,CAAC;IAC/B,gBAAgB,EAAE,SAAS,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,cAAc,EAAE,OAAO,CAAC;IACxB,iBAAiB,EAAE,cAAc,CAAC;IAClC,UAAU,EAAE,OAAO,CAAC;IACpB,uBAAuB,EAAE,OAAO,CAAC;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,aAAa,CAAC;IAC7B,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,YAAY,CAAC;CAC5B;AAED,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAMD,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAE/E;AAED,qCAAqC;AACrC,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED,6DAA6D;AAC7D,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,kBAAkB,EACxB,SAAS,EAAE,MAAM,EAAE,GAClB,iBAAiB,EAAE,CA6IrB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,cAAc,GAAG,iBAAiB,EAAE,CA6BhF"}

package/dist/lib/issuer-key-loader.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Issuer-key loader for `peac record command`.
+ *
+ * Implements the same issuer-key reference convention used by other
+ * PEAC tools: env:VAR_NAME and file:/path. Keeps the CLI signing UX
+ * aligned with the existing PEAC convention without coupling
+ * @peac/cli to any other package's loader implementation.
+ *
+ * Supported schemes:
+ *   env:VAR_NAME    loads JSON from process.env.VAR_NAME (or
+ *                   caller-supplied env)
+ *   file:/path      loads JSON from the file path
+ *
+ * The value at the resolved location is a JSON-encoded
+ * Ed25519PrivateJwk:
+ *
+ *   { "kty": "OKP", "crv": "Ed25519", "x": <b64url>, "d": <b64url>,
+ *     "kid": "optional" }
+ *
+ * `kid` is extracted from the JWK if present, otherwise derived from
+ * the public key (truncated SHA-256 of the base64url-encoded public
+ * key) so runs are reproducible.
+ *
+ * The loader NEVER logs key bytes; error messages reference field
+ * names and structural problems only.
+ */
+export declare class IssuerKeyLoadError extends Error {
+    readonly cause?: unknown | undefined;
+    readonly code = "cli.issuer_key_load_failed";
+    constructor(message: string, cause?: unknown | undefined);
+}
+export declare class IssuerKeyInvalidError extends Error {
+    readonly cause?: unknown | undefined;
+    readonly code = "cli.issuer_key_invalid";
+    constructor(message: string, cause?: unknown | undefined);
+}
+export interface LoadedIssuerKey {
+    privateKey: Uint8Array;
+    publicKey: Uint8Array;
+    kid: string;
+}
+/**
+ * Load the issuer key from a `--issuer-key` reference.
+ *
+ * @param schemeUri - One of `env:VAR` or `file:/path`.
+ * @param env       - Environment to consult for `env:` references.
+ *                    Defaults to `process.env`. Tests inject custom env.
+ */
+export declare function loadIssuerKey(schemeUri: string, env?: NodeJS.ProcessEnv): Promise<LoadedIssuerKey>;
+/**
+ * Derive a `kid` from a freshly-generated ephemeral public key. Same
+ * formula as the loader's fallback so observation records are
+ * consistent with the JWK-based path.
+ */
+export declare function deriveKidFromPublicKey(publicKey: Uint8Array): Promise<string>;
+//# sourceMappingURL=issuer-key-loader.d.ts.map

package/dist/lib/issuer-key-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"issuer-key-loader.d.ts","sourceRoot":"","sources":["../../src/lib/issuer-key-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAYH,qBAAa,kBAAmB,SAAQ,KAAK;IAIzC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO;IAH1B,QAAQ,CAAC,IAAI,gCAAgC;gBAE3C,OAAO,EAAE,MAAM,EACN,KAAK,CAAC,EAAE,OAAO,YAAA;CAK3B;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAI5C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO;IAH1B,QAAQ,CAAC,IAAI,4BAA4B;gBAEvC,OAAO,EAAE,MAAM,EACN,KAAK,CAAC,EAAE,OAAO,YAAA;CAK3B;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,UAAU,CAAC;IACvB,SAAS,EAAE,UAAU,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,EACjB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAAC,eAAe,CAAC,CAqF1B;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAAC,SAAS,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAInF"}

package/dist/lib/observation-builder.d.ts

@@ -0,0 +1,79 @@
+/**
+ * CLI observation record builder.
+ *
+ * Assembles the final `org.peacprotocol/cli-execution` observation
+ * record from the raw capture result + the flag-derived capture policy.
+ * Applies argv encoding, env filtering (captures only what the policy
+ * records; never mutates the child's execution env), cwd / binary-path
+ * encoding, and secret-scan suppression on stdout / stderr samples.
+ *
+ * Builder hard-fail invariants (mirrors of the schema invariants;
+ * surface the failure before emission so a flag-layer bug cannot
+ * produce a misleading record):
+ *   - command.program is basename-only; path-bearing tokens are
+ *     reduced to their basename. Path disclosure is governed by
+ *     --capture-binary-path and lives only under binary.path_*.
+ *   - raw argv tokens that exceed argv_max_bytes hard-fail with
+ *     `cli.argv_token_too_long`; raw mode never silently truncates.
+ *   - env.mode='raw' with rawEnvEnabled=false hard-fails with
+ *     `cli.env_mode_inconsistent` rather than silently downgrading
+ *     to hashed.
+ */
+export declare class CliObservationBuilderError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+import { type CliExecutionObservation } from '@peac/schema';
+import type { CaptureResult } from './capture.js';
+export type ArgvMode = 'hashed' | 'redacted' | 'raw';
+export type CwdMode = 'none' | 'hashed' | 'basename' | 'absolute';
+export type BinaryPathMode = 'none' | 'hashed' | 'absolute';
+export type EnvMode = 'hashed' | 'raw';
+export type StdinMode = 'none' | 'length-only' | 'hashed';
+export type ExitCodeMode = 'child' | 'record';
+export type ExecutionMode = 'deterministic_script' | 'templated_flow' | 'agent_loop' | 'human_step' | 'hybrid';
+export interface BuilderInput {
+    capture: CaptureResult;
+    /**
+     * The program token AS THE USER SUPPLIED IT (e.g. `node`, `./script.sh`,
+     * `/usr/bin/env`). This is what `command.program` records -- it does NOT
+     * leak the resolved absolute path. Path disclosure is governed
+     * exclusively by `--capture-binary-path` (recorded in `binary.path_*`).
+     */
+    programToken: string;
+    /**
+     * The resolved absolute path the wrapper actually spawned. Used
+     * internally for stat metadata and content digest under
+     * `--capture-binary-path hashed|absolute` -- NEVER recorded under
+     * `command.program`.
+     */
+    resolvedProgramPath: string;
+    /** Argv tail as supplied (post-`--`); never modified. */
+    rawArgv: string[];
+    cwd: string;
+    argvMode: ArgvMode;
+    cwdMode: CwdMode;
+    binaryPathMode: BinaryPathMode;
+    envMode: EnvMode;
+    stdinMode: StdinMode;
+    envAllowlist: string[];
+    parentEnv: NodeJS.ProcessEnv;
+    rawCaptureEnabled: boolean;
+    rawEnvEnabled: boolean;
+    secretScanEnabled: boolean;
+    secretScanDisabledUnsafely: boolean;
+    argvCaptureBytes: number;
+    stdoutSampleBytes: number;
+    stderrSampleBytes: number;
+    timeoutMs: number;
+    killGraceMs: number;
+    exitCodeMode: ExitCodeMode;
+    executionMode: ExecutionMode;
+    shellMode: boolean;
+    policyDigest?: string;
+    configDigest?: string;
+    approvalRef?: string;
+    peacCliVersion: string;
+}
+export declare function buildObservation(input: BuilderInput): Promise<CliExecutionObservation>;
+//# sourceMappingURL=observation-builder.d.ts.map

package/dist/lib/observation-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation-builder.d.ts","sourceRoot":"","sources":["../../src/lib/observation-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAcD,OAAO,EAA8B,KAAK,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACxF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAKlD,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,KAAK,CAAC;AACrD,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;AAClE,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;AAC5D,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;AACvC,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,aAAa,GAAG,QAAQ,CAAC;AAC1D,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,QAAQ,CAAC;AAC9C,MAAM,MAAM,aAAa,GACrB,sBAAsB,GACtB,gBAAgB,GAChB,YAAY,GACZ,YAAY,GACZ,QAAQ,CAAC;AAEb,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,aAAa,CAAC;IACvB;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,mBAAmB,EAAE,MAAM,CAAC;IAC5B,yDAAyD;IACzD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,cAAc,CAAC;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,SAAS,CAAC;IACrB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC,UAAU,CAAC;IAC7B,iBAAiB,EAAE,OAAO,CAAC;IAC3B,aAAa,EAAE,OAAO,CAAC;IACvB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,0BAA0B,EAAE,OAAO,CAAC;IACpC,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,YAAY,CAAC;IAC3B,aAAa,EAAE,aAAa,CAAC;IAC7B,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;CACxB;AAoOD,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAuG5F"}

package/dist/lib/observation-pipeline.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Shared CLI execution observation pipeline.
+ *
+ * Both `peac observe command` (unsigned JSON emission) and `peac
+ * record command` (Wire 0.2 JWS signing) reuse the same capture +
+ * build + validate pipeline so a record produced by one is
+ * indistinguishable from a record produced by the other (modulo the
+ * outer signing envelope). This module is the single source of truth
+ * for that shared behavior.
+ *
+ * Public surface intentionally narrow:
+ *   - resolveProgramPath(token, childEnv)        -- childEnv-aware PATH lookup
+ *   - preflightOutputWritable(output)            -- writability check before spawn
+ *   - runObservationCore(opts, ...)              -- capture + build + validate
+ *
+ * The pipeline is an OBSERVER, not a sandbox / permission system /
+ * shell orchestrator / process supervisor / job scheduler.
+ */
+import { type CliExecutionObservation } from '@peac/schema';
+import { type CaptureResult } from './capture.js';
+import { preflightOutputWritable as neutralPreflightOutputWritable } from './output-preflight.js';
+import { type ArgvMode, type CwdMode, type BinaryPathMode, type EnvMode, type StdinMode, type ExitCodeMode, type ExecutionMode } from './observation-builder.js';
+/** Capture-pipeline options shared by both subcommands. */
+export interface CoreObservationOptions {
+    captureMode: ArgvMode;
+    unsafeAllowRawCapture: boolean;
+    captureStdinMode: StdinMode;
+    captureStdoutBytes: number;
+    captureStderrBytes: number;
+    captureArgvBytes: number;
+    envAllow: string[];
+    envMode: EnvMode;
+    unsafeAllowRawEnv: boolean;
+    captureCwdMode: CwdMode;
+    captureBinaryPath: BinaryPathMode;
+    secretScan: boolean;
+    unsafeDisableSecretScan: boolean;
+    policyDigest?: string;
+    configDigest?: string;
+    approvalRef?: string;
+    executionMode: ExecutionMode;
+    shellMode: boolean;
+    timeoutMs: number;
+    killGraceMs: number;
+    exitCodeMode: ExitCodeMode;
+}
+export interface CoreObservationIO {
+    /** Environment passed to the spawned child (what the child RECEIVES). */
+    childEnv: NodeJS.ProcessEnv;
+    /** Environment inspected by --env-allow for record entries. */
+    captureEnv: NodeJS.ProcessEnv;
+    cwd: string;
+    peacCliVersion: string;
+}
+export type CoreObservationResult = {
+    ok: true;
+    observation: CliExecutionObservation;
+    capture: CaptureResult;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/**
+ * Resolve a program token to its absolute path. Resolution honors the
+ * supplied `childEnv` ONLY (the environment that will be passed to
+ * spawn). The ambient `process.env` is not consulted: callers must
+ * pass `childEnv` explicitly so the execution-environment source is
+ * auditable at the call site. When no executable is found in
+ * `childEnv.PATH`, returns the token unchanged so spawn surfaces a
+ * clear ENOENT error.
+ */
+export declare function resolveProgramPath(token: string, childEnv: NodeJS.ProcessEnv): string;
+/**
+ * Re-export of the neutral output-path preflight from
+ * `lib/output-preflight.ts`. Kept here so PR 2 callers
+ * (`observe command`, `record command`) and any future callers that
+ * already import this name from this module continue to work.
+ */
+export declare const preflightOutputWritable: typeof neutralPreflightOutputWritable;
+/**
+ * Run the shared capture + build + validate pipeline.
+ *
+ * Returns `{ ok: true, observation, capture }` when all stages succeed
+ * (observation is the schema-validated record; capture carries the
+ * child's exit info for downstream exit-code-mode handling).
+ * Returns `{ ok: false, code, message }` for any structured failure.
+ *
+ * Stages:
+ *   1. resolveProgramPath(programToken, childEnv)
+ *   2. captureCommand(...)        (raises CliSpawnFailedError)
+ *   3. buildObservation(...)      (raises CliObservationBuilderError)
+ *   4. CliExecutionSchema.safeParse(observation)
+ */
+export declare function runObservationCore(opts: CoreObservationOptions, programToken: string, args: string[], io: CoreObservationIO): Promise<CoreObservationResult>;
+//# sourceMappingURL=observation-pipeline.d.ts.map

package/dist/lib/observation-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation-pipeline.d.ts","sourceRoot":"","sources":["../../src/lib/observation-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,EAAsB,KAAK,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAChF,OAAO,EAAuC,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AACvF,OAAO,EAAE,uBAAuB,IAAI,8BAA8B,EAAE,MAAM,uBAAuB,CAAC;AAClG,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,OAAO,EACZ,KAAK,cAAc,EACnB,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,aAAa,EACnB,MAAM,0BAA0B,CAAC;AAElC,2DAA2D;AAC3D,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,QAAQ,CAAC;IACtB,qBAAqB,EAAE,OAAO,CAAC;IAC/B,gBAAgB,EAAE,SAAS,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,cAAc,EAAE,OAAO,CAAC;IACxB,iBAAiB,EAAE,cAAc,CAAC;IAClC,UAAU,EAAE,OAAO,CAAC;IACpB,uBAAuB,EAAE,OAAO,CAAC;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,aAAa,CAAC;IAC7B,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,YAAY,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC,UAAU,CAAC;IAC5B,+DAA+D;IAC/D,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,qBAAqB,GAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,WAAW,EAAE,uBAAuB,CAAC;IAAC,OAAO,EAAE,aAAa,CAAA;CAAE,GAC1E;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAuBrF;AAED;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,uCAAiC,CAAC;AAEtE;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,sBAAsB,EAC5B,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,EAAE,EACd,EAAE,EAAE,iBAAiB,GACpB,OAAO,CAAC,qBAAqB,CAAC,CAkFhC"}

package/dist/lib/output-preflight.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Race-free output-path writability preflight (neutral, surface-agnostic).
+ *
+ * Used by every CLI surface that supports `--output <file>` to verify the
+ * target path is writable BEFORE doing any side-effecting work (spawning a
+ * child process, loading an issuer key, signing, etc.). A record-producing
+ * wrapper must never do that work only to discover the record cannot be
+ * persisted.
+ *
+ * The preflight is deliberately non-invasive on the final target path:
+ *   - if the final target exists, open it for append/write check and
+ *     close it; never unlink the existing target
+ *   - if the final target does NOT exist, create a uniquely-named
+ *     sibling temp file in the parent directory with O_EXCL and
+ *     immediately unlink that temp file; the final target path is
+ *     not created or touched until the actual write step
+ *
+ * Result: between preflight and the eventual write, the CLI has NOT
+ * created or modified the final output path. Concurrent observers cannot
+ * race against a transient zero-byte target file produced by the preflight.
+ */
+/**
+ * Verify that `--output <file>` will be writable. Returns null on
+ * success; otherwise an error message suitable for pairing with
+ * `cli.output_write_failed`.
+ */
+export declare function preflightOutputWritable(output: string): string | null;
+//# sourceMappingURL=output-preflight.d.ts.map

package/dist/lib/output-preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-preflight.d.ts","sourceRoot":"","sources":["../../src/lib/output-preflight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiErE"}

package/dist/lib/secret-scan.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Secret-scan regex set for bounded-capture samples.
+ *
+ * Secret-scan is ON by default. When raw sample emission is possible
+ * (`--capture-mode raw && --unsafe-allow-raw-capture`), the wrapper
+ * runs this regex set against each candidate sample BEFORE emission.
+ * If a token-like pattern matches, the sample is suppressed and
+ * replaced with `{ sample_suppressed_reason: "secret_pattern_detected",
+ * matched_pattern_category: <category> }`. The literal match is NEVER
+ * recorded.
+ *
+ * The regex set is intentionally small (5 named patterns). False
+ * positives are tolerated; the suppression itself is observable so a
+ * verifier can detect over-suppression.
+ *
+ * Disabling secret-scan under raw capture requires the third unsafe
+ * flag (`--unsafe-disable-secret-scan`); enforcement lives in the
+ * subcommand flag-parse layer, not here.
+ */
+export type SecretCategory = 'bearer-token' | 'api-key' | 'jwt' | 'aws-access-key' | 'generic-high-entropy';
+export interface SecretMatch {
+    category: SecretCategory;
+}
+/**
+ * Scan a buffer or string for token-like patterns. Returns the first
+ * match (by pattern declaration order); the literal match is NEVER
+ * returned to callers.
+ */
+export declare function scanForSecrets(input: string | Uint8Array): SecretMatch | null;
+/**
+ * Scan an argv element. Same shape as `scanForSecrets` but documents
+ * intent: argv elements are scanned independently of stream samples.
+ */
+export declare function scanArgvElement(token: string): SecretMatch | null;
+//# sourceMappingURL=secret-scan.d.ts.map

package/dist/lib/secret-scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-scan.d.ts","sourceRoot":"","sources":["../../src/lib/secret-scan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,MAAM,cAAc,GACtB,cAAc,GACd,SAAS,GACT,KAAK,GACL,gBAAgB,GAChB,sBAAsB,CAAC;AA0C3B,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,WAAW,GAAG,IAAI,CAQ7E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAEjE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peac/cli",
-  "version": "0.13.4",
+  "version": "0.14.1",
   "description": "PEAC protocol command-line tools",
   "main": "dist/index.cjs",
   "types": "dist/index.d.ts",
@@ -38,13 +38,13 @@
   "dependencies": {
     "chalk": "^4.1.2",
     "commander": "^11.0.0",
-    "@peac/kernel": "0.13.4",
-    "@peac/audit": "0.13.4",
-    "@peac/net-node": "0.13.4",
-    "@peac/crypto": "0.13.4",
-    "@peac/policy-kit": "0.13.4",
-    "@peac/schema": "0.13.4",
-    "@peac/protocol": "0.13.4"
+    "@peac/audit": "0.14.1",
+    "@peac/kernel": "0.14.1",
+    "@peac/net-node": "0.14.1",
+    "@peac/crypto": "0.14.1",
+    "@peac/policy-kit": "0.14.1",
+    "@peac/protocol": "0.14.1",
+    "@peac/schema": "0.14.1"
   },
   "devDependencies": {
     "@types/node": "^22.19.11",