Release Oída-informed Germ cultivation

Author: emeisazam

.env.example

@@ -1,7 +1,7 @@
 # Local server. GERM_* is preferred; GERMINATOR_* remains supported as a legacy
 # fallback for old shells and launchers.
 GERM_HOST=127.0.0.1
-GERM_PORT=8765
+GERM_PORT=5178
 GERM_ACTIVE_PROVIDER=mock
 GERM_OUTPUT_DIR=output
 
@@ -49,12 +49,15 @@ GERM_LISTENER_MAX_DURATION_SECONDS=600
 HF_TOKEN=
 HUGGINGFACE_HUB_TOKEN=
 
-# Future Stability API provider. Not required for local generation.
+# Optional hosted Stable Audio 3 provider. Local providers do not require this key.
 STABILITY_API_KEY=
+GERM_STABILITY_API_URL=https://api.stability.ai
+GERM_STABILITY_POLL_SECONDS=10
 
-# Optional local listener fallback.
-OLLAMA_BASE_URL=http://127.0.0.1:11434
-OLLAMA_MODEL=llama3.2
+# Oída owns machine listening and audio understanding. Germ uses this bridge only
+# when "Re-listen with Oída" is requested.
+GERM_OIDA_URL=http://127.0.0.1:8765
+GERM_OIDA_TIMEOUT_SECONDS=1800
 
 # Dev conveniences read by the launch scripts (not by the server itself):
 # GERM_RELOAD=1 makes launch_germ.command start uvicorn with --reload.

.gitignore

@@ -36,6 +36,8 @@ output/sessions/
 
 apps/macos/.build/
 apps/macos/dist/
+apps/germ.app/
+.codex/
 
 /*.png
 /*.jpg

NOTICE

@@ -18,5 +18,5 @@ stable-audio-3 @ git+https://github.com/Stability-AI/stable-audio-3.git
 That dependency is not vendored in this repository. Install it only if your use
 case and environment are compatible with the upstream project and model terms.
 
-Earworm integration surfaces map germ metadata into Earworm 0.1 protocol-shaped
+Earworm integration surfaces map germ metadata into Earworm 0.4-compatible
 sessions for local provenance, consent, retention, and lineage workflows.

README.md

@@ -18,7 +18,7 @@ exploration tool for working with Stable Audio 3 workflows.
 ## Stable Audio 3 Focus
 
 The app exposes a local FastAPI server, a browser dashboard, generated WAV files,
-metadata JSON, and provider switching across mock, Python, MLX, and future API
+metadata JSON, and provider switching across mock, Python, MLX, and Stability API
 routes. It keeps technical Stable Audio controls visible while adding a germ workflow
 layer for sound matter, micro modules, culture, strain, mutation, pruning,
 propagation, listening, curation, and harvest.
@@ -48,9 +48,11 @@ Official Stable Audio references:
   incubated evolution.
 - Control layer for audio-to-control, safe OSC, MIDI intent, CV-safe exports, and
   control ancestry, including the norns/Fates OSC bridge.
-- Listener prompt enhancement and heuristic scoring through `/listener/enhance`
-  and `/listener/score`, with optional local Ollama fallback.
-- Earworm 0.1 export of generated metadata into local context-chain sessions.
+- Neutral, editable prompt compilation through `/listener/enhance`, local DSP-only
+  signal checks through `/listener/score`, and explicit re-listening through oída at
+  `/listener/relisten`. Machine listening and audio understanding stay in oída.
+- Earworm 0.4-compatible export of generated metadata into local context-chain
+  sessions, plus Akousma spec v1.3 lineage, kinship, and covenant-aware handoffs.
 - Shared audio player with waveform drawing, metadata preview, path copy, open, and
   Finder reveal.
 - Diagnostics for provider readiness and Hugging Face access.
@@ -112,6 +114,9 @@ Native macOS app (embeds the same dashboard, supervises the same daemon):
 apps/macos/script/build_and_run.sh
 ```
 
+The build stages the runnable bundle at `apps/germ.app`. To build it without
+launching it, use `apps/macos/script/build_and_run.sh --build-only`.
+
 Tailscale launch for another device in the same tailnet:
 
 ```bash
@@ -170,10 +175,13 @@ GERM_MAX_IMAGE_MB=8
 GERM_ENABLE_CLOUD_VISION=0
 GERM_LISTENER_MAX_AUDIO_MB=50
 GERM_LISTENER_MAX_DURATION_SECONDS=600
+STABILITY_API_KEY=        # optional: hosted Stable Audio 3
+GERM_STABILITY_API_URL=https://api.stability.ai
+GERM_STABILITY_POLL_SECONDS=10
+GERM_OIDA_URL=http://127.0.0.1:8765
+GERM_OIDA_TIMEOUT_SECONDS=1800
 GERM_RELOAD=1            # launch_germ.command only: start uvicorn with --reload
 GERM_TAILSCALE_IP=...    # scripts/run_tailscale.sh only: override the auto-detected IP
-OLLAMA_BASE_URL=http://127.0.0.1:11434
-OLLAMA_MODEL=llama3.2
 ```
 
 The older `GERMINATOR_*` names are still accepted as fallbacks for compatibility.
@@ -240,8 +248,8 @@ request is recorded, but a render already inside the model call may finish norma
 - Propagation: continuation workflow for loops, tails, beds, and textures.
 - Strains: creative LoRA palette and Culture Mix scaffold.
 - Herbarium: archive view over saved outputs.
-- Listener: prompt enhancer, heuristic scorer, repair proposals, and optional
-  local Ollama prompt enhancement with no mandatory cloud key.
+- Listener: a neutral prompt compiler, local signal checks, repair proposals, and
+  the oída re-listening bridge. **Oída hears. germ cultivates.**
 - Lab: placeholders for SAME latents, dataset prep, model comparison, benchmarks,
   and agent experiments.
 
@@ -268,10 +276,10 @@ sections.
 
 ## Listener
 
-Listener can enhance a rough idea into a Stable Audio prompt, merge a negative
-prompt, score WAV files with bounded local DSP features, propose loop-seam repair
-ranges, and fall back to local Ollama when available. It does not require a cloud
-LLM API for the app to run.
+Listener normalizes a rough idea without injecting a modality, scores WAV files with
+bounded local DSP features, and proposes measured loop-seam repairs. Re-listening and
+prompt derivation are delegated to oída; germ does not embed a listening or
+audio-understanding model and requires no general-purpose LLM API.
 
 ## API
 
@@ -299,6 +307,7 @@ POST /lora/strength
 GET  /listener/providers
 POST /listener/enhance
 POST /listener/score
+POST /listener/relisten
 GET  /strains
 POST /strains
 GET  /strains/{strain_id}
@@ -336,7 +345,7 @@ curl -X POST http://127.0.0.1:5178/generate \
   -d '{
     "provider": "mock",
     "model": "mock-sine",
-    "prompt": "TrackType: SFX, dry close-microphone loop of metallic friction",
+    "prompt": "dry close-microphone loop of metallic friction",
     "negative_prompt": "speech, vocals, melody, long reverb",
     "duration": 3.0,
     "steps": 8,
@@ -378,8 +387,8 @@ Generated metadata keeps existing compatibility fields and adds germ identity fi
 
 Each generated metadata record also includes an `earworm` block with deterministic
 session, asset, and provenance IDs. Use `POST /earworm/export` to write a local
-Earworm 0.1 session JSON from a metadata path. The cross-stack fixture lives at
-`tests/fixtures/germ-organism-mapping.session.json`.
+Earworm context-session JSON from a metadata path. The export shape remains
+compatible with Earworm's current v0.4 session schema contract.
 
 ## Development Notes
 

apps/README.md

@@ -0,0 +1,10 @@
+# Apps
+
+- `macos/` contains the SwiftPM source for the native germ shell.
+- `germ.app` is the generated runnable macOS bundle. Create or refresh it with
+  `macos/script/build_and_run.sh --build-only`; it stays out of git because it
+  contains machine-specific build output.
+
+The native shell renders the daemon's `/dashboard` route in a `WKWebView`, so
+it uses the same HTML, CSS, JavaScript, backend state, and saved sessions as the
+browser version.

apps/macos/Sources/GermMacOS/App/AppDelegate.swift

@@ -1,8 +1,26 @@
 import AppKit
+import Darwin
 
 final class AppDelegate: NSObject, NSApplicationDelegate {
+    private var terminationSignalSources: [DispatchSourceSignal] = []
+
     func applicationDidFinishLaunching(_ notification: Notification) {
+        installGracefulTerminationHandler(for: SIGTERM)
+        installGracefulTerminationHandler(for: SIGINT)
         NSApp.setActivationPolicy(.regular)
         NSApp.activate(ignoringOtherApps: true)
     }
+
+    /// Route shell/build-script termination through AppKit so
+    /// `willTerminateNotification` runs and the app can stop only the daemon
+    /// process it owns before exiting.
+    private func installGracefulTerminationHandler(for signalNumber: Int32) {
+        Darwin.signal(signalNumber, SIG_IGN)
+        let source = DispatchSource.makeSignalSource(signal: signalNumber, queue: .main)
+        source.setEventHandler {
+            NSApp.terminate(nil)
+        }
+        source.resume()
+        terminationSignalSources.append(source)
+    }
 }

apps/macos/Sources/GermMacOS/App/GermMacOSApp.swift

@@ -11,10 +11,12 @@ struct GermMacOSApp: App {
             ContentView()
                 .environmentObject(store)
                 .frame(minWidth: 980, minHeight: 640)
+                .ignoresSafeArea(.container, edges: .top)
                 .task {
                     await store.bootstrap()
                 }
         }
+        .windowStyle(.hiddenTitleBar)
         .commands {
             CommandMenu("germ") {
                 Button("Open Dashboard in Browser") {

apps/macos/Sources/GermMacOS/Services/DaemonSupervisor.swift

@@ -41,20 +41,43 @@ final class DaemonSupervisor {
             throw DaemonSupervisorError.repositoryRootNotFound
         }
 
+        let helper = root
+            .appendingPathComponent("apps", isDirectory: true)
+            .appendingPathComponent("macos", isDirectory: true)
+            .appendingPathComponent("script", isDirectory: true)
+            .appendingPathComponent("managed_daemon.py", isDirectory: false)
+        guard FileManager.default.isReadableFile(atPath: helper.path) else {
+            throw DaemonSupervisorError.launchFailed("Missing \(helper.path)")
+        }
+
         let outputPipe = Pipe()
         let errorPipe = Pipe()
         let proc = Process()
-        proc.executableURL = URL(fileURLWithPath: "/usr/bin/env")
-        proc.arguments = [
-            "uv",
-            "run",
-            "uvicorn",
+        let helperArguments = [
+            "-u",
+            helper.path,
+            "--parent-pid",
+            "\(ProcessInfo.processInfo.processIdentifier)",
             "server.main:app",
             "--host",
             host,
             "--port",
             "\(port)"
         ]
+        let venvPython = root
+            .appendingPathComponent(".venv", isDirectory: true)
+            .appendingPathComponent("bin", isDirectory: true)
+            .appendingPathComponent("python3", isDirectory: false)
+        if FileManager.default.isExecutableFile(atPath: venvPython.path) {
+            proc.executableURL = venvPython
+            proc.arguments = helperArguments
+        } else {
+            // Bootstrap through uv only when no synced environment exists. The
+            // helper still watches the app PID and tears down its whole
+            // uvicorn process group if the app disappears.
+            proc.executableURL = URL(fileURLWithPath: "/usr/bin/env")
+            proc.arguments = ["uv", "run", "--frozen", "python"] + helperArguments
+        }
         proc.currentDirectoryURL = root
         proc.standardOutput = outputPipe
         proc.standardError = errorPipe

apps/macos/Sources/GermMacOS/Services/LaunchAtLoginManager.swift

@@ -2,23 +2,43 @@ import Foundation
 import ServiceManagement
 
 enum LaunchAtLoginManager {
+    private static var status: SMAppService.Status {
+        SMAppService.mainApp.status
+    }
+
     static var statusLabel: String {
-        switch SMAppService.mainApp.status {
+        switch status {
         case .enabled:
             return "Enabled"
         case .notRegistered:
             return "Disabled"
         case .requiresApproval:
             return "Requires approval"
         case .notFound:
-            return "App not found"
+            return "Requires signed install"
         @unknown default:
             return "Unknown"
         }
     }
 
     static var isEnabled: Bool {
-        SMAppService.mainApp.status == .enabled
+        status == .enabled
+    }
+
+    static var canEnable: Bool {
+        status == .notRegistered
+    }
+
+    static var canDisable: Bool {
+        status == .enabled || status == .requiresApproval
+    }
+
+    static var requiresApproval: Bool {
+        status == .requiresApproval
+    }
+
+    static var isUnavailable: Bool {
+        status == .notFound
     }
 
     static func setEnabled(_ enabled: Bool) throws {
@@ -28,4 +48,8 @@ enum LaunchAtLoginManager {
             try SMAppService.mainApp.unregister()
         }
     }
+
+    static func openSystemSettings() {
+        SMAppService.openSystemSettingsLoginItems()
+    }
 }

apps/macos/Sources/GermMacOS/Services/ShellStore.swift

@@ -49,15 +49,16 @@ final class ShellStore: ObservableObject {
         let stored = UserDefaults.standard.string(forKey: "germDaemonBaseURL")
         daemonBaseURL = (stored?.isEmpty == false ? stored! : "http://127.0.0.1:5178")
         // Quit stops only the daemon this shell started; externally started
-        // daemons are observed, never owned. (A managed orphan would also die
-        // on its next log write, since its stdio pipes into this app.)
-        let supervisor = self.supervisor
+        // daemons are observed, never owned. The managed process helper also
+        // watches this app's PID so an unexpected exit cannot orphan uvicorn.
         NotificationCenter.default.addObserver(
             forName: NSApplication.willTerminateNotification,
             object: nil,
             queue: .main
-        ) { _ in
-            supervisor.stop()
+        ) { [weak self] _ in
+            Task { @MainActor [weak self] in
+                self?.supervisor.stop()
+            }
         }
         supervisor.onLogLine = { [weak self] line in
             Task { @MainActor [weak self] in