@phnx-labs/agents-cli 1.22.57 → 1.22.59

package/dist/lib/session/tool-calls.d.ts

@@ -10,12 +10,21 @@ export declare const TOOL_CHANGED_MAX_CALLS = 10000;
 export declare const TOOL_INDEX_LIMIT_ORDINAL: number;
 export declare const TOOL_TEXT_PROCESSING_MAX_BYTES: number;
 export declare const TOOL_SHELL_PARSE_MAX_BYTES: number;
-export declare const TOOL_INDEX_VERSION = 7;
+export declare const TOOL_INDEX_VERSION = 8;
 export type ToolCallOutcome = 'ok' | 'error' | 'unknown';
 export interface IndexedToolCall {
     ordinal: number;
     sourceCallId?: string;
     timestamp: string;
+    /**
+     * When the call's RESULT record arrived — the call's own end time, taken from
+     * the tool_result transcript record at `finish()` (PHNX-3437). `timestamp` is
+     * the start; `endTimestamp - timestamp` is the call's own blocking duration,
+     * which the traces insight engine attributes as a failed call's wasted time.
+     * Undefined for a call that never produced a result (still pending at scan end)
+     * and for rows produced by an older extractor.
+     */
+    endTimestamp?: string;
     tool: string;
     programs: string[];
     programOccurrences: ShellProgramOccurrence[];
@@ -81,6 +90,39 @@ export declare class ToolCallCollector {
     private removePending;
     private markChanged;
 }
+/** The prior scan's resume point for an append-only event stream. */
+export interface EventToolScanResumePoint {
+    /** ToolCallCollector snapshot after folding `eventCount` events. */
+    snapshot: ToolCallCollectorSnapshot;
+    /** How many events had been folded when the snapshot was taken. */
+    eventCount: number;
+}
+export interface EventToolScanResult {
+    /** The CHANGED calls — an append-safe upsert set, not the whole history. */
+    calls: IndexedToolCall[];
+    /** Serialized-ready snapshot to persist for the next incremental scan. */
+    snapshot: ToolCallCollectorSnapshot;
+    /** Events folded so far — the next scan's resume offset into `events`. */
+    eventCount: number;
+}
+/**
+ * Derive tool calls from a full-file harness's normalized events, optionally
+ * RESUMING from a prior scan of the same append-only stream.
+ *
+ * Without `prior` this is a full parse from event 0 (identical to the legacy
+ * {@link toolCallsFromEvents}). With `prior`, the collector is seeded from the
+ * prior snapshot and only events at or after `prior.eventCount` are folded — so
+ * an active session that grew by a few turns re-derives (and re-redacts) only
+ * those new tool calls instead of re-sanitizing its entire history on every
+ * daemon warm tick (PHNX-3411). The ordinals continue deterministically from the
+ * snapshot, so folding [0..k) then [k..n) yields the same index as folding
+ * [0..n) once, and the CHANGED set is safe to persist with `mode: 'append'`.
+ *
+ * The caller is responsible for only supplying `prior` when the stream is still
+ * an append of what was scanned before (same source, un-truncated,
+ * `prior.eventCount <= events.length`); anything else must full-scan.
+ */
+export declare function scanEventToolCalls(events: SessionEvent[], prior?: EventToolScanResumePoint): EventToolScanResult;
 /** Build indexed calls from the normalized parser contract used by full-file harnesses. */
 export declare function toolCallsFromEvents(events: SessionEvent[]): IndexedToolCall[];
 export declare function toolCallKey(sessionId: string, ordinal: number): string;

package/dist/lib/session/tool-calls.js

@@ -12,7 +12,10 @@ export const TOOL_CHANGED_MAX_CALLS = 10_000;
 export const TOOL_INDEX_LIMIT_ORDINAL = Number.MAX_SAFE_INTEGER;
 export const TOOL_TEXT_PROCESSING_MAX_BYTES = 64 * 1024;
 export const TOOL_SHELL_PARSE_MAX_BYTES = 64 * 1024;
-export const TOOL_INDEX_VERSION = 7;
+// Bumped to 8 for the per-call end timestamp (PHNX-3437): the extractor now
+// records when a call's result arrived, so a re-index re-derives it for rows
+// stored by an older extractor.
+export const TOOL_INDEX_VERSION = 8;
 const BASE64_BLOCK = /(?:[A-Za-z0-9+/]{256,}={0,2})/g;
 const SECRET_FIELD = /(?:token|secret|password|authorization|cookie|api[_-]?key|private[_-]?key)$/i;
 const KNOWN_SECRET_VALUES = knownSecretValuesFromEnv();
@@ -310,7 +313,7 @@ function buildCall(ordinal, timestamp, tool, args, command, sourceCallId) {
 }
 export function toolCallEvidenceBytes(call) {
     return Buffer.byteLength([
-        call.sourceCallId, call.timestamp, call.tool, call.input, call.errorCode,
+        call.sourceCallId, call.timestamp, call.endTimestamp, call.tool, call.input, call.errorCode,
         call.output, call.error, call.parseError, ...call.programs,
         ...call.programOccurrences.map((occurrence) => `${occurrence.role}:${occurrence.program}`),
     ].filter((value) => typeof value === 'string').join('\0'));
@@ -363,6 +366,9 @@ export class ToolCallCollector {
         const call = this.takePending(args.sourceCallId, tool);
         if (!call)
             return undefined;
+        if (typeof args.timestamp === 'string' && args.timestamp.length > 0) {
+            call.endTimestamp = sanitizeToolEvidenceText(args.timestamp, 128);
+        }
         const outcome = args.outcome === 'ok' || args.outcome === 'error' || args.outcome === 'unknown'
             ? args.outcome
             : undefined;
@@ -471,50 +477,74 @@ export class ToolCallCollector {
         return true;
     }
 }
+/** Fold one normalized event into a collector (the full-file harness contract). */
+function foldEventIntoCollector(collector, event) {
+    if (event.type === 'tool_use') {
+        collector.start({
+            timestamp: event.timestamp,
+            tool: event.tool || 'unknown',
+            input: event.args,
+            command: event.command,
+            sourceCallId: event.callId,
+        });
+    }
+    else if (event.type === 'tool_result') {
+        collector.finish({
+            timestamp: event.timestamp,
+            sourceCallId: event.callId,
+            tool: event.tool,
+            success: event.success,
+            outcome: event.outcome,
+            exitCode: event.exitCode,
+            statusCode: event.statusCode,
+            errorCode: event.errorCode,
+            output: event.output,
+        });
+    }
+    else if (event.type === 'error' && event.tool) {
+        const structuredError = event.outcome === 'error' || event.success === false;
+        const evidence = event.content || event.output || 'Tool execution failed';
+        collector.finish({
+            timestamp: event.timestamp,
+            sourceCallId: event.callId,
+            tool: event.tool,
+            success: structuredError ? false : undefined,
+            outcome: event.outcome,
+            exitCode: event.exitCode,
+            statusCode: event.statusCode,
+            errorCode: event.errorCode,
+            error: structuredError ? evidence : undefined,
+            output: structuredError ? undefined : evidence,
+        });
+    }
+}
+/**
+ * Derive tool calls from a full-file harness's normalized events, optionally
+ * RESUMING from a prior scan of the same append-only stream.
+ *
+ * Without `prior` this is a full parse from event 0 (identical to the legacy
+ * {@link toolCallsFromEvents}). With `prior`, the collector is seeded from the
+ * prior snapshot and only events at or after `prior.eventCount` are folded — so
+ * an active session that grew by a few turns re-derives (and re-redacts) only
+ * those new tool calls instead of re-sanitizing its entire history on every
+ * daemon warm tick (PHNX-3411). The ordinals continue deterministically from the
+ * snapshot, so folding [0..k) then [k..n) yields the same index as folding
+ * [0..n) once, and the CHANGED set is safe to persist with `mode: 'append'`.
+ *
+ * The caller is responsible for only supplying `prior` when the stream is still
+ * an append of what was scanned before (same source, un-truncated,
+ * `prior.eventCount <= events.length`); anything else must full-scan.
+ */
+export function scanEventToolCalls(events, prior) {
+    const startIndex = prior ? Math.min(prior.eventCount, events.length) : 0;
+    const collector = new ToolCallCollector(prior?.snapshot);
+    for (let i = startIndex; i < events.length; i++)
+        foldEventIntoCollector(collector, events[i]);
+    return { calls: collector.drainChanged(), snapshot: collector.snapshot(), eventCount: events.length };
+}
 /** Build indexed calls from the normalized parser contract used by full-file harnesses. */
 export function toolCallsFromEvents(events) {
-    const collector = new ToolCallCollector();
-    for (const event of events) {
-        if (event.type === 'tool_use') {
-            collector.start({
-                timestamp: event.timestamp,
-                tool: event.tool || 'unknown',
-                input: event.args,
-                command: event.command,
-                sourceCallId: event.callId,
-            });
-        }
-        else if (event.type === 'tool_result') {
-            collector.finish({
-                timestamp: event.timestamp,
-                sourceCallId: event.callId,
-                tool: event.tool,
-                success: event.success,
-                outcome: event.outcome,
-                exitCode: event.exitCode,
-                statusCode: event.statusCode,
-                errorCode: event.errorCode,
-                output: event.output,
-            });
-        }
-        else if (event.type === 'error' && event.tool) {
-            const structuredError = event.outcome === 'error' || event.success === false;
-            const evidence = event.content || event.output || 'Tool execution failed';
-            collector.finish({
-                timestamp: event.timestamp,
-                sourceCallId: event.callId,
-                tool: event.tool,
-                success: structuredError ? false : undefined,
-                outcome: event.outcome,
-                exitCode: event.exitCode,
-                statusCode: event.statusCode,
-                errorCode: event.errorCode,
-                error: structuredError ? evidence : undefined,
-                output: structuredError ? undefined : evidence,
-            });
-        }
-    }
-    return collector.drainChanged();
+    return scanEventToolCalls(events).calls;
 }
 export function toolCallKey(sessionId, ordinal) {
     return createHash('sha256').update(`${sessionId}\0${ordinal}`).digest('hex').slice(0, 20);

package/dist/lib/session/tool-store.d.ts

@@ -1,5 +1,5 @@
 import type Database from '../sqlite.js';
-import { type IndexedToolCall } from './tool-calls.js';
+import { type IndexedToolCall, type EventToolScanResumePoint } from './tool-calls.js';
 import type { SessionMeta } from './types.js';
 export declare function canonicalToolLedgerPath(filePath: string): string;
 /** Resolve the transcript that actually carries tool events for split-file harnesses. */
@@ -12,7 +12,14 @@ export declare function purgeMissingToolCallsInDirectory(db: Database.Database,
 export interface ToolScanResumePoint {
     /** Serialized ToolCallCollector snapshot at `parsedOffset`. */
     parserState: string;
-    /** Byte offset just past the last complete record consumed. */
+    /**
+     * Where a later scan may resume. For the streaming (claude/codex) path this is
+     * a BYTE offset just past the last complete record consumed. For the full-file
+     * harness path (`planEventToolResume`) it is instead the COUNT of normalized
+     * events already folded — the two never share a session (a session is one
+     * agent, and the streaming path is claude/codex only), so the column carries
+     * whichever meaning that agent's resumer wrote.
+     */
     parsedOffset: number;
 }
 export interface PersistToolCallsOptions {
@@ -37,3 +44,27 @@ export declare function persistToolCalls(db: Database.Database, session: Session
     fileMtimeMs: number;
     fileSize: number;
 }, options?: PersistToolCallsOptions): void;
+/**
+ * Decide whether a changed full-file-harness session can RESUME its tool index
+ * from the last scan instead of re-deriving every call (PHNX-3411).
+ *
+ * The warm-tick indexer re-derives tool calls for a changed session on every
+ * tick, and for an ACTIVE large session that means re-sanitizing tens of
+ * thousands of calls each time — the synchronous work that wedged the daemon
+ * event loop. Streaming harnesses (claude/codex) already resume from a byte
+ * offset; every other harness re-parses the whole file, so this brings them the
+ * same benefit at the EVENT level: the ledger stores how many events were folded
+ * (`parsed_offset`) plus the collector snapshot (`parser_state`), and a later
+ * scan folds only the newly appended events.
+ *
+ * Returns the prior resume point when it is safe to append, or `null` (full
+ * re-scan) whenever the stored prefix may no longer describe the current file:
+ * a different extractor, no recorded resume point, a source the ledger row does
+ * not describe, a transcript that shrank below what was already parsed (a
+ * truncation/rewrite, not an append), more events already folded than the file
+ * now yields, or a snapshot that does not read back.
+ */
+export declare function planEventToolResume(db: Database.Database, sessionId: string, sourcePath: string, stamp: {
+    fileMtimeMs: number;
+    fileSize: number;
+}, currentEventCount: number): EventToolScanResumePoint | null;

package/dist/lib/session/tool-store.js

@@ -75,13 +75,14 @@ export function persistToolCalls(db, session, calls, sourceStamp, options = {})
     const sourcePath = toolEvidenceSourcePath(session.filePath, session.agent);
     const insertCall = db.prepare(`
     INSERT INTO tool_calls (
-      call_key, session_id, ordinal, source_call_id, timestamp, tool, input,
+      call_key, session_id, ordinal, source_call_id, timestamp, end_timestamp, tool, input,
       outcome, exit_code, status_code, error_code, output, error, parse_error
       , evidence_bytes
-    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     ON CONFLICT(session_id, ordinal) DO UPDATE SET
       source_call_id = excluded.source_call_id,
       timestamp = excluded.timestamp,
+      end_timestamp = excluded.end_timestamp,
       tool = excluded.tool,
       input = excluded.input,
       outcome = excluded.outcome,
@@ -197,7 +198,7 @@ export function persistToolCalls(db, session, calls, sourceStamp, options = {})
         }
         for (const call of accepted) {
             const key = toolCallKey(session.id, call.ordinal);
-            insertCall.run(key, session.id, call.ordinal, call.sourceCallId ?? null, call.timestamp, call.tool, call.input, call.outcome, call.exitCode ?? null, call.statusCode ?? null, call.errorCode ?? null, call.output ?? null, call.error ?? null, call.parseError ?? null, toolCallEvidenceBytes(call));
+            insertCall.run(key, session.id, call.ordinal, call.sourceCallId ?? null, call.timestamp, call.endTimestamp ?? null, call.tool, call.input, call.outcome, call.exitCode ?? null, call.statusCode ?? null, call.errorCode ?? null, call.output ?? null, call.error ?? null, call.parseError ?? null, toolCallEvidenceBytes(call));
             // The upsert above preserves the rowid of a call it updated, so this is
             // the same rowid the existing text row (if any) was written under.
             const { rowid } = callRowid.get(key);
@@ -215,3 +216,55 @@ export function persistToolCalls(db, session, calls, sourceStamp, options = {})
     });
     txn();
 }
+/**
+ * Decide whether a changed full-file-harness session can RESUME its tool index
+ * from the last scan instead of re-deriving every call (PHNX-3411).
+ *
+ * The warm-tick indexer re-derives tool calls for a changed session on every
+ * tick, and for an ACTIVE large session that means re-sanitizing tens of
+ * thousands of calls each time — the synchronous work that wedged the daemon
+ * event loop. Streaming harnesses (claude/codex) already resume from a byte
+ * offset; every other harness re-parses the whole file, so this brings them the
+ * same benefit at the EVENT level: the ledger stores how many events were folded
+ * (`parsed_offset`) plus the collector snapshot (`parser_state`), and a later
+ * scan folds only the newly appended events.
+ *
+ * Returns the prior resume point when it is safe to append, or `null` (full
+ * re-scan) whenever the stored prefix may no longer describe the current file:
+ * a different extractor, no recorded resume point, a source the ledger row does
+ * not describe, a transcript that shrank below what was already parsed (a
+ * truncation/rewrite, not an append), more events already folded than the file
+ * now yields, or a snapshot that does not read back.
+ */
+export function planEventToolResume(db, sessionId, sourcePath, stamp, currentEventCount) {
+    const row = db.prepare(`
+    SELECT file_path, file_size, extractor_version, parsed_offset, parser_state
+    FROM tool_scan_ledger WHERE session_id = ?
+  `).get(sessionId);
+    if (!row)
+        return null;
+    if (row.extractor_version !== TOOL_INDEX_VERSION)
+        return null;
+    if (row.parsed_offset === null || !Number.isSafeInteger(row.parsed_offset) || row.parsed_offset < 0)
+        return null;
+    if (row.file_path !== canonicalToolLedgerPath(sourcePath))
+        return null;
+    if (stamp.fileSize < row.file_size)
+        return null;
+    // The file grew but reports fewer events than were already folded — the prefix
+    // was rewritten, not appended to. Re-scan from scratch.
+    if (row.parsed_offset > currentEventCount)
+        return null;
+    if (row.parser_state === null)
+        return null;
+    let snapshot;
+    try {
+        snapshot = JSON.parse(row.parser_state);
+    }
+    catch {
+        return null;
+    }
+    if (snapshot?.v !== 1 || !Number.isSafeInteger(snapshot.nextOrdinal))
+        return null;
+    return { snapshot, eventCount: row.parsed_offset };
+}

package/dist/lib/smart-launch.d.ts

@@ -95,6 +95,12 @@ export declare function resolveDeviceAuto(agent?: string, opts?: {
     /** Route only to devices with a row the interactive account picker can launch. */
     accountPicker?: boolean;
     probe?: (pool: string[], agent?: AgentType) => Promise<Map<string, DevicePlacementSignal>>;
+    /**
+     * Preferred hosts (`auto-launch.preferred`) that get the ranking boost.
+     * Defaults to the stored fleet block resolved over the candidate pool;
+     * injectable so a test pins it without touching disk.
+     */
+    preferred?: ReadonlySet<string>;
 }): Promise<DeviceAutoPlan>;
 /**
  * Resolve host for `--device auto`. Does NOT pick harness or accounts.

package/dist/lib/smart-launch.js

@@ -8,7 +8,7 @@
 import { queryAffinityRollup } from './session/db.js';
 import { localMachineId } from './session/origin-machine.js';
 import { loadDevicesSync } from './devices/registry.js';
-import { describeAutoPool, filterAutoPool, isAutoPoolMember } from './devices/pool.js';
+import { autoLaunchPreferredSet, describeAutoPool, filterAutoPool, isAutoPoolMember } from './devices/pool.js';
 import { normalizeHost } from './machine-id.js';
 import { probePoolSignals } from './teams/placement-probe.js';
 import { pickBestDevice } from './teams/scheduler.js';
@@ -153,7 +153,10 @@ export async function resolveDeviceAuto(agent, opts = {}) {
     if (eligiblePool.length === 0) {
         throw new Error(formatNoHealthyDeviceError(pool, signals, agent));
     }
-    const picked = pickBestDevice(eligiblePool, [], { signals, agentLabel: agent });
+    // `agents devices prefer <name>` boosts a device in the ranking — resolved
+    // over the same pool so a fleet default reaches a doc-less box.
+    const preferred = opts.preferred ?? autoLaunchPreferredSet(pool, { roster: pool });
+    const picked = pickBestDevice(eligiblePool, [], { signals, agentLabel: agent, preferred });
     return {
         host: picked === local ? null : picked,
         pickedDeviceKey: picked,

package/dist/lib/staleness/writers/plugins.js

@@ -8,8 +8,11 @@ function buildPluginsWriter(agent) {
         write({ version, versionHome, selection }) {
             const all = discoverPlugins();
             const map = new Map(all.map(p => [p.name, p]));
-            // Clean orphan plugin-skills from plugins that no longer exist.
-            cleanOrphanedPluginSkills(agent, versionHome, new Set(all.map(p => p.name)));
+            // Clean orphan plugin-skills from plugins that no longer exist. Pass the
+            // discovered plugins (not just names) so a stale install under one
+            // marketplace is trashed even when another marketplace still ships that
+            // name — the PHNX-2618 shadow `code` plugin.
+            cleanOrphanedPluginSkills(agent, versionHome, all);
             const synced = [];
             for (const name of selection) {
                 const plugin = map.get(name);

package/dist/lib/staleness/writers/sources.d.ts

@@ -7,6 +7,11 @@ export type EnabledExtra = {
 export declare function trustedSourceBases(): {
     dir: string;
 }[];
+/** Every `plugins/<plugin>/skills` dir across trusted source bases, filtered to an optional plugin/agent scope. */
+export declare function pluginSkillDirs(options?: {
+    agent?: AgentId;
+    plugins?: Set<string>;
+}): string[];
 /** Find the trusted source for a command markdown by name. */
 export declare function resolveCommandSource(name: string): string | null;
 /** Find the trusted source directory for a skill by name. */

package/dist/lib/staleness/writers/sources.js

@@ -54,7 +54,8 @@ function pluginSupportsAgent(manifest, agent) {
         return true;
     return !manifest.agents || manifest.agents.length === 0 || manifest.agents.includes(agent);
 }
-function pluginSkillDirs(options = {}) {
+/** Every `plugins/<plugin>/skills` dir across trusted source bases, filtered to an optional plugin/agent scope. */
+export function pluginSkillDirs(options = {}) {
     const dirs = [];
     for (const base of trustedSourceBases()) {
         const pluginsDir = path.join(base.dir, 'plugins');

package/dist/lib/staleness/writers/subagents.js

@@ -25,10 +25,16 @@ function buildSubagentsWriter(agent) {
             const dir = target.dir(versionHome);
             const synced = [];
             const paths = [];
+            const errors = [];
             for (const name of selection) {
                 const sub = map.get(name);
-                if (!sub)
+                if (!sub) {
+                    // Requested but not discoverable as an installed central subagent —
+                    // e.g. its AGENT.md failed to parse. Say so instead of silently
+                    // dropping it, which read as an unactionable doctor "hold" (PHNX-3187).
+                    errors.push(`subagent '${name}': no parseable AGENT.md in ~/.agents/subagents`);
                     continue;
+                }
                 try {
                     target.write(dir, sub);
                     synced.push(sub.name);
@@ -39,9 +45,13 @@ function buildSubagentsWriter(agent) {
                             paths.push(entry.path);
                     }
                 }
-                catch { /* per-item sync failure: skip */ }
+                catch (e) {
+                    // A genuine fs/transform failure must surface with its reason, not
+                    // vanish behind a bare `catch` (RUSH-2677 / PHNX-3187).
+                    errors.push(`subagent '${sub.name}': ${e.message}`);
+                }
             }
-            return { synced, paths };
+            return errors.length > 0 ? { synced, paths, errors } : { synced, paths };
         },
     };
 }

package/dist/lib/state.d.ts

@@ -198,10 +198,13 @@ export declare function getMonitorsDir(): string;
  * Path to built-in monitor definitions shipped in the system repo
  * (`~/.agents/.system/monitors/`). Unioned under the user monitors dir by
  * listMonitors()/readMonitor(): a monitor shipped here is available on every
- * install, and a user monitor of the same name overrides it. A built-in with no
- * `enabled:` field is opt-in — it stays disabled until the user enables it,
- * which materializes a user copy (writes never touch this pull-only mirror). The
- * directory need not exist.
+ * install, and a user monitor of the same name overrides it. A built-in is
+ * enabled by default like every other system-layer resource — it runs on every
+ * install unless the user shadows it with `enabled: false` (via `agents monitors
+ * pause`, which materializes a user copy; writes never touch this pull-only
+ * mirror). A shared-input built-in still carries its own `device:` owner pin in
+ * the shipped YAML so exactly one box fires it (SING-9). The directory need not
+ * exist.
  */
 export declare function getSystemMonitorsDir(): string;
 /** Path to the durable per-monitor state-diff store + fire history

package/dist/lib/state.js

@@ -491,10 +491,13 @@ export function getMonitorsDir() { return process.env.AGENTS_MONITORS_DIR ?? MON
  * Path to built-in monitor definitions shipped in the system repo
  * (`~/.agents/.system/monitors/`). Unioned under the user monitors dir by
  * listMonitors()/readMonitor(): a monitor shipped here is available on every
- * install, and a user monitor of the same name overrides it. A built-in with no
- * `enabled:` field is opt-in — it stays disabled until the user enables it,
- * which materializes a user copy (writes never touch this pull-only mirror). The
- * directory need not exist.
+ * install, and a user monitor of the same name overrides it. A built-in is
+ * enabled by default like every other system-layer resource — it runs on every
+ * install unless the user shadows it with `enabled: false` (via `agents monitors
+ * pause`, which materializes a user copy; writes never touch this pull-only
+ * mirror). A shared-input built-in still carries its own `device:` owner pin in
+ * the shipped YAML so exactly one box fires it (SING-9). The directory need not
+ * exist.
  */
 export function getSystemMonitorsDir() { return process.env.AGENTS_SYSTEM_MONITORS_DIR ?? SYSTEM_MONITORS_DIR; }
 /** Path to the durable per-monitor state-diff store + fire history

package/dist/lib/subagents.js

@@ -23,7 +23,12 @@ export function parseSubagentFrontmatter(filePath) {
     }
     try {
         const content = fs.readFileSync(filePath, 'utf-8');
-        const lines = content.split('\n');
+        // Split on CRLF or LF: git checks text files out with CRLF on Windows
+        // (core.autocrlf), so a plain split('\n') leaves a trailing '\r' on every
+        // line and the frontmatter fence `'---\r' !== '---'` never matches —
+        // silently dropping the subagent from discovery so it can never be
+        // installed or reconciled (PHNX-3187).
+        const lines = content.split(/\r?\n/);
         // Check for YAML frontmatter
         if (lines[0] === '---') {
             const endIndex = lines.slice(1).findIndex((l) => l === '---');
@@ -52,7 +57,8 @@ export function getSubagentBody(filePath) {
         return '';
     }
     const content = fs.readFileSync(filePath, 'utf-8');
-    const lines = content.split('\n');
+    // CRLF-robust for the same reason as parseSubagentFrontmatter (PHNX-3187).
+    const lines = content.split(/\r?\n/);
     // Skip YAML frontmatter
     if (lines[0] === '---') {
         const endIndex = lines.slice(1).findIndex((l) => l === '---');

package/dist/lib/sync-status.d.ts

@@ -93,6 +93,28 @@ export interface UnifiedSyncStatus {
         agentsNeedingSync: number;
     };
 }
+/**
+ * Residual drift for a single (agent, version) after a reconcile — the drifted
+ * and missing rows that a sync claimed to fix but did not. `orphan` rows are
+ * deliberately excluded: sync never removes them (that is `agents prune`'s job),
+ * so they are not "unfinished sync". Empty `drifted`+`missing` ⇒ converged.
+ */
+export interface ResidualDrift {
+    agent: AgentId;
+    version: string;
+    rows: ResourceStatusRow[];
+}
+/**
+ * Re-check that a version's home now matches its resolved sources after a
+ * reconcile. This is the post-write verification the `agents sync` success line
+ * depends on (PHNX-3186): the exit line must not read "reconciled" while drift
+ * it was asked to fix stays put. Resolves against non-project layers only
+ * (`excludeProject: true`), mirroring what the sync writer targets. Returns null
+ * when the version converged (no drifted/missing), else the residual rows.
+ */
+export declare function verifyVersionConverged(agent: AgentId, version: string, cwd?: string): ResidualDrift | null;
+/** One-line-per-resource description of residual drift, for the sync exit line. */
+export declare function formatResidualDrift(residual: ResidualDrift[]): string[];
 export interface SyncStatusOptions {
     cwd?: string;
     /** Restrict to specific agent ids; undefined = every supported agent. */

package/dist/lib/sync-status.js

@@ -27,6 +27,33 @@ import { getSystemAgentsDir, getUserAgentsDir } from './state.js';
 import * as fs from 'fs';
 import { isGitRepo, readOriginUrl } from './git.js';
 import { detectConfigDrift } from './config-drift.js';
+/**
+ * Re-check that a version's home now matches its resolved sources after a
+ * reconcile. This is the post-write verification the `agents sync` success line
+ * depends on (PHNX-3186): the exit line must not read "reconciled" while drift
+ * it was asked to fix stays put. Resolves against non-project layers only
+ * (`excludeProject: true`), mirroring what the sync writer targets. Returns null
+ * when the version converged (no drifted/missing), else the residual rows.
+ */
+export function verifyVersionConverged(agent, version, cwd = process.cwd()) {
+    const report = diffVersionResources(agent, version, { cwd, excludeProject: true });
+    const rows = rowsFromReport(agent, version, report)
+        .filter((r) => r.status === 'drifted' || r.status === 'missing');
+    if (rows.length === 0)
+        return null;
+    return { agent, version, rows };
+}
+/** One-line-per-resource description of residual drift, for the sync exit line. */
+export function formatResidualDrift(residual) {
+    const lines = [];
+    for (const r of residual) {
+        for (const row of r.rows) {
+            const detail = row.detail ? ` (${row.detail})` : '';
+            lines.push(`${r.agent}@${r.version}: ${row.status} ${row.kind} '${row.name}'${detail}`);
+        }
+    }
+    return lines;
+}
 const STATUS_MAP = {
     ok: 'synced',
     diff: 'drifted',

package/dist/lib/sync-umbrella.d.ts

@@ -64,6 +64,15 @@ export interface UmbrellaResult {
      * Empty when nothing was declined — never conflated with "nothing to do".
      */
     declined: string[];
+    /**
+     * The (agent, version) pairs the reconcile stage actually wrote into — the set
+     * the caller re-verifies for residual drift so the `✓ sync: reconciled` line is
+     * never printed while drift it was asked to fix stays put (PHNX-3186).
+     */
+    reconciledVersions: Array<{
+        agent: string;
+        version: string;
+    }>;
 }
 export interface RunUmbrellaArgs {
     flags: UmbrellaFlags;

package/dist/lib/sync-umbrella.js

@@ -15,7 +15,7 @@
  *               arrives with `agents secrets vault unlock`, #366/#367)
  *   reconcile-> refresh({ skipPrompts }) — re-materialize resources into homes
  */
-import { pullRepo } from './git.js';
+import { pullRepo, adoptUserRepoIfNeeded } from './git.js';
 import { getUserAgentsDir, getEnabledExtraRepos } from './state.js';
 import { listRemoteBundles, pullBundle } from './secrets/sync.js';
 import { SYNC_PASSPHRASE_ENV } from './secrets/sync-passphrase.js';
@@ -55,7 +55,7 @@ export function planUmbrellaStages(f) {
 export async function runUmbrellaSync(args) {
     const { flags, log, yes, passphrase, quiet = false } = args;
     const plan = planUmbrellaStages(flags);
-    const result = { plan, reconciled: false, declined: [] };
+    const result = { plan, reconciled: false, declined: [], reconciledVersions: [] };
     if (plan.fetchRepos) {
         const dirs = [
             { alias: 'user', dir: getUserAgentsDir() },
@@ -64,6 +64,24 @@ export async function runUmbrellaSync(args) {
         let pulled = 0;
         const errors = [];
         for (const { alias, dir } of dirs) {
+            // A box where `~/.agents` is present but not a git repo (or lost its
+            // `.git`) is a partial install: `pullRepo` there silently fails while the
+            // umbrella still reported `✓ reconciled`, so fleet dotfiles/resources never
+            // propagated and nothing said so (PHNX-3239, m0). Adopt it in place first —
+            // the same self-heal `agents sync user` runs (PHNX-3301) — so the pull has a
+            // real repo to fast-forward. A box that cannot be adopted (no recorded
+            // remote) fails LOUD into `errors` with the reason, never a silent no-op.
+            if (alias === 'user') {
+                const adopted = await adoptUserRepoIfNeeded(dir);
+                if (adopted && !adopted.success) {
+                    const hint = adopted.needsUrl ? ' — git-back it: agents repo pull user <git-url>' : '';
+                    errors.push(`${alias}: ${adopted.error}${hint}`);
+                    continue;
+                }
+                if (adopted?.success) {
+                    log(`repos: ${alias} adopted in place → ${adopted.commit} (${adopted.materialized} file(s) materialized)`);
+                }
+            }
             const r = await pullRepo(dir);
             if (r.success) {
                 pulled++;
@@ -116,6 +134,7 @@ export async function runUmbrellaSync(args) {
         const refreshed = await refresh({ skipPrompts: yes, quiet });
         result.reconciled = true;
         result.declined = refreshed.declined;
+        result.reconciledVersions = refreshed.reconciled;
         // Keep already-registered devices' reachability current, and surface newly
         // appeared tailnet nodes as "pending" for the menu-bar Register/Ignore gate
         // rather than silently adding them (refresh mode). Soft: a machine without