feat(companion): add release bundle verification mode

README.md

@@ -1737,6 +1737,7 @@ Companion runtime helper:
 - `src/companion/bootstrapManifest.ts` provides `createCompanionBootstrapManifest()` for generating a typed gateway/node/runtime bootstrap contract used by packaging flows, including optional initial status/location/push payloads.
 - `src/companion/releaseBundle.ts` provides `writeCompanionReleaseBundle()` for writing a distributable companion bundle directory (bootstrap JSON + launcher script + README + SHA-256 checksums).
 - `src/companion/shellTemplate.ts` provides `writeCompanionShellTemplate()` for emitting platform starter shells (macOS/iOS/Android native scaffold snippets + bootstrap JSON).
+- `src/companion/releaseVerify.ts` provides `verifyCompanionReleaseBundle()` for validating bundle checksums and optional signature metadata.
 
 Minimal companion CLI:
 - `flynn companion --once` connects to the gateway, registers a node, publishes one heartbeat, then exits.
@@ -1746,6 +1747,7 @@ Minimal companion CLI:
 - `flynn companion --export-release-bundle ./dist/companion-macos` writes a release bundle directory (`companion.bootstrap.json`, `run-companion.sh`, `README.md`, `CHECKSUMS.sha256`) and exits.
 - `flynn companion --export-release-bundle ./dist/companion-macos --signing-key ./keys/release-private.pem --signing-key-id team-k1` also writes `CHECKSUMS.sha256.sig` for signed verification workflows.
 - `flynn companion --platform ios --export-shell-template ./dist/companion-ios-template` writes a platform-native starter template directory (`companion.bootstrap.json`, native starter file, `README.md`) and exits.
+- `flynn companion --verify-release-bundle ./dist/companion-macos --verify-signing-key ./keys/release-public.pem --verify-signing-key-id team-k1 --require-signature` verifies checksums and signature metadata before install.
 - `flynn companion --once --platform ios --app-version 1.2.3 --device-name "iPhone" --status-text ready --battery-pct 84 --power-source battery` sends richer initial node status metadata.
 - `flynn companion --once --latitude 37.3349 --longitude -122.009 --location-source gps` bootstraps node location metadata.
 - `flynn companion --once --platform android --push-token <fcm-token>` (or `--platform ios --push-token <apns-token>`) registers push routing metadata during bootstrap.

docs/api/PROTOCOL.md

@@ -23,7 +23,7 @@ The gateway provides:
 - **HTTP Server**: Serves static dashboard and handles webhook endpoints
 - **Node Capability Negotiation**: Optional companion-node role/capability registration
 
-Operational note: onboarding (`flynn setup` / `flynn onboard`) now runs post-save live readiness checks (model/channel/memory/automation) and prints a guided first-success task flow. Companion CLI now also supports bootstrap-manifest export (`flynn companion --export-bootstrap <path|->`), release-bundle export (`--export-release-bundle <dir>` with optional `--signing-key`/`--signing-key-id` signature output), platform shell-template export (`--export-shell-template <dir>`), plus richer shell bootstrap flags for status/location/push (`--app-version`, `--latitude/--longitude`, `--push-token`, etc.) for desktop/mobile app packaging without changing JSON-RPC method/event shapes.
+Operational note: onboarding (`flynn setup` / `flynn onboard`) now runs post-save live readiness checks (model/channel/memory/automation) and prints a guided first-success task flow. Companion CLI now also supports bootstrap-manifest export (`flynn companion --export-bootstrap <path|->`), release-bundle export (`--export-release-bundle <dir>` with optional `--signing-key`/`--signing-key-id` signature output), release-bundle verification (`--verify-release-bundle <dir>` with optional `--verify-signing-key`/`--verify-signing-key-id`/`--require-signature`), platform shell-template export (`--export-shell-template <dir>`), plus richer shell bootstrap flags for status/location/push (`--app-version`, `--latitude/--longitude`, `--push-token`, etc.) for desktop/mobile app packaging without changing JSON-RPC method/event shapes.
 
 ### Execution Model (Sessions + Per-Session Queue)
 
@@ -1864,4 +1864,5 @@ For more implementation details, see:
 - Platform companion wrappers: `src/companion/platformClients.ts`
 - Companion bootstrap manifest helper: `src/companion/bootstrapManifest.ts` (typed packaging manifest contract used by `flynn companion --export-bootstrap`, including optional initial status/location/push payloads)
 - Companion release bundle helper: `src/companion/releaseBundle.ts` (writes bootstrap JSON + launcher script + README + `CHECKSUMS.sha256`; optional `CHECKSUMS.sha256.sig` when a signing key is provided)
+- Companion release bundle verifier: `src/companion/releaseVerify.ts` (validates `CHECKSUMS.sha256` and optional signature metadata against a provided public key)
 - Companion shell template helper: `src/companion/shellTemplate.ts` (writes platform-native starter template files for `macos`, `ios`, and `android` shell scaffolding)

docs/architecture/AGENT_DIAGRAM.md

@@ -158,6 +158,7 @@ Gateway streaming UX signals:
 - `flynn companion --export-bootstrap <path|->` can emit a resolved companion bootstrap manifest (gateway/node/runtime contract) for desktop/mobile packaging flows without opening a runtime connection.
 - `flynn companion --export-release-bundle <dir>` can emit a distributable shell bundle (bootstrap JSON + launcher + README + SHA-256 checksums) for desktop/mobile packaging pipelines.
 - `flynn companion --export-release-bundle ... --signing-key <pem>` can additionally emit `CHECKSUMS.sha256.sig` for signed artifact verification pipelines.
+- `flynn companion --verify-release-bundle <dir>` can validate bundle checksums and optional signatures before installation or rollout.
 - `flynn companion --export-shell-template <dir>` can emit platform starter shell templates (macOS/iOS/Android native scaffold files + bootstrap JSON) for reference app bootstrapping.
 - `flynn companion` can bootstrap status/location/push metadata on connect (`node.status.set` + optional `node.location.set`/`node.push_token.set`) so thin companion shells can register operational context in one launch.
 - Canvas artifacts are persisted by the gateway so session UI surfaces can recover after daemon restarts.

docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md

@@ -23,6 +23,7 @@ If you only want the protocol surface, see `docs/api/PROTOCOL.md`.
 - Companion packaging/bootstrap can be generated offline via `flynn companion --export-bootstrap <path|->`, which emits resolved gateway/node/runtime settings without opening a WebSocket session.
 - Companion release artifacts can be generated via `flynn companion --export-release-bundle <dir>`, producing bootstrap JSON + launcher + README + `CHECKSUMS.sha256` for installable shell distribution workflows.
 - Companion release-bundle exports can optionally be signed (`--signing-key`, `--signing-key-id`) to emit `CHECKSUMS.sha256.sig` for distribution trust verification.
+- Companion release bundles can be verified before install via `flynn companion --verify-release-bundle <dir>` with optional signature-key checks.
 - Companion platform starter scaffolds can be generated via `flynn companion --export-shell-template <dir>` for macOS/iOS/Android reference app bootstrapping.
 - Companion CLI supports one-shot shell bootstrap metadata for live sessions (`--app-version`/`--status-text`, `--latitude`/`--longitude`, `--push-token`) so desktop/mobile wrappers can initialize node status/location/push in a single launch flow.
 - Canvas artifacts are persisted per session under the gateway data directory for UI recovery across restarts.

docs/operations/COMPANION_RELEASE_BUNDLE.md

@@ -68,6 +68,16 @@ Expected result:
 
 If signature is present, verify `CHECKSUMS.sha256.sig` with your org signing key policy before launch.
 
+Automated CLI verification mode:
+
+```bash
+flynn companion \
+  --verify-release-bundle ./dist/companion-macos \
+  --verify-signing-key ./keys/release-public.pem \
+  --verify-signing-key-id team-k1 \
+  --require-signature
+```
+
 ## Launch
 
 ```bash

docs/plans/2026-02-26-personal-assistant-productization-plan.md

@@ -49,7 +49,7 @@ Within 8-10 weeks, ship a stable "Personal Assistant Mode" that supports:
 2. Ship a minimal mobile companion shell (iOS + Android) for registration, status, push token, and message handoff.
 3. Add signed release artifacts and installation docs.
 
-Status update (2026-02-27): companion bootstrap-manifest export is now available via `flynn companion --export-bootstrap <path|->` as a packaging contract for desktop/mobile shells, `flynn companion --export-release-bundle <dir>` now emits bundle artifacts (bootstrap JSON + launcher + README + `CHECKSUMS.sha256`, optional `CHECKSUMS.sha256.sig` with `--signing-key`), `flynn companion --export-shell-template <dir>` now emits macOS/iOS/Android starter shell templates, and `flynn companion` supports one-shot status/location/push bootstrap flags (`--app-version`, `--latitude/--longitude`, `--push-token`) so thin shells can initialize companion metadata in a single run.
+Status update (2026-02-27): companion bootstrap-manifest export is now available via `flynn companion --export-bootstrap <path|->` as a packaging contract for desktop/mobile shells, `flynn companion --export-release-bundle <dir>` now emits bundle artifacts (bootstrap JSON + launcher + README + `CHECKSUMS.sha256`, optional `CHECKSUMS.sha256.sig` with `--signing-key`), `flynn companion --verify-release-bundle <dir>` now validates checksum/signature artifacts before install, `flynn companion --export-shell-template <dir>` now emits macOS/iOS/Android starter shell templates, and `flynn companion` supports one-shot status/location/push bootstrap flags (`--app-version`, `--latitude/--longitude`, `--push-token`) so thin shells can initialize companion metadata in a single run.
 
 ### Implementation Anchors
 

docs/plans/state.json

@@ -7054,10 +7054,31 @@
         "docs/plans/state.json"
       ],
       "test_status": "pnpm test:run src/cli/companion.test.ts src/companion/releaseBundle.test.ts + pnpm typecheck passing"
+    },
+    "personal-assistant-productization-phase1-companion-bundle-verification-mode": {
+      "status": "completed",
+      "date": "2026-02-27",
+      "updated": "2026-02-27",
+      "summary": "Added companion release-bundle verification automation. `flynn companion --verify-release-bundle <dir>` now verifies checksum manifests and can validate signature metadata with `--verify-signing-key`, `--verify-signing-key-id`, and `--require-signature` gates. Added reusable `verifyCompanionReleaseBundle()` helper plus regression tests for signed/unsigned/tampered bundles.",
+      "files_modified": [
+        "src/companion/releaseVerify.ts",
+        "src/companion/releaseVerify.test.ts",
+        "src/companion/index.ts",
+        "src/cli/companion.ts",
+        "src/cli/companion.test.ts",
+        "README.md",
+        "docs/api/PROTOCOL.md",
+        "docs/architecture/AGENT_DIAGRAM.md",
+        "docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md",
+        "docs/operations/COMPANION_RELEASE_BUNDLE.md",
+        "docs/plans/2026-02-26-personal-assistant-productization-plan.md",
+        "docs/plans/state.json"
+      ],
+      "test_status": "pnpm test:run src/companion/releaseVerify.test.ts src/cli/companion.test.ts src/companion/releaseBundle.test.ts + pnpm typecheck passing"
     }
   },
   "overall_progress": {
-    "total_test_count": 2580,
+    "total_test_count": 2583,
     "all_tests_passing": true,
     "p0_completion": "3/3 (100%)",
     "p1_completion": "4/4 (100%)",
@@ -7072,7 +7093,7 @@
     "tier2_completion": "4/4 (100%) — inbound webhooks, vector memory search, Dockerfile, heartbeat monitor",
     "tier3_completion": "5/5 (100%) — lane queue, credential redaction, web UI token dashboard, xAI (Grok) provider, Voyage AI embeddings",
     "tier4_completion": "4/4 (100%) — gateway lock, shell completion, Tailscale Serve/Funnel, DM pairing codes",
-    "feature_gap_scorecard": "rebaselined 2026-02-26 and updated 2026-02-27 (phase 3 + phase 1 + phase 2 + phase 4 slices + companion packaging/bundle tooling + shell bootstrap controls + platform templates + signed artifacts) — channel breadth, setup wizard, baseline browser automation, subagent controls, browser workflow reliability primitives (wait/assert/extract/retries/checkpoints/guardrails/budgets), companion reconnect/runtime-handoff foundations, companion packaging primitives (bootstrap export + release-bundle artifacts + checksum manifests + optional signatures), companion install/verification runbook, platform starter shell templates for macOS/iOS/Android, and one-shot status/location/push shell bootstrap controls, voice reliability hardening (talk controls + TTS fallback/health + interruption-safe cancel semantics), and onboarding first-success funnel improvements are implemented; remaining high-impact personal-assistant gaps center on production-grade companion app binaries and distribution hardening automation.",
+    "feature_gap_scorecard": "rebaselined 2026-02-26 and updated 2026-02-27 (phase 3 + phase 1 + phase 2 + phase 4 slices + companion packaging/bundle tooling + shell bootstrap controls + platform templates + signed/verified artifacts) — channel breadth, setup wizard, baseline browser automation, subagent controls, browser workflow reliability primitives (wait/assert/extract/retries/checkpoints/guardrails/budgets), companion reconnect/runtime-handoff foundations, companion packaging primitives (bootstrap export + release-bundle artifacts + checksum manifests + optional signatures + verification mode), companion install/verification runbook, platform starter shell templates for macOS/iOS/Android, and one-shot status/location/push shell bootstrap controls, voice reliability hardening (talk controls + TTS fallback/health + interruption-safe cancel semantics), and onboarding first-success funnel improvements are implemented; remaining high-impact personal-assistant gaps center on production-grade companion app binaries and distribution automation hardening.",
     "operator_dx_milestone": "Phase 3 (Live Ops Dashboard): 2/2 plans complete — milestone done",
     "dashboard_observability": "completed — service health graphs + core service log viewer added to web UI via observability RPCs and bounded backend sampling",
     "gmail_auth_cli": "flynn gmail-auth command implemented with OAuth2 flow, doctor check, config routed to Telegram",
@@ -7105,7 +7126,7 @@
     "deeper_surfaces_phase3_companion_canvas_voice": "completed — companion reconnect resilience (auto-reconnect with backoff, pending-wait cancellation on disconnect), canvas artifact persistence (SQLite-backed store, daemon-restart durability), voice TTS fallback coverage (text-only reply on TTS failure, no dropped responses)",
     "deeper_surfaces_phase4_rollout": "completed — phase 4 rollout and operator readiness plan documented: canary rollout plan by feature flag/surface, explicit rollback playbook, operator docs and architecture/protocol docs synchronized",
     "post_phase_test_fixes": "completed — fixed 4 test failures introduced by phases 1-3: iOS/Android push listNodes (missing publishHeartbeat before platform-filtered query), server.test agent.send (run_state events now precede done; added sendAndWaitForDone helper), httpBody 413 (req.destroy() closed socket before response could be sent; replaced with Connection: close header on 413 responses)",
-    "personal_assistant_productization_plan": "in_progress — 8-10 week phased roadmap active; Phase 3 browser workflow reliability shipped, Phase 1 companion runtime reliability includes reconnect state replay + typed handoff support, companion packaging primitives now include bootstrap manifest export, release-bundle artifact generation, checksum manifests, optional signature emission, platform starter shell-template generation, and an install/verification runbook, companion shell bootstrap controls cover status/location/push metadata, Phase 2 voice reliability ships talk controls + TTS provider fallback/health + interruption-safe voice cancel mapping, and Phase 4 onboarding includes Personal Assistant Mode preset + live readiness checks + first-success guidance. Remaining phase focus: production-ready companion app surfaces and distribution automation polish.",
+    "personal_assistant_productization_plan": "in_progress — 8-10 week phased roadmap active; Phase 3 browser workflow reliability shipped, Phase 1 companion runtime reliability includes reconnect state replay + typed handoff support, companion packaging primitives now include bootstrap manifest export, release-bundle artifact generation, checksum manifests, optional signature emission, verification mode, platform starter shell-template generation, and an install/verification runbook, companion shell bootstrap controls cover status/location/push metadata, Phase 2 voice reliability ships talk controls + TTS provider fallback/health + interruption-safe voice cancel mapping, and Phase 4 onboarding includes Personal Assistant Mode preset + live readiness checks + first-success guidance. Remaining phase focus: production-ready companion app surfaces and distribution automation polish.",
     "subagents_support": "completed — subagent phases 1-3 shipped with `subagent.spawn/send/list/cancel/delete/summary`, per-child queue mode (`followup|interrupt`), budgets (`max_turns`, `max_total_tokens`, `turn_timeout_ms`), tool-profile overrides, trace-linked audit events, `/subagents` inspection commands, and focused regression tests."
   },
   "soul_md_and_cron_create": {

src/cli/companion.test.ts

@@ -12,6 +12,7 @@ const {
   mockCreateCompanionBootstrapManifest,
   mockWriteCompanionReleaseBundle,
   mockWriteCompanionShellTemplate,
+  mockVerifyCompanionReleaseBundle,
 } = vi.hoisted(() => {
   const runtimeCtorArgs: Array<{ url: string; token?: string; autoReconnect?: boolean }> = [];
   const runtimeInstances: Array<{
@@ -112,6 +113,24 @@ const {
       `${input.outputDir}/README.md`,
     ],
   }));
+  const verifyCompanionReleaseBundle = vi.fn(async (input: {
+    bundleDir: string;
+    publicKeyPem?: string;
+    expectedKeyId?: string;
+    requireSignature?: boolean;
+  }) => ({
+    bundleDir: input.bundleDir,
+    checksumsPath: `${input.bundleDir}/CHECKSUMS.sha256`,
+    verifiedFiles: [
+      { name: 'companion.bootstrap.json', expectedSha256: 'a'.repeat(64), actualSha256: 'a'.repeat(64) },
+      { name: 'run-companion.sh', expectedSha256: 'b'.repeat(64), actualSha256: 'b'.repeat(64) },
+      { name: 'README.md', expectedSha256: 'c'.repeat(64), actualSha256: 'c'.repeat(64) },
+    ],
+    signaturePath: `${input.bundleDir}/CHECKSUMS.sha256.sig`,
+    signaturePresent: true,
+    signatureVerified: Boolean(input.publicKeyPem),
+    signatureKeyId: input.expectedKeyId ?? 'bundle-k1',
+  }));
 
   return {
     mockLoadConfigSafe: loadConfigSafe,
@@ -121,6 +140,7 @@ const {
     mockCreateCompanionBootstrapManifest: createCompanionBootstrapManifest,
     mockWriteCompanionReleaseBundle: writeCompanionReleaseBundle,
     mockWriteCompanionShellTemplate: writeCompanionShellTemplate,
+    mockVerifyCompanionReleaseBundle: verifyCompanionReleaseBundle,
   };
 });
 
@@ -133,6 +153,7 @@ vi.mock('../companion/index.js', () => ({
   createCompanionBootstrapManifest: mockCreateCompanionBootstrapManifest,
   writeCompanionReleaseBundle: mockWriteCompanionReleaseBundle,
   writeCompanionShellTemplate: mockWriteCompanionShellTemplate,
+  verifyCompanionReleaseBundle: mockVerifyCompanionReleaseBundle,
   CompanionRuntimeClient: class {
     private connectionHandlers: Array<(event: { status: string }) => void> = [];
     connect = vi.fn(async () => {
@@ -174,6 +195,7 @@ describe('companion command', () => {
     mockCreateCompanionBootstrapManifest.mockClear();
     mockWriteCompanionReleaseBundle.mockClear();
     mockWriteCompanionShellTemplate.mockClear();
+    mockVerifyCompanionReleaseBundle.mockClear();
     mockLoadConfigSafe.mockReturnValue({
       config: {
         server: {
@@ -496,6 +518,45 @@ describe('companion command', () => {
     errSpy.mockRestore();
   });
 
+  it('verifies a release bundle and exits without runtime connection', async () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    const tempDir = await mkdtemp(join(tmpdir(), 'flynn-verify-key-'));
+    const keyPath = join(tempDir, 'release-public-key.pem');
+    await writeFile(keyPath, '---test-public-key---\n', 'utf8');
+    const program = new Command();
+    const { registerCompanionCommand } = await import('./companion.js');
+    registerCompanionCommand(program);
+
+    await program.parseAsync([
+      'node',
+      'test',
+      'companion',
+      '--verify-release-bundle',
+      '/tmp/flynn-companion-bundle',
+      '--verify-signing-key',
+      keyPath,
+      '--verify-signing-key-id',
+      'bundle-k1',
+      '--require-signature',
+    ]);
+
+    expect(mockVerifyCompanionReleaseBundle).toHaveBeenCalledOnce();
+    expect(mockVerifyCompanionReleaseBundle).toHaveBeenCalledWith({
+      bundleDir: '/tmp/flynn-companion-bundle',
+      publicKeyPem: '---test-public-key---\n',
+      expectedKeyId: 'bundle-k1',
+      requireSignature: true,
+    });
+    expect(mockRuntimeCtorArgs).toEqual([]);
+    expect(mockRuntimeInstances).toEqual([]);
+    expect(errSpy).not.toHaveBeenCalled();
+
+    await rm(tempDir, { recursive: true, force: true });
+    logSpy.mockRestore();
+    errSpy.mockRestore();
+  });
+
   it('applies location, push, and status bootstrap settings to runtime registration', async () => {
     const logSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
     const errSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
@@ -580,7 +641,7 @@ describe('companion command', () => {
     errSpy.mockRestore();
   });
 
-  it('sets process exit code when multiple export modes are combined', async () => {
+  it('sets process exit code when multiple companion modes are combined', async () => {
     const errSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
     const program = new Command();
     const { registerCompanionCommand } = await import('./companion.js');
@@ -596,6 +657,8 @@ describe('companion command', () => {
       '/tmp/flynn-companion-bundle',
       '--export-shell-template',
       '/tmp/flynn-companion-template',
+      '--verify-release-bundle',
+      '/tmp/flynn-companion-bundle',
     ]);
 
     expect(errSpy).toHaveBeenCalled();
@@ -624,4 +687,24 @@ describe('companion command', () => {
 
     errSpy.mockRestore();
   });
+
+  it('sets process exit code when verify-signing-key is provided without verify-release-bundle', async () => {
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    const program = new Command();
+    const { registerCompanionCommand } = await import('./companion.js');
+    registerCompanionCommand(program);
+
+    await program.parseAsync([
+      'node',
+      'test',
+      'companion',
+      '--verify-signing-key',
+      '/tmp/flynn-release-public.pem',
+    ]);
+
+    expect(errSpy).toHaveBeenCalled();
+    expect(process.exitCode).toBe(1);
+
+    errSpy.mockRestore();
+  });
 });

src/cli/companion.ts

@@ -7,6 +7,7 @@ import type { SetNodeLocationInput, SetNodePushTokenInput, SetNodeStatusInput }
 import { createCompanionBootstrapManifest } from '../companion/index.js';
 import { writeCompanionReleaseBundle } from '../companion/index.js';
 import { writeCompanionShellTemplate } from '../companion/index.js';
+import { verifyCompanionReleaseBundle } from '../companion/index.js';
 import { getConfigPath, loadConfigSafe } from './shared.js';
 
 type CompanionPlatform = SetNodeStatusInput['platform'];
@@ -42,8 +43,12 @@ interface CompanionCommandOptions {
   exportBootstrap?: string;
   exportReleaseBundle?: string;
   exportShellTemplate?: string;
+  verifyReleaseBundle?: string;
   signingKey?: string;
   signingKeyId?: string;
+  verifySigningKey?: string;
+  verifySigningKeyId?: string;
+  requireSignature?: boolean;
   once?: boolean;
 }
 
@@ -325,17 +330,32 @@ export async function runCompanionSession(options: CompanionCommandOptions): Pro
   const exportBootstrapPath = options.exportBootstrap?.trim();
   const exportReleaseBundleDir = options.exportReleaseBundle?.trim();
   const exportShellTemplateDir = options.exportShellTemplate?.trim();
+  const verifyReleaseBundleDir = options.verifyReleaseBundle?.trim();
   const signingKeyPath = options.signingKey?.trim();
   const signingKeyId = options.signingKeyId?.trim();
+  const verifySigningKeyPath = options.verifySigningKey?.trim();
+  const verifySigningKeyId = options.verifySigningKeyId?.trim();
 
-  const exportCount = [exportBootstrapPath, exportReleaseBundleDir, exportShellTemplateDir]
+  const modeCount = [exportBootstrapPath, exportReleaseBundleDir, exportShellTemplateDir, verifyReleaseBundleDir]
     .filter((value) => Boolean(value)).length;
-  if (exportCount > 1) {
+  if (modeCount > 1) {
-    throw new Error('export-bootstrap, export-release-bundle, and export-shell-template are mutually exclusive');
+    throw new Error('export-bootstrap, export-release-bundle, export-shell-template, and verify-release-bundle are mutually exclusive');
   }
   if (signingKeyPath && !exportReleaseBundleDir) {
     throw new Error('signing-key requires --export-release-bundle');
   }
+  if (signingKeyId && !exportReleaseBundleDir) {
+    throw new Error('signing-key-id requires --export-release-bundle');
+  }
+  if (verifySigningKeyPath && !verifyReleaseBundleDir) {
+    throw new Error('verify-signing-key requires --verify-release-bundle');
+  }
+  if (verifySigningKeyId && !verifyReleaseBundleDir) {
+    throw new Error('verify-signing-key-id requires --verify-release-bundle');
+  }
+  if (options.requireSignature && !verifyReleaseBundleDir) {
+    throw new Error('require-signature requires --verify-release-bundle');
+  }
 
   const manifest = createCompanionBootstrapManifest({
     gatewayUrl,
@@ -400,6 +420,34 @@ export async function runCompanionSession(options: CompanionCommandOptions): Pro
     return;
   }
 
+  if (verifyReleaseBundleDir) {
+    const verifyKeyPem = verifySigningKeyPath
+      ? await readFile(verifySigningKeyPath, 'utf8')
+      : undefined;
+    const verified = await verifyCompanionReleaseBundle({
+      bundleDir: verifyReleaseBundleDir,
+      publicKeyPem: verifyKeyPem,
+      expectedKeyId: verifySigningKeyId && verifySigningKeyId.length > 0 ? verifySigningKeyId : undefined,
+      requireSignature: options.requireSignature ?? false,
+    });
+    console.log(`Verified companion release bundle: ${verified.bundleDir}`);
+    console.log(`- Checksums: ${verified.checksumsPath}`);
+    console.log(`- Files verified: ${verified.verifiedFiles.length}`);
+    for (const file of verified.verifiedFiles) {
+      console.log(`  - ${file.name}`);
+    }
+    if (verified.signaturePresent) {
+      console.log(`- Signature file: ${verified.signaturePath}`);
+      console.log(`- Signature verified: ${verified.signatureVerified ? 'yes' : 'no (no public key provided)'}`);
+      if (verified.signatureKeyId) {
+        console.log(`- Signature key_id: ${verified.signatureKeyId}`);
+      }
+    } else {
+      console.log('- Signature file: not present');
+    }
+    return;
+  }
+
   const runtime = new CompanionRuntimeClient({
     url: gatewayUrl,
     token: gatewayToken,
@@ -592,6 +640,13 @@ export function registerCompanionCommand(program: Command): void {
       '--export-shell-template <dir>',
       'Write a platform shell template (bootstrap + native starter file + README) and exit',
     )
+    .option(
+      '--verify-release-bundle <dir>',
+      'Verify release bundle checksums/signature metadata and exit',
+    )
+    .option('--verify-signing-key <path>', 'Optional public-key PEM path for release-bundle signature verification')
+    .option('--verify-signing-key-id <value>', 'Optional expected signature key identifier')
+    .option('--require-signature', 'Require release-bundle signature file during verification', false)
     .option('--once', 'Connect, register, publish one heartbeat, then exit', false)
     .action(async (opts: CompanionCommandOptions) => {
       try {

src/companion/index.ts

@@ -12,6 +12,7 @@ export { CompanionHeartbeatLoop } from './heartbeatLoop.js';
 export { createCompanionBootstrapManifest } from './bootstrapManifest.js';
 export { writeCompanionReleaseBundle } from './releaseBundle.js';
 export { writeCompanionShellTemplate } from './shellTemplate.js';
+export { verifyCompanionReleaseBundle } from './releaseVerify.js';
 
 export type {
   CompanionRuntimeClientOptions,
@@ -87,3 +88,8 @@ export type {
   WriteCompanionShellTemplateInput,
   WriteCompanionShellTemplateResult,
 } from './shellTemplate.js';
+export type {
+  VerifyCompanionReleaseBundleInput,
+  VerifyCompanionReleaseBundleResult,
+  VerifiedReleaseFile,
+} from './releaseVerify.js';

src/companion/releaseVerify.test.ts

@@ -0,0 +1,116 @@
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { generateKeyPairSync } from 'node:crypto';
+import { describe, expect, it } from 'vitest';
+import { writeCompanionReleaseBundle } from './releaseBundle.js';
+import { verifyCompanionReleaseBundle } from './releaseVerify.js';
+
+describe('verifyCompanionReleaseBundle', () => {
+  it('verifies unsigned bundle checksums', async () => {
+    const tempDir = await mkdtemp(join(tmpdir(), 'flynn-release-verify-unsigned-'));
+    const bundleDir = join(tempDir, 'bundle');
+    await writeCompanionReleaseBundle({
+      outputDir: bundleDir,
+      manifest: {
+        schemaVersion: 1,
+        generatedAt: '2026-02-27T00:00:00.000Z',
+        gateway: { url: 'ws://127.0.0.1:18800' },
+        node: {
+          nodeId: 'verify-unsigned',
+          role: 'companion',
+          platform: 'macos',
+          capabilities: ['ui.canvas'],
+        },
+        runtime: {
+          heartbeatSeconds: 30,
+          handoffTimeoutMs: 120000,
+          autoReconnect: true,
+        },
+      },
+    });
+
+    const verified = await verifyCompanionReleaseBundle({
+      bundleDir,
+    });
+    expect(verified.signaturePresent).toBe(false);
+    expect(verified.verifiedFiles.map((file) => file.name)).toEqual([
+      'companion.bootstrap.json',
+      'run-companion.sh',
+      'README.md',
+    ]);
+
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  it('fails when checksum target content is modified', async () => {
+    const tempDir = await mkdtemp(join(tmpdir(), 'flynn-release-verify-mismatch-'));
+    const bundleDir = join(tempDir, 'bundle');
+    await writeCompanionReleaseBundle({
+      outputDir: bundleDir,
+      manifest: {
+        schemaVersion: 1,
+        generatedAt: '2026-02-27T00:00:00.000Z',
+        gateway: { url: 'ws://127.0.0.1:18800' },
+        node: {
+          nodeId: 'verify-mismatch',
+          role: 'companion',
+          platform: 'ios',
+          capabilities: ['ui.canvas'],
+        },
+        runtime: {
+          heartbeatSeconds: 30,
+          handoffTimeoutMs: 120000,
+          autoReconnect: true,
+        },
+      },
+    });
+
+    await writeFile(`${bundleDir}/README.md`, 'tampered\n', 'utf8');
+    await expect(verifyCompanionReleaseBundle({ bundleDir })).rejects.toThrow('Checksum mismatch');
+
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  it('verifies signature when public key is supplied', async () => {
+    const tempDir = await mkdtemp(join(tmpdir(), 'flynn-release-verify-signed-'));
+    const bundleDir = join(tempDir, 'bundle');
+    const keyPair = generateKeyPairSync('rsa', { modulusLength: 2048 });
+    const privatePem = keyPair.privateKey.export({ type: 'pkcs8', format: 'pem' }).toString();
+    const publicPem = keyPair.publicKey.export({ type: 'spki', format: 'pem' }).toString();
+
+    await writeCompanionReleaseBundle({
+      outputDir: bundleDir,
+      signingKeyPem: privatePem,
+      signingKeyId: 'bundle-k1',
+      manifest: {
+        schemaVersion: 1,
+        generatedAt: '2026-02-27T00:00:00.000Z',
+        gateway: { url: 'ws://127.0.0.1:18800' },
+        node: {
+          nodeId: 'verify-signed',
+          role: 'companion',
+          platform: 'android',
+          capabilities: ['ui.canvas'],
+        },
+        runtime: {
+          heartbeatSeconds: 30,
+          handoffTimeoutMs: 120000,
+          autoReconnect: true,
+        },
+      },
+    });
+
+    const verified = await verifyCompanionReleaseBundle({
+      bundleDir,
+      publicKeyPem: publicPem,
+      expectedKeyId: 'bundle-k1',
+      requireSignature: true,
+    });
+    expect(verified.signaturePresent).toBe(true);
+    expect(verified.signatureVerified).toBe(true);
+    expect(verified.signatureKeyId).toBe('bundle-k1');
+
+    await rm(tempDir, { recursive: true, force: true });
+  });
+});

src/companion/releaseVerify.ts

@@ -0,0 +1,178 @@
+import { createHash, createPublicKey, verify } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+
+export interface VerifyCompanionReleaseBundleInput {
+  bundleDir: string;
+  publicKeyPem?: string;
+  expectedKeyId?: string;
+  requireSignature?: boolean;
+}
+
+export interface VerifiedReleaseFile {
+  name: string;
+  expectedSha256: string;
+  actualSha256: string;
+}
+
+export interface VerifyCompanionReleaseBundleResult {
+  bundleDir: string;
+  checksumsPath: string;
+  verifiedFiles: VerifiedReleaseFile[];
+  signaturePath?: string;
+  signaturePresent: boolean;
+  signatureVerified: boolean;
+  signatureKeyId?: string;
+}
+
+interface ParsedSignature {
+  keyId?: string;
+  algorithm: string;
+  encoding: string;
+  signature: string;
+}
+
+function parseChecksums(raw: string): Array<{ hash: string; name: string }> {
+  const lines = raw
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && !line.startsWith('#'));
+  const entries: Array<{ hash: string; name: string }> = [];
+  for (const line of lines) {
+    const parts = line.split(/\s+/, 2);
+    const hash = parts[0];
+    const name = parts[1];
+    if (!hash || !name) {
+      throw new Error(`Invalid checksum line: ${line}`);
+    }
+    if (!/^[a-f0-9]{64}$/i.test(hash)) {
+      throw new Error(`Invalid SHA-256 checksum for ${name}`);
+    }
+    entries.push({ hash: hash.toLowerCase(), name });
+  }
+  if (entries.length === 0) {
+    throw new Error('No checksum entries found');
+  }
+  return entries;
+}
+
+function parseSignature(raw: string): ParsedSignature {
+  const parsed: Partial<ParsedSignature> = {};
+  const lines = raw
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && !line.startsWith('#'));
+  for (const line of lines) {
+    const split = line.indexOf('=');
+    if (split <= 0) {
+      continue;
+    }
+    const key = line.slice(0, split);
+    const value = line.slice(split + 1);
+    if (key === 'key_id') {
+      parsed.keyId = value;
+      continue;
+    }
+    if (key === 'algorithm') {
+      parsed.algorithm = value;
+      continue;
+    }
+    if (key === 'encoding') {
+      parsed.encoding = value;
+      continue;
+    }
+    if (key === 'signature') {
+      parsed.signature = value;
+    }
+  }
+  if (!parsed.algorithm || !parsed.encoding || !parsed.signature) {
+    throw new Error('Invalid signature metadata: algorithm/encoding/signature are required');
+  }
+  return parsed as ParsedSignature;
+}
+
+async function readOptional(path: string): Promise<string | undefined> {
+  try {
+    return await readFile(path, 'utf8');
+  } catch (error) {
+    if (
+      error
+      && typeof error === 'object'
+      && 'code' in error
+      && (error as { code?: string }).code === 'ENOENT'
+    ) {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+export async function verifyCompanionReleaseBundle(
+  input: VerifyCompanionReleaseBundleInput,
+): Promise<VerifyCompanionReleaseBundleResult> {
+  const checksumsPath = `${input.bundleDir}/CHECKSUMS.sha256`;
+  const checksumsRaw = await readFile(checksumsPath, 'utf8');
+  const checksumsEntries = parseChecksums(checksumsRaw);
+  const verifiedFiles: VerifiedReleaseFile[] = [];
+
+  for (const entry of checksumsEntries) {
+    const filePath = `${input.bundleDir}/${entry.name}`;
+    const fileRaw = await readFile(filePath);
+    const actualSha256 = createHash('sha256').update(fileRaw).digest('hex');
+    if (actualSha256 !== entry.hash) {
+      throw new Error(`Checksum mismatch for ${entry.name}`);
+    }
+    verifiedFiles.push({
+      name: entry.name,
+      expectedSha256: entry.hash,
+      actualSha256,
+    });
+  }
+
+  const signaturePath = `${input.bundleDir}/CHECKSUMS.sha256.sig`;
+  const signatureRaw = await readOptional(signaturePath);
+  const signaturePresent = signatureRaw !== undefined;
+  let signatureVerified = false;
+  let signatureKeyId: string | undefined;
+
+  if (input.requireSignature && !signaturePresent) {
+    throw new Error('Signature is required but CHECKSUMS.sha256.sig was not found');
+  }
+
+  if (input.publicKeyPem) {
+    if (!signaturePresent) {
+      throw new Error('Public key provided but CHECKSUMS.sha256.sig was not found');
+    }
+    const parsed = parseSignature(signatureRaw);
+    signatureKeyId = parsed.keyId;
+    if (parsed.algorithm !== 'sha256') {
+      throw new Error(`Unsupported signature algorithm: ${parsed.algorithm}`);
+    }
+    if (parsed.encoding !== 'base64') {
+      throw new Error(`Unsupported signature encoding: ${parsed.encoding}`);
+    }
+    if (input.expectedKeyId && parsed.keyId !== input.expectedKeyId) {
+      throw new Error(`Signature key_id mismatch: expected ${input.expectedKeyId}, got ${parsed.keyId ?? 'unset'}`);
+    }
+
+    const verified = verify(
+      'sha256',
+      Buffer.from(checksumsRaw, 'utf8'),
+      createPublicKey(input.publicKeyPem),
+      Buffer.from(parsed.signature, 'base64'),
+    );
+    if (!verified) {
+      throw new Error('Signature verification failed');
+    }
+    signatureVerified = true;
+  }
+
+  return {
+    bundleDir: input.bundleDir,
+    checksumsPath,
+    verifiedFiles,
+    signaturePath: signaturePresent ? signaturePath : undefined,
+    signaturePresent,
+    signatureVerified,
+    signatureKeyId,
+  };
+}