feat(companion): add runnable macOS menu-bar reference app scaffold

2026-02-26 20:51:00 -08:00
parent 3f6232d1fb
commit d303869866
21 changed files with 695 additions and 13 deletions
@@ -1739,7 +1739,8 @@ Companion runtime helper:
 - `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.
 - `src/companion/releasePipeline.ts` provides `buildAndVerifyCompanionReleaseBundle()` for build-and-verify automation (including signed bundle flows).
- `src/companion/referenceApps.ts` provides `generateReferenceCompanionApps()` for deterministic macOS/iOS/Android reference app starter exports.
+- `src/companion/macosMenuBarApp.ts` provides `generateMacOSMenuBarApp()` for emitting a runnable Swift Package macOS menu-bar companion scaffold.
+- `src/companion/referenceApps.ts` provides `generateReferenceCompanionApps()` for deterministic macOS/iOS/Android starter shells plus a runnable `macos-app` Swift Package scaffold.

 Minimal companion CLI:
 - `flynn companion --once` connects to the gateway, registers a node, publishes one heartbeat, then exits.
@@ -1751,7 +1752,7 @@ Minimal companion CLI:
 - `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.
 - `pnpm companion:bundle -- --output ./dist/companion-macos --platform macos --signing-key ./keys/release-private.pem --signing-key-id team-k1` builds and verifies a release bundle in one step.
- `pnpm companion:reference-apps -- --output ./apps/companion` regenerates macOS/iOS/Android reference app starter directories.
+- `pnpm companion:reference-apps -- --output ./apps/companion` regenerates macOS/iOS/Android reference app starter shells plus `apps/companion/macos-app` runnable scaffold.
 - GitHub Actions workflow `.github/workflows/companion-release-bundle.yml` runs build-and-verify bundle automation and uploads release artifacts on manual dispatch.

 `run-companion.sh` verifies bundle checksums (`CHECKSUMS.sha256`) before launching `flynn companion`.
@@ -3,6 +3,7 @@
 This directory contains generated companion starter shells for:

 - macOS menu-bar style wrapper
+- macOS runnable menu-bar app scaffold (Swift Package)
 - iOS shell
 - Android shell

@@ -1,6 +1,6 @@
 {
  "schemaVersion": 1,
-  "generatedAt": "2026-02-27T03:35:54.245Z",
+  "generatedAt": "2026-02-27T04:50:38.373Z",
  "gateway": {
    "url": "ws://127.0.0.1:18800"
  },
@@ -1,6 +1,6 @@
 {
  "schemaVersion": 1,
-  "generatedAt": "2026-02-27T03:35:54.245Z",
+  "generatedAt": "2026-02-27T04:50:38.373Z",
  "gateway": {
    "url": "ws://127.0.0.1:18800"
  },
@@ -0,0 +1,18 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+  name: "FlynnCompanionMenuBar",
+  platforms: [
+    .macOS(.v13)
+  ],
+  products: [
+    .executable(name: "FlynnCompanionMenuBar", targets: ["FlynnCompanionMenuBar"])
+  ],
+  targets: [
+    .executableTarget(
+      name: "FlynnCompanionMenuBar",
+      resources: [.copy("Resources/companion.bootstrap.json")]
+    )
+  ]
+)
@@ -0,0 +1,21 @@
+# Flynn macOS Companion Menu Bar App (Reference MVP)
+
+This is a runnable Swift Package reference app that creates a macOS menu bar companion controller.
+
+## Capabilities
+
+- Loads companion.bootstrap.json from package resources.
+- Starts/stops flynn companion as a child process from menu actions.
+- Runs one-shot handoff prompts (flynn companion --once --handoff ...).
+- Shows process state in the menu bar title (F, F* running, F! error).
+
+## Build + Run
+
+Run:
+cd <this-directory>
+swift run FlynnCompanionMenuBar
+
+Prerequisites:
+
+- macOS with Swift toolchain.
+- flynn executable available in PATH.
@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-02-27T04:50:38.373Z",
+  "gateway": {
+    "url": "ws://127.0.0.1:18800"
+  },
+  "node": {
+    "nodeId": "macos-menu-bar-reference",
+    "role": "companion",
+    "platform": "macos",
+    "capabilities": [
+      "ui.canvas",
+      "node.status.write",
+      "node.location.write",
+      "node.push.register"
+    ]
+  },
+  "runtime": {
+    "heartbeatSeconds": 30,
+    "handoffTimeoutMs": 120000,
+    "autoReconnect": true
+  }
+}
@@ -0,0 +1,218 @@
+import AppKit
+import Foundation
+
+struct CompanionBootstrap: Codable {
+  struct Gateway: Codable {
+    let url: String
+    let token: String?
+  }
+  struct Node: Codable {
+    let nodeId: String
+    let role: String
+    let platform: String
+    let capabilities: [String]
+  }
+  struct Runtime: Codable {
+    let heartbeatSeconds: Int
+    let handoffTimeoutMs: Int
+    let autoReconnect: Bool
+  }
+  let schemaVersion: Int
+  let generatedAt: String
+  let gateway: Gateway
+  let node: Node
+  let runtime: Runtime
+}
+
+final class CompanionProcessController {
+  private var process: Process?
+  private var isRunning = false
+  private(set) var lastError: String?
+  private let bootstrap: CompanionBootstrap
+
+  init(bootstrap: CompanionBootstrap) {
+    self.bootstrap = bootstrap
+  }
+
+  func start() {
+    guard process == nil else { return }
+    let proc = Process()
+    proc.executableURL = URL(fileURLWithPath: "/usr/bin/env")
+    var args: [String] = [
+      "flynn",
+      "companion",
+      "--url", bootstrap.gateway.url,
+      "--node-id", bootstrap.node.nodeId,
+      "--role", bootstrap.node.role,
+      "--platform", bootstrap.node.platform,
+      "--heartbeat", String(bootstrap.runtime.heartbeatSeconds),
+      "--handoff-timeout", String(bootstrap.runtime.handoffTimeoutMs),
+    ]
+    if let token = bootstrap.gateway.token, !token.isEmpty {
+      args += ["--token", token]
+    }
+    for capability in bootstrap.node.capabilities {
+      args += ["--capability", capability]
+    }
+    if !bootstrap.runtime.autoReconnect {
+      args.append("--once")
+    }
+    proc.arguments = args
+    proc.terminationHandler = { [weak self] p in
+      DispatchQueue.main.async {
+        self?.process = nil
+        self?.isRunning = false
+        if p.terminationStatus != 0 {
+          self?.lastError = "companion exited with status \(p.terminationStatus)"
+        }
+      }
+    }
+
+    do {
+      try proc.run()
+      process = proc
+      isRunning = true
+      lastError = nil
+    } catch {
+      lastError = error.localizedDescription
+      process = nil
+      isRunning = false
+    }
+  }
+
+  func stop() {
+    process?.terminate()
+    process = nil
+    isRunning = false
+  }
+
+  func runHandoff(message: String) {
+    guard !message.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else { return }
+    let proc = Process()
+    proc.executableURL = URL(fileURLWithPath: "/usr/bin/env")
+    var args: [String] = [
+      "flynn",
+      "companion",
+      "--once",
+      "--url", bootstrap.gateway.url,
+      "--node-id", bootstrap.node.nodeId,
+      "--role", bootstrap.node.role,
+      "--platform", bootstrap.node.platform,
+      "--handoff-timeout", String(bootstrap.runtime.handoffTimeoutMs),
+      "--handoff", message,
+    ]
+    if let token = bootstrap.gateway.token, !token.isEmpty {
+      args += ["--token", token]
+    }
+    proc.arguments = args
+    do {
+      try proc.run()
+    } catch {
+      lastError = "handoff failed: \(error.localizedDescription)"
+    }
+  }
+
+  var running: Bool { isRunning }
+}
+
+final class AppDelegate: NSObject, NSApplicationDelegate {
+  private var statusItem: NSStatusItem!
+  private var startItem: NSMenuItem!
+  private var stopItem: NSMenuItem!
+  private var handoffItem: NSMenuItem!
+  private var errorItem: NSMenuItem!
+  private var controller: CompanionProcessController!
+  private var refreshTimer: Timer?
+
+  func applicationDidFinishLaunching(_ notification: Notification) {
+    let bootstrap = Self.loadBootstrap()
+    controller = CompanionProcessController(bootstrap: bootstrap)
+    statusItem = NSStatusBar.system.statusItem(withLength: NSStatusItem.variableLength)
+    let menu = NSMenu()
+    startItem = NSMenuItem(title: "Start Companion", action: #selector(startCompanion), keyEquivalent: "s")
+    stopItem = NSMenuItem(title: "Stop Companion", action: #selector(stopCompanion), keyEquivalent: "x")
+    handoffItem = NSMenuItem(title: "Send Handoff...", action: #selector(sendHandoff), keyEquivalent: "h")
+    errorItem = NSMenuItem(title: "Last error: (none)", action: nil, keyEquivalent: "")
+    errorItem.isEnabled = false
+    menu.addItem(startItem)
+    menu.addItem(stopItem)
+    menu.addItem(handoffItem)
+    menu.addItem(NSMenuItem.separator())
+    menu.addItem(errorItem)
+    menu.addItem(NSMenuItem.separator())
+    menu.addItem(NSMenuItem(title: "Quit", action: #selector(quitApp), keyEquivalent: "q"))
+    startItem.target = self
+    stopItem.target = self
+    handoffItem.target = self
+    statusItem.menu = menu
+    refreshUI()
+    refreshTimer = Timer.scheduledTimer(withTimeInterval: 1.0, repeats: true) { [weak self] _ in
+      self?.refreshUI()
+    }
+  }
+
+  func applicationWillTerminate(_ notification: Notification) {
+    refreshTimer?.invalidate()
+    controller.stop()
+  }
+
+  @objc private func startCompanion() {
+    controller.start()
+    refreshUI()
+  }
+
+  @objc private func stopCompanion() {
+    controller.stop()
+    refreshUI()
+  }
+
+  @objc private func sendHandoff() {
+    let alert = NSAlert()
+    alert.messageText = "Companion Handoff"
+    alert.informativeText = "Send a one-shot handoff message through Flynn companion."
+    let input = NSTextField(frame: NSRect(x: 0, y: 0, width: 280, height: 24))
+    input.placeholderString = "message"
+    alert.accessoryView = input
+    alert.addButton(withTitle: "Send")
+    alert.addButton(withTitle: "Cancel")
+    let response = alert.runModal()
+    if response == .alertFirstButtonReturn {
+      controller.runHandoff(message: input.stringValue)
+      refreshUI()
+    }
+  }
+
+  @objc private func quitApp() {
+    NSApplication.shared.terminate(nil)
+  }
+
+  private func refreshUI() {
+    if controller.running {
+      statusItem.button?.title = "F*"
+      startItem.isEnabled = false
+      stopItem.isEnabled = true
+    } else {
+      statusItem.button?.title = controller.lastError == nil ? "F" : "F!"
+      startItem.isEnabled = true
+      stopItem.isEnabled = false
+    }
+    let errorText = controller.lastError ?? "(none)"
+    errorItem.title = "Last error: \(errorText)"
+  }
+
+  static func loadBootstrap() -> CompanionBootstrap {
+    guard let url = Bundle.module.url(forResource: "companion.bootstrap", withExtension: "json"),
+          let data = try? Data(contentsOf: url),
+          let decoded = try? JSONDecoder().decode(CompanionBootstrap.self, from: data)
+    else {
+      fatalError("Failed to load companion.bootstrap.json resource")
+    }
+    return decoded
+  }
+}
+
+let app = NSApplication.shared
+let delegate = AppDelegate()
+app.setActivationPolicy(.accessory)
+app.delegate = delegate
+app.run()
@@ -1,6 +1,6 @@
 {
  "schemaVersion": 1,
-  "generatedAt": "2026-02-27T03:35:54.245Z",
+  "generatedAt": "2026-02-27T04:50:38.373Z",
  "gateway": {
    "url": "ws://127.0.0.1:18800"
  },
@@ -1867,5 +1867,6 @@ For more implementation details, see:
 - Companion release bundle verifier: `src/companion/releaseVerify.ts` (validates `CHECKSUMS.sha256` and optional signature metadata against a provided public key)
 - Companion release automation pipeline: `src/companion/releasePipeline.ts` + `scripts/build-companion-release-bundle.ts` (build-and-verify workflow for deterministic companion artifact generation)
 - Companion shell template helper: `src/companion/shellTemplate.ts` (writes platform-native starter template files for `macos`, `ios`, and `android` shell scaffolding)
- Companion reference app exporter: `src/companion/referenceApps.ts` + `scripts/export-companion-reference-apps.ts` (regenerates in-repo platform starter app directories)
+- Companion macOS menu-bar app scaffold helper: `src/companion/macosMenuBarApp.ts` (writes runnable Swift Package menu-bar app starter surface)
+- Companion reference app exporter: `src/companion/referenceApps.ts` + `scripts/export-companion-reference-apps.ts` (regenerates in-repo platform starter app directories, including `apps/companion/macos-app`)
 - CI artifact workflow: `.github/workflows/companion-release-bundle.yml` (manual dispatch bundle build/verify/upload pipeline)
@@ -161,7 +161,7 @@ Gateway streaming UX signals:
 - `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.
 - `pnpm companion:bundle -- --output <dir> ...` runs a build-and-verify release pipeline for repeatable companion artifact generation.
- `pnpm companion:reference-apps -- --output apps/companion` regenerates in-repo macOS/iOS/Android reference app starter surfaces.
+- `pnpm companion:reference-apps -- --output apps/companion` regenerates in-repo macOS/iOS/Android reference app starter surfaces plus a runnable `macos-app` Swift Package menu-bar scaffold.
 - `.github/workflows/companion-release-bundle.yml` provides CI artifact generation for companion release bundles using the same build-and-verify pipeline.
 - `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.
@@ -27,7 +27,7 @@ If you only want the protocol surface, see `docs/api/PROTOCOL.md`.
 - Companion release bundles can be verified before install via `flynn companion --verify-release-bundle <dir>` with optional signature-key checks.
 - Companion packaging automation is available via `pnpm companion:bundle -- --output <dir> ...`, which builds and verifies the release bundle in one pass.
 - Companion platform starter scaffolds can be generated via `flynn companion --export-shell-template <dir>` for macOS/iOS/Android reference app bootstrapping.
- Companion reference app directories can be regenerated via `pnpm companion:reference-apps -- --output apps/companion` for repo-shipped starter surfaces.
+- Companion reference app directories can be regenerated via `pnpm companion:reference-apps -- --output apps/companion` for repo-shipped starter surfaces, including a runnable `macos-app` Swift Package menu-bar scaffold.
 - CI workflow `.github/workflows/companion-release-bundle.yml` mirrors this pipeline for manual artifact generation/upload.
 - 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.
@@ -55,6 +55,8 @@ Reference app starters can be regenerated in-repo with:
 pnpm companion:reference-apps -- --output ./apps/companion
 ```

+This also regenerates `apps/companion/macos-app`, a runnable Swift Package menu-bar reference app scaffold.
+
 CI automation:

 - `.github/workflows/companion-release-bundle.yml` provides a manual-dispatch workflow that generates an ephemeral signing key, builds/verifies a bundle with `pnpm companion:bundle`, and uploads artifacts.
@@ -6,7 +6,7 @@ Scope: ship the remaining product-layer capabilities that make Flynn feel like a

 ## Rebaseline (What Is Already Done)

-Completion update (2026-02-27): all roadmap phases are now implemented, including companion app-surface packaging outputs (bootstrap export, signed/verified release bundles, reference app starter surfaces, and CI artifact workflow), voice reliability, browser workflow reliability, and onboarding first-success improvements.
+Completion update (2026-02-27): all roadmap phases are now implemented, including companion app-surface packaging outputs (bootstrap export, signed/verified release bundles, reference app starter surfaces including a runnable macOS menu-bar Swift Package scaffold, and CI artifact workflow), voice reliability, browser workflow reliability, and onboarding first-success improvements.

 The following were previously treated as gaps but are already implemented in Flynn:

@@ -51,7 +51,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` + `RELEASE_MANIFEST.json`, optional `CHECKSUMS.sha256.sig` with `--signing-key`), `flynn companion --verify-release-bundle <dir>` now validates checksum/signature artifacts before install, `pnpm companion:bundle -- --output <dir> ...` now provides one-pass build-and-verify automation, `.github/workflows/companion-release-bundle.yml` provides CI artifact build/verify/upload, `flynn companion --export-shell-template <dir>` now emits macOS/iOS/Android starter shell templates, `pnpm companion:reference-apps` now regenerates in-repo macOS/iOS/Android reference app starter directories, 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` + `RELEASE_MANIFEST.json`, optional `CHECKSUMS.sha256.sig` with `--signing-key`), `flynn companion --verify-release-bundle <dir>` now validates checksum/signature artifacts before install, `pnpm companion:bundle -- --output <dir> ...` now provides one-pass build-and-verify automation, `.github/workflows/companion-release-bundle.yml` provides CI artifact build/verify/upload, `flynn companion --export-shell-template <dir>` now emits macOS/iOS/Android starter shell templates, `pnpm companion:reference-apps` now regenerates in-repo macOS/iOS/Android reference app starter directories plus `apps/companion/macos-app` runnable menu-bar scaffold, 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

@@ -7117,10 +7117,12 @@
      "status": "completed",
      "date": "2026-02-27",
      "updated": "2026-02-27",
-      "summary": "Added repo-shipped companion reference app surfaces for macOS/iOS/Android. New `generateReferenceCompanionApps()` helper and `pnpm companion:reference-apps` script deterministically regenerate `apps/companion/*` starter directories from typed bootstrap contracts.",
+      "summary": "Added repo-shipped companion reference app surfaces for macOS/iOS/Android and a runnable macOS menu-bar Swift Package scaffold (`apps/companion/macos-app`). `generateReferenceCompanionApps()` and `pnpm companion:reference-apps` regenerate these starter directories from typed bootstrap contracts.",
      "files_modified": [
        "src/companion/referenceApps.ts",
        "src/companion/referenceApps.test.ts",
+        "src/companion/macosMenuBarApp.ts",
+        "src/companion/macosMenuBarApp.test.ts",
        "src/companion/index.ts",
        "scripts/export-companion-reference-apps.ts",
        "package.json",
@@ -7128,6 +7130,9 @@
        "apps/companion/macos/MenuBarCompanion.swift",
        "apps/companion/macos/README.md",
        "apps/companion/macos/companion.bootstrap.json",
+        "apps/companion/macos-app/Package.swift",
+        "apps/companion/macos-app/README.md",
+        "apps/companion/macos-app/Sources/FlynnCompanionMenuBar/main.swift",
        "apps/companion/ios/CompanionBootstrap.swift",
        "apps/companion/ios/README.md",
        "apps/companion/ios/companion.bootstrap.json",
@@ -7142,7 +7147,7 @@
        "docs/plans/2026-02-26-personal-assistant-productization-plan.md",
        "docs/plans/state.json"
      ],
-      "test_status": "pnpm test:run src/companion/referenceApps.test.ts src/companion/shellTemplate.test.ts + pnpm typecheck passing"
+      "test_status": "pnpm test:run src/companion/macosMenuBarApp.test.ts src/companion/referenceApps.test.ts src/companion/shellTemplate.test.ts + pnpm typecheck passing"
    },
    "personal-assistant-productization-phase1-companion-release-manifest-artifact": {
      "status": "completed",
@@ -7208,7 +7213,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 finalized 2026-02-27 — channel breadth, setup wizard, browser workflow reliability primitives (wait/assert/extract/retries/checkpoints/guardrails/budgets), companion reconnect/runtime-handoff foundations, companion packaging/distribution primitives (bootstrap export + release-bundle artifacts + checksum manifests + release manifest artifact + optional signatures + verification mode + checksum-gated launcher + one-pass build/verify automation + CI workflow), repo-shipped macOS/iOS/Android reference app starter surfaces, 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.",
+    "feature_gap_scorecard": "rebaselined 2026-02-26 and finalized 2026-02-27 — channel breadth, setup wizard, browser workflow reliability primitives (wait/assert/extract/retries/checkpoints/guardrails/budgets), companion reconnect/runtime-handoff foundations, companion packaging/distribution primitives (bootstrap export + release-bundle artifacts + checksum manifests + release manifest artifact + optional signatures + verification mode + checksum-gated launcher + one-pass build/verify automation + CI workflow), repo-shipped macOS/iOS/Android reference app starter surfaces plus runnable macOS menu-bar Swift Package scaffold (`apps/companion/macos-app`), 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.",
    "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",
@@ -26,6 +26,7 @@ async function main(): Promise<void> {
  for (const entry of result.generated) {
    console.log(`- ${entry.platform}: ${entry.outputDir}`);
  }
+  console.log(`- macos-app: ${result.macosMenuBarAppDir}`);
  console.log(`- readme: ${result.readmePath}`);
 }

@@ -15,6 +15,7 @@ export { writeCompanionShellTemplate } from './shellTemplate.js';
 export { verifyCompanionReleaseBundle } from './releaseVerify.js';
 export { buildAndVerifyCompanionReleaseBundle } from './releasePipeline.js';
 export { generateReferenceCompanionApps } from './referenceApps.js';
+export { generateMacOSMenuBarApp } from './macosMenuBarApp.js';

 export type {
  CompanionRuntimeClientOptions,
@@ -104,3 +105,7 @@ export type {
  GenerateReferenceCompanionAppsResult,
  GeneratedReferenceCompanionApp,
 } from './referenceApps.js';
+export type {
+  GenerateMacOSMenuBarAppInput,
+  GenerateMacOSMenuBarAppResult,
+} from './macosMenuBarApp.js';
@@ -0,0 +1,50 @@
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { describe, expect, it } from 'vitest';
+import { generateMacOSMenuBarApp } from './macosMenuBarApp.js';
+
+describe('generateMacOSMenuBarApp', () => {
+  it('writes a runnable Swift package scaffold for menu bar companion', async () => {
+    const tempDir = await mkdtemp(join(tmpdir(), 'flynn-macos-menubar-app-'));
+    const outputDir = join(tempDir, 'macos-app');
+    const result = await generateMacOSMenuBarApp({
+      outputDir,
+      manifest: {
+        schemaVersion: 1,
+        generatedAt: '2026-02-27T00:00:00.000Z',
+        gateway: { url: 'ws://127.0.0.1:18800' },
+        node: {
+          nodeId: 'macos-menu-node',
+          role: 'companion',
+          platform: 'macos',
+          capabilities: ['ui.canvas'],
+        },
+        runtime: {
+          heartbeatSeconds: 30,
+          handoffTimeoutMs: 120000,
+          autoReconnect: true,
+        },
+      },
+    });
+
+    const packageSwift = await readFile(`${outputDir}/Package.swift`, 'utf8');
+    const mainSwift = await readFile(`${outputDir}/Sources/FlynnCompanionMenuBar/main.swift`, 'utf8');
+    const bootstrap = await readFile(`${outputDir}/Sources/FlynnCompanionMenuBar/Resources/companion.bootstrap.json`, 'utf8');
+    const readme = await readFile(`${outputDir}/README.md`, 'utf8');
+
+    expect(result.files).toEqual([
+      `${outputDir}/Package.swift`,
+      `${outputDir}/Sources/FlynnCompanionMenuBar/main.swift`,
+      `${outputDir}/Sources/FlynnCompanionMenuBar/Resources/companion.bootstrap.json`,
+      `${outputDir}/README.md`,
+    ]);
+    expect(packageSwift).toContain('FlynnCompanionMenuBar');
+    expect(mainSwift).toContain('NSStatusBar.system.statusItem');
+    expect(mainSwift).toContain('flynn');
+    expect(JSON.parse(bootstrap)).toMatchObject({ node: { nodeId: 'macos-menu-node' } });
+    expect(readme).toContain('menu bar companion');
+
+    await rm(tempDir, { recursive: true, force: true });
+  });
+});
@@ -0,0 +1,304 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import type { CompanionBootstrapManifest } from './bootstrapManifest.js';
+
+export interface GenerateMacOSMenuBarAppInput {
+  outputDir: string;
+  manifest: CompanionBootstrapManifest;
+}
+
+export interface GenerateMacOSMenuBarAppResult {
+  outputDir: string;
+  files: string[];
+}
+
+function packageSwift(): string {
+  return `// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+  name: "FlynnCompanionMenuBar",
+  platforms: [
+    .macOS(.v13)
+  ],
+  products: [
+    .executable(name: "FlynnCompanionMenuBar", targets: ["FlynnCompanionMenuBar"])
+  ],
+  targets: [
+    .executableTarget(
+      name: "FlynnCompanionMenuBar",
+      resources: [.copy("Resources/companion.bootstrap.json")]
+    )
+  ]
+)
+`;
+}
+
+function readmeBody(): string {
+  return `# Flynn macOS Companion Menu Bar App (Reference MVP)
+
+This is a runnable Swift Package reference app that creates a macOS menu bar companion controller.
+
+## Capabilities
+
+- Loads companion.bootstrap.json from package resources.
+- Starts/stops flynn companion as a child process from menu actions.
+- Runs one-shot handoff prompts (flynn companion --once --handoff ...).
+- Shows process state in the menu bar title (F, F* running, F! error).
+
+## Build + Run
+
+Run:
+cd <this-directory>
+swift run FlynnCompanionMenuBar
+
+Prerequisites:
+
+- macOS with Swift toolchain.
+- flynn executable available in PATH.
+`;
+}
+
+function mainSwift(manifest: CompanionBootstrapManifest): string {
+  return `import AppKit
+import Foundation
+
+struct CompanionBootstrap: Codable {
+  struct Gateway: Codable {
+    let url: String
+    let token: String?
+  }
+  struct Node: Codable {
+    let nodeId: String
+    let role: String
+    let platform: String
+    let capabilities: [String]
+  }
+  struct Runtime: Codable {
+    let heartbeatSeconds: Int
+    let handoffTimeoutMs: Int
+    let autoReconnect: Bool
+  }
+  let schemaVersion: Int
+  let generatedAt: String
+  let gateway: Gateway
+  let node: Node
+  let runtime: Runtime
+}
+
+final class CompanionProcessController {
+  private var process: Process?
+  private var isRunning = false
+  private(set) var lastError: String?
+  private let bootstrap: CompanionBootstrap
+
+  init(bootstrap: CompanionBootstrap) {
+    self.bootstrap = bootstrap
+  }
+
+  func start() {
+    guard process == nil else { return }
+    let proc = Process()
+    proc.executableURL = URL(fileURLWithPath: "/usr/bin/env")
+    var args: [String] = [
+      "flynn",
+      "companion",
+      "--url", bootstrap.gateway.url,
+      "--node-id", bootstrap.node.nodeId,
+      "--role", bootstrap.node.role,
+      "--platform", bootstrap.node.platform,
+      "--heartbeat", String(bootstrap.runtime.heartbeatSeconds),
+      "--handoff-timeout", String(bootstrap.runtime.handoffTimeoutMs),
+    ]
+    if let token = bootstrap.gateway.token, !token.isEmpty {
+      args += ["--token", token]
+    }
+    for capability in bootstrap.node.capabilities {
+      args += ["--capability", capability]
+    }
+    if !bootstrap.runtime.autoReconnect {
+      args.append("--once")
+    }
+    proc.arguments = args
+    proc.terminationHandler = { [weak self] p in
+      DispatchQueue.main.async {
+        self?.process = nil
+        self?.isRunning = false
+        if p.terminationStatus != 0 {
+          self?.lastError = "companion exited with status \\(p.terminationStatus)"
+        }
+      }
+    }
+
+    do {
+      try proc.run()
+      process = proc
+      isRunning = true
+      lastError = nil
+    } catch {
+      lastError = error.localizedDescription
+      process = nil
+      isRunning = false
+    }
+  }
+
+  func stop() {
+    process?.terminate()
+    process = nil
+    isRunning = false
+  }
+
+  func runHandoff(message: String) {
+    guard !message.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else { return }
+    let proc = Process()
+    proc.executableURL = URL(fileURLWithPath: "/usr/bin/env")
+    var args: [String] = [
+      "flynn",
+      "companion",
+      "--once",
+      "--url", bootstrap.gateway.url,
+      "--node-id", bootstrap.node.nodeId,
+      "--role", bootstrap.node.role,
+      "--platform", bootstrap.node.platform,
+      "--handoff-timeout", String(bootstrap.runtime.handoffTimeoutMs),
+      "--handoff", message,
+    ]
+    if let token = bootstrap.gateway.token, !token.isEmpty {
+      args += ["--token", token]
+    }
+    proc.arguments = args
+    do {
+      try proc.run()
+    } catch {
+      lastError = "handoff failed: \\(error.localizedDescription)"
+    }
+  }
+
+  var running: Bool { isRunning }
+}
+
+final class AppDelegate: NSObject, NSApplicationDelegate {
+  private var statusItem: NSStatusItem!
+  private var startItem: NSMenuItem!
+  private var stopItem: NSMenuItem!
+  private var handoffItem: NSMenuItem!
+  private var errorItem: NSMenuItem!
+  private var controller: CompanionProcessController!
+  private var refreshTimer: Timer?
+
+  func applicationDidFinishLaunching(_ notification: Notification) {
+    let bootstrap = Self.loadBootstrap()
+    controller = CompanionProcessController(bootstrap: bootstrap)
+    statusItem = NSStatusBar.system.statusItem(withLength: NSStatusItem.variableLength)
+    let menu = NSMenu()
+    startItem = NSMenuItem(title: "Start Companion", action: #selector(startCompanion), keyEquivalent: "s")
+    stopItem = NSMenuItem(title: "Stop Companion", action: #selector(stopCompanion), keyEquivalent: "x")
+    handoffItem = NSMenuItem(title: "Send Handoff...", action: #selector(sendHandoff), keyEquivalent: "h")
+    errorItem = NSMenuItem(title: "Last error: (none)", action: nil, keyEquivalent: "")
+    errorItem.isEnabled = false
+    menu.addItem(startItem)
+    menu.addItem(stopItem)
+    menu.addItem(handoffItem)
+    menu.addItem(NSMenuItem.separator())
+    menu.addItem(errorItem)
+    menu.addItem(NSMenuItem.separator())
+    menu.addItem(NSMenuItem(title: "Quit", action: #selector(quitApp), keyEquivalent: "q"))
+    startItem.target = self
+    stopItem.target = self
+    handoffItem.target = self
+    statusItem.menu = menu
+    refreshUI()
+    refreshTimer = Timer.scheduledTimer(withTimeInterval: 1.0, repeats: true) { [weak self] _ in
+      self?.refreshUI()
+    }
+  }
+
+  func applicationWillTerminate(_ notification: Notification) {
+    refreshTimer?.invalidate()
+    controller.stop()
+  }
+
+  @objc private func startCompanion() {
+    controller.start()
+    refreshUI()
+  }
+
+  @objc private func stopCompanion() {
+    controller.stop()
+    refreshUI()
+  }
+
+  @objc private func sendHandoff() {
+    let alert = NSAlert()
+    alert.messageText = "Companion Handoff"
+    alert.informativeText = "Send a one-shot handoff message through Flynn companion."
+    let input = NSTextField(frame: NSRect(x: 0, y: 0, width: 280, height: 24))
+    input.placeholderString = "message"
+    alert.accessoryView = input
+    alert.addButton(withTitle: "Send")
+    alert.addButton(withTitle: "Cancel")
+    let response = alert.runModal()
+    if response == .alertFirstButtonReturn {
+      controller.runHandoff(message: input.stringValue)
+      refreshUI()
+    }
+  }
+
+  @objc private func quitApp() {
+    NSApplication.shared.terminate(nil)
+  }
+
+  private func refreshUI() {
+    if controller.running {
+      statusItem.button?.title = "F*"
+      startItem.isEnabled = false
+      stopItem.isEnabled = true
+    } else {
+      statusItem.button?.title = controller.lastError == nil ? "F" : "F!"
+      startItem.isEnabled = true
+      stopItem.isEnabled = false
+    }
+    let errorText = controller.lastError ?? "(none)"
+    errorItem.title = "Last error: \\(errorText)"
+  }
+
+  static func loadBootstrap() -> CompanionBootstrap {
+    guard let url = Bundle.module.url(forResource: "companion.bootstrap", withExtension: "json"),
+          let data = try? Data(contentsOf: url),
+          let decoded = try? JSONDecoder().decode(CompanionBootstrap.self, from: data)
+    else {
+      fatalError("Failed to load companion.bootstrap.json resource")
+    }
+    return decoded
+  }
+}
+
+let app = NSApplication.shared
+let delegate = AppDelegate()
+app.setActivationPolicy(.accessory)
+app.delegate = delegate
+app.run()
+`;
+}
+
+export async function generateMacOSMenuBarApp(
+  input: GenerateMacOSMenuBarAppInput,
+): Promise<GenerateMacOSMenuBarAppResult> {
+  const packagePath = `${input.outputDir}/Package.swift`;
+  const sourceDir = `${input.outputDir}/Sources/FlynnCompanionMenuBar`;
+  const sourcePath = `${sourceDir}/main.swift`;
+  const resourcesDir = `${sourceDir}/Resources`;
+  const resourceBootstrapPath = `${resourcesDir}/companion.bootstrap.json`;
+  const readmePath = `${input.outputDir}/README.md`;
+
+  await mkdir(sourceDir, { recursive: true });
+  await mkdir(resourcesDir, { recursive: true });
+  await writeFile(packagePath, packageSwift(), 'utf8');
+  await writeFile(sourcePath, mainSwift(input.manifest), 'utf8');
+  await writeFile(resourceBootstrapPath, `${JSON.stringify(input.manifest, null, 2)}\n`, 'utf8');
+  await writeFile(readmePath, readmeBody(), 'utf8');
+
+  return {
+    outputDir: input.outputDir,
+    files: [packagePath, sourcePath, resourceBootstrapPath, readmePath],
+  };
+}
@@ -16,14 +16,18 @@ describe('generateReferenceCompanionApps', () => {

    expect(result.generated.map((entry) => entry.platform)).toEqual(['macos', 'ios', 'android']);
    const macosTemplate = await readFile(`${outputDir}/macos/MenuBarCompanion.swift`, 'utf8');
+    const macosAppMain = await readFile(`${outputDir}/macos-app/Sources/FlynnCompanionMenuBar/main.swift`, 'utf8');
    const iosTemplate = await readFile(`${outputDir}/ios/CompanionBootstrap.swift`, 'utf8');
    const androidTemplate = await readFile(`${outputDir}/android/CompanionBootstrap.kt`, 'utf8');
    const rootReadme = await readFile(`${outputDir}/README.md`, 'utf8');

    expect(macosTemplate).toContain('launchFlynnCompanion');
+    expect(macosAppMain).toContain('NSStatusBar.system.statusItem');
    expect(iosTemplate).toContain('CompanionBootstrap');
    expect(androidTemplate).toContain('data class CompanionBootstrap');
    expect(rootReadme).toContain('Companion Reference Apps');
+    expect(result.macosMenuBarAppDir).toBe(`${outputDir}/macos-app`);
+    expect(result.macosMenuBarAppFiles.length).toBeGreaterThan(0);

    await rm(tempDir, { recursive: true, force: true });
  });
@@ -1,6 +1,7 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { writeCompanionShellTemplate } from './shellTemplate.js';
 import type { CompanionBootstrapPlatform } from './bootstrapManifest.js';
+import { generateMacOSMenuBarApp } from './macosMenuBarApp.js';

 export interface GenerateReferenceCompanionAppsInput {
  outputDir: string;
@@ -17,6 +18,8 @@ export interface GeneratedReferenceCompanionApp {
 export interface GenerateReferenceCompanionAppsResult {
  rootDir: string;
  generated: GeneratedReferenceCompanionApp[];
+  macosMenuBarAppDir: string;
+  macosMenuBarAppFiles: string[];
  readmePath: string;
 }

@@ -33,6 +36,7 @@ function rootReadmeBody(): string {
 This directory contains generated companion starter shells for:

 - macOS menu-bar style wrapper
+- macOS runnable menu-bar app scaffold (Swift Package)
 - iOS shell
 - Android shell

@@ -76,11 +80,35 @@ export async function generateReferenceCompanionApps(
      files: result.files,
    });
  }
+  const macosManifest = {
+    schemaVersion: 1 as const,
+    generatedAt: generatedAt.toISOString(),
+    gateway: {
+      url: input.gatewayUrl,
+    },
+    node: {
+      nodeId: 'macos-menu-bar-reference',
+      role: 'companion',
+      platform: 'macos' as const,
+      capabilities: defaultCapabilities('macos'),
+    },
+    runtime: {
+      heartbeatSeconds: 30,
+      handoffTimeoutMs: 120000,
+      autoReconnect: true,
+    },
+  };
+  const macosMenuBar = await generateMacOSMenuBarApp({
+    outputDir: `${input.outputDir}/macos-app`,
+    manifest: macosManifest,
+  });
  const readmePath = `${input.outputDir}/README.md`;
  await writeFile(readmePath, rootReadmeBody(), 'utf8');
  return {
    rootDir: input.outputDir,
    generated,
+    macosMenuBarAppDir: macosMenuBar.outputDir,
+    macosMenuBarAppFiles: macosMenuBar.files,
    readmePath,
  };
 }