@hraness/slopcamera 3.5.0 → 3.6.0

package/README.md

@@ -47,14 +47,14 @@ the rendered output with source, runtime requirements and reproduction steps.
 
 ## Install Slopcamera
 
-Slopcamera v3.4.0 includes 17 reusable film and animation direction profiles, deterministic exposure helpers, and a sample renderer that defaults to native 4K. Use the [style direction guide](docs/how-to/direct-visual-styles.md) to author cel animation, pixel art, mathematical explanations, and historical film treatments from retained sources.
+Slopcamera v3.5.0 includes 17 reusable film and animation direction profiles, deterministic exposure helpers, and a sample renderer that defaults to native 4K. Use the [style direction guide](docs/how-to/direct-visual-styles.md) to author cel animation, pixel art, mathematical explanations, and historical film treatments from retained sources. On macOS, `slopcamera menubar` puts Slopcamera in the menu bar and explains each macOS notice before it appears.
 
 Install [Bun 1.3.14 or newer](https://bun.sh), then install the verified
-[Slopcamera v3.4.0 release](https://github.com/hraness/slopcamera/releases/tag/v3.4.0)
+[Slopcamera v3.5.0 release](https://github.com/hraness/slopcamera/releases/tag/v3.5.0)
 from its canonical archive:
 
 ```sh
-bun add --global https://github.com/hraness/slopcamera/releases/download/v3.4.0/hraness-slopcamera-3.4.0.tgz
+bun add --global https://github.com/hraness/slopcamera/releases/download/v3.5.0/hraness-slopcamera-3.5.0.tgz
 slopcamera skill install --target agents
 ```
 
@@ -90,8 +90,9 @@ Native engines install separately. The [source-install guide](docs/how-to/use-cu
 explains workspace placement and durable-run identity; the
 [capability reference](docs/reference/capabilities.md) names runtime requirements.
 
-Slopcamera is a CLI. On macOS, an optional unbundled menu-bar companion can show
-the files in the agent outputs directory; `slopcamera menubar` runs a prebuilt
+Slopcamera is a CLI. On macOS, an optional unbundled menu-bar companion shows
+what Slopcamera is rendering, how the last job ended, your last known credits
+balance and the newest files in the agent outputs directory; `slopcamera menubar` runs a prebuilt
 companion directly and does not install or launch an application bundle. The
 companion is a thin product binary over the shared
 [desktop-foundation](https://github.com/hraness/desktop-foundation) crate, pinned

package/apps/desktop/application/operation.ts

@@ -4,7 +4,7 @@ import type { z } from "zod";
 
 import type { ApplicationContext } from "./context";
 
-export const SLOPCAMERA_APPLICATION_TOOL_VERSION = "slopcamera-3.5.0" as const;
+export const SLOPCAMERA_APPLICATION_TOOL_VERSION = "slopcamera-3.6.0" as const;
 
 export const OPERATION_KINDS = [
   "scene.audit",

package/apps/desktop/cli/args.ts

@@ -3659,8 +3659,10 @@ export function parseCliArgs(argv: readonly string[]): CliCommand {
     case "menubar": {
       const parsed = parseOptions(argv.slice(1), { ...JSON_SPEC, "--foreground": "flag", "--background": "flag" });
       const positionals = parsed.positionals;
-      if (positionals.length > 1 || (positionals[0] !== undefined && !["install", "uninstall", "status"].includes(positionals[0]))) throw new CliError("usage", "Use slopcamera menubar [--foreground|--background] or slopcamera menubar install|uninstall|status. See slopcamera help menubar.");
+      if (positionals.length > 1 || (positionals[0] !== undefined && !["install", "uninstall", "status", "start"].includes(positionals[0]))) throw new CliError("usage", "Use slopcamera menubar [--foreground|--background] or slopcamera menubar install|uninstall|status|start. See slopcamera help menubar.");
       if (positionals[0] !== undefined && (optionFlag(parsed, "--foreground") || optionFlag(parsed, "--background"))) throw new CliError("usage", "Choose a menu-bar action or a run mode, not both.");
+      // `start` opens it now and returns, like --background; the login item's hints use it.
+      if (positionals[0] === "start") return { kind: "menubar", action: "run", mode: "background", json: optionFlag(parsed, "--json") };
       return { kind: "menubar", action: (positionals[0] as "install" | "uninstall" | "status" | undefined) ?? "run", mode: optionFlag(parsed, "--background") ? "background" : "foreground", json: optionFlag(parsed, "--json") };
     }
     case "outputs": {

package/apps/desktop/cli/commands.ts

@@ -1,3 +1,4 @@
+import { activityLabel, recordActivity, recordCredits } from "./menubar-status";
 import { reportUsefulResult, type UsefulResultObserver } from "../../../src/support-completion";
 import { SlopcameraCloudError } from "../../../src/cloud-errors";
 import {
@@ -362,7 +363,7 @@ import {
   workflowRunStore,
 } from "./workflow-runs";
 
-export const SLOPCAMERA_VERSION = "3.5.0";
+export const SLOPCAMERA_VERSION = "3.6.0";
 
 // Legacy direct renders predate per-target output contracts. Keep them
 // bounded generously enough for long-form production while preventing one
@@ -5548,6 +5549,7 @@ async function handleCreditsStatus(
   } catch (error) {
     throw creditsErrorToCli(error);
   }
+  recordCredits(context.stateRoot, { usd: balance.balance.usd, low: balance.lowBalance, checkedAt: context.clock() });
   const view = {
     configured: true,
     tokenSource: loaded.source,
@@ -8419,6 +8421,7 @@ async function resolveMutationTarget(
 export async function runCli(argv: readonly string[], dependencies: CliDependencies = {}): Promise<number> {
   const io = dependencies.io ?? processIo;
   let jsonRequested = argv.includes("--json") || argv.includes("--jsonl");
+  let activity: { readonly stateRoot: string; readonly label: string; readonly startedAt: number } | undefined;
   try {
     const command = parseCliArgs(argv);
     jsonRequested = "json" in command ? command.json : command.kind === "events" && command.format !== "human";
@@ -8513,6 +8516,11 @@ export async function runCli(argv: readonly string[], dependencies: CliDependenc
         ? {}
         : { renderGalleryScene: dependencies.renderGalleryScene }),
     };
+    const label = activityLabel(command);
+    if (label !== undefined) {
+      activity = { stateRoot, label, startedAt: context.clock() };
+      recordActivity(stateRoot, { state: "running", label, startedAt: activity.startedAt });
+    }
     const mutationTarget = await resolveMutationTarget(paths, stateRoot, command);
     await withCommandHostResources(context, command, async admittedContext => {
       if (mutationTarget === undefined) {
@@ -8535,9 +8543,15 @@ export async function runCli(argv: readonly string[], dependencies: CliDependenc
       || command.kind === "project-render" && command.action === "run" && !command.dryRun) {
       reportUsefulResult(dependencies.onUsefulResult);
     }
+    if (activity !== undefined) {
+      recordActivity(activity.stateRoot, { state: "done", label: activity.label, startedAt: activity.startedAt, finishedAt: io.now().getTime() });
+    }
     return 0;
   } catch (error) {
     const failure = asCliError(error);
+    if (activity !== undefined) {
+      recordActivity(activity.stateRoot, { state: "failed", label: activity.label, startedAt: activity.startedAt, finishedAt: io.now().getTime(), error: failure.code });
+    }
     const payload = {
       error: {
         code: failure.code,

package/apps/desktop/cli/help.ts

@@ -1,9 +1,11 @@
+import { slopcameraSupportAdvancedHelp, slopcameraSupportHelpLine } from "../../../src/support";
+
 import { HTML_OVERLAY_SCAFFOLD_KINDS } from "../html-overlay";
 
 const HTML_OVERLAY_SCAFFOLD_KIND_HELP =
   HTML_OVERLAY_SCAFFOLD_KINDS.join("|");
 
-const GLOBAL_HELP = `slopcamera: a media studio for coding agents
+const globalHelp = () => `slopcamera: a media studio for coding agents
 
 Usage: slopcamera <command> [options]
 
@@ -35,11 +37,6 @@ Commands:
   credits status|topup|wait|forget
                                  Buy and inspect hosted generation credits
   media audio|color              Apply local non-destructive audio and video effects
-  menubar [--foreground|--background]
-                                 Show your outputs in the menu bar
-  menubar install|uninstall|status  Open it at login, stop that, or check it
-  support [--json|protocol --json|offer --json|shown <id>|release <id>|dismiss|snooze|enable|status --json]
-                                 Optional support; no feature requires payment
   outputs                        Print the agent outputs directory
   recordings list               List recording bundles
   projects list|create           List projects or create one from a recording
@@ -63,19 +60,21 @@ Examples:
   slopcamera render run REC --output out.mp4  Render a recording
 
 Run slopcamera help <command> for command-specific help.
-Optional support: slopcamera support · Turn off: HRANESS_SUPPORT_AUDIENCE=off`;
+${slopcameraSupportHelpLine()}`;
 
 const HELP: Readonly<Record<string, string>> = {
+  advanced: `${slopcameraSupportAdvancedHelp()}`,
   menubar: `Usage:
   slopcamera menubar [--foreground|--background] [--json]
-  slopcamera menubar install|uninstall|status [--json]
+  slopcamera menubar install|uninstall|status|start [--json]
 
-Shows 📷 in the menu bar with your recent outputs. It only lists and opens
-files in the outputs folder (slopcamera outputs).
+Shows what Slopcamera is doing in the menu bar: a render in progress, how the
+last job ended and your last known credits balance, plus your newest outputs.
+It only reads that status and the outputs folder (slopcamera outputs).
 
   menubar               Open it now; it closes when this command ends
-  menubar --background  Open it now and return
-  menubar install       Open it now and every time you log in
+  menubar start         Open it now and return (same as --background)
+  menubar install       Open it every time you log in
   menubar uninstall     Stop opening it at login and remove the installed copy
   menubar status        Check whether it opens at login and is running
 
@@ -83,9 +82,10 @@ If it's already in your menu bar, starting it again says so and succeeds.
 macOS shows a notice that slopcamera-menubar can open at login. Turn it off any
 time in System Settings › General › Login Items & Extensions.
 
-The menu bar isn't in released packages yet. In a Slopcamera checkout, build it
-with cargo build --release --manifest-path desktop/Cargo.toml and slopcamera
-finds it; elsewhere, set SLOPCAMERA_MENUBAR to the built file.`,
+The menu bar isn't in released packages yet, so it isn't listed in
+slopcamera help. In a Slopcamera checkout, build it with
+cargo build --release --manifest-path desktop/Cargo.toml and slopcamera finds
+it; elsewhere, set SLOPCAMERA_MENUBAR to the built file.`,
   capabilities: `Usage: slopcamera capabilities [--json]
 
 Print the exact statically assembled capability manifest for this CLI build. Each module owns named operation, workflow, MCP-tool, command, and runtime-profile identities. The manifest includes trust classes, resource/effect policies, runtime requirements, qualification status, and a canonical SHA-256. It reads no workspace source, loads no plugin, probes no runtime, and grants no authority. Use doctor separately to inspect this machine's currently available executables.`,
@@ -701,8 +701,8 @@ Long inactivity is analyzed and removed by default; use --keep-inactivity to opt
 };
 
 export function commandHelp(topic: readonly string[]): string {
-  if (topic.length === 0) return GLOBAL_HELP;
-  return HELP[topic[0]!] ?? GLOBAL_HELP;
+  if (topic.length === 0) return globalHelp();
+  return HELP[topic[0]!] ?? globalHelp();
 }
 
 export function completions(words: readonly string[]): readonly string[] {

package/apps/desktop/cli/menubar-status.ts

@@ -0,0 +1,155 @@
+import { chmodSync, lstatSync, openSync, closeSync, readFileSync, renameSync, rmSync, writeSync, constants } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+
+import type { CliCommand } from "./args";
+
+/**
+ * The small status file the menu bar reads: what Slopcamera is doing now,
+ * how the last render ended, and the last credits balance a command saw.
+ * It holds plain labels, times and fixed error codes only — never paths,
+ * prompts, tokens or account identifiers. Writes are best effort: a status
+ * that can't be saved never fails the command.
+ */
+export const MENUBAR_STATUS_FILE = "menubar-status.json";
+const MAX_STATUS_BYTES = 16 * 1024;
+
+export type ActivityState = "running" | "done" | "failed";
+
+export interface MenubarActivity {
+  readonly state: ActivityState;
+  readonly label: string;
+  readonly startedAt: number;
+  readonly finishedAt?: number;
+  readonly error?: string;
+}
+
+export interface MenubarCredits {
+  readonly usd: string;
+  readonly low: boolean;
+  readonly checkedAt: number;
+}
+
+export interface MenubarStatus {
+  readonly schemaVersion: 1;
+  readonly activity?: MenubarActivity;
+  readonly credits?: MenubarCredits;
+}
+
+/** Plain labels for the commands that make media. Everything else leaves the status alone. */
+export function activityLabel(command: CliCommand): string | undefined {
+  switch (command.kind) {
+    case "render-run": return command.dryRun ? undefined : "Rendering a recording";
+    case "project-render": return command.action === "run" && !command.dryRun ? "Rendering a project" : undefined;
+    case "project-cinema": return "Rendering a project";
+    case "html-render": return "Rendering an HTML scene";
+    case "diagram-render": return "Rendering a diagram";
+    case "image-vectorize": return "Vectorizing an image";
+    case "ai-image-generate": return "Generating an image";
+    case "ai-video-generate": return "Generating a video";
+    case "ai-speech-generate": return "Generating speech";
+    case "directing": return "Directing a clip";
+    case "studio": return "Running a studio job";
+    case "spatial-scene": return command.action === "render" ? "Rendering a 3D scene" : undefined;
+    case "workflows-run": return "Running a workflow";
+    case "code-run": return "Running a workflow";
+    default: return undefined;
+  }
+}
+
+function parse(text: string): MenubarStatus {
+  try {
+    const value: unknown = JSON.parse(text);
+    if (typeof value !== "object" || value === null || (value as { schemaVersion?: unknown }).schemaVersion !== 1) return { schemaVersion: 1 };
+    const record = value as Record<string, unknown>;
+    const activity = record.activity as MenubarActivity | undefined;
+    const credits = record.credits as MenubarCredits | undefined;
+    return {
+      schemaVersion: 1,
+      ...(activity !== undefined && typeof activity === "object" && typeof activity.label === "string" ? { activity } : {}),
+      ...(credits !== undefined && typeof credits === "object" && typeof credits.usd === "string" ? { credits } : {}),
+    };
+  } catch {
+    return { schemaVersion: 1 };
+  }
+}
+
+export function readMenubarStatus(stateRoot: string): MenubarStatus {
+  const path = join(stateRoot, MENUBAR_STATUS_FILE);
+  try {
+    const info = lstatSync(path);
+    if (!info.isFile() || info.size > MAX_STATUS_BYTES) return { schemaVersion: 1 };
+    return parse(readFileSync(path, "utf8"));
+  } catch {
+    return { schemaVersion: 1 };
+  }
+}
+
+const LOCK_FILE = `.${MENUBAR_STATUS_FILE}.lock`;
+/** A held lock blocks a write for this long before it is skipped. */
+const LOCK_BUDGET_MS = 250;
+/** A lock older than this is a crashed writer's and is reclaimed. */
+const LOCK_STALE_MS = 10_000;
+
+function sleepSync(ms: number): void {
+  Bun.sleepSync(ms);
+}
+
+/**
+ * Runs `update` holding a small exclusive lock file, so a render finishing
+ * while `credits status` runs cannot overwrite the other slot. Returns
+ * undefined when the lock never comes free; the write is then skipped
+ * rather than lost-halfway.
+ */
+function withStatusLock<T>(stateRoot: string, update: () => T): T | undefined {
+  const lock = join(stateRoot, LOCK_FILE);
+  const deadline = Date.now() + LOCK_BUDGET_MS;
+  for (;;) {
+    let fd: number;
+    try {
+      fd = openSync(lock, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") return undefined;
+      try {
+        if (Date.now() - lstatSync(lock).mtimeMs > LOCK_STALE_MS) rmSync(lock, { force: true });
+      } catch { /* races with the lock holder */ }
+      if (Date.now() >= deadline) return undefined;
+      sleepSync(5);
+      continue;
+    }
+    closeSync(fd);
+    try {
+      return update();
+    } finally {
+      try { rmSync(lock, { force: true }); } catch { /* best effort */ }
+    }
+  }
+}
+
+/** Replaces the status file atomically with an owner-only file. Never throws. */
+export function writeMenubarStatus(stateRoot: string, update: (current: MenubarStatus) => MenubarStatus): void {
+  withStatusLock(stateRoot, () => {
+    const path = join(stateRoot, MENUBAR_STATUS_FILE);
+    const staged = join(stateRoot, `.${MENUBAR_STATUS_FILE}.${randomUUID()}.tmp`);
+    try {
+      const root = lstatSync(stateRoot);
+      if (!root.isDirectory()) return;
+      const text = `${JSON.stringify(update(readMenubarStatus(stateRoot)))}\n`;
+      if (Buffer.byteLength(text) > MAX_STATUS_BYTES) return;
+      const fd = openSync(staged, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+      try { writeSync(fd, text); } finally { closeSync(fd); }
+      chmodSync(staged, 0o600);
+      renameSync(staged, path);
+    } catch {
+      try { rmSync(staged, { force: true }); } catch { /* best effort */ }
+    }
+  });
+}
+
+export function recordActivity(stateRoot: string, activity: MenubarActivity): void {
+  writeMenubarStatus(stateRoot, (current) => ({ ...current, activity }));
+}
+
+export function recordCredits(stateRoot: string, credits: MenubarCredits): void {
+  writeMenubarStatus(stateRoot, (current) => ({ ...current, credits }));
+}

package/apps/desktop/cli/menubar.ts

@@ -7,6 +7,7 @@ import { writeJson, writeLine } from "./io";
 import { ensurePrivateDirectory } from "./paths";
 
 const SETTLE_MS = 400;
+/** The label earlier releases used; the menu bar now manages its own login item. */
 const LABEL = "com.hraness.slopcamera.menubar";
 
 function xml(value: string): string { return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;"); }
@@ -109,109 +110,86 @@ function readAgent(path: string, environment: Environment): string | null {
   return readRegular(path, 16 * 1024).toString("utf8");
 }
 
-/** Configuration state only; it does not claim the launchd service is running. */
-export type LaunchAgentState = "absent" | "installed" | "conflict";
-export type LaunchctlRunner = (args: readonly string[], allowMissing?: boolean) => string | null;
-function launchctl(args: readonly string[], allowMissing = false): string | null {
-  const uid = process.getuid?.();
-  if (uid === undefined) throw new CliError("unavailable", "The current user has no launchd GUI domain.");
-  const result = Bun.spawnSync(["/bin/launchctl", ...args.map((arg) => arg.replaceAll("{uid}", String(uid)))], { stdin: "ignore", stdout: "pipe", stderr: "pipe", timeout: 10_000, maxBuffer: 64 * 1024 });
-  return interpretLaunchctlResult(result, uid, allowMissing);
-}
-export function interpretLaunchctlResult(result: { success: boolean; exitCode: number; stdout: Uint8Array; stderr: Uint8Array }, uid: number, allowMissing: boolean): string | null {
-  if (result.stdout.byteLength + result.stderr.byteLength > 64 * 1024) throw new CliError("unavailable", "launchctl exceeded the bounded response size.");
-  if (result.success && result.exitCode === 0) return Buffer.from(result.stdout).toString();
-  if (allowMissing && result.exitCode === 113 && result.stdout.length === 0 && Buffer.from(result.stderr).toString() === `Bad request.\nCould not find service "${LABEL}" in domain for user gui: ${uid}\n`) return null;
-  throw new CliError("unavailable", "launchctl could not reconcile the Slopcamera menu-bar LaunchAgent. Run menubar install again to retry.");
-}
-
-function loadedOwned(path: string, binary: string, current: string | null, run: LaunchctlRunner): boolean {
-  const output = run(["print", `gui/{uid}/${LABEL}`], true);
-  if (output === null) return false;
-  const uid = process.getuid?.();
-  if (current === null || Buffer.byteLength(output) > 64 * 1024 || !output.startsWith(`gui/${uid}/${LABEL} = {\n`)) {
-    throw new CliError("conflict", "The loaded menu-bar service has an unverified identity.");
-  }
-  const lines = output.split("\n").map(line => line.trim());
-  const field = (key: string): string | null => {
-    const values = lines.filter(line => line.startsWith(`${key} = `));
-    return values.length === 1 ? values[0]!.slice(key.length + 3) : null;
-  };
-  const argumentsStart = lines.indexOf("arguments = {");
-  const argumentsEnd = lines.indexOf("}", argumentsStart + 1);
-  if (field("path") !== path || field("program") !== binary || argumentsStart < 0 || argumentsEnd !== argumentsStart + 2 || lines[argumentsStart + 1] !== binary) {
-    throw new CliError("conflict", "The loaded menu-bar service does not match this install; it was left untouched.");
-  }
-  return true;
-}
-export function launchAgentState(binary: string, environment: Environment = process.env): LaunchAgentState {
-  const content = readAgent(launchAgentPath(environment), environment);
-  if (content === null) return "absent";
-  checkParents(binary, environment);
-  assertOwnedFile(binary);
-  return content === launchAgentPlist(binary) && exists(binary) ? "installed" : "conflict";
-}
-function assertMac(platform: NodeJS.Platform): void {
-  if (platform !== "darwin") throw new CliError("unsupported-plan", "Slopcamera menu-bar LaunchAgents are supported only on macOS.");
-}
-export function installLaunchAgent(binary: string, environment: Environment = process.env, platform: NodeJS.Platform = process.platform, runLaunchctl: LaunchctlRunner = launchctl): LaunchAgentState {
-  assertMac(platform);
-  if (!isAbsolute(binary)) throw new CliError("unsafe-path", "LaunchAgent binary must be an absolute path.");
+/**
+ * Copies the built menu bar into its installed location, replacing an
+ * earlier copy. Existing shared directory permissions are preserved;
+ * symbolic links and files other users can write are refused.
+ */
+export function installBinary(binary: string, environment: Environment = process.env): string {
+  if (!isAbsolute(binary)) throw new CliError("unsafe-path", "The menu-bar build must be an absolute path.");
   const stable = installedBinaryPath(environment);
-  const path = launchAgentPath(environment);
-  const current = readAgent(path, environment);
-  const expected = launchAgentPlist(stable);
   checkParents(stable, environment);
   assertOwnedFile(stable);
-  if (current !== null && current !== expected || current === null && infoAt(stable) !== null) {
-    throw new CliError("conflict", "The existing Slopcamera menu-bar install is not owned by this command.");
-  }
   const bytes = readRegular(binary, MAX_BINARY_BYTES, true);
-  loadedOwned(path, stable, current, runLaunchctl);
-  checkParents(path, environment, true);
   checkParents(stable, environment, true);
-  // Unique private staging directories prevent predictable temporary-file clobbering.
-  const binaryStage = mkdtempSync(join(dirname(stable), ".install-"));
-  let agentStage: string | undefined;
+  const stage = mkdtempSync(join(dirname(stable), ".install-"));
   try {
-    agentStage = mkdtempSync(join(dirname(path), ".slopcamera-install-"));
-    const stagedBinary = join(binaryStage, "binary");
-    const stagedAgent = join(agentStage, "agent.plist");
-    writeFileSync(stagedBinary, bytes, { mode: 0o700, flag: "wx" });
-    writeFileSync(stagedAgent, expected, { mode: 0o600, flag: "wx" });
-    if (readAgent(path, environment) !== current) throw new CliError("conflict", "The menu-bar install changed concurrently.");
+    const staged = join(stage, "binary");
+    writeFileSync(staged, bytes, { mode: 0o700, flag: "wx" });
     assertOwnedFile(stable);
-    // Retry bootstrap even when the plist matches: a previous bootstrap may have failed.
-    if (loadedOwned(path, stable, current, runLaunchctl)) runLaunchctl(["bootout", `gui/{uid}/${LABEL}`], true);
-    renameSync(stagedBinary, stable);
-    renameSync(stagedAgent, path);
-    runLaunchctl(["bootstrap", "gui/{uid}", path]);
-    return "installed";
+    renameSync(staged, stable);
+    return stable;
   } finally {
-    rmSync(binaryStage, { recursive: true });
-    if (agentStage !== undefined) rmSync(agentStage, { recursive: true });
+    rmSync(stage, { recursive: true });
   }
 }
-export function uninstallLaunchAgent(_binary: string, environment: Environment = process.env, platform: NodeJS.Platform = process.platform, runLaunchctl: LaunchctlRunner = launchctl): LaunchAgentState {
-  assertMac(platform);
-  const stable = installedBinaryPath(environment);
+
+/**
+ * Removes the login item earlier releases wrote under the old label, but
+ * only when it is exactly the file they wrote. It never calls launchctl: a
+ * copy that is already running keeps running until you quit it or log out.
+ */
+export function removeLegacyAgent(environment: Environment = process.env): "absent" | "removed" | "foreign" {
   const path = launchAgentPath(environment);
   const current = readAgent(path, environment);
   if (current === null) return "absent";
-  if (current !== launchAgentPlist(stable)) throw new CliError("conflict", "The existing Slopcamera menu-bar LaunchAgent is not owned by this command.");
-  checkParents(stable, environment);
-  assertOwnedFile(stable);
-  if (loadedOwned(path, stable, current, runLaunchctl)) runLaunchctl(["bootout", `gui/{uid}/${LABEL}`], true);
-  if (readAgent(path, environment) !== current) throw new CliError("conflict", "The menu-bar install changed concurrently.");
-  assertOwnedFile(stable);
+  if (current !== launchAgentPlist(installedBinaryPath(environment))) return "foreign";
   rmSync(path);
-  if (infoAt(stable) !== null) rmSync(stable);
-  return "absent";
+  return "removed";
+}
+
+function assertMac(platform: NodeJS.Platform): void {
+  if (platform !== "darwin") throw new CliError("unsupported-plan", "The Slopcamera menu bar runs only on macOS.");
+}
+
+export interface HelperResult { readonly code: number; readonly stdout: string; readonly stderr: string }
+/** Runs the installed menu bar's own install, uninstall or status command. */
+export type HelperRunner = (binary: string, args: readonly string[], env: Environment) => Promise<HelperResult>;
+
+async function runHelper(binary: string, args: readonly string[], env: Environment): Promise<HelperResult> {
+  const child = Bun.spawn([binary, ...args], { stdin: "ignore", stdout: "pipe", stderr: "pipe", env: { ...env } as Record<string, string> });
+  const [stdout, stderr, code] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
+  return { code, stdout: stdout.slice(0, 64 * 1024), stderr: stderr.slice(0, 64 * 1024) };
 }
+
+const AGENT_MARKERS = ["AI_AGENT", "CLAUDECODE", "CODEX_SANDBOX", "CODEX_SANDBOX_NETWORK_DISABLED", "CURSOR_AGENT", "GEMINI_CLI"];
+
+/**
+ * The helper decides between human and agent output from its environment.
+ * Its output is captured here, so a person's terminal is passed on as
+ * `HRANESS_AUDIENCE=human`; agents and explicit settings pass through.
+ */
+export function helperEnvironment(env: Environment): Environment {
+  const agent = AGENT_MARKERS.some((name) => (env[name] ?? "") !== "");
+  return env.HRANESS_AUDIENCE !== undefined || agent ? env : { ...env, HRANESS_AUDIENCE: "human" };
+}
+
+function helperFailure(result: HelperResult): CliError {
+  // The helper prints the login-item notice on stderr before the error;
+  // the failure is the last ✗ line plus the → hint that follows it.
+  const lines = result.stderr.split("\n");
+  let start = -1;
+  for (const [index, line] of lines.entries()) {
+    const trimmed = line.trimStart();
+    if (trimmed.startsWith("✗") || trimmed.startsWith("FAIL")) start = index;
+  }
+  const text = (start === -1 ? result.stderr : lines.slice(start).join("\n")).trim().replace(/^(✗|FAIL)\s+/u, "");
+  return new CliError(result.code === 2 ? "usage" : "unavailable", text === "" ? "The Slopcamera menu bar couldn't change its login item." : text);
+}
+
 /** `slopcamera-menubar` exits with this code when another copy already holds the menu bar. */
 export const ALREADY_RUNNING_EXIT = 3;
 const NOT_BUILT = "The Slopcamera menu bar isn't in this release yet. Build it with cargo build --release --manifest-path desktop/Cargo.toml in a Slopcamera checkout; slopcamera finds it there, or set SLOPCAMERA_MENUBAR to the built file.";
-const LOGIN_ITEMS = "System Settings › General › Login Items & Extensions";
 
 export type Launched = "running" | "already-running" | "exited";
 export type BinaryRunner = (binary: string, foreground: boolean) => Promise<number | null>;
@@ -240,11 +218,6 @@ export function marks(env: Readonly<Record<string, string | undefined>>): Marks
   return ascii ? { ok: "OK", warn: "WARN", note: "NOTE", next: "->" } : { ok: "✓", warn: "⚠", note: "🔐", next: "→" };
 }
 
-/** The LOGIN_ITEM notice (notifies, so there is no confirm line). The requester is the bare companion until Slopcamera ships as an app. */
-export function loginItemNotice(env: Readonly<Record<string, string | undefined>>): string {
-  return `${marks(env).note} macOS will show a notice that slopcamera-menubar can open at login. That's Slopcamera's menu bar.\n   It lists your outputs and opens when you log in. Nothing else runs in the background. Turn it off any time in ${LOGIN_ITEMS}.\n`;
-}
-
 export function launchMessage(outcome: Launched, env: Readonly<Record<string, string | undefined>>): string {
   const mark = marks(env);
   if (outcome === "already-running") return `${mark.ok} Slopcamera is already in your menu bar. Look for 📷.`;
@@ -252,42 +225,6 @@ export function launchMessage(outcome: Launched, env: Readonly<Record<string, st
   return "The Slopcamera menu bar closed.";
 }
 
-export function stateMessage(action: "install" | "uninstall" | "status", state: LaunchAgentState, running: boolean, env: Readonly<Record<string, string | undefined>>): string {
-  const mark = marks(env);
-  if (state === "conflict") return `${mark.warn} Another menu-bar setup that this command didn't create is in the way. It was left untouched.\n  Remove ~/Library/LaunchAgents/${LABEL}.plist yourself if you don't need it.`;
-  if (state === "absent") return action === "uninstall" ? `${mark.ok} Slopcamera no longer opens in your menu bar at login.` : `Slopcamera doesn't open at login.\n${mark.next} slopcamera menubar install`;
-  if (action === "install") return `${mark.ok} Slopcamera opens in your menu bar now and at every login. Look for 📷.\n  Remove it any time: slopcamera menubar uninstall`;
-  return running
-    ? `${mark.ok} Slopcamera opens at login and is in your menu bar now.`
-    : `${mark.warn} Slopcamera is set to open at login but isn't running. It may be turned off in ${LOGIN_ITEMS}.\n${mark.next} slopcamera menubar install`;
-}
-
-/** Whether launchd reports the loaded companion as running. Reads state only. */
-export function serviceRunning(runLaunchctl: LaunchctlRunner): boolean {
-  const output = runLaunchctl(["print", `gui/{uid}/${LABEL}`], true);
-  return output !== null && output.split("\n").some((line) => line.trim() === "state = running");
-}
-
-export type ProcessProbe = () => boolean;
-/** Whether any copy of the companion runs for this user, including one started by hand. */
-function companionProcessRunning(): boolean {
-  const uid = process.getuid?.();
-  if (uid === undefined) return false;
-  try {
-    return Bun.spawnSync(["/usr/bin/pgrep", "-x", "-U", String(uid), "slopcamera-menubar"], { stdin: "ignore", stdout: "ignore", stderr: "ignore", timeout: 5_000 }).exitCode === 0;
-  } catch { return false; }
-}
-
-/** The menu bar is showing when launchd runs the login item or another copy holds it. */
-async function menubarShowing(runLaunchctl: LaunchctlRunner, probe: ProcessProbe, waitMs: number): Promise<boolean> {
-  const deadline = Date.now() + waitMs;
-  for (;;) {
-    if (serviceRunning(runLaunchctl) || probe()) return true;
-    if (Date.now() >= deadline) return false;
-    await Bun.sleep(200);
-  }
-}
-
 export async function launchMenubar(io: CliIo, repositoryRoot: string, asJson: boolean, mode: "foreground" | "background" = "foreground", runBinary: BinaryRunner = spawnBinary): Promise<void> {
   const binary = resolveMenubarBinary(repositoryRoot, io.env);
   if (binary === null) throw new CliError("unavailable", NOT_BUILT);
@@ -295,23 +232,38 @@ export async function launchMenubar(io: CliIo, repositoryRoot: string, asJson: b
   if (asJson) writeJson(io, { running: outcome !== "exited", foreground: mode === "foreground", alreadyRunning: outcome === "already-running" });
   else writeLine(io, launchMessage(outcome, io.env));
 }
-export async function manageMenubar(io: CliIo, repositoryRoot: string, action: "install" | "uninstall" | "status", asJson: boolean, runLaunchctl: LaunchctlRunner = launchctl, probe: ProcessProbe = companionProcessRunning): Promise<void> {
+export async function manageMenubar(io: CliIo, repositoryRoot: string, action: "install" | "uninstall" | "status", asJson: boolean, run: HelperRunner = runHelper): Promise<void> {
   assertMac(io.platform);
   const stable = installedBinaryPath(io.env);
-  let state: LaunchAgentState;
+  const args = asJson ? [action, "--json"] : [action];
+  const env = helperEnvironment(io.env);
+  const forward = (result: HelperResult): void => {
+    if (result.stdout !== "") io.stdout(result.stdout);
+    if (result.code !== 0) throw helperFailure(result);
+    if (result.stderr !== "") io.stderr(result.stderr);
+  };
   if (action === "install") {
     const binary = resolveMenubarBinary(repositoryRoot, io.env);
     if (binary === null) throw new CliError("unavailable", NOT_BUILT);
-    if (!asJson) io.stderr(loginItemNotice(io.env));
-    state = installLaunchAgent(binary, io.env, io.platform, runLaunchctl);
-  } else {
-    state = action === "uninstall" ? uninstallLaunchAgent(stable, io.env, io.platform, runLaunchctl) : launchAgentState(stable, io.env);
+    const installed = binary === stable ? stable : installBinary(binary, io.env);
+    forward(await run(installed, args, env));
+    // The old login item goes only after the new one is in place, so a
+    // failed install never leaves nothing to start at login.
+    removeLegacyAgent(io.env);
+    return;
   }
-  // A fresh login item may take a moment to start, so install waits briefly.
-  const running = state === "installed" && await menubarShowing(runLaunchctl, probe, action === "install" ? 1_000 : 0);
-  if (asJson) writeJson(io, { launchAgent: state, running });
-  else writeLine(io, stateMessage(action, state, running, io.env));
+  if (action === "uninstall") removeLegacyAgent(io.env);
+  if (!exists(stable)) {
+    if (asJson) writeJson(io, { login: "off", running: false, installed: false });
+    else if (action === "uninstall") writeLine(io, `${marks(io.env).ok} Slopcamera won't open at login.`);
+    else writeLine(io, `Slopcamera's menu bar isn't installed.\n${marks(io.env).next} slopcamera menubar install`);
+    return;
+  }
+  const result = await run(stable, args, env);
+  forward(result);
+  if (action === "uninstall") rmSync(stable);
 }
+
 export async function reportOutputsRoot(io: CliIo, stateRoot: string, asJson: boolean): Promise<void> {
   const directory = outputsRoot(stateRoot);
   await ensurePrivateDirectory(directory);