@phnx-labs/agents-cli 1.20.74 → 1.20.76

package/dist/lib/exec.js

@@ -15,10 +15,13 @@ import { getBinaryPath, getVersionHomePath, isVersionInstalled, resolveVersion }
 import { resolveModel, buildReasoningFlags } from './models.js';
 import { maybeRotate, createTimer, redactPrompt, redactArgs } from './events.js';
 import { sanitizeProcessEnv } from './secrets/bundles.js';
+import { resolveActor, actorEnv } from './actor.js';
 import { getShimsDir, getHistoryDir } from './state.js';
 import { resolveCodexHome } from './codex-home.js';
 import { readCodexConfiguredModel } from './shims.js';
 import { writePidSessionEntry, extractSessionIdArg } from './session/pid-registry.js';
+import { loadHookSessionIndex, resolveHookSessionId } from './session/hook-sessions.js';
+import { sessionIdMarkerLine } from './hosts/session-marker.js';
 import { recordRunName } from './session/run-names.js';
 import { mailboxDir, isValidMailboxId } from './mailbox.js';
 import { composeWin32CommandLine } from './platform/index.js';
@@ -312,14 +315,29 @@ export function buildExecEnv(options) {
     // iterations share one inbox.
     if (options.sessionId && isValidMailboxId(options.sessionId)) {
         result.AGENTS_MAILBOX_DIR = mailboxDir(options.sessionId);
+        // Full session id for agent-callable tools (`agents feed post`, etc.).
+        result.AGENT_SESSION_ID = options.sessionId;
+        result.AGENTS_SESSION_ID = options.sessionId;
     }
     result.AGENTS_RUNTIME = resolveInteractive(options) ? 'terminal' : 'headless';
+    // So activity / feed posts stamp the right harness without re-detecting.
+    if (options.agent) {
+        result.AGENTS_AGENT_NAME = options.agent;
+    }
+    if (options.cwd) {
+        result.AGENTS_CWD = options.cwd;
+    }
     // Export the run's durable name (companion to AGENT_SESSION_ID) so a
     // SessionStart hook / the agent can associate its transcript with the handle
     // the user gave the run. Only set when --name was passed.
     if (options.name) {
         result.AGENT_SESSION_NAME = options.name;
     }
+    // Actor provenance -- who initiated this run. Rides the env so the whole spawn
+    // tree shares one actor, and (for a resolved human) so the agent's own git
+    // commits are credited to the person instead of the shared account. options.env
+    // (spread last) overrides any of these keys a caller sets explicitly.
+    Object.assign(result, actorEnv(resolveActor()));
     return {
         ...result,
         ...options.env,
@@ -666,10 +684,16 @@ export function buildExecCommand(options) {
     else {
         cmd.push(...modeFlags);
     }
-    // Add print/headless flags only when a prompt is provided. Without a prompt
-    // the caller wants an interactive REPL -- passing --print would immediately
-    // wait on stdin and never render the TUI.
-    if (!interactive && options.headless && template.printFlags) {
+    // Add print/headless flags whenever the run RESOLVED headless -- gate on the
+    // resolved state (`!interactive`), not the raw `--headless` flag. Headless is
+    // inferred from prompt presence (resolveInteractive), and `--headless` defaults
+    // to `false` at the CLI layer, so gating on `options.headless` skipped these
+    // flags for a bare `agents run <agent> "prompt"`. For antigravity that meant
+    // `agy <prompt>` with no `--print`, launching the TUI and dying on `/dev/tty`
+    // in any non-terminal shell. `!interactive` is true for both an explicit
+    // `--headless` and a prompt-inferred headless run; an interactive run (no
+    // prompt, or `--interactive`) still skips them so the CLI opens its REPL.
+    if (!interactive && template.printFlags) {
         cmd.push(...template.printFlags);
     }
     // Resume vs. create. With `resume`, emit the agent's NATIVE resume reference:
@@ -842,9 +866,15 @@ export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
     }
     // The only flag the bash shim injects (codex); everything else is transparent.
     const launchArgs = agent === 'codex' ? ['-c', 'check_for_update_on_startup=false'] : [];
+    // Mint a launch id and export it as AGENT_LAUNCH_ID so the agent's SessionStart
+    // hook records the same id — the join key that maps this launch to its exact
+    // session even though the recorded pid here is the cmd.exe wrapper (Windows) or
+    // a shell, while the hook runs under the agent descendant. This is the primary
+    // attribution path on Windows (no lsof), so the launchId join matters most here.
+    const launchId = randomUUID();
     // mode/effort are required by ExecOptions but unused by buildExecEnv (which only
     // derives the per-version config-dir env); pass the agent's default to satisfy the type.
-    const env = buildExecEnv({ agent, version, cwd, mode: defaultModeFor(agent), effort: 'auto' });
+    const env = buildExecEnv({ agent, version, cwd, mode: defaultModeFor(agent), effort: 'auto', env: { AGENT_LAUNCH_ID: launchId } });
     const { command, args, shell } = resolveShimSpawn(process.platform, binary, [...launchArgs, ...rawArgs]);
     return new Promise((resolve) => {
         const child = spawn(command, args, { cwd, stdio: 'inherit', env, shell });
@@ -860,6 +890,8 @@ export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
                 agent,
                 sessionId: extractSessionIdArg(rawArgs),
                 cwd,
+                launchId,
+                terminalId: process.env.AGENT_TERMINAL_ID,
                 startedAtMs: Date.now(),
             });
         }
@@ -1008,6 +1040,12 @@ async function runInTmux(options, executable, args) {
             agent: options.agent,
             sessionId: options.sessionId,
             cwd,
+            // spawnAgent injected AGENT_LAUNCH_ID into options.env before delegating
+            // here; record the same id so the hook (running under the pane-leaf agent
+            // pid) reconciles by launchId. This pane's pid usually IS the agent pid,
+            // but the launchId join is robust even when it isn't.
+            launchId: options.env?.AGENT_LAUNCH_ID,
+            terminalId: process.env.AGENT_TERMINAL_ID,
             tmuxPane: pane,
             startedAtMs: Date.now(),
         });
@@ -1066,6 +1104,36 @@ async function runInTmux(options, executable, args) {
     // Pane still alive → the user detached; keep the session for `agents focus`.
     return { exitCode: 0, stderr: '', stdout: '' };
 }
+/**
+ * Print the run's resolved session id as a one-line stdout sentinel so a `--host`
+ * launcher can relate the remote-created session back to itself (see the
+ * `emitSessionId` option and hosts/session-marker.ts).
+ *
+ * For Claude the id was forced up front (`options.sessionId`, wired as
+ * `--session-id`), so it's authoritative with no lookup. Every other agent coined
+ * its OWN id, which its SessionStart hook recorded under this run's launchId — the
+ * exact join key `agents sessions --active` uses — so we read it back from the hook
+ * index by launchId (falling back to the child pid the hook may have recorded
+ * under). Nothing to emit when the hook hasn't landed an id (hookless harness):
+ * the launcher simply keeps the un-mapped task, never a fabricated id.
+ */
+function emitResolvedSessionId(options, launchId, childPid) {
+    let sessionId = options.sessionId;
+    if (!sessionId) {
+        try {
+            sessionId = resolveHookSessionId(loadHookSessionIndex(), {
+                pid: childPid ?? 0,
+                kind: options.agent,
+                launchId,
+            });
+        }
+        catch {
+            /* hook index unreadable — emit nothing rather than a guess */
+        }
+    }
+    if (sessionId)
+        process.stdout.write(sessionIdMarkerLine(sessionId));
+}
 /**
  * Spawn an agent process and return its exit code plus a tee'd copy of stderr.
  *
@@ -1104,7 +1172,17 @@ async function spawnAgent(options) {
     // timeout. Spend is recorded to the shared ledger in the close handler. The
     // watcher is dormant (and zero-cost) when no caps are configured.
     const cwd = options.cwd || process.cwd();
-    const runId = randomUUID();
+    // Mint the launch id once. It doubles as the budget watcher's run id AND is
+    // exported to the child as AGENT_LAUNCH_ID, so the agent's SessionStart hook
+    // records the SAME id in its own state file (terminals/sessions/<pid>.json).
+    // That id is the join key that reconciles this launch's pid-registry entry
+    // with the hook's authoritative session id even when the hook runs under a
+    // different pid (tmux pane leaf / cmd.exe wrapper) — see pid-registry.ts and
+    // session/hook-sessions.ts. Injected into options.env so every downstream env
+    // build (the bare spawn below AND the tmux env prefix in runInTmux) carries it.
+    const launchId = randomUUID();
+    const runId = launchId;
+    options = { ...options, env: { ...options.env, AGENT_LAUNCH_ID: launchId } };
     const watcherState = await setupBudgetWatcher(options, cwd, runId);
     maybeRotate();
     const timer = createTimer('agent.run', {
@@ -1178,6 +1256,8 @@ async function spawnAgent(options) {
             agent: options.agent,
             sessionId: options.sessionId,
             cwd: options.cwd || process.cwd(),
+            launchId,
+            terminalId: process.env.AGENT_TERMINAL_ID,
             tmuxPane: process.env.TMUX_PANE,
             startedAtMs: Date.now(),
         });
@@ -1264,6 +1344,12 @@ async function spawnAgent(options) {
             // Budget kill resolves with a DISTINCT non-zero exit so CI/headless and
             // teams/cloud can tell a budget termination apart from a normal failure.
             const exitCode = budgetKilled ? BUDGET_KILL_EXIT_CODE : (code ?? 0);
+            // Relate the session id back to a `--host` launcher (see the emitSessionId
+            // doc). Claude's id is the one we forced; every other agent coined its own,
+            // which the SessionStart hook recorded under this run's launchId — resolve
+            // and print it as a one-line sentinel that rides the followed log home.
+            if (options.emitSessionId)
+                emitResolvedSessionId(options, launchId, child.pid);
             timer.end({ exitCode, status: budgetKilled ? 'budget_killed' : code === 0 ? 'success' : 'failed' });
             resolve({ exitCode, stderr: stderrBuffer, stdout: stdoutTail });
         });
@@ -1358,6 +1444,109 @@ export const RATE_LIMIT_PATTERNS = [
 export function detectRateLimit(text) {
     return RATE_LIMIT_PATTERNS.some(pattern => pattern.test(text));
 }
+/**
+ * Patterns that indicate an authentication failure — the agent is logged out,
+ * its token was revoked, or the session expired. These are the user-visible
+ * strings a logged-out agent surfaces (observed across the routine-run corpus).
+ * Unlike a rate limit, an auth failure is NOT self-healing by failover — every
+ * chain entry on the same account fails identically — so it is classified
+ * separately and never triggers a fallback attempt.
+ *
+ * The bare `401` is deliberately paired with an auth keyword: a plain "401" can
+ * appear in legitimate output (an HTTP-status table, a log line), so it only
+ * counts when it co-occurs with OAuth/authentication/credentials/Unauthorized.
+ */
+export const AUTH_FAILURE_PATTERNS = [
+    /OAuth (?:access token has been revoked|session expired)/i,
+    /(?:Please run|run) \/login/i,
+    /\bNot logged in\b/i,
+    /Invalid authentication credentials/i,
+    /Failed to authenticate/i,
+    /organization has (?:disabled|revoked) .*(?:subscription|access)/i,
+    /401\b[^\n]*(?:OAuth|authenticat|credential|Unauthorized)/i,
+];
+/**
+ * Return true if the text contains any known authentication-failure indicator.
+ * Agent-agnostic: matches the user-visible error string wherever it surfaces
+ * (stdout tail, a captured error message, a plain-text agent's output).
+ */
+export function detectAuthFailure(text) {
+    return AUTH_FAILURE_PATTERNS.some(pattern => pattern.test(text));
+}
+/**
+ * Return true if a stream-json log carries the structural markers of an auth
+ * failure. This is the authoritative signal for Claude: a logged-out run emits
+ *   {"type":"system","subtype":"api_retry","error":"authentication_failed",…}
+ *   {"type":"assistant",…,"error":"authentication_failed"}
+ *   {"type":"result","is_error":true,"result":"Failed to authenticate…"}
+ * Note `terminal_reason` is "completed" on such a run, so exit-code / terminal-
+ * reason logic can never catch it — the `error:"authentication_failed"` marker
+ * and the `result`+`is_error` text are the reliable signals.
+ *
+ * Gated on the Claude stream-json shape; other agents don't emit these fields,
+ * so callers pass their agent and this returns false for non-claude.
+ */
+export function detectAuthFailureEvent(logText, agent) {
+    if (agent !== 'claude')
+        return false;
+    const lines = logText.split('\n');
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed[0] !== '{')
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (parsed?.error === 'authentication_failed')
+            return true;
+        if (parsed?.type === 'result' &&
+            parsed?.is_error === true &&
+            typeof parsed?.result === 'string' &&
+            detectAuthFailure(parsed.result)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Return the first human-readable auth-failure phrase found in the text, for use
+ * as a stable, short run `errorMessage` reason. Falls back to null when the only
+ * signal was the structural `error:"authentication_failed"` marker with no
+ * user-visible string.
+ */
+export function authFailureReason(text) {
+    for (const pattern of AUTH_FAILURE_PATTERNS) {
+        const m = text.match(pattern);
+        if (m)
+            return m[0];
+    }
+    return null;
+}
+/**
+ * Decide whether a run's stream-json log is an authentication failure. The
+ * single source of truth for both the foreground and detached run paths.
+ *
+ * The structural marker (`detectAuthFailureEvent`, gated on `is_error:true`) is
+ * authoritative and safe on ANY exit — it catches a logged-out Claude that exits
+ * 0 (its `result` event carries `is_error:true` while `terminal_reason` is
+ * "completed"). The raw user-visible string (`detectAuthFailure`) is only
+ * consulted when the process actually FAILED, as a fallback for a run that died
+ * mid-stream before emitting a `result` event. That gate is what prevents a
+ * genuinely-completed run whose output merely *mentions* an auth phrase (e.g. a
+ * routine documenting a login flow) from being misclassified and having its
+ * legitimate report suppressed.
+ */
+export function isAuthFailureFromLog(logText, agent, opts) {
+    if (detectAuthFailureEvent(logText, agent))
+        return true;
+    if (opts.processFailed && detectAuthFailure(logText))
+        return true;
+    return false;
+}
 /**
  * Build the prompt handed to the fallback agent when the primary was stopped
  * mid-task by a rate limit.

package/dist/lib/feed-post.d.ts

@@ -0,0 +1,63 @@
+import { type ActivityEvent } from './activity.js';
+import { type PidSessionEntry } from './session/pid-registry.js';
+/** Soft cap so a runaway agent can't flood the activity lane with essays. */
+export declare const STATUS_POST_MAX_CHARS = 500;
+export interface FeedPostInput {
+    /** Human-readable progress text (required). Domain-agnostic free text. */
+    text: string;
+    /** Override session id (escape hatch for scripts/tests). Prefer auto-resolve. */
+    sessionId?: string;
+    /** Override activity root (tests). */
+    activityRoot?: string;
+    /** Override env for identity resolution (tests). */
+    env?: NodeJS.ProcessEnv;
+    /** Override cwd stamp (defaults to process.cwd() / env). */
+    cwd?: string;
+    /** Fixed timestamp (tests). */
+    ts?: string;
+    /**
+     * Starting pid for registry ancestor walk (defaults to process.ppid so the
+     * walk begins at the parent of this CLI process — usually the agent/shell).
+     * Tests inject a fake pid here.
+     */
+    startPid?: number;
+    /** Override parent-pid lookup (tests). */
+    getParentPid?: (pid: number) => number | undefined;
+    /** Override registry read (tests). */
+    readEntry?: (pid: number) => PidSessionEntry | undefined;
+    /** Override full registry list for launchId match (tests). */
+    listEntries?: () => PidSessionEntry[];
+}
+export interface FeedPostResult {
+    event: ActivityEvent;
+}
+export interface PostIdentity {
+    sessionId: string;
+    mailboxId: string;
+    host: string;
+    runtime: string;
+    agent?: string;
+    cwd?: string;
+    pid?: number;
+    launchId?: string;
+    terminalId?: string;
+    tmuxPane?: string;
+}
+/**
+ * Resolve who is posting. Order:
+ *  1. Explicit --session flag
+ *  2. Env: AGENT_SESSION_ID / AGENTS_SESSION_ID / basename(AGENTS_MAILBOX_DIR)
+ *  3. Env AGENT_LAUNCH_ID → match in pid registry
+ *  4. Walk parent PIDs from startPid (default process.ppid) through by-pid registry
+ */
+export declare function resolvePostIdentity(input: Pick<FeedPostInput, 'sessionId' | 'env' | 'cwd' | 'startPid' | 'getParentPid' | 'readEntry' | 'listEntries'>): PostIdentity | undefined;
+/** Walk up to 16 ancestors looking for a by-pid registry entry with a session. */
+export declare function walkPidRegistry(startPid: number, getParent: (pid: number) => number | undefined, readEntry: (pid: number) => PidSessionEntry | undefined): PidSessionEntry | undefined;
+/** Best-effort parent pid of `pid` (Linux /proc, else `ps`). */
+export declare function parentPidOf(pid: number): number | undefined;
+export declare function normalizeStatusText(text: string): string;
+/**
+ * Append a `status.posted` milestone for the calling agent.
+ * Throws if text is empty or session identity cannot be resolved.
+ */
+export declare function postFeedStatus(input: FeedPostInput): FeedPostResult;

package/dist/lib/feed-post.js

@@ -0,0 +1,204 @@
+/**
+ * Agent status posts — deliberate progress messages into the activity stream.
+ *
+ * Surface: `agents feed post <text>` (agent-callable; humans watch via
+ * `agents feed` / `agents activity` / `agents events --module activity`).
+ *
+ * Identity is automatic: session id, agent, cwd, launch/pid/tmux provenance
+ * are resolved from the process environment and the per-pid launch registry
+ * (`lib/session/pid-registry.ts`). The agent only authors free-form text —
+ * no domain-specific flags (tickets, URLs, tracks).
+ *
+ * Storage: append-only activity log as a `status.posted` milestone. Does NOT
+ * open a feed block (blocks remain "needs you" state only).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { spawnSync } from 'child_process';
+import { appendActivityEvent, } from './activity.js';
+import { machineId } from './machine-id.js';
+import { isValidMailboxId } from './mailbox.js';
+import { listPidSessionEntries, readPidSessionEntry, } from './session/pid-registry.js';
+/** Soft cap so a runaway agent can't flood the activity lane with essays. */
+export const STATUS_POST_MAX_CHARS = 500;
+/**
+ * Resolve who is posting. Order:
+ *  1. Explicit --session flag
+ *  2. Env: AGENT_SESSION_ID / AGENTS_SESSION_ID / basename(AGENTS_MAILBOX_DIR)
+ *  3. Env AGENT_LAUNCH_ID → match in pid registry
+ *  4. Walk parent PIDs from startPid (default process.ppid) through by-pid registry
+ */
+export function resolvePostIdentity(input) {
+    const env = input.env ?? process.env;
+    const readEntry = input.readEntry ?? readPidSessionEntry;
+    const listEntries = input.listEntries ?? listPidSessionEntries;
+    const getParent = input.getParentPid ?? parentPidOf;
+    const envSession = firstValidId([
+        input.sessionId,
+        env.AGENT_SESSION_ID,
+        env.AGENTS_SESSION_ID,
+        mailboxIdFromEnv(env),
+    ]);
+    const launchId = env.AGENT_LAUNCH_ID?.trim() || undefined;
+    let registry;
+    if (launchId) {
+        registry = listEntries().find((e) => e.launchId === launchId);
+    }
+    if (!registry) {
+        const start = input.startPid ?? (typeof process.ppid === 'number' ? process.ppid : undefined);
+        if (start && start > 1) {
+            registry = walkPidRegistry(start, getParent, readEntry);
+        }
+    }
+    // Prefer env session (explicit + managed run), fill gaps from registry.
+    const sessionId = envSession ?? registry?.sessionId;
+    if (!sessionId || !isValidMailboxId(sessionId))
+        return undefined;
+    const mailboxFromEnv = mailboxIdFromEnv(env);
+    const mailboxId = mailboxFromEnv && isValidMailboxId(mailboxFromEnv)
+        ? mailboxFromEnv
+        : sessionId;
+    return {
+        sessionId,
+        mailboxId,
+        host: machineIdFromEnv(env),
+        runtime: env.AGENTS_RUNTIME?.trim() || 'headless',
+        agent: env.AGENTS_AGENT_NAME?.trim()
+            || registry?.agent
+            || detectAgentKind(env),
+        cwd: input.cwd
+            ?? (env.AGENTS_CWD?.trim() || registry?.cwd || process.cwd()),
+        pid: registry?.pid,
+        launchId: launchId || registry?.launchId,
+        terminalId: env.AGENT_TERMINAL_ID?.trim() || registry?.terminalId,
+        tmuxPane: env.TMUX_PANE?.trim() || registry?.tmuxPane,
+    };
+}
+function firstValidId(candidates) {
+    for (const raw of candidates) {
+        const id = (raw ?? '').trim();
+        if (id && isValidMailboxId(id))
+            return id;
+    }
+    return undefined;
+}
+function mailboxIdFromEnv(env) {
+    const dir = env.AGENTS_MAILBOX_DIR?.trim();
+    if (!dir)
+        return undefined;
+    const base = path.basename(dir.replace(/[/\\]+$/, ''));
+    return base || undefined;
+}
+/** Walk up to 16 ancestors looking for a by-pid registry entry with a session. */
+export function walkPidRegistry(startPid, getParent, readEntry) {
+    let pid = startPid;
+    const seen = new Set();
+    let firstHit;
+    for (let i = 0; i < 16 && pid && pid > 1 && !seen.has(pid); i++) {
+        seen.add(pid);
+        const entry = readEntry(pid);
+        if (entry) {
+            if (entry.sessionId && isValidMailboxId(entry.sessionId))
+                return entry;
+            if (!firstHit)
+                firstHit = entry;
+        }
+        pid = getParent(pid);
+    }
+    // Entry without sessionId still carries agent/cwd/launchId — usable when
+    // session id comes from env.
+    return firstHit;
+}
+/** Best-effort parent pid of `pid` (Linux /proc, else `ps`). */
+export function parentPidOf(pid) {
+    if (!Number.isInteger(pid) || pid <= 1)
+        return undefined;
+    if (process.platform === 'linux') {
+        try {
+            const status = fs.readFileSync(`/proc/${pid}/status`, 'utf8');
+            const m = status.match(/^PPid:\s*(\d+)/m);
+            if (m) {
+                const pp = Number(m[1]);
+                return Number.isInteger(pp) && pp > 0 ? pp : undefined;
+            }
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    try {
+        const r = spawnSync('ps', ['-o', 'ppid=', '-p', String(pid)], {
+            encoding: 'utf8',
+            timeout: 1000,
+        });
+        if (r.status === 0) {
+            const pp = Number((r.stdout || '').trim());
+            return Number.isInteger(pp) && pp > 0 ? pp : undefined;
+        }
+    }
+    catch {
+        /* best-effort */
+    }
+    return undefined;
+}
+export function normalizeStatusText(text) {
+    const collapsed = text.replace(/\s+/g, ' ').trim();
+    if (!collapsed)
+        return '';
+    if (collapsed.length <= STATUS_POST_MAX_CHARS)
+        return collapsed;
+    return `${collapsed.slice(0, STATUS_POST_MAX_CHARS - 1)}…`;
+}
+/**
+ * Append a `status.posted` milestone for the calling agent.
+ * Throws if text is empty or session identity cannot be resolved.
+ */
+export function postFeedStatus(input) {
+    const detail = normalizeStatusText(input.text);
+    if (!detail) {
+        throw new Error('Status text is empty. Usage: agents feed post "what just happened"');
+    }
+    const identity = resolvePostIdentity(input);
+    if (!identity) {
+        throw new Error('No session id. Run from an agents-cli session '
+            + '(AGENT_SESSION_ID / AGENTS_MAILBOX_DIR / pid registry), or pass --session <id>.');
+    }
+    const event = {
+        ts: input.ts ?? new Date().toISOString(),
+        event: 'status.posted',
+        sessionId: identity.sessionId,
+        mailboxId: identity.mailboxId,
+        host: identity.host,
+        runtime: identity.runtime,
+        cwd: identity.cwd,
+        agent: identity.agent,
+        tool: 'feed.post',
+        detail,
+        ...(identity.pid !== undefined ? { pid: identity.pid } : {}),
+        ...(identity.launchId ? { launchId: identity.launchId } : {}),
+        ...(identity.terminalId ? { terminalId: identity.terminalId } : {}),
+        ...(identity.tmuxPane ? { tmuxPane: identity.tmuxPane } : {}),
+    };
+    appendActivityEvent(event, input.activityRoot);
+    return {
+        event: {
+            v: 1,
+            tier: 'milestone',
+            ...event,
+        },
+    };
+}
+function machineIdFromEnv(env) {
+    const raw = env.AGENTS_SYNC_MACHINE_ID || undefined;
+    if (raw) {
+        return raw.split('.')[0].trim().toLowerCase().replace(/[^a-z0-9_-]/g, '-') || 'unknown';
+    }
+    return machineId();
+}
+function detectAgentKind(env) {
+    if (env.CLAUDECODE === '1')
+        return 'claude';
+    if (env.CODEX_CI || env.CODEX_HOME)
+        return 'codex';
+    return 'agent';
+}

package/dist/lib/fleet/apply.d.ts

@@ -11,6 +11,30 @@ import type { DeviceProfile } from '../devices/registry.js';
 import type { DeviceDesired, DeviceProbe, DeviceDiff, FleetAction, FleetPlan, AuthFilePayload } from './types.js';
 /** Strip a version suffix from an agent spec: `claude@latest` -> `claude`. */
 export declare function agentIdOf(spec: string): string;
+/**
+ * The explicit pinned version of a spec, or undefined for an id-level spec.
+ * `claude@2.1.170` -> `2.1.170`; `claude`, `claude@latest`, `claude@oldest`, and
+ * `claude@all` all return undefined (the label channels install-latest / are
+ * expanded upstream, so they diff at id granularity, not per-version).
+ */
+export declare function pinnedVersion(spec: string): string | undefined;
+/** True when any spec in the roster pins an explicit version (needs a version probe). */
+export declare function rosterNeedsVersions(desired: DeviceDesired[]): boolean;
+/**
+ * Expand any `<agent>@all` spec into one pinned spec per version installed on the
+ * source, so `--agent claude@all` replicates THIS machine's exact version set.
+ * `versionsOf` returns the source's installed versions for an agent id. Every
+ * other spec passes through unchanged; the result is de-duplicated in order.
+ * Throws if `@all` names an agent with no installed versions here (nothing to
+ * replicate — a clear misconfig, not a silent no-op).
+ */
+export declare function expandAllSpecs(specs: string[], versionsOf: (id: string) => string[]): string[];
+/**
+ * Parse `agents view --json` (the all-agents array form) into a map of agent id
+ * -> installed version strings. Tolerant: returns undefined on any parse failure
+ * so a version-pinned spec falls back to id-level presence rather than crashing.
+ */
+export declare function parseInstalledVersions(stdout: string): Record<string, string[]> | undefined;
 /** Source-side auth availability, computed once from `snapshotAuth`. */
 export interface SourceAuth {
     /** Agent ids the source has a readable, propagatable credential file for. */
@@ -37,8 +61,14 @@ export interface DiffContext {
 }
 /** Pure: desired vs probed -> per-device diff + flat action list. */
 export declare function diffFleet(desired: DeviceDesired[], probes: Map<string, DeviceProbe>, ctx: DiffContext): FleetPlan;
-/** Probe one device: reachability + agents-cli version + installed agent ids. */
-export declare function probeDevice(device: DeviceProfile): DeviceProbe;
+export interface ProbeOptions {
+    /** Also fetch per-agent installed versions (one extra `agents view --json`
+     * round-trip). Enable only when the plan has a version-pinned spec. */
+    withVersions?: boolean;
+}
+/** Probe one device: reachability + agents-cli version + installed agent ids
+ * (and, when `withVersions`, the installed version strings per agent). */
+export declare function probeDevice(device: DeviceProfile, opts?: ProbeOptions): DeviceProbe;
 export interface ApplyStep {
     kind: FleetAction['kind'];
     ok: boolean;