@phnx-labs/agents-cli 1.22.66 → 1.22.69

package/dist/lib/fleet-shared-state.js

@@ -0,0 +1,105 @@
+/**
+ * Non-secret daemon state exchanged through the already fleet-synced user repo.
+ *
+ * Each device owns exactly one file under `~/.agents/devices/<device>/`, so
+ * normal `agents repo push/pull user` merges the fleet without devices dialing
+ * one another on every daemon tick. OAuth/setup-token values never belong here:
+ * auth publishes only a readiness verdict; the existing encrypted SSH transport
+ * remains the one path that may carry secret material.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { assertValidDeviceName } from './devices/registry.js';
+import { atomicWriteFileSync, ensureLockTarget, withFileLock } from './fs-atomic.js';
+import { getUserAgentsDir } from './state.js';
+export const FLEET_SHARED_STATE_VERSION = 1;
+export const FLEET_SHARED_STATE_FILE = 'daemon-state.json';
+/** Path owned by one device in the conflict-free tracked device-doc tree. */
+export function fleetSharedStatePath(device, userAgentsDir = getUserAgentsDir()) {
+    assertValidDeviceName(device);
+    return path.join(userAgentsDir, 'devices', device, FLEET_SHARED_STATE_FILE);
+}
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function parseFleetSharedDeviceState(raw, owner) {
+    const parsed = JSON.parse(raw);
+    if (!isRecord(parsed) || parsed.version !== FLEET_SHARED_STATE_VERSION || parsed.device !== owner) {
+        throw new Error('unrecognized shared-state envelope');
+    }
+    const usage = parsed.usage;
+    if (usage !== undefined && (!isRecord(usage) || !isRecord(usage.rows))) {
+        throw new Error('unrecognized usage snapshot');
+    }
+    const auth = parsed.auth;
+    if (auth !== undefined &&
+        (!isRecord(auth) || !['ready', 'missing', 'invalid'].includes(String(auth.status)))) {
+        throw new Error('unrecognized auth verdict');
+    }
+    return parsed;
+}
+/**
+ * Merge one daemon-owned field into this device's shared file under a real
+ * inter-process lock. Stable serialization avoids dirtying the user repo when
+ * neither usage nor auth state changed.
+ */
+export function updateFleetSharedDeviceState(device, patch, userAgentsDir = getUserAgentsDir()) {
+    const file = fleetSharedStatePath(device, userAgentsDir);
+    ensureLockTarget(file, '');
+    return withFileLock(file, () => {
+        let current = {
+            version: FLEET_SHARED_STATE_VERSION,
+            device,
+        };
+        try {
+            const raw = fs.readFileSync(file, 'utf-8').trim();
+            if (raw)
+                current = parseFleetSharedDeviceState(raw, device);
+        }
+        catch {
+            // The owning device repairs its own malformed file from authoritative
+            // local state. Peer files are never repaired by this writer.
+        }
+        const next = {
+            ...current,
+            ...(patch.usage !== undefined ? { usage: patch.usage } : {}),
+            ...(patch.auth !== undefined ? { auth: patch.auth } : {}),
+            version: FLEET_SHARED_STATE_VERSION,
+            device,
+        };
+        const serialized = `${JSON.stringify(next, null, 2)}\n`;
+        if (fs.readFileSync(file, 'utf-8') === serialized)
+            return { changed: false, path: file };
+        atomicWriteFileSync(file, serialized, 'utf-8');
+        return { changed: true, path: file };
+    });
+}
+/** Read every valid peer-owned state file; malformed peers fail separately. */
+export function readFleetSharedDeviceStates(userAgentsDir = getUserAgentsDir()) {
+    const devicesDir = path.join(userAgentsDir, 'devices');
+    let entries;
+    try {
+        entries = fs.readdirSync(devicesDir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { states: [], errors: [] };
+        return { states: [], errors: [{ device: '*', message: err.message }] };
+    }
+    const states = [];
+    const errors = [];
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!entry.isDirectory())
+            continue;
+        const file = path.join(devicesDir, entry.name, FLEET_SHARED_STATE_FILE);
+        if (!fs.existsSync(file))
+            continue;
+        try {
+            states.push(parseFleetSharedDeviceState(fs.readFileSync(file, 'utf-8'), entry.name));
+        }
+        catch (err) {
+            errors.push({ device: entry.name, message: err.message });
+        }
+    }
+    return { states, errors };
+}

package/dist/lib/hosts/remote-cmd.d.ts

@@ -118,6 +118,8 @@ export interface WindowsAgentsCommand {
      * pass false for probes whose reachability keys off a sentinel, not the code.
      */
     propagateExit?: boolean;
+    /** Remap a reached peer command's 255 to 254 so SSH's own 255 stays unambiguous. */
+    remapExit255?: boolean;
 }
 /**
  * The PowerShell script (pre-encoding) that {@link buildWindowsAgentsCommand}

package/dist/lib/hosts/remote-cmd.js

@@ -131,6 +131,11 @@ export const RUN_OPTION_FORWARDING = {
     // process follows the remote run to completion, so its exit handler fires at
     // the right moment anyway.
     notify: 'local-only',
+    // --no-trace-sync (traceSync=false) gates the LOCAL run-exit trace auto-sync,
+    // which only arms for local runs anyway (exec.ts skips it for --device/--lease).
+    // On a --device dispatch the remote box runs its own run-exit sync, so this
+    // flag is never forwarded — it is a local-exit-behavior toggle, not remote.
+    traceSync: 'local-only',
     // Deprecated alias for --device auto; resolved on the launching box before SSH.
     smart: 'local-only',
     // Broadcast mode (agents run --broadcast) is its own fan-out dispatch — mutually
@@ -289,7 +294,7 @@ export function stripClixml(stdout) {
         .trim();
 }
 export function windowsAgentsScript(cmd) {
-    const { args, env, cwd, propagateExit = true } = cmd;
+    const { args, env, cwd, propagateExit = true, remapExit255 = false } = cmd;
     const parts = [POWERSHELL_PROGRESS_SILENCE];
     if (env)
         for (const [k, v] of Object.entries(env))
@@ -297,8 +302,12 @@ export function windowsAgentsScript(cmd) {
     if (cwd)
         parts.push(`Set-Location -LiteralPath ${powershellQuote(cwd)}`);
     parts.push(`& ${['agents', ...args].map(powershellQuote).join(' ')}`);
-    if (propagateExit)
-        parts.push('exit $LASTEXITCODE');
+    if (propagateExit) {
+        if (remapExit255)
+            parts.push('$agentsExit = $LASTEXITCODE', 'if ($agentsExit -eq 255) { exit 254 }', 'exit $agentsExit');
+        else
+            parts.push('exit $LASTEXITCODE');
+    }
     return parts.join('; ');
 }
 /**

package/dist/lib/lock-compromise.d.ts

@@ -0,0 +1,8 @@
+/**
+ * proper-lockfile invokes this callback from its background refresh timer.
+ * Its default is to throw there, outside the caller's promise chain, which can
+ * terminate the daemon. These leases are advisory serialization barriers: log
+ * a broken lease and let the owning operation finish instead of crashing the
+ * shared process.
+ */
+export declare function logAndContinueOnLockCompromised(scope: string): (err: Error) => void;

package/dist/lib/lock-compromise.js

@@ -0,0 +1,12 @@
+/**
+ * proper-lockfile invokes this callback from its background refresh timer.
+ * Its default is to throw there, outside the caller's promise chain, which can
+ * terminate the daemon. These leases are advisory serialization barriers: log
+ * a broken lease and let the owning operation finish instead of crashing the
+ * shared process.
+ */
+export function logAndContinueOnLockCompromised(scope) {
+    return (err) => {
+        console.warn(`[agents ${scope}] Lock was compromised; continuing without crashing: ${err.message}`);
+    };
+}

package/dist/lib/monitors/engine.d.ts

@@ -58,6 +58,7 @@ export declare class MonitorEngine {
     private monitors;
     private lastEval;
     private ticking;
+    private running;
     constructor(logFn?: LogFn);
     /** Load owned+enabled monitors and start the tick loop. */
     start(options?: {
@@ -65,7 +66,7 @@ export declare class MonitorEngine {
     }): void;
     /** Reload monitor configs (SIGHUP). */
     reload(): void;
-    /** Stop the tick loop. */
+    /** Stop the tick loop. No monitor dispatches after this until `start()`. */
     stop(): void;
     private loadAll;
     private intervalMs;

package/dist/lib/monitors/engine.js

@@ -54,6 +54,14 @@ export function decideFire(monitor, observation) {
     const raw = observation.raw;
     const payload = observation.meta ?? {};
     const dedupeKey = cond.dedupeKey;
+    // A snapshot the source flagged as an OBSERVATION FAILURE (a poll that exited
+    // non-zero or emitted a transport/auth/rate-limit error) is never a value
+    // change: don't fire, don't move the baseline — so an empty→error→empty flap
+    // can't read as two value changes (PHNX-3510). The engine records it as a
+    // failed check separately, feeding the drought health streak.
+    if (observation.failed) {
+        return { fire: false, value: raw, dedupeKey, persist: false, event: null };
+    }
     if (cond.mode === 'every') {
         // Fire on every tick that carries a real observation. An empty (or
         // whitespace-only) observation means "nothing to report": firing an action
@@ -122,11 +130,13 @@ export class MonitorEngine {
     monitors = [];
     lastEval = new Map();
     ticking = false;
+    running = false;
     constructor(logFn = () => { }) {
         this.logFn = logFn;
     }
     /** Load owned+enabled monitors and start the tick loop. */
     start(options = {}) {
+        this.running = true;
         this.loadAll();
         this.logFn('INFO', `Monitor engine started (${this.monitors.length} monitor(s) on this device)`);
         if (!options.externalScheduler) {
@@ -138,8 +148,9 @@ export class MonitorEngine {
         this.loadAll();
         this.logFn('INFO', `Monitor engine reloaded (${this.monitors.length} monitor(s) on this device)`);
     }
-    /** Stop the tick loop. */
+    /** Stop the tick loop. No monitor dispatches after this until `start()`. */
     stop() {
+        this.running = false;
         if (this.timer) {
             clearInterval(this.timer);
             this.timer = null;
@@ -159,7 +170,11 @@ export class MonitorEngine {
     }
     /** Evaluate every due monitor once. Overlap-guarded so a slow cycle never stacks. */
     async tick() {
-        if (this.ticking)
+        // A stopped engine dispatches nothing (PHNX-3608): under the external
+        // scheduler the supervisor owns the timer, so a `stop()` (monitors service
+        // disabled) must be honoured HERE — otherwise the next supervised tick would
+        // still fire the last-loaded monitors even though the engine is stopped.
+        if (!this.running || this.ticking)
             return;
         this.ticking = true;
         try {
@@ -196,6 +211,16 @@ export class MonitorEngine {
             if (!observation) {
                 checkError = 'source produced no observation';
             }
+            else if (observation.failed) {
+                // The poll ran but did not OBSERVE (non-zero exit, or a transport/auth/
+                // rate-limit error in its output). Skip it entirely: no decideFire, no
+                // fire, watched-state untouched — so no empty→error→empty flap dispatches
+                // an agent on a dead premise. Record it as a failed check so a sustained
+                // streak escalates as a drought, the same health surface `--postcondition`
+                // uses on the action side (PHNX-3510).
+                checkError = `poll failed: ${observation.failureReason ?? 'observation failure'}`;
+                this.logFn('WARN', `monitor '${monitor.name}' poll failed (${observation.failureReason ?? 'observation failure'}) — not treated as a value change`);
+            }
             else {
                 const decision = decideFire(monitor, observation);
                 if (decision.fire && decision.event) {

package/dist/lib/monitors/sources/command.js

@@ -6,6 +6,7 @@
  * here. No agent, no sandbox: a plain `/bin/sh -c` (or `cmd /c` on Windows).
  */
 import { execFile } from 'child_process';
+import { classifyPollFailure } from './failure.js';
 const DEFAULT_TIMEOUT_MS = 60_000;
 /** Run the source command and return its combined stdout as the observation. */
 export function evaluate(source) {
@@ -22,10 +23,19 @@ export function evaluate(source) {
                 : err
                     ? 1
                     : 0;
-            // A non-zero exit is still a real observation (the diff might be exactly
-            // "command started failing"); surface stderr when stdout is empty.
+            // Surface stderr when stdout is empty.
             const raw = (stdout && stdout.length > 0 ? stdout : stderr ?? '').replace(/\s+$/, '');
-            resolve({ raw, meta: { exitCode } });
+            // A poll that failed to OBSERVE — non-zero exit, or a transport/auth/
+            // rate-limit error shape in its output (which a piped `gh … | jq`
+            // swallows the exit code of) — is not a new value. Flag it so the engine
+            // skips it instead of reading empty→error→empty as two value changes and
+            // dispatching an agent on a dead premise (PHNX-3510).
+            const failureReason = classifyPollFailure({ exitCode, text: raw });
+            resolve({
+                raw,
+                meta: { exitCode },
+                ...(failureReason ? { failed: true, failureReason } : {}),
+            });
         });
     });
 }

package/dist/lib/monitors/sources/failure.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Poll-failure classifier (PHNX-3510).
+ *
+ * A poll that FAILS to observe — the command exited non-zero, or its output
+ * carries a transport/auth/rate-limit error shape — is an OBSERVATION FAILURE,
+ * not a new value. Reading it as a value is the defect this closes: a
+ * `gh pr list … | jq` monitor whose gh half intermittently prints
+ * `GraphQL: API rate limit already exceeded …` flapped empty→error→empty, and an
+ * `[on-change]` monitor read that as two value changes and dispatched a full
+ * agent run on a premise that was false.
+ *
+ * The exit code alone is not enough: when gh is piped into jq the shell's exit
+ * status is jq's (0 on empty input), so the rate-limit text can ride an exit-0
+ * observation. The text patterns catch exactly that case. They stay tightly
+ * scoped to unambiguous failure shapes so a legitimate observation whose content
+ * merely mentions "timeout" is never misread as a failure.
+ */
+/** The failure reason matched in a poll's output text, or null when it looks clean. */
+export declare function matchFailureText(text: string): string | null;
+/**
+ * Classify one poll snapshot. Returns a short failure reason when the snapshot is
+ * an observation failure (non-zero exit, or a failure-shaped output), else null —
+ * in which case the snapshot is a genuine value the condition may diff.
+ *
+ * A failure-shaped OUTPUT is checked even on exit 0, because a piped command
+ * (`gh … | jq`) swallows the failing half's exit code. A non-zero exit is a
+ * failure regardless of output shape.
+ */
+export declare function classifyPollFailure(input: {
+    exitCode?: number;
+    text: string;
+}): string | null;

package/dist/lib/monitors/sources/failure.js

@@ -0,0 +1,52 @@
+/**
+ * Poll-failure classifier (PHNX-3510).
+ *
+ * A poll that FAILS to observe — the command exited non-zero, or its output
+ * carries a transport/auth/rate-limit error shape — is an OBSERVATION FAILURE,
+ * not a new value. Reading it as a value is the defect this closes: a
+ * `gh pr list … | jq` monitor whose gh half intermittently prints
+ * `GraphQL: API rate limit already exceeded …` flapped empty→error→empty, and an
+ * `[on-change]` monitor read that as two value changes and dispatched a full
+ * agent run on a premise that was false.
+ *
+ * The exit code alone is not enough: when gh is piped into jq the shell's exit
+ * status is jq's (0 on empty input), so the rate-limit text can ride an exit-0
+ * observation. The text patterns catch exactly that case. They stay tightly
+ * scoped to unambiguous failure shapes so a legitimate observation whose content
+ * merely mentions "timeout" is never misread as a failure.
+ */
+const FAILURE_TEXT_PATTERNS = [
+    { re: /\bAPI rate limit (?:already )?exceeded\b/i, reason: 'API rate limit exceeded' },
+    { re: /\bsecondary rate limit\b/i, reason: 'secondary rate limit' },
+    { re: /^\s*GraphQL:\s/im, reason: 'GraphQL error' },
+    { re: /\bbad credentials\b/i, reason: 'bad credentials' },
+    { re: /\b(?:401 Unauthorized|403 Forbidden)\b/i, reason: 'auth error' },
+    { re: /\bcould not resolve host\b/i, reason: 'transport error (DNS)' },
+    { re: /\bconnection (?:refused|reset|timed out)\b/i, reason: 'connection error' },
+    { re: /\bnetwork is unreachable\b/i, reason: 'network unreachable' },
+];
+/** The failure reason matched in a poll's output text, or null when it looks clean. */
+export function matchFailureText(text) {
+    for (const { re, reason } of FAILURE_TEXT_PATTERNS) {
+        if (re.test(text))
+            return reason;
+    }
+    return null;
+}
+/**
+ * Classify one poll snapshot. Returns a short failure reason when the snapshot is
+ * an observation failure (non-zero exit, or a failure-shaped output), else null —
+ * in which case the snapshot is a genuine value the condition may diff.
+ *
+ * A failure-shaped OUTPUT is checked even on exit 0, because a piped command
+ * (`gh … | jq`) swallows the failing half's exit code. A non-zero exit is a
+ * failure regardless of output shape.
+ */
+export function classifyPollFailure(input) {
+    const textReason = matchFailureText(input.text);
+    const badExit = typeof input.exitCode === 'number' && input.exitCode !== 0;
+    if (badExit) {
+        return textReason ? `${textReason} (exit ${input.exitCode})` : `command exited ${input.exitCode}`;
+    }
+    return textReason;
+}

package/dist/lib/monitors/sources/types.d.ts

@@ -11,6 +11,15 @@ import type { MonitorSource } from '../config.js';
 export interface Observation {
     raw: string;
     meta?: Record<string, unknown>;
+    /**
+     * The source flagged this snapshot as an OBSERVATION FAILURE (a poll that
+     * exited non-zero or emitted a transport/auth/rate-limit error), not a value.
+     * The engine skips it: no fire, watched-state untouched, counted as a failed
+     * check for drought health (PHNX-3510).
+     */
+    failed?: boolean;
+    /** Short human reason for `failed`, surfaced in drought health and `test`. */
+    failureReason?: string;
 }
 /** Poll-model evaluator: return one observation, or null when none is available. */
 export type SourceEvaluator = (source: MonitorSource) => Promise<Observation | null>;

package/dist/lib/owner-message.d.ts

@@ -0,0 +1,12 @@
+export interface OwnerMessageOptions {
+    /** Scannable subject line, when the caller has one (feed post does; notify does not). */
+    title?: string;
+    /** Explicit session id (`--session`); otherwise resolved from the run environment. */
+    sessionId?: string;
+}
+/**
+ * Shape a raw owner-send body into the composed broadcast message. Pure except
+ * for the identity/index reads that {@link resolvePostIdentity} /
+ * {@link getSessionById} already perform for feed posts.
+ */
+export declare function composeOwnerMessage(rawText: string, opts?: OwnerMessageOptions): string;

package/dist/lib/owner-message.js

@@ -0,0 +1,44 @@
+/**
+ * Compose an owner-bound phone ping through the SAME shaper `agents feed post`
+ * uses, so `agents notify` / `agents send --to owner` stop shipping a raw body
+ * dump (PHNX-3698).
+ *
+ * Before this, an owner send delivered the body verbatim: a long wall of prose,
+ * a `TEAM-N` key iMessage renders as dead text, and no way back to the session.
+ * Routing the body through {@link composeBroadcastMessage} makes an owner ping
+ * identical to an important feed post of the same event — short-shaped body,
+ * every ticket key linkified to its Linear URL, and the current session's
+ * `…/console/sessions/<id>` page as a tappable crumb.
+ *
+ * The session/agent/host are resolved the same way a feed post resolves them
+ * ({@link resolvePostIdentity} — the pid-registry / env walk), so a `notify`
+ * run inside an agent session inherits that session with no flag. Outside a
+ * session (a human at a shell) identity is undefined: the ping still gets
+ * short-shaping and ticket linkification, just no session crumb.
+ */
+import { composeBroadcastMessage } from './feed-broadcast.js';
+import { resolvePostIdentity } from './feed-post.js';
+import { getSessionById, resolveFullSessionId } from './session/db.js';
+import { linearIssueUrl } from './session/linear.js';
+/**
+ * Shape a raw owner-send body into the composed broadcast message. Pure except
+ * for the identity/index reads that {@link resolvePostIdentity} /
+ * {@link getSessionById} already perform for feed posts.
+ */
+export function composeOwnerMessage(rawText, opts = {}) {
+    const identity = resolvePostIdentity({ sessionId: opts.sessionId });
+    // A footer crumb that would 404 (an 8-char short id) is upgraded to the full
+    // indexed id so the console URL resolves; a full/native id passes through.
+    const session = resolveFullSessionId(identity?.sessionId);
+    const ticket = session ? getSessionById(session)?.ticketId : undefined;
+    const ctx = {
+        ...(opts.title?.trim() ? { title: opts.title.trim() } : {}),
+        text: rawText,
+        level: 'important',
+        ...(ticket ? { ticket, ticketUrl: linearIssueUrl(ticket) } : {}),
+        ...(identity?.agent ? { agent: identity.agent } : {}),
+        ...(identity?.host ? { host: identity.host } : {}),
+        ...(session ? { session } : {}),
+    };
+    return composeBroadcastMessage(ctx);
+}

package/dist/lib/refresh-coordinator.js

@@ -3,6 +3,7 @@ import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import lockfile from 'proper-lockfile';
 import { getCacheDir } from './state.js';
+import { logAndContinueOnLockCompromised } from './lock-compromise.js';
 const REFRESH_LOCK_STALE_MS = 2 * 60_000;
 let refreshLockRootOverride = null;
 export function setRefreshLockRootForTest(root) {
@@ -39,6 +40,7 @@ export async function withRefreshLease(options) {
         stale: REFRESH_LOCK_STALE_MS,
         update: REFRESH_LOCK_STALE_MS / 4,
         retries: { retries: 240, minTimeout: 25, maxTimeout: 500, factor: 1.2 },
+        onCompromised: logAndContinueOnLockCompromised('refresh lease'),
     });
     try {
         const completed = options.readCompleted();

package/dist/lib/run-trace-sync.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The policy gate, pure and unit-testable. `disabled` is the resolved
+ * `--no-trace-sync` (commander maps it to `traceSync === false`).
+ */
+export declare function shouldAutoSyncTraces(disabled: boolean): boolean;
+/**
+ * Arm a fire-and-forget `agents traces sync` for when this process exits.
+ * No-op unless {@link shouldAutoSyncTraces} passes. Best-effort by
+ * construction: a missing binary or a stalled child never affects the run.
+ * The spawn happens in the exit handler because the upload is async work Node
+ * cannot run after `exit` — a watchdog here could never fire.
+ */
+export declare function armRunFinishTraceSync(opts?: {
+    disabled?: boolean;
+}): void;
+/**
+ * Fire a fire-and-forget `agents traces sync` NOW (not on exit). An important
+ * owner-bound ping (`feed post --level important`, `agents notify`,
+ * `send --to owner`) links the caller's `…/console/sessions/<id>` page, and that
+ * page only exists once the session's shard has been uploaded — trace sync fires
+ * on run exit (PHNX-3628), not when a mid-run ping is posted. This closes that
+ * gap so the tapped link resolves instead of 404ing. No-op unless
+ * {@link shouldAutoSyncTraces} passes (signed in + already opted into the store);
+ * the incremental watermark keeps the push to essentially just this session.
+ */
+export declare function fireTraceSyncInBackground(opts?: {
+    disabled?: boolean;
+}): void;

package/dist/lib/run-trace-sync.js

@@ -0,0 +1,99 @@
+/**
+ * Auto-sync this device's just-finished session trace when a local, headless
+ * `agents run` exits (PHNX-3628).
+ *
+ * Why exit-armed + spawn, exactly like `run-notify`: the sync reads this
+ * device's `sessions.db` and PUTs redacted shards over the network — async work
+ * that CANNOT run inside a `process.on('exit')` handler (Node runs no more
+ * microtasks after exit). So, mirroring `notifyDesktop`, on exit we SPAWN a
+ * detached `agents traces sync` and unref it; it finishes after the parent is
+ * gone, and the run itself returns immediately instead of waiting on the PUTs.
+ *
+ * The upload is incremental by construction (`syncTraces` de-dups by the
+ * `traces-sync.json` mtime watermark), so the spawned sync pushes essentially
+ * just the session that finished, not the whole history.
+ *
+ * Default policy: fire ONLY when the user has ALREADY opted into the traces
+ * store — i.e. they are signed in AND have run `agents traces sync` at least
+ * once (`hasSyncedBefore`). A user who never synced is never touched. Opt out
+ * of a given run with `--no-trace-sync` or `AGENTS_NO_TRACE_SYNC=1`.
+ *
+ * Local runs only: a run placed on another machine (`--device`/`--on`/
+ * `--computer`/`--where device:`, `--lease`, `--box`, or `--cloud`) has its
+ * trajectory on the REMOTE box, not this device's `sessions.db`, so arming here
+ * would upload nothing useful — the remote box runs its own exit sync. The
+ * caller gates every remote-placement signal out before arming (it reuses the
+ * file's own `hostTargetGiven` predicate plus `--lease`/`--box`; `--cloud`
+ * returns earlier).
+ */
+import { spawn } from 'child_process';
+import { getCliLaunch } from './cli-entry.js';
+import { readSession } from './identity/client.js';
+import { hasSyncedBefore } from './traces/sync.js';
+/**
+ * The policy gate, pure and unit-testable. `disabled` is the resolved
+ * `--no-trace-sync` (commander maps it to `traceSync === false`).
+ */
+export function shouldAutoSyncTraces(disabled) {
+    if (disabled)
+        return false;
+    if (process.env.AGENTS_NO_TRACE_SYNC === '1')
+        return false;
+    if (!readSession())
+        return false; // not signed in → nothing to authenticate an upload
+    if (!hasSyncedBefore())
+        return false; // never opted into the traces store
+    return true;
+}
+/**
+ * Spawn a detached, unref'd `agents traces sync` and return immediately. The one
+ * place the fire-and-forget child is built, shared by the run-exit arm and the
+ * feed/notify important-post trigger.
+ *
+ * Re-invoke this CLI through getCliLaunch, NOT a hand-rolled
+ * [process.execPath, process.argv[1], …] — under the compiled standalone binary
+ * argv[1] is the bun virtual entry (/$bunfs/root/agents), which would become a
+ * bogus subcommand and silently no-op the whole feature (cli-entry.ts). The
+ * spawned `traces sync` is a fresh process with its own event loop, so its own
+ * per-request network timeouts (syncTraces) bound it.
+ */
+function spawnDetachedTraceSync() {
+    try {
+        const { command, args } = getCliLaunch(['traces', 'sync']);
+        const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+        // A child that never starts (ENOENT) emits an async 'error'; without a
+        // listener Node re-throws it as uncaught. Swallow — this is best-effort.
+        child.on('error', () => { });
+        child.unref();
+    }
+    catch {
+        // A synchronous spawn failure must never change the caller's outcome.
+    }
+}
+/**
+ * Arm a fire-and-forget `agents traces sync` for when this process exits.
+ * No-op unless {@link shouldAutoSyncTraces} passes. Best-effort by
+ * construction: a missing binary or a stalled child never affects the run.
+ * The spawn happens in the exit handler because the upload is async work Node
+ * cannot run after `exit` — a watchdog here could never fire.
+ */
+export function armRunFinishTraceSync(opts = {}) {
+    if (!shouldAutoSyncTraces(!!opts.disabled))
+        return;
+    process.on('exit', spawnDetachedTraceSync);
+}
+/**
+ * Fire a fire-and-forget `agents traces sync` NOW (not on exit). An important
+ * owner-bound ping (`feed post --level important`, `agents notify`,
+ * `send --to owner`) links the caller's `…/console/sessions/<id>` page, and that
+ * page only exists once the session's shard has been uploaded — trace sync fires
+ * on run exit (PHNX-3628), not when a mid-run ping is posted. This closes that
+ * gap so the tapped link resolves instead of 404ing. No-op unless
+ * {@link shouldAutoSyncTraces} passes (signed in + already opted into the store);
+ * the incremental watermark keeps the push to essentially just this session.
+ */
+export function fireTraceSyncInBackground(opts = {}) {
+    if (!shouldAutoSyncTraces(!!opts.disabled))
+        return;
+    spawnDetachedTraceSync();
+}

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

@@ -207,6 +207,10 @@ export declare function _resetFileStoreForTest(opts?: {
     passphraseDir?: string | null;
     passphrase?: string | null;
 }): void;
+/** Test-only: flush the in-memory metadata cache to disk now. Production flushes
+ *  once at process exit; a test needs the on-disk copy mid-run to simulate the
+ *  next `agents` process reading it. */
+export declare function _flushMetaCacheForTest(): void;
 /** Test-only: shorten the store-lock acquire timeout so a contended-lock assertion
  *  fails fast instead of waiting out the 30s production budget. */
 export declare function _setFileStoreLockTimeoutForTest(ms: number | null): void;