diff --git a/src/genie-commands/__tests__/update.test.ts b/src/genie-commands/__tests__/update.test.ts index 4b21c43e0..aaca9993e 100644 --- a/src/genie-commands/__tests__/update.test.ts +++ b/src/genie-commands/__tests__/update.test.ts @@ -47,6 +47,7 @@ import { type VerifyResult, _resetNextDeprecationLatchForTest, applyConvergenceExitSignal, + attemptAlreadyCurrentDeliveryRepair, compareVersions, createPrivateUpdateTempRoot, decideDowngrade, @@ -60,6 +61,7 @@ import { hashPhysicalFileIncrementally, isGenieProcessSnapshotLine, manifestUrlForChannel, + mapAlreadyCurrentRepairOutcome, narrowUpdateAgentSyncSelection, normalizeVersion, persistChannel, @@ -2766,3 +2768,85 @@ describe('applyConvergenceExitSignal — exit 2 only on delivery-pending (D3 gua expect(logs.join('\n')).not.toContain('deliveryComplete'); }); }); + +describe('mapAlreadyCurrentRepairOutcome — pure repair→directive mapping (Group D deliverable 1)', () => { + test('an old-parent publish (activation-pending) hands off to setup', () => { + expect( + mapAlreadyCurrentRepairOutcome({ + kind: 'published', + record: { + schemaVersion: 1, + deliveryId: 'a'.repeat(32), + targetVersion: '5.260722.11', + canonicalPayloadSha256: 'a'.repeat(64), + channel: 'dev', + deliveredAt: '2026-07-22T00:00:00.000Z', + }, + handoff: 'activation-pending', + artifactSha256: 'd'.repeat(64), + }), + ).toEqual({ action: 'exit-handoff' }); + }); + + test('a target-current publish reports the repair and continues the current path', () => { + expect( + mapAlreadyCurrentRepairOutcome({ + kind: 'published', + record: { + schemaVersion: 1, + deliveryId: 'a'.repeat(32), + targetVersion: '5.260722.11', + canonicalPayloadSha256: 'a'.repeat(64), + channel: 'dev', + deliveredAt: '2026-07-22T00:00:00.000Z', + }, + handoff: 'current', + artifactSha256: 'd'.repeat(64), + }), + ).toEqual({ action: 'repaired-current' }); + }); + + test('already-matching, channel-advanced, and failed all proceed unchanged', () => { + expect(mapAlreadyCurrentRepairOutcome({ kind: 'already-matching' })).toEqual({ action: 'proceed-current' }); + expect( + mapAlreadyCurrentRepairOutcome({ kind: 'channel-advanced', from: '5.260722.11', to: '5.260722.12' }), + ).toEqual({ action: 'proceed-current' }); + expect( + mapAlreadyCurrentRepairOutcome({ + kind: 'failed', + stage: 'download-verify', + detail: 'x', + deliveryComplete: false, + }), + ).toEqual({ action: 'proceed-current' }); + }); +}); + +describe('attemptAlreadyCurrentDeliveryRepair — fail-closed skip with no install (CI-portable, no network/codex)', () => { + let prevGenieHome: string | undefined; + let dir: string; + + beforeEach(() => { + prevGenieHome = process.env.GENIE_HOME; + dir = mkdtempSync(join(tmpdir(), 'update-repair-skip-')); + process.env.GENIE_HOME = dir; + }); + + afterEach(() => { + if (prevGenieHome === undefined) Reflect.deleteProperty(process.env, 'GENIE_HOME'); + else process.env.GENIE_HOME = prevGenieHome; + rmSync(dir, { recursive: true, force: true }); + }); + + test('an empty GENIE_HOME (no installed payload) proceeds without any lease, download, or mutation', async () => { + // No plugins/genie payload and no binary ⇒ observeInstalledForRepair returns + // null ⇒ the repair is skipped entirely. This is the common already-current + // case in a CI environment: never touches the network or the codex CLI. + const directive = await attemptAlreadyCurrentDeliveryRepair('dev', 'linux-x64'); + expect(directive).toEqual({ action: 'proceed-current' }); + // No lease file was created (the skip returns before lease acquisition). + expect(existsSync(join(dir, '.codex-lifecycle.lock'))).toBe(false); + // No delivery record was minted. + expect(existsSync(join(dir, '.codex-plugin-delivery-record.json'))).toBe(false); + }); +}); diff --git a/src/genie-commands/codex-delivery-repair.test.ts b/src/genie-commands/codex-delivery-repair.test.ts new file mode 100644 index 000000000..d5e6b143d --- /dev/null +++ b/src/genie-commands/codex-delivery-repair.test.ts @@ -0,0 +1,441 @@ +import { describe, expect, test } from 'bun:test'; +import type { CodexActivationStore, DeliveryRecord, PublishDeliveryInput } from '../lib/codex-activation.js'; +import type { DeliveryRecordReadState } from '../lib/codex-host-observation.js'; +import type { HeldLifecycleLease } from '../lib/codex-lifecycle-lease.js'; +import { + type CandidateProof, + type DeliveryRepairSeams, + type InstalledProof, + type PinnedManifest, + type ReobservedTarget, + type RepairPinnedTarget, + buildLocalRepairExpectation, + repairMissingDelivery, +} from './codex-delivery-repair.js'; + +const T = '5.260722.11'; +const N = '5.260722.1'; +const PLATFORM = 'darwin-arm64'; +const RELEASE_TAG = `v${T}`; +const RELEASE_NAME = `genie-${T}-darwin-arm64.tar.gz`; +const CHANNEL = 'dev'; +const PAYLOAD_DIGEST = 'a'.repeat(64); +const BINARY_DIGEST = 'b'.repeat(64); +const MANIFEST_DIGEST = 'c'.repeat(64); +const ARTIFACT_DIGEST = 'd'.repeat(64); +const DELIVERY_ROOT = '/home/dev/.genie'; +const TARBALL_PATH = '/tmp/repair/genie.tar.gz'; + +const PINNED: RepairPinnedTarget = { + channel: CHANNEL, + targetVersion: T, + platformTriple: PLATFORM, + releaseTag: RELEASE_TAG, + releaseName: RELEASE_NAME, +}; + +const INSTALLED: InstalledProof = { + version: T, + pluginTreeSha256: PAYLOAD_DIGEST, + binarySha256: BINARY_DIGEST, + deliveryRoot: DELIVERY_ROOT, +}; + +/** A store that records exactly which methods were invoked and echoes the publish input. */ +function spyStore(): { store: CodexActivationStore; publishCalls: PublishDeliveryInput[]; touched: string[] } { + const publishCalls: PublishDeliveryInput[] = []; + const touched: string[] = []; + const forbid = (name: string) => () => { + touched.push(name); + throw new Error(`repair must never call ${name}`); + }; + const store: CodexActivationStore = { + observe: forbid('observe') as CodexActivationStore['observe'], + publishDelivery(_lease, input): DeliveryRecord { + touched.push('publishDelivery'); + publishCalls.push(input); + return { + schemaVersion: 1, + deliveryId: input.deliveryId ?? 'e'.repeat(32), + targetVersion: input.targetVersion, + canonicalPayloadSha256: input.canonicalPayloadSha256, + channel: input.channel, + deliveredAt: '2026-07-22T00:00:00.000Z', + ...(input.attestation ?? {}), + }; + }, + withRevalidatedDeliveryRoot: forbid( + 'withRevalidatedDeliveryRoot', + ) as CodexActivationStore['withRevalidatedDeliveryRoot'], + beginActivation: forbid('beginActivation') as CodexActivationStore['beginActivation'], + advanceIntentPhase: forbid('advanceIntentPhase') as CodexActivationStore['advanceIntentPhase'], + finalizeActivation: forbid('finalizeActivation') as CodexActivationStore['finalizeActivation'], + quarantineIntent: forbid('quarantineIntent') as CodexActivationStore['quarantineIntent'], + }; + return { store, publishCalls, touched }; +} + +function spyLease(): HeldLifecycleLease { + return { ok: true, operationId: 'f'.repeat(32), kind: 'update-delivery', assertOperation() {}, release() {} }; +} + +interface SeamOverrides { + readDeliveryRecord?: () => DeliveryRecordReadState; + observeInstalled?: () => InstalledProof; + fetchManifest?: (channel: string) => Promise; + downloadAndVerify?: (target: RepairPinnedTarget) => Promise; + hashArtifact?: (path: string) => string; + proveCandidate?: (path: string) => Promise; + reobserve?: () => ReobservedTarget | null; + installedGeneration?: string | null; + store?: CodexActivationStore; +} + +/** Happy-path seams + a call log; overrides let each test tamper exactly one stage. */ +function makeSeams(overrides: SeamOverrides = {}): { seams: DeliveryRepairSeams; log: string[] } { + const log: string[] = []; + const installedGeneration = overrides.installedGeneration ?? N; // old-parent by default + const store = overrides.store ?? spyStore().store; + const seams: DeliveryRepairSeams = { + readDeliveryRecord: + overrides.readDeliveryRecord ?? + (() => { + log.push('readDeliveryRecord'); + return { status: 'absent' }; + }), + observeInstalled: + overrides.observeInstalled ?? + (() => { + log.push('observeInstalled'); + return INSTALLED; + }), + fetchManifest: + overrides.fetchManifest ?? + (async (channel) => { + log.push(`fetchManifest:${channel}`); + return { version: T, manifestSha256: MANIFEST_DIGEST }; + }), + downloadAndVerify: + overrides.downloadAndVerify ?? + (async (target) => { + log.push(`downloadAndVerify:${target.releaseName}`); + return TARBALL_PATH; + }), + hashArtifact: + overrides.hashArtifact ?? + ((path) => { + log.push(`hashArtifact:${path}`); + return ARTIFACT_DIGEST; + }), + proveCandidate: + overrides.proveCandidate ?? + (async (path) => { + log.push(`proveCandidate:${path}`); + return { version: T, pluginTreeSha256: PAYLOAD_DIGEST, binarySha256: BINARY_DIGEST }; + }), + reobserve: + overrides.reobserve ?? + (() => { + log.push('reobserve'); + return { installedGeneration, canonicalVersion: T, canonicalPayloadSha256: PAYLOAD_DIGEST }; + }), + store, + lease: spyLease(), + deliveryId: 'a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6', + }; + return { seams, log }; +} + +/** A present authenticated record binding exactly the local tuple (drives the fast path). */ +function matchingRecordReadState(): DeliveryRecordReadState { + return { + status: 'present', + record: { + targetVersion: T, + canonicalPayloadSha256: PAYLOAD_DIGEST, + channel: CHANNEL, + deliveryId: 'a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6', + platformTriple: PLATFORM, + releaseTag: RELEASE_TAG, + releaseName: RELEASE_NAME, + releaseManifestSha256: MANIFEST_DIGEST, + artifactSha256: ARTIFACT_DIGEST, + installedBinarySha256: BINARY_DIGEST, + deliveryRoot: DELIVERY_ROOT, + }, + }; +} + +describe('buildLocalRepairExpectation — binds only locally-known fields (no network digests)', () => { + test('binds the local tuple and omits the manifest/artifact digests', () => { + const expectation = buildLocalRepairExpectation(PINNED, INSTALLED); + expect(expectation).toEqual({ + targetVersion: T, + canonicalPayloadSha256: PAYLOAD_DIGEST, + channel: CHANNEL, + platformTriple: PLATFORM, + releaseTag: RELEASE_TAG, + releaseName: RELEASE_NAME, + installedBinarySha256: BINARY_DIGEST, + deliveryRoot: DELIVERY_ROOT, + }); + // The two network-derived digests are never bound in the fast path. + expect('releaseManifestSha256' in expectation).toBe(false); + expect('artifactSha256' in expectation).toBe(false); + }); +}); + +describe('no-network fast path — a matching record downloads and publishes nothing', () => { + test('already-matching record returns without any network or publish', async () => { + const { store, publishCalls, touched } = spyStore(); + const { seams, log } = makeSeams({ store, readDeliveryRecord: () => matchingRecordReadState() }); + const outcome = await repairMissingDelivery(PINNED, seams); + expect(outcome).toEqual({ kind: 'already-matching' }); + expect(publishCalls).toHaveLength(0); + expect(touched).toEqual([]); + // No manifest fetch, download, hash, or prove happened. + expect(log.some((entry) => entry.startsWith('fetchManifest'))).toBe(false); + expect(log.some((entry) => entry.startsWith('downloadAndVerify'))).toBe(false); + }); + + test('a repeated repair after publication (matching record) still performs no download', async () => { + // Simulate the second run: the record now binds the tuple. + const { seams, log } = makeSeams({ readDeliveryRecord: () => matchingRecordReadState() }); + const outcome = await repairMissingDelivery(PINNED, seams); + expect(outcome.kind).toBe('already-matching'); + expect(log.filter((entry) => entry.startsWith('downloadAndVerify'))).toHaveLength(0); + }); +}); + +describe('old-parent → current-target / no-record: publishes one bound record, keeps N, handoff activation-pending', () => { + test('publishes exactly one record bound to the pinned tuple with the persisted authenticated digest', async () => { + const { store, publishCalls, touched } = spyStore(); + const { seams } = makeSeams({ store, installedGeneration: N }); + const outcome = await repairMissingDelivery(PINNED, seams); + expect(outcome.kind).toBe('published'); + if (outcome.kind !== 'published') throw new Error('expected published'); + expect(outcome.handoff).toBe('activation-pending'); // N < T ⇒ still needs setup activation + expect(outcome.artifactSha256).toBe(ARTIFACT_DIGEST); + // Exactly one publish; no activation-owned store method touched. + expect(publishCalls).toHaveLength(1); + expect(touched).toEqual(['publishDelivery']); + // The record binds the full pinned tuple, including the computed authenticated digest. + expect(publishCalls[0].attestation).toEqual({ + platformTriple: PLATFORM, + releaseTag: RELEASE_TAG, + releaseName: RELEASE_NAME, + releaseManifestSha256: MANIFEST_DIGEST, + artifactSha256: ARTIFACT_DIGEST, + installedBinarySha256: BINARY_DIGEST, + deliveryRoot: DELIVERY_ROOT, + }); + expect(publishCalls[0].targetVersion).toBe(T); + expect(publishCalls[0].canonicalPayloadSha256).toBe(PAYLOAD_DIGEST); + expect(publishCalls[0].channel).toBe(CHANNEL); + }); + + test('pins channel/version/platform/tag/name + manifest digest BEFORE the download, and hashes AFTER', async () => { + const { seams, log } = makeSeams({ installedGeneration: N }); + await repairMissingDelivery(PINNED, seams); + const firstFetch = log.findIndex((entry) => entry.startsWith('fetchManifest')); + const download = log.findIndex((entry) => entry.startsWith('downloadAndVerify')); + const hash = log.findIndex((entry) => entry.startsWith('hashArtifact')); + // Manifest is pinned before the asset download; the digest is computed after. + expect(firstFetch).toBeGreaterThanOrEqual(0); + expect(firstFetch).toBeLessThan(download); + expect(download).toBeLessThan(hash); + // The download names the exact pinned asset. + expect(log[download]).toBe(`downloadAndVerify:${RELEASE_NAME}`); + }); +}); + +describe('live target-current / removal-observed: repairs with no plugin command', () => { + test('registered N == T ⇒ published handoff current, only publishDelivery touched', async () => { + const { store, touched } = spyStore(); + const { seams } = makeSeams({ store, installedGeneration: T }); + const outcome = await repairMissingDelivery(PINNED, seams); + expect(outcome.kind).toBe('published'); + if (outcome.kind === 'published') expect(outcome.handoff).toBe('current'); + expect(touched).toEqual(['publishDelivery']); // no plugin/activation mutation + }); + + test('removal-observed (registration absent) ⇒ published handoff activation-pending', async () => { + const { seams } = makeSeams({ installedGeneration: null }); + const outcome = await repairMissingDelivery(PINNED, seams); + expect(outcome.kind).toBe('published'); + if (outcome.kind === 'published') expect(outcome.handoff).toBe('activation-pending'); + }); +}); + +describe('channel advance routes to ordinary upgrade and mints no record for stale bytes', () => { + test('pre-download advance: the pinned manifest already names a newer version', async () => { + const { store, publishCalls } = spyStore(); + const { seams, log } = makeSeams({ + store, + fetchManifest: async () => ({ version: '5.260722.12', manifestSha256: MANIFEST_DIGEST }), + }); + const outcome = await repairMissingDelivery(PINNED, seams); + expect(outcome).toEqual({ kind: 'channel-advanced', from: T, to: '5.260722.12' }); + expect(publishCalls).toHaveLength(0); + // Never downloads stale bytes when the channel already advanced. + expect(log.some((entry) => entry.startsWith('downloadAndVerify'))).toBe(false); + }); + + test('under-lease recheck advance: channel moved after download ⇒ no publish', async () => { + const { store, publishCalls } = spyStore(); + let call = 0; + const { seams } = makeSeams({ + store, + fetchManifest: async () => { + call += 1; + return call === 1 + ? { version: T, manifestSha256: MANIFEST_DIGEST } + : { version: '5.260722.12', manifestSha256: 'f'.repeat(64) }; + }, + }); + const outcome = await repairMissingDelivery(PINNED, seams); + expect(outcome).toEqual({ kind: 'channel-advanced', from: T, to: '5.260722.12' }); + expect(publishCalls).toHaveLength(0); + }); +}); + +describe('tamper / lease / reobservation matrix — every failure leaves state unchanged, deliveryComplete:false', () => { + async function expectUnchangedFailure(overrides: SeamOverrides, stage: string): Promise { + const spy = spyStore(); + const { seams } = makeSeams({ ...overrides, store: spy.store }); + const outcome = await repairMissingDelivery(PINNED, seams); + expect(outcome.kind).toBe('failed'); + if (outcome.kind !== 'failed') throw new Error('expected failed'); + expect(outcome.stage).toBe(stage as never); + expect(outcome.deliveryComplete).toBe(false); + // Nothing was published; no store method mutated durable state. + expect(spy.publishCalls).toHaveLength(0); + expect(spy.touched).toEqual([]); + } + + test('manifest unavailable at pin time', async () => { + await expectUnchangedFailure({ fetchManifest: async () => null }, 'manifest-pin'); + }); + + test('artifact signature/attestation rejects the download', async () => { + await expectUnchangedFailure( + { + downloadAndVerify: async () => { + throw new Error('signature verification failed'); + }, + }, + 'download-verify', + ); + }); + + test('artifact digest computation fails', async () => { + await expectUnchangedFailure( + { + hashArtifact: () => { + throw new Error('cannot read tarball'); + }, + }, + 'artifact-digest', + ); + }); + + test('private extraction/prove fails', async () => { + await expectUnchangedFailure( + { + proveCandidate: async () => { + throw new Error('symlink in payload'); + }, + }, + 'extract-prove', + ); + }); + + test('candidate version tampering', async () => { + await expectUnchangedFailure( + { + proveCandidate: async () => ({ + version: '5.260722.9', + pluginTreeSha256: PAYLOAD_DIGEST, + binarySha256: BINARY_DIGEST, + }), + }, + 'candidate-version', + ); + }); + + test('payload tampering — candidate plugin tree differs from installed', async () => { + await expectUnchangedFailure( + { proveCandidate: async () => ({ version: T, pluginTreeSha256: '9'.repeat(64), binarySha256: BINARY_DIGEST }) }, + 'candidate-payload', + ); + }); + + test('installed-byte tampering — candidate binary differs from installed', async () => { + await expectUnchangedFailure( + { proveCandidate: async () => ({ version: T, pluginTreeSha256: PAYLOAD_DIGEST, binarySha256: '9'.repeat(64) }) }, + 'candidate-binary', + ); + }); + + test('manifest tampering — recheck bytes changed without a version advance', async () => { + let call = 0; + await expectUnchangedFailure( + { + fetchManifest: async () => { + call += 1; + return call === 1 + ? { version: T, manifestSha256: MANIFEST_DIGEST } + : { version: T, manifestSha256: '9'.repeat(64) }; + }, + }, + 'channel-recheck', + ); + }); + + test('reobservation unavailable', async () => { + await expectUnchangedFailure({ reobserve: () => null }, 'reobserve'); + }); + + test('installed bytes changed between proof and publication', async () => { + await expectUnchangedFailure( + { reobserve: () => ({ installedGeneration: N, canonicalVersion: T, canonicalPayloadSha256: '9'.repeat(64) }) }, + 'reobserve', + ); + }); + + test('lease-fenced publish leaves everything unchanged and reports publish failure', async () => { + const fencedStore: CodexActivationStore = { + ...spyStore().store, + publishDelivery() { + throw new Error('codex lifecycle transition fenced: operation does not match held'); + }, + }; + const { seams } = makeSeams({ store: fencedStore }); + const outcome = await repairMissingDelivery(PINNED, seams); + expect(outcome.kind).toBe('failed'); + if (outcome.kind === 'failed') { + expect(outcome.stage).toBe('publish'); + expect(outcome.deliveryComplete).toBe(false); + } + }); +}); + +describe('a non-matching (mismatch) record is repaired, not accepted', () => { + test('a record binding a different platform is treated as non-matching and repaired', async () => { + const stalePlatformRecord: DeliveryRecordReadState = { + status: 'present', + record: { + targetVersion: T, + canonicalPayloadSha256: PAYLOAD_DIGEST, + channel: CHANNEL, + deliveryId: 'a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6', + platformTriple: 'linux-x64', // differs from the pinned darwin-arm64 + }, + }; + const { seams, log } = makeSeams({ readDeliveryRecord: () => stalePlatformRecord, installedGeneration: T }); + const outcome = await repairMissingDelivery(PINNED, seams); + expect(outcome.kind).toBe('published'); + // A mismatch is NOT a fast-path hit: the download ran. + expect(log.some((entry) => entry.startsWith('downloadAndVerify'))).toBe(true); + }); +}); diff --git a/src/genie-commands/codex-delivery-repair.ts b/src/genie-commands/codex-delivery-repair.ts new file mode 100644 index 000000000..cf98b8939 --- /dev/null +++ b/src/genie-commands/codex-delivery-repair.ts @@ -0,0 +1,326 @@ +/** + * Group D — immutable same-version delivery repair. + * + * A machine can hold the delivered generation T with NO readable authenticated + * delivery record: `install.sh`/an interrupted convergence left the binary at T + * but never published the record, so setup exits `delivery-incomplete` and an + * already-current `genie update` used to return before repairing it. This module + * lets update/install publish that MISSING record EXACTLY ONCE for the installed + * target, without performing activation and without redefining the target from a + * moving channel. + * + * The hazard this closes (Decision 10): installed bytes cannot attest to + * themselves. So the repair does NOT relabel local bytes — it re-fetches the + * exact signed artifact and proves it reproduces the installed bytes: + * + * 1. Pin channel + immutable target version/platform + release tag/name + + * fetched release-manifest bytes/digest BEFORE any asset download. The + * manifest is NOT a source of the artifact digest. + * 2. Download the exact named asset, compute its SHA-256 AFTER download, and + * authenticate that digest through the existing GitHub attestation/cosign + * trust anchors (the injected `downloadAndVerify` rejects on any failure). + * 3. Extract privately and prove the candidate VERSION / binary / plugin tree + * against the canonical installed bytes. + * 4. Recheck the pinned channel under the already-held lifecycle lease. A + * channel advance routes to ordinary upgrade and mints NO record for stale + * bytes; otherwise reobserve and publish once through the existing deep + * delivery store, persisting the computed authenticated digest. + * + * A no-network fast path returns `already-matching` when a record already binds + * the locally-known pinned tuple, so a repeated repair neither downloads nor + * republishes. EVERY verification/lease/reobservation failure returns before the + * single publish, so all delivery/journal/plugin/cache/config/role state is left + * unchanged with `deliveryComplete: false`. Publishing writes only the delivery + * record: it preserves the old registered generation and performs no + * activation-owned prompt, journal, enabled-state, plugin, or role mutation. + */ + +// Group B's contract, consumed (not reimplemented) via the stable executor facade +// for the assessment and directly from the leaf module for its record/expectation types. +import { assessAuthenticatedDelivery } from '../lib/codex-activation-executor.js'; +import type { CodexActivationStore, DeliveryAttestationBinding, DeliveryRecord } from '../lib/codex-activation.js'; +import type { ActivationDeliveryExpectation, DeliveryRecordReadState } from '../lib/codex-host-observation.js'; +import type { HeldLifecycleLease } from '../lib/codex-lifecycle-lease.js'; +import { classifyCodexDelivery } from './codex-delivery.js'; + +/** The immutable target pinned before any download; every field is locally known at pin time. */ +export interface RepairPinnedTarget { + channel: string; + /** The installed/canonical VERSION being repaired (never a moving-channel value). */ + targetVersion: string; + /** `process.platform-process.arch` (e.g. `linux-x64`, `darwin-arm64`). */ + platformTriple: string; + /** Release tag, e.g. `v5.260722.11`. */ + releaseTag: string; + /** Exact named asset, e.g. `genie-5.260722.11-darwin-arm64.tar.gz`. */ + releaseName: string; +} + +/** The fetched release manifest, reduced to the fields the repair pins/rechecks. */ +export interface PinnedManifest { + /** The channel's resolved target version at fetch time. */ + version: string; + /** SHA-256 of the fetched manifest bytes (NOT an artifact digest source). */ + manifestSha256: string; +} + +/** What a freshly extracted candidate tarball proves about itself. */ +export interface CandidateProof { + version: string; + pluginTreeSha256: string; + binarySha256: string; +} + +/** The canonical installed bytes the candidate is proven against — all locally computed. */ +export interface InstalledProof { + version: string; + /** The canonical installed plugin-payload digest (equals a matching record's `canonicalPayloadSha256`). */ + pluginTreeSha256: string; + binarySha256: string; + deliveryRoot: string; +} + +/** Re-observed reality immediately before the single publish. */ +export interface ReobservedTarget { + /** Installed plugin generation N from a live query (null = absent registration). */ + installedGeneration: string | null; + canonicalVersion: string; + canonicalPayloadSha256: string; +} + +/** Injected I/O seams so the orchestrator is pure of network/codex/home coupling in tests. */ +export interface DeliveryRepairSeams { + /** Current on-disk delivery record read-state (Group B assessment input). Local, no network. */ + readDeliveryRecord(): DeliveryRecordReadState; + /** The canonical installed bytes — all locally computed; used for the fast path AND candidate proof. */ + observeInstalled(): InstalledProof; + /** Fetch the pinned manifest for the channel (pre-download pin AND under-lease recheck). null = unavailable. */ + fetchManifest(channel: string): Promise; + /** Download + attestation-verify the exact named asset; resolves to the local path, rejects on any verify failure. */ + downloadAndVerify(target: RepairPinnedTarget): Promise; + /** SHA-256 of the downloaded artifact, computed AFTER download. */ + hashArtifact(tarballPath: string): string; + /** Extract privately and prove the candidate tree; rejects on unsafe extraction. */ + proveCandidate(tarballPath: string): Promise; + /** Re-observe the installed generation + canonical digest immediately before publish. null = unobservable. */ + reobserve(): ReobservedTarget | null; + /** The deep delivery store, opened by the caller under the held lease. */ + store: CodexActivationStore; + /** The held lifecycle lease (parent-owned; the repair never acquires its own). */ + lease: HeldLifecycleLease; + now?: () => Date; + deliveryId?: string; +} + +/** After a successful publish, whether setup will find the target current or still pending activation. */ +export type RepairHandoff = 'activation-pending' | 'current'; + +export type RepairFailureStage = + | 'manifest-pin' + | 'download-verify' + | 'artifact-digest' + | 'extract-prove' + | 'candidate-version' + | 'candidate-payload' + | 'candidate-binary' + | 'channel-recheck' + | 'reobserve' + | 'publish'; + +export type DeliveryRepairOutcome = + | { kind: 'already-matching' } + | { kind: 'published'; record: DeliveryRecord; handoff: RepairHandoff; artifactSha256: string } + | { kind: 'channel-advanced'; from: string; to: string } + | { kind: 'failed'; stage: RepairFailureStage; detail: string; deliveryComplete: false }; + +/** + * Build the LOCAL matching expectation — every field is known without a network + * round-trip, so the fast path can prove a record `matching` and skip the + * download entirely. The manifest and artifact digests are deliberately NOT bound + * here: they were authenticated at publish time and require the network to + * recompute, which would defeat the no-network fast path. + */ +export function buildLocalRepairExpectation( + pinned: RepairPinnedTarget, + installed: InstalledProof, +): ActivationDeliveryExpectation { + return { + targetVersion: pinned.targetVersion, + canonicalPayloadSha256: installed.pluginTreeSha256, + channel: pinned.channel, + platformTriple: pinned.platformTriple, + releaseTag: pinned.releaseTag, + releaseName: pinned.releaseName, + installedBinarySha256: installed.binarySha256, + deliveryRoot: installed.deliveryRoot, + }; +} + +/** + * Repair a missing/non-matching delivery record for the installed target exactly + * once. Returns `already-matching` (no network) when a record already binds the + * local tuple, `channel-advanced` when the pinned channel moved (route to ordinary + * upgrade), `published` on the one successful publication, or `failed` with every + * durable state left unchanged. + */ +export async function repairMissingDelivery( + pinned: RepairPinnedTarget, + seams: DeliveryRepairSeams, +): Promise { + const installed = seams.observeInstalled(); + // No-network fast path: an already-bound record needs no download or publish. + const expectation = buildLocalRepairExpectation(pinned, installed); + if (assessAuthenticatedDelivery(seams.readDeliveryRecord(), expectation) === 'matching') { + return { kind: 'already-matching' }; + } + + // Pin the manifest BEFORE any asset download; the manifest is not the artifact digest. + const pinnedManifest = await seams.fetchManifest(pinned.channel); + if (pinnedManifest === null) { + return fail('manifest-pin', 'release manifest unavailable; cannot pin the repair target'); + } + const preAdvance = channelAdvance(pinnedManifest.version, pinned.targetVersion); + if (preAdvance !== null) return preAdvance; + + const verified = await downloadAndProve(pinned, installed, seams); + if (verified.kind !== 'ok') return verified.outcome; + + // Recheck the pinned channel under the held lease immediately before publication. + const recheck = await seams.fetchManifest(pinned.channel); + if (recheck === null) return fail('channel-recheck', 'release manifest unavailable at the under-lease recheck'); + const advance = channelAdvance(recheck.version, pinned.targetVersion); + if (advance !== null) return advance; + // Same version but different manifest bytes is manifest tampering — fail closed. + if (recheck.manifestSha256 !== pinnedManifest.manifestSha256) { + return fail('channel-recheck', 'release manifest bytes changed under the lease without a version advance'); + } + + return publishRepair(pinned, installed, pinnedManifest, verified, seams); +} + +interface VerifiedCandidate { + kind: 'ok'; + artifactSha256: string; + candidate: CandidateProof; +} + +/** Download → hash-after → extract/prove → prove-against-installed. Any failure returns before publish. */ +async function downloadAndProve( + pinned: RepairPinnedTarget, + installed: InstalledProof, + seams: DeliveryRepairSeams, +): Promise { + let tarballPath: string; + try { + tarballPath = await seams.downloadAndVerify(pinned); + } catch (error) { + return { kind: 'fail', outcome: fail('download-verify', errorText(error)) }; + } + let artifactSha256: string; + try { + artifactSha256 = seams.hashArtifact(tarballPath); + } catch (error) { + return { kind: 'fail', outcome: fail('artifact-digest', errorText(error)) }; + } + let candidate: CandidateProof; + try { + candidate = await seams.proveCandidate(tarballPath); + } catch (error) { + return { kind: 'fail', outcome: fail('extract-prove', errorText(error)) }; + } + const mismatch = proveCandidateAgainstInstalled(candidate, installed, pinned); + if (mismatch !== null) return { kind: 'fail', outcome: mismatch }; + return { kind: 'ok', artifactSha256, candidate }; +} + +/** The candidate must reproduce the installed target exactly: version, payload tree, and binary. */ +function proveCandidateAgainstInstalled( + candidate: CandidateProof, + installed: InstalledProof, + pinned: RepairPinnedTarget, +): DeliveryRepairOutcome | null { + if (candidate.version !== pinned.targetVersion || candidate.version !== installed.version) { + return fail('candidate-version', `candidate version ${candidate.version} differs from installed target`); + } + if (candidate.pluginTreeSha256 !== installed.pluginTreeSha256) { + return fail('candidate-payload', 'candidate plugin tree differs from the canonical installed payload'); + } + if (candidate.binarySha256 !== installed.binarySha256) { + return fail('candidate-binary', 'candidate binary differs from the installed binary'); + } + return null; +} + +/** Reobserve, then publish the single authenticated record; N is preserved (no plugin/cache mutation). */ +function publishRepair( + pinned: RepairPinnedTarget, + installed: InstalledProof, + pinnedManifest: PinnedManifest, + verified: VerifiedCandidate, + seams: DeliveryRepairSeams, +): DeliveryRepairOutcome { + const reobserved = seams.reobserve(); + if (reobserved === null) return fail('reobserve', 'installed state unobservable before publication'); + if ( + reobserved.canonicalVersion !== pinned.targetVersion || + reobserved.canonicalPayloadSha256 !== installed.pluginTreeSha256 + ) { + return fail('reobserve', 'installed bytes changed between candidate proof and publication'); + } + const attestation: DeliveryAttestationBinding = { + platformTriple: pinned.platformTriple, + releaseTag: pinned.releaseTag, + releaseName: pinned.releaseName, + releaseManifestSha256: pinnedManifest.manifestSha256, + artifactSha256: verified.artifactSha256, + installedBinarySha256: installed.binarySha256, + deliveryRoot: installed.deliveryRoot, + }; + let record: DeliveryRecord; + try { + record = seams.store.publishDelivery(seams.lease, { + targetVersion: pinned.targetVersion, + canonicalPayloadSha256: reobserved.canonicalPayloadSha256, + channel: pinned.channel, + deliveryId: seams.deliveryId, + now: seams.now, + attestation, + }); + } catch (error) { + return fail('publish', errorText(error)); + } + return { + kind: 'published', + record, + handoff: handoffFor(reobserved.installedGeneration, pinned.targetVersion), + artifactSha256: verified.artifactSha256, + }; +} + +/** + * A channel advance is a target-version change (someone published a newer + * generation). It routes to ordinary upgrade and mints NO same-version record for + * stale installed bytes. A manifest whose version equals the pinned target is not + * an advance. + */ +function channelAdvance(manifestVersion: string, targetVersion: string): DeliveryRepairOutcome | null { + if (manifestVersion === targetVersion) return null; + const order = classifyCodexDelivery(targetVersion, manifestVersion); + // Any non-equal parseable pair (upgrade or downgrade) is an advance; an + // unparseable manifest version is fail-closed as an advance so no stale record mints. + if (order.kind === 'current') return null; + return { kind: 'channel-advanced', from: targetVersion, to: manifestVersion }; +} + +/** After publish, setup finds `current` only when the registered generation already equals the target. */ +function handoffFor(installedGeneration: string | null, targetVersion: string): RepairHandoff { + return installedGeneration === targetVersion ? 'current' : 'activation-pending'; +} + +function fail(stage: RepairFailureStage, detail: string): DeliveryRepairOutcome { + return { kind: 'failed', stage, detail, deliveryComplete: false }; +} + +function errorText(error: unknown): string { + return error instanceof Error ? error.message : String(error); +} diff --git a/src/genie-commands/install.ts b/src/genie-commands/install.ts index f7ecec2f4..5bc1546c2 100644 --- a/src/genie-commands/install.ts +++ b/src/genie-commands/install.ts @@ -16,11 +16,14 @@ import { readFileSync, writeFileSync } from 'node:fs'; import { homedir } from 'node:os'; import { join } from 'node:path'; import { type LifecycleLease, acquireLifecycleLease } from '../lib/agent-sync.js'; +import { observeCodexActivation, openCodexActivationStore } from '../lib/codex-activation-executor.js'; import { type HeldLifecycleLease, type LifecycleLeaseResult, acquireLifecycleLease as acquireCodexLifecycleLease, } from '../lib/codex-lifecycle-lease.js'; +import { genieConfigExists, getGenieConfigPath } from '../lib/genie-config.js'; +import { retireInstallVersionMarker } from '../lib/install-version-marker.js'; import { type InstallIntegrationsOptions, type IntegrationResult, @@ -41,6 +44,7 @@ import { CODEX_RETIRE_RECOVERY, CodexLifecycleBusyError, classifyCodexDelivery, + publishCodexDelivery, } from './codex-delivery.js'; import { cleanupV4 } from './legacy-v4.js'; import { runAgentSyncSafe } from './update.js'; @@ -149,6 +153,85 @@ function buildInstallCodexDeferral(installedVersion: string): IntegrationResult }; } +/** Best-effort channel token for the deferred-install delivery record (informational; inner guard binds core only). */ +function resolveDeliveryChannelForInstall(): string { + try { + if (!genieConfigExists()) return 'stable'; + const raw = JSON.parse(readFileSync(getGenieConfigPath(), 'utf8')) as { updateChannel?: string }; + if (raw.updateChannel === 'dev' || raw.updateChannel === 'next') return 'dev'; + if (raw.updateChannel === 'homolog') return 'homolog'; + return 'stable'; + } catch { + return 'stable'; + } +} + +/** + * Deliverable 7: a deferred install (installed generation N ≠ delivered T) + * publishes its matching delivery record BEFORE the exit-2 handoff, so setup can + * later activate against a real record instead of exiting `delivery-incomplete`. + * Install re-fetches nothing — install.sh already downloaded and attestation- + * verified this exact tarball — so this only records the delivered fact through + * the shared publish gate under the held `install-converge` lease, using observed + * reality (N from the live query, T + digest from the canonical scan). A matching + * record is neither re-downloaded nor republished (idempotent); a payload-less or + * codex-absent environment publishes nothing. + */ +/** + * Group D install lifecycle finishers, both gated on convergence success + * (`!codexFailed` — a failed convergence threw earlier and never reaches here, + * preserving prior state): publish a deferred install's matching delivery record + * (deliverable 7) and retire the orphaned legacy `.install-version` marker + * (Decision 14). Both are best-effort so neither can fail a completed install. + */ +function finalizeInstallDeliveryLifecycle( + codexDeferral: CodexInstallDeferral | null, + lease: HeldLifecycleLease | null, + codexFailed: boolean, +): void { + if (codexFailed) return; + if (codexDeferral !== null && lease !== null) { + try { + publishDeferredInstallDeliveryFacts(codexDeferral.installedVersion, lease); + } catch { + // Recording the delivered fact is best-effort; never fail a completed install over it. + } + } + try { + retireInstallVersionMarker(GENIE_HOME); + } catch { + // orphan-metadata cleanup must never fail a completed install. + } +} + +function publishDeferredInstallDeliveryFacts(installedVersion: string, lease: HeldLifecycleLease): void { + let command: string | null = null; + try { + command = resolveRuntimeExecutable('codex', process.cwd()); + } catch { + command = null; + } + const snapshot = observeCodexActivation({ genieHome: GENIE_HOME, command }); + if (snapshot.canonical.status !== 'ok') return; + const targetVersion = snapshot.canonical.version.canonical; + const canonicalPayloadSha256 = snapshot.canonical.digest; + if ( + snapshot.delivery.status === 'present' && + snapshot.delivery.record.targetVersion === targetVersion && + snapshot.delivery.record.canonicalPayloadSha256 === canonicalPayloadSha256 + ) { + return; // matching record already published — never republish. + } + publishCodexDelivery({ + lease, + store: openCodexActivationStore({ genieHome: GENIE_HOME }), + installedVersion, + targetVersion, + canonicalPayloadSha256, + channel: resolveDeliveryChannelForInstall(), + }); +} + /** * Converge the extracted `/bin/{plugins,skills,templates}` trees into * the canonical `/{plugins,skills,templates}` layout that `genie update` @@ -323,6 +406,13 @@ export function installCommand( if (results.some((result) => result.runtime === 'codex' && result.ok && result.hookReviewRequired)) { console.log(' \x1b[33m!\x1b[0m Review Genie hooks with /hooks, then start a new Codex task.'); } + // Deliverable 7: a deferred install publishes its matching delivery record + // (through the shared publish gate, under the held lease) BEFORE the exit-2 + // handoff, so setup activates against a real record. Best-effort and + // idempotent — a payload-less env or a matching record publishes nothing — + // then retire the orphaned legacy `.install-version` marker on convergence + // success (Decision 14, Group D). Both are Group-D lifecycle finishers. + finalizeInstallDeliveryLifecycle(codexDeferral, codexLease, codexFailed); // Delivered-but-action-required (Codex generation deferred): exit 2 with the // one A-owned result trailer and no all-green footer. install.sh maps this to // an installer exit 2 (deliverable 3). diff --git a/src/genie-commands/update.ts b/src/genie-commands/update.ts index 3bbd0b397..21df6ea8a 100644 --- a/src/genie-commands/update.ts +++ b/src/genie-commands/update.ts @@ -30,6 +30,10 @@ import { runAgentSync, } from '../lib/agent-sync.js'; import { observeCodexActivation, openCodexActivationStore } from '../lib/codex-activation-executor.js'; +import { assessAuthenticatedDelivery } from '../lib/codex-activation-executor.js'; +import { parseReleaseVersion, scanPhysicalTree } from '../lib/codex-activation.js'; +import type { DeliveryFact } from '../lib/codex-activation.js'; +import type { DeliveryRecordReadState } from '../lib/codex-host-observation.js'; import { type HeldLifecycleLease, acquireLifecycleLease as acquireCodexLifecycleLease, @@ -46,6 +50,7 @@ import { verifyInstallStagingDirectory, } from '../lib/install-promotion.js'; import { inspectPhysicalPath } from '../lib/install-transaction.js'; +import { retireInstallVersionMarker } from '../lib/install-version-marker.js'; import { type CodexAgentInstallResult, type IntegrationResult, @@ -69,6 +74,15 @@ import { convergeAuxiliaryTree, fingerprintAuxiliaryTree, } from './auxiliary-trees.js'; +import { + type CandidateProof, + type DeliveryRepairOutcome, + type DeliveryRepairSeams, + type InstalledProof, + type RepairPinnedTarget, + buildLocalRepairExpectation, + repairMissingDelivery, +} from './codex-delivery-repair.js'; import { CODEX_DELIVERY_RESULT_TRAILER, CODEX_LIFECYCLE_BUSY_TRAILER, @@ -1822,6 +1836,256 @@ function recoverInstallPromotionAndConvergePayload(): void { writeFileSync(join(GENIE_HOME, 'VERSION'), exactVersion); } +// ============================================================================ +// Same-version delivery repair on the already-current path (Group D deliverable 1) +// ============================================================================ + +export type AlreadyCurrentRepairDirective = + | { action: 'proceed-current' } + | { action: 'repaired-current' } + | { action: 'exit-handoff' }; + +/** + * Pure mapping of a repair outcome to the already-current directive. A published + * record whose registered generation still trails the target hands off to setup + * (exit 2 with the delivery trailer); a target-current publish reports the repair + * and continues the normal already-current success; already-matching / + * channel-advanced / failed all proceed unchanged — the repair is best-effort and + * leaves durable state untouched, so the next update retries or picks up an advance. + */ +export function mapAlreadyCurrentRepairOutcome(outcome: DeliveryRepairOutcome): AlreadyCurrentRepairDirective { + if (outcome.kind === 'published') { + return outcome.handoff === 'activation-pending' ? { action: 'exit-handoff' } : { action: 'repaired-current' }; + } + return { action: 'proceed-current' }; +} + +/** The pinned, immutable repair target — every field is locally known at pin time. */ +function buildRepairPinnedTarget(channel: string, platformId: string): RepairPinnedTarget { + const version = normalizeVersion(VERSION); + return { + channel, + targetVersion: version, + platformTriple: `${process.platform}-${process.arch}`, + releaseTag: `v${version}`, + releaseName: `genie-${version}-${platformId}.tar.gz`, + }; +} + +/** The canonical installed payload root under GENIE_HOME, or null when no payload is present. */ +function resolveCanonicalPayloadRoot(): string | null { + for (const candidate of [GENIE_HOME, join(GENIE_HOME, 'bin')]) { + if (existsSync(join(candidate, 'plugins', 'genie'))) return candidate; + } + return null; +} + +function hashFileSha256(path: string): string | null { + try { + return createHash('sha256').update(readFileSync(path)).digest('hex'); + } catch { + return null; + } +} + +/** Local canonical observation; null when the installed payload/binary cannot be safely observed. */ +function observeInstalledForRepair(): InstalledProof | null { + const snapshot = observeCodexActivation({ genieHome: GENIE_HOME, command: null }); + if (snapshot.canonical.status !== 'ok') return null; + const root = resolveCanonicalPayloadRoot(); + if (root === null) return null; + const binarySha256 = hashFileSha256(join(GENIE_BIN, 'genie')); + if (binarySha256 === null) return null; + return { + version: snapshot.canonical.version.canonical, + pluginTreeSha256: snapshot.canonical.digest, + binarySha256, + deliveryRoot: root, + }; +} + +/** Map the activation snapshot's delivery fact onto Group B's read-state shape. */ +function deliveryFactToReadState(fact: DeliveryFact): DeliveryRecordReadState { + if (fact.status === 'present') return { status: 'present', record: fact.record }; + if (fact.status === 'invalid') return { status: 'invalid', detail: fact.detail }; + return { status: 'absent' }; +} + +/** Re-scan a freshly extracted tarball into a candidate proof; throws on any unsafe/unreadable member. */ +async function proveCandidateFromTarball(tarballPath: string): Promise { + const extractRoot = createPrivateUpdateTempRoot(); + try { + await extractTarball(tarballPath, extractRoot); + chmodSync(extractRoot, 0o700); + const tree = scanPhysicalTree(join(extractRoot, 'plugins', 'genie')); + if (tree.status !== 'ok' || tree.digest === undefined) { + throw new Error(`candidate plugin tree is not a safe physical tree: ${tree.status}`); + } + const version = parseReleaseVersion(readTrimmedFile(join(extractRoot, 'VERSION'))); + if (version === null) throw new Error('candidate VERSION is missing or fails the release grammar'); + const binarySha256 = hashFileSha256(join(extractRoot, 'genie')); + if (binarySha256 === null) throw new Error('candidate binary is unreadable'); + return { version: version.canonical, pluginTreeSha256: tree.digest, binarySha256 }; + } finally { + rmSync(extractRoot, { recursive: true, force: true }); + } +} + +function readTrimmedFile(path: string): string | null { + try { + const value = readFileSync(path, 'utf8').trim(); + return value.length > 0 ? value : null; + } catch { + return null; + } +} + +function manifestPinDigest(manifest: LatestManifest): string { + const canonical = JSON.stringify({ + schema_version: manifest.schema_version, + channel: manifest.channel, + version: manifest.version, + released_at: manifest.released_at, + tarball_base: manifest.tarball_base, + platforms: manifest.platforms, + }); + return createHash('sha256').update(canonical).digest('hex'); +} + +/** + * Attempt the same-version delivery repair before an already-current return. + * Wholly best-effort and fail-closed: a matching record, an unobservable install, + * a busy codex lease, or any repair failure all return `proceed-current` with zero + * durable mutation, so the already-current path is never regressed. The download + * and private extraction happen under the held codex lease and are cleaned up on + * every path; only the single `publishDelivery` mutates durable state. + */ +export async function attemptAlreadyCurrentDeliveryRepair( + channel: string, + platformId: string, +): Promise { + const installed = observeInstalledForRepair(); + if (installed === null) return { action: 'proceed-current' }; + const pinned = buildRepairPinnedTarget(channel, platformId); + // No-network, no-lease fast path: an already-bound record needs no repair. + const record = deliveryFactToReadState(observeCodexActivation({ genieHome: GENIE_HOME, command: null }).delivery); + if (assessAuthenticatedDelivery(record, buildLocalRepairExpectation(pinned, installed)) === 'matching') { + return { action: 'proceed-current' }; + } + const lease = acquireCodexLifecycleLease('update-delivery', { genieHome: GENIE_HOME }); + if (!lease.ok) return { action: 'proceed-current' }; // another lifecycle command holds it — retry later. + const tempRoots: string[] = []; + try { + const seams = buildAlreadyCurrentRepairSeams(platformId, installed, lease, tempRoots); + const outcome = await repairMissingDelivery(pinned, seams); + return mapAlreadyCurrentRepairOutcome(outcome); + } catch { + return { action: 'proceed-current' }; + } finally { + lease.release(); + for (const root of tempRoots) rmSync(root, { recursive: true, force: true }); + } +} + +/** Build the real repair seams; download roots are tracked in `tempRoots` for cleanup by the caller. */ +function buildAlreadyCurrentRepairSeams( + platformId: string, + installed: InstalledProof, + lease: HeldLifecycleLease, + tempRoots: string[], +): DeliveryRepairSeams { + return { + readDeliveryRecord: () => + deliveryFactToReadState(observeCodexActivation({ genieHome: GENIE_HOME, command: null }).delivery), + observeInstalled: () => installed, + fetchManifest: async (channel) => { + const manifest = await fetchLatestManifest(channel as ReleaseChannel); + if (manifest === null) return null; + return { version: normalizeVersion(manifest.version), manifestSha256: manifestPinDigest(manifest) }; + }, + downloadAndVerify: async (target) => { + const manifest = await fetchLatestManifest(target.channel as ReleaseChannel); + if (manifest === null) throw new Error('release manifest unavailable for asset download'); + const destDir = createPrivateUpdateTempRoot(); + tempRoots.push(destDir); + return downloadAndVerifyTarball(manifest, platformId, destDir); + }, + hashArtifact: (path) => { + const digest = hashFileSha256(path); + if (digest === null) throw new Error('downloaded artifact is unreadable'); + return digest; + }, + proveCandidate: (path) => proveCandidateFromTarball(path), + reobserve: () => reobserveForRepair(), + store: openCodexActivationStore({ genieHome: GENIE_HOME }), + lease, + }; +} + +/** Re-observe the installed generation + canonical digest immediately before publication. */ +function reobserveForRepair(): { + installedGeneration: string | null; + canonicalVersion: string; + canonicalPayloadSha256: string; +} | null { + let command: string | null = null; + try { + command = resolveRuntimeExecutable('codex', process.cwd()); + } catch { + command = null; + } + const snapshot = observeCodexActivation({ genieHome: GENIE_HOME, command }); + if (snapshot.canonical.status !== 'ok') return null; + const registration = snapshot.query.status === 'ok' ? snapshot.query.registration : { present: false as const }; + const installedGeneration = registration.present && registration.version ? registration.version.canonical : null; + return { + installedGeneration, + canonicalVersion: snapshot.canonical.version.canonical, + canonicalPayloadSha256: snapshot.canonical.digest, + }; +} + +/** Best-effort retirement of the legacy `.install-version` marker after a proven-successful convergence. */ +function retireLegacyInstallMarkerSafe(): void { + try { + retireInstallVersionMarker(GENIE_HOME); + } catch { + // Orphan-metadata cleanup must never fail a completed update. + } +} + +/** + * The already-current terminal path. Group D deliverable 1: before returning + * "Already up to date", repair a MISSING authenticated delivery record for the + * installed target exactly once (fail-closed, best-effort — a matching record or + * any failure proceeds unchanged with zero durable mutation). An old-parent + * repair hands off to setup (exit 2); every other case converges and retires the + * legacy marker as usual. + */ +async function handleAlreadyCurrentUpdate( + channel: string, + platform: string, + installedVersion: string, + latestVersion: string | null | undefined, +): Promise { + const repair = await attemptAlreadyCurrentDeliveryRepair(channel, platform); + if (repair.action === 'exit-handoff') { + // Old-parent repair published one bound record but the registered generation + // still trails the target: hand off to setup (exit 2) with the one delivery + // trailer and exact next action, keeping N registered. + process.exitCode = 2; + log(CODEX_DELIVERY_RESULT_TRAILER); + return; + } + success(`Already up to date (v${normalizeVersion(installedVersion)}, channel ${channel})`); + if (repair.action === 'repaired-current') { + log('Repaired the missing Codex delivery record for the installed generation.'); + } + runTrackedManualUpdateConvergence(latestVersion ?? normalizeVersion(installedVersion)); + retireLegacyInstallMarkerSafe(); + console.log(); +} + export async function updateCommand(options: UpdateCommandOptions = {}): Promise { // The read-only capability probe is answered before mode resolution and any // mutation: it self-hashes this binary, prints exactly one JSON object, and @@ -1894,9 +2158,7 @@ export async function updateCommand(options: UpdateCommandOptions = {}): Promise await persistChannel(channel); if (shortCircuitIfCurrent(installedVersion, latestVersion)) { - success(`Already up to date (v${normalizeVersion(installedVersion)}, channel ${channel})`); - runTrackedManualUpdateConvergence(latestVersion ?? normalizeVersion(installedVersion)); - console.log(); + await handleAlreadyCurrentUpdate(channel, platform, installedVersion, latestVersion); return; } @@ -1942,6 +2204,10 @@ export async function updateCommand(options: UpdateCommandOptions = {}): Promise runV4CleanupSafe(); if (!runFreshConvergenceOrReport(lifecycleLease)) return; await runPostUpdateVerifySafe({ ...options, noRestart, noVerify }, diagnosticsCtx); + // Convergence succeeded: retire the orphaned legacy `.install-version` marker + // (Decision 14). Canonical VERSION is the sole authority; this only runs after + // a proven-successful delivery + convergence, so a failed run preserves it. + retireLegacyInstallMarkerSafe(); } finally { lifecycleLease.release(); } diff --git a/src/lib/codex-activation.ts b/src/lib/codex-activation.ts index b8946f638..15c3599c7 100644 --- a/src/lib/codex-activation.ts +++ b/src/lib/codex-activation.ts @@ -133,6 +133,27 @@ export interface DeliveryRecord { canonicalPayloadSha256: string; channel: string; deliveredAt: string; + // Group D immutable attestation bindings (deliverables 1+2). All optional and + // additive: an ordinary pending publish omits them (legacy 6-field record); a + // same-version repair pins and persists the full authenticated tuple. Present + // fields are structurally validated on read so a persisted authenticated record + // round-trips as `present`, not `invalid`. Group B's `AuthenticatedDeliveryRecord` + // view already declares these, so the assessment can bind them when an + // expectation supplies them. + /** os-arch platform triple (`process.platform-process.arch`), matches PLATFORM_TRIPLE_RE. */ + platformTriple?: string; + /** Release tag, e.g. `v5.260722.11`. */ + releaseTag?: string; + /** Release/asset name pinned before download. */ + releaseName?: string; + /** SHA-256 of the fetched release-manifest bytes (NOT an artifact digest source). */ + releaseManifestSha256?: string; + /** SHA-256 computed over the downloaded asset AFTER download and authenticated via attestation/cosign. */ + artifactSha256?: string; + /** SHA-256 of the installed binary the candidate was proven against. */ + installedBinarySha256?: string; + /** Absolute canonical delivery root the payload was proven against. */ + deliveryRoot?: string; } export interface ReceiptTombstone { @@ -229,8 +250,22 @@ const DELIVERY_KEYS: ReadonlySet = new Set([ 'canonicalPayloadSha256', 'channel', 'deliveredAt', + // Group D optional attestation bindings. + 'platformTriple', + 'releaseTag', + 'releaseName', + 'releaseManifestSha256', + 'artifactSha256', + 'installedBinarySha256', + 'deliveryRoot', ]); +const PLATFORM_TRIPLE_RE = /^[a-z0-9]+-[a-z0-9_]+$/; +/** A bounded free-text attestation field (tag/name/root): non-empty and length-capped. */ +function isBoundedText(value: unknown): value is string { + return typeof value === 'string' && value.length > 0 && value.length <= 256; +} + export function parseDeliveryRecordStructure(content: string): DeliveryRecord | null { const parsed = safeJson(content); if (!isPlainObject(parsed)) return null; @@ -242,6 +277,7 @@ export function parseDeliveryRecordStructure(content: string): DeliveryRecord | if (!isHex256(record.canonicalPayloadSha256)) return null; if (typeof record.channel !== 'string' || record.channel.length === 0 || record.channel.length > 128) return null; if (typeof record.deliveredAt !== 'string' || record.deliveredAt.length === 0) return null; + if (!attestationFieldsValid(record)) return null; return { schemaVersion: 1, deliveryId: record.deliveryId as string, @@ -249,6 +285,62 @@ export function parseDeliveryRecordStructure(content: string): DeliveryRecord | canonicalPayloadSha256: record.canonicalPayloadSha256 as string, channel: record.channel as string, deliveredAt: record.deliveredAt as string, + ...pickAttestationFields(record), + }; +} + +/** Every PRESENT attestation field must satisfy its shape; absent fields are legal (legacy record). */ +function attestationFieldsValid(record: Record): boolean { + if ( + record.platformTriple !== undefined && + !(typeof record.platformTriple === 'string' && PLATFORM_TRIPLE_RE.test(record.platformTriple)) + ) { + return false; + } + if (record.releaseTag !== undefined && !isBoundedText(record.releaseTag)) return false; + if (record.releaseName !== undefined && !isBoundedText(record.releaseName)) return false; + if (record.deliveryRoot !== undefined && !isBoundedText(record.deliveryRoot)) return false; + for (const key of ['releaseManifestSha256', 'artifactSha256', 'installedBinarySha256'] as const) { + if (record[key] !== undefined && !isHex256(record[key])) return false; + } + return true; +} + +/** Copy only the present, already-validated attestation fields onto the parsed record. */ +function pickAttestationFields(record: Record): Partial { + const out: Partial = {}; + if (record.platformTriple !== undefined) out.platformTriple = record.platformTriple as string; + if (record.releaseTag !== undefined) out.releaseTag = record.releaseTag as string; + if (record.releaseName !== undefined) out.releaseName = record.releaseName as string; + if (record.releaseManifestSha256 !== undefined) out.releaseManifestSha256 = record.releaseManifestSha256 as string; + if (record.artifactSha256 !== undefined) out.artifactSha256 = record.artifactSha256 as string; + if (record.installedBinarySha256 !== undefined) out.installedBinarySha256 = record.installedBinarySha256 as string; + if (record.deliveryRoot !== undefined) out.deliveryRoot = record.deliveryRoot as string; + return out; +} + +/** + * Validate a publish-time attestation binding and return the fields, or throw so + * a malformed binding is rejected before it is written. Returns an empty object + * when no binding is supplied (ordinary pending publish keeps the legacy shape). + */ +function bindAttestation(binding: DeliveryAttestationBinding | undefined): Partial { + if (binding === undefined) return {}; + if (!PLATFORM_TRIPLE_RE.test(binding.platformTriple)) throw new Error('attestation platformTriple is malformed'); + if (!isBoundedText(binding.releaseTag)) throw new Error('attestation releaseTag is malformed'); + if (!isBoundedText(binding.releaseName)) throw new Error('attestation releaseName is malformed'); + if (!isBoundedText(binding.deliveryRoot)) throw new Error('attestation deliveryRoot is malformed'); + if (!isHex256(binding.releaseManifestSha256)) throw new Error('attestation releaseManifestSha256 is malformed'); + if (!isHex256(binding.artifactSha256)) throw new Error('attestation artifactSha256 is malformed'); + if (!isHex256(binding.installedBinarySha256)) throw new Error('attestation installedBinarySha256 is malformed'); + return { + platformTriple: binding.platformTriple, + releaseTag: binding.releaseTag, + releaseName: binding.releaseName, + releaseManifestSha256: binding.releaseManifestSha256, + artifactSha256: binding.artifactSha256, + installedBinarySha256: binding.installedBinarySha256, + deliveryRoot: binding.deliveryRoot, }; } @@ -1484,6 +1576,24 @@ export interface PublishDeliveryInput { downgradeFrom?: string; deliveryId?: string; now?: () => Date; + /** + * Group D's immutable attestation bindings (deliverables 1+2). Ordinary pending + * publishes omit them; a same-version repair pins and persists the full tuple. + * Each present value is structurally validated before it is written so a + * malformed binding is rejected at publish time rather than corrupting a record. + */ + attestation?: DeliveryAttestationBinding; +} + +/** The immutable attestation tuple a same-version repair persists into the delivery record. */ +export interface DeliveryAttestationBinding { + platformTriple: string; + releaseTag: string; + releaseName: string; + releaseManifestSha256: string; + artifactSha256: string; + installedBinarySha256: string; + deliveryRoot: string; } export interface DeliveryRootOps { @@ -1575,6 +1685,7 @@ function publishDeliveryImpl(deliveryPath: string, receiptPath: string, input: P canonicalPayloadSha256: input.canonicalPayloadSha256, channel: input.channel, deliveredAt: now().toISOString(), + ...bindAttestation(input.attestation), }; if (input.downgradeFrom !== undefined) { const from = parseReleaseVersion(input.downgradeFrom); diff --git a/src/lib/install-version-marker.test.ts b/src/lib/install-version-marker.test.ts new file mode 100644 index 000000000..10dd437ab --- /dev/null +++ b/src/lib/install-version-marker.test.ts @@ -0,0 +1,161 @@ +import { afterEach, beforeEach, describe, expect, test } from 'bun:test'; +import { existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { + INSTALL_VERSION_MARKER_NAME, + readInstallVersionMarker, + resolveInstallVersionMarkerPath, + retireInstallVersionMarker, + uninstallInstallVersionMarker, +} from './install-version-marker.js'; + +let genieHome: string; + +beforeEach(() => { + genieHome = mkdtempSync(join(tmpdir(), 'genie-install-marker-')); +}); + +afterEach(() => { + rmSync(genieHome, { recursive: true, force: true }); +}); + +function markerPath(): string { + return join(genieHome, INSTALL_VERSION_MARKER_NAME); +} + +function writeMarker(content: string): void { + writeFileSync(markerPath(), content); +} + +function backupSidecars(): string[] { + return readdirSync(genieHome).filter((name) => name.startsWith(`${INSTALL_VERSION_MARKER_NAME}.genie-backup-`)); +} + +describe('resolveInstallVersionMarkerPath', () => { + test('resolves the stable .install-version path under the given home', () => { + expect(resolveInstallVersionMarkerPath(genieHome)).toBe(join(genieHome, '.install-version')); + }); +}); + +describe('readInstallVersionMarker — never a version authority, only diagnostics', () => { + test('absent when no marker exists', () => { + expect(readInstallVersionMarker(genieHome)).toEqual({ status: 'absent' }); + }); + + test('present returns the trimmed legacy value', () => { + writeMarker(' 5.260500.3\n'); + expect(readInstallVersionMarker(genieHome)).toEqual({ status: 'present', value: '5.260500.3' }); + }); + + test('a symlink marker is unsafe (never followed)', () => { + writeFileSync(join(genieHome, 'real-version'), '9.9.9'); + symlinkSync(join(genieHome, 'real-version'), markerPath()); + const read = readInstallVersionMarker(genieHome); + expect(read.status).toBe('unsafe'); + }); + + test('an oversized marker is unsafe drift', () => { + writeMarker('x'.repeat(5 * 1024)); + const read = readInstallVersionMarker(genieHome); + expect(read.status).toBe('unsafe'); + }); +}); + +describe('retireInstallVersionMarker — retire only after success, preserve on unsafe, idempotent', () => { + test('already-absent is a no-op success', () => { + expect(retireInstallVersionMarker(genieHome)).toEqual({ status: 'already-absent' }); + }); + + test('a present regular marker is backed up then removed, reporting its prior value', () => { + writeMarker('5.260500.3\n'); + const result = retireInstallVersionMarker(genieHome); + expect(result).toEqual({ status: 'retired', previousValue: '5.260500.3' }); + // Marker gone. + expect(readInstallVersionMarker(genieHome)).toEqual({ status: 'absent' }); + // Prior bytes preserved in exactly one backup sidecar. + expect(backupSidecars()).toHaveLength(1); + }); + + test('retirement is idempotent — a second call after retirement is already-absent with no new backup', () => { + writeMarker('5.260500.3'); + retireInstallVersionMarker(genieHome); + const before = backupSidecars().length; + expect(retireInstallVersionMarker(genieHome)).toEqual({ status: 'already-absent' }); + expect(backupSidecars()).toHaveLength(before); + }); + + test('an unsafe (symlink) marker is preserved exactly in place, never followed or deleted', () => { + writeFileSync(join(genieHome, 'real-version'), '9.9.9'); + symlinkSync(join(genieHome, 'real-version'), markerPath()); + const result = retireInstallVersionMarker(genieHome); + expect(result.status).toBe('preserved'); + // The symlink survives untouched (still an unsafe read), and its target still holds its bytes. + expect(readInstallVersionMarker(genieHome).status).toBe('unsafe'); + expect(readInstallVersionMarker(genieHome).status).not.toBe('absent'); + }); + + test('an empty marker retires with a null previous value', () => { + writeMarker(' \n'); + expect(retireInstallVersionMarker(genieHome)).toEqual({ status: 'retired', previousValue: null }); + }); +}); + +describe('uninstallInstallVersionMarker — tolerates either layout, idempotent, dry-run safe', () => { + test('absent marker uninstalls cleanly (post-convergence layout)', () => { + expect(uninstallInstallVersionMarker(genieHome)).toEqual({ status: 'absent' }); + }); + + test('present regular marker is removed (legacy layout)', () => { + writeMarker('5.260500.3'); + expect(uninstallInstallVersionMarker(genieHome)).toEqual({ status: 'removed', path: markerPath() }); + expect(readInstallVersionMarker(genieHome)).toEqual({ status: 'absent' }); + }); + + test('dry-run reports would-remove and mutates nothing', () => { + writeMarker('5.260500.3'); + expect(uninstallInstallVersionMarker(genieHome, { dryRun: true })).toEqual({ + status: 'would-remove', + path: markerPath(), + }); + expect(readInstallVersionMarker(genieHome)).toEqual({ status: 'present', value: '5.260500.3' }); + }); + + test('a symlink marker is unlinked (never its target)', () => { + const target = join(genieHome, 'real-version'); + writeFileSync(target, '9.9.9'); + symlinkSync(target, markerPath()); + expect(uninstallInstallVersionMarker(genieHome)).toEqual({ status: 'removed', path: markerPath() }); + // Marker link gone; the target it pointed at is preserved on disk. + expect(readInstallVersionMarker(genieHome)).toEqual({ status: 'absent' }); + expect(existsSync(target)).toBe(true); + }); + + test('uninstall is idempotent — a second removal is a benign absent', () => { + writeMarker('5.260500.3'); + uninstallInstallVersionMarker(genieHome); + expect(uninstallInstallVersionMarker(genieHome)).toEqual({ status: 'absent' }); + }); + + test('a directory in the marker slot is reported, never recursively removed', () => { + mkdirSync(markerPath()); + const result = uninstallInstallVersionMarker(genieHome); + expect(result.status).toBe('error'); + }); +}); + +describe('retire → uninstall interplay proves both layouts are safe to rerun', () => { + test('successful convergence retires the marker so a later uninstall sees no marker', () => { + writeMarker('5.260500.3'); + expect(retireInstallVersionMarker(genieHome).status).toBe('retired'); + // Post-convergence machine: uninstall tolerates the already-retired layout. + expect(uninstallInstallVersionMarker(genieHome)).toEqual({ status: 'absent' }); + }); + + test('a machine that never retired still uninstalls the legacy marker', () => { + writeMarker('4.260428.19'); + // Interrupted/failed convergence never called retire — the legacy marker persists. + expect(readInstallVersionMarker(genieHome)).toEqual({ status: 'present', value: '4.260428.19' }); + expect(uninstallInstallVersionMarker(genieHome)).toEqual({ status: 'removed', path: markerPath() }); + }); +}); diff --git a/src/lib/install-version-marker.ts b/src/lib/install-version-marker.ts new file mode 100644 index 000000000..4018bd8e6 --- /dev/null +++ b/src/lib/install-version-marker.ts @@ -0,0 +1,170 @@ +/** + * `.install-version` legacy install-marker lifecycle — Group D exclusive ownership. + * + * The v4-era installer wrote a `~/.genie/.install-version` marker whose content + * duplicated the installed version. In v5 the canonical `VERSION` file is the + * SOLE installed-version authority (Decision 14): the legacy marker is orphaned + * drift that disagrees with `VERSION` on any machine upgraded across the v4→v5 + * boundary. Synchronising it would only mint a second authority, so this module + * RETIRES the marker rather than reconciling it. + * + * This is the ONE module that owns the marker's lifecycle. Only install, update, + * and uninstall wire to it; Group C (role-agent convergence) never imports or + * mutates this API, which keeps install-lifecycle writes off the role-convergence + * critical path. + * + * - `readInstallVersionMarker` — bounded, symlink-rejecting read of the legacy + * marker (`absent | present | unsafe`). Never trusted as version authority. + * - `retireInstallVersionMarker` — delete the legacy marker AFTER a successful + * install/update convergence. The caller gates the call on convergence + * success, so a failed convergence never reaches it and the prior bytes stay + * intact. The delete is backup-first (prior bytes are copied to a + * `.genie-backup-*` sidecar) and atomic, so an interrupted retirement leaves + * either the original file or nothing recoverable-from-backup — never a + * partial write. An unsafe (symlink/non-regular) marker is preserved and + * reported rather than followed. Idempotent: an already-absent marker is a + * no-op success. + * - `uninstallInstallVersionMarker` — remove the marker during uninstall, + * tolerating either layout (present regular file, present symlink, or already + * absent) and honouring a dry-run. The symlink itself is unlinked, never its + * target. + * + * Canonical `VERSION` is authoritative: this module never writes a version into + * the marker and never reads it back as the installed version. + */ + +import { randomBytes } from 'node:crypto'; +import { type Stats, copyFileSync, lstatSync, unlinkSync } from 'node:fs'; +import { join } from 'node:path'; +import { fsyncParentDir, readBoundedRegularFile, unlinkWithParentFsync } from './codex-activation-persistence.js'; +import { resolveGenieHome } from './genie-home.js'; + +/** The stable legacy marker filename, resolved under `GENIE_HOME`. */ +export const INSTALL_VERSION_MARKER_NAME = '.install-version'; + +/** A legacy marker cannot plausibly exceed a version string; anything larger is treated as unsafe drift. */ +const MAX_MARKER_BYTES = 4 * 1024; + +/** Stable path to the legacy marker under a given (or resolved) Genie home. */ +export function resolveInstallVersionMarkerPath(genieHome: string = resolveGenieHome()): string { + return join(genieHome, INSTALL_VERSION_MARKER_NAME); +} + +export type InstallVersionMarkerRead = + | { status: 'absent' } + | { status: 'present'; value: string } + | { status: 'unsafe'; detail: string }; + +/** + * Bounded, symlink-rejecting read of the legacy marker. The returned `value` is + * the trimmed marker content for diagnostics ONLY; callers must never treat it as + * the installed version (canonical `VERSION` is authoritative). A symlink, + * non-regular kind, oversize, or unreadable marker is `unsafe`, never `present`. + */ +export function readInstallVersionMarker(genieHome: string = resolveGenieHome()): InstallVersionMarkerRead { + const read = readBoundedRegularFile(resolveInstallVersionMarkerPath(genieHome), MAX_MARKER_BYTES); + switch (read.status) { + case 'absent': + return { status: 'absent' }; + case 'ok': + return { status: 'present', value: read.content.trim() }; + case 'symlink': + return { status: 'unsafe', detail: 'install-version marker is a symlink' }; + case 'non-regular': + return { status: 'unsafe', detail: 'install-version marker is not a regular file' }; + case 'oversized': + return { status: 'unsafe', detail: `install-version marker is oversized (${read.size} bytes)` }; + case 'unreadable': + return { status: 'unsafe', detail: `install-version marker unreadable: ${read.detail}` }; + } +} + +export type InstallVersionMarkerRetirement = + | { status: 'already-absent' } + | { status: 'retired'; previousValue: string | null } + | { status: 'preserved'; detail: string }; + +/** + * Retire (delete) the legacy marker after a successful install/update + * convergence. The caller MUST only invoke this once convergence has succeeded; + * a failed convergence returns before this point so the marker's prior bytes are + * preserved untouched. + * + * A present regular marker is backed up (prior bytes copied to a + * `.genie-backup-*` sidecar) and then atomically unlinked. An already-absent + * marker is a no-op success (idempotent). An unsafe marker (symlink or + * non-regular) is left exactly in place and reported — retirement never follows a + * symlink or blindly removes an unexpected kind. + */ +export function retireInstallVersionMarker(genieHome: string = resolveGenieHome()): InstallVersionMarkerRetirement { + const path = resolveInstallVersionMarkerPath(genieHome); + const read = readInstallVersionMarker(genieHome); + if (read.status === 'absent') return { status: 'already-absent' }; + if (read.status === 'unsafe') return { status: 'preserved', detail: read.detail }; + // Regular file: preserve prior bytes to a backup sidecar, then atomically remove. + backupRegularFile(path); + unlinkWithParentFsync(path); + return { status: 'retired', previousValue: read.value.length > 0 ? read.value : null }; +} + +export interface UninstallMarkerOptions { + /** When true, report what would be removed without mutating anything. */ + dryRun?: boolean; +} + +export type UninstallMarkerResult = + | { status: 'absent' } + | { status: 'would-remove'; path: string } + | { status: 'removed'; path: string } + | { status: 'error'; path: string; detail: string }; + +/** + * Remove the legacy marker during uninstall, tolerating either layout so a + * machine that already retired the marker (post-convergence) and one that still + * carries it both uninstall cleanly and idempotently. A symlink is unlinked + * (never followed); an already-absent marker is a benign `absent`. Uninstall does + * NOT back the marker up — the whole install is being removed. + */ +export function uninstallInstallVersionMarker( + genieHome: string = resolveGenieHome(), + options: UninstallMarkerOptions = {}, +): UninstallMarkerResult { + const path = resolveInstallVersionMarkerPath(genieHome); + let stat: Stats; + try { + stat = lstatSync(path); + } catch (error) { + if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { status: 'absent' }; + return { status: 'error', path, detail: errorText(error) }; + } + // A directory here is unexpected legacy corruption; unlinkSync would EISDIR. + // Report it rather than recursively removing an unknown tree. + if (stat.isDirectory()) { + return { status: 'error', path, detail: 'install-version marker is unexpectedly a directory' }; + } + if (options.dryRun) return { status: 'would-remove', path }; + try { + unlinkSync(path); + fsyncParentDir(path); + return { status: 'removed', path }; + } catch (error) { + if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { status: 'absent' }; + return { status: 'error', path, detail: errorText(error) }; + } +} + +/** Best-effort copy of prior marker bytes to a unique sidecar; a backup failure never blocks retirement. */ +function backupRegularFile(path: string): void { + const backup = `${path}.genie-backup-${new Date().toISOString().replace(/[:.]/g, '-')}-${randomBytes(6).toString('hex')}`; + try { + copyFileSync(path, backup); + fsyncParentDir(backup); + } catch { + // Prior bytes are already durable on disk until the unlink below; a failed + // forensic copy must not prevent retirement of a proven-current install. + } +} + +function errorText(error: unknown): string { + return error instanceof Error ? error.message : String(error); +} diff --git a/tests/integration/codex-delivery-bootstrap.test.ts b/tests/integration/codex-delivery-bootstrap.test.ts new file mode 100644 index 000000000..90e3e4a61 --- /dev/null +++ b/tests/integration/codex-delivery-bootstrap.test.ts @@ -0,0 +1,248 @@ +/** + * Group D integration proof: the same-version delivery repair publishes ONE + * authenticated record through the REAL deep delivery store, round-trips the full + * attestation tuple back through the store's own parser, and is idempotent on a + * rerun. Every network/attestation seam is STUBBED — this suite runs with no + * `codex` binary and no network, so it is CI-portable by construction. + */ + +import { afterEach, beforeEach, describe, expect, test } from 'bun:test'; +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { + type DeliveryRepairSeams, + type InstalledProof, + type ReobservedTarget, + repairMissingDelivery, +} from '../../src/genie-commands/codex-delivery-repair.js'; +import { + observeCodexActivation, + openCodexActivationStore, + parseReleaseVersion, + scanPhysicalTree, +} from '../../src/lib/codex-activation.js'; +import type { DeliveryRecordReadState } from '../../src/lib/codex-host-observation.js'; +import { acquireLifecycleLease } from '../../src/lib/codex-lifecycle-lease.js'; + +const T = '5.260722.11'; +const PLATFORM = 'linux-x64'; +const CHANNEL = 'dev'; +const MANIFEST_DIGEST = 'c'.repeat(64); +const ARTIFACT_DIGEST = 'd'.repeat(64); +const BINARY_DIGEST = 'b'.repeat(64); + +let genieHome: string; + +beforeEach(() => { + genieHome = mkdtempSync(join(tmpdir(), 'genie-delivery-bootstrap-')); + // Minimal canonical payload the store's observation can scan: VERSION + plugin tree. + writeFileSync(join(genieHome, 'VERSION'), `${T}\n`); + mkdirSync(join(genieHome, 'plugins', 'genie'), { recursive: true }); + writeFileSync(join(genieHome, 'plugins', 'genie', 'plugin.json'), '{"name":"genie"}\n'); +}); + +afterEach(() => { + rmSync(genieHome, { recursive: true, force: true }); +}); + +/** The canonical installed plugin-tree digest the store computes for this fixture. */ +function canonicalPayloadDigest(): string { + const tree = scanPhysicalTree(join(genieHome, 'plugins', 'genie')); + if (tree.status !== 'ok' || tree.digest === undefined) + throw new Error(`fixture payload not scannable: ${tree.status}`); + return tree.digest; +} + +function installedProof(): InstalledProof { + return { + version: T, + pluginTreeSha256: canonicalPayloadDigest(), + binarySha256: BINARY_DIGEST, + deliveryRoot: genieHome, + }; +} + +/** Read the on-disk delivery record via the store's own observation (real parser round-trip). */ +function readRecordReadState(): DeliveryRecordReadState { + const fact = observeCodexActivation({ genieHome, command: null }).delivery; + if (fact.status === 'present') return { status: 'present', record: fact.record }; + if (fact.status === 'invalid') return { status: 'invalid', detail: fact.detail }; + return { status: 'absent' }; +} + +interface SeamConfig { + installedGeneration: string | null; + fetchManifest?: () => Promise<{ version: string; manifestSha256: string } | null>; +} + +/** Real store + real lease; stubbed network/attestation. The lease MUST be released by the caller. */ +function makeRealStoreSeams(config: SeamConfig): { seams: DeliveryRepairSeams; release: () => void } { + const lease = acquireLifecycleLease('update-delivery', { genieHome }); + if (!lease.ok) throw new Error('could not acquire the update-delivery lease in the fixture'); + const reobserve = (): ReobservedTarget => ({ + installedGeneration: config.installedGeneration, + canonicalVersion: T, + canonicalPayloadSha256: canonicalPayloadDigest(), + }); + const seams: DeliveryRepairSeams = { + readDeliveryRecord: readRecordReadState, + observeInstalled: installedProof, + fetchManifest: config.fetchManifest ?? (async () => ({ version: T, manifestSha256: MANIFEST_DIGEST })), + downloadAndVerify: async () => '/stub/tarball.tar.gz', // no network + hashArtifact: () => ARTIFACT_DIGEST, + proveCandidate: async () => ({ + version: T, + pluginTreeSha256: canonicalPayloadDigest(), + binarySha256: BINARY_DIGEST, + }), + reobserve, + store: openCodexActivationStore({ genieHome }), + lease, + }; + return { seams, release: () => lease.release() }; +} + +describe('codex-delivery-bootstrap — repair round-trips one authenticated record through the real store', () => { + test('old-parent/no-record: publishes one bound record readable as present, handoff activation-pending', async () => { + const { seams, release } = makeRealStoreSeams({ installedGeneration: '5.260722.1' }); + try { + const outcome = await repairMissingDelivery( + { + channel: CHANNEL, + targetVersion: T, + platformTriple: PLATFORM, + releaseTag: `v${T}`, + releaseName: `genie-${T}-${PLATFORM}.tar.gz`, + }, + seams, + ); + expect(outcome.kind).toBe('published'); + if (outcome.kind === 'published') expect(outcome.handoff).toBe('activation-pending'); + } finally { + release(); + } + // The record is now on disk and parses through the store's OWN parser (extended schema round-trip). + const readState = readRecordReadState(); + expect(readState.status).toBe('present'); + if (readState.status === 'present') { + expect(readState.record.targetVersion).toBe(T); + expect(readState.record.artifactSha256).toBe(ARTIFACT_DIGEST); + expect(readState.record.releaseManifestSha256).toBe(MANIFEST_DIGEST); + expect(readState.record.platformTriple).toBe(PLATFORM); + expect(readState.record.releaseTag).toBe(`v${T}`); + expect(parseReleaseVersion(readState.record.targetVersion)).not.toBeNull(); + } + }); + + test('rerun after publication is already-matching with no second download', async () => { + const first = makeRealStoreSeams({ installedGeneration: T }); + try { + await repairMissingDelivery( + { + channel: CHANNEL, + targetVersion: T, + platformTriple: PLATFORM, + releaseTag: `v${T}`, + releaseName: `genie-${T}-${PLATFORM}.tar.gz`, + }, + first.seams, + ); + } finally { + first.release(); + } + // Second run: a download seam that fails proves the fast path never reaches it. + const second = makeRealStoreSeams({ installedGeneration: T }); + let downloadCalled = false; + second.seams.downloadAndVerify = async () => { + downloadCalled = true; + throw new Error('rerun must not download'); + }; + try { + const outcome = await repairMissingDelivery( + { + channel: CHANNEL, + targetVersion: T, + platformTriple: PLATFORM, + releaseTag: `v${T}`, + releaseName: `genie-${T}-${PLATFORM}.tar.gz`, + }, + second.seams, + ); + expect(outcome).toEqual({ kind: 'already-matching' }); + expect(downloadCalled).toBe(false); + } finally { + second.release(); + } + }); + + test('a channel advance under the lease publishes nothing and leaves the store record absent', async () => { + const { seams, release } = makeRealStoreSeams({ + installedGeneration: '5.260722.1', + fetchManifest: async () => ({ version: '5.260722.12', manifestSha256: MANIFEST_DIGEST }), + }); + try { + const outcome = await repairMissingDelivery( + { + channel: CHANNEL, + targetVersion: T, + platformTriple: PLATFORM, + releaseTag: `v${T}`, + releaseName: `genie-${T}-${PLATFORM}.tar.gz`, + }, + seams, + ); + expect(outcome.kind).toBe('channel-advanced'); + } finally { + release(); + } + // No stale record was minted. + expect(readRecordReadState().status).toBe('absent'); + }); + + test('a tampered persisted platform is treated as non-matching and republished', async () => { + // Publish a good record first. + const first = makeRealStoreSeams({ installedGeneration: T }); + try { + await repairMissingDelivery( + { + channel: CHANNEL, + targetVersion: T, + platformTriple: PLATFORM, + releaseTag: `v${T}`, + releaseName: `genie-${T}-${PLATFORM}.tar.gz`, + }, + first.seams, + ); + } finally { + first.release(); + } + // Repair for a DIFFERENT platform tuple: the persisted record no longer matches, so it republishes. + const second = makeRealStoreSeams({ installedGeneration: T }); + let downloaded = false; + const originalDownload = second.seams.downloadAndVerify; + second.seams.downloadAndVerify = async (target) => { + downloaded = true; + return originalDownload(target); + }; + try { + const outcome = await repairMissingDelivery( + { + channel: CHANNEL, + targetVersion: T, + platformTriple: 'darwin-arm64', + releaseTag: `v${T}`, + releaseName: `genie-${T}-darwin-arm64.tar.gz`, + }, + second.seams, + ); + expect(outcome.kind).toBe('published'); + expect(downloaded).toBe(true); // the non-match forced a real download, not the fast path + } finally { + second.release(); + } + const readState = readRecordReadState(); + expect(readState.status).toBe('present'); + if (readState.status === 'present') expect(readState.record.platformTriple).toBe('darwin-arm64'); + }); +});