@atrib/attest 0.0.0

package/dist/cli.js

@@ -0,0 +1,729 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// atrib-attest-cli / atrib-emit-cli: thin command-line wrapper around
+// emitInProcess, the in-process signing entrypoint from index.ts. One
+// implementation serves both bin names; the invoked basename picks the
+// diagnostic identity and the default `_local.producer` label.
+//
+// Per D082, hook-class producers spawn this binary instead of importing
+// @atrib/emit, which keeps the operator's hook source directory free of a
+// package.json and node_modules/. The binary itself is a short-lived Node
+// process that signs in-process, so records remain byte-identical to MCP-
+// server-signed and middleware-signed records per spec §1.3.
+//
+// Wire contract (stable as of @atrib/emit@0.11.3):
+//
+//   stdin: one JSON object, the same envelope emitInProcess accepts.
+//     {
+//       "event_type":   "https://atrib.dev/v1/types/observation" | "...annotation" | "...revision" | extension URI,
+//       "content":      { ... },
+//       "context_id":   "<32-hex>"?,
+//       "informed_by":  ["sha256:..."]?,
+//       "annotates":    "sha256:..."?,
+//       "revises":      "sha256:..."?,
+//       "session_token":"<base64url>"?,
+//       "provenance_token": "<base64url>"?,
+//       "tool_name":    "..."?,
+//       "args_hash":    "sha256:..."?,
+//       "result_hash":  "sha256:..."?
+//     }
+//
+//   stdout: one JSON object, the EmitOutput shape emitInProcess returns.
+//     signed:
+//       { "signed": true, "record_hash": "sha256:...", "warnings": [ ... ] }
+//     refused:
+//       { "signed": false, "context_id": "<32-hex>", "refusals": [ ... ] }
+//
+//   stderr: human-readable diagnostic line(s) for the spawning hook to log.
+//
+//   exit code: 0 when signed, 3 when refused. Hook helpers parse stdout and
+//     absorb non-zero exits so the user's session stays unblocked.
+//
+// CLI flags (kept minimal because the envelope carries everything routable):
+//   --log-endpoint <url>     override ATRIB_LOG_ENDPOINT for this call
+//   --flush-deadline-ms <n>  override the 5000ms default
+//   --version                print package version and exit 0
+//   --help                   print this usage and exit 0
+//
+// Environment variables (honored exactly as emitInProcess + resolveKey do):
+//   ATRIB_LOG_ENDPOINT, ATRIB_MIRROR_FILE, ATRIB_AUTOCHAIN_SOURCE,
+//   ATRIB_AGENT, ATRIB_PRIVATE_KEY, ATRIB_KEYCHAIN_TIMEOUT_MS,
+//   ATRIB_OP_TIMEOUT_MS, ATRIB_CONTEXT_ID, CLAUDE_CODE_SESSION_ID,
+//   CODEX_THREAD_ID, ATRIB_ACTIVE_SESSION_PROFILE. Optional P042
+//   local-substrate attempts also read ATRIB_LOCAL_SUBSTRATE_ENDPOINT,
+//   ATRIB_LOCAL_SUBSTRATE_MODE=shadow|commit, and ATRIB_LOCAL_SUBSTRATE_TIMEOUT_MS.
+import { randomBytes } from 'node:crypto';
+import { readFileSync, realpathSync, accessSync, constants as fsConstants } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createHttpLocalSubstrateTransport } from '@atrib/mcp';
+import { emitInProcess } from './index.js';
+import { resolveKey } from './keys.js';
+const HEX_32_PATTERN = /^[0-9a-f]{32}$/;
+function parseArgs(argv) {
+    const out = {
+        subcommand: 'emit',
+        showVersion: false,
+        showHelp: false,
+        showDescribe: false,
+        jsonOutput: false,
+    };
+    let start = 0;
+    // First positional, if it's a known subcommand, sets the mode.
+    if (argv[0] === 'doctor' || argv[0] === 'emit') {
+        out.subcommand = argv[0];
+        start = 1;
+    }
+    for (let i = start; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--version' || a === '-v') {
+            out.showVersion = true;
+            continue;
+        }
+        if (a === '--help' || a === '-h') {
+            out.showHelp = true;
+            continue;
+        }
+        if (a === '--describe') {
+            out.showDescribe = true;
+            continue;
+        }
+        if (a === '--json') {
+            out.jsonOutput = true;
+            continue;
+        }
+        if (a === '--log-endpoint') {
+            const next = argv[i + 1];
+            if (next === undefined)
+                throw new Error(`--log-endpoint requires a value`);
+            out.logEndpoint = next;
+            i++;
+            continue;
+        }
+        if (a === '--flush-deadline-ms') {
+            const next = argv[i + 1];
+            if (next === undefined)
+                throw new Error(`--flush-deadline-ms requires a value`);
+            const n = Number(next);
+            if (!Number.isFinite(n) || n <= 0) {
+                throw new Error(`--flush-deadline-ms must be a positive number (got ${next})`);
+            }
+            out.flushDeadlineMs = n;
+            i++;
+            continue;
+        }
+        throw new Error(`unknown argument: ${a}`);
+    }
+    return out;
+}
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on('end', () => resolve(data));
+        process.stdin.on('error', reject);
+    });
+}
+function readPackageVersion() {
+    // dist/cli.js sits next to dist/index.js. The package.json is one dir up.
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkgPath = join(here, '..', 'package.json');
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        return pkg.version ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function detectBinName(argv1) {
+    if (typeof argv1 === 'string' && argv1.length > 0) {
+        const base = argv1.split('/').pop() ?? '';
+        if (base.includes('attest'))
+            return 'atrib-attest-cli';
+    }
+    return 'atrib-emit-cli';
+}
+const BIN_NAME = detectBinName(process.argv[1]);
+function printHelp() {
+    process.stderr.write(`${BIN_NAME} ${readPackageVersion()}
+Sign one cognitive event (observation / annotation / revision) in-process,
+without an MCP transport. See D082 in atrib/DECISIONS.md.
+
+USAGE
+  ${BIN_NAME} [emit] [--log-endpoint <url>] [--flush-deadline-ms <n>] < envelope.json
+  ${BIN_NAME} doctor [--log-endpoint <url>] [--json]
+  ${BIN_NAME} --describe
+  ${BIN_NAME} --version | --help
+
+SUBCOMMANDS
+  emit (default)            Read one JSON envelope from stdin, sign in-process,
+                            write EmitOutput JSON to stdout. Exit code always 0
+                            per §5.8 degradation contract.
+  doctor                    Substrate readiness check: verify a signing key is
+                            resolvable, the log endpoint is reachable, and the
+                            local mirror path is writable. Exits 0 if all
+                            checks pass, non-zero otherwise.
+
+GLOBAL OPTIONS
+  --log-endpoint <url>      Override ATRIB_LOG_ENDPOINT.
+  --flush-deadline-ms <n>   (emit) Override the default 5000ms post-sign flush bound.
+  --json                    (doctor) Emit machine-readable JSON to stdout.
+  --describe                Emit a JSON description of this CLI's contract
+                            (subcommands, options, envelope schema, env vars).
+  --version                 Print package version.
+  --help                    Print this help.
+
+ENVELOPE FIELDS (emit, read from stdin as one JSON object)
+  event_type, content (required); context_id, informed_by,
+  allow_unresolved_informed_by, annotates, revises, session_token,
+  provenance_token, tool_name, args_hash, result_hash (optional).
+
+OUTPUT
+  emit: EmitOutput JSON on stdout, always exit 0.
+  doctor: text summary on stdout (or JSON with --json), exit 0 on pass.
+`);
+}
+function buildDescription() {
+    return {
+        name: BIN_NAME,
+        version: readPackageVersion(),
+        description: 'Thin command-line wrapper around emitInProcess (atrib D082). Reads one JSON envelope on stdin, signs the record in-process, writes EmitOutput JSON to stdout. Emit exits 0 when signed and 3 when refused.',
+        subcommands: {
+            emit: {
+                description: 'Sign one cognitive event (default; runs when no subcommand is given).',
+                reads_stdin: true,
+            },
+            doctor: {
+                description: 'Substrate readiness check: key, log endpoint, mirror path.',
+                reads_stdin: false,
+            },
+        },
+        options: [
+            { flag: '--log-endpoint', takes_value: true, description: 'Override ATRIB_LOG_ENDPOINT.' },
+            {
+                flag: '--flush-deadline-ms',
+                takes_value: true,
+                description: '(emit) Upper bound on post-sign queue flush in ms; default 5000.',
+            },
+            { flag: '--json', takes_value: false, description: '(doctor) Machine-readable JSON output.' },
+            { flag: '--describe', takes_value: false, description: 'This description block.' },
+            { flag: '--version', takes_value: false, description: 'Package version.' },
+            { flag: '--help', takes_value: false, description: 'Usage.' },
+        ],
+        envelope_schema: {
+            required: {
+                event_type: 'URI per spec §1.2.4. Normative: https://atrib.dev/v1/types/{observation,annotation,revision,tool_call,transaction,directory_anchor}. Shorthand aliases for those leaves are accepted.',
+                content: 'Object of any shape. Becomes the signed semantic payload.',
+            },
+            optional: {
+                context_id: '32-hex trace identifier; threads records into a coherent session chain (D072, D078).',
+                informed_by: 'Array of sha256:<64-hex> record_hashes; INFORMED_BY edge per §3.2.4 when resolvable.',
+                allow_unresolved_informed_by: 'Boolean escape hatch. Set true only for deliberate dangling informed_by claims.',
+                annotates: 'sha256:<64-hex> record_hash; required when event_type is the annotation URI per D058 / §1.2.7.',
+                revises: 'sha256:<64-hex> record_hash; required when event_type is the revision URI per D059 / §1.2.9.',
+                session_token: 'Cross-session causal anchor per W3C Trace Context tracestate.',
+                provenance_token: 'Genesis-record-only 22-char base64url cross-session anchor per spec §1.2.6 / D044.',
+                tool_name: 'Disclosed tool name per §8.2 (optional disclosure posture).',
+                args_hash: 'sha256:<64-hex> commitment to canonical args per §8.3 salted-commitment posture.',
+                result_hash: 'sha256:<64-hex> commitment to canonical result bytes per §8.3 salted-commitment posture.',
+                producer: 'Producer label routed to mirror sidecar `_local.producer`. Defaults to the invoked bin name ("atrib-emit-cli" or "atrib-attest-cli"); hook helpers override with finer attribution (e.g. "claude-hooks-builtin-2b").',
+                local_substrate: 'Optional watcher-WAL coordinator commit envelope: { operation: "enqueue_record_and_join_receipt", wal: { entry_id, source_path, receipt_join_field, join_back_target }, endpoint?, timeout_ms? }. Falls back to local signing when unavailable.',
+            },
+        },
+        output_schema: {
+            signed: 'boolean discriminant. true means a record was signed; false means the write was refused.',
+            record_hash: '"sha256:<64-hex>" of the signed canonical form. Present only when signed is true.',
+            log_index: 'integer position in the log if submission confirmed within flush deadline, else null.',
+            checkpoint: 'C2SP signed note string if confirmed, else null.',
+            inclusion_proof: 'array of base64 SHA-256 hashes (proof bundle) if confirmed, else null or omitted.',
+            context_id: '32-hex trace id the record was signed under.',
+            warnings: 'array of strings for signed degradation paths, such as queued submission.',
+            refusals: 'array of refusal reasons. Present only when signed is false.',
+        },
+        env_vars: [
+            {
+                name: 'ATRIB_PRIVATE_KEY',
+                description: 'base64url Ed25519 32-byte seed. First key source tried.',
+                required: false,
+            },
+            {
+                name: 'ATRIB_KEY_FILE',
+                description: 'Path to a file containing the seed. Second source.',
+                required: false,
+            },
+            {
+                name: 'ATRIB_KEYCHAIN_TIMEOUT_MS',
+                description: 'Keychain spawn timeout in ms (default 3000).',
+                required: false,
+            },
+            {
+                name: 'ATRIB_OP_TIMEOUT_MS',
+                description: '1Password CLI spawn timeout in ms (default 10000).',
+                required: false,
+            },
+            {
+                name: 'ATRIB_LOG_ENDPOINT',
+                description: 'Override the log submission URL.',
+                required: false,
+            },
+            {
+                name: 'ATRIB_MIRROR_FILE',
+                description: 'JSONL file path the signing path appends to.',
+                required: false,
+            },
+            {
+                name: 'ATRIB_AUTOCHAIN_SOURCE',
+                description: 'JSONL file path the inheritance reads from (chain composition).',
+                required: false,
+            },
+            {
+                name: 'ATRIB_AGENT',
+                description: 'Agent label used in the default mirror filename.',
+                required: false,
+            },
+            {
+                name: 'ATRIB_CONTEXT_ID',
+                description: 'Default 32-hex context_id when envelope omits one (D078).',
+                required: false,
+            },
+            {
+                name: 'ATRIB_LOCAL_SUBSTRATE_ENDPOINT',
+                description: 'Optional P042 coordinator endpoint. Shadow mode sends a bounded probe; commit mode sends a bounded long-lived sign_record commit.',
+                required: false,
+            },
+            {
+                name: 'ATRIB_LOCAL_SUBSTRATE_MODE',
+                description: 'Optional local-substrate mode. "shadow" is the endpoint default; "commit" delegates long-lived sign_record submission after hash matching. Watcher-WAL commit still uses an explicit local_substrate envelope.',
+                required: false,
+            },
+            {
+                name: 'ATRIB_LOCAL_SUBSTRATE_TIMEOUT_MS',
+                description: 'Optional per local-substrate attempt timeout in ms; defaults to 1500.',
+                required: false,
+            },
+            {
+                name: 'CLAUDE_CODE_SESSION_ID',
+                description: 'Harness-injected fallback (D083): UUID stripped + lowercased to a 32-hex context_id when ATRIB_CONTEXT_ID is unset. One entry in @atrib/mcp KNOWN_HARNESS_DISCOVERIES.',
+                required: false,
+            },
+            {
+                name: 'CODEX_THREAD_ID',
+                description: 'Codex harness fallback (D083): UUID stripped + lowercased to a 32-hex context_id when ATRIB_CONTEXT_ID is unset.',
+                required: false,
+            },
+            {
+                name: 'ATRIB_ACTIVE_SESSION_PROFILE',
+                description: 'Profile name for the host-written active-session state file, e.g. ~/.claude/state/active-session-id-codex. Falls back to ATRIB_AGENT when unset.',
+                required: false,
+            },
+        ],
+        spec_references: [
+            {
+                section: '§1.3',
+                url: 'https://github.com/creatornader/atrib/blob/main/atrib-spec.md#13-canonical-serialization',
+            },
+            {
+                section: '§1.4.2',
+                url: 'https://github.com/creatornader/atrib/blob/main/atrib-spec.md#142-record-hash',
+            },
+            {
+                section: '§5.8',
+                url: 'https://github.com/creatornader/atrib/blob/main/atrib-spec.md#58-degradation-contract',
+            },
+        ],
+        decision_references: [
+            {
+                adr: 'D079',
+                url: 'https://github.com/creatornader/atrib/blob/main/DECISIONS.md#d079-the-six-core-cognitive-primitives--atribs-agent-facing-surface',
+            },
+            {
+                adr: 'D081',
+                url: 'https://github.com/creatornader/atrib/blob/main/DECISIONS.md#d081-in-process-emit-for-hook-class-producers-emitinprocess',
+            },
+            {
+                adr: 'D082',
+                url: 'https://github.com/creatornader/atrib/blob/main/DECISIONS.md#d082-cli-binary-distribution-of-emitinprocess-supersedes-d081s-integration-shape',
+            },
+        ],
+    };
+}
+async function checkKey() {
+    const t0 = Date.now();
+    try {
+        const key = await resolveKey();
+        const timing = Date.now() - t0;
+        if (!key) {
+            return {
+                ok: false,
+                detail: 'no signing key resolved (set ATRIB_PRIVATE_KEY, ATRIB_KEY_FILE, or store seed in macOS Keychain as service "atrib-creator")',
+                timing_ms: timing,
+            };
+        }
+        return {
+            ok: true,
+            detail: `key resolved (source: ${key.source})`,
+            timing_ms: timing,
+            data: { source: key.source },
+        };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            detail: `resolveKey threw: ${e instanceof Error ? e.message : String(e)}`,
+            timing_ms: Date.now() - t0,
+        };
+    }
+}
+async function checkLogEndpoint(endpoint) {
+    // Probe the checkpoint endpoint rather than /v1/entries: HEAD-ish, doesn't
+    // require auth, returns the signed tree head. Reachable + parseable means
+    // the log is alive and we can talk to it; any HTTP error or network failure
+    // is a soft-fail (signing still works via the local queue, just no confirm).
+    const probeUrl = endpoint.replace(/\/v1\/entries\/?$/, '') + '/v1/checkpoint';
+    const t0 = Date.now();
+    try {
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), 5000);
+        const r = await fetch(probeUrl, { method: 'GET', signal: ac.signal });
+        clearTimeout(timer);
+        const timing = Date.now() - t0;
+        if (!r.ok) {
+            return {
+                ok: false,
+                detail: `log endpoint returned ${r.status} from ${probeUrl}; signing still works locally`,
+                timing_ms: timing,
+                data: { url: probeUrl, status: r.status },
+            };
+        }
+        const text = await r.text();
+        // Checkpoint format is "<origin>\n<tree_size>\n<root_hash>\n\n<signature>"
+        // per C2SP signed-note. We only need to confirm tree_size parses; the
+        // signature is verified by separate consumers.
+        const lines = text.split('\n');
+        const treeSize = Number(lines[1] ?? '0');
+        return {
+            ok: true,
+            detail: `log endpoint reachable (${probeUrl}, tree_size ${treeSize})`,
+            timing_ms: timing,
+            data: { url: probeUrl, tree_size: treeSize },
+        };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            detail: `log endpoint unreachable: ${e instanceof Error ? e.message : String(e)} (${probeUrl})`,
+            timing_ms: Date.now() - t0,
+            data: { url: probeUrl },
+        };
+    }
+}
+function checkMirrorWritable() {
+    const t0 = Date.now();
+    const path = process.env['ATRIB_MIRROR_FILE'] ??
+        join(homedir(), '.atrib', 'records', `atrib-emit-${process.env['ATRIB_AGENT'] ?? 'claude-code'}.jsonl`);
+    const parent = dirname(path);
+    try {
+        // The mirror file itself may or may not exist; we care about the parent
+        // dir being writable. Best-effort: if parent missing, that's a fail
+        // (signing path would create the file later but the runtime needs the dir).
+        accessSync(parent, fsConstants.W_OK);
+        return {
+            ok: true,
+            detail: `mirror parent writable (${parent})`,
+            timing_ms: Date.now() - t0,
+            data: { path, parent },
+        };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            detail: `mirror parent not writable: ${parent} (${e instanceof Error ? e.message : String(e)})`,
+            timing_ms: Date.now() - t0,
+            data: { path, parent },
+        };
+    }
+}
+async function runDoctor(opts) {
+    const endpoint = opts.logEndpoint ?? process.env['ATRIB_LOG_ENDPOINT'] ?? 'https://log.atrib.dev/v1/entries';
+    const [key, logEndpoint, mirror] = await Promise.all([
+        checkKey(),
+        checkLogEndpoint(endpoint),
+        Promise.resolve(checkMirrorWritable()),
+    ]);
+    return {
+        ok: key.ok && logEndpoint.ok && mirror.ok,
+        version: readPackageVersion(),
+        checks: { key, log_endpoint: logEndpoint, mirror_writable: mirror },
+    };
+}
+function renderDoctorText(report) {
+    const lines = [];
+    lines.push(`${BIN_NAME} ${report.version}: substrate readiness check`);
+    const fmt = (label, r) => {
+        const tag = r.ok ? '[OK]  ' : '[FAIL]';
+        return `  ${tag} ${label.padEnd(18)} ${r.detail} (${r.timing_ms}ms)`;
+    };
+    lines.push(fmt('key', report.checks.key));
+    lines.push(fmt('log_endpoint', report.checks.log_endpoint));
+    lines.push(fmt('mirror_writable', report.checks.mirror_writable));
+    lines.push('');
+    lines.push(report.ok ? 'All checks passed.' : 'One or more checks failed.');
+    return lines.join('\n');
+}
+// The CLI's wire envelope mirrors what callers passed to the MCP-transport
+// version exactly. Re-shape it into the EmitInput shape (lowercase property
+// names) the in-process API expects, dropping unknown keys silently.
+function buildEmitInput(envelope) {
+    const out = {};
+    if (envelope.event_type !== undefined)
+        out['event_type'] = envelope.event_type;
+    if (envelope.content !== undefined)
+        out['content'] = envelope.content;
+    if (envelope.context_id !== undefined)
+        out['context_id'] = envelope.context_id;
+    if (envelope.informed_by !== undefined)
+        out['informed_by'] = envelope.informed_by;
+    if (envelope.allow_unresolved_informed_by !== undefined) {
+        out['allow_unresolved_informed_by'] = envelope.allow_unresolved_informed_by;
+    }
+    if (envelope.annotates !== undefined)
+        out['annotates'] = envelope.annotates;
+    if (envelope.revises !== undefined)
+        out['revises'] = envelope.revises;
+    if (envelope.session_token !== undefined)
+        out['session_token'] = envelope.session_token;
+    if (envelope.provenance_token !== undefined)
+        out['provenance_token'] = envelope.provenance_token;
+    if (envelope.tool_name !== undefined)
+        out['tool_name'] = envelope.tool_name;
+    if (envelope.args_hash !== undefined)
+        out['args_hash'] = envelope.args_hash;
+    if (envelope.result_hash !== undefined)
+        out['result_hash'] = envelope.result_hash;
+    return out;
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function asNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function parseOptionalPositiveIntValue(value) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : undefined;
+}
+function buildLocalSubstrateCommitOption(envelope, producerLabel) {
+    const spec = envelope.local_substrate;
+    if (!isObject(spec))
+        return undefined;
+    const operation = asNonEmptyString(spec.operation);
+    const mode = asNonEmptyString(spec.mode);
+    const wantsCommit = operation === 'enqueue_record_and_join_receipt' ||
+        mode === 'watcher-wal-commit' ||
+        mode === 'commit';
+    if (!wantsCommit)
+        return undefined;
+    const wal = isObject(spec.wal) ? spec.wal : undefined;
+    const entryId = asNonEmptyString(wal?.entry_id);
+    const sourcePath = asNonEmptyString(wal?.source_path);
+    const receiptJoinField = asNonEmptyString(wal?.receipt_join_field);
+    const joinBackTarget = asNonEmptyString(wal?.join_back_target);
+    if (!entryId || !sourcePath || !receiptJoinField || !joinBackTarget) {
+        writeStderrLine(`${BIN_NAME}: local_substrate commit skipped; wal entry_id, source_path, receipt_join_field, and join_back_target are required`);
+        return undefined;
+    }
+    const endpoint = asNonEmptyString(spec.endpoint) ??
+        asNonEmptyString(process.env['ATRIB_LOCAL_SUBSTRATE_ENDPOINT']);
+    if (!endpoint) {
+        writeStderrLine(`${BIN_NAME}: local_substrate commit skipped; ATRIB_LOCAL_SUBSTRATE_ENDPOINT is unset`);
+        return undefined;
+    }
+    const timeoutMs = parseOptionalPositiveIntValue(spec.timeout_ms) ??
+        parseOptionalPositiveIntValue(process.env['ATRIB_LOCAL_SUBSTRATE_TIMEOUT_MS']);
+    return {
+        transport: createHttpLocalSubstrateTransport(endpoint),
+        producer: {
+            name: asNonEmptyString(spec.producer_name) ?? producerLabel,
+            harness_class: 'watcher-wal',
+            pid: process.pid,
+            transport: asNonEmptyString(spec.transport) ?? 'cli-stdin-wal',
+            creator_key_policy: 'explicit-watcher-creator',
+        },
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        wal: {
+            entry_id: entryId,
+            source_path: sourcePath,
+            receipt_join_field: receiptJoinField,
+            join_back_target: joinBackTarget,
+        },
+        onWarning: (message, detail) => {
+            writeStderrLine(detail === undefined ? message : `${message}: ${JSON.stringify(detail).slice(0, 500)}`);
+        },
+    };
+}
+function writeStdoutJson(value) {
+    process.stdout.write(JSON.stringify(value) + '\n');
+}
+function writeStderrLine(line) {
+    process.stderr.write(line + '\n');
+}
+// Compose a hook-safe fallback result for the cases where we cannot even
+// reach emitInProcess (stdin parse failure, etc). The caller's hook reads
+// our stdout and logs it; a structured payload keeps the contract uniform.
+function fallbackResult(reason, rawInput) {
+    return {
+        signed: false,
+        context_id: contextIdFromRawInput(rawInput),
+        refusals: [`${BIN_NAME} skipped: ${reason}`],
+    };
+}
+function contextIdFromRawInput(rawInput) {
+    if (rawInput && typeof rawInput === 'object' && !Array.isArray(rawInput)) {
+        const contextId = rawInput['context_id'];
+        if (typeof contextId === 'string' && HEX_32_PATTERN.test(contextId)) {
+            return contextId;
+        }
+    }
+    return randomBytes(16).toString('hex');
+}
+export async function main(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs(argv);
+    }
+    catch (e) {
+        writeStderrLine(`${BIN_NAME}: ${e instanceof Error ? e.message : String(e)}`);
+        writeStdoutJson(fallbackResult('invalid CLI arguments'));
+        return 3;
+    }
+    if (parsed.showVersion) {
+        process.stdout.write(`${readPackageVersion()}\n`);
+        return 0;
+    }
+    if (parsed.showHelp) {
+        printHelp();
+        return 0;
+    }
+    if (parsed.showDescribe) {
+        writeStdoutJson(buildDescription());
+        return 0;
+    }
+    if (parsed.subcommand === 'doctor') {
+        const report = await runDoctor({ logEndpoint: parsed.logEndpoint });
+        if (parsed.jsonOutput) {
+            writeStdoutJson(report);
+        }
+        else {
+            process.stdout.write(renderDoctorText(report) + '\n');
+        }
+        // Doctor exits non-zero on failure: operator-facing diagnostic, NOT the
+        // hook-safe always-0 contract of `emit`. Scripts can rely on this to gate
+        // CI / deployment checks.
+        return report.ok ? 0 : 1;
+    }
+    // Default subcommand: emit.
+    let raw;
+    try {
+        raw = await readStdin();
+    }
+    catch (e) {
+        writeStderrLine(`${BIN_NAME}: stdin read error: ${e instanceof Error ? e.message : String(e)}`);
+        writeStdoutJson(fallbackResult('stdin read error'));
+        return 3;
+    }
+    if (raw.trim().length === 0) {
+        writeStderrLine(`${BIN_NAME}: empty stdin; expected one JSON envelope`);
+        writeStdoutJson(fallbackResult('empty stdin'));
+        return 3;
+    }
+    let envelope;
+    try {
+        envelope = JSON.parse(raw);
+    }
+    catch (e) {
+        writeStderrLine(`${BIN_NAME}: stdin parse error: ${e instanceof Error ? e.message : String(e)}`);
+        writeStdoutJson(fallbackResult('stdin parse error'));
+        return 3;
+    }
+    if (envelope.event_type === undefined || envelope.content === undefined) {
+        writeStderrLine(`${BIN_NAME}: envelope missing required field(s) event_type or content`);
+        writeStdoutJson(fallbackResult('envelope missing event_type or content', envelope));
+        return 3;
+    }
+    const args = buildEmitInput(envelope);
+    // Identify CLI-signed records distinctly from MCP-server emits so the
+    // mirror's by-producer aggregation buckets hook-spawned signing apart
+    // from interactive tool calls. Hooks override via the envelope's
+    // top-level `producer` field when they need finer attribution
+    // (e.g. "claude-hooks-builtin-2b").
+    const envelopeProducer = typeof envelope.producer === 'string' && envelope.producer.length > 0
+        ? envelope.producer
+        : BIN_NAME;
+    const options = {
+        producer: envelopeProducer,
+    };
+    if (parsed.logEndpoint !== undefined)
+        options.logEndpoint = parsed.logEndpoint;
+    if (parsed.flushDeadlineMs !== undefined)
+        options.flushDeadlineMs = parsed.flushDeadlineMs;
+    const localSubstrateCommit = buildLocalSubstrateCommitOption(envelope, envelopeProducer);
+    if (localSubstrateCommit !== undefined) {
+        options.localSubstrate = false;
+        options.localSubstrateCommit = localSubstrateCommit;
+    }
+    const t0 = Date.now();
+    try {
+        const result = await emitInProcess(args, options);
+        writeStdoutJson(result);
+        const elapsed = Date.now() - t0;
+        if (!result.signed) {
+            writeStderrLine(`${BIN_NAME}: refused refusals=${result.refusals.length} elapsed=${elapsed}ms`);
+            return 3;
+        }
+        writeStderrLine(`${BIN_NAME}: ok record_hash=${String(result.record_hash).slice(0, 24)}… log_index=${result.log_index ?? 'null'} ` +
+            `warnings=${result.warnings.length} elapsed=${elapsed}ms`);
+        return 0;
+    }
+    catch (e) {
+        // emitInProcess returns refused writes as structured JSON. This catch is
+        // for unexpected setup failures or future regressions. Surface the error
+        // to the hook log and return structured fallback JSON on stdout.
+        const elapsed = Date.now() - t0;
+        const message = e instanceof Error ? e.message : String(e);
+        writeStderrLine(`${BIN_NAME}: emitInProcess threw: ${message} elapsed=${elapsed}ms`);
+        writeStdoutJson(fallbackResult(`emitInProcess threw: ${message}`));
+        return 3;
+    }
+}
+// Invoke main() when run as a script (the bin entrypoint), not when imported.
+// Both sides resolved through realpath so a symlink shim (npm install -g
+// creates one; operators may also create their own) matches the resolved
+// dist/cli.js path the module loader saw. Without realpath, the entrypoint
+// check fails when the binary is invoked via symlink and the CLI exits
+// silently with no work done. Observed during D082 smoke testing.
+function isInvokedAsEntrypoint() {
+    const argv1 = process.argv[1];
+    if (typeof argv1 !== 'string' || argv1.length === 0)
+        return false;
+    const moduleFile = fileURLToPath(import.meta.url);
+    try {
+        return realpathSync(moduleFile) === realpathSync(argv1);
+    }
+    catch {
+        // realpathSync throws if a path doesn't exist (rare, but possible if
+        // argv[1] is something unusual). Fall back to the unresolved compare.
+        return import.meta.url === pathToFileURL(argv1).href;
+    }
+}
+if (isInvokedAsEntrypoint()) {
+    void main(process.argv.slice(2)).then((code) => {
+        process.exit(code);
+    });
+}