pgserve 2.6.0 → 2.6.4

package/src/commands/gc.js

@@ -31,7 +31,7 @@
 
 import { readAdminJson } from '../lib/admin-json.js';
 import { classifyOrphans } from '../gc/orphan-detection.js';
-import { writeGcAudit } from '../gc/audit-log.js';
+import { writeGcAudit, rotateGcAuditLogs } from '../gc/audit-log.js';
 import {
   selectMetaRows,
   selectExistingDbs,
@@ -164,6 +164,21 @@ export async function runGc(argv = []) {
     detail: `mode=${opts.apply ? 'apply' : 'dry-run'} port=${port} staleAfterDays=${opts.staleAfterDays}`,
   });
 
+  // Rotate audit logs older than 90 days — runs on every gc invocation
+  // (dry-run or apply). Boundary guard preserves the current day's log.
+  // Errors are surfaced via the audit log itself; never aborts the gc run.
+  try {
+    const rotation = rotateGcAuditLogs();
+    if (rotation.deleted.length > 0 || rotation.errors.length > 0) {
+      writeGcAudit({
+        action: 'rotate-summary',
+        detail: `deleted=${rotation.deleted.length} kept=${rotation.kept.length} errors=${rotation.errors.length}`,
+      });
+    }
+  } catch (err) {
+    writeGcAudit({ action: 'error', reason: 'rotate_failed', detail: err.message });
+  }
+
   let metaRows;
   try {
     metaRows = selectMetaRows({ port });

package/src/commands/verify.js

@@ -45,6 +45,8 @@ import {
   writeCacheToken,
 } from '../cosign/cache-token.js';
 import { sha256File, verifyBinary } from '../cosign/verify-binary.js';
+import { loadLockedRoots as loadLockedRootsImpl } from '../cosign/locked-roots.js';
+import { readAdminJson } from '../lib/admin-json.js';
 
 const EXIT_OK = 0;
 const EXIT_VERIFY_FAILED = 2;
@@ -110,6 +112,8 @@ function parseArgs(args) {
     cosignBin: null,
     allowFetch: false,
     noCache: false,
+    slug: null,
+    port: null,
   };
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
@@ -119,6 +123,15 @@ function parseArgs(args) {
     else if (a === '--no-cache') opts.noCache = true;
     else if (a === '--bundle') opts.bundlePath = args[++i];
     else if (a === '--cosign-bin') opts.cosignBin = args[++i];
+    else if (a === '--slug') opts.slug = args[++i];
+    else if (a === '--port' || a === '-p') {
+      const v = Number(args[++i]);
+      if (!Number.isInteger(v) || v <= 0 || v > 65535) {
+        process.stderr.write('pgserve verify: --port requires an integer in [1, 65535]\n');
+        return { exit: EXIT_INVOCATION };
+      }
+      opts.port = v;
+    }
     else if (a === '--help' || a === '-h') {
       printHelp(process.stdout);
       return { exit: EXIT_OK };
@@ -136,6 +149,10 @@ function parseArgs(args) {
     printHelp(process.stderr);
     return { exit: EXIT_INVOCATION };
   }
+  if (opts.slug !== null && (typeof opts.slug !== 'string' || opts.slug.trim().length === 0)) {
+    process.stderr.write('pgserve verify: --slug requires a non-empty value\n');
+    return { exit: EXIT_INVOCATION };
+  }
   return { opts };
 }
 
@@ -155,12 +172,19 @@ Options:
   --cosign-bin <path>    Override the cosign executable
   --allow-fetch          Allow downloading cosign if missing
   --no-cache             Never read or write the verified-cache token
+  --slug <slug>          Verify against the locked_roots snapshot for
+                         the named consumer slug from public.autopg_meta
+                         (frozen at \`pgserve create-app\` time). When
+                         omitted, the live TRUSTED_IDENTITIES list is used.
+  --port, -p <N>         Override the postgres port for --slug lookups
+                         (default: read ~/.autopg/admin.json or 5432)
   --help, -h             Show this help
 
 Exit codes:
   0  Verified (fresh or cache hit)
-  2  Verification failed
-  3  Invocation problem (missing binary/bundle/cosign/pretrusted key)
+  2  Verification failed (binary's identity not in trust list / locked roots)
+  3  Invocation problem (missing binary/bundle/cosign/pretrusted key,
+     unknown --slug, autopg_meta not bootstrapped)
 `);
 }
 
@@ -183,11 +207,30 @@ function emit({ json }, payload) {
   }
 }
 
+function resolveVerifyPort(opts) {
+  if (typeof opts.port === 'number') return opts.port;
+  try {
+    const admin = readAdminJson();
+    if (admin && Number.isInteger(admin.port) && admin.port > 0) return admin.port;
+  } catch {
+    /* admin.json absent — fall through */
+  }
+  return 5432;
+}
+
 /**
  * Run the verify command. `argv` is the bare argument list AFTER the
- * `verify` token. Returns an integer exit code.
+ * `verify` token.
+ *
+ * @param {string[]} argv
+ * @param {object} [deps]                       dependency injection seam
+ * @param {Function} [deps.loadLockedRoots]     test stub for the
+ *                                              autopg_meta loader; defaults
+ *                                              to the real psql shellout.
+ * @returns {number} exit code
  */
-export function runVerify(argv) {
+export function runVerify(argv, deps = {}) {
+  const loadLockedRoots = deps.loadLockedRoots || loadLockedRootsImpl;
   const parsed = parseArgs(argv);
   if (parsed.exit !== undefined) return parsed.exit;
   const opts = parsed.opts;
@@ -296,10 +339,55 @@ export function runVerify(argv) {
   }
 
   // ── Cosign path ──────────────────────────────────────────────────────
+  // --slug: load the frozen locked_roots from autopg_meta and pass them
+  // through as options.trustList so cosign verification runs against the
+  // create-app-time snapshot, not the live TRUSTED_IDENTITIES (BRIEF v5
+  // deliverable D4b — the manifest LOCK 1 invariant).
+  let slugTrustList;
+  let slugLockedAt;
+  if (opts.slug) {
+    try {
+      const port = resolveVerifyPort(opts);
+      const loaded = loadLockedRoots({ slug: opts.slug, port });
+      slugTrustList = loaded.lockedRoots;
+      slugLockedAt = loaded.createdAt;
+    } catch (err) {
+      // Map structured loader errors → invocation exit code (3). These
+      // are operator/setup problems, not "this binary is wrong" failures
+      // (which are exit code 2 — handled below by verifyBinary's
+      // empty-trust-list / no-matching-identity reasons).
+      if (
+        err.code === 'EAUTOPGMETAMISSING'
+        || err.code === 'EAUTOPGSLUGUNKNOWN'
+        || err.code === 'EAUTOPGLOCKEDPARSE'
+      ) {
+        emit(opts, {
+          ok: false,
+          reason: 'slug-lookup-failed',
+          detail: err.message,
+          slug: opts.slug,
+          loaderCode: err.code,
+        });
+        return EXIT_INVOCATION;
+      }
+      // Anything else (postgres unreachable, psql crash, etc.) is also
+      // an invocation problem — operator hasn't connected pgserve verify
+      // to a reachable postmaster.
+      emit(opts, {
+        ok: false,
+        reason: 'slug-lookup-failed',
+        detail: err.message,
+        slug: opts.slug,
+      });
+      return EXIT_INVOCATION;
+    }
+  }
+
   const result = verifyBinary(binaryPath, {
     cosignBin: opts.cosignBin || process.env.PGSERVE_COSIGN_BIN || undefined,
     bundlePath: opts.bundlePath || undefined,
     allowFetch: opts.allowFetch === true,
+    trustList: slugTrustList,
   });
 
   if (!result.ok) {
@@ -348,6 +436,8 @@ export function runVerify(argv) {
     cacheFile,
     bundle: result.bundle,
     cosignBin: result.cosignBin,
+    slug: opts.slug || undefined,
+    slugLockedAt: slugLockedAt || undefined,
   });
   return EXIT_OK;
 }

package/src/cosign/locked-roots.js

@@ -0,0 +1,141 @@
+/**
+ * Locked-roots loader — reads `autopg_meta.locked_roots` for a slug.
+ *
+ * pgserve singleton (v2.6) — `autopg-distribution-cutover-finalize`
+ * wish, Group 3 (deliverable D4a). Companion to `pgserve verify --slug
+ * <slug>` (D4b): the verify verb passes the loaded `lockedRoots` as
+ * `options.trustList` to `verifyBinary()` so verification runs against
+ * the frozen-at-create-app snapshot, not the live `TRUSTED_IDENTITIES`.
+ *
+ * Why this is its own module:
+ *   - keeps create-app + verify decoupled (verify must not import
+ *     create-app's full verb code);
+ *   - lets tests stub the loader via dependency injection without
+ *     spinning up postgres;
+ *   - mirrors the cohort-canonical pattern of one psql-shellout file
+ *     per concern (provision/queries.js, gc/queries.js, etc.).
+ *
+ * Structured errors with stable `code` values let `pgserve verify`'s
+ * error-mapping layer pick the correct exit code:
+ *
+ *   EAUTOPGMETAMISSING  table doesn't exist (schema not bootstrapped on
+ *                       this postmaster — operator hasn't run any
+ *                       `pgserve create-app` yet) → invocation problem
+ *   EAUTOPGSLUGUNKNOWN  table exists but no row for slug → invocation
+ *                       problem; actionable message includes the
+ *                       remediation `pgserve create-app <slug>`
+ *   EAUTOPGLOCKEDPARSE  row exists but locked_roots JSONB is malformed
+ *                       (file rot / direct-mutation accident) →
+ *                       invocation problem
+ */
+
+import { pgQuery, quoteLiteral } from '../lib/pg-query.js';
+import { sanitizeSlug } from '../provision/db-naming.js';
+
+/**
+ * Load the locked-roots snapshot for a slug.
+ *
+ * @param {object} args
+ * @param {string} args.slug  raw or sanitized slug; sanitizeSlug runs
+ *                            inside so callers can pass either form.
+ * @param {number} [args.port=5432]
+ * @returns {{
+ *   slug: string,
+ *   lockedRoots: Array<object>,
+ *   createdAt: string,
+ *   lastUpdated: string,
+ *   manifestPath: string,
+ * }}
+ * @throws Error with `.code` set to one of EAUTOPGMETAMISSING /
+ *         EAUTOPGSLUGUNKNOWN / EAUTOPGLOCKEDPARSE on the structured
+ *         failure modes above; the underlying psql error otherwise.
+ */
+export function loadLockedRoots({ slug, port = 5432 } = {}) {
+  if (typeof slug !== 'string' || slug.trim().length === 0) {
+    throw new TypeError('loadLockedRoots: slug must be a non-empty string');
+  }
+  const sanitized = sanitizeSlug(slug);
+  if (sanitized.length === 0) {
+    const err = new Error(
+      `loadLockedRoots: slug "${slug}" sanitizes to empty; pick a slug `
+      + 'with at least one alphanumeric character',
+    );
+    err.code = 'EAUTOPGSLUGUNKNOWN';
+    throw err;
+  }
+
+  // Probe the table existence in the same query so we can disambiguate
+  // "table missing" from "row missing". `to_regclass` returns NULL when
+  // the relation is absent in the active search_path; we wrap the
+  // SELECT in a CTE that conditionally returns 'NO_TABLE' / 'NO_ROW' /
+  // the tab-separated payload. Plain text comes back via psql -At -F\t.
+  const sentinel = '__autopg_loaded__';
+  const sql = [
+    "WITH t AS (SELECT to_regclass('public.autopg_meta') AS rel)",
+    'SELECT',
+    "  CASE WHEN t.rel IS NULL THEN 'NO_TABLE' ELSE",
+    `    COALESCE((SELECT '${sentinel}\t' || locked_roots::text || '\t' ||`,
+    "             to_char(created_at AT TIME ZONE 'UTC', 'YYYY-MM-DD\"T\"HH24:MI:SS.MS\"Z\"') || '\t' ||",
+    "             to_char(last_updated AT TIME ZONE 'UTC', 'YYYY-MM-DD\"T\"HH24:MI:SS.MS\"Z\"') || '\t' ||",
+    '             manifest_path',
+    '             FROM public.autopg_meta',
+    `             WHERE slug = ${quoteLiteral(sanitized)} LIMIT 1), 'NO_ROW')`,
+    '  END AS payload',
+    'FROM t',
+  ].join('\n');
+
+  const out = pgQuery({ sql, port, captureStdout: true });
+
+  if (out === 'NO_TABLE') {
+    const err = new Error(
+      `loadLockedRoots: public.autopg_meta does not exist on this postmaster `
+      + '(no apps registered yet — run `pgserve create-app <slug>` to bootstrap)',
+    );
+    err.code = 'EAUTOPGMETAMISSING';
+    throw err;
+  }
+
+  if (out === 'NO_ROW' || !out.startsWith(`${sentinel}\t`)) {
+    const err = new Error(
+      `loadLockedRoots: no autopg_meta row for slug "${sanitized}" `
+      + `— run \`pgserve create-app ${sanitized}\` first`,
+    );
+    err.code = 'EAUTOPGSLUGUNKNOWN';
+    err.slug = sanitized;
+    throw err;
+  }
+
+  // Strip the sentinel + parse the four tab-separated fields.
+  const payload = out.slice(sentinel.length + 1);
+  const [lockedRootsJson, createdAt, lastUpdated, manifestPath] = payload.split('\t');
+
+  let lockedRoots;
+  try {
+    lockedRoots = JSON.parse(lockedRootsJson);
+  } catch (err) {
+    const wrap = new Error(
+      `loadLockedRoots: locked_roots JSONB for slug "${sanitized}" is malformed: ${err.message}`,
+    );
+    wrap.code = 'EAUTOPGLOCKEDPARSE';
+    wrap.slug = sanitized;
+    wrap.cause = err;
+    throw wrap;
+  }
+  if (!Array.isArray(lockedRoots)) {
+    const err = new Error(
+      `loadLockedRoots: locked_roots for slug "${sanitized}" is not a JSON array `
+      + `(got ${typeof lockedRoots})`,
+    );
+    err.code = 'EAUTOPGLOCKEDPARSE';
+    err.slug = sanitized;
+    throw err;
+  }
+
+  return {
+    slug: sanitized,
+    lockedRoots,
+    createdAt,
+    lastUpdated,
+    manifestPath,
+  };
+}

package/src/cosign/trust-list.js

@@ -37,22 +37,45 @@ export const TRUSTED_IDENTITIES = Object.freeze([
     id: 'automagik-genie-release',
     publisher: '@automagik/genie',
     issuer: SIGSTORE_GITHUB_ACTIONS_ISSUER,
-    identityRegexp: '^https://github.com/automagik-dev/genie/.github/workflows/release.yml@refs/tags/v.*$',
-    description: 'Namastex automagik genie release workflow (GitHub Actions OIDC)',
+    // genie's release.yml is an orchestrator that workflow_call's into
+    // sign-attest.yml — the Fulcio SAN URI therefore binds to
+    // sign-attest.yml@<ref>, not release.yml@<ref>. Verified against
+    // both v4.260511.1 (released from main) and v4.260511.2 (released
+    // from wish/genie-distribution-cutover-g1) bundle certificates on
+    // 2026-05-11: both cert subjects are
+    // `automagik-dev/genie/.github/workflows/sign-attest.yml@refs/tags/v4.260511.x`.
+    // Same shape as pgserve's own entry below.
+    identityRegexp: '^https://github.com/automagik-dev/genie/.github/workflows/sign-attest.yml@refs/tags/v.*$',
+    description: 'Namastex automagik genie sign-attest workflow (GitHub Actions OIDC)',
   }),
   Object.freeze({
     id: 'automagik-omni-release',
     publisher: '@automagik/omni',
     issuer: SIGSTORE_GITHUB_ACTIONS_ISSUER,
-    identityRegexp: '^https://github.com/automagik-dev/omni/.github/workflows/release.yml@refs/tags/v.*$',
-    description: 'Namastex automagik omni release workflow (GitHub Actions OIDC)',
+    // Omni signing pipeline mirrors genie's orchestrator+workflow_call
+    // pattern (Felipe directive 2026-05-11, decision 2.α for
+    // `v3-prerelease-trust-loop` G2): release.yml orchestrates, the
+    // cosign keyless sign-blob runs inside a reusable sign-attest.yml,
+    // and the Fulcio SAN URI binds to sign-attest.yml@<ref>. Anchoring
+    // here pre-emptively so omni's first signed tag (post-G2 merge)
+    // verifies without a follow-up trust-list flip. Re-validate against
+    // the first signed omni bundle during G4 smoke.
+    identityRegexp: '^https://github.com/automagik-dev/omni/.github/workflows/sign-attest.yml@refs/tags/v.*$',
+    description: 'Namastex automagik omni sign-attest workflow (GitHub Actions OIDC)',
   }),
   Object.freeze({
     id: 'automagik-pgserve-release',
     publisher: 'pgserve',
     issuer: SIGSTORE_GITHUB_ACTIONS_ISSUER,
-    identityRegexp: '^https://github.com/namastexlabs/pgserve/.github/workflows/release.yml@refs/tags/v.*$',
-    description: 'Namastex automagik pgserve release workflow (GitHub Actions OIDC)',
+    // Wave A (v2.6.x): pgserve's signing happens in `sign-attest.yml`,
+    // not `release.yml` (which is the unrelated npm-publish workflow
+    // with zero cosign content). Renaming sign-attest.yml → release.yml
+    // would clobber that workflow, so we anchor the trust regex on
+    // sign-attest.yml instead. Mirror image of genie PR #1725 (binding
+    // release.yml@refs/tags/v* — same Sigstore identity discipline,
+    // different workflow filename).
+    identityRegexp: '^https://github.com/namastexlabs/pgserve/.github/workflows/sign-attest.yml@refs/tags/v.*$',
+    description: 'Namastex automagik pgserve sign-attest workflow (GitHub Actions OIDC)',
   }),
 ]);
 

package/src/cosign/verify-binary.js

@@ -54,13 +54,141 @@ export function sha256File(filePath) {
 }
 
 /**
- * Resolve the sidecar bundle path for a given binary path. Convention:
- * `<binary>.bundle`. Operators that publish detached `.sig` + `.cert` can
- * regenerate a bundle with `cosign sign-blob --bundle <path>.bundle`; we
- * intentionally only support the bundle form to keep the surface narrow.
+ * Candidate sidecar bundle paths for a given binary path, in priority
+ * order. First existing file wins. When none exist, the first candidate
+ * (`<binary>.bundle`) is returned so the caller's existing
+ * `bundle-missing` error path keeps the same operator-facing message
+ * shape.
+ *
+ * Three conventions are accepted:
+ *
+ *   1. `<binary>.bundle` — `cosign sign-blob --bundle` default;
+ *      pgserve's own producer convention.
+ *   2. `<binary-stem>.intoto.jsonl` — slsa-github-generator
+ *      per-artifact provenance (writes `<artifact>.intoto.jsonl` when
+ *      provenance-name interpolates the artifact stem). The stem is
+ *      computed by stripping `.tgz` (the only archive ext used in the
+ *      automagik-cohort cosign trust loop today).
+ *   3. `<dirname>/provenance.intoto.jsonl` — slsa-github-generator
+ *      generic-provenance default (single sibling per release upload).
+ *      This is what `automagik-dev/genie` ships today (verified via
+ *      `gh release view` against v4.260508.3+).
+ *
+ * Why fall-through, not single-shape: CV-VERIFY-BUNDLE-NAMING (qa
+ * Wave-B-live finding 2026-05-09). pgserve's prior single-shape
+ * resolver returned literal `<binary>.bundle` and failed every
+ * `pgserve verify` against producer-side artifacts that ship per the
+ * standards-compliant `intoto.jsonl` conventions. Consumer-side
+ * fall-through preserves the producer's standards conformance instead
+ * of forcing every producer-side wave (A/B/C) into a non-standard
+ * `.bundle` rename.
+ */
+export function resolveBundleCandidates(binaryPath) {
+  const stem = binaryPath.replace(/\.tgz$/, '');
+  return [
+    `${binaryPath}.bundle`,
+    `${stem}.intoto.jsonl`,
+    path.join(path.dirname(binaryPath), 'provenance.intoto.jsonl'),
+  ];
+}
+
+/**
+ * Resolve the sidecar bundle path for a given binary path. Returns the
+ * first existing candidate; when none exist, returns the first
+ * candidate (`<binary>.bundle`) so the existing `bundle-missing` error
+ * path retains its operator-facing message shape.
+ *
+ * Callers that need the full candidate list (e.g. for diagnostics) can
+ * use `resolveBundleCandidates` directly.
  */
 export function resolveBundlePath(binaryPath) {
-  return `${binaryPath}.bundle`;
+  const candidates = resolveBundleCandidates(binaryPath);
+  return candidates.find((p) => fs.existsSync(p)) ?? candidates[0];
+}
+
+/**
+ * Detect detached cosign artifacts (`<binary>.sig` + `<binary>.cert`)
+ * for a binary. Returns `{ signature, certificate }` when both
+ * siblings exist; null otherwise.
+ *
+ * WAVE-B-BUNDLE-FORMAT (v2.6.3): cosign supports two output shapes for
+ * `cosign sign-blob`:
+ *
+ *   1. Bundled  — `--bundle <path>` writes a JSON envelope containing
+ *      sig + cert + tlog + bundle metadata. Verified via
+ *      `cosign verify-blob --bundle <path>`.
+ *   2. Detached — `--output-signature <sig> --output-certificate <cert>`
+ *      writes two sidecar files. Verified via
+ *      `cosign verify-blob --signature <sig> --certificate <cert>`.
+ *
+ * `automagik-dev/genie` (and many slsa-github-generator-driven release
+ * pipelines) emit the detached pair as their release-identity-bearing
+ * signature, alongside a separate `provenance.intoto.jsonl` carrying
+ * the SLSA generator's identity. Pre-fix pgserve only consumed bundled
+ * formats and silently failed `pgserve verify` against detached
+ * producers because `provenance.intoto.jsonl`'s cert subject doesn't
+ * match the consumer-side trust regex. This helper closes that gap on
+ * the consumer side per the asymmetric-cohort principle (Postel's Law:
+ * pgserve adapts to producer-side standards-compliant emit shapes).
+ *
+ * Priority semantics (used in verifyBinary):
+ *   - When a caller passes `options.bundlePath` explicitly, that wins.
+ *   - Otherwise, detached takes priority over bundle resolution when
+ *     both shapes' siblings exist for the same binary. Reasoning:
+ *     producer-explicit publishing of `<binary>.sig` + `<binary>.cert`
+ *     is the established cosign convention; preferring bundles
+ *     silently could mask producer-side regressions in a dual-emit
+ *     setup. Operators who specifically want bundle resolution can
+ *     pass `--bundle <path>` to override.
+ */
+export function resolveDetachedCosign(binaryPath) {
+  const signature = `${binaryPath}.sig`;
+  const certificate = `${binaryPath}.cert`;
+  if (fs.existsSync(signature) && fs.existsSync(certificate)) {
+    return { signature, certificate };
+  }
+  return null;
+}
+
+/**
+ * Compute the verification material pgserve will hand to cosign for a
+ * given binary, applying the priority rules documented on
+ * `resolveDetachedCosign`. Returned shapes:
+ *
+ *   { kind: 'bundle',   bundlePath, exists, probed: string[] }
+ *   { kind: 'detached', signature, certificate, exists, probed: string[] }
+ *
+ * `exists` is true iff every required sibling file is on disk. `probed`
+ * lists the paths inspected so the bundle-missing diagnostic can echo
+ * them back to operators.
+ */
+export function resolveVerificationMaterial(binaryPath, { bundlePath } = {}) {
+  if (bundlePath) {
+    return {
+      kind: 'bundle',
+      bundlePath,
+      exists: fs.existsSync(bundlePath),
+      probed: [bundlePath],
+    };
+  }
+  const detached = resolveDetachedCosign(binaryPath);
+  if (detached) {
+    return {
+      kind: 'detached',
+      signature: detached.signature,
+      certificate: detached.certificate,
+      exists: true,
+      probed: [detached.signature, detached.certificate],
+    };
+  }
+  const candidates = resolveBundleCandidates(binaryPath);
+  const found = candidates.find((p) => fs.existsSync(p));
+  return {
+    kind: 'bundle',
+    bundlePath: found ?? candidates[0],
+    exists: !!found,
+    probed: [...candidates, `${binaryPath}.sig`, `${binaryPath}.cert`],
+  };
 }
 
 /**
@@ -187,12 +315,23 @@ export function verifyBinary(binaryPath, options = {}) {
     return { ok: false, reason: 'binary-not-a-file', detail: binaryPath };
   }
 
-  const bundlePath = options.bundlePath || resolveBundlePath(binaryPath);
-  if (!fs.existsSync(bundlePath)) {
+  const material = resolveVerificationMaterial(binaryPath, { bundlePath: options.bundlePath });
+  if (!material.exists) {
+    // CV-VERIFY-BUNDLE-NAMING (v2.6.3) + WAVE-B-BUNDLE-FORMAT (v2.6.3):
+    // when neither bundled siblings nor the detached `.sig`+`.cert` pair
+    // exist, surface the full probed list in the error detail so
+    // operators see exactly which paths pgserve inspected. The
+    // bundle-missing reason code is unchanged so any log-grep wired
+    // against it keeps working; an explicit override via
+    // options.bundlePath narrows the probe list to just that path.
     return {
       ok: false,
       reason: 'bundle-missing',
-      detail: `expected sigstore bundle at ${bundlePath} (run \`cosign sign-blob --bundle ${bundlePath} ${binaryPath}\` to attest)`,
+      detail:
+        `expected cosign verification material for ${binaryPath} — probed: ${material.probed.join(', ')}. `
+        + `Pass --bundle <path> to override, or run `
+        + `\`cosign sign-blob --bundle ${binaryPath}.bundle ${binaryPath}\` to attest `
+        + `(or use detached \`--output-signature ${binaryPath}.sig --output-certificate ${binaryPath}.cert\`).`,
     };
   }
 
@@ -225,7 +364,7 @@ export function verifyBinary(binaryPath, options = {}) {
     }
     const result = invokeCosign({
       cosignBin,
-      bundlePath,
+      material,
       binaryPath,
       identity,
     });
@@ -238,7 +377,10 @@ export function verifyBinary(binaryPath, options = {}) {
         tier: COSIGN_TIER,
         sha256,
         cosignBin,
-        bundle: bundlePath,
+        // Back-compat: callers reading `.bundle` still get a value
+        // (null when detached, the path when bundled).
+        bundle: material.kind === 'bundle' ? material.bundlePath : null,
+        material,
         identityChain,
       };
     }
@@ -254,10 +396,18 @@ export function verifyBinary(binaryPath, options = {}) {
   };
 }
 
-function invokeCosign({ cosignBin, bundlePath, binaryPath, identity }) {
+function invokeCosign({ cosignBin, material, binaryPath, identity }) {
+  // WAVE-B-BUNDLE-FORMAT (v2.6.3): dispatch on material.kind so cosign
+  // gets the matching argv shape — `--bundle <path>` for bundled
+  // sigstore JSON envelopes; `--signature <sig> --certificate <cert>`
+  // for detached cosign sign-blob output (genie's release-identity-
+  // bearing artifacts ship in this shape).
+  const materialArgs = material.kind === 'detached'
+    ? ['--signature', material.signature, '--certificate', material.certificate]
+    : ['--bundle', material.bundlePath];
   const args = [
     'verify-blob',
-    '--bundle', bundlePath,
+    ...materialArgs,
     '--certificate-identity-regexp', identity.identityRegexp,
     '--certificate-oidc-issuer', identity.issuer,
     binaryPath,