@phnx-labs/agents-cli 1.20.93 → 1.21.0

package/CHANGELOG.md

@@ -1,5 +1,269 @@
 # Changelog
 
+## 1.21.0
+
+- **A clone of your own DotAgents repo no longer hijacks project-layer rule resolution (RUSH-2037).**
+  Cloning `~/.agents` to the canonical `~/src/github.com/<you>/.agents` path (to edit
+  rules in an editor) made that checkout eligible as a *project* layer whenever you
+  worked from its parent directory. Because project outranks user, a stale clone's
+  `rules/subrules/*` then silently shadowed the live user rules by filename, and the
+  compile planted an out-of-date `AGENTS.md` in an ancestor dir that every session
+  beneath it ingested. Project-layer discovery now identifies a DotAgents repo by
+  **repo identity** (git origin), not path: a `.agents/` that is itself a git checkout
+  whose origin matches the user's or system's DotAgents repo is skipped, so the live
+  user layer wins. Legitimate project `.agents/` layers (a plain subdirectory of a
+  project, or a git repo with an unrelated origin) are unaffected.
+  Source: `apps/cli/src/lib/state.ts`.
+
+- **`agents sessions --local` no longer dials remote-host teammates over ssh,
+  in the default listing or `--active` (RUSH-2118).** `--local` is supposed to
+  mean this-machine-only, but the underlying `AgentManager` poll still fired a
+  real ssh round-trip for every teammate dispatched via
+  `agents teams add --device` — even a teammate that had already finished.
+  On a box with 30 completed remote-host teammates that measured out to 180
+  real `ssh` execve calls (6 per teammate: two ssh calls in
+  `syncRemoteMirror`, run three times per poll) and a ~4.3s
+  `--active --local` call. A `--local` query now reads a remote-host
+  teammate's last-persisted `meta.json` state instead of dialing it, and a
+  teammate that has already reached a terminal status (completed/failed/
+  stopped) is never re-dialed by ANY `--active` query, local or not — its
+  final log bytes and exit code were already captured on the poll that
+  resolved it. The same gate now covers every `--local` surface: the bare
+  default listing's live-glyph enrichment (`maybeLiveIndex`) and `--preview`
+  (`renderSessionPreview`, freely combinable with `--local`) both called the
+  local-only `getActiveSessions()` with no `localOnly` threaded through,
+  despite the `--local` help text already promising this-machine-only for
+  all of them. Source: `apps/cli/src/lib/teams/agents.ts`
+  (`syncRemoteMirror`, `readNewEvents`, `updateStatusFromProcess`,
+  `AgentManager`), `apps/cli/src/lib/session/active.ts` (`listTeamsActive`,
+  `getActiveSessions`), `apps/cli/src/commands/sessions.ts`
+  (`gatherActiveSessions`, `maybeLiveIndex`, `renderSessionPreview`).
+
+- **A rules preset now applies at `agents run` time, not only after `agents
+  rules switch` (RUSH-2128).** `setActiveRulesPreset` used to take effect only on the next
+  explicit `agents rules switch`/`agents add`/`agents use` — a preset change
+  made any other way left the harness launching against a stale rules file
+  until someone remembered to re-sync. `agents run` now re-applies the active
+  preset for the resolved agent+version immediately before dispatch, every
+  time, with a skip-fast sentinel so an unchanged preset costs no recompose or
+  rewrite. Version-scoped only; per-model preset scoping is a follow-up.
+  Source: `apps/cli/src/lib/rules/run-sync.ts`, `apps/cli/src/commands/exec.ts`.
+
+- **Activity events now carry the same actor and session lineage as operational events.**
+  The TypeScript activity writer and the embedded PostToolUse hook stamp actor kind,
+  launch id, and parent session id from the shared execution provenance floor, so
+  `agents events` no longer invents an agent name as the activity record's OS user.
+  Source: `apps/cli/src/lib/event-provenance.ts`, `apps/cli/src/lib/activity.ts`.
+
+- **`agents view` no longer re-scans every installed Claude binary on each run.**
+  When a Claude model extractor produced zero models (a broken regex, or a
+  mid-install CLI), the result was never cached — so `getModelCatalog` re-ran a
+  full `readFileSync` scan of the 230-270MB Claude binary for every affected
+  installed version, on every invocation (~1.85s each). With 4 affected
+  versions installed, that was ~7.5s added to every `agents view`. A 0-model
+  extraction is now cached too, stamped with when it was attempted, and served
+  for 24 hours before self-healing by retrying; an upgrade/reinstall (a new
+  source mtime) still re-extracts immediately, as before. Measured on a real
+  install with 7 Claude versions (4 of them hitting the broken extractor): the
+  cold first-call cost (~12.5s, unavoidable) drops to ~1-2ms on every
+  subsequent call. Source: `apps/cli/src/lib/models.ts`.
+
+- **Per-device and fleet-wide config keys now have a home: the `config:` block in
+  the two-tier agents.yaml store.** Three new subcommands under `agents devices`
+  (no new top-level noun): `agents devices set-interactive <name>` records the one
+  device agents show YOU artifacts on (browser opens, dashboards) as
+  `config.interactiveHost` in the central, synced agents.yaml — skills no longer
+  guess "the online macOS box", and the host is marked `★ interactive` in
+  `agents devices list`. `agents devices configure <name> --max-agents N
+  --scheduler on|off` and `agents devices note <name> "…"` (repeat
+  to append, `--clear` to empty) write device-scope keys under `config:` in
+  `~/.agents/devices/<name>/agents.yaml` — targetable for any device from any box
+  (the devices/ tree syncs; each machine reads only its own). The default browser
+  profile joins the same registry as `browser.profile`, routed to the existing
+  device-local `defaultBrowserProfile` field (no duplicate key, resolution order
+  unchanged). Unset keys always mean today's behavior; everything is scriptable
+  with `--json`, and `devices list --json` now carries each row's `config` and an
+  `interactive` flag. agents.yaml files the CLI writes now carry a
+  `yaml-language-server` hint pointing at the new
+  `apps/cli/schema/agents-yaml.schema.json`.
+
+  The keys are live inputs, not just stored values. `--scheduler off` stops the
+  routines scheduler from starting on that device — `routines add` skips the
+  auto-start with the reason, a manual `routines start` refuses, and the daemon
+  re-evaluates the gate on every SIGHUP reload (boot it again with
+  `agents devices configure <host> --scheduler on` + any reload, no daemon
+  restart). `--max-agents` feeds host ranking: Factory auto-launch excludes a
+  device at its cap (counting device-wide running agents) and names the cap when
+  a pool is exhausted; teams placement excludes it from the least-loaded
+  auto-pick (counting the team's own roster, local teammates included) and an
+  all-capped pool fails loud instead of over-filling a machine. Setup asks
+  instead of guessing: bare `agents setup` ends with a skippable preferences
+  step (which machine you sit at → interactive host; which browser agents drive
+  here → device default), `agents setup fleet` offers the interactive host after
+  a sync, and the `agents setup browser` picker highlights the auto-detect
+  winner. Source: `apps/cli/src/lib/device-config.ts`,
+  `apps/cli/src/lib/state.ts`, `apps/cli/src/lib/daemon.ts`,
+  `apps/cli/src/lib/teams/scheduler.ts`, `apps/cli/src/commands/ssh.ts`,
+  `apps/cli/src/commands/setup-preferences.ts`,
+  `apps/factory/src/core/launchHost.ts`,
+  `apps/cli/schema/agents-yaml.schema.json`.
+
+- **Mailbox messages now expire and dead boxes are reaped automatically.** Messages
+  enqueued without an explicit TTL used to sit in the spool forever, so pending mail
+  would outlive the session that needed it. They now get a 24-hour default TTL
+  (`AGENTS_MAILBOX_TTL` overrides the default; `agents message … --ttl 2h` sets it
+  per message). When a message expires, a live-but-idle box archives it with a
+  `dropped: expired` receipt. The watchdog tick also runs a liveness sweep using the
+  same live-session set as `agents sessions --active`, archiving pending mail in dead
+  boxes as `dropped: dead` and pruning stale consumed entries. Dropped messages tied
+  to a feed block surface a failure receipt (`status: dropped` / `expired`) so the
+  sender sees the bounce instead of silence. Run the sweep manually with
+  `agents mailboxes gc` (`--json` supported). Source:
+  `apps/cli/src/lib/mailbox.ts`, `apps/cli/src/lib/mailbox-gc.ts`,
+  `apps/cli/src/commands/message.ts`, `apps/cli/src/commands/mailboxes.ts`,
+  `apps/cli/src/commands/watchdog.ts`, `apps/cli/src/lib/feed.ts`.
+
+- **The menu-bar helper can no longer leak CLI processes until the machine is unusable.**
+  Its poll shelled `agents doctor --json` through an unbounded `Process` +
+  `readDataToEndOfFile()`. Two properties composed badly: the call had no deadline
+  (`doctor --json` measures **136s on an idle box**, against a 60s poll interval), and a
+  helper that died mid-call left the child reparented to launchd (PPID 1) with nothing
+  to reap it — along with the `node -e` version probes that child had forked. Both fire
+  together, because the helper crashes under exactly the conditions that make the CLI
+  slow: `NSApplication.shared` segfaults inside `SLSNewConnection` when WindowServer is
+  too starved to hand out a connection, launchd's `KeepAlive` restarts it, and the
+  restart spawns a new doctor while the old one keeps burning a core. Observed on a real
+  machine: 38 orphaned doctors + 92 orphaned probes, ~13 of 18 cores consumed, load
+  average 490, keystrokes visibly lagging.
+  The crash itself cannot be prevented from inside the app — it is AppKit dereferencing
+  a null connection before any of our code runs — so a crash no longer costs anything
+  permanent: every child carries a deadline (30s; 180s for `doctor --json`, above its
+  real measured cost); it is spawned as its own process-group leader so a timeout kills
+  the whole subtree rather than just the CLI; and each live child is recorded on disk so
+  the *next* launch reaps whatever a crash abandoned (no exit handler runs on SIGSEGV).
+  The doctor refresh also drops from every 60s to every 15 minutes, and the launchd job
+  gains `ThrottleInterval` 30 so a startup crash-loop cannot respawn every 10s.
+  A poll that blows its deadline now shows a stale menu instead of taking the machine
+  down with it. Source: `apps/cli/menubar/Sources/MenubarHelper/ChildProcess.swift`,
+  `AgentsCLI.swift`, `StatusItemController.swift`, `main.swift`,
+  `apps/cli/src/lib/menubar/install-menubar.ts`.
+
+- **The macOS menu-bar helper is now notarized, ending the "app is damaged"
+  dialog and the per-run `no valid code signature; skipping launch` spam
+  (RUSH-2134).** The helper shipped Developer-ID signed but *not* notarized, so
+  Gatekeeper on macOS 26+ rejected it as damaged and the install path tried to
+  heal it by re-signing ad-hoc on every `agents` invocation — which can never
+  satisfy Gatekeeper, so the dialog and the noise persisted. The release now
+  notarizes + staples the helper (`menubar/scripts/build.sh`, mandatory for any
+  Developer-ID build, run under the release's `agents secrets exec apple.com`
+  context), the `prepack` gate refuses to pack an un-notarized bundle
+  (`scripts/verify-menubar-helper.sh` now requires a stapled ticket), and the
+  runtime ad-hoc re-sign band-aid is deleted — a notarized + stapled bundle
+  survives npm's tarball round-trip untouched, so the helper launches with no
+  per-machine healing. The launch guards now verify Gatekeeper acceptance (not
+  just `codesign --verify`) and fail loud pointing at an upgrade rather than
+  re-signing over it. Source: `apps/cli/menubar/scripts/build.sh`,
+  `apps/cli/scripts/verify-menubar-helper.sh`, `apps/cli/scripts/release.sh`,
+  `apps/cli/src/lib/menubar/install-menubar.ts`.
+
+- **`agents projects import` gains Linear as a source, and gates the Factory guess.**
+  `import --from-linear` turns the workspace's Linear projects into definitions via the
+  `linear` CLI, binding a local checkout only on an exact name match so it never
+  silently points a project at the wrong repo. `--from-factory` now imports only
+  `high`-confidence rows by default (`--min-confidence low|medium|high`, `--all` to
+  take everything), and prints why each row was skipped — the auto-detected registry
+  used to absorb every stale clone it found. Source: `apps/cli/src/lib/project-import.ts`.
+- **`agents projects list` columns line up again.** Widths are computed from the rows
+  being printed instead of a fixed 32-character path pad that every home-relative root
+  ran straight through. Source: `apps/cli/src/commands/projects.ts`.
+
+- **`agents projects status` shows the next Linear milestone.** A new `next` line names
+  the project's earliest unfinished milestone with its progress and a human due date
+  (`Beta cut · 3/8 · due in 6 days`, `overdue by 3 days`, `due Aug 21`) — a percentage
+  says how far along a project is, the milestone says what it is due to hit next. The
+  milestone list comes from the project rather than from issue assignments, so a
+  milestone with nothing filed under it yet still shows; it rides along on the first
+  page of the existing issue fetch, costing no extra request. Source:
+  `apps/cli/src/lib/linear-project-counts.ts`.
+
+- **`agents publish --branch <b>` now pushes the index to `<b>`, not just the printed URL (#1061).**
+  The flag rewrote the printed `raw.githubusercontent.com/.../<b>/skills-index.json`
+  URL, but the commit still landed on the checked-out branch — so `--branch dev` from a
+  `main` checkout published the index to `main` while advertising a `dev` URL that didn't
+  resolve. `commitAndPush` now takes an optional target branch and pushes
+  `<current>:<target>`, reporting back the branch the index actually landed on so the URL
+  references it. Omitting `--branch` still publishes to the repo's current branch.
+  Source: `apps/cli/src/lib/git.ts` (`commitAndPush`, `pushOrigin`, `getCurrentBranch`),
+  `apps/cli/src/commands/packages.ts`.
+
+- **Remove the unused `agents hq` command.** `agents hq floor --json` was a
+  machine-readable bridge for an interactive Agents HQ floor UI that was never
+  built — `apps/factory` has zero references to it and it had no other consumer.
+  Typing `agents hq` now prints a clear removal notice and exits non-zero instead
+  of silently disappearing. Source: `apps/cli/src/index.ts`,
+  `apps/cli/src/lib/startup/command-registry.ts` (removed
+  `apps/cli/src/commands/hq.ts`, `apps/cli/src/lib/hq/`).
+
+- **Removed `agents drive` and the R2/CRDT background session-sync beta.** Both
+  predate `agents sessions export`/`import`, which now cover the same ground
+  without a daemon: `agents drive` (rsync-based session/config mirroring) and
+  the opt-in `session-sync` beta (`agents sessions sync`, the daemon's ~90s R2
+  push/pull loop, `agents sync --sessions`) are gone. If you had `session-sync`
+  or `drive` enabled, re-enable is no longer possible — use `--host` for live
+  cross-machine reads or `agents sessions export --encrypt` /
+  `agents sessions import` for portable, encrypted transcript bundles instead.
+  The R2 network client and CRDT merge machinery are removed entirely with the
+  rest of the background sync. Export/import's own encrypted-bundle path
+  survives unchanged: it never talked to R2 over the network — it only reuses
+  the `r2.backups` bundle's shared `R2_SYNC_ENC_KEY` for local AES-256-GCM
+  encryption, falling back to a printed ephemeral key when that bundle isn't
+  configured. Source: `apps/cli/src/commands/drive.ts`,
+  `apps/cli/src/commands/sessions-sync.ts`, `apps/cli/src/lib/session/sync/crdt.ts`,
+  `apps/cli/src/lib/session/sync/sync.ts`, `apps/cli/src/lib/session/sync/r2.ts`,
+  `apps/cli/src/lib/daemon.ts`.
+
+- **A routine that fires less often than weekly can now be caught up at all.** Overdue
+  detection walked a fixed one-week window for the most recent expected fire, so any cron whose
+  gap exceeds that returned nothing and the routine was skipped entirely — never flagged
+  overdue on any device, never caught up, no `missed` record, silently. Monthly, semi-monthly,
+  quarterly and annual routines were all in that class. Measured on a real schedule
+  (`0 9 1,13,25 * *`, 12-day gaps): on **10 of every 28 days** the routine could not be
+  evaluated. The lookback now widens (week → month → quarter → year) only when the narrower
+  window finds nothing, so a dense schedule never walks more than a week of occurrences.
+- **Catch-up no longer resurrects a retired routine.** `detectOverdueJobs` never checked
+  `endAt`, and the scheduler only auto-disables lazily inside a live cron tick — so a routine
+  whose `endAt` elapsed while the daemon was down was still enabled on disk, rescheduled on
+  restart, and executed by the catch-up pass.
+- **One-shot detection matches the scheduler's.** Overdue used the raw `runOnce` flag while the
+  scheduler uses `isOneShotRoutine`, so a one-shot-*like* schedule (a fixed minute/hour/day/
+  month) that never carried the flag could be replayed by catch-up.
+- **The creation floor now covers built-in routines.** `routineEffectiveStart` resolved a
+  routine's file through a user-layer-only lookup, but `listJobs` reads the system layer too —
+  so a built-in shipped in the system repo had neither a `createdAt` stamp nor a resolvable
+  path, the floor was skipped, and it read as instantly overdue on first daemon start. Added
+  `resolveJobFilePath`, which resolves across every layer the loader reads.
+- **A `createdAt` in the future is clamped to now.** Left unclamped (clock skew, a hand-edited
+  year) it sits after every possible expected fire, so the routine could never be flagged
+  overdue until wall-clock time caught up.
+
+- **A routine now runs on exactly one device, instead of once per device listed.** `devices:`
+  was an allowlist where *every* listed device fired independently, so a routine pinned to two
+  boxes ran twice on every schedule — two full agent sessions doing identical work and burning
+  double the agent quota. On one live fleet seven routines were in that state: `security-sweep`
+  ran at 15:30:02 on one box and 15:30:03 on the other, both completing. Ownership is now a pure
+  function of the config (the first device in normalized sort order), so every daemon reaches the
+  same answer with no lease, no cross-device coordination, and no split brain when the fleet
+  partitions. Omitting `devices` still means fleet-wide, which is what `watchdog` and
+  `check-updates` want.
+- **`agents routines add --devices a,b` and `devices --set a,b` are now rejected.** A routine
+  belongs to one machine; the error names the fix. Routines already on disk with a multi-device
+  pin keep running — on their owner only — rather than being dropped.
+- **`agents doctor` lists any routine still carrying a multi-device pin**, with the devices it
+  names, the one that now fires, and the command to make it explicit. Also in `doctor --json` as
+  `ambiguousDevicePins`. The remediation deliberately offers the candidates rather than
+  prescribing the owner: the lowest-sorted name can be a registry alias that matches no live
+  machine, and cementing that would keep the routine dead.
+
 ## 1.20.93
 
 - **`agents send` is a real delivery envelope; `notify` is just `--to owner` (RUSH-2123).** Flag-first form: `--to`, `--text`, `--channel`, `--attach`, `--url`. `--to owner` expands from `notify.owner` in agents.yaml. Positional text still works. Help names the three planes (deliver / record / control) so send is not confused with `feed post`, `activity`, or `message`/`sessions inject`. Source: `apps/cli/src/commands/send.ts`, `apps/cli/src/lib/channels/send.ts`.

package/README.md

@@ -476,6 +476,9 @@ agents devices list                     # fleet + headroom: load, mem, idle/busy
 agents devices list --live              # force a live probe of every device (alias of --refresh)
 agents devices list --full              # add per-device cores and free/total RAM
 agents devices list --no-stats          # instant: names/addresses only, skip the probe
+agents devices set-interactive zion     # the device agents show YOU artifacts on (★ in the list)
+agents devices configure mac-mini --max-agents 4 --scheduler off   # per-device config (syncs via devices/<name>/agents.yaml)
+agents devices note mac-mini "runs the releases — don't reboot"    # operator notes, repeat to append
 agents ssh mac-mini                     # hardened SSH: fails fast if offline,
                                         # PowerShell on Windows, password-from-Keychain,
                                         # auto-syncs your terminfo (Ghostty/kitty/…) so

package/dist/commands/beta.js

@@ -1,9 +1,7 @@
 import chalk from 'chalk';
 import { ALL_BETA_FEATURES, getBetaConfigLocation, getEnabledBetaFeatures, setBetaEnabled, } from '../lib/beta.js';
 const BETA_DESCRIPTIONS = {
-    drive: 'Google Drive integration for reading and writing files',
     factory: 'Cloud-based agent dispatch via Rush Factory',
-    'session-sync': 'Cross-machine session transcript sync via R2 (daemon push/pull)',
     projects: 'Named multi-repo projects with a progress rollup (agents projects)',
 };
 function parseFeatures(values) {
@@ -19,12 +17,12 @@ function parseFeatures(values) {
 export function registerBetaCommands(program) {
     const beta = program
         .command('beta')
-        .description('Enable or disable preview features like drive and factory.')
+        .description('Enable or disable preview features like factory.')
         .addHelpText('after', `
 Examples:
   agents beta list
-  agents beta enable drive factory
-  agents beta disable drive
+  agents beta enable factory
+  agents beta disable factory
 `);
     beta
         .command('list')

package/dist/commands/doctor.js

@@ -13,6 +13,7 @@ import { resolveHost } from '../lib/hosts/registry.js';
 import { sshExecAsync } from '../lib/ssh-exec.js';
 import { sshTargetFor } from '../lib/hosts/types.js';
 import { machineId, normalizeHost } from '../lib/session/sync/config.js';
+import { findAmbiguousDevicePins } from '../lib/routines.js';
 import chalk from 'chalk';
 import { checkAllClis, collectTeamsDoctorData } from '../lib/teams/agents.js';
 import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError, getAccountInfo } from '../lib/agents.js';
@@ -1298,6 +1299,10 @@ export function registerDoctorCommand(program) {
             const inventory = await collectLocalFleetInventory(cwd);
             const localName = machineId();
             const duplicateHooks = inspectDuplicateVersionHooks(cwd);
+            // A routine belongs to one device. A multi-device pin used to fire it
+            // once per listed device — duplicate agent runs, duplicate spend — so
+            // surface any that are still on disk with the exact fix.
+            const ambiguousPins = findAmbiguousDevicePins(cwd);
             // Legacy account-global sign-in map, kept for `--json` back-compat
             // (ssh.ts RemoteDoctorJson / menubar read `signIn`). File-based, no home.
             const signIn = {};
@@ -1361,6 +1366,9 @@ export function registerDoctorCommand(program) {
                     // reading `sync`/`orphans`/`repos` are unaffected.
                     health: computeOverviewHealth(syncRows, orphanRows, repoBehindMarkers, duplicateHooks),
                     duplicateHooks,
+                    // Routines whose `devices` names more than one machine — each used to
+                    // fire once per device. `owner` is the one that fires now.
+                    ambiguousDevicePins: ambiguousPins,
                     // Prioritized RUSH-2069 findings (critical/warning, per-version, with
                     // remediation). Additive alongside the legacy fields above.
                     findings,
@@ -1404,6 +1412,21 @@ export function registerDoctorCommand(program) {
             if (syncRows.some((r) => r.status !== 'fresh' || (r.unwiredHooks ?? 0) > 0) || repoBehindMarkers.some((m) => m.behind > 0)) {
                 console.log(chalk.gray('\nRun `agents status` to review and sync what has drifted.'));
             }
+            // A routine runs on exactly one device. Each of these named several and
+            // used to fire once per device — duplicate agent runs on every schedule.
+            if (ambiguousPins.length > 0) {
+                console.log();
+                console.log(chalk.yellow(`${ambiguousPins.length} routine(s) pin more than one device — a routine runs on exactly one:`));
+                for (const pin of ambiguousPins) {
+                    console.log(`  ${chalk.cyan(pin.name)} ${chalk.gray(`[${pin.devices.join(', ')}]`)} ` +
+                        `${chalk.gray('→ fires only on')} ${pin.owner}`);
+                    // Deliberately not prescribing `--set ${pin.owner}`: ownership is the
+                    // lowest-sorted name, which can be a registry alias that matches no
+                    // live machine (`worker` here), and cementing that keeps the routine
+                    // dead. Name the candidates and let the operator pick the real box.
+                    console.log(chalk.gray(`      fix: agents routines devices ${pin.name} --set <${pin.devices.join('|')}>`));
+                }
+            }
             return;
         }
         const parsed = parseTargetArg(target);

package/dist/commands/exec.js

@@ -23,6 +23,7 @@ import * as os from 'os';
 import { spawnSync } from 'child_process';
 import { randomUUID } from 'crypto';
 import { isSessionTrackedAgent } from '../lib/session/types.js';
+import { applyActiveRulesPresetAtRun } from '../lib/rules/run-sync.js';
 /** Distinguish a terminal account-picker marker from an explicit @version pin. */
 export function parseRunAccountPickerRequest(agentSpec) {
     const requested = agentSpec.endsWith('@');
@@ -1978,6 +1979,18 @@ export function registerRunCommand(program) {
             }
         }
         const defaultVersion = version ?? resolveVersion(agent, cwd);
+        // Re-apply the active rules preset before every launch (issue: preset
+        // changes via `setActiveRulesPreset` only took effect after an explicit
+        // `agents rules switch` / `agents sync`). Version-scoped, skip-fast when
+        // nothing changed — see lib/rules/run-sync.ts. Placed here (immediately
+        // after the resolved version is known, before ACP/loop/fallback branch
+        // off) so every downstream dispatch path for this agent+version sees a
+        // fresh rules file, not just the plain execAgent path. `defaultVersion`
+        // is null when nothing is installed yet — execAgent handles that error
+        // path itself; there's no version home to sync into.
+        if (defaultVersion) {
+            applyActiveRulesPresetAtRun(agent, defaultVersion, getVersionHomePath(agent, defaultVersion));
+        }
         // Login preflight (advisory, warn + continue). On a local INTERACTIVE
         // launch, probe whether this agent's account has a credential and print a
         // one-line warning if it looks logged out — so you find out BEFORE the TUI

package/dist/commands/mailboxes.js

@@ -2,7 +2,9 @@ import * as os from 'os';
 import * as path from 'path';
 import chalk from 'chalk';
 import { die, humanDuration, relTime, truncate, visibleWidth } from '../lib/format.js';
+import { setHelpSections } from '../lib/help.js';
 import { listBoxes, readBox, mailboxDir, isValidMailboxId, watchMessages, } from '../lib/mailbox.js';
+import { gcMailbox } from '../lib/mailbox-gc.js';
 import { GLYPH, masthead, sparkline, aggregate, hourlyCounts, graphEdges, } from '../lib/comms-render.js';
 import { getMailboxRootDir } from '../lib/state.js';
 import { getActiveSessions } from '../lib/session/active.js';
@@ -262,6 +264,21 @@ function renderBetween(boxes, a, b, json) {
         console.log(`    ${truncate(m.text.replace(/\s+/g, ' ').trim(), 100)}`);
     }
 }
+async function runGcCommand(opts) {
+    const sessions = await getActiveSessions();
+    const activeBoxIds = new Set(sessions.map(mailboxIdForActiveSession).filter((id) => !!id));
+    const result = gcMailbox(activeBoxIds);
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    if (result.messagesDroppedDead === 0 && result.messagesDroppedExpired === 0) {
+        console.log(chalk.dim(`gc: ${result.boxesScanned} boxes scanned, no pending messages dropped.`));
+        return;
+    }
+    console.log(chalk.yellow(`gc: ${result.messagesDroppedDead} dead-box messages, ${result.messagesDroppedExpired} expired messages dropped ` +
+        `(${result.boxesScanned} boxes scanned, ${result.deadBoxes} dead boxes).`));
+}
 function renderGraph(boxes, filters, json) {
     const nonEmpty = boxes.filter((b) => b.messages.length > 0);
     const msgs = aggregate(nonEmpty).filter((m) => matchesFilters(m, m.toLabel, m.box, filters));
@@ -313,7 +330,7 @@ function newestMessage(box) {
     return box.messages.reduce((a, b) => (a.ts >= b.ts ? a : b));
 }
 export function registerMailboxesCommand(program) {
-    program
+    const cmd = program
         .command('mailboxes')
         .alias('mailbox')
         .argument('[id]', 'A mailbox id (session UUID / teams agentId) to inspect in full')
@@ -387,4 +404,25 @@ export function registerMailboxesCommand(program) {
         }
         renderOverview(boxes, limit, filters);
     });
+    const gcCmd = cmd
+        .command('gc')
+        .description('Run a liveness sweep: archive pending messages in dead boxes and prune stale consumed mail.')
+        .option('--json', 'Emit the GC result as JSON')
+        .action(async (_opts, command) => runGcCommand({ json: command.optsWithGlobals().json === true }));
+    setHelpSections(gcCmd, {
+        examples: `
+      # One-shot sweep using the live session set as the liveness source
+      agents mailboxes gc
+
+      # Machine-readable summary (for scripts / monitors)
+      agents mailboxes gc --json
+    `,
+        notes: `
+      A box is considered dead when no live session (the same source
+      \`agents sessions --active\` uses) owns it. Pending messages in dead boxes
+      are archived as \`dropped: dead\`; expired messages in live boxes are
+      archived as \`dropped: expired\'. Both surfaces a failure receipt back to
+      the feed store when the message carried a blockId.
+    `,
+    });
 }

package/dist/commands/message.js

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
 import { spawn } from 'child_process';
 import { die } from '../lib/format.js';
+import { parseDuration } from '../lib/hooks/cache.js';
 import { getActiveSessions } from '../lib/session/active.js';
 import { getTaskById, updateTaskStatus } from '../lib/cloud/store.js';
 import { resolveProvider } from '../lib/cloud/registry.js';
@@ -53,6 +54,7 @@ async function deliverViaMailbox(mailboxId, text, block, opts) {
         text,
         from: opts.from,
         blockId: block?.blockId,
+        ttlSeconds: opts.ttlSeconds,
     });
     if (block) {
         recordMessageReceipt(block.blockId, {
@@ -116,10 +118,19 @@ export function registerMessageCommand(program) {
         .option('--from <who>', 'Label recorded as the sender of this message')
         .option('--as <operator>', 'Verified operator id answering a high-consequence block')
         .option('--surface <surface>', 'Surface that is sending this answer (feed, terminal, etc.)', 'cli')
+        .option('--ttl <dur>', 'Delivery TTL if the message is not consumed (e.g. 30m, 1h, 24h); 0 disables expiry')
         .action(async (target, text, opts) => {
         if (!target.trim()) {
             die('Target must be a session/agent id or cloud task id. Run `agents sessions --active` to list running agents.');
         }
+        let ttlSeconds;
+        if (opts.ttl !== undefined) {
+            const parsed = parseDuration(opts.ttl);
+            if (parsed == null) {
+                die(`Invalid --ttl ${JSON.stringify(opts.ttl)}: expected a duration like 30m, 1h, 24h, or 0.`);
+            }
+            ttlSeconds = parsed;
+        }
         const sessions = await getActiveSessions();
         const res = resolveMessageTarget(target, sessions, (id) => getTaskById(id) != null);
         switch (res.kind) {
@@ -152,7 +163,7 @@ export function registerMessageCommand(program) {
                     // First-answer-wins for any path that closes an open block.
                     claimBlockAnswer(block, opts);
                     if (route.kind === 'mailbox') {
-                        await deliverViaMailbox(res.id, text, block, opts);
+                        await deliverViaMailbox(res.id, text, block, { from: opts.from, ttlSeconds });
                         return;
                     }
                     if (route.kind === 'tmux' || route.kind === 'iterm' || route.kind === 'pty') {

package/dist/commands/packages.js

@@ -14,7 +14,7 @@ import { AGENTS, getAllCliStates, agentLabel, } from '../lib/agents.js';
 import { capableAgents } from '../lib/capabilities.js';
 import { DEFAULT_REGISTRIES } from '../lib/types.js';
 import { getRegistries, setRegistry, removeRegistry, search as searchRegistries, resolvePackage, validatedNpmSpec, validatedPyPISpec, buildSkillIndex, verifySkillIntegrity, parseOwnerRepoFromRemote, } from '../lib/registry.js';
-import { cloneRepo, commitAndPush, getRemoteUrl, isGitRepo } from '../lib/git.js';
+import { cloneRepo, commitAndPush, getCurrentBranch, getRemoteUrl, isGitRepo } from '../lib/git.js';
 import { discoverCommands, resolveCommandSource, installCommand, installCommandCentrally, } from '../lib/commands.js';
 import { discoverSkillsFromRepo, installSkill, installSkillCentrally, } from '../lib/skills.js';
 import { discoverHooksFromRepo, installHooks, installHooksCentrally, } from '../lib/hooks.js';
@@ -335,7 +335,7 @@ When to use:
         .description('Generate a skills-index.json for a git repo and push it, making its skills discoverable via agents search/install')
         .option('--repo <alias>', 'Publish an extra repo added via `agents repo add` (default: your ~/.agents repo)')
         .option('--name <name>', 'Registry name to suggest in the output (default: the repo name)')
-        .option('--branch <branch>', 'Branch the raw URL should reference', 'main')
+        .option('--branch <branch>', 'Branch to push the index to and reference in the raw URL (default: the repo\'s current branch)')
         .option('--dry-run', 'Write the index and print the URL without committing or pushing')
         .addHelpText('after', `
 Publish walks a repo's skills/ directory, records a sha256 of every SKILL.md,
@@ -398,20 +398,29 @@ the sha256 in the index and abort on mismatch.
         for (const s of index.skills) {
             console.log(`  ${chalk.cyan(s.name)} ${chalk.gray(`sha256:${s.sha256?.slice(0, 12)}…`)}`);
         }
+        // The branch the URL references must be the branch the index actually
+        // lands on. In a real push that's whatever commitAndPush reports back
+        // (the requested --branch, else the checked-out branch); in a dry run we
+        // resolve it the same way without pushing.
+        let urlBranch;
         if (options.dryRun) {
+            urlBranch = options.branch || (await getCurrentBranch(repoDir));
             console.log(chalk.gray(`\nDry run — wrote ${indexPath} but did not commit or push.`));
         }
         else {
             const pushSpinner = ora('Committing and pushing skills-index.json...').start();
-            const result = await commitAndPush(repoDir, 'chore: update skills-index.json (agents publish)');
+            const result = await commitAndPush(repoDir, 'chore: update skills-index.json (agents publish)', options.branch);
             if (!result.success) {
                 pushSpinner.fail(`Push failed: ${result.error}`);
                 console.log(chalk.gray('The index was written locally — commit and push it manually to publish.'));
                 process.exit(1);
             }
-            pushSpinner.succeed('Pushed skills-index.json');
+            // commitAndPush always reports the pushed branch on success; the `??`
+            // only satisfies the optional return type, it is not a behavior path.
+            urlBranch = result.branch ?? (await getCurrentBranch(repoDir));
+            pushSpinner.succeed(`Pushed skills-index.json to ${urlBranch}`);
         }
-        const rawUrl = `https://raw.githubusercontent.com/${repoSlug}/${options.branch}/skills-index.json`;
+        const rawUrl = `https://raw.githubusercontent.com/${repoSlug}/${urlBranch}/skills-index.json`;
         const registryName = options.name || repoSlug.split('/')[1] || 'my-skills';
         console.log(chalk.bold('\nPublished. Share these with anyone who wants your skills:\n'));
         console.log(chalk.gray('  Index URL:'));

package/dist/commands/projects.d.ts

@@ -9,6 +9,7 @@
  * lifecycle state, plan completion, open PRs, and tickets in flight.
  */
 import type { Command } from 'commander';
+import { type LinearMilestone } from '../lib/linear-project-counts.js';
 /** Recursion guard: a peer answering a probe fan-out never re-fans-out itself. */
 export declare const PROJECTS_NO_FANOUT_ENV = "AGENTS_PROJECTS_LOCAL";
 /**
@@ -19,4 +20,31 @@ export declare const PROJECTS_NO_FANOUT_ENV = "AGENTS_PROJECTS_LOCAL";
  * string when everything answered.
  */
 export declare function formatFleetSkippedNote(skipped: string[]): string;
+/** One `projects list` row, pre-render. */
+export interface ProjectListRow {
+    name: string;
+    path: string;
+    repo: string;
+}
+/**
+ * Column widths for `projects list`, sized to the rows actually being printed.
+ * Fixed padding was the bug: home-relative roots run past 50 characters, so a
+ * hardcoded 32 pushed the repo column off its gridline on every long path.
+ * Paths longer than {@link LIST_PATH_MAX} truncate rather than widen the table.
+ */
+export declare function computeProjectListWidths(rows: ProjectListRow[]): {
+    name: number;
+    path: number;
+    repo: number;
+};
+/**
+ * A milestone's target date as a person would say it — "due tomorrow",
+ * "overdue by 3 days", "due Aug 21" — never a raw `2026-08-21` or a duration in
+ * hours. Linear stores a calendar date with no timezone, so both sides are
+ * compared at LOCAL midnight; parsing `YYYY-MM-DD` with `new Date(str)` would
+ * read it as UTC and shift the answer by a day for anyone west of Greenwich.
+ */
+export declare function formatMilestoneDue(targetDate: string, nowMs: number): string | undefined;
+/** The `next` card line: what this project is due to hit, and how far along it is. */
+export declare function formatNextMilestone(ms: LinearMilestone, nowMs: number): string;
 export declare function registerProjectsCommands(program: Command): void;