@open-agent-toolkit/cli 0.2.50 → 0.2.52

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/project/links/compute.d.ts

@@ -4,6 +4,7 @@ import { type LinksInput } from './render.js';
 export interface ComputeLinksOptions {
     durableSummaryPath?: string;
     now: Date;
+    ref?: string;
 }
 export declare function computeLinksInput(target: SyncTarget, git: GitRunner, options: ComputeLinksOptions): Promise<LinksInput>;
 //# sourceMappingURL=compute.d.ts.map

package/dist/commands/project/links/compute.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compute.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/links/compute.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAElE,OAAO,EAGL,KAAK,UAAU,EAChB,MAAM,UAAU,CAAC;AAElB,MAAM,WAAW,mBAAmB;IAClC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,GAAG,EAAE,IAAI,CAAC;CACX;AAED,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,SAAS,EACd,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,UAAU,CAAC,CA6BrB"}
+{"version":3,"file":"compute.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/links/compute.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAElE,OAAO,EAGL,KAAK,UAAU,EAChB,MAAM,UAAU,CAAC;AAElB,MAAM,WAAW,mBAAmB;IAClC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,GAAG,EAAE,IAAI,CAAC;IACV,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,SAAS,EACd,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,UAAU,CAAC,CA8BrB"}

package/dist/commands/project/links/compute.js

@@ -1,11 +1,12 @@
 import { LINKABLE_ARTIFACTS, } from './render.js';
 export async function computeLinksInput(target, git, options) {
-    await git.run(['fetch', target.remote, `+${target.ref}:${target.ref}`], {
+    const selectedRef = options.ref ?? target.ref;
+    await git.run(['fetch', target.remote, `+${selectedRef}:${selectedRef}`], {
         cwd: target.repoRoot,
     });
     const [sha, tree, origin] = await Promise.all([
-        git.run(['rev-parse', target.ref], { cwd: target.repoRoot }),
-        git.run(['ls-tree', '--name-only', target.ref], { cwd: target.repoRoot }),
+        git.run(['rev-parse', selectedRef], { cwd: target.repoRoot }),
+        git.run(['ls-tree', '--name-only', selectedRef], { cwd: target.repoRoot }),
         git.run(['remote', 'get-url', target.remote], { cwd: target.repoRoot }),
     ]);
     const treeNames = new Set(tree.stdout
@@ -16,7 +17,7 @@ export async function computeLinksInput(target, git, options) {
     return {
         slug: target.slug,
         sha: sha.stdout,
-        ref: target.ref,
+        ref: selectedRef,
         originUrl: origin.stdout,
         present,
         ...(options.durableSummaryPath

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

@@ -1,17 +1,26 @@
 import { type CommandContext, type GlobalOptions } from '../../../app/command-context.js';
 import { type GitRunner } from '../../project/sync/git.js';
+import { type SyncTarget } from '../../project/sync/ref-sync.js';
 import { resolveSyncedTarget } from '../../project/sync/resolve-target.js';
+import { resolveProjectsRoot } from '../../shared/oat-paths.js';
 import { Command } from 'commander';
 import { computeLinksInput } from './compute.js';
 interface ProjectLinksDependencies {
     buildCommandContext: (options: GlobalOptions) => CommandContext;
     resolveProjectRoot: (cwd: string) => Promise<string>;
+    resolveProjectsRoot: typeof resolveProjectsRoot;
     resolveSyncedTarget: typeof resolveSyncedTarget;
+    resolveLinksTarget: typeof resolveLinksTarget;
     computeLinksInput: typeof computeLinksInput;
     gitRunner: GitRunner;
     processEnv: NodeJS.ProcessEnv;
     now: () => Date;
 }
+interface ResolvedLinksTarget {
+    target: SyncTarget;
+    ref: string;
+}
+export declare function resolveLinksTarget(repoRoot: string, projectsRoot: string, pathOrSlug: string | undefined, env: NodeJS.ProcessEnv, git: GitRunner, resolveTarget: typeof resolveSyncedTarget): Promise<ResolvedLinksTarget>;
 export declare function createProjectLinksCommand(overrides?: Partial<ProjectLinksDependencies>): Command;
 export {};
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/links/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AAI5E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAQ9C,UAAU,wBAAwB;IAChC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,SAAS,EAAE,SAAS,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;IAC9B,GAAG,EAAE,MAAM,IAAI,CAAC;CACjB;AA4ED,wBAAgB,yBAAyB,CACvC,SAAS,GAAE,OAAO,CAAC,wBAAwB,CAAM,GAChD,OAAO,CAsBT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/links/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,EAGL,KAAK,UAAU,EAChB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAEL,mBAAmB,EACpB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AASjE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAQ9C,UAAU,wBAAwB;IAChC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,SAAS,EAAE,SAAS,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;IAC9B,GAAG,EAAE,MAAM,IAAI,CAAC;CACjB;AAmCD,UAAU,mBAAmB;IAC3B,MAAM,EAAE,UAAU,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;CACb;AAwBD,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,GAAG,EAAE,SAAS,EACd,aAAa,EAAE,OAAO,mBAAmB,GACxC,OAAO,CAAC,mBAAmB,CAAC,CAgE9B;AAoDD,wBAAgB,yBAAyB,CACvC,SAAS,GAAE,OAAO,CAAC,wBAAwB,CAAM,GAChD,OAAO,CAsBT"}

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

@@ -1,7 +1,10 @@
 import { isAbsolute, relative, resolve, sep } from 'node:path';
 import { buildCommandContext, } from '../../../app/command-context.js';
 import { defaultGitRunner } from '../../project/sync/git.js';
-import { resolveSyncedTarget } from '../../project/sync/resolve-target.js';
+import { buildSyncTarget, classifyRemoteRefLookup, } from '../../project/sync/ref-sync.js';
+import { probeSyncedTerminalRefs, resolveSyncedTarget, } from '../../project/sync/resolve-target.js';
+import { resolveProjectsRoot } from '../../shared/oat-paths.js';
+import { completedSyncedRefName, resolveProjectScope, resolveScopeRoot, } from '../../shared/project-scope.js';
 import { readGlobalOptions } from '../../shared/shared.utils.js';
 import { CliError } from '../../../errors/cli-error.js';
 import { resolveProjectRoot } from '../../../fs/paths.js';
@@ -11,7 +14,9 @@ import { renderLinksBlock } from './render.js';
 const DEFAULT_DEPENDENCIES = {
     buildCommandContext,
     resolveProjectRoot,
+    resolveProjectsRoot,
     resolveSyncedTarget,
+    resolveLinksTarget,
     computeLinksInput,
     gitRunner: defaultGitRunner,
     processEnv: process.env,
@@ -30,13 +35,77 @@ function normalizeDurableSummaryPath(repoRoot, durableSummaryPath) {
     }
     return repositoryRelative.split(sep).join('/');
 }
+function linksSlug(repoRoot, projectsRoot, pathOrSlug) {
+    if (!pathOrSlug.includes('/') && !pathOrSlug.includes('\\')) {
+        return pathOrSlug;
+    }
+    const absolute = isAbsolute(pathOrSlug)
+        ? resolve(pathOrSlug)
+        : resolve(repoRoot, pathOrSlug);
+    const sharedRoot = resolveScopeRoot(repoRoot, projectsRoot, 'shared');
+    if (resolveProjectScope(absolute, sharedRoot, repoRoot) !== 'synced') {
+        return null;
+    }
+    const child = relative(resolveScopeRoot(repoRoot, projectsRoot, 'synced'), absolute);
+    return child && !child.includes(sep) ? child : null;
+}
+export async function resolveLinksTarget(repoRoot, projectsRoot, pathOrSlug, env, git, resolveTarget) {
+    let resolved = null;
+    let resolutionError;
+    try {
+        resolved = await resolveTarget({ repoRoot, env }, pathOrSlug, { gitRunner: git }, { allowMissingCheckout: true });
+    }
+    catch (error) {
+        resolutionError = error;
+        if (!(error instanceof CliError) ||
+            error.exitCode !== 1 ||
+            !error.message.startsWith('No synced project named ')) {
+            throw error;
+        }
+    }
+    const slug = pathOrSlug
+        ? linksSlug(repoRoot, projectsRoot, pathOrSlug)
+        : resolved?.slug;
+    if (!slug) {
+        if (resolutionError)
+            throw resolutionError;
+        throw new CliError('No synced project is available for link rendering.', 1);
+    }
+    const target = resolved ?? buildSyncTarget(repoRoot, projectsRoot, slug);
+    const completedRef = completedSyncedRefName(slug);
+    const lookup = await git.run(['ls-remote', '--exit-code', target.remote, completedRef], { cwd: repoRoot, allowFailure: true });
+    if (classifyRemoteRefLookup(lookup, target.remote, completedRef) === 'absent') {
+        if (resolutionError)
+            throw resolutionError;
+        return { target, ref: target.ref };
+    }
+    const rows = lookup.stdout.split('\n').filter(Boolean);
+    const [sha, ref] = rows[0]?.trim().split(/\s+/) ?? [];
+    if (rows.length !== 1 ||
+        ref !== completedRef ||
+        !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i.test(sha ?? '')) {
+        throw new CliError(`Unable to verify terminal links for ${slug}: origin returned a malformed completed-ref advertisement.`, 2);
+    }
+    const probe = await probeSyncedTerminalRefs(target, sha, git);
+    if (probe.state === 'wrong-sha') {
+        throw new CliError(`Cannot refresh links for ${slug}: active ${probe.activeRef} is ${probe.activeSha ?? 'absent'} while completed ${probe.completedRef} is ${probe.completedSha ?? 'absent'}. Repair the terminal ref mismatch first.`, 1);
+    }
+    if (probe.state === 'completed-only' || probe.state === 'both') {
+        return { target, ref: completedRef };
+    }
+    if (resolutionError)
+        throw resolutionError;
+    return { target, ref: target.ref };
+}
 async function runLinks(context, pathOrSlug, options, dependencies) {
     try {
         const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
-        const target = await dependencies.resolveSyncedTarget({ repoRoot, env: dependencies.processEnv }, pathOrSlug, {}, { allowMissingCheckout: true });
+        const projectsRoot = await dependencies.resolveProjectsRoot(repoRoot, dependencies.processEnv);
+        const { target, ref } = await dependencies.resolveLinksTarget(repoRoot, projectsRoot, pathOrSlug, dependencies.processEnv, dependencies.gitRunner, dependencies.resolveSyncedTarget);
         const input = await dependencies.computeLinksInput(target, dependencies.gitRunner, {
             durableSummaryPath: normalizeDurableSummaryPath(repoRoot, options.durableSummary),
             now: dependencies.now(),
+            ref,
         });
         const markdown = renderLinksBlock(input);
         if (context.json || options.format === 'json') {

package/dist/commands/project/list.d.ts

@@ -1,7 +1,9 @@
 import { type CommandContext, type GlobalOptions } from '../../app/command-context.js';
 import { type GitRunner } from '../project/sync/git.js';
-import { listSyncedRecords } from '../project/sync/record.js';
-import { type ProjectSummary } from '@open-agent-toolkit/control-plane';
+import { listSyncedRecords, type SyncedProjectRecord } from '../project/sync/record.js';
+import { buildSyncTarget } from '../project/sync/ref-sync.js';
+import { probeSyncedTerminalRefs, type SyncedTerminalRefProbe } from '../project/sync/resolve-target.js';
+import { type ProjectListRow, type ProjectSummary } from '@open-agent-toolkit/control-plane';
 import { Command } from 'commander';
 interface ProjectListDependencies {
     buildCommandContext: (options: GlobalOptions) => CommandContext;
@@ -9,6 +11,8 @@ interface ProjectListDependencies {
     resolveProjectsRoot: (repoRoot: string, env: NodeJS.ProcessEnv) => Promise<string>;
     listProjects: (projectsRoot: string) => Promise<ProjectSummary[]>;
     listSyncedRecords: typeof listSyncedRecords;
+    probeSyncedTerminalRefs: typeof probeSyncedTerminalRefs;
+    probeAuthoritativeCompletedRef: typeof probeAuthoritativeCompletedRef;
     directoryExists: (path: string) => Promise<boolean>;
     readProjectMetadata: (projectPath: string) => Promise<ProjectListMetadata>;
     processEnv: NodeJS.ProcessEnv;
@@ -19,6 +23,10 @@ interface ProjectListMetadata {
     phase: string;
     phaseStatus: string;
 }
+export declare function classifyLegacySyncedRecord(record: SyncedProjectRecord, path: string, probe?: SyncedTerminalRefProbe): Extract<ProjectListRow, {
+    kind: 'recorded-absent' | 'recorded-terminal' | 'terminal-invalid';
+}>;
+export declare function probeAuthoritativeCompletedRef(target: ReturnType<typeof buildSyncTarget>, git: GitRunner): Promise<SyncedTerminalRefProbe | null>;
 export declare function createProjectListCommand(overrides?: Partial<ProjectListDependencies>): Command;
 export {};
 //# sourceMappingURL=list.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../src/commands/project/list.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAWlE,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAE5C,UAAU,uBAAuB;IAC/B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,YAAY,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAClE,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACpD,mBAAmB,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC3E,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;IAC9B,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,UAAU,mBAAmB;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAoXD,wBAAgB,wBAAwB,CACtC,SAAS,GAAE,OAAO,CAAC,uBAAuB,CAAM,GAC/C,OAAO,CAwBT"}
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../src/commands/project/list.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,EACL,iBAAiB,EACjB,KAAK,mBAAmB,EACzB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,eAAe,EAEhB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,uBAAuB,EACvB,KAAK,sBAAsB,EAC5B,MAAM,uCAAuC,CAAC;AAY/C,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,cAAc,EACpB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAE5C,UAAU,uBAAuB;IAC/B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,YAAY,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAClE,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,8BAA8B,EAAE,OAAO,8BAA8B,CAAC;IACtE,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACpD,mBAAmB,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC3E,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;IAC9B,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,UAAU,mBAAmB;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AA6KD,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,mBAAmB,EAC3B,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,sBAAsB,GAC7B,OAAO,CACR,cAAc,EACd;IAAE,IAAI,EAAE,iBAAiB,GAAG,mBAAmB,GAAG,kBAAkB,CAAA;CAAE,CACvE,CA0FA;AAED,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,UAAU,CAAC,OAAO,eAAe,CAAC,EAC1C,GAAG,EAAE,SAAS,GACb,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAwBxC;AA8TD,wBAAgB,wBAAwB,CACtC,SAAS,GAAE,OAAO,CAAC,uBAAuB,CAAM,GAC/C,OAAO,CAwBT"}