@phnx-labs/agents-cli 1.20.34 → 1.20.36

package/dist/lib/drift.js

@@ -0,0 +1,112 @@
+import { ALL_AGENT_IDS } from './agents.js';
+import { getGlobalDefault, listInstalledVersions } from './versions.js';
+import { loadManifest, isStale } from './staleness/index.js';
+import { diffVersionResources } from './doctor-diff.js';
+import { diffVersionCommands, iterCommandsCapableVersions } from './commands.js';
+import { diffVersionSkills, iterSkillsCapableVersions } from './skills.js';
+import { iterHooksCapableVersions, listUnmanagedHooksInVersionHome } from './hooks.js';
+// Lines naming exactly what's out of sync for a version, plugins prioritized:
+// each divergent plugin gets its own line with specifics (stale mirror version,
+// invalid manifest, or the bundled skills/commands missing from the mirror —
+// the system-repo plugin content that matters most). Other kinds collapse to
+// compact counts so the readout stays scannable.
+export function divergenceLines(report) {
+    const lines = [];
+    for (const p of report.kinds.plugins) {
+        if (p.status === 'missing')
+            lines.push(`plugin ${p.name} — not installed`);
+        else if (p.status === 'diff')
+            lines.push(`plugin ${p.name} — ${p.detail ?? 'mirror drifted'}`);
+    }
+    for (const kind of ['commands', 'skills', 'hooks', 'rules', 'mcp', 'permissions', 'subagents']) {
+        const rows = report.kinds[kind];
+        const miss = rows.filter((r) => r.status === 'missing').length;
+        const dif = rows.filter((r) => r.status === 'diff').length;
+        const bits = [];
+        if (miss)
+            bits.push(`${miss} missing`);
+        if (dif)
+            bits.push(`${dif} drifted`);
+        if (bits.length)
+            lines.push(`${kind.padEnd(11)} ${bits.join(' · ')}`);
+    }
+    return lines;
+}
+export function checkSyncStatus(cwd) {
+    const rows = [];
+    // Every installed version, not just the default — a stale NON-default version
+    // (e.g. one you launched from yesterday) is exactly the rot that silently
+    // serves outdated/invalid resources and that `--fix` now heals. Hiding it here
+    // is why that class of bug went unnoticed.
+    for (const agent of ALL_AGENT_IDS) {
+        const def = getGlobalDefault(agent);
+        for (const version of listInstalledVersions(agent)) {
+            const manifest = loadManifest(agent, version);
+            const status = !manifest
+                ? 'never-synced'
+                : isStale(manifest, agent, version, cwd) ? 'stale' : 'fresh';
+            const row = { agent, version, status, isDefault: version === def };
+            if (status === 'stale') {
+                // Resolve the specifics against non-project layers (the global home is
+                // never reconciled against per-cwd project resources).
+                const report = diffVersionResources(agent, version, { cwd, excludeProject: true });
+                const lines = divergenceLines(report);
+                if (lines.length)
+                    row.divergence = lines;
+            }
+            rows.push(row);
+        }
+    }
+    return rows;
+}
+export function countOrphans() {
+    const byKey = new Map();
+    const ensure = (agent, version) => {
+        const key = `${agent}@${version}`;
+        let row = byKey.get(key);
+        if (!row) {
+            row = { agent, version, commands: 0, skills: 0, hooks: 0 };
+            byKey.set(key, row);
+        }
+        return row;
+    };
+    for (const { agent, version } of iterCommandsCapableVersions()) {
+        const diff = diffVersionCommands(agent, version);
+        if (diff.orphans.length > 0)
+            ensure(agent, version).commands = diff.orphans.length;
+    }
+    for (const { agent, version } of iterSkillsCapableVersions()) {
+        const diff = diffVersionSkills(agent, version);
+        if (diff.orphans.length > 0)
+            ensure(agent, version).skills = diff.orphans.length;
+    }
+    // Orphan hooks are scripts in the version home that no agents.yaml/hooks.yaml
+    // entry registers — so the registrar never wires them to an event and they
+    // never fire. (Distinct from the source-diff `diffVersionHooks().orphans`,
+    // which false-flags valid system-sourced registered hooks.)
+    for (const { agent, version } of iterHooksCapableVersions()) {
+        const dead = listUnmanagedHooksInVersionHome(agent, version);
+        if (dead.length > 0)
+            ensure(agent, version).hooks = dead.length;
+    }
+    return Array.from(byKey.values()).filter((r) => r.commands + r.skills + r.hooks > 0);
+}
+/**
+ * Compute the same drift/divergence diagnostic `agents doctor` prints, reduced
+ * to a summary with a single `hasDrift` boolean. The gate `agents check` maps
+ * to an exit code; the readout `agents doctor` renders in full.
+ */
+export function computeDrift(cwd) {
+    const syncRows = checkSyncStatus(cwd);
+    const orphanRows = countOrphans();
+    const staleCount = syncRows.filter((r) => r.status === 'stale').length;
+    const neverSyncedCount = syncRows.filter((r) => r.status === 'never-synced').length;
+    return {
+        syncRows,
+        orphanRows,
+        staleCount,
+        neverSyncedCount,
+        orphanVersionCount: orphanRows.length,
+        hasDrift: syncRows.some((r) => r.status !== 'fresh'),
+    };
+}

package/dist/lib/events.d.ts

@@ -1,7 +1,7 @@
 /**
  * Centralized event logging for agents-cli.
  *
- * Structured JSONL logs at ~/.agents/logs/events-YYYY-MM-DD.jsonl
+ * Structured JSONL logs at ~/.agents/.cache/logs/events-YYYY-MM-DD.jsonl
  * with automatic daily rotation and rich metadata for debugging/auditing.
  *
  * Features:
@@ -11,7 +11,7 @@
  * - Permissions: logs dir is 0700, files are 0600 (owner-only)
  * - Performance tracking: withTiming() wrapper for any async function
  */
-export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'resource.sync' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'error' | 'warn' | 'info' | 'debug';
+export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'resource.sync' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'error' | 'warn' | 'info' | 'debug';
 export interface EventMeta {
     ts: string;
     tz: string;
@@ -22,12 +22,18 @@ export interface EventMeta {
     pid: number;
     ppid: number;
     event: EventType;
+    osUser: string;
+    transport: 'local' | 'ssh';
+    sshClientIp?: string;
 }
 export interface EventPayload {
     agent?: string;
     version?: string;
     sessionId?: string;
     cwd?: string;
+    /** Top-level command group, e.g. 'teams', 'secrets' — the audit filter key. */
+    module?: string;
+    /** Full command path, e.g. 'teams create', 'secrets get'. */
     command?: string;
     args?: string[];
     input?: string;
@@ -155,6 +161,7 @@ export declare function query(options: {
     eventTypes?: EventType[];
     agent?: string;
     command?: string;
+    module?: string;
     limit?: number;
 }): EventRecord[];
 /**
@@ -170,4 +177,4 @@ export declare function getTimingStats(label: string, options?: {
     p50Ms: number;
     p95Ms: number;
 } | null;
-export declare const LOGS_PATH: string;
+export declare function getLogsPath(): string;

package/dist/lib/events.js

@@ -1,7 +1,7 @@
 /**
  * Centralized event logging for agents-cli.
  *
- * Structured JSONL logs at ~/.agents/logs/events-YYYY-MM-DD.jsonl
+ * Structured JSONL logs at ~/.agents/.cache/logs/events-YYYY-MM-DD.jsonl
  * with automatic daily rotation and rich metadata for debugging/auditing.
  *
  * Features:
@@ -15,9 +15,26 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import { createHash } from 'node:crypto';
+import { parseSshConnection } from './session/provenance.js';
+import { getLogsDir } from './state.js';
 // ─── Constants ────────────────────────────────────────────────────────────────
-// Logs live under the cache bucket — they're regenerable telemetry.
-const LOGS_DIR = path.join(os.homedir(), '.agents', '.cache', 'logs');
+// Logs live under the cache bucket — they're regenerable telemetry. Route
+// through state's canonical home anchor (HOME override → os.homedir()) rather
+// than a bare os.homedir(): on Windows os.homedir() reads USERPROFILE and
+// ignores a HOME override, so a test (or any caller) that redirects HOME would
+// have its events silently written to the real profile instead. state.getLogsDir()
+// honors the HOME override on every platform while falling back to os.homedir()
+// (== USERPROFILE on Windows) in production where HOME is unset.
+//
+// Resolved lazily + memoized: importing this module must NOT call getLogsDir()
+// at eval time. events.ts is pulled in transitively (skills/versions/exec/
+// runner), and several tests mock './state.js' with partial factories that omit
+// getLogsDir — an eager call would crash those on import. Deferring to first use
+// keeps a bare import side-effect-free while staying a one-time resolution.
+let _logsDir;
+function logsDir() {
+    return (_logsDir ??= getLogsDir());
+}
 /** Default retention period in days. */
 const DEFAULT_RETENTION_DAYS = 7;
 /** Default max length for truncated strings. */
@@ -53,16 +70,16 @@ function getLogFilePath(date = new Date()) {
     const yyyy = date.getFullYear();
     const mm = String(date.getMonth() + 1).padStart(2, '0');
     const dd = String(date.getDate()).padStart(2, '0');
-    return path.join(LOGS_DIR, `events-${yyyy}-${mm}-${dd}.jsonl`);
+    return path.join(logsDir(), `events-${yyyy}-${mm}-${dd}.jsonl`);
 }
 function ensureLogsDir() {
-    if (!fs.existsSync(LOGS_DIR)) {
-        fs.mkdirSync(LOGS_DIR, { recursive: true, mode: DIR_MODE });
+    if (!fs.existsSync(logsDir())) {
+        fs.mkdirSync(logsDir(), { recursive: true, mode: DIR_MODE });
     }
     else {
         // Ensure permissions are correct on existing dir
         try {
-            fs.chmodSync(LOGS_DIR, DIR_MODE);
+            fs.chmodSync(logsDir(), DIR_MODE);
         }
         catch {
             // May fail if not owner
@@ -130,6 +147,30 @@ function truncatePayload(payload, maxLength = DEFAULT_TRUNCATE_LENGTH) {
     }
     return result;
 }
+/**
+ * Who is running this process and from where. Derived once per process from the
+ * OS user and $SSH_CONNECTION (via the same parser the sessions layer uses), then
+ * cached — provenance can't change mid-process, so every emit() pays for it once.
+ */
+let _origin;
+function auditOrigin() {
+    if (_origin)
+        return _origin;
+    let osUser = 'unknown';
+    try {
+        osUser = os.userInfo().username;
+    }
+    catch {
+        // Container/edge cases where the uid has no passwd entry.
+    }
+    const ssh = process.env.SSH_CONNECTION ? parseSshConnection(process.env.SSH_CONNECTION) : undefined;
+    _origin = {
+        osUser,
+        transport: ssh ? 'ssh' : 'local',
+        ...(ssh ? { sshClientIp: ssh.clientIp } : {}),
+    };
+    return _origin;
+}
 // ─── Core API ─────────────────────────────────────────────────────────────────
 /**
  * Emit a structured event to the daily log file.
@@ -152,23 +193,33 @@ export function emit(event, payload = {}) {
             pid: process.pid,
             ppid: process.ppid,
             event,
+            ...auditOrigin(),
             ...truncatePayload(payload),
         };
         const line = JSON.stringify(record) + '\n';
         const logPath = getLogFilePath();
+        const isNew = !fs.existsSync(logPath);
         fs.appendFileSync(logPath, line, { mode: FILE_MODE });
-        // Ensure file permissions (appendFileSync doesn't respect mode on existing files)
-        try {
-            fs.chmodSync(logPath, FILE_MODE);
-        }
-        catch {
-            // May fail if not owner
+        // appendFileSync's mode only applies when it CREATES the file, so we chmod
+        // to guarantee 0600 — but only on first write to a given path this process.
+        // command.start/end fire on every invocation; chmod-per-append would double
+        // the syscalls on the hot path for no gain (perms don't drift mid-run).
+        if (isNew || logPath !== _chmoddedPath) {
+            _chmoddedPath = logPath;
+            try {
+                fs.chmodSync(logPath, FILE_MODE);
+            }
+            catch {
+                // May fail if not owner
+            }
         }
     }
     catch {
         // Silent failure - logging should never break the CLI
     }
 }
+/** Last log path this process chmod'd — avoids a redundant chmod per append. */
+let _chmoddedPath;
 /**
  * Convenience wrapper for timed operations.
  * Returns a function to call when the operation completes.
@@ -360,10 +411,10 @@ export function emitError(err, payload = {}) {
  */
 export function rotate(retentionDays = DEFAULT_RETENTION_DAYS) {
     try {
-        if (!fs.existsSync(LOGS_DIR))
+        if (!fs.existsSync(logsDir()))
             return 0;
         const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1000;
-        const files = fs.readdirSync(LOGS_DIR).filter(f => f.startsWith('events-') && f.endsWith('.jsonl'));
+        const files = fs.readdirSync(logsDir()).filter(f => f.startsWith('events-') && f.endsWith('.jsonl'));
         let removed = 0;
         for (const file of files) {
             const match = file.match(/^events-(\d{4})-(\d{2})-(\d{2})\.jsonl$/);
@@ -372,7 +423,7 @@ export function rotate(retentionDays = DEFAULT_RETENTION_DAYS) {
             const [, yyyy, mm, dd] = match;
             const fileDate = new Date(parseInt(yyyy), parseInt(mm) - 1, parseInt(dd));
             if (fileDate.getTime() < cutoff) {
-                fs.unlinkSync(path.join(LOGS_DIR, file));
+                fs.unlinkSync(path.join(logsDir(), file));
                 removed++;
             }
         }
@@ -402,34 +453,58 @@ export function maybeRotate() {
  * @returns Array of event records
  */
 export function query(options) {
-    const { startDate, endDate = new Date(), eventTypes, agent, command, limit } = options;
+    const { startDate, endDate = new Date(), eventTypes, agent, command, module, limit } = options;
     const results = [];
-    if (!fs.existsSync(LOGS_DIR))
+    if (!fs.existsSync(logsDir()))
         return results;
-    const files = fs.readdirSync(LOGS_DIR)
+    const files = fs.readdirSync(logsDir())
         .filter(f => f.startsWith('events-') && f.endsWith('.jsonl'))
         .sort()
         .reverse();
+    // Coarse file skip works on whole days, so floor the bounds to midnight —
+    // otherwise a sub-day window (`--since 2h` at 15:00 → startDate 13:00) would
+    // drop *today's* file, whose date stamps to 00:00. Precise filtering below is
+    // per-record on `ts`.
+    const startDay = startDate
+        ? new Date(startDate.getFullYear(), startDate.getMonth(), startDate.getDate())
+        : undefined;
+    const endDay = endDate
+        ? new Date(endDate.getFullYear(), endDate.getMonth(), endDate.getDate())
+        : undefined;
+    const startMs = startDate?.getTime();
+    const endMs = endDate?.getTime();
     for (const file of files) {
         const match = file.match(/^events-(\d{4})-(\d{2})-(\d{2})\.jsonl$/);
         if (!match)
             continue;
         const [, yyyy, mm, dd] = match;
         const fileDate = new Date(parseInt(yyyy), parseInt(mm) - 1, parseInt(dd));
-        if (startDate && fileDate < startDate)
+        if (startDay && fileDate < startDay)
             continue;
-        if (endDate && fileDate > endDate)
+        if (endDay && fileDate > endDay)
             continue;
-        const content = fs.readFileSync(path.join(LOGS_DIR, file), 'utf-8');
+        const content = fs.readFileSync(path.join(logsDir(), file), 'utf-8');
         const lines = content.trim().split('\n').filter(Boolean);
         for (const line of lines.reverse()) {
             try {
                 const record = JSON.parse(line);
+                // Precise per-record window — the file skip above is day-granular only.
+                const recMs = Date.parse(record.ts);
+                if (startMs !== undefined && !isNaN(recMs) && recMs < startMs)
+                    continue;
+                if (endMs !== undefined && !isNaN(recMs) && recMs > endMs)
+                    continue;
                 if (eventTypes && !eventTypes.includes(record.event))
                     continue;
                 if (agent && record.agent !== agent)
                     continue;
-                if (command && record.command !== command)
+                // `--command` matches by path prefix on a word boundary, so a coarse
+                // "teams" catches "teams create"/"teams remove" while an exact
+                // "teams create" stays exact.
+                if (command && record.command !== command &&
+                    !(typeof record.command === 'string' && record.command.startsWith(command + ' ')))
+                    continue;
+                if (module && record.module !== module)
                     continue;
                 results.push(record);
                 if (limit && results.length >= limit) {
@@ -469,4 +544,6 @@ export function getTimingStats(label, options = {}) {
     };
 }
 // ─── Exports ──────────────────────────────────────────────────────────────────
-export const LOGS_PATH = LOGS_DIR;
+export function getLogsPath() {
+    return logsDir();
+}

package/dist/lib/exec.d.ts

@@ -230,6 +230,12 @@ export interface FallbackEntry {
     agent: AgentId;
     /** Optional pinned version (e.g. '0.116.0'). When set, takes precedence over the active default. */
     version?: string;
+    /**
+     * Env vars merged over options.env for THIS attempt only. Used by profiles
+     * with `fallback_model` to swap the model env key (e.g. ANTHROPIC_MODEL) on
+     * a same-agent retry without touching auth or base URL.
+     */
+    envOverride?: Record<string, string>;
 }
 /** ExecOptions extended with a fallback chain for rate-limit cascading. */
 export interface FallbackOptions extends ExecOptions {
@@ -237,6 +243,17 @@ export interface FallbackOptions extends ExecOptions {
     fallback: FallbackEntry[];
     /** Fallback requires a prompt -- chain handoff doesn't apply to interactive sessions. */
     prompt: string;
+    /**
+     * Optional out-param the caller reads AFTER the call to learn which chain
+     * entry actually executed — updated to each entry as it is attempted, so on
+     * return it holds the agent+version whose exit code is returned. Lets the
+     * audit log record the fallback that really ran, not always the primary
+     * (issue #347).
+     */
+    dispatchSink?: {
+        agent?: AgentId;
+        version?: string;
+    };
 }
 /**
  * Build the prompt handed to the fallback agent when the primary was stopped

package/dist/lib/exec.js

@@ -16,6 +16,9 @@ import { resolveModel, buildReasoningFlags } from './models.js';
 import { maybeRotate, createTimer, redactPrompt, redactArgs } from './events.js';
 import { sanitizeProcessEnv } from './secrets/bundles.js';
 import { getShimsDir } from './state.js';
+import { writePidSessionEntry, extractSessionIdArg } from './session/pid-registry.js';
+import { mailboxDir, isValidMailboxId } from './mailbox.js';
+import { composeWin32CommandLine } from './platform/index.js';
 /**
  * Map a raw mode string (CLI flag, YAML field, env var) to the canonical Mode.
  *
@@ -181,6 +184,14 @@ export function buildExecEnv(options) {
             : (resolvedVersion && isVersionInstalled('claude', resolvedVersion) ? resolvedVersion : null);
         if (version) {
             result.CLAUDE_CONFIG_DIR = path.join(getVersionHomePath('claude', version), '.claude');
+            // A managed pin lives in a per-version dir; Claude Code's own background
+            // auto-updater would rewrite that pinned binary in place (and has left it
+            // half-swapped and broken). Disable it so a pin stays a pin. Honor an
+            // explicit user value — from process.env (already in result) or from
+            // options.env (spread over result below).
+            if (result.DISABLE_AUTOUPDATER === undefined) {
+                result.DISABLE_AUTOUPDATER = '1';
+            }
         }
         delete result.CODEX_HOME;
         delete result.COPILOT_HOME;
@@ -236,6 +247,14 @@ export function buildExecEnv(options) {
         delete result.COPILOT_HOME;
         delete result.KIMI_CODE_HOME;
     }
+    // Point the agent at its own mailbox so the PreToolUse `mailbox-inject` hook
+    // knows which box to drain and inject mid-run. Keyed by the session id — the
+    // same id the writer resolves via mailboxIdForActiveSession(). A loop run
+    // overrides this to its run-level box via options.env (spread below), so all
+    // iterations share one inbox.
+    if (options.sessionId && isValidMailboxId(options.sessionId)) {
+        result.AGENTS_MAILBOX_DIR = mailboxDir(options.sessionId);
+    }
     return {
         ...result,
         ...options.env,
@@ -471,11 +490,12 @@ export function buildExecCommand(options) {
     // on Linux installs where the shims dir isn't on PATH, spawning the bare
     // versioned name fails with ENOENT even though `agents view` shows the agent.
     //
-    // On Windows the shims dir holds a `.cmd` companion next to the bash alias
-    // (see createVersionedAlias); prefer it so spawn() can launch it (the bash
-    // script is not directly executable by cmd.exe). When no shim exists on disk
-    // we fall back to the bare versioned name, which spawnAgent() resolves via
-    // PATH (+ PATHEXT/shell on Windows).
+    // On Windows the alias is materialized as a `.cmd` only (see
+    // createVersionedAlias — a bash alias next to it would shadow the `.cmd` in
+    // cmd.exe/PowerShell name resolution); the extensionless existsSync branch
+    // below still matches a legacy install's bash alias. When no shim exists on
+    // disk we fall back to the bare versioned name, which spawnAgent() resolves
+    // via PATH (+ PATHEXT/shell on Windows).
     if (options.version && cmd.length > 0) {
         const versionedName = `${cmd[0]}@${options.version}`;
         const absPath = path.join(getShimsDir(), versionedName);
@@ -671,7 +691,14 @@ export function resolveShimSpawn(platform, binary, extraArgs) {
         // Use win32 path semantics regardless of the host running this (the platform
         // is the parameter, not process.platform) so `C:\...` reads as absolute.
         const useShell = !path.win32.isAbsolute(binary) || binary.endsWith('.cmd');
-        return { command: binary, args: extraArgs, shell: useShell };
+        if (useShell) {
+            // DEP0190-safe: hand cmd.exe ONE fully-quoted command line with an EMPTY
+            // args array, so Node never concatenates `extraArgs` (which carry the
+            // user's raw prompt/flags) into the shell line unescaped — that concat is
+            // both the deprecation and a command-injection surface.
+            return { command: composeWin32CommandLine(binary, extraArgs), args: [], shell: true };
+        }
+        return { command: binary, args: extraArgs, shell: false };
     }
     return { command: binary, args: extraArgs, shell: false };
 }
@@ -704,6 +731,21 @@ export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
     const { command, args, shell } = resolveShimSpawn(process.platform, binary, [...launchArgs, ...rawArgs]);
     return new Promise((resolve) => {
         const child = spawn(command, args, { cwd, stdio: 'inherit', env, shell });
+        // Record the launch so `ag sessions --active` can attribute the agent
+        // process to its cwd (and exact session when the caller passed
+        // --session-id). Vital on Windows, where there is no lsof to recover a
+        // foreign process's cwd. On the shell path this pid is the cmd.exe
+        // wrapper, not the agent binary — the active scan resolves that by
+        // walking the candidate's ancestors (readAncestorSessionEntry).
+        if (child.pid) {
+            writePidSessionEntry({
+                pid: child.pid,
+                agent,
+                sessionId: extractSessionIdArg(rawArgs),
+                cwd,
+                startedAtMs: Date.now(),
+            });
+        }
         child.on('exit', (code, signal) => resolve(code ?? (signal ? 1 : 0)));
         child.on('error', (err) => {
             process.stderr.write(`agents: failed to launch ${agent}: ${err.message}\n`);
@@ -722,6 +764,15 @@ export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
  * unbuffered.
  */
 async function spawnAgent(options) {
+    // Assign a known session id up front for agents that accept one, so the
+    // launcher can record an EXACT pid -> session mapping (see pid-registry) —
+    // otherwise the headless `ag sessions --active` path can only guess
+    // "newest .jsonl in the cwd" and collapses co-located agents onto one row.
+    // Claude: `--session-id <uuid>` CREATES the session with that id (wired in
+    // buildExecCommand). Skip on resume — the id is the one being resumed.
+    if (options.agent === 'claude' && !options.resume && !options.sessionId) {
+        options = { ...options, sessionId: randomUUID() };
+    }
     const cmd = buildExecCommand(options);
     const [executable, ...args] = cmd;
     const timeoutMs = options.timeout ? parseTimeout(options.timeout) : undefined;
@@ -762,14 +813,32 @@ async function spawnAgent(options) {
             ? ['inherit', 'inherit', 'inherit']
             : ['inherit', tapStdout ? 'pipe' : 'inherit', 'pipe'];
         // On Windows, .cmd batch wrappers (npm-installed CLIs) require shell:true
-        // whether addressed by name or absolute path.
+        // whether addressed by name or absolute path. On that shell path, compose a
+        // single fully-quoted command line and pass an EMPTY args array (see
+        // composeWin32CommandLine) so Node never concatenates the args array — which
+        // carries the user's prompt — into the cmd.exe line unescaped (DEP0190 +
+        // command injection).
         const useShell = process.platform === 'win32' && (!path.isAbsolute(executable) || executable.endsWith('.cmd'));
-        const child = spawn(executable, args, {
+        const spawnCommand = useShell ? composeWin32CommandLine(executable, args) : executable;
+        const spawnArgs = useShell ? [] : args;
+        const child = spawn(spawnCommand, spawnArgs, {
             cwd: options.cwd || process.cwd(),
             stdio,
             env: buildExecEnv(options),
             shell: useShell,
         });
+        // Record this launch so `ag sessions --active` can map the pid to its exact
+        // session (sessionId is set for Claude above) instead of guessing the newest
+        // .jsonl in the cwd — the collapse that made co-located agents indistinguishable.
+        // Best-effort: pruned when the pid dies; a failed write just degrades to the heuristic.
+        writePidSessionEntry({
+            pid: child.pid ?? 0,
+            agent: options.agent,
+            sessionId: options.sessionId,
+            cwd: options.cwd || process.cwd(),
+            tmuxPane: process.env.TMUX_PANE,
+            startedAtMs: Date.now(),
+        });
         // Mark startup time (time from function call to process spawn)
         timer.mark('startup');
         let budgetKilled = false;
@@ -994,9 +1063,20 @@ export async function runWithFallback(options) {
         }
     }
     for (let i = 0; i < chain.length; i++) {
-        const { agent, version } = chain[i];
+        const { agent, version, envOverride } = chain[i];
+        // Record the entry we're about to attempt so the caller (audit log) sees the
+        // agent+version that actually ran, even after a rate-limit handoff.
+        if (options.dispatchSink) {
+            options.dispatchSink.agent = agent;
+            options.dispatchSink.version = version;
+        }
         const pinnedSessionId = agent === 'claude' ? randomUUID() : undefined;
-        const prompt = prevAgent
+        // Same-host retry (same agent+version as previous entry — used by profile
+        // `fallback_model` swaps) keeps the original prompt: the model changed,
+        // not the CLI, so a `/continue` handoff prompt would be misleading.
+        const prev = i > 0 ? chain[i - 1] : undefined;
+        const sameHostRetry = !!prev && prev.agent === agent && prev.version === version;
+        const prompt = prevAgent && !sameHostRetry
             ? buildFallbackPrompt(prevAgent, prevSessionId, agent, options.prompt)
             : options.prompt;
         const execOpts = {
@@ -1004,12 +1084,18 @@ export async function runWithFallback(options) {
             agent,
             version,
             prompt,
+            env: envOverride ? { ...(options.env ?? {}), ...envOverride } : options.env,
             sessionId: pinnedSessionId ?? (i === 0 ? options.sessionId : undefined),
         };
         const label = version ? `${agent}@${version}` : agent;
+        const modelSwapNote = sameHostRetry && envOverride
+            ? ` (retry with ${Object.entries(envOverride).map(([k, v]) => `${k}=${v}`).join(', ')})`
+            : '';
         const banner = i === 0
             ? `[agents] running ${label}`
-            : `[agents] fallback → ${label}`;
+            : sameHostRetry
+                ? `[agents] retry → ${label}${modelSwapNote}`
+                : `[agents] fallback → ${label}`;
         process.stderr.write(`${banner}${pinnedSessionId ? ` (session ${pinnedSessionId.slice(0, 8)})` : ''}\n`);
         let result;
         try {
@@ -1032,7 +1118,9 @@ export async function runWithFallback(options) {
         }
         const next = chain[i + 1];
         const nextLabel = next.version ? `${next.agent}@${next.version}` : next.agent;
-        process.stderr.write(`[agents] ${label} hit rate limit. Handing off to ${nextLabel}...\n`);
+        const nextSameHost = next.agent === agent && next.version === version;
+        const handoffVerb = nextSameHost ? 'Retrying on same host' : 'Handing off';
+        process.stderr.write(`[agents] ${label} hit rate limit. ${handoffVerb} to ${nextLabel}...\n`);
         prevAgent = agent;
         prevSessionId = pinnedSessionId;
     }

package/dist/lib/git.d.ts

@@ -112,6 +112,11 @@ export declare function isSystemRepoOrigin(dir: string): Promise<boolean>;
  * Check if repo has uncommitted changes (including untracked files).
  */
 export declare function hasLocalChanges(dir: string): Promise<boolean>;
+/**
+ * Render an absolute path in ~-relative form with forward slashes, matching the
+ * way the rest of the CLI prints home-anchored paths (e.g. `~/.agents/.system`).
+ */
+export declare function displayHomePath(dir: string): string;
 /**
  * Pull changes in an existing repo.
  * Refuses to pull if the working tree is dirty -- user must commit or discard changes first.
@@ -121,6 +126,28 @@ export declare function pullRepo(dir: string): Promise<{
     commit: string;
     error?: string;
 }>;
+/**
+ * Rebase a repo onto its remote, optionally pushing local commits back up.
+ *
+ * The one-repo counterpart to `pullRepo` used by `agents sync <repo>`:
+ *   1. Refuse if the working tree is dirty (commit or discard first).
+ *   2. `git fetch origin` then `git pull --rebase origin <branch>` — rebase, not
+ *      merge, so a local commit lands cleanly on top of upstream with no merge
+ *      bubble.
+ *   3. When `push` is set, `git push origin <branch>` to send local commits up.
+ *
+ * The branch is read from the repo's current HEAD (falls back to `main`) rather
+ * than hardcoded. System repos pass `push: false` — they are pull-only mirrors
+ * of the npm-shipped upstream.
+ */
+export declare function syncRepoGit(dir: string, opts: {
+    push: boolean;
+}): Promise<{
+    success: boolean;
+    commit: string;
+    pushed: boolean;
+    error?: string;
+}>;
 /**
  * Get git status for sync display.
  * Returns files categorized by their status relative to HEAD.