@peac/cli 0.13.4 → 0.14.1

package/dist/index.mjs

@@ -1,19 +1,20 @@
 #!/usr/bin/env node
-import { Command, CommanderError } from 'commander';
-import { verifyReceipt, fetchIssuerConfig, parseIssuerConfig } from '@peac/protocol';
-import { generateKeypair, base64urlEncode, sign, decode, canonicalize } from '@peac/crypto';
+import { Command, CommanderError, Option } from 'commander';
+import { verifyReceipt, fetchIssuerConfig, parseIssuerConfig, issue, IssueError } from '@peac/protocol';
+import { generateKeypair, base64urlEncode, sign, decode, canonicalize, sha256Hex as sha256Hex$1, validateKeypair, base64urlDecode, derivePublicKey } from '@peac/crypto';
 import * as fs6 from 'fs';
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, statSync, openSync, constants, closeSync, unlinkSync, createReadStream } from 'fs';
 import * as path6 from 'path';
-import { join } from 'path';
+import { join, resolve, dirname, delimiter } from 'path';
 import { loadProfile, serializePolicyJson, serializePolicyYaml, ProfileError, createExamplePolicy, loadPolicy, PolicyValidationError, PolicyLoadError, compilePeacTxt, compileRobotsSnippet, compileAiprefTemplates, renderPolicyMarkdown, explainMatches, evaluate, listProfiles, getProfileSummary, parsePolicyDocument } from '@peac/policy-kit';
-import { execSync } from 'child_process';
-import { createHash } from 'crypto';
-import { computeReceiptRef, validateWorkflowContextOrdered, isValidPurposeToken, isCanonicalPurpose, validateObligationsExtension, validateInteractionOrdered, validateDisputeAttestation, validateAttributionAttestation, validateAgentIdentityAttestation, ReceiptClaimsSchema, parseReceiptClaims } from '@peac/schema';
+import { execSync, spawn } from 'child_process';
+import { createHash, randomBytes } from 'crypto';
+import { LIFECYCLE_OBSERVATION_TYPE_URIS, computeReceiptRef, CLI_EXECUTION_EXTENSION_KEY, CLI_COMMAND_EXECUTION_TYPE, validateLifecycleObservation, LIFECYCLE_OBSERVATION_EXTENSION_KEY, validateWorkflowContextOrdered, isValidPurposeToken, isCanonicalPurpose, validateObligationsExtension, validateInteractionOrdered, validateDisputeAttestation, validateAttributionAttestation, validateAgentIdentityAttestation, ReceiptClaimsSchema, CliExecutionSchema, isCanonicalIss, parseReceiptClaims, OpaqueRefSchema } from '@peac/schema';
 import { POLICY } from '@peac/kernel';
 import { readDisputeBundle } from '@peac/audit';
 import { createRequire } from 'module';
 import chalk from 'chalk';
+import { readFile } from 'fs/promises';
 
 function getGlobalOptions(cmd) {
   const parent = cmd.parent;
@@ -194,8 +195,8 @@ policy.command("validate").description("Validate a PEAC policy file (YAML or JSO
         );
       } else {
         console.error("Policy validation failed:\n");
-        for (const issue of err.issues) {
-          console.error(`   - ${issue.path.join(".")}: ${issue.message}`);
+        for (const issue3 of err.issues) {
+          console.error(`   - ${issue3.path.join(".")}: ${issue3.message}`);
         }
       }
       process.exit(1);
@@ -2804,6 +2805,1922 @@ var DiscoverCommand = class {
   }
 };
 
+// src/lib/cli-limits.ts
+var CLI_LIMITS = {
+  /** Default max bytes retained in the stdout sample buffer (raw mode only). */
+  defaultStdoutSampleBytes: 16384,
+  /** Default max bytes retained in the stderr sample buffer (raw mode only). */
+  defaultStderrSampleBytes: 16384,
+  /** Hard ceiling for the stdout / stderr sample buffer (raw mode only). */
+  maxStdoutSampleBytes: 65536,
+  maxStderrSampleBytes: 65536,
+  /** Default max bytes recorded in argv (raw mode only). */
+  defaultArgvCaptureBytes: 4096,
+  /** Hard ceiling for argv bytes (raw mode only). */
+  maxArgvCaptureBytes: 16384,
+  /** Hard ceiling for env entry count (deny-by-default; allowlist <= this). */
+  maxEnvEntries: 32,
+  /** Default wrapper timeout (10 minutes). */
+  defaultTimeoutMs: 6e5,
+  /** Wrapper timeout hard ceiling (24 hours). */
+  maxTimeoutMs: 864e5,
+  /** Wrapper timeout floor (1 ms). */
+  minTimeoutMs: 1,
+  /** Default SIGTERM-to-SIGKILL grace (5 seconds). */
+  defaultKillGraceMs: 5e3,
+  /** SIGTERM-to-SIGKILL grace hard ceiling (60 seconds). */
+  maxKillGraceMs: 6e4,
+  /** SIGTERM-to-SIGKILL grace floor. */
+  minKillGraceMs: 0
+};
+var SHELL_BINARY_BASENAMES = /* @__PURE__ */ new Set([
+  "sh",
+  "bash",
+  "zsh",
+  "dash",
+  "fish",
+  "pwsh",
+  "cmd"
+]);
+function isShellBinary(programBasename) {
+  return SHELL_BINARY_BASENAMES.has(programBasename.toLowerCase());
+}
+var CliSpawnFailedError = class extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "CliSpawnFailedError";
+  }
+  code = "cli.spawn_failed";
+};
+function validateSpawnInputs(program2, args) {
+  if (typeof program2 !== "string" || program2.length === 0) {
+    throw new CliSpawnFailedError("program token must be a non-empty string");
+  }
+  if (program2.includes("\0")) {
+    throw new CliSpawnFailedError("program token must not contain a NUL byte");
+  }
+  if (!Array.isArray(args)) {
+    throw new CliSpawnFailedError("args must be an array of strings");
+  }
+  const validatedArgs = [];
+  for (const a of args) {
+    if (typeof a !== "string") {
+      throw new CliSpawnFailedError("args must be an array of strings");
+    }
+    if (a.includes("\0")) {
+      throw new CliSpawnFailedError("args must not contain NUL bytes");
+    }
+    validatedArgs.push(a);
+  }
+  return { program: program2, args: validatedArgs };
+}
+var SHA256_PREFIX = "sha256:";
+var SIGNAL_EXIT_CODES = {
+  SIGHUP: 129,
+  SIGINT: 130,
+  SIGQUIT: 131,
+  SIGABRT: 134,
+  SIGKILL: 137,
+  SIGUSR1: 138,
+  SIGUSR2: 140,
+  SIGPIPE: 141,
+  SIGALRM: 142,
+  SIGTERM: 143
+};
+function exitCodeForSignal(signal) {
+  if (!signal) return 128;
+  return SIGNAL_EXIT_CODES[signal] ?? 128;
+}
+function newStreamHasher() {
+  return {
+    hasher: createHash("sha256"),
+    length: 0,
+    truncated: false,
+    sampleBuffer: [],
+    sampleBytes: 0
+  };
+}
+function feedHasher(state, chunk, sampleCap, rawEnabled) {
+  state.hasher.update(chunk);
+  state.length += chunk.length;
+  if (rawEnabled && state.sampleBytes < sampleCap) {
+    const remaining = sampleCap - state.sampleBytes;
+    if (chunk.length <= remaining) {
+      state.sampleBuffer.push(chunk);
+      state.sampleBytes += chunk.length;
+    } else {
+      state.sampleBuffer.push(chunk.subarray(0, remaining));
+      state.sampleBytes += remaining;
+      state.truncated = true;
+    }
+  } else if (rawEnabled && state.sampleBytes >= sampleCap) {
+    state.truncated = true;
+  }
+}
+function finalizeStreamRef(state, rawEnabled) {
+  const ref = {
+    length: state.length,
+    sha256: SHA256_PREFIX + state.hasher.digest("hex"),
+    truncated: state.truncated
+  };
+  if (rawEnabled && state.sampleBuffer.length > 0) {
+    ref.sample_base64 = Buffer.concat(state.sampleBuffer, state.sampleBytes).toString("base64");
+  }
+  return ref;
+}
+async function pumpStdin(parent, childStdin, mode, abortSignal) {
+  let length = 0;
+  const truncated = false;
+  const hasher = mode === "hashed" ? createHash("sha256") : null;
+  return new Promise((resolve3) => {
+    let settled = false;
+    let drainWaiter = null;
+    const finalize = () => {
+      const out = { length, truncated };
+      if (hasher) out.sha256 = SHA256_PREFIX + hasher.digest("hex");
+      return out;
+    };
+    const cleanup = () => {
+      parent.off("data", onData);
+      parent.off("end", onEnd);
+      parent.off("error", onParentError);
+      childStdin.off("drain", onDrain);
+      childStdin.off("error", onChildError);
+      abortSignal.removeEventListener("abort", onAbort);
+    };
+    const settle = () => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      try {
+        childStdin.end();
+      } catch {
+      }
+      if (drainWaiter) {
+        const reject = drainWaiter;
+        drainWaiter = null;
+        try {
+          reject(new Error("pump-aborted"));
+        } catch {
+        }
+      }
+      resolve3(finalize());
+    };
+    const onData = (chunk) => {
+      if (settled) return;
+      const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      length += buf.length;
+      if (hasher) hasher.update(buf);
+      let writable = false;
+      try {
+        writable = childStdin.write(buf);
+      } catch {
+        settle();
+        return;
+      }
+      if (!writable) {
+        try {
+          parent.pause();
+        } catch {
+        }
+        const waiter = new Promise((res, rej) => {
+          drainWaiter = rej;
+          childStdin.once("drain", () => {
+            drainWaiter = null;
+            res();
+          });
+        });
+        waiter.then(() => {
+          if (settled) return;
+          try {
+            parent.resume();
+          } catch {
+          }
+        }).catch(() => {
+        });
+      }
+    };
+    const onEnd = () => settle();
+    const onParentError = () => settle();
+    const onChildError = () => settle();
+    const onDrain = () => {
+    };
+    const onAbort = () => {
+      try {
+        parent.pause();
+      } catch {
+      }
+      settle();
+    };
+    parent.on("data", onData);
+    parent.on("end", onEnd);
+    parent.on("error", onParentError);
+    childStdin.on("drain", onDrain);
+    childStdin.on("error", onChildError);
+    if (abortSignal.aborted) {
+      onAbort();
+    } else {
+      abortSignal.addEventListener("abort", onAbort, { once: true });
+    }
+  });
+}
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+async function captureCommand(opts) {
+  const startedAt = nowIso();
+  const startMs = Date.now();
+  const stdoutState = newStreamHasher();
+  const stderrState = newStreamHasher();
+  const stdioConfig = opts.stdinMode === "none" ? ["ignore", "pipe", "pipe"] : ["pipe", "pipe", "pipe"];
+  const { program: program2, args } = validateSpawnInputs(opts.program, opts.args);
+  const child = spawn(program2, args, {
+    cwd: opts.cwd,
+    env: opts.env,
+    stdio: stdioConfig,
+    shell: false,
+    windowsHide: true
+  });
+  child.stdout.on("data", (chunk) => {
+    feedHasher(stdoutState, chunk, opts.stdoutSampleBytes, opts.rawCaptureEnabled);
+  });
+  child.stderr.on("data", (chunk) => {
+    feedHasher(stderrState, chunk, opts.stderrSampleBytes, opts.rawCaptureEnabled);
+  });
+  let stdinCapture = {
+    length: 0,
+    truncated: false
+  };
+  let stdinPromise = null;
+  const stdinAbort = new AbortController();
+  if (opts.stdinMode !== "none") {
+    const parent = opts.parentStdin ?? process.stdin;
+    stdinPromise = pumpStdin(parent, child.stdin, opts.stdinMode, stdinAbort.signal);
+  }
+  let timedOut = false;
+  let terminationSignal = null;
+  let killHandle;
+  const timeoutHandle = setTimeout(() => {
+    timedOut = true;
+    terminationSignal = "SIGTERM";
+    try {
+      child.kill("SIGTERM");
+    } catch {
+    }
+    killHandle = setTimeout(() => {
+      if (child.exitCode === null && child.signalCode === null) {
+        terminationSignal = "SIGKILL";
+        try {
+          child.kill("SIGKILL");
+        } catch {
+        }
+      }
+    }, opts.killGraceMs);
+  }, opts.timeoutMs);
+  const exitInfo = await new Promise(
+    (resolve3, reject) => {
+      let settled = false;
+      child.on("close", (code, signal) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timeoutHandle);
+        if (killHandle) clearTimeout(killHandle);
+        stdinAbort.abort();
+        const exitCode = code === null ? exitCodeForSignal(signal) : code;
+        resolve3({ exitCode, signal: signal ?? null });
+      });
+      child.on("error", (err) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timeoutHandle);
+        if (killHandle) clearTimeout(killHandle);
+        stdinAbort.abort();
+        reject(
+          new CliSpawnFailedError(
+            `failed to spawn child process: ${err instanceof Error ? err.message : String(err)}`,
+            err
+          )
+        );
+      });
+    }
+  );
+  if (stdinPromise) {
+    stdinCapture = await stdinPromise;
+  }
+  const finishedAt = nowIso();
+  const durationMs = Date.now() - startMs;
+  const stdinRef = opts.stdinMode === "none" ? { mode: "none" } : opts.stdinMode === "length-only" ? { mode: "length-only", length: stdinCapture.length, truncated: stdinCapture.truncated } : {
+    mode: "hashed",
+    length: stdinCapture.length,
+    sha256: stdinCapture.sha256,
+    truncated: stdinCapture.truncated
+  };
+  return {
+    exitCode: exitInfo.exitCode,
+    signal: exitInfo.signal,
+    timedOut,
+    terminationSignal,
+    startedAt,
+    finishedAt,
+    durationMs,
+    stdout: finalizeStreamRef(stdoutState, opts.rawCaptureEnabled),
+    stderr: finalizeStreamRef(stderrState, opts.rawCaptureEnabled),
+    stdin: stdinRef
+  };
+}
+function preflightOutputWritable(output2) {
+  if (output2 === "-" || output2 === "") return null;
+  const absPath = resolve(output2);
+  const parent = dirname(absPath);
+  try {
+    const st = statSync(parent);
+    if (!st.isDirectory()) {
+      return `parent path '${parent}' is not a directory`;
+    }
+  } catch (err) {
+    return `parent directory '${parent}' does not exist (${err?.code ?? (err instanceof Error ? err.message : String(err))})`;
+  }
+  let existingFd;
+  try {
+    existingFd = openSync(absPath, constants.O_WRONLY | constants.O_APPEND);
+  } catch (err) {
+    const code = err?.code;
+    if (code !== "ENOENT") {
+      return `cannot open '${absPath}' for write (${code ?? (err instanceof Error ? err.message : String(err))})`;
+    }
+  }
+  if (existingFd !== void 0) {
+    try {
+      closeSync(existingFd);
+    } catch {
+    }
+    return null;
+  }
+  const tempName = `.peac-preflight-${randomBytes(8).toString("hex")}.tmp`;
+  const tempPath = join(parent, tempName);
+  let fd;
+  try {
+    fd = openSync(tempPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 384);
+  } catch (err) {
+    return `parent directory '${parent}' is not writable (${err?.code ?? (err instanceof Error ? err.message : String(err))})`;
+  } finally {
+    if (fd !== void 0) {
+      try {
+        closeSync(fd);
+      } catch {
+      }
+    }
+  }
+  try {
+    unlinkSync(tempPath);
+  } catch {
+  }
+  return null;
+}
+
+// src/lib/secret-scan.ts
+var SECRET_PATTERNS = [
+  // JWS / JWT (three base64url segments separated by dots; first segment
+  // starts with a base64-encoded `{"`).
+  {
+    category: "jwt",
+    pattern: /eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/
+  },
+  // Bearer token in HTTP-auth shape.
+  {
+    category: "bearer-token",
+    pattern: /\bBearer\s+[A-Za-z0-9._~+/-]{16,}=*/i
+  },
+  // AWS access key (AKIA / ASIA prefix + 16 uppercase alnum).
+  {
+    category: "aws-access-key",
+    pattern: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/
+  },
+  // Generic API-key shape (sk_ / pk_ / api[-_]?key= prefix + >=20 alnum).
+  {
+    category: "api-key",
+    pattern: /\b(?:sk|pk|sk-live|sk-test|pk-live|pk-test)[_-][A-Za-z0-9]{20,}/
+  },
+  // High-entropy token (>=32 contiguous base64url-ish chars). Conservative
+  // length to reduce false positives on random hex IDs.
+  {
+    category: "generic-high-entropy",
+    pattern: /[A-Za-z0-9_-]{32,}/
+  }
+];
+function scanForSecrets(input) {
+  const text = typeof input === "string" ? input : Buffer.from(input).toString("utf8");
+  for (const { category, pattern } of SECRET_PATTERNS) {
+    if (pattern.test(text)) {
+      return { category };
+    }
+  }
+  return null;
+}
+function scanArgvElement(token) {
+  return scanForSecrets(token);
+}
+
+// src/lib/observation-builder.ts
+var CliObservationBuilderError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "CliObservationBuilderError";
+    this.code = code;
+  }
+};
+function basenameAny(p) {
+  return p.replace(/^.*[\\/]/, "");
+}
+var SHA256_PREFIX2 = "sha256:";
+function sha256Hex(input) {
+  return SHA256_PREFIX2 + createHash("sha256").update(input).digest("hex");
+}
+async function sha256OfFile(path9) {
+  return new Promise((resolve3, reject) => {
+    const hasher = createHash("sha256");
+    const stream = createReadStream(path9);
+    stream.on("data", (chunk) => {
+      hasher.update(chunk);
+    });
+    stream.on("end", () => {
+      resolve3(SHA256_PREFIX2 + hasher.digest("hex"));
+    });
+    stream.on("error", reject);
+  });
+}
+function isStructuralArgvToken(token) {
+  if (token === "--") return true;
+  if (/^-[A-Za-z0-9?]$/.test(token)) return true;
+  if (/^--[A-Za-z][A-Za-z0-9_-]*$/.test(token)) return true;
+  return false;
+}
+function encodeArgv(rawArgv, mode, argvCaptureBytes, secretScanEnabled) {
+  const tokenCount = rawArgv.length;
+  if (mode === "hashed") {
+    const canon = JSON.stringify(rawArgv);
+    return { argv_sha256: sha256Hex(canon), argv_token_count: tokenCount };
+  }
+  if (mode === "redacted") {
+    const out2 = rawArgv.map((tok) => {
+      if (isStructuralArgvToken(tok)) return tok;
+      const eq = tok.match(/^(--[A-Za-z][A-Za-z0-9_-]*=)(.*)$/);
+      if (eq) {
+        const value = eq[2];
+        const byteLen2 = Buffer.byteLength(value, "utf8");
+        return `${eq[1]}<redacted:${byteLen2}>`;
+      }
+      const byteLen = Buffer.byteLength(tok, "utf8");
+      return `<redacted:${byteLen}>`;
+    });
+    return { argv: out2, argv_token_count: tokenCount };
+  }
+  const out = rawArgv.map((tok, idx) => {
+    if (Buffer.byteLength(tok, "utf8") > argvCaptureBytes) {
+      throw new CliObservationBuilderError(
+        "cli.argv_token_too_long",
+        `command.argv[${idx}] (${Buffer.byteLength(tok, "utf8")} bytes) exceeds argv_max_bytes (${argvCaptureBytes}); raise --capture-argv-bytes or use --capture-mode hashed/redacted`
+      );
+    }
+    let scanResult = null;
+    if (secretScanEnabled) {
+      scanResult = scanArgvElement(tok);
+    }
+    if (scanResult) {
+      return `<secret-suppressed:${scanResult.category}>`;
+    }
+    return tok;
+  });
+  return { argv: out, argv_token_count: tokenCount };
+}
+function buildEnvBlock(parentEnv, allowlist, mode, rawEnvEnabled) {
+  if (mode === "raw" && !rawEnvEnabled) {
+    throw new CliObservationBuilderError(
+      "cli.env_mode_inconsistent",
+      "env.mode=raw requires --unsafe-allow-raw-env; refusing to silently downgrade to hashed"
+    );
+  }
+  const entries = {};
+  for (const key of allowlist) {
+    const val = parentEnv[key];
+    if (val === void 0) continue;
+    if (mode === "hashed") {
+      entries[key] = { value_sha256: sha256Hex(val) };
+    } else {
+      entries[key] = { value: val };
+    }
+  }
+  return { mode, entries };
+}
+function buildCwd(cwd, mode) {
+  switch (mode) {
+    case "none":
+      return { cwd_mode: "none" };
+    case "hashed":
+      return { cwd_mode: "hashed", cwd_sha256: sha256Hex(cwd) };
+    case "basename":
+      return { cwd_mode: "basename", cwd_basename: basenameAny(cwd) };
+    case "absolute":
+      return { cwd_mode: "absolute", cwd_absolute: cwd };
+  }
+}
+async function buildBinary(resolvedProgram, pathMode, shellMode) {
+  const built = { path_mode: pathMode };
+  let isRegularFile = false;
+  if (pathMode !== "none") {
+    try {
+      const st = statSync(resolvedProgram);
+      built.size_bytes = st.size;
+      built.mode_octal = (st.mode & 4095).toString(8).padStart(4, "0");
+      isRegularFile = st.isFile();
+    } catch {
+    }
+  }
+  switch (pathMode) {
+    case "none":
+      break;
+    case "hashed":
+      built.path_sha256 = sha256Hex(resolvedProgram);
+      break;
+    case "absolute":
+      built.path_absolute = resolvedProgram;
+      break;
+  }
+  if (pathMode !== "none" && isRegularFile) {
+    try {
+      built.sha256 = await sha256OfFile(resolvedProgram);
+    } catch {
+    }
+  }
+  if (shellMode) {
+    if (pathMode === "none") {
+      throw new CliObservationBuilderError(
+        "cli.shell_mode_required",
+        "shell_mode=true requires --capture-binary-path != none so shell_ref has a defined source"
+      );
+    }
+    built.shell_ref = built.path_sha256 ?? sha256Hex(resolvedProgram);
+  }
+  return built;
+}
+function applySecretScan(ref, scanEnabled) {
+  if (!scanEnabled || ref.sample_base64 === void 0) {
+    return ref;
+  }
+  const decoded = Buffer.from(ref.sample_base64, "base64").toString("utf8");
+  const match = scanForSecrets(decoded);
+  if (!match) return ref;
+  const { sample_base64: _omit, ...rest } = ref;
+  return {
+    ...rest,
+    sample_suppressed_reason: "secret_pattern_detected",
+    matched_pattern_category: match.category
+  };
+}
+async function buildObservation(input) {
+  const argvEncoded = encodeArgv(
+    input.rawArgv,
+    input.argvMode,
+    input.argvCaptureBytes,
+    input.secretScanEnabled
+  );
+  const programName = basenameAny(input.programToken);
+  const command = input.argvMode === "hashed" ? {
+    program: programName,
+    argv_mode: "hashed",
+    argv_sha256: argvEncoded.argv_sha256,
+    argv_token_count: argvEncoded.argv_token_count
+  } : input.argvMode === "redacted" ? {
+    program: programName,
+    argv_mode: "redacted",
+    argv: argvEncoded.argv,
+    argv_token_count: argvEncoded.argv_token_count
+  } : {
+    program: programName,
+    argv_mode: "raw",
+    argv: argvEncoded.argv,
+    argv_token_count: argvEncoded.argv_token_count
+  };
+  const cwd = buildCwd(input.cwd, input.cwdMode);
+  const binary = await buildBinary(
+    input.resolvedProgramPath,
+    input.binaryPathMode,
+    input.shellMode
+  );
+  const env = buildEnvBlock(
+    input.parentEnv,
+    input.envAllowlist,
+    input.envMode,
+    input.rawEnvEnabled
+  );
+  const stdoutRef = applySecretScan(input.capture.stdout, input.secretScanEnabled);
+  const stderrRef = applySecretScan(input.capture.stderr, input.secretScanEnabled);
+  const observation = {
+    type: CLI_COMMAND_EXECUTION_TYPE,
+    surface: { kind: "cli" },
+    command,
+    cwd,
+    binary,
+    stdin_ref: input.capture.stdin,
+    stdout_ref: stdoutRef,
+    stderr_ref: stderrRef,
+    env,
+    started_at: input.capture.startedAt,
+    finished_at: input.capture.finishedAt,
+    duration_ms: input.capture.durationMs,
+    exit_code: input.capture.exitCode,
+    ...input.capture.signal ? { signal: input.capture.signal } : {},
+    timed_out: input.capture.timedOut,
+    timeout_ms: input.timeoutMs,
+    kill_grace_ms: input.killGraceMs,
+    ...input.capture.terminationSignal ? { termination_signal: input.capture.terminationSignal } : {},
+    exit_code_mode: input.exitCodeMode,
+    shell_mode: input.shellMode,
+    execution_mode: input.executionMode,
+    capture_policy: {
+      stdout_max_bytes: input.stdoutSampleBytes,
+      stderr_max_bytes: input.stderrSampleBytes,
+      argv_max_bytes: input.argvCaptureBytes,
+      env_allowlist: input.envAllowlist,
+      stdin_mode: input.stdinMode,
+      cwd_mode: input.cwdMode,
+      binary_path_mode: input.binaryPathMode,
+      secret_scan: input.secretScanEnabled,
+      raw_capture_unsafely_allowed: input.rawCaptureEnabled,
+      raw_env_unsafely_allowed: input.rawEnvEnabled,
+      secret_scan_disabled_unsafely: input.secretScanDisabledUnsafely,
+      timeout_ms: input.timeoutMs,
+      kill_grace_ms: input.killGraceMs,
+      exit_code_mode: input.exitCodeMode
+    },
+    platform: {
+      os: process.platform,
+      arch: process.arch,
+      peac_cli_version: input.peacCliVersion
+    },
+    ...input.policyDigest ? { policy_digest: input.policyDigest } : {},
+    ...input.configDigest ? { config_digest: input.configDigest } : {},
+    ...input.approvalRef ? { approval_ref: input.approvalRef } : {}
+  };
+  return observation;
+}
+
+// src/lib/observation-pipeline.ts
+function resolveProgramPath(token, childEnv) {
+  if (token.includes("/") || token.includes("\\")) {
+    return resolve(token);
+  }
+  const PATH = childEnv.PATH ?? "";
+  const dirs = PATH.split(delimiter);
+  const exts = process.platform === "win32" ? (childEnv.PATHEXT ?? ".EXE;.CMD;.BAT").split(";") : [""];
+  for (const dir of dirs) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      const candidate = join(dir, token + ext);
+      try {
+        const st = statSync(candidate);
+        if (!st.isFile()) continue;
+        if (process.platform !== "win32" && (st.mode & 73) === 0) continue;
+        return candidate;
+      } catch {
+      }
+    }
+  }
+  return token;
+}
+var preflightOutputWritable2 = preflightOutputWritable;
+async function runObservationCore(opts, programToken, args, io) {
+  const resolvedProgramPath = resolveProgramPath(programToken, io.childEnv);
+  let capture;
+  try {
+    capture = await captureCommand({
+      program: resolvedProgramPath,
+      args,
+      cwd: io.cwd,
+      env: io.childEnv,
+      stdinMode: opts.captureStdinMode,
+      rawCaptureEnabled: opts.captureMode === "raw" && opts.unsafeAllowRawCapture,
+      stdoutSampleBytes: opts.captureStdoutBytes,
+      stderrSampleBytes: opts.captureStderrBytes,
+      timeoutMs: opts.timeoutMs,
+      killGraceMs: opts.killGraceMs
+    });
+  } catch (err) {
+    if (err instanceof CliSpawnFailedError) {
+      return { ok: false, code: err.code, message: err.message };
+    }
+    return {
+      ok: false,
+      code: "cli.spawn_failed",
+      message: err instanceof Error ? err.message : String(err)
+    };
+  }
+  let observation;
+  try {
+    observation = await buildObservation({
+      capture,
+      programToken,
+      resolvedProgramPath,
+      rawArgv: args,
+      cwd: io.cwd,
+      argvMode: opts.captureMode,
+      cwdMode: opts.captureCwdMode,
+      binaryPathMode: opts.captureBinaryPath,
+      envMode: opts.envMode,
+      stdinMode: opts.captureStdinMode,
+      envAllowlist: opts.envAllow,
+      parentEnv: io.captureEnv,
+      rawCaptureEnabled: opts.captureMode === "raw" && opts.unsafeAllowRawCapture,
+      rawEnvEnabled: opts.envMode === "raw" && opts.unsafeAllowRawEnv,
+      secretScanEnabled: opts.secretScan,
+      secretScanDisabledUnsafely: opts.unsafeDisableSecretScan,
+      argvCaptureBytes: opts.captureArgvBytes,
+      stdoutSampleBytes: opts.captureStdoutBytes,
+      stderrSampleBytes: opts.captureStderrBytes,
+      timeoutMs: opts.timeoutMs,
+      killGraceMs: opts.killGraceMs,
+      exitCodeMode: opts.exitCodeMode,
+      executionMode: opts.executionMode,
+      shellMode: opts.shellMode,
+      policyDigest: opts.policyDigest,
+      configDigest: opts.configDigest,
+      approvalRef: opts.approvalRef,
+      peacCliVersion: io.peacCliVersion
+    });
+  } catch (err) {
+    if (err instanceof CliObservationBuilderError) {
+      return { ok: false, code: err.code, message: err.message };
+    }
+    return {
+      ok: false,
+      code: "cli.builder_failed",
+      message: err instanceof Error ? err.message : String(err)
+    };
+  }
+  const parsed = CliExecutionSchema.safeParse(observation);
+  if (!parsed.success) {
+    const first = parsed.error.issues[0];
+    const path9 = first?.path?.join(".") ?? "";
+    return {
+      ok: false,
+      code: "cli.schema_rejection",
+      message: `${path9 ? "[" + path9 + "] " : ""}${first?.message ?? "schema validation failed"}`
+    };
+  }
+  return { ok: true, observation: parsed.data, capture };
+}
+var COMMAND_OPTION_ERROR_CODES = {
+  programRequired: "cli.program_required",
+  unsafeFlagRequired: "cli.unsafe_flag_required",
+  secretScanDisableRequiresUnsafeFlag: "cli.secret_scan_disable_requires_unsafe_flag",
+  shellModeRequired: "cli.shell_mode_required",
+  argvTokenTooLong: "cli.argv_token_too_long",
+  outOfRange: "cli.out_of_range",
+  invalidPolicyDigest: "cli.invalid_policy_digest",
+  invalidConfigDigest: "cli.invalid_config_digest",
+  invalidApprovalRef: "cli.invalid_approval_ref",
+  invalidEnvKey: "cli.invalid_env_key",
+  // Signing-only (used by validateSigningOptions).
+  signingInputRequired: "cli.signing_input_required",
+  signingInputConflict: "cli.signing_input_conflict",
+  issuerIdRequired: "cli.issuer_id_required",
+  issuerIdInvalid: "cli.issuer_id_invalid"
+};
+var SHA256_DIGEST = /^sha256:[a-f0-9]{64}$/;
+var ENV_KEY_GRAMMAR = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var ENV_KEY_BYTES_MAX = 256;
+function isValidIntInRange(n, min, max) {
+  return typeof n === "number" && Number.isInteger(n) && Number.isFinite(n) && n >= min && n <= max;
+}
+function utf8Bytes(s) {
+  return new TextEncoder().encode(s).byteLength;
+}
+function basenameAny2(p) {
+  return p.replace(/^.*[\\/]/, "");
+}
+function validateCoreCommandOptions(opts, childArgv) {
+  const failures = [];
+  if (childArgv.length === 0) {
+    failures.push({
+      code: COMMAND_OPTION_ERROR_CODES.programRequired,
+      message: "a program after `--` is required (e.g., -- echo hi)"
+    });
+    return failures;
+  }
+  if (!isValidIntInRange(opts.timeoutMs, CLI_LIMITS.minTimeoutMs, CLI_LIMITS.maxTimeoutMs)) {
+    failures.push({
+      code: COMMAND_OPTION_ERROR_CODES.outOfRange,
+      message: `--timeout-ms must be a finite integer in [${CLI_LIMITS.minTimeoutMs}, ${CLI_LIMITS.maxTimeoutMs}]`
+    });
+  }
+  if (!isValidIntInRange(opts.killGraceMs, CLI_LIMITS.minKillGraceMs, CLI_LIMITS.maxKillGraceMs)) {
+    failures.push({
+      code: COMMAND_OPTION_ERROR_CODES.outOfRange,
+      message: `--kill-grace-ms must be a finite integer in [${CLI_LIMITS.minKillGraceMs}, ${CLI_LIMITS.maxKillGraceMs}]`
+    });
+  }
+  if (!isValidIntInRange(opts.captureStdoutBytes, 0, CLI_LIMITS.maxStdoutSampleBytes)) {
+    failures.push({
+      code: COMMAND_OPTION_ERROR_CODES.outOfRange,
+      message: `--capture-stdout-bytes must be a finite integer in [0, ${CLI_LIMITS.maxStdoutSampleBytes}]`
+    });
+  }
+  if (!isValidIntInRange(opts.captureStderrBytes, 0, CLI_LIMITS.maxStderrSampleBytes)) {
+    failures.push({
+      code: COMMAND_OPTION_ERROR_CODES.outOfRange,
+      message: `--capture-stderr-bytes must be a finite integer in [0, ${CLI_LIMITS.maxStderrSampleBytes}]`
+    });
+  }
+  if (!isValidIntInRange(opts.captureArgvBytes, 0, CLI_LIMITS.maxArgvCaptureBytes)) {
+    failures.push({
+      code: COMMAND_OPTION_ERROR_CODES.outOfRange,
+      message: `--capture-argv-bytes must be a finite integer in [0, ${CLI_LIMITS.maxArgvCaptureBytes}]`
+    });
+  }
+  if (opts.envAllow.length > CLI_LIMITS.maxEnvEntries) {
+    failures.push({
+      code: COMMAND_OPTION_ERROR_CODES.outOfRange,
+      message: `--env-allow accepts at most ${CLI_LIMITS.maxEnvEntries} keys`
+    });
+  }
+  for (const key of opts.envAllow) {
+    if (!ENV_KEY_GRAMMAR.test(key)) {
+      failures.push({
+        code: COMMAND_OPTION_ERROR_CODES.invalidEnvKey,
+        message: `--env-allow key '${key}' must match ${ENV_KEY_GRAMMAR}`
+      });
+    } else if (utf8Bytes(key) > ENV_KEY_BYTES_MAX) {
+      failures.push({
+        code: COMMAND_OPTION_ERROR_CODES.invalidEnvKey,
+        message: `--env-allow key '${key}' exceeds ${ENV_KEY_BYTES_MAX} UTF-8 bytes`
+      });
+    }
+  }
+  if (opts.policyDigest !== void 0 && !SHA256_DIGEST.test(opts.policyDigest)) {
+    failures.push({
+      code: COMMAND_OPTION_ERROR_CODES.invalidPolicyDigest,
+      message: "--policy-digest must match sha256:<64 lowercase hex>"
+    });
+  }
+  if (opts.configDigest !== void 0 && !SHA256_DIGEST.test(opts.configDigest)) {
+    failures.push({
+      code: COMMAND_OPTION_ERROR_CODES.invalidConfigDigest,
+      message: "--config-digest must match sha256:<64 lowercase hex>"
+    });
+  }
+  if (opts.approvalRef !== void 0) {
+    const ref = OpaqueRefSchema.safeParse(opts.approvalRef);
+    if (!ref.success) {
+      failures.push({
+        code: COMMAND_OPTION_ERROR_CODES.invalidApprovalRef,
+        message: `--approval-ref must satisfy the opaque-reference grammar: ${ref.error.issues.map((i) => i.message).join("; ")}`
+      });
+    }
+  }
+  if (opts.captureMode === "raw" && !opts.unsafeAllowRawCapture) {
+    failures.push({
+      code: COMMAND_OPTION_ERROR_CODES.unsafeFlagRequired,
+      message: "--capture-mode raw requires --unsafe-allow-raw-capture"
+    });
+  }
+  if (opts.envMode === "raw" && !opts.unsafeAllowRawEnv) {
+    failures.push({
+      code: COMMAND_OPTION_ERROR_CODES.unsafeFlagRequired,
+      message: "--env-mode raw requires --unsafe-allow-raw-env"
+    });
+  }
+  if (opts.unsafeAllowRawCapture && !opts.secretScan && !opts.unsafeDisableSecretScan) {
+    failures.push({
+      code: COMMAND_OPTION_ERROR_CODES.secretScanDisableRequiresUnsafeFlag,
+      message: "--secret-scan off under raw capture requires --unsafe-disable-secret-scan"
+    });
+  }
+  if (opts.captureMode === "raw" && opts.unsafeAllowRawCapture) {
+    const tokens = childArgv.slice(1);
+    for (const tok of tokens) {
+      if (utf8Bytes(tok) > opts.captureArgvBytes) {
+        failures.push({
+          code: COMMAND_OPTION_ERROR_CODES.argvTokenTooLong,
+          message: `raw argv token (${utf8Bytes(tok)} bytes) exceeds --capture-argv-bytes (${opts.captureArgvBytes})`
+        });
+        break;
+      }
+    }
+  }
+  const programToken = childArgv[0];
+  const programBasename = basenameAny2(programToken);
+  if (isShellBinary(programBasename) && !opts.shellMode) {
+    failures.push({
+      code: COMMAND_OPTION_ERROR_CODES.shellModeRequired,
+      message: `program '${programBasename}' is a shell binary; --shell-mode is required to acknowledge that the user intentionally invoked a shell`
+    });
+  }
+  if (opts.shellMode && opts.captureBinaryPath === "none") {
+    failures.push({
+      code: COMMAND_OPTION_ERROR_CODES.shellModeRequired,
+      message: "--shell-mode requires --capture-binary-path != none"
+    });
+  }
+  return failures;
+}
+function validateSigningOptions(opts) {
+  const failures = [];
+  const hasIssuerKey = typeof opts.issuerKey === "string" && opts.issuerKey.length > 0;
+  const hasEphemeral = opts.unsafeEphemeralKey === true;
+  if (!hasIssuerKey && !hasEphemeral) {
+    failures.push({
+      code: COMMAND_OPTION_ERROR_CODES.signingInputRequired,
+      message: "record command requires exactly one of --issuer-key <env:VAR|file:/path> or --unsafe-ephemeral-key"
+    });
+  }
+  if (hasIssuerKey && hasEphemeral) {
+    failures.push({
+      code: COMMAND_OPTION_ERROR_CODES.signingInputConflict,
+      message: "--issuer-key and --unsafe-ephemeral-key are mutually exclusive"
+    });
+  }
+  if (typeof opts.issuerId !== "string" || opts.issuerId.length === 0) {
+    failures.push({
+      code: COMMAND_OPTION_ERROR_CODES.issuerIdRequired,
+      message: "--issuer-id <url> is required (canonical issuer URL)"
+    });
+  } else if (!isCanonicalIss(opts.issuerId)) {
+    failures.push({
+      code: COMMAND_OPTION_ERROR_CODES.issuerIdInvalid,
+      message: `--issuer-id '${opts.issuerId}' is not canonical (expected https:// ASCII origin or did: identifier)`
+    });
+  }
+  return failures;
+}
+
+// src/commands/observe-command.ts
+var ARGV_MODES = ["hashed", "redacted", "raw"];
+var CWD_MODES = ["none", "hashed", "basename", "absolute"];
+var BINARY_PATH_MODES = ["none", "hashed", "absolute"];
+var STDIN_MODES = ["none", "length-only", "hashed"];
+var ENV_MODES = ["hashed", "raw"];
+var EXIT_CODE_MODES = ["child", "record"];
+var EXECUTION_MODES = [
+  "deterministic_script",
+  "templated_flow",
+  "agent_loop",
+  "human_step",
+  "hybrid"
+];
+var OBSERVE_COMMAND_ERROR_CODES = {
+  outputWriteFailed: "cli.output_write_failed"
+};
+var DEFAULT_OPTIONS = {
+  captureMode: "hashed",
+  unsafeAllowRawCapture: false,
+  captureStdinMode: "none",
+  captureStdoutBytes: CLI_LIMITS.defaultStdoutSampleBytes,
+  captureStderrBytes: CLI_LIMITS.defaultStderrSampleBytes,
+  captureArgvBytes: CLI_LIMITS.defaultArgvCaptureBytes,
+  envAllow: [],
+  envMode: "hashed",
+  unsafeAllowRawEnv: false,
+  captureCwdMode: "hashed",
+  captureBinaryPath: "hashed",
+  secretScan: true,
+  unsafeDisableSecretScan: false,
+  executionMode: "deterministic_script",
+  shellMode: false,
+  output: "-",
+  timeoutMs: CLI_LIMITS.defaultTimeoutMs,
+  killGraceMs: CLI_LIMITS.defaultKillGraceMs,
+  exitCodeMode: "child"
+};
+function parseIntegerFlag(raw) {
+  if (raw.trim() === "") return Number.NaN;
+  const n = Number(raw);
+  return Number.isInteger(n) && Number.isFinite(n) ? n : Number.NaN;
+}
+function validateObserveOptions(opts, childArgv) {
+  return validateCoreCommandOptions(opts, childArgv);
+}
+async function runObserveCommand(options, childArgv, io = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const writeStdout = io.writeStdout ?? ((c) => process.stdout.write(c));
+  const writeStderr = io.writeStderr ?? ((c) => process.stderr.write(c));
+  const childEnv = io.childEnv ?? process.env;
+  const captureEnv = io.captureEnv ?? process.env;
+  const cwd = io.cwd ?? process.cwd();
+  const peacCliVersion = io.peacCliVersion ?? "0.14.1";
+  const failures = validateObserveOptions(opts, childArgv);
+  if (failures.length > 0) {
+    for (const f of failures) {
+      writeStderr(`${f.code}: ${f.message}
+`);
+    }
+    return { exitCode: 2 };
+  }
+  const programToken = childArgv[0];
+  const args = childArgv.slice(1);
+  const outputErr = preflightOutputWritable2(opts.output);
+  if (outputErr !== null) {
+    writeStderr(`${OBSERVE_COMMAND_ERROR_CODES.outputWriteFailed}: ${outputErr}
+`);
+    return { exitCode: 2 };
+  }
+  const core = await runObservationCore(opts, programToken, args, {
+    childEnv,
+    captureEnv,
+    cwd,
+    peacCliVersion
+  });
+  if (!core.ok) {
+    writeStderr(`${core.code}: ${core.message}
+`);
+    return { exitCode: 2 };
+  }
+  const json = JSON.stringify(core.observation);
+  if (opts.output === "-" || opts.output === "") {
+    writeStdout(json + "\n");
+  } else {
+    try {
+      writeFileSync(opts.output, json + "\n");
+    } catch (err) {
+      writeStderr(
+        `${OBSERVE_COMMAND_ERROR_CODES.outputWriteFailed}: failed to write '${opts.output}': ${err instanceof Error ? err.message : String(err)}
+`
+      );
+      return { exitCode: 2 };
+    }
+  }
+  if (opts.exitCodeMode === "record") {
+    return { exitCode: 0 };
+  }
+  return { exitCode: core.capture.exitCode };
+}
+function observeCommandSubcommand() {
+  const cmd = new Command("command");
+  cmd.description(
+    "Wrap a command and emit an unsigned CLI execution observation record. observe command is an OBSERVER, not a sandbox, permission system, shell orchestrator, or process supervisor. The command after `--` is spawned exactly as supplied (shell: false)."
+  ).addOption(
+    new Option("--capture-mode <mode>", "argv capture mode").choices([...ARGV_MODES]).default("hashed")
+  ).option(
+    "--unsafe-allow-raw-capture",
+    "required alongside --capture-mode raw to acknowledge raw stream sample emission",
+    false
+  ).addOption(
+    new Option("--capture-stdin-mode <mode>", "stdin capture (and pass-through) mode").choices([...STDIN_MODES]).default("none")
+  ).option(
+    "--capture-stdout-bytes <n>",
+    `stdout sample cap (raw mode only); max ${CLI_LIMITS.maxStdoutSampleBytes}`,
+    parseIntegerFlag,
+    CLI_LIMITS.defaultStdoutSampleBytes
+  ).option(
+    "--capture-stderr-bytes <n>",
+    `stderr sample cap (raw mode only); max ${CLI_LIMITS.maxStderrSampleBytes}`,
+    parseIntegerFlag,
+    CLI_LIMITS.defaultStderrSampleBytes
+  ).option(
+    "--capture-argv-bytes <n>",
+    `argv per-token byte cap (raw mode only); max ${CLI_LIMITS.maxArgvCaptureBytes}`,
+    parseIntegerFlag,
+    CLI_LIMITS.defaultArgvCaptureBytes
+  ).option(
+    "--env-allow <KEYS>",
+    "comma-separated allowlist of env vars to record (deny-by-default)",
+    (v, prev) => prev.concat(
+      v.split(",").map((s) => s.trim()).filter(Boolean)
+    ),
+    []
+  ).addOption(
+    new Option("--env-mode <mode>", "env value capture mode").choices([...ENV_MODES]).default("hashed")
+  ).option(
+    "--unsafe-allow-raw-env",
+    "required alongside --env-mode raw to acknowledge raw env value capture",
+    false
+  ).addOption(
+    new Option("--capture-cwd-mode <mode>", "cwd capture mode").choices([...CWD_MODES]).default("hashed")
+  ).addOption(
+    new Option("--capture-binary-path <mode>", "binary path capture mode").choices([...BINARY_PATH_MODES]).default("hashed")
+  ).addOption(
+    new Option("--secret-scan <state>", "secret-scan over raw samples").choices(["on", "off"]).default("on")
+  ).option(
+    "--unsafe-disable-secret-scan",
+    "required to disable secret-scan when raw capture is enabled",
+    false
+  ).option("--policy-digest <sha256>", "optional policy digest (sha256:<hex>)").option("--config-digest <sha256>", "optional config digest (sha256:<hex>)").option("--approval-ref <opaque>", "optional opaque approval reference").addOption(
+    new Option("--execution-mode <mode>", "execution-mode tag for this record").choices([...EXECUTION_MODES]).default("deterministic_script")
+  ).option(
+    "--shell-mode",
+    "acknowledge that the program is a shell binary; PEAC does NOT rewrite the command",
+    false
+  ).option("--output <file>", "output path for the JSON record (default: stdout)", "-").option(
+    "--timeout-ms <n>",
+    `wrapper timeout in ms; max ${CLI_LIMITS.maxTimeoutMs} (24h)`,
+    parseIntegerFlag,
+    CLI_LIMITS.defaultTimeoutMs
+  ).option(
+    "--kill-grace-ms <n>",
+    `SIGTERM-to-SIGKILL grace in ms; max ${CLI_LIMITS.maxKillGraceMs}`,
+    parseIntegerFlag,
+    CLI_LIMITS.defaultKillGraceMs
+  ).addOption(
+    new Option("--exit-code-mode <mode>", "wrapper exit-code policy").choices([...EXIT_CODE_MODES]).default("child")
+  ).allowUnknownOption(false).allowExcessArguments(true);
+  cmd.action(async (rawOpts, cmdInstance) => {
+    const childArgv = cmdInstance.args;
+    const options = {
+      captureMode: rawOpts.captureMode,
+      unsafeAllowRawCapture: Boolean(rawOpts.unsafeAllowRawCapture),
+      captureStdinMode: rawOpts.captureStdinMode,
+      captureStdoutBytes: rawOpts.captureStdoutBytes,
+      captureStderrBytes: rawOpts.captureStderrBytes,
+      captureArgvBytes: rawOpts.captureArgvBytes,
+      envAllow: rawOpts.envAllow ?? [],
+      envMode: rawOpts.envMode,
+      unsafeAllowRawEnv: Boolean(rawOpts.unsafeAllowRawEnv),
+      captureCwdMode: rawOpts.captureCwdMode,
+      captureBinaryPath: rawOpts.captureBinaryPath,
+      secretScan: rawOpts.secretScan === "on",
+      unsafeDisableSecretScan: Boolean(rawOpts.unsafeDisableSecretScan),
+      policyDigest: rawOpts.policyDigest,
+      configDigest: rawOpts.configDigest,
+      approvalRef: rawOpts.approvalRef,
+      executionMode: rawOpts.executionMode,
+      shellMode: Boolean(rawOpts.shellMode),
+      output: rawOpts.output ?? "-",
+      timeoutMs: rawOpts.timeoutMs,
+      killGraceMs: rawOpts.killGraceMs,
+      exitCodeMode: rawOpts.exitCodeMode
+    };
+    const result = await runObserveCommand(options, childArgv);
+    process.exitCode = result.exitCode;
+  });
+  return cmd;
+}
+function observeCommand() {
+  const observe = new Command("observe").description(
+    "Observe local activity and emit unsigned observation records."
+  );
+  observe.addCommand(observeCommandSubcommand());
+  return observe;
+}
+var IssuerKeyLoadError = class extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "IssuerKeyLoadError";
+  }
+  code = "cli.issuer_key_load_failed";
+};
+var IssuerKeyInvalidError = class extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "IssuerKeyInvalidError";
+  }
+  code = "cli.issuer_key_invalid";
+};
+async function loadIssuerKey(schemeUri, env = process.env) {
+  let raw;
+  if (schemeUri.startsWith("env:")) {
+    const varName = schemeUri.slice(4);
+    if (!varName) {
+      throw new IssuerKeyLoadError(
+        "env: scheme requires a variable name (e.g., env:PEAC_ISSUER_KEY)"
+      );
+    }
+    const envValue = env[varName];
+    if (!envValue) {
+      throw new IssuerKeyLoadError(`environment variable ${varName} is not set or empty`);
+    }
+    raw = envValue;
+  } else if (schemeUri.startsWith("file:")) {
+    const filePath = schemeUri.slice(5);
+    if (!filePath) {
+      throw new IssuerKeyLoadError("file: scheme requires a path (e.g., file:/path/to/key.json)");
+    }
+    try {
+      raw = await readFile(filePath, "utf-8");
+    } catch (err) {
+      throw new IssuerKeyLoadError(
+        `failed to read key file: ${filePath} (${err?.code ?? (err instanceof Error ? err.message : String(err))})`,
+        err
+      );
+    }
+  } else {
+    throw new IssuerKeyLoadError(
+      `unsupported --issuer-key scheme: ${schemeUri} (expected env:VAR_NAME or file:/path)`
+    );
+  }
+  let jwk;
+  try {
+    jwk = JSON.parse(raw);
+  } catch (err) {
+    throw new IssuerKeyInvalidError("issuer key is not valid JSON", err);
+  }
+  if (typeof jwk !== "object" || jwk === null || !("kty" in jwk) || !("crv" in jwk) || !("d" in jwk)) {
+    throw new IssuerKeyInvalidError("JWK must contain kty, crv, and d fields");
+  }
+  const j = jwk;
+  if (j.kty !== "OKP" || j.crv !== "Ed25519") {
+    throw new IssuerKeyInvalidError(
+      `JWK must be Ed25519 (kty: OKP, crv: Ed25519); got kty=${String(j.kty)} crv=${String(j.crv)}`
+    );
+  }
+  if (typeof j.d !== "string" || typeof j.x !== "string") {
+    throw new IssuerKeyInvalidError("JWK d and x fields must be base64url strings");
+  }
+  const ed25519Jwk = {
+    kty: "OKP",
+    crv: "Ed25519",
+    x: j.x,
+    d: j.d
+  };
+  const valid = await validateKeypair(ed25519Jwk);
+  if (!valid) {
+    throw new IssuerKeyInvalidError("JWK keypair validation failed: d does not derive to x");
+  }
+  const privateKey = base64urlDecode(ed25519Jwk.d);
+  const publicKey = await derivePublicKey(privateKey);
+  let kid;
+  if (typeof j.kid === "string" && j.kid.length > 0) {
+    kid = j.kid;
+  } else {
+    const pubB64 = base64urlEncode(publicKey);
+    const hash = await sha256Hex$1(pubB64);
+    kid = hash.slice(0, 16);
+  }
+  return { privateKey, publicKey, kid };
+}
+async function deriveKidFromPublicKey(publicKey) {
+  const pubB64 = base64urlEncode(publicKey);
+  const hash = await sha256Hex$1(pubB64);
+  return hash.slice(0, 16);
+}
+
+// src/commands/record-command.ts
+var ARGV_MODES2 = ["hashed", "redacted", "raw"];
+var CWD_MODES2 = ["none", "hashed", "basename", "absolute"];
+var BINARY_PATH_MODES2 = ["none", "hashed", "absolute"];
+var STDIN_MODES2 = ["none", "length-only", "hashed"];
+var ENV_MODES2 = ["hashed", "raw"];
+var EXIT_CODE_MODES2 = ["child", "record"];
+var EXECUTION_MODES2 = [
+  "deterministic_script",
+  "templated_flow",
+  "agent_loop",
+  "human_step",
+  "hybrid"
+];
+var RECORD_COMMAND_ERROR_CODES = {
+  outputWriteFailed: "cli.output_write_failed",
+  // Signing-specific (not part of the shared option-validation set).
+  issuerKeyLoadFailed: "cli.issuer_key_load_failed",
+  signingFailed: "cli.signing_failed"
+};
+var DEFAULT_OPTIONS2 = {
+  captureMode: "hashed",
+  unsafeAllowRawCapture: false,
+  captureStdinMode: "none",
+  captureStdoutBytes: CLI_LIMITS.defaultStdoutSampleBytes,
+  captureStderrBytes: CLI_LIMITS.defaultStderrSampleBytes,
+  captureArgvBytes: CLI_LIMITS.defaultArgvCaptureBytes,
+  envAllow: [],
+  envMode: "hashed",
+  unsafeAllowRawEnv: false,
+  captureCwdMode: "hashed",
+  captureBinaryPath: "hashed",
+  secretScan: true,
+  unsafeDisableSecretScan: false,
+  executionMode: "deterministic_script",
+  shellMode: false,
+  output: "-",
+  timeoutMs: CLI_LIMITS.defaultTimeoutMs,
+  killGraceMs: CLI_LIMITS.defaultKillGraceMs,
+  exitCodeMode: "child",
+  unsafeEphemeralKey: false
+};
+function validateRecordOptions(opts, childArgv) {
+  const core = validateCoreCommandOptions(opts, childArgv);
+  const programRequired = core.find((f) => f.code === COMMAND_OPTION_ERROR_CODES.programRequired);
+  if (programRequired) return core;
+  return [...core, ...validateSigningOptions(opts)];
+}
+async function resolveIssuerKey(opts, issuerKeyEnv) {
+  if (opts.unsafeEphemeralKey) {
+    const { privateKey, publicKey } = await generateKeypair();
+    const kid = await deriveKidFromPublicKey(publicKey);
+    return { ok: true, privateKey, kid };
+  }
+  try {
+    const loaded = await loadIssuerKey(opts.issuerKey, issuerKeyEnv);
+    return { ok: true, privateKey: loaded.privateKey, kid: loaded.kid };
+  } catch (err) {
+    if (err instanceof IssuerKeyInvalidError) {
+      return { ok: false, code: err.code, message: err.message };
+    }
+    if (err instanceof IssuerKeyLoadError) {
+      return { ok: false, code: err.code, message: err.message };
+    }
+    return {
+      ok: false,
+      code: RECORD_COMMAND_ERROR_CODES.issuerKeyLoadFailed,
+      message: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+async function runRecordCommand(options, childArgv, io = {}) {
+  const opts = { ...DEFAULT_OPTIONS2, ...options };
+  const writeStdout = io.writeStdout ?? ((c) => process.stdout.write(c));
+  const writeStderr = io.writeStderr ?? ((c) => process.stderr.write(c));
+  const childEnv = io.childEnv ?? process.env;
+  const captureEnv = io.captureEnv ?? process.env;
+  const issuerKeyEnv = io.issuerKeyEnv ?? process.env;
+  const cwd = io.cwd ?? process.cwd();
+  const peacCliVersion = io.peacCliVersion ?? "0.14.1";
+  const failures = validateRecordOptions(opts, childArgv);
+  if (failures.length > 0) {
+    for (const f of failures) {
+      writeStderr(`${f.code}: ${f.message}
+`);
+    }
+    return { exitCode: 2 };
+  }
+  const programToken = childArgv[0];
+  const args = childArgv.slice(1);
+  const outputErr = preflightOutputWritable2(opts.output);
+  if (outputErr !== null) {
+    writeStderr(`${RECORD_COMMAND_ERROR_CODES.outputWriteFailed}: ${outputErr}
+`);
+    return { exitCode: 2 };
+  }
+  const keyResult = await resolveIssuerKey(opts, issuerKeyEnv);
+  if (!keyResult.ok) {
+    writeStderr(`${keyResult.code}: ${keyResult.message}
+`);
+    return { exitCode: 2 };
+  }
+  const core = await runObservationCore(opts, programToken, args, {
+    childEnv,
+    captureEnv,
+    cwd,
+    peacCliVersion
+  });
+  if (!core.ok) {
+    writeStderr(`${core.code}: ${core.message}
+`);
+    return { exitCode: 2 };
+  }
+  let jws;
+  try {
+    const result = await issue({
+      iss: opts.issuerId,
+      kind: "evidence",
+      type: CLI_COMMAND_EXECUTION_TYPE,
+      privateKey: keyResult.privateKey,
+      kid: keyResult.kid,
+      extensions: {
+        [CLI_EXECUTION_EXTENSION_KEY]: core.observation
+      }
+    });
+    jws = result.jws;
+  } catch (err) {
+    const message = err instanceof IssueError ? err.message : err instanceof Error ? err.message : String(err);
+    writeStderr(`${RECORD_COMMAND_ERROR_CODES.signingFailed}: ${message}
+`);
+    return { exitCode: 2 };
+  }
+  if (opts.output === "-" || opts.output === "") {
+    writeStdout(jws + "\n");
+  } else {
+    try {
+      writeFileSync(opts.output, jws + "\n");
+    } catch (err) {
+      writeStderr(
+        `${RECORD_COMMAND_ERROR_CODES.outputWriteFailed}: failed to write '${opts.output}': ${err instanceof Error ? err.message : String(err)}
+`
+      );
+      return { exitCode: 2 };
+    }
+  }
+  if (opts.exitCodeMode === "record") {
+    return { exitCode: 0 };
+  }
+  return { exitCode: core.capture.exitCode };
+}
+function recordCommandSubcommand() {
+  const cmd = new Command("command");
+  cmd.description(
+    "Wrap a command and emit a signed CLI execution record. record command is an OBSERVER, not a sandbox, permission system, shell orchestrator, or process supervisor. The command after `--` is spawned exactly as supplied (shell: false). Use --unsafe-ephemeral-key only for local development and tests; the public key is not published through normal issuer-key discovery."
+  ).addOption(
+    new Option("--capture-mode <mode>", "argv capture mode").choices([...ARGV_MODES2]).default("hashed")
+  ).option("--unsafe-allow-raw-capture", "required alongside --capture-mode raw", false).addOption(
+    new Option("--capture-stdin-mode <mode>", "stdin capture (and pass-through) mode").choices([...STDIN_MODES2]).default("none")
+  ).option(
+    "--capture-stdout-bytes <n>",
+    `stdout sample cap (raw mode only); max ${CLI_LIMITS.maxStdoutSampleBytes}`,
+    parseIntegerFlag,
+    CLI_LIMITS.defaultStdoutSampleBytes
+  ).option(
+    "--capture-stderr-bytes <n>",
+    `stderr sample cap (raw mode only); max ${CLI_LIMITS.maxStderrSampleBytes}`,
+    parseIntegerFlag,
+    CLI_LIMITS.defaultStderrSampleBytes
+  ).option(
+    "--capture-argv-bytes <n>",
+    `argv per-token byte cap (raw mode only); max ${CLI_LIMITS.maxArgvCaptureBytes}`,
+    parseIntegerFlag,
+    CLI_LIMITS.defaultArgvCaptureBytes
+  ).option(
+    "--env-allow <KEYS>",
+    "comma-separated allowlist of env vars to record (deny-by-default)",
+    (v, prev) => prev.concat(
+      v.split(",").map((s) => s.trim()).filter(Boolean)
+    ),
+    []
+  ).addOption(
+    new Option("--env-mode <mode>", "env value capture mode").choices([...ENV_MODES2]).default("hashed")
+  ).option("--unsafe-allow-raw-env", "required alongside --env-mode raw", false).addOption(
+    new Option("--capture-cwd-mode <mode>", "cwd capture mode").choices([...CWD_MODES2]).default("hashed")
+  ).addOption(
+    new Option("--capture-binary-path <mode>", "binary path capture mode").choices([...BINARY_PATH_MODES2]).default("hashed")
+  ).addOption(
+    new Option("--secret-scan <state>", "secret-scan over raw samples").choices(["on", "off"]).default("on")
+  ).option(
+    "--unsafe-disable-secret-scan",
+    "required to disable secret-scan when raw capture is enabled",
+    false
+  ).option("--policy-digest <sha256>", "optional policy digest (sha256:<hex>)").option("--config-digest <sha256>", "optional config digest (sha256:<hex>)").option("--approval-ref <opaque>", "optional opaque approval reference").addOption(
+    new Option("--execution-mode <mode>", "execution-mode tag for this record").choices([...EXECUTION_MODES2]).default("deterministic_script")
+  ).option(
+    "--shell-mode",
+    "acknowledge that the program is a shell binary; PEAC does NOT rewrite the command",
+    false
+  ).option("--output <file>", "output path for the JWS (default: stdout)", "-").option(
+    "--timeout-ms <n>",
+    `wrapper timeout in ms; max ${CLI_LIMITS.maxTimeoutMs} (24h)`,
+    parseIntegerFlag,
+    CLI_LIMITS.defaultTimeoutMs
+  ).option(
+    "--kill-grace-ms <n>",
+    `SIGTERM-to-SIGKILL grace in ms; max ${CLI_LIMITS.maxKillGraceMs}`,
+    parseIntegerFlag,
+    CLI_LIMITS.defaultKillGraceMs
+  ).addOption(
+    new Option("--exit-code-mode <mode>", "wrapper exit-code policy").choices([...EXIT_CODE_MODES2]).default("child")
+  ).option("--issuer-key <ref>", "issuer key reference: env:VAR_NAME or file:/path/to/jwk.json").option("--issuer-id <url>", "canonical issuer URL recorded as `iss`").option(
+    "--unsafe-ephemeral-key",
+    "Generates an ephemeral local signing key. The public key is not published through normal issuer-key discovery. Use only for local development and tests.",
+    false
+  ).allowUnknownOption(false).allowExcessArguments(true);
+  cmd.action(async (rawOpts, cmdInstance) => {
+    const childArgv = cmdInstance.args;
+    const options = {
+      captureMode: rawOpts.captureMode,
+      unsafeAllowRawCapture: Boolean(rawOpts.unsafeAllowRawCapture),
+      captureStdinMode: rawOpts.captureStdinMode,
+      captureStdoutBytes: rawOpts.captureStdoutBytes,
+      captureStderrBytes: rawOpts.captureStderrBytes,
+      captureArgvBytes: rawOpts.captureArgvBytes,
+      envAllow: rawOpts.envAllow ?? [],
+      envMode: rawOpts.envMode,
+      unsafeAllowRawEnv: Boolean(rawOpts.unsafeAllowRawEnv),
+      captureCwdMode: rawOpts.captureCwdMode,
+      captureBinaryPath: rawOpts.captureBinaryPath,
+      secretScan: rawOpts.secretScan === "on",
+      unsafeDisableSecretScan: Boolean(rawOpts.unsafeDisableSecretScan),
+      policyDigest: rawOpts.policyDigest,
+      configDigest: rawOpts.configDigest,
+      approvalRef: rawOpts.approvalRef,
+      executionMode: rawOpts.executionMode,
+      shellMode: Boolean(rawOpts.shellMode),
+      output: rawOpts.output ?? "-",
+      timeoutMs: rawOpts.timeoutMs,
+      killGraceMs: rawOpts.killGraceMs,
+      exitCodeMode: rawOpts.exitCodeMode,
+      issuerKey: rawOpts.issuerKey,
+      issuerId: rawOpts.issuerId,
+      unsafeEphemeralKey: Boolean(rawOpts.unsafeEphemeralKey)
+    };
+    const result = await runRecordCommand(options, childArgv);
+    process.exitCode = result.exitCode;
+  });
+  return cmd;
+}
+function recordCommand() {
+  const record = new Command("record").description(
+    "Sign and emit signed records over locally observed activity."
+  );
+  record.addCommand(recordCommandSubcommand());
+  return record;
+}
+var EVENT_KINDS = [
+  "lifecycle-approval-requested",
+  "lifecycle-approval-granted",
+  "lifecycle-approval-denied",
+  "lifecycle-evaluation-started",
+  "lifecycle-evaluation-completed",
+  "lifecycle-experiment-assigned",
+  "lifecycle-experiment-result",
+  "lifecycle-workflow-transition",
+  "lifecycle-mode-observed"
+];
+var TYPE_URI_BY_EVENT_KIND = (() => {
+  const map = {};
+  for (const k of EVENT_KINDS) {
+    map[k] = `org.peacprotocol/${k}`;
+  }
+  for (const uri of LIFECYCLE_OBSERVATION_TYPE_URIS) {
+    const k = uri.replace(/^org\.peacprotocol\//, "");
+    if (!EVENT_KINDS.includes(k)) {
+      throw new Error(`emit-lifecycle: type URI ${uri} has no matching event_kind discriminator`);
+    }
+  }
+  return map;
+})();
+var OBSERVED_MODES = [
+  "deterministic_script",
+  "templated_flow",
+  "agent_loop",
+  "human_step",
+  "hybrid"
+];
+var EMIT_LIFECYCLE_ERROR_CODES = {
+  missingRequiredField: "lifecycle.missing_required_field",
+  eventKindUnknown: "lifecycle.event_kind_unknown",
+  invalidObservedAt: "lifecycle.invalid_observed_at",
+  invalidObservedMode: "lifecycle.invalid_observed_mode",
+  invalidState: "lifecycle.invalid_state",
+  issuerKeyRequired: "cli.issuer_key_required",
+  issuerIdRequired: "cli.issuer_id_required",
+  issuerIdInvalid: "cli.issuer_id_invalid",
+  unsafeEphemeralKeyMutex: "cli.unsafe_ephemeral_key_mutex",
+  issuerKeyLoadFailed: "cli.issuer_key_load_failed",
+  signingFailed: "cli.signing_failed",
+  outputWriteFailed: "cli.output_write_failed"
+};
+var RFC_3339_WITH_OFFSET = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+function validateEmitLifecycleOptions(opts) {
+  const failures = [];
+  if (!opts.eventKind) {
+    failures.push({
+      code: EMIT_LIFECYCLE_ERROR_CODES.missingRequiredField,
+      message: "--event-kind is required"
+    });
+  } else if (!EVENT_KINDS.includes(opts.eventKind)) {
+    failures.push({
+      code: EMIT_LIFECYCLE_ERROR_CODES.eventKindUnknown,
+      message: `--event-kind must be one of: ${EVENT_KINDS.join(", ")}`
+    });
+  }
+  if (!opts.subjectRef) {
+    failures.push({
+      code: EMIT_LIFECYCLE_ERROR_CODES.missingRequiredField,
+      message: "--subject-ref is required"
+    });
+  }
+  if (!opts.observedAt) {
+    failures.push({
+      code: EMIT_LIFECYCLE_ERROR_CODES.missingRequiredField,
+      message: "--observed-at is required (no default-now; provide the wall-clock time at which the EXTERNAL system observed the event)"
+    });
+  } else if (!RFC_3339_WITH_OFFSET.test(opts.observedAt)) {
+    failures.push({
+      code: EMIT_LIFECYCLE_ERROR_CODES.invalidObservedAt,
+      message: "--observed-at must be RFC 3339 with timezone offset (e.g., 2026-05-12T10:00:00Z)"
+    });
+  }
+  const ek = opts.eventKind;
+  if (ek && EVENT_KINDS.includes(ek)) {
+    if (ek === "lifecycle-approval-requested" || ek === "lifecycle-approval-granted" || ek === "lifecycle-approval-denied") {
+      if (!opts.approvalRef) {
+        failures.push({
+          code: EMIT_LIFECYCLE_ERROR_CODES.missingRequiredField,
+          message: `--approval-ref is required for event-kind ${ek}`
+        });
+      }
+      if (!opts.approverRef) {
+        failures.push({
+          code: EMIT_LIFECYCLE_ERROR_CODES.missingRequiredField,
+          message: `--approver-ref is required for event-kind ${ek}`
+        });
+      }
+    } else if (ek === "lifecycle-evaluation-completed") {
+      if (!opts.resultRef) {
+        failures.push({
+          code: EMIT_LIFECYCLE_ERROR_CODES.missingRequiredField,
+          message: "--result-ref is required for event-kind lifecycle-evaluation-completed"
+        });
+      }
+    } else if (ek === "lifecycle-experiment-assigned") {
+      if (!opts.experimentRef) {
+        failures.push({
+          code: EMIT_LIFECYCLE_ERROR_CODES.missingRequiredField,
+          message: "--experiment-ref is required for event-kind lifecycle-experiment-assigned"
+        });
+      }
+    } else if (ek === "lifecycle-experiment-result") {
+      if (!opts.experimentRef) {
+        failures.push({
+          code: EMIT_LIFECYCLE_ERROR_CODES.missingRequiredField,
+          message: "--experiment-ref is required for event-kind lifecycle-experiment-result"
+        });
+      }
+      if (!opts.resultRef) {
+        failures.push({
+          code: EMIT_LIFECYCLE_ERROR_CODES.missingRequiredField,
+          message: "--result-ref is required for event-kind lifecycle-experiment-result"
+        });
+      }
+    } else if (ek === "lifecycle-workflow-transition") {
+      if (!opts.fromState) {
+        failures.push({
+          code: EMIT_LIFECYCLE_ERROR_CODES.missingRequiredField,
+          message: "--from-state is required for event-kind lifecycle-workflow-transition"
+        });
+      }
+      if (!opts.toState) {
+        failures.push({
+          code: EMIT_LIFECYCLE_ERROR_CODES.missingRequiredField,
+          message: "--to-state is required for event-kind lifecycle-workflow-transition"
+        });
+      }
+    } else if (ek === "lifecycle-mode-observed") {
+      if (!opts.observedMode) {
+        failures.push({
+          code: EMIT_LIFECYCLE_ERROR_CODES.missingRequiredField,
+          message: "--observed-mode is required for event-kind lifecycle-mode-observed"
+        });
+      }
+    }
+  }
+  if (opts.observedMode && !OBSERVED_MODES.includes(opts.observedMode)) {
+    failures.push({
+      code: EMIT_LIFECYCLE_ERROR_CODES.invalidObservedMode,
+      message: `--observed-mode must be one of: ${OBSERVED_MODES.join(", ")}`
+    });
+  }
+  for (const [flag, value] of [
+    ["--from-state", opts.fromState],
+    ["--to-state", opts.toState]
+  ]) {
+    if (value !== void 0) {
+      if (value.length === 0) {
+        failures.push({
+          code: EMIT_LIFECYCLE_ERROR_CODES.invalidState,
+          message: `${flag} must not be empty`
+        });
+      } else if (/^\s|\s$/.test(value)) {
+        failures.push({
+          code: EMIT_LIFECYCLE_ERROR_CODES.invalidState,
+          message: `${flag} must not have leading or trailing whitespace`
+        });
+      } else if (new TextEncoder().encode(value).byteLength > 256) {
+        failures.push({
+          code: EMIT_LIFECYCLE_ERROR_CODES.invalidState,
+          message: `${flag} must be <= 256 UTF-8 bytes`
+        });
+      }
+    }
+  }
+  const hasIssuerKey = !!opts.issuerKey;
+  if (!hasIssuerKey && !opts.unsafeEphemeralKey) {
+    failures.push({
+      code: EMIT_LIFECYCLE_ERROR_CODES.issuerKeyRequired,
+      message: "one of --issuer-key or --unsafe-ephemeral-key is required"
+    });
+  } else if (hasIssuerKey && opts.unsafeEphemeralKey) {
+    failures.push({
+      code: EMIT_LIFECYCLE_ERROR_CODES.unsafeEphemeralKeyMutex,
+      message: "--issuer-key and --unsafe-ephemeral-key are mutually exclusive"
+    });
+  }
+  if (!opts.issuerId) {
+    failures.push({
+      code: EMIT_LIFECYCLE_ERROR_CODES.issuerIdRequired,
+      message: "--issuer-id is required"
+    });
+  } else if (!isCanonicalIss(opts.issuerId)) {
+    failures.push({
+      code: EMIT_LIFECYCLE_ERROR_CODES.issuerIdInvalid,
+      message: "--issuer-id must be a canonical https://<origin> URL or did:<method>:<id> identifier"
+    });
+  }
+  return failures;
+}
+async function resolveIssuerKey2(opts, issuerKeyEnv) {
+  if (opts.unsafeEphemeralKey) {
+    const { privateKey, publicKey } = await generateKeypair();
+    const kid = await deriveKidFromPublicKey(publicKey);
+    return { ok: true, privateKey, kid };
+  }
+  try {
+    const loaded = await loadIssuerKey(opts.issuerKey, issuerKeyEnv);
+    return { ok: true, privateKey: loaded.privateKey, kid: loaded.kid };
+  } catch (err) {
+    if (err instanceof IssuerKeyInvalidError) {
+      return { ok: false, code: err.code, message: err.message };
+    }
+    if (err instanceof IssuerKeyLoadError) {
+      return { ok: false, code: err.code, message: err.message };
+    }
+    return {
+      ok: false,
+      code: EMIT_LIFECYCLE_ERROR_CODES.issuerKeyLoadFailed,
+      message: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+function buildLifecycleObservation(opts) {
+  const obs = {
+    event_kind: opts.eventKind,
+    subject_ref: opts.subjectRef,
+    observed_at: opts.observedAt
+  };
+  if (opts.parentRef) obs.parent_ref = opts.parentRef;
+  if (opts.upstreamArtifactRef) obs.upstream_artifact_ref = opts.upstreamArtifactRef;
+  if (opts.upstreamArtifactDigest) obs.upstream_artifact_digest = opts.upstreamArtifactDigest;
+  if (opts.policyRef) obs.policy_ref = opts.policyRef;
+  if (opts.policyDigest) obs.policy_digest = opts.policyDigest;
+  if (opts.rubricRef) obs.rubric_ref = opts.rubricRef;
+  if (opts.scoreRef) obs.score_ref = opts.scoreRef;
+  if (opts.resultDigest) obs.result_digest = opts.resultDigest;
+  const ek = opts.eventKind;
+  if (ek === "lifecycle-approval-requested" || ek === "lifecycle-approval-granted" || ek === "lifecycle-approval-denied") {
+    obs.approval_ref = opts.approvalRef;
+    obs.approver_ref = opts.approverRef;
+  } else if (ek === "lifecycle-evaluation-completed") {
+    obs.result_ref = opts.resultRef;
+  } else if (ek === "lifecycle-experiment-assigned") {
+    obs.experiment_ref = opts.experimentRef;
+    if (opts.cohortRef) obs.cohort_ref = opts.cohortRef;
+    if (opts.variantRef) obs.variant_ref = opts.variantRef;
+  } else if (ek === "lifecycle-experiment-result") {
+    obs.experiment_ref = opts.experimentRef;
+    obs.result_ref = opts.resultRef;
+    if (opts.cohortRef) obs.cohort_ref = opts.cohortRef;
+    if (opts.variantRef) obs.variant_ref = opts.variantRef;
+  } else if (ek === "lifecycle-workflow-transition") {
+    obs.from_state = opts.fromState;
+    obs.to_state = opts.toState;
+  } else if (ek === "lifecycle-mode-observed") {
+    obs.observed_mode = opts.observedMode;
+  }
+  if (ek !== "lifecycle-mode-observed" && opts.observedMode) {
+    obs.observed_mode = opts.observedMode;
+  }
+  return obs;
+}
+async function runEmitLifecycle(options, io = {}) {
+  const opts = {
+    unsafeEphemeralKey: false,
+    output: "-",
+    ...options
+  };
+  const writeStdout = io.writeStdout ?? ((c) => process.stdout.write(c));
+  const writeStderr = io.writeStderr ?? ((c) => process.stderr.write(c));
+  const issuerKeyEnv = io.issuerKeyEnv ?? process.env;
+  const failures = validateEmitLifecycleOptions(opts);
+  if (failures.length > 0) {
+    for (const f of failures) {
+      writeStderr(`${f.code}: ${f.message}
+`);
+    }
+    return { exitCode: 2 };
+  }
+  const outputErr = preflightOutputWritable(opts.output);
+  if (outputErr !== null) {
+    writeStderr(`${EMIT_LIFECYCLE_ERROR_CODES.outputWriteFailed}: ${outputErr}
+`);
+    return { exitCode: 2 };
+  }
+  const keyResult = await resolveIssuerKey2(opts, issuerKeyEnv);
+  if (!keyResult.ok) {
+    writeStderr(`${keyResult.code}: ${keyResult.message}
+`);
+    return { exitCode: 2 };
+  }
+  const observation = buildLifecycleObservation(opts);
+  const validation = validateLifecycleObservation(observation);
+  if (!validation.ok) {
+    for (const e of validation.errors) {
+      writeStderr(`${e.code}: ${e.message}
+`);
+    }
+    return { exitCode: 2 };
+  }
+  let jws;
+  try {
+    const recordType = TYPE_URI_BY_EVENT_KIND[opts.eventKind];
+    const result = await issue({
+      iss: opts.issuerId,
+      kind: "evidence",
+      type: recordType,
+      privateKey: keyResult.privateKey,
+      kid: keyResult.kid,
+      extensions: {
+        [LIFECYCLE_OBSERVATION_EXTENSION_KEY]: validation.value
+      }
+    });
+    jws = result.jws;
+  } catch (err) {
+    const message = err instanceof IssueError ? err.message : err instanceof Error ? err.message : String(err);
+    writeStderr(`${EMIT_LIFECYCLE_ERROR_CODES.signingFailed}: ${message}
+`);
+    return { exitCode: 2 };
+  }
+  if (opts.output === "-" || opts.output === "") {
+    writeStdout(jws + "\n");
+  } else {
+    try {
+      writeFileSync(opts.output, jws + "\n");
+    } catch (err) {
+      writeStderr(
+        `${EMIT_LIFECYCLE_ERROR_CODES.outputWriteFailed}: failed to write '${opts.output}': ${err instanceof Error ? err.message : String(err)}
+`
+      );
+      return { exitCode: 2 };
+    }
+  }
+  return { exitCode: 0 };
+}
+function emitLifecycleSubcommand() {
+  const cmd = new Command("lifecycle");
+  cmd.description(
+    "Issue a signed lifecycle observation record from caller-supplied flags. The caller is the observer (the lifecycle event was emitted by an external orchestrator, workflow engine, evaluation system, approval system, or agent runtime); the CLI is the issuance path; the caller-provided issuer key is the signer-of-record. PEAC does not approve, evaluate, score, transition, orchestrate, schedule, or vouch for the truth of the event. The full contract is specified in docs/specs/LIFECYCLE-OBSERVATION-PROFILE.md."
+  ).option(
+    "--event-kind <kind>",
+    `one of the 9 lifecycle event-kind discriminator values: ${EVENT_KINDS.join(", ")}`
+  ).option("--subject-ref <opaque>", "opaque reference to the subject of the observation").option("--parent-ref <opaque>", "optional opaque reference to a parent observation").option("--upstream-artifact-ref <opaque>", "optional opaque reference to an upstream artifact").option(
+    "--upstream-artifact-digest <sha256>",
+    "optional canonical sha256 digest of the upstream artifact"
+  ).option("--policy-ref <opaque>", "optional opaque reference to an upstream policy document").option("--policy-digest <sha256>", "optional canonical sha256 digest of the policy document").option("--rubric-ref <opaque>", "optional opaque reference to an evaluation rubric").option(
+    "--approval-ref <opaque>",
+    "opaque reference to the approval (REQUIRED for approval-* event kinds)"
+  ).option(
+    "--approver-ref <opaque>",
+    "opaque pseudonymous reference to the approver (REQUIRED for approval-* event kinds; @-containing values reject as PII)"
+  ).option(
+    "--experiment-ref <opaque>",
+    "opaque reference to the experiment (REQUIRED for experiment-* event kinds)"
+  ).option("--cohort-ref <opaque>", "optional opaque reference to the experiment cohort").option("--variant-ref <opaque>", "optional opaque reference to the experiment variant").option("--observed-mode <mode>", `observed runtime-mode tag: ${OBSERVED_MODES.join(", ")}`).option(
+    "--result-ref <opaque>",
+    "opaque reference to a stored result artifact (REQUIRED for evaluation-completed and experiment-result)"
+  ).option("--result-digest <sha256>", "optional canonical sha256 digest of the result artifact").option(
+    "--score-ref <opaque>",
+    "optional opaque reference to a stored score artifact (score values are NEVER inlined)"
+  ).option(
+    "--from-state <name>",
+    "free-form source state name (REQUIRED for workflow-transition; max 128 chars)"
+  ).option(
+    "--to-state <name>",
+    "free-form destination state name (REQUIRED for workflow-transition; max 128 chars)"
+  ).option(
+    "--observed-at <rfc3339>",
+    "RFC 3339 timestamp at which the EXTERNAL system observed the event (REQUIRED; no default-now)"
+  ).option("--issuer-key <ref>", "issuer key reference: env:VAR_NAME or file:/path/to/jwk.json").option("--issuer-id <url>", "canonical issuer URL recorded as `iss`").option(
+    "--unsafe-ephemeral-key",
+    "Generate an ephemeral local signing key. The public key is not published through normal issuer-key discovery. Use only for local development and tests.",
+    false
+  ).option("--output <file>", "output path for the JWS (default: stdout)", "-");
+  cmd.action(async (rawOpts) => {
+    const options = {
+      eventKind: rawOpts.eventKind,
+      subjectRef: rawOpts.subjectRef,
+      parentRef: rawOpts.parentRef,
+      upstreamArtifactRef: rawOpts.upstreamArtifactRef,
+      upstreamArtifactDigest: rawOpts.upstreamArtifactDigest,
+      policyRef: rawOpts.policyRef,
+      policyDigest: rawOpts.policyDigest,
+      rubricRef: rawOpts.rubricRef,
+      approvalRef: rawOpts.approvalRef,
+      approverRef: rawOpts.approverRef,
+      experimentRef: rawOpts.experimentRef,
+      cohortRef: rawOpts.cohortRef,
+      variantRef: rawOpts.variantRef,
+      observedMode: rawOpts.observedMode,
+      resultRef: rawOpts.resultRef,
+      resultDigest: rawOpts.resultDigest,
+      scoreRef: rawOpts.scoreRef,
+      fromState: rawOpts.fromState,
+      toState: rawOpts.toState,
+      observedAt: rawOpts.observedAt,
+      issuerKey: rawOpts.issuerKey,
+      issuerId: rawOpts.issuerId,
+      unsafeEphemeralKey: Boolean(rawOpts.unsafeEphemeralKey),
+      output: rawOpts.output ?? "-"
+    };
+    const result = await runEmitLifecycle(options);
+    process.exitCode = result.exitCode;
+  });
+  return cmd;
+}
+function emitCommand() {
+  const emit = new Command("emit").description(
+    "Issue signed records over events emitted by external systems (caller-supplied event emission/export surface)."
+  );
+  emit.addCommand(emitLifecycleSubcommand());
+  return emit;
+}
+
 // src/index.ts
 var program = new Command();
 program.name("peac").description("PEAC protocol command-line tools").version(getVersion()).exitOverride();
@@ -2939,6 +4856,9 @@ program.addCommand(policy);
 program.addCommand(conformance);
 program.addCommand(samples);
 program.addCommand(reconcileCommand());
+program.addCommand(observeCommand());
+program.addCommand(recordCommand());
+program.addCommand(emitCommand());
 doctor(program);
 program.command("discover").description("Discover and parse a remote /.well-known/peac.txt policy document").argument("<url>", "Origin URL (http/https) whose /.well-known/peac.txt to fetch").option("-j, --json", "output in JSON format").action(async (url, opts) => {
   const cmd = new DiscoverCommand();