@phnx-labs/agents-cli 1.20.56 → 1.20.57

package/CHANGELOG.md

@@ -2,10 +2,15 @@
 
 ## Unreleased
 
+## 1.20.57
+
+- **`agents teams resume` / `agents teams message` — resume a stopped teammate with a follow-up message.** A teammate that ended its turn with more to do (PR open awaiting review, headless turn cap, a redirect after the fact) could not be reached: `agents message` resolves only *live* sessions, so a completed/stopped/failed teammate had no path back short of finishing the work by hand or spawning a fresh, context-less teammate. `teams resume <team> <teammate> <message>` re-enters the teammate's **own** session with the message as the next user turn, re-launching through the same backend (local process or remote host) in its original worktree and flipping it back to `running` so `teams status` tracks it live. `teams message` is the same command with automatic routing by reconciled status: a **running** teammate is steered via its mailbox (delivered at its next tool call, no re-launch); a **stopped** one is resumed; a **pending** one is refused with a pointer to `teams start`. Works for every harness — the resume delegates to `agents run --resume`, inheriting native resume for Claude/Codex and the universal `/continue` replay for the rest (OpenCode, Grok, Kimi, …); the resume target is the teammate's captured underlying session id (`remoteSessionId ?? agentId`), and a non-Claude teammate that died before emitting a session id is refused with a clear error rather than resumed into a fresh run. This also makes good on `teams stop`'s long-standing "can be restarted later" promise, which no code implemented. Source: `apps/cli/src/commands/teams.ts` (`message`/`resume` subcommands, `decideTeamMessageRoute`), `apps/cli/src/lib/teams/agents.ts` (`AgentManager.resumeTeammate`, resume-aware `buildRunArgv`/`buildCommand`/`launchProcess`/`launchRemoteProcess`).
+- **The always-on daemon now hosts the secrets broker (socket-first) — one supervised backbone instead of a separate service (#416, step 1).** `runDaemon()` binds the broker via the new `startHostedBroker()` before the scheduler and the heavy browser/session-sync services, so `agents secrets` resolves within ms of daemon start. It serves the same socket + wire protocol as the standalone broker (no `PROTOCOL_VERSION` bump — `agentGetSync`/`agentPing`/`agentAutoLoadSync` are unchanged), but is daemon-safe: no pid-guard, no `process.exit`/signal handlers/self-heal-exit (which would take the daemon down), TTL-eviction only. `ensureAgentRunning()` gains a Path 0 that prefers the daemon and falls back to the standalone `com.phnx-labs.agents-secrets-agent` launchd service, and the daemon only hosts when no broker is already reachable, so a live standalone broker is never orphaned. Retiring the standalone service (a gated `launchctl bootout` migration) and child-spawning the heavy services are the follow-on (#417). Source: `apps/cli/src/lib/secrets/agent.ts` (`startHostedBroker`, `ensureAgentRunning` Path 0, `agentPing` exported), `apps/cli/src/lib/daemon.ts` (`runDaemon` broker host + shutdown).
+- **Clarified `agents secrets list` POLICY column labels.** The column previously mixed policy names, runtime state, and implementation jargon (`daily · 7d left`, `always ask`, `never · NO ACL`). It now uses a consistent `policy · state` form: `daily`, `daily · held 7d`, `always · prompt`, and `never · no prompt`. Source: `apps/cli/src/commands/secrets.ts` (`renderPolicyCol`).
+
 ## 1.20.56
 
 - **Fix native routine schedulers rejecting the published CLI as a Bun virtual path.** Bun's standalone runtime reports the embedded `/$bunfs/root/agents` entry as existing at `process.argv[1]`, while the real physical executable lives at `process.execPath`. Daemon resolution now substitutes that physical executable before generating launchd/systemd manifests or detached launches; the existing virtual-path guard still rejects any virtual path that reaches supervision. Source: `apps/cli/src/lib/daemon.ts`.
-
 - **Fix: `agents teams`, `agents message`, and `agents profiles check` work again on the signed standalone binary (regression from #315).** When `agents` resolves to the bun-compiled Mach-O (shipped since 1.20.53), three self-spawn sites relaunched the CLI as `[process.execPath, process.argv[1], …]` — but under a bun standalone executable `process.argv[1]` is the virtual entry `/$bunfs/root/agents`, so the child died with `unknown command '/$bunfs/root/agents'` (or `/bin/sh: /$bunfs/root/agents: No such file or directory`). Every teammate spawned by a compiled-binary install failed in 0s. New shared `getAgentsInvocation(subArgs)` (`apps/cli/src/lib/daemon.ts`) resolves the real on-disk binary — mapping the `/$bunfs/root/…` virtual path to `process.execPath`, running a `.js` entry under node, and a native binary directly — and `teams/agents.ts`, `commands/message.ts`, and `commands/profiles.ts` route through it. Verified end-to-end: a teammate spawned by the freshly-compiled binary runs to `completed` with no `$bunfs` error. Source: `apps/cli/src/lib/daemon.ts` (`getAgentsInvocation`), `apps/cli/src/lib/teams/agents.ts`, `apps/cli/src/commands/{message,profiles}.ts`.
 ## 1.20.55
 

package/dist/commands/secrets.d.ts

@@ -66,8 +66,9 @@ export declare function buildSecretsExecEnv(parentEnv: NodeJS.ProcessEnv, secret
  * parse, so multi-line values are rejected rather than silently corrupted.
  */
 export declare function bundleEnvToDotenv(env: Record<string, string>): string;
-/** The POLICY column for `secrets list`: the prompt policy, plus a "Nh left"
- * hint when a `daily` bundle is currently held by the secrets-agent. `held`
+/** The POLICY column for `secrets list`: the prompt policy, plus a concise
+ * state hint. `daily` shows `held Nh` when the secrets-agent is currently
+ * caching the bundle; `always` and `never` show whether they prompt. `held`
  * maps bundle name → expiry epoch-ms (from agentStatus()). */
 export declare function renderPolicyCol(b: SecretsBundle, held?: Map<string, number>): string;
 /** Register the `agents secrets` command tree. */

package/dist/commands/secrets.js

@@ -387,17 +387,18 @@ function compactRemaining(expiresAt) {
         return `${hours}h`;
     return `${Math.round(hours / 24)}d`;
 }
-/** The POLICY column for `secrets list`: the prompt policy, plus a "Nh left"
- * hint when a `daily` bundle is currently held by the secrets-agent. `held`
+/** The POLICY column for `secrets list`: the prompt policy, plus a concise
+ * state hint. `daily` shows `held Nh` when the secrets-agent is currently
+ * caching the bundle; `always` and `never` show whether they prompt. `held`
  * maps bundle name → expiry epoch-ms (from agentStatus()). */
 export function renderPolicyCol(b, held) {
     // `never` is loud on purpose — it's the only tier with no user-presence gate.
     if (bundlePolicy(b) === 'never')
-        return chalk.red.bold('never · NO ACL');
+        return chalk.red.bold('never · no prompt');
     if (bundlePolicy(b) === 'always')
-        return chalk.yellow('always ask');
+        return chalk.yellow('always · prompt');
     const exp = held?.get(b.name);
-    return exp ? chalk.green(`daily · ${compactRemaining(exp)} left`) : chalk.gray('daily');
+    return exp ? chalk.green(`daily · held ${compactRemaining(exp)}`) : chalk.gray('daily');
 }
 /** Below this width the fixed date columns no longer fit; `list` uses cards. */
 const SECRETS_WIDE = 96;
@@ -657,7 +658,7 @@ export function registerSecretsCommands(program) {
             return;
         }
         // Cross-reference the secrets-agent so `daily` bundles that are currently
-        // held can show "· Nh left". Soft-fails to no hint if the broker is down.
+        // held can show "· held Nh". Soft-fails to no hint if the broker is down.
         const held = new Map();
         if (process.platform === 'darwin') {
             try {

package/dist/commands/teams.d.ts

@@ -6,7 +6,26 @@
  * dependencies between teammates, and clean up when work is done.
  */
 import type { Command } from 'commander';
-import { AgentManager } from '../lib/teams/agents.js';
+import { AgentManager, AgentStatus } from '../lib/teams/agents.js';
+/** Where `teams message`/`teams resume` routes a follow-up, by teammate status. */
+export type TeamMessageRoute = {
+    kind: 'steer';
+} | {
+    kind: 'resume';
+} | {
+    kind: 'need-message';
+} | {
+    kind: 'not-started';
+};
+/**
+ * Decide how a follow-up to a teammate is delivered from its reconciled status.
+ * Pure — the source of truth for the routing table, unit-tested without I/O.
+ *   - pending                       -> not-started (tell them to `teams start`)
+ *   - running     + message         -> steer (mailbox)
+ *   - stopped/etc + message         -> resume (re-enter session)
+ *   - any actionable + no message   -> need-message
+ */
+export declare function decideTeamMessageRoute(status: AgentStatus, hasMessage: boolean): TeamMessageRoute;
 /**
  * Register the generic cloud dispatcher — staged cloud teammates get
  * dispatched when their --after deps resolve, using repo/branch stored on

package/dist/commands/teams.js

@@ -3,7 +3,8 @@ import { die, relTime, truncate, isJsonMode, padRight } from '../lib/format.js';
 import * as fs from 'fs/promises';
 import { addHostOption } from '../lib/hosts/option.js';
 import * as path from 'path';
-import { AgentManager, checkCliSignedIn, collectTeamsDoctorData, getAgentsDir, VALID_TASK_TYPES, } from '../lib/teams/agents.js';
+import { AgentManager, AgentStatus, checkCliSignedIn, collectTeamsDoctorData, getAgentsDir, VALID_TASK_TYPES, } from '../lib/teams/agents.js';
+import { mailboxDir, enqueue } from '../lib/mailbox.js';
 import { resolveProvider } from '../lib/cloud/registry.js';
 import { emit } from '../lib/events.js';
 import { runSupervisor } from '../lib/teams/supervisor.js';
@@ -126,6 +127,23 @@ function parseTeammate(spec) {
 function shortId(id) {
     return id.slice(0, 8);
 }
+/**
+ * Decide how a follow-up to a teammate is delivered from its reconciled status.
+ * Pure — the source of truth for the routing table, unit-tested without I/O.
+ *   - pending                       -> not-started (tell them to `teams start`)
+ *   - running     + message         -> steer (mailbox)
+ *   - stopped/etc + message         -> resume (re-enter session)
+ *   - any actionable + no message   -> need-message
+ */
+export function decideTeamMessageRoute(status, hasMessage) {
+    if (status === AgentStatus.PENDING)
+        return { kind: 'not-started' };
+    if (!hasMessage)
+        return { kind: 'need-message' };
+    if (status === AgentStatus.RUNNING)
+        return { kind: 'steer' };
+    return { kind: 'resume' };
+}
 /**
  * Preamble injected into every factory worker's prompt. Tells the worker
  * which team + teammate name + task-type it is, and how to file new tasks.
@@ -816,6 +834,12 @@ export function registerTeamsCommands(program) {
       # Delta-poll status without rereading everything
       agents teams status pricing-page --since 2026-04-24T09:00:00-07:00
 
+      # Nudge a teammate that stopped with more to do — resumes its own session
+      agents teams resume pricing-page backend "Review's in — rebase-merge the PR, then release"
+
+      # Steer a still-running teammate mid-flight (delivered at its next tool call)
+      agents teams message pricing-page qa "Skip the flaky screenshot test for now"
+
       # Wind everyone down when shipped
       agents teams disband pricing-page
     `,
@@ -1646,7 +1670,7 @@ export function registerTeamsCommands(program) {
     });
     // stop
     addHostOption(teams.command('stop [team] [teammate]'))
-        .description('Stop a running teammate. Can be restarted later. Cleans up worktree if no uncommitted changes.')
+        .description('Stop a running teammate. Resume it later with `agents teams resume`. Cleans up worktree if no uncommitted changes.')
         .option('--json', 'Output machine-readable JSON')
         .action(async (team, ref, opts) => {
         const mgr = mkManager();
@@ -1733,6 +1757,85 @@ export function registerTeamsCommands(program) {
             console.log(chalk.yellow(`Worktree '${agent.worktreeName}' has uncommitted changes. Keeping it at: ${agent.worktreePath}`));
         }
     });
+    // message / resume — send a follow-up message to a teammate. Routes by the
+    // teammate's reconciled status: a RUNNING teammate is STEERED via its mailbox
+    // (delivered at its next tool call); a STOPPED one (completed/failed/stopped)
+    // is RESUMED — re-entering its own session with the message as the next user
+    // turn, re-attaching it to the team as live.
+    async function teamMessageAction(team, ref, message, opts) {
+        const mgr = mkManager();
+        const lookup = await mgr.resolveAgentIdInTask(team, ref);
+        if (lookup.kind === 'none')
+            die(`No teammate matching '${ref}' in team ${team}`, 2);
+        if (lookup.kind === 'ambiguous') {
+            const shorts = lookup.matches.map(shortId).join(', ');
+            die(`'${ref}' matches multiple teammates: ${shorts}. Use more characters or a name.`, 2);
+        }
+        const agentId = lookup.agentId;
+        // mgr.get reconciles the teammate's status (PID + start-time guard / remote
+        // .exit sentinel / exit-code reap) before we branch — so running-vs-stopped
+        // is a fact, not a guess.
+        const agent = await mgr.get(agentId);
+        if (!agent)
+            die(`Teammate ${shortId(agentId)} vanished from team ${team}.`);
+        const display = agent.name || shortId(agentId);
+        const status = agent.status;
+        const hasMessage = message != null && message.trim().length > 0;
+        const route = decideTeamMessageRoute(status, hasMessage);
+        switch (route.kind) {
+            case 'not-started':
+                die(`Teammate '${display}' hasn't started yet (waiting on --after deps). Run \`agents teams start ${team}\` to launch it.`);
+                return;
+            case 'need-message':
+                if (status === AgentStatus.RUNNING) {
+                    die(`Teammate '${display}' is running — pass a message to steer it.`);
+                }
+                die(`Teammate '${display}' is ${status} — pass a message to resume it: \`agents teams resume ${team} ${display} "<message>"\`.`);
+                return;
+            case 'steer': {
+                // Running -> steer via mailbox; never re-launch (that forks a 2nd session).
+                enqueue(mailboxDir(agentId), { to: agentId, text: message, from: opts.from });
+                if (isJsonMode(opts)) {
+                    console.log(JSON.stringify({ team, agent_id: agentId, name: agent.name ?? null, action: 'steer', status }, null, 2));
+                    return;
+                }
+                console.log(chalk.green(`Steering ${chalk.cyan(display)} (running) — `) +
+                    chalk.dim('message queued; it will see it at its next tool call.'));
+                return;
+            }
+            case 'resume': {
+                // Stopped / completed / failed -> resume its own session with the message.
+                try {
+                    await mgr.resumeTeammate(agentId, message);
+                }
+                catch (err) {
+                    die(err.message);
+                }
+                if (isJsonMode(opts)) {
+                    console.log(JSON.stringify({ team, agent_id: agentId, name: agent.name ?? null, action: 'resume', prior_status: status }, null, 2));
+                    return;
+                }
+                console.log(chalk.green(`Resuming ${chalk.cyan(display)} `) +
+                    chalk.dim(`(was ${status}) in team ${team} — re-entering its session with your message.`));
+                console.log(chalk.dim(`Track it with \`agents teams status ${team}\`.`));
+                return;
+            }
+        }
+    }
+    addHostOption(teams.command('message <team> <teammate> <message>'))
+        .description('Send a follow-up message to a teammate. A running teammate is steered via its mailbox; a stopped one is resumed — re-entering its own session with the message.')
+        .option('--from <who>', 'Label recorded as the sender of this message')
+        .option('--json', 'Output machine-readable JSON')
+        .action(async (team, ref, message, opts) => {
+        await teamMessageAction(team, ref, message, opts);
+    });
+    addHostOption(teams.command('resume <team> <teammate> [message]'))
+        .description("Resume a stopped teammate (completed/failed/stopped) by re-entering its own session with a message as the next user turn. If the teammate is still running, the message is steered via its mailbox instead.")
+        .option('--from <who>', 'Label recorded as the sender of this message')
+        .option('--json', 'Output machine-readable JSON')
+        .action(async (team, ref, message, opts) => {
+        await teamMessageAction(team, ref, message, opts);
+    });
     // remove
     teams
         .command('remove [team] [teammate]')

package/dist/lib/daemon.js

@@ -306,6 +306,28 @@ export async function runDaemon() {
     catch (err) {
         log('ERROR', `Stray daemon reaper failed: ${err.message}`);
     }
+    // #416: host the secrets broker socket-first — before the scheduler and the
+    // heavy browser/session-sync services — so `agents secrets` resolves within
+    // ms of daemon start. Only host when no broker is already reachable, so we
+    // never orphan a live standalone broker's clients (that broker stays the
+    // server until it idle-exits or the daemon restarts). Best-effort: a failure
+    // here must not stop the daemon. Retiring the standalone launchd service is
+    // the follow-on (#416 step 2 / #417).
+    let hostedBroker = null;
+    try {
+        const { agentPing, startHostedBroker } = await import('./secrets/agent.js');
+        if ((await agentPing()).reachable) {
+            log('INFO', 'Secrets broker already running (standalone); daemon not hosting it');
+        }
+        else {
+            hostedBroker = await startHostedBroker();
+            if (hostedBroker)
+                log('INFO', 'Secrets broker hosted in daemon (socket-first)');
+        }
+    }
+    catch (err) {
+        log('WARN', `Secrets broker host skipped: ${err.message}`);
+    }
     const scheduler = new JobScheduler(async (config) => {
         log('INFO', `Triggering job '${config.name}' (agent: ${config.agent})`);
         try {
@@ -594,6 +616,7 @@ export async function runDaemon() {
         clearTimeout(tmuxReconcileKickoff);
         clearInterval(launchHealthInterval);
         clearTimeout(launchHealthKickoff);
+        hostedBroker?.close();
         removeDaemonPid();
         removeHeartbeat();
         process.exit(0);

package/dist/lib/secrets/agent.d.ts

@@ -172,6 +172,27 @@ export declare function shouldWipeOnWatchEvent(chunk: string): boolean;
 export declare function runSecretsAgent(opts?: {
     service?: boolean;
 }): Promise<void>;
+/**
+ * Host the secrets broker inside the always-on daemon (#416).
+ *
+ * Serves the SAME socket and wire protocol as the standalone `runSecretsAgent`
+ * — so every existing client (`agentGetSync`, `agentPing`, `agentAutoLoadSync`)
+ * keeps working unchanged, no PROTOCOL_VERSION bump — but it is daemon-safe:
+ *
+ *   - no pid-file single-instance guard (the daemon owns the instance);
+ *   - no `process.exit`, no SIGTERM/SIGINT handlers, no self-heal/idle-exit
+ *     (those would kill the daemon — the daemon is the always-on backbone and
+ *     manages its own version/lifecycle). The sweep only TTL-evicts.
+ *
+ * The caller (`runDaemon`) must only invoke this when NO broker is already
+ * reachable (ping first) — this function clears a stale socket before binding,
+ * so calling it while a live standalone broker holds the socket would orphan
+ * that broker's clients. Returns a handle the daemon closes on shutdown, or
+ * null off-darwin (nothing to broker without biometry).
+ */
+export declare function startHostedBroker(): Promise<{
+    close(): void;
+} | null>;
 /** True if a broker socket exists at all. Cheap; gates the sync read so the
  * never-unlocked path stays a single stat. */
 export declare function agentSocketExists(): boolean;
@@ -246,6 +267,12 @@ export declare function agentLock(name?: string): Promise<number>;
  * predates the server-side exclusion, so this keeps the internal entry from
  * surfacing in `agents secrets status` in that skew window. */
 export declare function agentStatus(): Promise<AgentStatusEntry[]>;
+/** Ping result: whether a broker is reachable + speaking our protocol, and the
+ * version of the code it's running (for staleness detection). */
+export declare function agentPing(): Promise<{
+    reachable: boolean;
+    cliVersion?: string;
+}>;
 /**
  * Ensure a broker is running and reachable. Returns true once the socket answers
  * a ping. macOS only.

package/dist/lib/secrets/agent.js

@@ -500,6 +500,132 @@ export async function runSecretsAgent(opts = {}) {
         watcher = null;
     }
 }
+/**
+ * Host the secrets broker inside the always-on daemon (#416).
+ *
+ * Serves the SAME socket and wire protocol as the standalone `runSecretsAgent`
+ * — so every existing client (`agentGetSync`, `agentPing`, `agentAutoLoadSync`)
+ * keeps working unchanged, no PROTOCOL_VERSION bump — but it is daemon-safe:
+ *
+ *   - no pid-file single-instance guard (the daemon owns the instance);
+ *   - no `process.exit`, no SIGTERM/SIGINT handlers, no self-heal/idle-exit
+ *     (those would kill the daemon — the daemon is the always-on backbone and
+ *     manages its own version/lifecycle). The sweep only TTL-evicts.
+ *
+ * The caller (`runDaemon`) must only invoke this when NO broker is already
+ * reachable (ping first) — this function clears a stale socket before binding,
+ * so calling it while a live standalone broker holds the socket would orphan
+ * that broker's clients. Returns a handle the daemon closes on shutdown, or
+ * null off-darwin (nothing to broker without biometry).
+ */
+export async function startHostedBroker() {
+    if (!onDarwin())
+        return null;
+    const store = new Map();
+    const sock = socketPath(); // agentDir() creates the 0700 dir as a side effect
+    const handle = (req) => handleAgentRequest(store, req);
+    const onConn = (conn) => {
+        conn.setEncoding('utf-8');
+        let buf = '';
+        conn.on('data', (chunk) => {
+            buf += chunk;
+            let nl;
+            while ((nl = buf.indexOf('\n')) >= 0) {
+                const line = buf.slice(0, nl);
+                buf = buf.slice(nl + 1);
+                if (!line.trim())
+                    continue;
+                let resp;
+                try {
+                    resp = handle(JSON.parse(line));
+                }
+                catch (err) {
+                    resp = { ok: false, error: err.message };
+                }
+                conn.write(JSON.stringify(resp) + '\n');
+            }
+        });
+        conn.on('error', () => { });
+    };
+    // Bind race-safely: never clobber a LIVE standalone broker. Try to listen; if
+    // the socket is already bound, a broker raced us after runDaemon's ping — if
+    // it answers, back off and let it serve (return null); if it's a stale socket
+    // file with no live listener, reclaim it and retry once. (Unconditionally
+    // unlinking before bind — as an earlier draft did — could remove a live
+    // broker's socket in the sub-ms window after runDaemon's reachability check.)
+    const listenOnce = () => new Promise((resolve, reject) => {
+        const s = net.createServer(onConn);
+        s.once('error', (err) => {
+            if (err.code === 'EADDRINUSE')
+                resolve('inuse');
+            else
+                reject(err);
+        });
+        s.listen(sock, () => {
+            try {
+                fs.chmodSync(sock, 0o600);
+            }
+            catch { /* dir 0700 already gates it */ }
+            resolve(s);
+        });
+    });
+    let bound = await listenOnce();
+    if (bound === 'inuse') {
+        if ((await agentPing()).reachable)
+            return null; // a live broker holds it — don't clobber
+        try {
+            fs.unlinkSync(sock);
+        }
+        catch { /* gone */ }
+        bound = await listenOnce();
+        if (bound === 'inuse')
+            return null; // still contended — the standalone fallback covers it
+    }
+    const server = bound;
+    // TTL eviction ONLY. Unlike the standalone broker's sweep, there is no
+    // self-heal-exit or idle-exit here — the daemon is always-on and owns the
+    // upgrade/lifecycle path; a broker that called process.exit() would take the
+    // whole daemon down with it.
+    const sweepTimer = setInterval(() => {
+        const now = Date.now();
+        for (const [name, e] of store)
+            if (now >= e.expiresAt)
+                store.delete(name);
+    }, SWEEP_INTERVAL_MS);
+    // Auto-lock on sleep, same as the standalone broker: the signed helper emits
+    // LOCK/SLEEP lines; wipe the in-memory store on a wipe-worthy event.
+    let watcher = null;
+    try {
+        watcher = spawn(getKeychainHelperPath(), ['watch-lock'], { stdio: ['ignore', 'pipe', 'ignore'] });
+        watcher.stdout?.setEncoding('utf-8');
+        watcher.stdout?.on('data', (chunk) => {
+            if (shouldWipeOnWatchEvent(chunk))
+                store.clear();
+        });
+        watcher.on('error', () => { watcher = null; });
+    }
+    catch {
+        watcher = null;
+    }
+    return {
+        close() {
+            store.clear();
+            clearInterval(sweepTimer);
+            try {
+                watcher?.kill();
+            }
+            catch { /* already gone */ }
+            try {
+                server.close();
+            }
+            catch { /* not listening */ }
+            try {
+                fs.unlinkSync(sock);
+            }
+            catch { /* gone */ }
+        },
+    };
+}
 // ─── Client ──────────────────────────────────────────────────────────────────
 /** Open the socket, send one request, resolve the one response. Async path —
  * used by the unlock/lock/status commands, which already run in async actions. */
@@ -766,7 +892,7 @@ export async function agentStatus() {
 }
 /** Ping result: whether a broker is reachable + speaking our protocol, and the
  * version of the code it's running (for staleness detection). */
-async function agentPing() {
+export async function agentPing() {
     if (!agentSocketExists())
         return { reachable: false };
     const r = await request({ cmd: 'ping' });
@@ -802,6 +928,23 @@ export async function ensureAgentRunning(timeoutMs = 5000) {
             return true;
         await teardownStaleBroker();
     }
+    // Path 0 (#416): prefer the always-on daemon — it hosts the broker socket
+    // (one supervised backbone rather than a separate launchd service). If
+    // bringing the daemon up makes the broker answer, we're done. Fall through to
+    // the standalone-service paths below when the daemon path isn't available
+    // (kept as a fallback until the standalone service is retired, #416 step 2).
+    try {
+        const { ensureDaemonStarted } = await import('../daemon.js');
+        if (ensureDaemonStarted()) {
+            const d0 = Date.now() + timeoutMs;
+            while (Date.now() < d0) {
+                if ((await agentPing()).reachable)
+                    return true;
+                await new Promise((r) => setTimeout(r, 120));
+            }
+        }
+    }
+    catch { /* daemon path unavailable — fall through to the standalone service */ }
     // Path 1: the persistent service. installSecretsAgentService is idempotent and
     // waits for the socket; for an already-installed service we kickstart and wait.
     try {

package/dist/lib/teams/agents.d.ts

@@ -301,6 +301,22 @@ export declare class AgentManager {
     rescanFromDisk(): Promise<number>;
     private loadExistingAgents;
     spawn(taskName: string, agentType: AgentType, prompt: string, cwd?: string | null, mode?: Mode | null, effort?: EffortLevel, parentSessionId?: string | null, workspaceDir?: string | null, version?: string | null, name?: string | null, after?: string[], model?: string | null, envOverrides?: Record<string, string> | null, taskType?: TaskType | null, cloudProvider?: string | null, cloudSessionId?: string | null, cloudRepo?: string | null, cloudBranch?: string | null, worktreeName?: string | null, worktreePath?: string | null, profileName?: string | null, hostName?: string | null, hostTarget?: string | null, repoPath?: string | null): Promise<AgentProcess>;
+    /**
+     * Resume a STOPPED teammate (completed / failed / stopped) by re-entering its
+     * own session with `message` as the next user turn. Re-launches through the
+     * SAME backend the teammate first used (local process or remote host), reusing
+     * its stored cwd / worktree / host / version / model / effort, and flips it
+     * back to RUNNING so the team tracks it live again.
+     *
+     * The resume target is the teammate's underlying agent session id: for Claude
+     * that IS its agent_id (unified identity, pinned via --session-id at first
+     * launch); other harnesses only expose their session/thread id after their
+     * first stream event, captured as `remoteSessionId`.
+     *
+     * Callers branch on status first — a RUNNING teammate is steered via its
+     * mailbox, never re-launched — so this method assumes a non-running teammate.
+     */
+    resumeTeammate(agentId: string, message: string): Promise<AgentProcess>;
     /**
      * Actually spawn the OS process for a teammate. Extracted from spawn() so
      * staged teammates can be launched later by startReady().

package/dist/lib/teams/agents.js

@@ -1357,11 +1357,69 @@ export class AgentManager {
         await this.cleanupOldAgents();
         return agent;
     }
+    /**
+     * Resume a STOPPED teammate (completed / failed / stopped) by re-entering its
+     * own session with `message` as the next user turn. Re-launches through the
+     * SAME backend the teammate first used (local process or remote host), reusing
+     * its stored cwd / worktree / host / version / model / effort, and flips it
+     * back to RUNNING so the team tracks it live again.
+     *
+     * The resume target is the teammate's underlying agent session id: for Claude
+     * that IS its agent_id (unified identity, pinned via --session-id at first
+     * launch); other harnesses only expose their session/thread id after their
+     * first stream event, captured as `remoteSessionId`.
+     *
+     * Callers branch on status first — a RUNNING teammate is steered via its
+     * mailbox, never re-launched — so this method assumes a non-running teammate.
+     */
+    async resumeTeammate(agentId, message) {
+        await this.initialize();
+        const agent = await this.get(agentId);
+        if (!agent)
+            throw new Error(`No teammate with id ${agentId}`);
+        const who = agent.name ?? agent.agentId.slice(0, 8);
+        // The message rides as `agents run`'s prompt positional. A leading '-' makes
+        // commander parse it as an (unknown) flag, exiting the child non-zero — the
+        // teammate would silently land FAILED. `--` can't rescue it: `agents run`
+        // treats post-`--` tokens as native passthrough and unsets the prompt. Fail
+        // loud and early instead. (Steer/mailbox delivery has no such limit.)
+        if (message.startsWith('-')) {
+            throw new Error(`Resume message can't start with '-' — \`agents run\` would parse it as a flag. ` +
+                `Rephrase so it leads with a word (e.g. "Please ${message}").`);
+        }
+        // Cloud-backed teammates run on remote provider infrastructure with no local
+        // or host process to re-launch; continuing them goes through the provider.
+        if (agent.cloudProvider) {
+            throw new Error(`Teammate '${who}' is a ${agent.cloudProvider} cloud task — resume it with ` +
+                `\`agents message ${agent.cloudSessionId ?? agent.agentId} "<message>"\` instead.`);
+        }
+        // For non-Claude teammates the agent_id is NOT the harness session id — that
+        // is only known once the agent emitted its first stream event. If it never
+        // did (e.g. it failed before its first turn), there is no resumable handle.
+        if (agent.agentType !== 'claude' && !agent.remoteSessionId) {
+            throw new Error(`No resumable session id was captured for ${agent.agentType} teammate '${who}' — ` +
+                `its session id is discovered from the agent's own output, which never arrived ` +
+                `(it may have failed before its first turn). Start a fresh teammate instead.`);
+        }
+        const resume = { id: agent.remoteSessionId ?? agent.agentId, message };
+        // Flip to RUNNING up front so a concurrent status poll can't reap the
+        // teammate between the exit-sentinel clear and the new PID landing; the
+        // launch re-persists with the fresh pid/startTime.
+        agent.status = AgentStatus.RUNNING;
+        agent.completedAt = null;
+        if (agent.hostName) {
+            await this.launchRemoteProcess(agent, resume);
+        }
+        else {
+            await this.launchProcess(agent, resume);
+        }
+        return agent;
+    }
     /**
      * Actually spawn the OS process for a teammate. Extracted from spawn() so
      * staged teammates can be launched later by startReady().
      */
-    async launchProcess(agent) {
+    async launchProcess(agent, resume) {
         const running = await this.listRunning();
         warnIfMemoryLow(running.length);
         const effort = agent.effort ?? 'medium';
@@ -1369,10 +1427,20 @@ export class AgentManager {
         // forwarded). Effort is a separate knob wired into buildReasoningFlags
         // inside buildCommand.
         const resolvedModel = agent.model ?? null;
-        const cmd = this.buildCommand(agent.agentType, agent.prompt, agent.mode, resolvedModel, agent.cwd, agent.agentId, effort, agent.version, agent.profileName);
-        debug(`Launching ${agent.agentType} agent ${agent.agentId} [${agent.mode}]: ${cmd.slice(0, 3).join(' ')}...`);
+        const cmd = this.buildCommand(agent.agentType, agent.prompt, agent.mode, resolvedModel, agent.cwd, agent.agentId, effort, agent.version, agent.profileName, resume);
+        debug(`Launching ${agent.agentType} agent ${agent.agentId} [${agent.mode}]${resume ? ' (resume)' : ''}: ${cmd.slice(0, 3).join(' ')}...`);
         try {
             const stdoutPath = await agent.getStdoutPath();
+            // Always TRUNCATE — including on resume. The status reader re-reads the
+            // whole log from byte 0 every poll (lastReadPos is in-memory, not
+            // persisted) and marks terminal status from the last `result` event it
+            // sees, with no liveness guard. If the resumed turn's stream were appended
+            // after the prior turn's `result:success`, that stale event would win for
+            // the entire duration of the new (still-running) turn — reporting the
+            // teammate COMPLETED while it works, and steering a second follow-up into
+            // a forked session. Truncating keeps exactly one turn in the log, so the
+            // re-read is always correct. The authoritative transcript lives in the
+            // agent's own session (resumed via --resume), not this stdout mirror.
             const stdoutFile = await fs.open(stdoutPath, 'w');
             const stdoutFd = stdoutFile.fd;
             // Wrap the teammate command in a shell that records the underlying CLI's
@@ -1424,7 +1492,7 @@ export class AgentManager {
      * created ON THE HOST off the freshly-fetched default branch; the teammate runs
      * there. Otherwise it runs in the host repo path directly.
      */
-    async launchRemoteProcess(agent) {
+    async launchRemoteProcess(agent, resume) {
         if (!agent.hostName || !agent.hostTarget || !agent.repoPath) {
             throw new Error(`Remote teammate ${agent.agentId} is missing host placement (host/target/repo).`);
         }
@@ -1448,17 +1516,25 @@ export class AgentManager {
         }
         // Worktree isolation on the host, if the team enables it. createRemoteWorktree
         // fetches origin and branches off origin/<default>, returning the host path.
+        // On RESUME the worktree already exists from the original launch — reuse it
+        // (its path is persisted) instead of re-creating (which would fail on the
+        // existing branch and would also discard the teammate's in-progress work).
         let remoteCwd = agent.repoPath;
         if (agent.worktreeName) {
-            const worktreePath = createRemoteWorktree(agent.hostTarget, agent.repoPath, agent.worktreeName);
-            agent.worktreePath = worktreePath;
-            remoteCwd = worktreePath;
+            if (resume && agent.worktreePath) {
+                remoteCwd = agent.worktreePath;
+            }
+            else {
+                const worktreePath = createRemoteWorktree(agent.hostTarget, agent.repoPath, agent.worktreeName);
+                agent.worktreePath = worktreePath;
+                remoteCwd = worktreePath;
+            }
         }
         // Same run argv the local path builds (shared buildRunArgv keeps the prompt
         // scaffolding + flags from drifting); dispatched non-blocking (follow:false)
         // — the supervisor polls the host, we don't block here.
         const effort = agent.effort ?? 'medium';
-        const forwardedArgs = this.buildRunArgv(agent.agentType, agent.prompt, agent.mode, agent.model ?? null, effort, agent.version, agent.profileName);
+        const forwardedArgs = this.buildRunArgv(agent.agentType, agent.prompt, agent.mode, agent.model ?? null, effort, agent.version, agent.profileName, resume);
         try {
             const { task } = await dispatchAgentsCommand(host, {
                 forwardedArgs,
@@ -1469,6 +1545,13 @@ export class AgentManager {
             agent.remoteLog = task.remoteLog ?? null;
             agent.remoteExit = task.remoteExit ?? null;
             agent.remoteLogOffset = 0;
+            // On resume the offset resets to 0 against a FRESH remote log, and
+            // syncRemoteMirror appends the delta onto the local mirror. Truncate that
+            // mirror first so the prior turn's terminal event can't linger and get
+            // re-read as the current status (same hazard the local path truncates for).
+            if (resume) {
+                await fs.writeFile(await agent.getStdoutPath(), '').catch(() => { });
+            }
             agent.status = AgentStatus.RUNNING;
             agent.startedAt = new Date();
             await agent.saveMeta();
@@ -1670,38 +1753,46 @@ export class AgentManager {
      * before invoking `agents`. `sessionId` is likewise local-only (the remote run
      * mints its own session on the host).
      */
-    buildRunArgv(agentType, prompt, mode, model, effort, version, profileName) {
-        // Compose the prompt: a plan-mode prefix for Claude (clarifying headless
-        // plan-mode restrictions) and a universal summary suffix. These are
-        // team-specific prompt scaffolding — `agents run` does not apply them.
-        let fullPrompt = prompt + PROMPT_SUFFIX;
-        if (agentType === 'claude' && mode === 'plan') {
-            fullPrompt = CLAUDE_PLAN_MODE_PREFIX + fullPrompt;
+    buildRunArgv(agentType, prompt, mode, model, effort, version, profileName, resume) {
+        // Compose the prompt. On RESUME the message is the teammate's next user turn,
+        // not a fresh brief — so skip the original brief and the plan-mode prefix, but
+        // keep PROMPT_SUFFIX so the resumed run still emits a final summary the team
+        // parser reads. On a fresh launch, add the plan-mode prefix for Claude and the
+        // universal summary suffix. These are team-specific prompt scaffolding —
+        // `agents run` does not apply them.
+        let fullPrompt;
+        if (resume) {
+            fullPrompt = resume.message + PROMPT_SUFFIX;
+        }
+        else {
+            fullPrompt = prompt + PROMPT_SUFFIX;
+            if (agentType === 'claude' && mode === 'plan') {
+                fullPrompt = CLAUDE_PLAN_MODE_PREFIX + fullPrompt;
+            }
         }
         // Profile target takes precedence — `agents run <profile>` resolves the
         // host harness, version pin, and env injection in one place. Plain
         // version pins only apply when no profile is selected.
         const target = profileName ?? (version ? `${agentType}@${version}` : agentType);
-        const args = [
-            'run',
-            target,
-            fullPrompt,
-            '--mode', mode,
-            '--effort', effort,
-            '--json',
-            '--headless',
-            '--quiet',
-        ];
+        // Keep the prompt as the first positional (right after target), matching the
+        // fresh-launch shape, and add `--resume <id>` among the flags. `agents run`
+        // continues the teammate's own session natively (claude `--resume`, codex
+        // `resume`) or via the universal `/continue` replay for other harnesses.
+        const args = ['run', target, fullPrompt];
+        if (resume) {
+            args.push('--resume', resume.id);
+        }
+        args.push('--mode', mode, '--effort', effort, '--json', '--headless', '--quiet');
         if (model)
             args.push('--model', model);
         args.push('--env', 'AGENTS_RUNTIME=teams');
         return args;
     }
-    buildCommand(agentType, prompt, mode, model, cwd = null, sessionId = null, effort = 'medium', version = null, profileName = null) {
+    buildCommand(agentType, prompt, mode, model, cwd = null, sessionId = null, effort = 'medium', version = null, profileName = null, resume) {
         // Route through getAgentsInvocation so a teammate launched by the compiled
         // standalone binary (#315) doesn't relaunch as `agents /$bunfs/root/agents …`
         // (process.argv[1] is the bun virtual entry there) → "unknown command".
-        const inv = getAgentsInvocation(this.buildRunArgv(agentType, prompt, mode, model, effort, version, profileName));
+        const inv = getAgentsInvocation(this.buildRunArgv(agentType, prompt, mode, model, effort, version, profileName, resume));
         const cmd = [inv.command, ...inv.args];
         if (cwd)
             cmd.push('--cwd', cwd);
@@ -1709,7 +1800,9 @@ export class AgentManager {
         // AGENTS_MAILBOX_DIR by the same id mailboxIdForActiveSession returns.
         // Claude also forwards --session-id to its CLI (unified identity);
         // other agents ignore the flag but still get the correct mailbox dir.
-        if (sessionId) {
+        // On RESUME we continue an existing session — `--session-id` CREATES one and
+        // `agents run` rejects it alongside `--resume`, so it must be omitted.
+        if (sessionId && !resume) {
             cmd.push('--session-id', sessionId);
         }
         // Claude: grant access to the teammate's working directory.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.56",
+  "version": "1.20.57",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",