@phnx-labs/agents-cli 1.22.14 → 1.22.16

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## 1.22.16
+
+- **Resume exact sessions locally or across the fleet with `agents resume <id>` and `agents run <agent|auto> --resume <id>`.** Full IDs use the local SQLite index before any SSH fan-out; remote owners route to the recorded device and version home. Session metadata now records launch mode alongside harness, version, account, cwd, and machine so strict resume reconstructs the original run. Claude, Codex, Grok, Kimi, Droid, and Cursor use their verified version-specific native resume syntax; `run auto --resume` can select another healthy harness/account and continue through `/continue` when native resume is unavailable. Source: `apps/cli/src/commands/{exec,resume,sessions}.ts`, `apps/cli/src/lib/{exec,session/db}.ts`, `packages/session-tracker/src/hook.sh`.
+
+- **Hooks: one-level event dirs (`hooks/<event-name>/<script>`) are first-class.**
+  System hooks organize by harness event (`session-start/`, `pre-tool-use/`, …).
+  Install names stay the file basename. Dirs with top-level scripts expand into
+  individual hooks; fixture-only dirs remain directory bundles. Manifest `script:`
+  may be a relative path under `hooks/`. Source: `apps/cli/src/lib/hooks.ts`,
+  `apps/cli/src/lib/staleness/writers/sources.ts`, `apps/cli/src/lib/versions.ts`,
+  `apps/cli/src/lib/__tests__/hooks-nested-groups.test.ts`.
+
+- **`agents humans show owner [--json]`** — new command to display the owner config from `~/.agents/humans.yaml`. The file is written automatically on first run when `notify.owner` exists in `agents.yaml`. Source: `apps/cli/src/lib/humans.ts`, `apps/cli/src/commands/humans.ts`.
+
+- **`humans.yaml` — typed, versioned owner config.** `~/.agents/humans.yaml` (`version: 1`) now stores owner identity (name, timezone, quiet hours, severity), notification channels, and escalation policy. `notify.owner` in `agents.yaml` is migrated into it on first run and the `notify.owner` key is removed from `agents.yaml`; unrelated keys are preserved. `agents send --to owner` / `agents notify` prefer `humans.yaml` with a fallback to `agents.yaml` during the migration window. Source: `apps/cli/src/lib/humans.ts`, `apps/cli/src/commands/humans.ts`, `apps/cli/src/lib/migrate.ts`.
+
+- **`agents memory` ignores `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and `MEMORY.md`.** These rule/index files lived in `~/.agents/memory/` but were incorrectly surfaced as memory facts. `isFactFile()` now excludes them by name (case-insensitive). Source: `apps/cli/src/lib/memory.ts`.
+
+- **Permissions write path fixed — `groups/` subdirectory.** `installPermissionSet`, `removePermissionSet`, and `savePermissionSet` now all write to the `groups/` subdirectory (matching `discoverPermissionGroups()` which already reads from `groups/`). Source: `apps/cli/src/lib/permissions.ts`.
+
+- **Stop eagerly creating webhooks directories.** `ensureAgentsDir()` no longer creates `~/.agents/webhooks/` or `~/.agents/.system/webhooks/` on startup — both dirs are created on first actual use. Source: `apps/cli/src/lib/state.ts`.
+
+- **Terminals canonically under `.cache/`.** The stale migration comment that blocked `terminals/` from moving to `~/.agents/.cache/terminals/` is replaced by the actual move. Factory already writes to `.cache/terminals/` (`foreman.registry.ts:9`), so no app-level change is needed. Source: `apps/cli/src/lib/migrate.ts`.
+
+- **Menu bar warns when a device is under high load (local or remote).** The
+  agents-cli menu bar now shows a `⚠ <device> — high load N%` row in NEEDS YOU when
+  a machine's load or memory crosses the `headroom()` "loaded" threshold (≥75%), and
+  a red `✕` when critical. The local machine is probed natively via `getloadavg`
+  (zero subprocess); fleet peers come from the daemon-warmed `.fleet-stats.json`
+  cache with a freshness guard — never the slow `agents doctor` path. Action-required
+  rows are now emphasized so items that need you stand out. Source:
+  `apps/cli/menubar/Sources/MenubarHelper/LocalState.swift`,
+  `apps/cli/menubar/Sources/MenubarHelper/StatusItemController.swift`.
+
+- **Projects canonicalization contract.** `agents projects import --from-factory` / `--min-confidence` / `--all` are gone; import is `--from-linear` only, and `~/.agents/factory/projects.json` is never read or migrated. `agents projects list --json` returns definitions only (zero session scan / SSH); `--with-agents` is an explicit opt-in for local active counts. New `agents projects save --json` reads one complete `ProjectDef` from stdin, validates, writes atomically under `~/.agents/projects/`, and prints the saved def. `agents projects rm <name> --json` returns machine-readable success/error. Factory's `managedProjects.ts` shells only through `agents projects list|save|rm` — never reads or writes project YAML/JSON directly, never seeds or migrates legacy Factory state; errors stay explicit for inline UI display. Source: `apps/cli/src/commands/projects.ts`, `apps/cli/src/lib/projects.ts`, `apps/factory/src/core/managedProjects.ts`, `apps/cli/docs/11-projects.md`.
+
+- **`ProjectDef` YAML gains `dispatch` block and `linear.name`.** `~/.agents/projects/<name>.yaml` now accepts a `dispatch:` block (`enabled`, `maxAgents`, `provider`, `host`) that opts a project into auto-dispatch and is read directly by `agents __auto-dispatch` — previously these fields lived only in Factory's own registry. `linear.name` stores the Linear project display name alongside the existing `projectId` and `url`. Both fields are optional; existing YAMLs are unchanged. Source: `apps/cli/src/lib/projects.ts`, `apps/cli/src/lib/auto-dispatch.ts`.
+
+- **`agents secrets` no longer pops a generic "Agents CLI needs to authenticate" Touch ID sheet on every agent launch.** `listBundles` — which runs on essentially every secrets touch (session-title generation, `agents devices list`, every `agents run`, every remote launch that resolves secrets on the host) — could not ask the keychain for just the bundle *metadata* items: with hashed service names (#316) those names are opaque, so it fell back to a **broad `agents-cli.` keychain scan** that also matched the ACL'd secret *value* items. On machines where a bundle carries a biometric ACL (e.g. a `hold`-tier bundle holding an SSN or a password), macOS evaluated that value ACL during the attributes-only scan and raised a **generic, context-less** Touch ID prompt — on every launch, so a busy fleet felt like a machine-wide bombardment. Neither `kSecUseAuthenticationUIFail` nor `LAContext.interactionNotAllowed` can list the no-ACL items while skipping the ACL'd ones (both return nothing), so the fix is to stop doing the broad scan: a per-machine **no-ACL metadata-name index** (opaque hashes only, in the regenerable helpers dir — it leaks nothing #316 didn't) is read as a silent file instead. The write paths keep it current; an absent/stale index self-heals by rebuilding from the one-time scan, and a missing entry only makes `secrets list` cosmetically incomplete — it never affects a resolve-by-name. Your sensitive bundles keep their biometric gate on real value reads; only the bundle *listing* goes silent. Source: `apps/cli/src/lib/secrets/bundles.ts`.
+
+## 1.22.15
+
+- **Separate routine definitions from device activation (#2023).** Enable a routine by listing its name in `~/.agents/devices/<hostname>/agents.yaml`; built-in Watchdog setup and `watchdog on|off` now update that host-owned manifest without rewriting the routine definition. Source: `apps/cli/src/lib/routine-activation.ts`, `apps/cli/src/commands/setup-watchdog.ts`.
+
+- **`agents devices list` no longer shows the "Leased boxes" section by default — it moves behind a new `--all` flag (RUSH-2190).** Loading the section routes through crabbox's bundle auto-detect, which scans the keychain and can raise a macOS Touch ID sheet *after* the device table has printed, hanging non-interactive callers (observed: the `.agents-system` SessionStart topology hook). The default list now renders only registered devices, which are reachable without any secrets; the load/mem/headroom columns are unchanged (the stats probe was already broker-only). `agents devices list --all` restores the section; `--no-stats` remains a hard "instant, no provider calls" opt-out even with `--all`. Source: `apps/cli/src/commands/ssh.ts` (`showLeasedBoxesSection`), `apps/cli/src/commands/ssh.test.ts`.
+
+- **Install: `plugin:` prefix on the unified path (Phase 5 packaging).**
+  `agents install plugin:<spec>` uses the same grammar and trust gate as
+  `agents plugins install` (`name@url`, local path, `--allow-exec-surfaces`).
+  Specialized verbs still work; `agents install` is the one add path for mcp,
+  skill, plugin, and GitHub sources. Source: `apps/cli/src/commands/packages.ts`,
+  `apps/cli/src/lib/registry.ts`.
+
 ## 1.22.14
 
 - **`agents secrets view <bundle> --reveal` now resolves a locked keychain bundle

package/README.md

@@ -341,9 +341,11 @@ agents sessions resume                     # multi-select; packs two sessions pe
 agents sessions resume "auth middleware"   # pre-filter the pool, then choose
 agents sessions resume --tmux              # into persistent tmux — survives editor restarts
 agents sessions resume --host zion --tmux  # resume on another machine over SSH
+agents resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897  # original harness/version/device/mode
+agents run auto --resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897  # adapt if its account is unavailable
 ```
 
-`agents sessions resume` reopens sessions in whatever terminal you're in -- auto-detected across iTerm, Ghostty, tmux, and the VSCodium agent-terminal, or forced with `--iterm` / `--ghostty` / `--tmux` / `--vscodium`. Back them with **tmux** and the runs turn durable: detach, close your editor, reboot the GUI -- the session is still alive to `agents tmux attach`. The whole `agents tmux` subsystem (persistent multiplexer sessions that survive editor restarts and can be shared with other tools) sits underneath.
+`agents sessions resume` reopens several sessions in whatever terminal you're in -- auto-detected across iTerm, Ghostty, tmux, and the VSCodium agent-terminal, or forced with `--iterm` / `--ghostty` / `--tmux` / `--vscodium`. `agents resume <id>` resumes one session without requiring you to name its harness: exact IDs take a local SQLite fast path, then resolve fleet-wide and restore the source harness, version, device, cwd, and recorded launch mode. Back them with **tmux** and the runs turn durable: detach, close your editor, reboot the GUI -- the session is still alive to `agents tmux attach`. The whole `agents tmux` subsystem (persistent multiplexer sessions that survive editor restarts and can be shared with other tools) sits underneath.
 
 ### Send an agent to the background — and bring it back
 
@@ -396,7 +398,7 @@ agents watchdog --nudge    # actually inject "Continue." into the stalled split
 agents watchdog --watch    # daemon loop: a tick every --interval
 ```
 
-`agents watchdog` detects a stalled session, resolves the *exact* terminal split it lives in (tmux, iTerm, VSCodium, or a raw pty), and injects a nudge -- `Continue.` by default, or set `--text`. It's dry by default; `--nudge` acts on a single tick, and `agents watchdog enable` flips global auto-nudge on so `--watch` injects on its own. Steer a single run with `agents watchdog policy <id> off | keep | handsoff`.
+`agents watchdog` detects a stalled session, resolves the *exact* terminal split it lives in (tmux, iTerm, VSCodium, or a raw pty), and injects a nudge -- `Continue.` by default, or set `--text`. It's dry by default; `--nudge` acts on a single tick, and `agents watchdog on|off` enables or disables the built-in routine on this device. `agents setup watchdog` chooses devices. Steer a single run with `agents watchdog policy <id> off | keep | handsoff`.
 
 A stalled session whose tail shows a hard account limit ("You've hit your weekly limit · resets …") is **rotated in place** instead of nudged: the watchdog gates on the same healthy-account selection `agents run auto` makes (zero healthy → one skip event per cooldown window, terminal untouched), injects the harness's exit sequence, relaunches `agents run auto --interactive --session-id <uuid>` in the *same* tab, then replays the old session's resume once the new TUI is live. Default on; `agents watchdog rotate off` disables it (nudging stays on).
 
@@ -921,11 +923,11 @@ agents routines run daily-digest       # Test it now, ignore the schedule
 agents routines logs daily-digest      # Last execution — status + report (add --full for raw stdout)
 agents routines stats                  # Run count, failed, missed, avg/p50/p95 duration — per job or all
 
-# Routines sync to every device; restrict to an allowlist with --devices
+# Definitions sync to every device; activation is stored per hostname
 agents routines add nightly-drain --schedule "0 3 * * *" --agent claude \
-  --devices yosemite-s0,mac-mini --prompt "Drain the local work queue"
+  --prompt "Drain the local work queue"
 
-agents routines devices nightly-drain --set yosemite-s0,mac-mini  # update allowlist
+agents routines devices nightly-drain --set yosemite-s0,mac-mini  # enable on both hosts
 agents routines list --host yosemite-s0                            # query another device
 
 # Signed webhook trigger: Linear issue labeled "agent" fires a routine

package/dist/commands/cloud.js

@@ -7,8 +7,7 @@ import { resolveProvider, getAllProviders, getDefaultProviderId } from '../lib/c
 import { insertTask, updateTaskStatus, getTaskById, listTasks as listStoredTasks, listActiveTasks } from '../lib/cloud/store.js';
 import { renderStream } from '../lib/cloud/stream.js';
 import { MissingTargetError, MAX_IMAGES_PER_DISPATCH } from '../lib/cloud/types.js';
-import { normalizeTriggerEvent, validateTrigger, writeJob, jobExists, GITHUB_TRIGGER_EVENTS } from '../lib/routines.js';
-import { machineId } from '../lib/machine-id.js';
+import { normalizeTriggerEvent, validateTrigger, writeJob, setJobEnabled, jobExists, GITHUB_TRIGGER_EVENTS } from '../lib/routines.js';
 import { emit } from '../lib/events.js';
 import { shareRuntimeEnv } from '../lib/share/config.js';
 /** Map a supported image file extension to its wire mimeType. Rejects anything else. */
@@ -310,16 +309,15 @@ Examples:
             };
             if (repoValues[0])
                 routine.repo = repoValues[0];
-            // --host with --on: the webhook-fired run places on that machine (the
-            // routine carries the placement, and firing pins to THIS device so a
-            // fleet of receivers can't each dispatch a duplicate).
+            // --host controls where the enabled local receiver dispatches the run.
+            // Device activation remains in this receiver's device manifest.
             if (options.host) {
                 routine.host = options.host;
                 if (options.remoteCwd)
                     routine.remoteCwd = options.remoteCwd;
-                routine.devices = [machineId()];
             }
             writeJob(routine);
+            setJobEnabled(routine.name, true);
             if (json) {
                 console.log(JSON.stringify({ ok: true, registered: routineName, trigger }, null, 2));
             }

package/dist/commands/exec.js

@@ -532,7 +532,7 @@ export function registerRunCommand(program) {
         .option('--headless', 'Force headless mode. Auto-enabled when a prompt is provided; pass explicitly to stay headless with no prompt (reads the prompt from stdin).', false)
         .option('--no-auth-check', 'Skip the pre-launch "looks logged out" warning on an interactive run (advisory; never blocks anyway). Also silenced by AGENTS_NO_AUTH_CHECK=1.')
         .option('-i, --interactive', 'Force interactive mode even when a prompt is provided. Mutually exclusive with --headless.')
-        .option('--resume [id]', 'Resume a previous conversation. Accepts a full or partial session id (prefix-matched against the index); omit the id to pick from recent sessions interactively. Resumes under the version that started the session. claude/codex resume natively; other agents replay via a /continue first message. Pair with a prompt to continue headlessly.')
+        .option('--resume [id]', 'Resume a previous conversation. Full IDs resolve locally first, then fleet-wide. Claude, Codex, Grok, Kimi, Droid, and Cursor use version-gated native resume; other agents replay via /continue. Pair with a prompt to continue headlessly.')
         .option('--session-id <id>', 'Force a NEW conversation to use this exact session UUID (Claude only). This CREATES a session — to resume an existing one, use --resume.')
         .option('--name <slug>', 'Name the run — seeds the session label so it shows up as `<name>` in `agents sessions` and resolves by it (and `agents hosts logs <name>` for --host runs) instead of an opaque id. An agent-generated title later refines the label; your name shows until then. Optional.')
         .option('--notify', 'Post a desktop notification when a headless run finishes. Fired by this process on exit, so it survives whatever launched the run (the menu bar dispatching it, a terminal you closed).')
@@ -668,7 +668,7 @@ export function registerRunCommand(program) {
 
       Fallback: --fallback codex,antigravity retries on rate-limit failure via /continue handoff. Each entry accepts @version.
 
-      Resume: --resume <id> continues a prior conversation (full or partial id; omit to pick interactively). claude/codex resume natively; others replay via a /continue first message. Add a prompt to continue headlessly.
+      Resume: --resume <id> resolves full IDs locally first, then fleet-wide, and restores the source version/device/mode. Claude, Codex, Grok, Kimi, Droid, and Cursor use version-gated native resume; others replay via /continue. agents resume <id> infers the harness too.
 
       Passthrough: everything after -- is forwarded verbatim to the underlying agent CLI.
         agents run kimi -- --plan --some-native-flag value
@@ -781,7 +781,89 @@ export function registerRunCommand(program) {
                 `Pin a concrete harness instead: agents run <harness>@<version>.`));
             process.exit(1);
         }
-        const autoHarnessRequested = normalizedAgentSpec === RUN_AUTO_KEYWORD;
+        let autoHarnessRequested = normalizedAgentSpec === RUN_AUTO_KEYWORD;
+        let resolvedResumeSource;
+        // Concrete resume ids resolve BEFORE placement. Full UUIDs take the local
+        // SQLite fast path; only a local miss fans out to the fleet. This lets a
+        // command entered on zion discover that the owning version-home is on a
+        // worker, while a command entered on that worker never pays for SSH.
+        if (typeof options.resume === 'string' && options.resume.trim()) {
+            const selector = options.resume.trim();
+            const injectedSource = (() => {
+                try {
+                    const parsed = JSON.parse(process.env.AGENTS_RESUME_SOURCE_JSON ?? 'null');
+                    return parsed?.id === selector ? parsed : undefined;
+                }
+                catch {
+                    return undefined;
+                }
+            })();
+            delete process.env.AGENTS_RESUME_SOURCE_JSON;
+            const outcome = injectedSource
+                ? { kind: 'resolved', session: injectedSource }
+                : await (await import('./sessions.js')).resolveSessionMetadataValue(selector);
+            if (outcome.kind === 'partial') {
+                console.error(chalk.red(`Could not resolve session while these devices were unavailable: ${outcome.failedPeers.join(', ')}`));
+                process.exit(2);
+            }
+            if (outcome.kind === 'not-found') {
+                console.error(chalk.red(`No session matching "${selector}".`));
+                process.exit(1);
+            }
+            if (outcome.kind === 'ambiguous') {
+                console.error(chalk.red(`"${selector}" matches ${outcome.candidates.length} sessions. Pass the full session id.`));
+                process.exit(1);
+            }
+            resolvedResumeSource = outcome.session;
+            const [requestedAgent, requestedVersion] = normalizedAgentSpec.split('@');
+            if (!autoHarnessRequested && requestedAgent !== resolvedResumeSource.agent) {
+                console.error(chalk.red(`Session ${resolvedResumeSource.shortId} belongs to ${resolvedResumeSource.agent}, not ${requestedAgent}. ` +
+                    `Use: agents resume ${resolvedResumeSource.id}`));
+                process.exit(1);
+            }
+            if (!autoHarnessRequested && requestedVersion && requestedVersion !== resolvedResumeSource.version) {
+                console.error(chalk.red(`Session ${resolvedResumeSource.shortId} started with ${resolvedResumeSource.agent}@${resolvedResumeSource.version ?? 'unknown'}, ` +
+                    `not @${requestedVersion}.`));
+                process.exit(1);
+            }
+            // Omitted --mode inherits the effective source mode. Commander keeps
+            // the normal new-run default as a real value, so consult its provenance
+            // rather than mistaking the default for an explicit override.
+            if (command.getOptionValueSource('mode') === 'default') {
+                if (resolvedResumeSource.mode)
+                    options.mode = resolvedResumeSource.mode;
+                else if (!options.quiet)
+                    process.stderr.write(chalk.yellow(`[agents] session ${resolvedResumeSource.shortId} predates stored launch modes; using --mode ${options.mode}\n`));
+            }
+            const { machineId } = await import('../lib/machine-id.js');
+            const sourceMachine = resolvedResumeSource.machine;
+            const explicitPlacement = hostTargetGiven(options).length > 0;
+            if (sourceMachine && sourceMachine !== machineId() && !explicitPlacement) {
+                options.host = sourceMachine;
+            }
+            else if (!autoHarnessRequested && sourceMachine && sourceMachine !== machineId() && explicitPlacement && !hostTargetGiven(options).includes(sourceMachine)) {
+                console.error(chalk.red(`Strict resume must run on ${sourceMachine}, where session ${resolvedResumeSource.shortId} is owned. ` +
+                    `Use agents run auto --resume ${resolvedResumeSource.id} to hand off elsewhere.`));
+                process.exit(1);
+            }
+            // On the owning machine, `auto` first asks the existing account router
+            // whether the exact source version is healthy. If it is, native resume
+            // wins. If not, keep `auto` so the normal harness/account router selects
+            // a healthy local target and the later resume block performs /continue.
+            if (autoHarnessRequested && (!sourceMachine || sourceMachine === machineId())) {
+                const sourceAgent = resolvedResumeSource.agent;
+                if (sourceAgent in AGENTS && resolvedResumeSource.version) {
+                    const { resolveRunVersion } = await import('../lib/rotate.js');
+                    const health = await resolveRunVersion(sourceAgent, 'available', resolvedResumeSource.cwd ?? process.cwd());
+                    if (!health.exhausted && health.version === resolvedResumeSource.version) {
+                        normalizedAgentSpec = `${sourceAgent}@${resolvedResumeSource.version}`;
+                        autoHarnessRequested = false;
+                        if (!options.quiet)
+                            process.stderr.write(chalk.gray(`[agents] auto resume → native ${normalizedAgentSpec} on ${sourceMachine ?? machineId()}\n`));
+                    }
+                }
+            }
+        }
         if (autoHarnessRequested) {
             // `auto` is reserved. If a future harness registers that id, the
             // keyword collides — fail loud rather than silently shadow the harness.
@@ -797,7 +879,7 @@ export function registerRunCommand(program) {
             // Host layer: with no explicit --host/--device, default to the
             // affinity pick. Skipped on a host-dispatched run — its dispatcher
             // already resolved this layer (see runAutoDefaultsToAffinity).
-            if (runAutoDefaultsToAffinity(options))
+            if (!resolvedResumeSource && runAutoDefaultsToAffinity(options))
                 options.device = 'auto';
         }
         // --device auto / --host auto (and deprecated --smart): affinity-pick host.
@@ -2013,7 +2095,8 @@ export function registerRunCommand(program) {
             // AgentId is wider than SessionAgentId (amp/kiro/goose/copilot keep no transcripts);
             // those simply yield no matches and fall through to the not-found error.
             const sessionAgent = agent;
-            await discoverSessions({ agent: sessionAgent, version });
+            if (!resolvedResumeSource)
+                await discoverSessions({ agent: sessionAgent, version });
             // Resume is interactive unless a follow-on prompt makes it headless.
             const wantsInteractive = resolveInteractive({ interactive: options.interactive, headless: options.headless, prompt });
             const idArg = typeof options.resume === 'string' ? options.resume.trim() : '';
@@ -2024,9 +2107,9 @@ export function registerRunCommand(program) {
             catch {
                 scopeCwd = cwd;
             }
-            let session;
+            let session = resolvedResumeSource;
             if (idArg) {
-                let matches = findSessionsById(idArg, { agent: sessionAgent, version, cwd: scopeCwd });
+                let matches = session ? [session] : findSessionsById(idArg, { agent: sessionAgent, version, cwd: scopeCwd });
                 if (matches.length === 0) {
                     const wide = findSessionsById(idArg, { agent: sessionAgent, version });
                     if (wide.length > 0) {
@@ -2076,10 +2159,12 @@ export function registerRunCommand(program) {
                 session = picked.session;
                 forceInteractive = true; // bare resume always lands in the agent's TUI
             }
-            // Pin to the chosen session's own version (the isolated HOME the transcript
-            // lives in) and route by tier.
-            version = session.version;
-            if (nativeResume(agent)) {
+            // Native resume is valid only for the source harness + exact isolated
+            // version. `auto` may have selected another healthy harness/account; in
+            // that case keep the target version and hand off through /continue.
+            const canResumeNatively = session.agent === agent && nativeResume(agent, session.version);
+            if (canResumeNatively) {
+                version = session.version;
                 resumeNative = true;
                 resumeSessionId = session.id;
                 // Native `--resume` (claude/codex) resolves the transcript relative to the

package/dist/commands/humans.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `agents humans` — owner identity and notification channel management.
+ *
+ * Reads from ~/.agents/humans.yaml (created by migration from owner.md and
+ * agents.yaml notify.owner). Provides inspection commands for the current
+ * owner config.
+ */
+import type { Command } from 'commander';
+/** Register the `agents humans` command tree. */
+export declare function registerHumansCommands(program: Command): void;

package/dist/commands/humans.js

@@ -0,0 +1,91 @@
+/**
+ * `agents humans` — owner identity and notification channel management.
+ *
+ * Reads from ~/.agents/humans.yaml (created by migration from owner.md and
+ * agents.yaml notify.owner). Provides inspection commands for the current
+ * owner config.
+ */
+import { setHelpSections } from '../lib/help.js';
+import { readHumans, getOwnerFromHumans } from '../lib/humans.js';
+/** Register the `agents humans` command tree. */
+export function registerHumansCommands(program) {
+    const humansCmd = program
+        .command('humans')
+        .description('Inspect owner identity and notification channel config (humans.yaml)');
+    setHelpSections(humansCmd, {
+        examples: `
+      # Show owner identity and channel config as JSON
+      agents humans show owner --json
+
+      # Show owner identity in human-readable form
+      agents humans show owner
+    `,
+        notes: `
+      humans.yaml is the canonical owner identity file at ~/.agents/humans.yaml.
+      It is populated by migrating notify.owner from agents.yaml and frontmatter
+      from owner.md. Use \`agents humans show owner\` to inspect the current config.
+    `,
+    });
+    const showCmd = humansCmd
+        .command('show')
+        .description('Show config from humans.yaml');
+    setHelpSections(showCmd, {
+        examples: `
+      agents humans show owner
+      agents humans show owner --json
+    `,
+    });
+    showCmd
+        .command('owner')
+        .description('Show the configured owner identity and notification channels')
+        .option('--json', 'Output as JSON')
+        .action((opts) => {
+        const humans = readHumans();
+        if (!humans) {
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(null) + '\n');
+            }
+            else {
+                process.stderr.write('humans.yaml not found — run `agents` once to trigger migration\n');
+                process.exitCode = 1;
+            }
+            return;
+        }
+        const owner = getOwnerFromHumans();
+        if (opts.json) {
+            process.stdout.write(JSON.stringify(owner ?? null, null, 2) + '\n');
+        }
+        else {
+            if (!owner) {
+                process.stdout.write('No owner configured in humans.yaml\n');
+                return;
+            }
+            if (owner.name)
+                process.stdout.write(`Name:     ${owner.name}\n`);
+            if (owner.timezone)
+                process.stdout.write(`Timezone: ${owner.timezone}\n`);
+            if (owner.quiet_hours)
+                process.stdout.write(`Quiet:    ${owner.quiet_hours}\n`);
+            if (owner.default_severity)
+                process.stdout.write(`Severity: ${owner.default_severity}\n`);
+            if (owner.notify) {
+                process.stdout.write(`Notify:   channel=${owner.notify.channel} to=${owner.notify.to}\n`);
+            }
+            if (owner.channels?.length) {
+                process.stdout.write(`Channels:\n`);
+                for (const ch of owner.channels) {
+                    const extra = [ch.transport, ch.intrusive ? 'intrusive' : null].filter(Boolean).join(', ');
+                    process.stdout.write(`  - ${ch.id}${extra ? ` (${extra})` : ''}\n`);
+                }
+            }
+            if (owner.policy) {
+                process.stdout.write(`Policy:\n`);
+                for (const [sev, channels] of Object.entries(owner.policy)) {
+                    if (Array.isArray(channels) && channels.length) {
+                        process.stdout.write(`  ${sev}: ${channels.join(', ')}\n`);
+                    }
+                }
+            }
+        }
+    });
+}

package/dist/commands/packages.js

@@ -22,7 +22,7 @@ import { discoverWorkflowsFromRepo, installWorkflowCentrally, } from '../lib/wor
 import { discoverSubagentsFromRepo, installSubagentCentrally, } from '../lib/subagents.js';
 import { discoverPermissionsFromRepo, installPermissionSet, } from '../lib/permissions.js';
 import { listInstalledVersions, resolveConfiguredAgentTargets, syncResourcesToVersion, } from '../lib/versions.js';
-import { isInteractiveTerminal, isPromptCancelled, parseCommaSeparatedList, requireDestructiveArg, requireInteractiveSelection, resolveInstalledAgentTargetsAutoInstalling, } from './utils.js';
+import { formatPath, isInteractiveTerminal, isPromptCancelled, parseCommaSeparatedList, requireDestructiveArg, requireInteractiveSelection, resolveInstalledAgentTargetsAutoInstalling, } from './utils.js';
 import { itemPicker } from '../lib/picker.js';
 import { registerMcpCommandToTargets, discoverMcpConfigsFromRepo, installMcpConfigCentrally, } from '../lib/mcp.js';
 export function buildMcpPackageCommand(pkg) {
@@ -435,37 +435,30 @@ the sha256 in the index and abort on mismatch.
     // ==========================================================================
     program
         .command('install <identifier>')
-        .description('Install a package by registry name (mcp:notion), GitHub URL (gh:user/repo), or skill identifier')
+        .description('Install a package: mcp:, skill:, plugin:, or GitHub (gh:user/repo) — one install path (Phase 5)')
         .option('-a, --agents <list>', 'Targets: claude, codex@0.116.0, or cursor@default')
         .option('--types <list>', 'When source is a repo: comma-separated resource types to install (skills,workflows,commands,hooks,permissions,subagents,mcp)')
         .option('--names <list>', 'When source is a repo: comma-separated resource names within the selected types')
         .option('-y, --yes', 'Auto-install any missing agent versions without prompting')
+        .option('--allow-exec-surfaces', 'With plugin: allow plugins that ship hooks/mcp/bin (same as agents plugins install)')
         .addHelpText('after', `
-Install resolves the package type (MCP server, skill, command, hook) and installs to the specified agents. Packages can come from registries (mcp:, skill:), GitHub (gh:user/repo), or direct URLs.
+Install is the unified add path (Phase 5 packaging). Prefix the identifier:
+
+  mcp:<name>       MCP server from a registry
+  skill:<name>     skill from a registry (or gh: fallback)
+  plugin:<spec>    plugin — same grammar as agents plugins install (name@url or path)
+  gh:user/repo     clone a DotAgents / multi-resource repo and install selected types
 
 Examples:
-  # Install an MCP server from a registry
   agents install mcp:notion --agents claude
-
-  # Install skills and commands from GitHub
+  agents install skill:animator --agents claude,codex
+  agents install plugin:my-plugin@https://github.com/user/my-plugin.git
+  agents install plugin:~/Projects/rush-toolkit
   agents install gh:anthropics/skills --agents codex,claude
-
-  # Install using GitHub shorthand
-  agents install gh:user/repo --agents claude@2.1.112
-
-  # Install only specific resource types from a multi-resource repo
   agents install gh:phnx-labs/.agents-system --types skills,workflows --agents claude@all
 
-  # Install specific resources by name
-  agents install gh:phnx-labs/.agents-system --types skills --names animator,composer --agents claude@all
-
-  # Install to all installed agents (uses defaults or prompts)
-  agents install mcp:postgres
-
-When to use:
-  - After search: 'agents search notion' then 'agents install mcp:notion'
-  - Team setup: 'agents install gh:team/resources' to sync everyone's tooling
-  - Quick MCP add: 'agents install mcp:<name>' when you know the package name
+Specialized verbs still work (agents plugins install, agents skills add) and
+delegate to the same underlying installers.
 `)
         .action(async (identifier, options) => {
         const spinner = ora('Resolving package...').start();
@@ -473,10 +466,85 @@ When to use:
             const resolved = await resolvePackage(identifier);
             if (!resolved) {
                 spinner.fail('Package not found');
-                console.log(chalk.gray('\nTip: Use explicit prefix (mcp:, skill:, gh:) or check the identifier.'));
+                console.log(chalk.gray('\nTip: Use explicit prefix (mcp:, skill:, plugin:, gh:) or check the identifier.'));
                 process.exit(1);
             }
             spinner.succeed(`Found ${resolved.type} package`);
+            if (resolved.type === 'plugin') {
+                spinner.stop();
+                const spec = resolved.pluginSpec ?? resolved.source;
+                console.log(chalk.gray(`Installing plugin from: ${spec}`));
+                const { installPlugin, getPlugin, inspectPluginCapabilities, pluginCapabilityLabels, parseInstallSpec, checkPluginDependencies, hasPluginExecSurfaces, pluginSupportsAgent, syncPluginToVersion, pluginResourceGroups, } = await import('../lib/plugins.js');
+                const { listInstalledVersions, getGlobalDefault, getVersionHomePath, syncResourcesToVersion } = await import('../lib/versions.js');
+                const { agentLabel } = await import('../lib/agents.js');
+                let name;
+                let root;
+                try {
+                    const result = await installPlugin(spec);
+                    name = result.name;
+                    root = result.root;
+                }
+                catch (err) {
+                    console.log(chalk.red(`Install failed: ${err.message}`));
+                    process.exit(1);
+                }
+                const plugin = getPlugin(name);
+                if (!plugin) {
+                    console.log(chalk.red(`Installed but could not load plugin '${name}'`));
+                    process.exit(1);
+                }
+                const capabilities = inspectPluginCapabilities(root);
+                const allowExec = options.allowExecSurfaces === true;
+                if (hasPluginExecSurfaces(capabilities) && !allowExec) {
+                    const source = parseInstallSpec(spec).source;
+                    console.error(chalk.red('Install refused: plugin ships executable surfaces:'));
+                    for (const label of pluginCapabilityLabels(capabilities)) {
+                        console.error(`  ${label}`);
+                    }
+                    console.error(`Re-run with --allow-exec-surfaces if you trust the source: ${source}@HEAD`);
+                    fs.rmSync(root, { recursive: true, force: true });
+                    process.exit(1);
+                }
+                const missingDeps = checkPluginDependencies(plugin.manifest);
+                if (missingDeps.length > 0) {
+                    console.log(chalk.yellow(`Warning: missing dependencies: ${missingDeps.join(', ')}`));
+                    console.log(chalk.gray('Install them with: agents install plugin:<name>@<source>'));
+                }
+                // Same sync loop as `agents plugins install` (default version per harness).
+                console.log();
+                let synced = 0;
+                for (const agentId of capableAgents('plugins')) {
+                    if (!pluginSupportsAgent(plugin, agentId))
+                        continue;
+                    const versions = listInstalledVersions(agentId);
+                    if (versions.length === 0)
+                        continue;
+                    const defaultVer = getGlobalDefault(agentId);
+                    const targetVersions = defaultVer ? [defaultVer] : [versions[versions.length - 1]];
+                    for (const version of targetVersions) {
+                        const didSync = allowExec
+                            ? syncPluginToVersion(plugin, agentId, getVersionHomePath(agentId, version), {
+                                allowExecSurfaces: true,
+                            }).success
+                            : syncResourcesToVersion(agentId, version, { plugins: [name] }).plugins.length > 0;
+                        if (didSync) {
+                            console.log(chalk.green(`  Synced to ${agentLabel(agentId)}@${version}`));
+                            synced++;
+                        }
+                    }
+                }
+                if (synced === 0) {
+                    console.log(chalk.gray('  No supported agent versions installed — run "agents use <agent>@<version>" to sync.'));
+                }
+                console.log(chalk.bold(`\nInstalled ${plugin.name} v${plugin.manifest.version} to ${formatPath(root)}`));
+                const groups = pluginResourceGroups(plugin);
+                if (groups.length > 0) {
+                    for (const g of groups) {
+                        console.log(chalk.gray(`  ${g.label}: ${g.items.slice(0, 8).join(', ')}${g.items.length > 8 ? '…' : ''}`));
+                    }
+                }
+                return;
+            }
             if (resolved.type === 'mcp') {
                 // Install MCP server
                 const entry = resolved.mcpEntry;

package/dist/commands/projects.d.ts

@@ -24,11 +24,8 @@ export declare function formatFleetSkippedNote(skipped: string[]): string;
  *
  * `stderr: 'ignore'` is load-bearing, not tidiness. A checkout with no origin
  * makes git print `error: No such remote 'origin'` on ITS stderr, which is the
- * terminal's — the catch below never sees it. That was invisible while this was
- * called once from `add` inside a real repo, and became noise the moment
- * `import --from-factory` started calling it per row: importing 12 registry
- * rows printed two raw git errors between the progress lines. Absence of a
- * remote is an expected answer here (`undefined`), not something to report.
+ * terminal's — the catch below never sees it. Absence of a remote is an
+ * expected answer here (`undefined`), not something to report.
  */
 export declare function originSlug(cwd: string): string | undefined;
 /** One `projects list` row, pre-render. */