@phnx-labs/agents-cli 1.22.15 → 1.22.16

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # 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`.

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
 

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/resume.d.ts

@@ -0,0 +1,17 @@
+import type { Command } from 'commander';
+interface ResumeOptions {
+    mode?: string;
+    interactive?: boolean;
+    headless?: boolean;
+    cwd?: string;
+    quiet?: boolean;
+}
+/** Translate `agents resume <id>` to the canonical `agents run` surface after
+ * resolving the source identity. The run command remains the only executor. */
+export declare function buildResumeRunArgs(session: {
+    id: string;
+    agent: string;
+    version?: string;
+}, prompt: string | undefined, options: ResumeOptions): string[];
+export declare function registerResumeCommand(program: Command): void;
+export {};

package/dist/commands/resume.js

@@ -0,0 +1,80 @@
+/** Strict session resume convenience command. */
+import { spawn } from 'child_process';
+import chalk from 'chalk';
+import { setHelpSections } from '../lib/help.js';
+import { resolveSessionMetadataValue } from './sessions.js';
+/** Translate `agents resume <id>` to the canonical `agents run` surface after
+ * resolving the source identity. The run command remains the only executor. */
+export function buildResumeRunArgs(session, prompt, options) {
+    const spec = session.version ? `${session.agent}@${session.version}` : session.agent;
+    const args = ['run', spec, ...(prompt === undefined ? [] : [prompt]), '--resume', session.id];
+    if (options.mode)
+        args.push('--mode', options.mode);
+    if (options.interactive)
+        args.push('--interactive');
+    if (options.headless)
+        args.push('--headless');
+    if (options.cwd)
+        args.push('--cwd', options.cwd);
+    if (options.quiet)
+        args.push('--quiet');
+    return args;
+}
+export function registerResumeCommand(program) {
+    const cmd = program
+        .command('resume <session-id> [prompt]')
+        .description('Resume a session with its original harness, version, device, account, cwd, and mode')
+        .option('-m, --mode <mode>', 'Override the recorded launch mode')
+        .option('-i, --interactive', 'Resume interactively even when a prompt is provided')
+        .option('--headless', 'Resume headlessly (a prompt is required)')
+        .option('--cwd <path>', 'Override the recorded working directory')
+        .option('-q, --quiet', 'Suppress routing banners')
+        .action(async (sessionId, prompt, options) => {
+        const outcome = await resolveSessionMetadataValue(sessionId.trim());
+        if (outcome.kind === 'partial') {
+            console.error(chalk.red(`Could not resolve session while these devices were unavailable: ${outcome.failedPeers.join(', ')}`));
+            process.exitCode = 2;
+            return;
+        }
+        if (outcome.kind === 'not-found') {
+            console.error(chalk.red(`No session matching "${sessionId}".`));
+            process.exitCode = 1;
+            return;
+        }
+        if (outcome.kind === 'ambiguous') {
+            console.error(chalk.red(`"${sessionId}" matches ${outcome.candidates.length} sessions. Pass the full session id.`));
+            process.exitCode = 1;
+            return;
+        }
+        const args = buildResumeRunArgs(outcome.session, prompt, options);
+        const child = spawn(process.execPath, [process.argv[1], ...args], {
+            stdio: 'inherit',
+            env: {
+                ...process.env,
+                // Avoid repeating the fleet lookup in the delegated local `run`
+                // process. The value is metadata-only and is not forwarded over SSH;
+                // the owner performs its own local SQLite lookup.
+                AGENTS_RESUME_SOURCE_JSON: JSON.stringify(outcome.session),
+            },
+        });
+        const exitCode = await new Promise((resolve) => {
+            child.once('error', () => resolve(127));
+            child.once('exit', (code, signal) => resolve(code ?? (signal ? 1 : 0)));
+        });
+        process.exitCode = exitCode;
+    });
+    setHelpSections(cmd, {
+        examples: `
+      # Resume by full id
+      agents resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897
+
+      # Resume and continue headlessly
+      agents resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897 "finish the tests"
+
+      # Deliberately change permissions
+      agents resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897 --mode edit`,
+        notes: `
+      Full IDs resolve from the local session database first; an SSH fleet lookup runs only after a local miss.
+      Use agents run auto --resume <id> when the original account is unavailable and another harness may continue.`,
+    });
+}

package/dist/commands/sessions.d.ts

@@ -281,8 +281,8 @@ export declare function mergeLocalFirst(sessions: SessionMeta[], localMachine: s
  */
 export declare function serializeSessionsJson(sessions: SessionMeta[]): string;
 /** The intentionally small metadata contract emitted by `sessions --resolve`.
- * Transcript locations, extracted plans, account data, costs, and other indexed
- * payload stay local to the machine that owns them. */
+ * It includes only launch identity needed to route/resume. Transcript paths,
+ * extracted plans, costs, and content stay on the machine that owns them. */
 export declare function serializeResolvedSessionsJson(sessions: SessionMeta[]): string;
 /**
  * Whether the local machine's sessions belong in an `--active` view. Local is
@@ -636,12 +636,21 @@ export declare function fleetCandidatesByQuery(rows: SessionMeta[], query: strin
 export declare function metadataResolveForwardedArgs(selector: string, scope: Pick<SessionFilterOptions, 'agent' | 'project'>): string[];
 /** Build the local-only peer argv for a distributed tool search. */
 export declare function toolSearchForwardedArgs(argv: string[], hosts: string[]): string[];
-/** Resolution must fail closed when any selected peer did not answer. Choosing
- * from a partial fleet can turn an unseen candidate into a false unique match. */
+/** Resolution fails closed for prefixes/keywords when a peer did not answer.
+ * A full UUID is globally unique, so one exact hit is sufficient even when an
+ * unrelated registered device is offline. */
 export declare function metadataResolveOutcome(localMatches: SessionMeta[], remote: {
     sessions: SessionMeta[];
     unreachable: string[];
 }, selector: string): MetadataResolveOutcome;
+/** Reusable local-first resolver for `agents run --resume` and `agents resume`.
+ * Full UUIDs hit the local SQLite index without any SSH fan-out. */
+export declare function resolveSessionMetadataValue(selector: string, scope?: {
+    agent?: string;
+    project?: string;
+    local?: boolean;
+    hosts?: string[];
+}, deps?: Pick<FleetResolveDeps, 'gatherRemoteList'>): Promise<MetadataResolveOutcome>;
 /**
  * Locate a full session id or short id prefix across the online fleet and render it from the machine
  * that holds it. The local disk already missed; this fans `sessions <id> --json

package/dist/commands/sessions.js

@@ -814,8 +814,8 @@ export function serializeSessionsJson(sessions) {
     return JSON.stringify(serializable, null, 2) + '\n';
 }
 /** The intentionally small metadata contract emitted by `sessions --resolve`.
- * Transcript locations, extracted plans, account data, costs, and other indexed
- * payload stay local to the machine that owns them. */
+ * It includes only launch identity needed to route/resume. Transcript paths,
+ * extracted plans, costs, and content stay on the machine that owns them. */
 export function serializeResolvedSessionsJson(sessions) {
     const safe = sessions.map((session) => ({
         id: session.id,
@@ -826,6 +826,7 @@ export function serializeResolvedSessionsJson(sessions) {
         lastActivity: session.lastActivity,
         project: session.project,
         version: session.version,
+        mode: session.mode,
         label: session.label,
         topic: session.topic,
         machine: session.machine,
@@ -3447,6 +3448,7 @@ function modeFlag(mode) {
         return '--json';
     return undefined; // summary — the peer's default render
 }
+const FULL_SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /** Resolve a fleet sweep through the same canonical full-id / prefix resolver as
  * local lookups, then group copies by logical session id. Synced mirrors of one
  * session therefore stay one candidate even when several machines report them;
@@ -3501,19 +3503,46 @@ export function toolSearchForwardedArgs(argv, hosts) {
         args.push('--local');
     return args;
 }
-/** Resolution must fail closed when any selected peer did not answer. Choosing
- * from a partial fleet can turn an unseen candidate into a false unique match. */
+/** Resolution fails closed for prefixes/keywords when a peer did not answer.
+ * A full UUID is globally unique, so one exact hit is sufficient even when an
+ * unrelated registered device is offline. */
 export function metadataResolveOutcome(localMatches, remote, selector) {
-    if (remote.unreachable.length > 0) {
-        return { kind: 'partial', failedPeers: remote.unreachable };
-    }
     const candidates = fleetCandidatesByQuery([...localMatches, ...remote.sessions], selector);
+    if (FULL_SESSION_ID_RE.test(selector) && candidates.length === 1 && candidates[0].id.toLowerCase() === selector.toLowerCase()) {
+        return { kind: 'resolved', session: candidates[0].hits[0].session };
+    }
+    if (remote.unreachable.length > 0)
+        return { kind: 'partial', failedPeers: remote.unreachable };
     if (candidates.length === 0)
         return { kind: 'not-found' };
     if (candidates.length > 1)
         return { kind: 'ambiguous', candidates };
     return { kind: 'resolved', session: candidates[0].hits[0].session };
 }
+/** Reusable local-first resolver for `agents run --resume` and `agents resume`.
+ * Full UUIDs hit the local SQLite index without any SSH fan-out. */
+export async function resolveSessionMetadataValue(selector, scope = {}, deps = { gatherRemoteList }) {
+    const localMachine = machineId();
+    const includeLocal = !scope.hosts?.length || shouldIncludeLocal(scope.hosts, localMachine);
+    const indexed = includeLocal ? applyScopeFilters(querySessions(), scope) : [];
+    const localMatches = resolveIndexedMetadataRows(indexed, selector)
+        .map(session => ({ ...session, machine: session.machine || localMachine }));
+    if (FULL_SESSION_ID_RE.test(selector)) {
+        const localOutcome = metadataResolveOutcome(localMatches, { sessions: [], unreachable: [] }, selector);
+        if (localOutcome.kind === 'resolved')
+            return localOutcome;
+    }
+    if (scope.local === true)
+        return metadataResolveOutcome(localMatches, { sessions: [], unreachable: [] }, selector);
+    try {
+        const forwarded = metadataResolveForwardedArgs(selector, scope);
+        const remote = await deps.gatherRemoteList(forwarded, scope.hosts);
+        return metadataResolveOutcome(localMatches, remote, selector);
+    }
+    catch (error) {
+        return metadataResolveOutcome(localMatches, { sessions: [], unreachable: [error?.message ?? 'fleet fan-out'] }, selector);
+    }
+}
 /** Resolve one selector to indexed metadata across the fleet without reading or
  * rendering transcript events. A peer answering the parent sweep returns every
  * local candidate; the parent performs the one logical-session uniqueness gate. */
@@ -3529,18 +3558,7 @@ async function resolveSessionMetadata(selector, scope, deps = { gatherRemoteList
         process.stdout.write(serializeResolvedSessionsJson(localMatches));
         return;
     }
-    let remoteResult = { sessions: [], unreachable: [] };
-    if (scope.local !== true) {
-        try {
-            const forwarded = metadataResolveForwardedArgs(selector, scope);
-            const result = await deps.gatherRemoteList(forwarded, scope.hosts);
-            remoteResult = { sessions: result.sessions, unreachable: result.unreachable };
-        }
-        catch (error) {
-            remoteResult = { sessions: [], unreachable: [error?.message ?? 'fleet fan-out'] };
-        }
-    }
-    const outcome = metadataResolveOutcome(localMatches, remoteResult, selector);
+    const outcome = await resolveSessionMetadataValue(selector, scope, deps);
     if (outcome.kind === 'partial') {
         console.error(chalk.red(`Partial session resolution: ${outcome.failedPeers.join(', ')} did not answer.`));
         console.error(chalk.gray('No unique/no-match decision was made. Upgrade or reconnect every peer, then retry.'));

package/dist/index.js

@@ -94,7 +94,7 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadExport, loadPackages, loadRoutines, loadMonitors, loadProjects, loadRun, loadFork, loadDefaults, loadSet, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadSnapshot, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadFactory, loadUsage, loadCost, loadPerf, loadTrends, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadShare, loadSend, loadFeed, loadMailboxes, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadExport, loadPackages, loadRoutines, loadMonitors, loadProjects, loadRun, loadFork, loadDefaults, loadSet, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadSnapshot, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadFactory, loadUsage, loadCost, loadPerf, loadTrends, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadHumans, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadShare, loadSend, loadFeed, loadMailboxes, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { renderWhatsNew } from './lib/whats-new.js';
 import { getCliLaunch } from './lib/cli-entry.js';
@@ -980,6 +980,7 @@ async function registerAllEagerCommands() {
     await reg(loadAudit);
     await reg(loadWebhook);
     await reg(loadFunnel);
+    await reg(loadHumans);
     registerHqTombstoneCommand(program);
     await reg(loadFeed);
     await reg(loadMailboxes);
@@ -1177,7 +1178,7 @@ if (process.env.AGENTS_SKIP_MIGRATION !== '1') {
         // Bumping the suffix re-runs migrations for every user; binary releases that
         // don't change the schema must NOT re-run (they would destroy user content
         // when migration steps overlap with user-authored paths). See issue #20.
-        const sentinelValue = 'v14';
+        const sentinelValue = 'v15';
         let needRun = true;
         try {
             if (fs.existsSync(sentinel) && fs.readFileSync(sentinel, 'utf-8').trim() === sentinelValue) {

package/dist/lib/channels/send.d.ts

@@ -59,7 +59,10 @@ export type ResolveSendResult = {
 export declare function isOwnerAlias(to: string | undefined): boolean;
 /** Compose body + optional URL lines (skip urls already present in the body). */
 export declare function composeSendText(text: string, urls?: string[]): string;
-/** Read notify.owner; null when either field is missing. */
+/**
+ * Read the owner destination; humans.yaml is the primary source, agents.yaml
+ * notify.owner is the fallback. Returns null when neither is set.
+ */
 export declare function readOwnerDest(meta: Meta): {
     channel: string;
     to: string;