@open-agent-toolkit/cli 0.2.51 → 0.2.53

package/dist/commands/project/dispatch/index.js

@@ -0,0 +1,137 @@
+import { readFile } from 'node:fs/promises';
+import { isAbsolute, join } from 'node:path';
+import { buildCommandContext, } from '../../../app/command-context.js';
+import { readGlobalOptions } from '../../shared/shared.utils.js';
+import { fileExists } from '../../../fs/io.js';
+import { resolveProjectRoot, validateRealPathWithinScope } from '../../../fs/paths.js';
+import { Command } from 'commander';
+import { recordProjectDispatch, redactDispatchMessage, } from './record.js';
+const DEFAULT_DEPENDENCIES = {
+    buildCommandContext,
+    resolveProjectRoot,
+    readFile: (path) => readFile(path, 'utf8'),
+    readStdin: async () => {
+        const chunks = [];
+        for await (const chunk of process.stdin) {
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        }
+        return Buffer.concat(chunks).toString('utf8');
+    },
+};
+async function resolveProjectPath(repoRoot, project) {
+    if (!project)
+        return null;
+    const candidate = isAbsolute(project) ? project : join(repoRoot, project);
+    const validated = await validateRealPathWithinScope(candidate, repoRoot);
+    if (!(await fileExists(join(validated.realPath, 'state.md')))) {
+        throw new Error('Project path must contain a readable state.md.');
+    }
+    return validated.realPath;
+}
+function axes(values) {
+    return values
+        .map(([name, value]) => `${name}=${value ?? 'not-reported'}`)
+        .join(' ');
+}
+/**
+ * Render the two layers separately. Configured invocation is launcher-owned and
+ * immutable; runtime observation is optional per-run corroboration. They are
+ * never combined into one "effective" identity, because a mismatch must stay
+ * legible as a mismatch rather than silently overwrite either side.
+ */
+function runtimeIdentityLines(identity) {
+    const { configured, observed } = identity;
+    return [
+        `Configured invocation (immutable): ${axes([
+            ['role', configured.roleName],
+            ['role_selector', configured.roleSelector],
+            ['model', configured.model],
+            ['effort', configured.effort],
+            ['service_tier', configured.serviceTier],
+        ])}`,
+        observed === null
+            ? `Observed runtime identity: not reported${identity.reason === null ? '' : ` (${identity.reason})`} (corroboration only; the configured invocation is unchanged).`
+            : `Observed runtime identity (${observed.source}, ${identity.match} on ${identity.comparedAxes.length === 0
+                ? 'no comparable axis'
+                : identity.comparedAxes.join('+')}): ${axes([
+                ['lineage', observed.childLineage],
+                ['role', observed.role],
+                ['model', observed.model],
+                ['effort', observed.effort],
+                ['service_tier', observed.serviceTier],
+            ])}`,
+    ];
+}
+async function runRecordCommand(options, context, dependencies) {
+    let repoRoot = null;
+    let projectPath = null;
+    try {
+        repoRoot = await dependencies.resolveProjectRoot(context.cwd);
+        projectPath = await resolveProjectPath(repoRoot, options.project);
+        const content = options.eventFile === '-'
+            ? await dependencies.readStdin()
+            : await dependencies.readFile(options.eventFile);
+        // Hand the raw event to the recorder; it owns the single authoritative
+        // parse, and parsing twice would relabel the provenance of its own output.
+        const raw = await recordProjectDispatch({
+            projectPath,
+            input: JSON.parse(content),
+        });
+        // The degradation reason is caller-influenced text on the success path, so
+        // it goes through the same single redaction boundary as every failure
+        // message. Producing a message that skips this boundary is exactly the
+        // per-producer regression this command was restructured to prevent.
+        const result = {
+            ...raw,
+            runtimeIdentity: {
+                ...raw.runtimeIdentity,
+                reason: raw.runtimeIdentity.reason === null
+                    ? null
+                    : redactDispatchMessage(raw.runtimeIdentity.reason, {
+                        project: projectPath,
+                        repo: repoRoot,
+                        home: context.home,
+                    }),
+            },
+        };
+        if (context.json) {
+            context.logger.json(result);
+        }
+        else {
+            if (result.status === 'persisted') {
+                context.logger.success(`Recorded project dispatch: ${result.path}`);
+            }
+            else {
+                context.logger.info('Dispatch evidence is valid; no project path was supplied, so nothing was persisted.');
+            }
+            for (const line of runtimeIdentityLines(result.runtimeIdentity)) {
+                context.logger.info(line);
+            }
+        }
+        process.exitCode = 0;
+    }
+    catch (error) {
+        // Single redaction boundary for every failure this command can surface.
+        const message = redactDispatchMessage(error instanceof Error ? error.message : String(error), { project: projectPath, repo: repoRoot, home: context.home });
+        if (context.json) {
+            context.logger.json({ status: 'error', message });
+        }
+        else {
+            context.logger.error(message);
+        }
+        process.exitCode = 1;
+    }
+}
+export function createProjectDispatchCommand(overrides = {}) {
+    const dependencies = { ...DEFAULT_DEPENDENCIES, ...overrides };
+    return new Command('dispatch')
+        .description('Validate and persist project dispatch provenance')
+        .addCommand(new Command('record')
+        .description('Record one generic dispatch plus namespaced OAT evidence')
+        .option('--project <project-path>', 'Project path; omit to validate without persistence')
+        .requiredOption('--event-file <json-file-or-dash>', 'Complete record and event JSON file, or - for standard input')
+        .action(async (options, command) => {
+        const context = dependencies.buildCommandContext(readGlobalOptions(command));
+        await runRecordCommand(options, context, dependencies);
+    }));
+}

package/dist/commands/project/dispatch/record.d.ts

@@ -0,0 +1,91 @@
+import { type GenericDispatchRecord } from '../../../providers/identity/generic-dispatch-record.js';
+import { type OatDispatchEvidenceEvent, type PersistedOatDispatchRecordV1 } from '../../../providers/identity/oat-dispatch-record.js';
+/**
+ * Test seam for deterministic concurrency coverage. `afterRead` fires after the
+ * caller has read the journal revision it will publish against and before the
+ * writer lock is acquired, which is exactly the window a stale concurrent
+ * writer occupies.
+ */
+export interface DispatchRecordRaceBarriers {
+    afterRead?: () => Promise<void>;
+}
+/**
+ * Hard redaction boundary. Producers redact their own messages, but this is the
+ * last stop before a message reaches `--json`, so a future call site that
+ * forgets cannot regress NFR1. Known roots become stable labels; anything else
+ * that still looks like an absolute path is scrubbed.
+ *
+ * The detector is shared with the record sanitizer. Two independent notions of
+ * "looks like a path" is how a path could be scrubbed from an error message and
+ * written verbatim into the durable record by the same command.
+ */
+export declare function redactDispatchMessage(message: string, roots?: {
+    project?: string | null;
+    repo?: string | null;
+    home?: string | null;
+}): string;
+export interface DispatchRecordInput {
+    record: GenericDispatchRecord;
+    event: OatDispatchEvidenceEvent;
+    /** Why an observation degraded, when one did. Not durable evidence. */
+    observationReason?: string | null;
+}
+/**
+ * Configured and observed identity, reported side by side and never merged.
+ * `configured` is the launcher-owned immutable selection; `observed` is
+ * optional per-run corroboration that is `null` whenever the provider reported
+ * nothing. A `match` of `mismatching` is evidence, not authorization.
+ */
+export interface DispatchRecordRuntimeIdentity {
+    configured: {
+        roleName: string;
+        roleSelector: string | null;
+        model: string | null;
+        effort: string | null;
+        serviceTier: string | null;
+    };
+    observed: {
+        provider: string;
+        source: string;
+        observedAt: string;
+        childLineage: string | null;
+        role: string | null;
+        model: string | null;
+        effort: string | null;
+        serviceTier: string | null;
+    } | null;
+    match: 'matching' | 'mismatching' | 'not-comparable' | null;
+    /**
+     * The axes `match` rests on. A `matching` verdict says nothing about an axis
+     * absent from this list.
+     */
+    comparedAxes: readonly string[];
+    /**
+     * Why an observation is `not-reported`, so a caller attaching a 25 MB rollout
+     * can tell that outcome from one attaching an empty array. A per-command
+     * diagnostic, never durable evidence.
+     */
+    reason: string | null;
+    status: 'reported' | 'not-reported';
+}
+export type ProjectDispatchRecordResult = {
+    status: 'persisted' | 'validated-only';
+    path: string | null;
+    created: boolean;
+    record: PersistedOatDispatchRecordV1;
+    runtimeIdentity: DispatchRecordRuntimeIdentity;
+};
+export declare function parseDispatchRecordInput(value: unknown): DispatchRecordInput;
+/**
+ * Parse once, here. An earlier revision parsed in the command layer and again
+ * here; because the metadata path resolves to a finished observation, the second
+ * parse saw its own output as caller-supplied and overwrote the parser source
+ * with `caller-asserted`. Parsing is not idempotent by design — provenance
+ * depends on which input form arrived — so it must happen exactly once.
+ */
+export declare function recordProjectDispatch(input: {
+    projectPath: string | null;
+    input: unknown;
+    raceBarriers?: DispatchRecordRaceBarriers;
+}): Promise<ProjectDispatchRecordResult>;
+//# sourceMappingURL=record.d.ts.map

package/dist/commands/project/dispatch/record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/dispatch/record.ts"],"names":[],"mappings":"AAcA,OAAO,EAKL,KAAK,qBAAqB,EAC3B,MAAM,6CAA6C,CAAC;AACrD,OAAO,EAOL,KAAK,wBAAwB,EAE7B,KAAK,4BAA4B,EAElC,MAAM,yCAAyC,CAAC;AAWjD;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACjC;AAoCD;;;;;;;;;GASG;AAEH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,KAAK,GAAE;IACL,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjB,GACL,MAAM,CAcR;AAaD,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,qBAAqB,CAAC;IAC9B,KAAK,EAAE,wBAAwB,CAAC;IAChC,uEAAuE;IACvE,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED;;;;;GAKG;AACH,MAAM,WAAW,6BAA6B;IAC5C,UAAU,EAAE;QACV,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;KAC5B,CAAC;IACF,QAAQ,EAAE;QACR,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;KAC5B,GAAG,IAAI,CAAC;IACT,KAAK,EAAE,UAAU,GAAG,aAAa,GAAG,gBAAgB,GAAG,IAAI,CAAC;IAC5D;;;OAGG;IACH,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC;;;;OAIG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,UAAU,GAAG,cAAc,CAAC;CACrC;AAED,MAAM,MAAM,2BAA2B,GAAG;IACxC,MAAM,EAAE,WAAW,GAAG,gBAAgB,CAAC;IACvC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,4BAA4B,CAAC;IACrC,eAAe,EAAE,6BAA6B,CAAC;CAChD,CAAC;AAsEF,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAgF5E;AAgKD;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CAAC,KAAK,EAAE;IACjD,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,OAAO,CAAC;IACf,YAAY,CAAC,EAAE,0BAA0B,CAAC;CAC3C,GAAG,OAAO,CAAC,2BAA2B,CAAC,CA6HvC"}

package/dist/commands/project/dispatch/record.js

@@ -0,0 +1,402 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { publishContainedJsonRevision, redactedFsError, withContainedWriterLock, } from '../../../fs/io.js';
+import { assertJournalIdentityHasNoAbsolutePath, redactAbsolutePaths, } from '../../../providers/identity/absolute-paths.js';
+import { CLAUDE_OBSERVATION_SOURCE } from '../../../providers/identity/claude-runtime-observation.js';
+import { CODEX_OBSERVATION_SOURCE } from '../../../providers/identity/codex-runtime-observation.js';
+import { assertBoundedDispatchRecordSize, assertNoSensitiveDispatchContent, identityFieldsOf, parseGenericDispatchRecord, } from '../../../providers/identity/generic-dispatch-record.js';
+import { augmentDispatchRecord, compareObservedRuntimeMetadata, comparedObservationAxes, configuredInvocationForObservation, parsePersistedOatDispatchRecord, parseRuntimeObservation, } from '../../../providers/identity/oat-dispatch-record.js';
+import { observationFromFacts, parseRuntimeObservationEnvelope, projectRuntimeObservation, providerSupportsRuntimeObservation, } from '../../../providers/identity/runtime-observation.js';
+const REQUEST_ID_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/;
+const DISPATCH_LOCK_NAME = '.dispatch-lock';
+/**
+ * The journal is append-only. Revision 1 keeps the plain `<request-id>.json`
+ * name; every later revision is published create-only under
+ * `<request-id>@<NNNN>.json`. Publishing revision N+1 exclusively is the
+ * compare-and-swap: a caller that lost the race observes `EEXIST` instead of
+ * replacing the winner, and no publication can ever clobber an existing file.
+ * `@` is outside the request-ID character class, so the split is unambiguous.
+ */
+const REVISION_SEPARATOR = '@';
+const REVISION_SUFFIX_PATTERN = /^(.*)@(\d{4})$/;
+const MAX_REVISION = 9999;
+function revisionFileName(requestId, revision) {
+    return revision === 1
+        ? `${requestId}.json`
+        : `${requestId}${REVISION_SEPARATOR}${String(revision).padStart(4, '0')}.json`;
+}
+function parseJournalEntry(fileName) {
+    if (!fileName.endsWith('.json'))
+        return null;
+    const stem = fileName.slice(0, -'.json'.length);
+    const suffixed = REVISION_SUFFIX_PATTERN.exec(stem);
+    const requestId = suffixed?.[1] ?? stem;
+    const revision = suffixed ? Number(suffixed[2]) : 1;
+    if (!REQUEST_ID_PATTERN.test(requestId) || revision < 1)
+        return null;
+    return { requestId, revision, fileName };
+}
+/**
+ * Hard redaction boundary. Producers redact their own messages, but this is the
+ * last stop before a message reaches `--json`, so a future call site that
+ * forgets cannot regress NFR1. Known roots become stable labels; anything else
+ * that still looks like an absolute path is scrubbed.
+ *
+ * The detector is shared with the record sanitizer. Two independent notions of
+ * "looks like a path" is how a path could be scrubbed from an error message and
+ * written verbatim into the durable record by the same command.
+ */
+export function redactDispatchMessage(message, roots = {}) {
+    let redacted = message;
+    const labelled = [
+        ['<project>', roots.project],
+        ['<repo>', roots.repo],
+        ['<home>', roots.home],
+    ];
+    // Longest root first so a nested project path is not masked by its repo.
+    for (const [label, root] of [...labelled].sort(([, left], [, right]) => (right?.length ?? 0) - (left?.length ?? 0))) {
+        if (root)
+            redacted = redacted.split(root).join(label);
+    }
+    return redactAbsolutePaths(redacted);
+}
+/**
+ * Source strings that state provenance. A parser source is only ever written by
+ * the projection path that actually parsed provider output; a caller-supplied
+ * observation is always recorded as caller-asserted.
+ */
+const OBSERVATION_SOURCE_BY_PROVIDER = {
+    codex: CODEX_OBSERVATION_SOURCE,
+    claude: CLAUDE_OBSERVATION_SOURCE,
+};
+const CALLER_ASSERTED_OBSERVATION_SOURCE = 'caller-asserted';
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Resolve a post-launch observation event.
+ *
+ * A caller may submit either a finished `observation` or the sanitized provider
+ * `metadata` it was derived from. Submitting both is ambiguous and is refused
+ * rather than silently preferring one.
+ *
+ * Both forms are validated here, at the durable-write boundary, rather than
+ * being trusted from the producer. An earlier revision normalized only the
+ * metadata form, which left the finished-observation form able to assert its
+ * own `match`, name a provider the record does not use, and store values the
+ * metadata path would have refused. That is the per-producer-obligation class
+ * this boundary exists to prevent, so `match` is always derived and never read
+ * from the caller, and the provider is always bound to the record's own.
+ *
+ * Value shape is enforced once more in `runtimeObservationSchema`, so both
+ * forms converge on the same identifier rules without either path carrying its
+ * own copy of them.
+ */
+function resolveObservationEvent(record, event) {
+    if (event.kind !== 'runtime-observation')
+        return event;
+    if ('metadata' in event && 'observation' in event) {
+        throw new Error('A runtime observation event carries either observation or metadata, not both.');
+    }
+    if ('metadata' in event)
+        return event;
+    const observation = event.observation;
+    if (!isRecord(observation) || observation.status !== 'reported') {
+        return event;
+    }
+    if (observation.provider !== record.provider) {
+        throw new Error('A runtime observation must name the same provider as its dispatch record.');
+    }
+    if (!providerSupportsRuntimeObservation(record.provider)) {
+        throw new Error(`Provider ${record.provider} has no runtime observation capability, so it cannot report an observation.`);
+    }
+    return {
+        ...event,
+        observation: parseRuntimeObservation({
+            ...observation,
+            // Provenance is derived, never accepted: a hand-authored observation
+            // cannot borrow a parser's source string and pass as a genuine parse.
+            source: CALLER_ASSERTED_OBSERVATION_SOURCE,
+            match: compareObservedRuntimeMetadata(observation, configuredInvocationForObservation(record)),
+            comparedAxes: comparedObservationAxes(observation, configuredInvocationForObservation(record)),
+        }),
+    };
+}
+export function parseDispatchRecordInput(value) {
+    if (!isRecord(value)) {
+        throw new Error('Dispatch record input must be a JSON object.');
+    }
+    const keys = Object.keys(value).sort();
+    if (keys.length !== 2 || keys[0] !== 'event' || keys[1] !== 'record') {
+        throw new Error('Dispatch record input accepts only record and event.');
+    }
+    if (!isRecord(value.event)) {
+        throw new Error('Dispatch record event must be a JSON object.');
+    }
+    // Raw provider metadata is the one input a caller may legitimately supply
+    // unmodified, so it is projected through the owning parser's allowlist and
+    // asserted as the projection. Everything else is asserted exactly as given.
+    // Asserting the raw entries instead would refuse real rollouts outright —
+    // a Codex `session_id` alone classifies as sensitive — which is what pushed
+    // sanitization onto callers and invited a hand-rolled stripper.
+    const rawMetadata = isRecord(value.event.metadata)
+        ? value.event.metadata
+        : null;
+    assertNoSensitiveDispatchContent(rawMetadata === null
+        ? value
+        : {
+            ...value,
+            event: {
+                ...value.event,
+                metadata: { ...rawMetadata, entries: null },
+            },
+        });
+    const record = parseGenericDispatchRecord(value.record);
+    if (rawMetadata !== null) {
+        if ('observation' in value.event) {
+            throw new Error('A runtime observation event carries either observation or metadata, not both.');
+        }
+        const envelope = parseRuntimeObservationEnvelope(rawMetadata);
+        const projected = envelope.provider === record.provider
+            ? projectRuntimeObservation(envelope.provider, envelope.entries)
+            : {
+                facts: null,
+                reason: `observation metadata names provider ${envelope.provider}, but the record names ${record.provider}`,
+            };
+        const facts = projected.facts;
+        assertNoSensitiveDispatchContent(facts, '<observation-metadata>');
+        const { metadata: _metadata, ...rest } = value.event;
+        // Built here from parsed provider output, so it carries a parser source and
+        // must not be re-processed as if a caller had supplied it.
+        const observation = observationFromFacts({
+            record,
+            provider: envelope.provider,
+            source: OBSERVATION_SOURCE_BY_PROVIDER[envelope.provider] ?? 'unknown',
+            observedAt: envelope.observedAt,
+            facts,
+        });
+        return {
+            record,
+            event: { ...rest, observation },
+            observationReason: observation.status === 'reported'
+                ? null
+                : // Facts can be produced and still be declined downstream, when the
+                    // session declares a different request than this record does.
+                    (projected.reason ??
+                        'observation metadata correlates to a different request'),
+        };
+    }
+    return {
+        record,
+        event: resolveObservationEvent(record, value.event),
+    };
+}
+function runtimeIdentityFor(record, reason = null) {
+    const observation = record.oat.runtimeObservation;
+    return {
+        configured: {
+            roleName: record.role_name,
+            roleSelector: record.role_selector,
+            model: record.model_selector,
+            effort: record.effort_selector,
+            serviceTier: record.service_tier_selector ?? null,
+        },
+        observed: observation.status === 'reported'
+            ? {
+                provider: observation.provider,
+                source: observation.source,
+                observedAt: observation.observedAt,
+                childLineage: observation.childLineage ?? null,
+                role: observation.role ?? null,
+                model: observation.model ?? null,
+                effort: observation.effort ?? null,
+                serviceTier: observation.serviceTier ?? null,
+            }
+            : null,
+        match: observation.status === 'reported' ? observation.match : null,
+        comparedAxes: observation.status === 'reported' ? (observation.comparedAxes ?? []) : [],
+        reason: observation.status === 'reported' ? null : reason,
+        status: observation.status,
+    };
+}
+function genericPart(record) {
+    const { oat: _oat, ...generic } = record;
+    return parseGenericDispatchRecord(generic);
+}
+function sameGenericRecord(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function isMissingError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === 'ENOENT');
+}
+async function readPersistedRecord(path, reportedPath) {
+    let content;
+    try {
+        content = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (isMissingError(error)) {
+            return null;
+        }
+        // A damaged or unreadable journal must not put an absolute project path
+        // into durable output; NFR1 treats that as a P0 disclosure.
+        throw redactedFsError(error, 'read', reportedPath);
+    }
+    return parsePersistedOatDispatchRecord(JSON.parse(content));
+}
+/** Highest published revision per request ID. */
+async function readLatestRevisions(dispatchDir) {
+    let names;
+    try {
+        names = await readdir(dispatchDir);
+    }
+    catch (error) {
+        if (isMissingError(error)) {
+            return new Map();
+        }
+        throw redactedFsError(error, 'scan', 'dispatch/');
+    }
+    const latest = new Map();
+    for (const name of names.sort()) {
+        const entry = parseJournalEntry(name);
+        if (!entry)
+            continue;
+        const known = latest.get(entry.requestId);
+        if (!known || entry.revision > known.revision) {
+            latest.set(entry.requestId, entry);
+        }
+    }
+    return latest;
+}
+function fallbackTriggerRequestId(event) {
+    if (event.kind !== 'fallback-link')
+        return null;
+    const requestId = event.evidence?.triggerRequestId;
+    if (typeof requestId !== 'string' || !REQUEST_ID_PATTERN.test(requestId)) {
+        throw new Error('Fallback trigger request ID is invalid.');
+    }
+    return requestId;
+}
+function isAlreadyPublished(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === 'EEXIST');
+}
+async function publishRevision(projectPath, dispatchDir, requestId, revision, record) {
+    if (revision > MAX_REVISION) {
+        throw new Error(`Dispatch journal for ${requestId} reached its ${MAX_REVISION}-revision limit.`);
+    }
+    const fileName = revisionFileName(requestId, revision);
+    // Last check before bytes reach the journal. The sanitizer runs at parse, but
+    // the journal is committed to a shared repository, so the guarantee is
+    // enforced on the exact value being written rather than trusted upstream.
+    // Guarantees identity and control fields only; prose redaction is
+    // best-effort by design. See absolute-paths.ts.
+    assertJournalIdentityHasNoAbsolutePath(identityFieldsOf(genericPart(record)));
+    assertBoundedDispatchRecordSize(record);
+    try {
+        await publishContainedJsonRevision(join(dispatchDir, fileName), record, projectPath);
+    }
+    catch (error) {
+        if (isAlreadyPublished(error)) {
+            throw new Error('The dispatch journal advanced to a newer revision while this write was prepared; the concurrent update was preserved and this stale write was refused.', { cause: error });
+        }
+        throw error;
+    }
+    return `dispatch/${fileName}`;
+}
+/**
+ * Parse once, here. An earlier revision parsed in the command layer and again
+ * here; because the metadata path resolves to a finished observation, the second
+ * parse saw its own output as caller-supplied and overwrote the parser source
+ * with `caller-asserted`. Parsing is not idempotent by design — provenance
+ * depends on which input form arrived — so it must happen exactly once.
+ */
+export async function recordProjectDispatch(input) {
+    const parsedInput = parseDispatchRecordInput(input.input);
+    if (input.projectPath === null) {
+        const record = augmentDispatchRecord(parsedInput);
+        return {
+            status: 'validated-only',
+            path: null,
+            created: false,
+            record,
+            runtimeIdentity: runtimeIdentityFor(record, parsedInput.observationReason ?? null),
+        };
+    }
+    const projectPath = input.projectPath;
+    const dispatchDir = join(projectPath, 'dispatch');
+    const requestId = parsedInput.record.request_id;
+    const latest = await readLatestRevisions(dispatchDir);
+    const existingEntry = latest.get(requestId) ?? null;
+    const existing = existingEntry
+        ? await readPersistedRecord(join(dispatchDir, existingEntry.fileName), `dispatch/${existingEntry.fileName}`)
+        : null;
+    if (existing &&
+        !sameGenericRecord(genericPart(existing), parsedInput.record)) {
+        throw new Error('Existing generic fields are immutable and cannot be redefined.');
+    }
+    const relatedRecords = [];
+    for (const [otherId, entry] of [...latest].sort(([left], [right]) => left < right ? -1 : 1)) {
+        if (otherId === requestId)
+            continue;
+        const related = await readPersistedRecord(join(dispatchDir, entry.fileName), `dispatch/${entry.fileName}`);
+        if (related)
+            relatedRecords.push(related);
+    }
+    const triggerRequestId = fallbackTriggerRequestId(parsedInput.event);
+    const triggerEntry = triggerRequestId
+        ? (latest.get(triggerRequestId) ?? null)
+        : null;
+    const trigger = triggerEntry
+        ? await readPersistedRecord(join(dispatchDir, triggerEntry.fileName), `dispatch/${triggerEntry.fileName}`)
+        : null;
+    if (triggerRequestId !== null && trigger === null) {
+        throw new Error('Fallback requires the rejected trigger record.');
+    }
+    await input.raceBarriers?.afterRead?.();
+    // One shared, identity-bound transition. The lock serializes the trigger
+    // claim and the fallback publication; the exclusive revision name is the
+    // compare-and-swap, so a stale concurrent writer loses without any write
+    // being able to replace the winner's evidence.
+    return withContainedWriterLock(join(projectPath, DISPATCH_LOCK_NAME), projectPath, async () => {
+        let triggerRecord = trigger ?? undefined;
+        if (trigger && triggerEntry && triggerRequestId) {
+            const claimed = augmentDispatchRecord({
+                record: trigger,
+                event: {
+                    kind: 'fallback-claim',
+                    requestId: triggerRequestId,
+                    source: 'provider-wrapper',
+                    claim: {
+                        fallbackRequestId: requestId,
+                        claimedAt: new Date().toISOString(),
+                    },
+                },
+            });
+            if (JSON.stringify(claimed) !== JSON.stringify(trigger)) {
+                await publishRevision(projectPath, dispatchDir, triggerRequestId, triggerEntry.revision + 1, claimed);
+            }
+            triggerRecord = claimed;
+        }
+        const record = augmentDispatchRecord({
+            record: existing ?? parsedInput.record,
+            event: parsedInput.event,
+            ...(triggerRecord ? { triggerRecord } : {}),
+            relatedRecords,
+        });
+        const revision = (existingEntry?.revision ?? 0) + 1;
+        const path = await publishRevision(projectPath, dispatchDir, requestId, revision, record);
+        return {
+            status: 'persisted',
+            path,
+            created: revision === 1,
+            record,
+            runtimeIdentity: runtimeIdentityFor(record, parsedInput.observationReason ?? null),
+        };
+    });
+}

package/dist/commands/project/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/project/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsBpC,wBAAgB,oBAAoB,IAAI,OAAO,CAsB9C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/project/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuBpC,wBAAgB,oBAAoB,IAAI,OAAO,CAuB9C"}

package/dist/commands/project/index.js

@@ -2,6 +2,7 @@ import { Command } from 'commander';
 import { createProjectArchiveCommand } from './archive/index.js';
 import { createProjectCompleteDiscoveryCommand } from './complete-discovery/index.js';
 import { createProjectCompleteStateCommand } from './complete-state/index.js';
+import { createProjectDispatchCommand } from './dispatch/index.js';
 import { createProjectDispatchCeilingCommand } from './dispatch-ceiling/index.js';
 import { createProjectLinksCommand } from './links/index.js';
 import { createProjectListCommand } from './list.js';
@@ -24,6 +25,7 @@ export function createProjectCommand() {
         .addCommand(createProjectArchiveCommand())
         .addCommand(createProjectCompleteDiscoveryCommand())
         .addCommand(createProjectCompleteStateCommand())
+        .addCommand(createProjectDispatchCommand())
         .addCommand(createProjectDispatchCeilingCommand())
         .addCommand(createProjectListCommand())
         .addCommand(createProjectLinksCommand())

package/dist/commands/providers/inspect/inspect.d.ts

@@ -1,4 +1,11 @@
 import type { ProvidersInspectDependencies } from '../../providers/providers.types.js';
+import { loadSyncConfig } from '../../../config/index.js';
+import { resolveProviderScopeContext } from '../../../providers/shared/index.js';
 import { Command } from 'commander';
-export declare function createProvidersInspectCommand(overrides?: Partial<ProvidersInspectDependencies>): Command;
+type ContextualInspectDependencies = ProvidersInspectDependencies & {
+    loadSyncConfig?: typeof loadSyncConfig;
+    resolveProviderScopeContext?: typeof resolveProviderScopeContext;
+};
+export declare function createProvidersInspectCommand(overrides?: Partial<ContextualInspectDependencies>): Command;
+export {};
 //# sourceMappingURL=inspect.d.ts.map

package/dist/commands/providers/inspect/inspect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../../../src/commands/providers/inspect/inspect.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAGV,4BAA4B,EAC7B,MAAM,qCAAqC,CAAC;AAoB7C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuLpC,wBAAgB,6BAA6B,CAC3C,SAAS,GAAE,OAAO,CAAC,4BAA4B,CAAM,GACpD,OAAO,CAiBT"}
+{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../../../src/commands/providers/inspect/inspect.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAKV,4BAA4B,EAC7B,MAAM,qCAAqC,CAAC;AAM7C,OAAO,EAAuB,cAAc,EAAE,MAAM,eAAe,CAAC;AAQpE,OAAO,EAGL,2BAA2B,EAG5B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,KAAK,6BAA6B,GAAG,4BAA4B,GAAG;IAClE,cAAc,CAAC,EAAE,OAAO,cAAc,CAAC;IACvC,2BAA2B,CAAC,EAAE,OAAO,2BAA2B,CAAC;CAClE,CAAC;AAmWF,wBAAgB,6BAA6B,CAC3C,SAAS,GAAE,OAAO,CAAC,6BAA6B,CAAM,GACrD,OAAO,CAuBT"}