@phnx-labs/agents-cli 1.20.88 → 1.20.89

package/CHANGELOG.md

@@ -1,5 +1,268 @@
 # Changelog
 
+## 1.20.89
+
+- **Webhook handler layer for one-off agent/workflow/command/routine triggers.**
+  Routines still fire from signed webhooks, but a new `~/.agents/webhooks/*.yml`
+  layer can also run one-off actions: `run.agent`, `run.workflow`, `run.command`,
+  or delegate to an existing `routine`. Handlers support the same source/event/
+  action/label/repo/branch filters as routine triggers, plus Linear
+  `stateTo`/`stateFrom` state-change filters. Prompts and commands can use
+  `{{issue.identifier}}`, `{{updatedFrom.state.name}}`, etc. The receiver emits
+  `webhook.received`, `webhook.authorized`, `webhook.rejected`, `webhook.matched`,
+  `webhook.fired`, `webhook.handler.start`, and `webhook.handler.end` events.
+  Source: `apps/cli/src/lib/triggers/handlers.ts`,
+  `apps/cli/src/lib/triggers/webhook.ts`, `apps/cli/src/lib/routines.ts`,
+  `apps/cli/src/commands/routines.ts`, `apps/cli/docs/03-routines.md`.
+
+- **`agents routines add` gains `--state-to` and `--state-from` filters for Linear
+  triggers.** A Linear routine or handler can now fire only on a specific state
+  transition (for example `--state-to Plan`), instead of on every issue update.
+
+- **Values substituted into `run.command` are shell-quoted.** A webhook context is
+  built from an external payload, and fields like `issue.title` or a GitHub
+  `pull_request` title are free text any outside contributor can set — pasted raw
+  into a shell command they would be a command-injection sink. Substituted values
+  are now single-quoted (POSIX `sh`), so a payload stays one inert argument while
+  the operator's own template keeps its pipes, redirects, and `&&`. On Windows,
+  where `exec` runs through `cmd.exe` and these quoting rules do not hold, a
+  `run.command` containing `{{…}}` is refused with a clear error rather than run.
+  `run.prompt` is unaffected — it never reaches a shell.
+  Source: `apps/cli/src/lib/routines.ts` (`substituteWebhookCommand`,
+  `assertShellSubstitutionSupported`), `apps/cli/src/lib/triggers/handlers.ts`.
+
+- **The `Cmd-Shift-O` quick-dispatch bar now lists the repo's open Linear tickets,
+  and dispatches one on a click (RUSH-2098).** The panel only captured NEW work;
+  it now also shows what already exists. Switching the repo dropdown switches the
+  Linear project (the repo name is matched against `linear projects` reduced to
+  lowercase alphanumerics, so `agents-cli` finds "Agents CLI" with nothing to
+  configure; a worktree resolves to its parent repo, and a repo that matches no
+  project says so and lets you pick one, remembered per repo). Rows are ranked
+  urgent-first — Linear priority, then overdue, then in progress, then newest —
+  and typing filters them, so an existing ticket surfaces before Return files a
+  duplicate. Clicking a row (or `⌘1`–`⌘5`) dispatches that ticket to the selected
+  agents in the picked repo: **Run** claims it and implements it, **Plan** posts a
+  plan as a ticket comment. `⌘`-click opens it in Linear instead. The list renders
+  from a 90-second warm cache so the panel still appears instantly. Source:
+  `apps/cli/menubar/Sources/MenubarHelper/LinearTickets.swift`,
+  `apps/cli/menubar/Sources/MenubarHelper/PromptPanel.swift`,
+  `apps/cli/menubar/Sources/MenubarHelper/AgentsCLI.swift`.
+
+- **Fixed: a menu-bar dispatch whose child printed more than ~64 KiB hung forever
+  and never notified.** The helper read a monitored child's stdout only from the
+  process-termination handler, so a child that filled the pipe buffer blocked on
+  write, never exited, and the completion callback never fired — two `linear`
+  processes were left wedged by a single ticket fetch. Both monitored paths (the
+  ticket agent and `linear create`) now drain stdout, and feed stdin, on a
+  background queue while the child runs. Source:
+  `apps/cli/menubar/Sources/MenubarHelper/AgentsCLI.swift`.
+
+- **The daemon warns when it was launched from an ephemeral root.** A daemon
+  started from a temp dir (`/tmp`, `/var/folders`, `/dev/shm`) or a git worktree
+  resolves its own job modules by dynamic `import()` rooted at the launch entry
+  (`getAgentsBinPath` → `process.argv[1]`). When that directory is later removed
+  — a `/tmp` cleanup, a review/verify checkout teardown, `git worktree remove` —
+  the long-lived daemon keeps ENOENT-ing on every routine's imports
+  (`auto-dispatch.ts`, `routines-placement.ts`, `devices/fleet.ts`), silently
+  wedging until restart. `anchorDaemonCwd` already rescues the cwd, but nothing
+  can re-root a deleted module tree. `runDaemon` now calls
+  `warnEphemeralDaemonRoot` at startup, so the risk is logged the moment the
+  daemon comes up — including a direct `agents __daemon-run` that never passes
+  through the launch-time `validateDaemonBinary` check. That launch-time check is
+  also broadened from git-worktree-only to any ephemeral root via the shared
+  `describeEphemeralDaemonRoot` predicate. The fix for a wedged daemon is
+  unchanged: run it from the globally installed binary
+  (`npm i -g @phnx-labs/agents-cli`) so its entry roots at a stable version home.
+  Source: `apps/cli/src/lib/daemon.ts`
+  (`describeEphemeralDaemonRoot`, `warnEphemeralDaemonRoot`, `validateDaemonBinary`).
+
+- **A `README.md` / `AGENTS.md` sitting in a resource directory is no longer
+  installed as a resource.** `listResources` skipped only dotfiles, so every `.md`
+  beside the actual resources was materialized as one: `commands/README.md` — which
+  the system repo has shipped for months — installed a bogus `/README` slash command
+  into every agent home, and adding per-directory `AGENTS.md` docs would have added
+  `/AGENTS`, `/CLAUDE`, and `/GEMINI` alongside it. `README`, `AGENTS`, `CLAUDE`, and
+  `GEMINI` are now filtered from both `listResources` and `resolveResource` for every
+  kind **except `rules`**, where `AGENTS.md` *is* the resource (the composed ruleset
+  that syncs as each agent's memory file). The check tests `!entry.isDirectory()`
+  rather than `isFile()`, because a `Dirent` for a symlink reports
+  `isFile() === false` and `CLAUDE.md`/`GEMINI.md` are symlinks to `AGENTS.md` by
+  convention — a resource *directory* named `agents/` is still a real resource.
+  Verified against the real installed layers: 30 commands with `README` leaking
+  before, 29 with none after.
+- **`agents commands list` and the command picker no longer offer a name that
+  cannot be opened.** `listCentralCommands` and `discoverCommands`
+  (`src/lib/commands.ts`) run their own `readdirSync` scans rather than going
+  through `listResources`, so they kept offering `README` while
+  `agents commands view README` answered "not found" — a listed-but-unopenable
+  name. Both now share the one exported `isDirectoryDoc` predicate, so every
+  enumerator agrees. Verified: 27 names with `README` before, 26 with none after.
+- **`agents commands add/remove/view` no longer suggest `README` as the example
+  command name.** With `README` reserved as a directory doc, the six hardcoded
+  examples in the help text and non-interactive hints named a command that can never
+  exist. They now use `plan`, which actually ships.
+
+- **File-backed secrets bundles no longer require `AGENTS_SECRETS_PASSPHRASE` on
+  macOS.** The encrypted file store now silently auto-provisions a stable
+  machine-local key (a 0600 file under `~/.agents/.secrets-key/`, kept outside the
+  encrypted store) on first use on **every** platform, macOS included — no prompt,
+  no Touch ID, nothing to set or remember. Previously a file-backed bundle on a Mac
+  hard-failed unless `AGENTS_SECRETS_PASSPHRASE` was exported, which blocked
+  headless reads (e.g. the `auth` bundle the usage/auth reader consults) and
+  frequently hung. Setting `AGENTS_SECRETS_PASSPHRASE` still works and takes
+  precedence — use it to hold the key off disk or to share one bundle's ciphertext
+  across boxes under a common key. Source: `apps/cli/src/lib/secrets/filestore.ts`,
+  `apps/cli/src/lib/secrets/bundles.ts`.
+
+- **Menu-bar & daemon notifications now use the current agents-cli mark, not the
+  legacy logo.** A desktop notification from the menu-bar helper or the routines
+  daemon showed the old `assets/logo.png` gradient "A" — outdated, and blank in the
+  notification's left-hand app-icon slot. `MenubarHelper.app`'s `AppIcon.icns` is
+  now generated from the current brand mark (`assets/app-icon.svg` → `app-icon.png`:
+  the lime-tile lowercase `a` shared with the agi-cli web favicon and the menu-bar
+  glyph), which drives both the notification's right-hand `contentImage` and its
+  left-hand app icon. The installer also registers the bundle with LaunchServices
+  (`lsregister -f`) at its `~/Library/Application Support` path so the OS can resolve
+  that app icon. Source: `apps/cli/menubar/scripts/build.sh`,
+  `apps/cli/src/lib/menubar/install-menubar.ts`, `assets/app-icon.svg`.
+
+- **The menu bar is a single instance, always.** Two copies of the helper could
+  run at once — launchd's `KeepAlive` service plus a LaunchServices/`open` launch
+  of the same `.app` — putting two agents marks in the menu bar, and the second
+  copy could hold `Cmd-Shift-V`/`Cmd-Shift-O` (`RegisterEventHotKey` is
+  first-come). The helper now takes an `flock` on
+  `~/.agents/.cache/state/menubar.lock` at launch and holds it for its lifetime;
+  a helper that cannot take the lock pops the **running** helper's menu open and
+  exits 0, since re-launching a menu-bar app means "show me the one I already
+  have". An `flock` rather than a pid file: the kernel releases it when the
+  holder dies, so a `SIGKILL`ed helper cannot leave a stale "already running"
+  that blocks every later launch. Source:
+  `apps/cli/menubar/Sources/MenubarHelper/SingleInstance.swift`,
+  `apps/cli/menubar/Sources/MenubarHelper/StatusItemController.swift`.
+
+- **`agents menubar setup` configures the menu bar end-to-end.** One idempotent
+  command for a machine that is wrong — never configured, helper down, or showing
+  a duplicate icon. It ends every running helper, installs/refreshes the bundle,
+  checks its code signature, writes the launchd login item (`RunAtLoad` +
+  `KeepAlive`), clears a previous `agents menubar disable`, and verifies exactly
+  one helper came back up — reporting each as its own step and exiting nonzero if
+  it cannot reach that state. `--check` reports without changing; `--json` emits
+  the step list. Source: `apps/cli/src/commands/menubar.ts`,
+  `apps/cli/src/lib/menubar/install-menubar.ts`.
+
+- **`agents menubar status` now shows a duplicate.** Live helper processes were
+  collapsed to a boolean `running`, so two copies of the *installed* bundle — the
+  duplicate a user actually sees — reported as healthy. `--json` now carries an
+  `instances` array (copies of the installed bundle) beside the existing
+  `foreignInstances`, and the text readout names every extra pid and points at
+  `agents menubar setup`. Source:
+  `apps/cli/src/lib/menubar/install-menubar.ts` (`classifyMenubarProcesses`).
+
+- **Quick-dispatch ticket list: one-row filter + sort, and a scrollable list.**
+  The ticket controls sit on a single row of popups next to the Linear project
+  (project · filter · sort) — not a chip matrix or two-column block. Quick filter
+  options: All open, Todo, Doing, Backlog, P1 only, P2 only, Overdue. Quick sort
+  options: Urgent first, Newest, Oldest, Due date, Priority (flat list, no
+  status grouping). Filter and sort picks are remembered across summons. Ticket
+  rows scroll inside a fixed viewport so more than five matches stay reachable
+  without growing the panel. Source:
+  `apps/cli/menubar/Sources/MenubarHelper/LinearTickets.swift`,
+  `apps/cli/menubar/Sources/MenubarHelper/PromptPanel.swift`.
+
+- **`release.sh` now takes a release lease, and refuses to bump past an
+  unpublished tag.** Releases run from whichever fleet box an agent happens to be
+  on, so two agents could enter the pipeline at once; the collision only surfaced
+  at the publish gate (`merged tree != built tree -- refusing to publish`), after
+  one run had already merged and tagged, leaving the version merged but unshipped.
+  A new `scripts/release-lease.sh` holds mutual exclusion on `origin` as an orphan
+  commit at `refs/release-lock/held` — a second claimant's push can never be a
+  fast-forward, so git's rejection *is* the failed lock acquisition. The lease is
+  claimed before the first mutation and dropped by the existing cleanup trap on
+  every exit path. Because a healthy release routinely outlives any sane
+  expiry — the CI matrix alone has run 57 minutes and release 1.20.77 took 186
+  minutes — the lease is **renewed** by a background renewer for the whole run,
+  and the squash-merge, the tag, and the publish each **verify** ownership first,
+  failing closed if it can no longer be proven. A lease that stops being renewed
+  is reclaimable after 30 minutes, and reclaiming names the dead holder instead
+  of silently overwriting it. Separately,
+  `release.sh` now refuses to cut a new version while an older `v*` tag exists
+  that npm never received, and points at the re-run that finishes it — bumping
+  past an unpublished tag is what turned a one-version gap into npm 1.20.78 vs
+  main 1.20.81. Source: `apps/cli/scripts/release-lease.sh`,
+  `apps/cli/scripts/release.sh`.
+
+- **`agents funnel down` disables a public Funnel port from the same wrapper used
+  to enable ingress.** Webhook ingress now has a complete local receiver runbook:
+  keep GitHub/Linear signing keys in `agents secrets`, bind the receiver to
+  `127.0.0.1`, expose it with `agents funnel up`, rotate one source secret at a
+  time, and turn the public port off with `agents funnel down` before stopping or
+  moving the receiver. Source: `apps/cli/src/commands/funnel.ts`,
+  `apps/cli/src/lib/funnel.ts`, `apps/cli/docs/03-routines.md`.
+
+- **New `agents secrets rotate-passphrase` re-keys the encrypted file store under
+  a new master passphrase, atomically (RUSH-1975).** Until now there was no
+  supported way to rotate the file-store passphrase — `rekey` only renames macOS
+  keychain service names and `rotate <bundle> <key>` replaces a single secret
+  value, so a leaked passphrase (RUSH-1968) could only be remediated by a
+  hand-rolled non-atomic script or an export-to-plaintext round-trip (the exact
+  exposure being fixed). The new command decrypts every `<item>.enc` under the
+  current key, re-encrypts under a freshly generated one, and swaps both the
+  ciphertext and the 0600 key file by directory rename after verifying every item
+  round-trips. A crash at any point self-heals on the next *rotate* run to a single
+  readable store — content-aware recovery probes which key actually decrypts the
+  live store (not merely which files are present) and classifies the WHOLE store:
+  it completes the rotation forward or rolls back only when one key opens every
+  item, and if a later `secrets set` contaminated a crashed rotation into a MIXED
+  store (items under two keys at once, or a store dir recreated by an interstitial
+  write after the crash left it absent, so its backup holds items the live dir does
+  not) it refuses with an actionable error and preserves every recovery artifact
+  rather than sweeping the only copy of a key or the backed-up ciphertext — so a
+  crash anywhere in the swap can never orphan the store, even when a write landed in
+  between. The rotation and every store write run under
+  one cross-process lock, so a `secrets set` or a second rotation can never
+  interleave with a swap in the first place. No plaintext secret or passphrase is
+  ever written to disk, argv, or a log. Items
+  that don't decrypt under the current key (orphan caches, stale test artifacts)
+  are carried through verbatim, never re-keyed. Dry-run by default (`--commit` to
+  apply). A dry run never re-keys, but it *does* heal an interrupted rotation —
+  that is how a crashed store becomes readable again without re-keying it — and it
+  says so instead of claiming nothing was written. Refuses while the secrets-agent
+  holds live unlocks or while
+  `AGENTS_SECRETS_PASSPHRASE` is exported in the environment, unless `--force`.
+  Headless-safe and Linux-first. Source: `apps/cli/src/lib/secrets/filestore.ts`,
+  `apps/cli/src/commands/secrets-rotate-passphrase.ts`.
+
+- **`agents sessions --active --json` now reports who is watching each session.**
+  The `viewingIn` field carries the same string the table prints — `codium tab 3`,
+  `ghostty tab 2`, or `detached` for a live tmux pane with **no client attached**
+  (its terminal was closed or crashed). It is `null` both for a session that isn't
+  tmux-hosted and for one whose pane the locator could not resolve — `detached` is
+  claimed only when the pane was actually located, so absence of evidence is never
+  reported as evidence of absence. Previously the JSON path returned
+  before the locator pass ran, so the field never appeared and a machine consumer
+  could not tell a session someone is looking at from an orphaned one — which is
+  exactly what the Factory extension's `Agents: Resume` picker ranks by. The JSON
+  path resolves tmux clients only — no osascript — so scriptable output keeps the
+  cheapness the old ordering was protecting; a Ghostty-attached client resolves as
+  `ghostty` without its tab number. Peers running an older CLI that still emits the
+  `{app, tab}` object are normalized at the fan-out boundary, so a mixed-version
+  fleet sweep stays correct. Source: `apps/cli/src/lib/session/viewing-in.ts`
+  (`viewingInLabel`, `parseViewingIn`), `apps/cli/src/commands/sessions.ts`
+  (`serializeActiveSessionsForJson`, `enrichTmuxLocators`),
+  `apps/cli/src/lib/session/remote-active.ts`.
+
+- **Webhook handlers gain `run.env` and `host` placement.** A handler can now
+  inject environment variables into the process it spawns (`run.env`), and choose
+  where that run executes (`host`). `host` takes a device name (`yosemite-s0`), or
+  `fleet` to pick any eligible online worker, or `fleet/<platform>` /
+  `<platform>/fleet` (also a bare `linux` / `macos` / `windows`) to restrict that
+  pick to one platform. A fleet expression that matches no eligible device fails
+  loudly rather than silently falling back to the local machine, so `fleet/linux`
+  can never land on a macOS box. Omitting `host` runs locally, as before.
+  Source: `apps/cli/src/lib/triggers/handlers.ts` (`resolveHandlerHost`),
+  `apps/cli/src/lib/routines-placement.ts` (`pickFleetDevice` platform filter),
+  `apps/cli/src/lib/routines.ts` (`JobConfig.env`), `apps/cli/src/lib/runner.ts`.
+
 ## 1.20.88
 
 - **`agents doctor` redesigned into a prioritized, fleet-aware, per-version

package/README.md

@@ -1002,16 +1002,24 @@ Other useful commands: `agents doctor` checks CLI availability and resource sync
 On macOS, `agents-cli` puts a status item in your menu bar -- a live glance at what your agents are doing, plus a Spotlight-style bar for filing work without breaking focus.
 
 ```bash
-agents menubar enable      # install + launch at login
+agents menubar setup       # configure end-to-end: one instance, started at login
 agents menubar status      # is it installed and running?
 ```
 
+There is only ever **one** agents mark: the helper takes a lock at launch, so a
+second copy surfaces the running one's menu and exits instead of adding a
+duplicate icon. `agents menubar setup` is the recovery command when a machine is
+already wrong -- it ends any duplicate, installs the bundle, wires the login
+item, and verifies exactly one helper came back up.
+
 The dropdown surfaces a **NEEDS YOU** queue (agents waiting on a question, a plan review, or a permission prompt), the running roster, and a routines summary -- the same live state as `agents sessions --active`, one click away.
 
 ### Quick-issue bar (⌘⇧O)
 
 Press `Cmd-Shift-O` anywhere for a thin capture surface: type a one-line note, `Cmd-V` to paste, and attach one or more recent screenshots (double-click a thumbnail to preview it in full). Submit, and a headless agent picks the right project from your recent sessions, investigates, and files the Linear ticket itself -- you never leave what you were doing.
 
+The bar also lists the **open Linear tickets of the repo you picked**, urgent first. Switching the repo switches the Linear project; typing filters the list, so an existing ticket shows up before you file a duplicate; and clicking a row (or `⌘1`-`⌘5`) dispatches that ticket to the selected agents -- **Run** implements it, **Plan** posts a plan as a ticket comment.
+
 <p align="center">
   <img src="assets/menubar-quickissue.svg" alt="The Cmd-Shift-O quick-issue bar: a one-line note with attached screenshot thumbnails that a headless agent turns into a filed Linear ticket" width="100%" />
 </p>

package/dist/commands/commands.js

@@ -35,7 +35,7 @@ Examples:
   agents commands add
 
   # Install specific commands by name
-  agents commands add --names README,debug --agents codex@0.116.0
+  agents commands add --names plan,debug --agents codex@0.116.0
 
 When to use:
   - Project setup: 'agents commands add gh:team/commands' to sync everyone's workflow
@@ -90,7 +90,7 @@ Examples:
   agents commands add
 
   # Install specific commands to a single version
-  agents commands add --names README,debug --agents codex@0.116.0
+  agents commands add --names plan,debug --agents codex@0.116.0
 
   # Pull commands from GitHub and sync to all installed agents
   agents commands add gh:user/repo --agents claude,codex,cursor
@@ -125,7 +125,7 @@ Examples:
                 else {
                     if (!isInteractiveTerminal()) {
                         requireInteractiveSelection('Selecting commands from ~/.agents/commands/', [
-                            'agents commands add --names README,debug --agents codex',
+                            'agents commands add --names plan,debug --agents codex',
                             'agents commands add gh:user/repo --agents codex',
                         ]);
                     }
@@ -272,7 +272,7 @@ Examples:
         .addHelpText('after', `
 Examples:
   # Remove a command by name
-  agents commands remove README
+  agents commands remove plan
 
   # Interactive: pick commands to remove
   agents commands remove
@@ -305,7 +305,7 @@ Examples:
             }
             if (!isInteractiveTerminal()) {
                 requireInteractiveSelection('Selecting commands to remove', [
-                    'agents commands remove README',
+                    'agents commands remove plan',
                 ]);
             }
             try {
@@ -422,7 +422,7 @@ Examples:
         .addHelpText('after', `
 Examples:
   # View a specific command
-  agents commands view README
+  agents commands view plan
 
   # Interactive picker
   agents commands view
@@ -437,7 +437,7 @@ Examples:
             }
             if (!isInteractiveTerminal()) {
                 requireInteractiveSelection('Selecting a command to view', [
-                    'agents commands view README',
+                    'agents commands view plan',
                 ]);
             }
             try {

package/dist/commands/factory.js

@@ -6,6 +6,7 @@ import { homedir } from 'os';
 import { betaEnableHint, isBetaEnabled } from '../lib/beta.js';
 import { insertTask } from '../lib/cloud/store.js';
 import { emit } from '../lib/events.js';
+import { buildFactorySnapshot } from '../lib/factory/snapshot.js';
 function requireFactoryUrl() {
     const url = process.env.FACTORY_FLOOR_URL;
     if (!url) {
@@ -51,14 +52,28 @@ export function registerFactoryCommands(program) {
 Examples:
   agents factory submit PROJ-123
   agents factory submit https://linear.app/example/issue/PROJ-123
+  agents factory snapshot --json
 `);
-    factory.hook('preAction', () => {
-        if (enabled)
+    factory.hook('preAction', (_thisCommand, actionCommand) => {
+        // Foreman must be able to read its tick input before any beta-gated action.
+        if (enabled || actionCommand.name() === 'snapshot')
             return;
         console.error(chalk.red('agents factory is in beta.'));
         console.error(chalk.gray(betaEnableHint('factory')));
         process.exit(1);
     });
+    factory
+        .command('snapshot')
+        .description('Read the complete Software Factory state without dispatching or changing it.')
+        .option('--json', 'Output the stable machine-readable snapshot')
+        .action(async (opts) => {
+        const snapshot = await buildFactorySnapshot();
+        if (opts.json) {
+            console.log(JSON.stringify(snapshot, null, 2));
+            return;
+        }
+        renderSnapshot(snapshot);
+    });
     factory
         .command('submit <linear-ref>')
         .description('Submit a Linear issue (PROJ-123 or URL) to the Software Factory.')
@@ -93,3 +108,12 @@ Examples:
         console.log(`  tail output  agents cloud logs ${result.cloud_execution_id}`);
     });
 }
+function renderSnapshot(snapshot) {
+    console.log(chalk.bold(`Factory snapshot ${snapshot.generatedAt}`));
+    console.log(`  sessions     ${snapshot.sessions.length}`);
+    console.log(`  open PRs     ${snapshot.prs.length}`);
+    console.log(`  devices      ${snapshot.devices.length}`);
+    for (const [project, queue] of Object.entries(snapshot.queues)) {
+        console.log(`  ${project.padEnd(12)} todo ${queue.todo} · in progress ${queue.inProgress} · blocked ${queue.blocked}`);
+    }
+}

package/dist/commands/funnel.js

@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-import { buildFunnelStatusCommand, buildFunnelUpCommand, parseFunnelPort } from '../lib/funnel.js';
+import { buildFunnelDownCommand, buildFunnelStatusCommand, buildFunnelUpCommand, parseFunnelPort } from '../lib/funnel.js';
 import { resolveHost } from '../lib/hosts/registry.js';
 import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
 import { sshTargetFor } from '../lib/hosts/types.js';
@@ -59,4 +59,19 @@ export function registerFunnelCommand(program) {
             process.exit(1);
         }
     });
+    funnel
+        .command('down <host>')
+        .description('Disable Tailscale Funnel exposure for a public HTTPS port.')
+        .option('--port <n>', 'Public Funnel port: 443, 8443, or 10000', '443')
+        .action(async (host, opts) => {
+        try {
+            const publicPort = parseFunnelPort(opts.port ?? '443');
+            await runOnHost(host, buildFunnelDownCommand(publicPort));
+            console.log(chalk.green(`Funnel disabled on ${host}: public :${publicPort}`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
 }

package/dist/commands/menubar.js

@@ -7,7 +7,8 @@
  * user; these commands are the manual override.
  */
 import chalk from 'chalk';
-import { enableMenubarService, disableMenubarService, getMenubarStatus, } from '../lib/menubar/install-menubar.js';
+import { setHelpSections } from '../lib/help.js';
+import { enableMenubarService, disableMenubarService, getMenubarStatus, runMenubarSetup, } from '../lib/menubar/install-menubar.js';
 function notMac() {
     if (process.platform !== 'darwin') {
         console.log(chalk.yellow('The menu bar helper is macOS only.'));
@@ -15,10 +16,122 @@ function notMac() {
     }
     return false;
 }
+/** Shared status readout — `status`, bare `menubar`, and `setup --check` all end here. */
+function printStatus(s, opts = {}) {
+    const yn = (b) => (b ? chalk.green('yes') : chalk.gray('no'));
+    console.log(chalk.bold('Menu bar helper\n'));
+    console.log(`  running            ${yn(s.running)}`);
+    console.log(`  service installed  ${yn(s.serviceInstalled)}`);
+    if (opts.brief) {
+        console.log(chalk.gray('\n  setup | enable | disable | status'));
+        return;
+    }
+    console.log(`  app installed      ${s.installedApp ? chalk.gray(s.installedApp) : chalk.gray('no')}`);
+    console.log(`  installed version  ${s.installedVersion ? chalk.gray(s.installedVersion) : chalk.gray('unknown')}`);
+    console.log(`  current version    ${chalk.gray(s.currentVersion)}`);
+    console.log(`  bundle source      ${s.source ? chalk.gray(s.source) : chalk.red('missing (cannot enable)')}`);
+    console.log(`  disabled by user   ${yn(s.disabledByUser)}`);
+    // Two copies of the INSTALLED bundle is the duplicate the user sees as two
+    // agents marks in the menu bar. It used to read as a healthy `running: yes`.
+    if (s.instances.length > 1) {
+        console.log(chalk.yellow(`\n  ${s.instances.length} copies of the installed helper are running — that is the duplicate menu-bar icon:`));
+        for (const p of s.instances)
+            console.log(chalk.gray(`    ${p.pid}  ${p.executable}`));
+        console.log(chalk.gray('  Fix it with `agents menubar setup`.'));
+    }
+    if (s.foreignInstances.length > 0) {
+        // RegisterEventHotKey is first-come, so the helper that registered the
+        // chord first owns Cmd-Shift-V/O. A process list cannot say which that
+        // was — only that a rival exists — so report the conflict, not a winner.
+        // The loser has no other symptom: its chords simply never fire.
+        const n = s.foreignInstances.length;
+        console.log(chalk.yellow(`\n  ${n} other helper process${n === 1 ? '' : 'es'} running — ${n === 1 ? 'it' : 'they'} may hold Cmd-Shift-V/O instead of the installed one:`));
+        for (const p of s.foreignInstances)
+            console.log(chalk.gray(`    ${p.pid}  ${p.executable}`));
+        console.log(chalk.gray('  End them with `agents menubar setup`.'));
+    }
+    if (s.stale) {
+        console.log(chalk.yellow('\n  Installed helper is stale — runs on next `agents` startup, or `agents menubar setup` now.'));
+    }
+    else if (!s.serviceInstalled && !s.disabledByUser) {
+        console.log(chalk.gray('\n  Set it up with `agents menubar setup`.'));
+    }
+}
+function printSetupResult(r) {
+    console.log(chalk.bold('Menu bar setup\n'));
+    for (const step of r.steps) {
+        const mark = step.outcome === 'failed' ? chalk.red('✗')
+            : step.outcome === 'changed' ? chalk.green('+') : chalk.green('✓');
+        console.log(`  ${mark} ${step.name.padEnd(15)} ${chalk.gray(step.detail)}`);
+    }
+    console.log();
+    if (r.configured) {
+        console.log(chalk.green('Menu bar configured.') + chalk.gray('  One agents mark, started at login.'));
+    }
+    else {
+        console.log(chalk.red('Menu bar not fully configured.') + chalk.gray('  See the failed step above.'));
+    }
+}
 export function registerMenubarCommands(program) {
     const menubar = program
         .command('menubar')
         .description('Manage the macOS menu-bar helper (running sessions, agents awaiting input, routines)');
+    // `setup` is the one command that gets a machine to the intended state:
+    // exactly one status item, started at login. `enable` stays the narrow
+    // install+start; setup adds duplicate cleanup and verifies the end state.
+    const setup = menubar
+        .command('setup')
+        .description('Configure the menu bar end-to-end: one instance, started at login')
+        .option('--check', 'Report the current state, change nothing')
+        .option('--json', 'Emit machine-readable JSON')
+        .action((options) => {
+        if (options.check) {
+            const s = getMenubarStatus();
+            if (options.json) {
+                process.stdout.write(JSON.stringify(s) + '\n');
+                return;
+            }
+            if (notMac())
+                return;
+            printStatus(s);
+            return;
+        }
+        if (!options.json && notMac())
+            return;
+        const r = runMenubarSetup();
+        if (options.json) {
+            process.stdout.write(JSON.stringify(r) + '\n');
+        }
+        else {
+            printSetupResult(r);
+        }
+        if (!r.configured)
+            process.exitCode = 1;
+    });
+    setHelpSections(setup, {
+        examples: `
+      # Configure the menu bar end-to-end (idempotent — safe to re-run)
+      agents menubar setup
+
+      # Two agents marks in the menu bar? This ends the duplicate.
+      agents menubar setup
+
+      # See the current state without changing anything
+      agents menubar setup --check
+    `,
+        notes: `
+      Configures, in order: every running helper ended, the helper bundle at
+      ~/Library/Application Support/agents-cli, its code signature, the launchd
+      login item (com.phnx-labs.agents-menubar — RunAtLoad + KeepAlive), then
+      verifies exactly one helper came back up.
+
+      Every running helper is ended and launchd restarts one, so the survivor is
+      always the login-managed copy. Exits nonzero if it cannot reach that state.
+
+      Setup clears a previous \`agents menubar disable\`. To turn the menu bar off
+      again, run \`agents menubar disable\`.
+    `,
+    });
     menubar
         .command('enable')
         .description('Install and start the menu-bar helper (launches at login)')
@@ -40,7 +153,7 @@ export function registerMenubarCommands(program) {
         if (notMac())
             return;
         disableMenubarService();
-        console.log(chalk.green('Menu bar helper disabled.') + chalk.gray('  Re-enable any time with `agents menubar enable`.'));
+        console.log(chalk.green('Menu bar helper disabled.') + chalk.gray('  Re-enable any time with `agents menubar setup`.'));
     });
     menubar
         .command('status')
@@ -56,33 +169,7 @@ export function registerMenubarCommands(program) {
             console.log(chalk.yellow('The menu bar helper is macOS only.'));
             return;
         }
-        const yn = (b) => (b ? chalk.green('yes') : chalk.gray('no'));
-        console.log(chalk.bold('Menu bar helper\n'));
-        console.log(`  running            ${yn(s.running)}`);
-        console.log(`  service installed  ${yn(s.serviceInstalled)}`);
-        console.log(`  app installed      ${s.installedApp ? chalk.gray(s.installedApp) : chalk.gray('no')}`);
-        console.log(`  installed version  ${s.installedVersion ? chalk.gray(s.installedVersion) : chalk.gray('unknown')}`);
-        console.log(`  current version    ${chalk.gray(s.currentVersion)}`);
-        console.log(`  bundle source      ${s.source ? chalk.gray(s.source) : chalk.red('missing (cannot enable)')}`);
-        console.log(`  disabled by user   ${yn(s.disabledByUser)}`);
-        if (s.foreignInstances.length > 0) {
-            // RegisterEventHotKey is first-come, so the helper that registered the
-            // chord first owns Cmd-Shift-V/O. A process list cannot say which that
-            // was — only that a rival exists — so report the conflict, not a
-            // winner. The loser
-            // has no other symptom: its chords simply never fire.
-            const n = s.foreignInstances.length;
-            console.log(chalk.yellow(`\n  ${n} other helper process${n === 1 ? '' : 'es'} running — ${n === 1 ? 'it' : 'they'} may hold Cmd-Shift-V/O instead of the installed one:`));
-            for (const p of s.foreignInstances)
-                console.log(chalk.gray(`    ${p.pid}  ${p.executable}`));
-            console.log(chalk.gray('  End it, then `agents menubar enable` to restart the installed helper.'));
-        }
-        if (s.stale) {
-            console.log(chalk.yellow('\n  Installed helper is stale — runs on next `agents` startup, or `agents menubar enable` now.'));
-        }
-        else if (!s.serviceInstalled && !s.disabledByUser) {
-            console.log(chalk.gray('\n  Enable it with `agents menubar enable`.'));
-        }
+        printStatus(s);
     });
     // Bare `agents menubar` -> status.
     menubar.action(() => {
@@ -91,10 +178,6 @@ export function registerMenubarCommands(program) {
             console.log(chalk.yellow('The menu bar helper is macOS only.'));
             return;
         }
-        const yn = (b) => (b ? chalk.green('yes') : chalk.gray('no'));
-        console.log(chalk.bold('Menu bar helper\n'));
-        console.log(`  running            ${yn(s.running)}`);
-        console.log(`  service installed  ${yn(s.serviceInstalled)}`);
-        console.log(chalk.gray('\n  enable | disable | status'));
+        printStatus(s, { brief: true });
     });
 }