@phnx-labs/agents-cli 1.22.70 → 1.22.71

package/dist/lib/exec-bounded.js

@@ -0,0 +1,113 @@
+/**
+ * Async, deadline-bounded, process-group-killable subprocess exec (PHNX-3695).
+ *
+ * The daemon runs every background service on ONE Node event loop. A
+ * synchronous `execFileSync`/`spawnSync` on a service tick blocks that loop for
+ * the whole life of the child — and while it is blocked NOTHING else on the loop
+ * runs, including the supervisor's per-tick deadline timer and the browser IPC
+ * server's socket handlers. That is the wedge PHNX-3411 fixed the *symptom* of:
+ * the browser `version` probe (a trivial synchronous handler) "accepts but never
+ * replies" because the loop that would reply is frozen inside a sync spawn.
+ *
+ * `execFileBounded` is the non-blocking replacement for those tick-path spawns.
+ * It spawns with async `child_process.spawn`, so the event loop keeps serving
+ * other work while the child runs, and it bounds the child two ways:
+ *
+ *  - a `timeoutMs` deadline: on expiry it SIGTERMs the child, then SIGKILLs it
+ *    after {@link KILL_GRACE_MS} if it ignored the term — the same escalation
+ *    `sshExecAsync` uses (ssh-exec.ts).
+ *  - a process GROUP kill: the child is spawned as its own group leader
+ *    (`detached` on POSIX) so the signal reaches the whole subtree, not just the
+ *    direct child. A bare `child.kill()` would leave grandchildren running — the
+ *    orphaned-`ps`/`powershell` leak class. Windows uses `taskkill /T`.
+ *
+ * It never throws for a non-zero exit, a signal, or a spawn error: every outcome
+ * is reported in the returned {@link BoundedExecResult} so a caller on a tick
+ * path can branch on it instead of wrapping every call in try/catch.
+ */
+import { spawn } from 'child_process';
+/** Grace between SIGTERM and SIGKILL for a child that overran its deadline. */
+export const KILL_GRACE_MS = 250;
+/**
+ * Run `file args` with a hard deadline, killing the whole process group on
+ * timeout. Resolves (never rejects) with the captured output and outcome.
+ */
+export function execFileBounded(file, args, opts) {
+    const isWin = process.platform === 'win32';
+    return new Promise((resolve) => {
+        const child = spawn(file, args, {
+            cwd: opts.cwd,
+            env: opts.env ?? process.env,
+            // POSIX: lead a new process group so a timeout kill(-pid) reaches the
+            // whole subtree, not just the direct child. Windows has no process
+            // groups here — taskkill /T handles the tree instead.
+            detached: !isWin,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        let timedOut = false;
+        let killTimer = null;
+        // Signal the whole group on POSIX (negative pid); on Windows tear the tree
+        // down with taskkill. Best-effort — an already-dead child is fine.
+        const killGroup = (signal) => {
+            if (child.pid === undefined)
+                return;
+            try {
+                if (isWin) {
+                    // taskkill is itself a child; spawn it detached and forget it.
+                    spawn('taskkill', ['/F', '/T', '/PID', String(child.pid)], { stdio: 'ignore', windowsHide: true }).on('error', () => { });
+                }
+                else {
+                    process.kill(-child.pid, signal);
+                }
+            }
+            catch { /* group already gone */ }
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killGroup('SIGTERM');
+            // SIGTERM is advisory; a wedged child can ignore it and keep the Promise
+            // (and the caller's tick) pending forever. Enforce a hard SIGKILL bound.
+            killTimer = setTimeout(() => {
+                if (!settled)
+                    killGroup('SIGKILL');
+            }, KILL_GRACE_MS);
+            killTimer.unref?.();
+        }, opts.timeoutMs);
+        timer.unref?.();
+        const clearTimers = () => {
+            clearTimeout(timer);
+            if (killTimer)
+                clearTimeout(killTimer);
+        };
+        child.stdout?.setEncoding('utf-8');
+        child.stderr?.setEncoding('utf-8');
+        child.stdout?.on('data', (chunk) => { stdout += chunk; });
+        child.stderr?.on('data', (chunk) => { stderr += chunk; });
+        // A child that closes stdin early makes end()/write emit EPIPE; with no
+        // listener Node escalates it to an uncaught exception. Swallow it — the real
+        // outcome is still reported by 'close'/'error' below.
+        child.stdin?.on('error', () => { });
+        if (opts.input !== undefined)
+            child.stdin?.end(opts.input);
+        else
+            child.stdin?.end();
+        child.on('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimers();
+            resolve({ code: null, stdout, stderr: stderr + err.message, timedOut });
+        });
+        child.on('close', (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimers();
+            resolve({ code, stdout, stderr, timedOut });
+        });
+    });
+}

package/dist/lib/feed/events.d.ts

@@ -110,21 +110,21 @@ export interface CallerIdentity {
 }
 /** Identify the environment that invoked agents-cli, not the source callsite. */
 export declare function detectCaller(env?: NodeJS.ProcessEnv, stdoutIsTTY?: boolean): CallerIdentity;
-/**
- * Emit a structured event to the append-only audit log.
- *
- * @param event - The event type
- * @param payload - Event-specific data (agent, version, cwd, etc.)
- * @param overrides - Envelope fields the CALLER owns rather than the writer.
- *   Only `ts` today: a batched out-of-process producer (`agents events emit`)
- *   records when each event HAPPENED, but flushes them together later, so
- *   stamping write-time would collapse a whole batch onto the flush instant and
- *   corrupt every `--since` boundary. `ts` stays in RESERVED_META_KEYS so a
- *   *payload* still cannot inject it — this explicit channel is the only way in.
- */
 export declare function emit(event: EventType, payload?: EventPayload, overrides?: {
     ts?: string;
 }): void;
+/**
+ * Async, non-blocking counterpart of {@link emit} for callers on the daemon's
+ * shared event loop (PHNX-3695). `emit` acquires the event-log lock with
+ * `withFileLock` → `sleepSync` (`Atomics.wait`), which HALTS the loop for up to
+ * 30s under contention (a peer appending to the same log). `emitAsync` acquires
+ * it with `withFileLockAsync`, so the loop keeps turning. The under-lock body is
+ * identical (a µs-scale append + a rare rotate). Best-effort like `emit`: never
+ * throws; a caller on a tick fires it and moves on.
+ */
+export declare function emitAsync(event: EventType, payload?: EventPayload, overrides?: {
+    ts?: string;
+}): Promise<void>;
 /**
  * Convenience wrapper for timed operations.
  * Returns a function to call when the operation completes.
@@ -135,14 +135,21 @@ export declare function emit(event: EventType, payload?: EventPayload, overrides
  * done({ exitCode: 0 }); // emits agent.run.end with durationMs
  */
 export declare function emitStart(startEvent: EventType, payload?: EventPayload): (endPayload?: EventPayload) => void;
-export declare function emitRoutineEnd(meta: {
+interface RoutineEndMeta {
     jobName: string;
     runId?: string;
     status: string;
     duration?: number;
     exitCode?: number | null;
     detail?: string;
-}): void;
+}
+export declare function emitRoutineEnd(meta: RoutineEndMeta): void;
+/**
+ * Async, non-blocking `routine.end` for the daemon heartbeat tick (PHNX-3695):
+ * the reaper (`reapExitedRunningJobs`) runs on the shared event loop, so it emits
+ * through {@link emitAsync} rather than the `sleepSync`-locked {@link emit}.
+ */
+export declare function emitRoutineEndAsync(meta: RoutineEndMeta): Promise<void>;
 /**
  * Measure execution time of a synchronous function.
  * Emits a perf.timing event with the duration.
@@ -272,3 +279,4 @@ export declare function stats(options?: {
 }): EventStats;
 export declare function getLogsPath(): string;
 export declare function _resetForTest(overrideEventsPath?: string, overrideUserAgentsDir?: string): void;
+export {};

package/dist/lib/feed/events.js

@@ -16,7 +16,7 @@ import * as path from 'path';
 import * as os from 'os';
 import { createHash } from 'node:crypto';
 import { gzipSync, gunzipSync } from 'node:zlib';
-import { ensureLockTarget, withFileLock } from '../fs-atomic.js';
+import { ensureLockTarget, withFileLock, withFileLockAsync } from '../fs-atomic.js';
 import { getUserAgentsDir } from '../state.js';
 import { stampProvenance, resetEventProvenanceForTest } from '../event-provenance.js';
 import { recordSample } from '../perf/spool.js';
@@ -493,48 +493,77 @@ export function detectCaller(env = process.env, stdoutIsTTY = Boolean(process.st
  *   corrupt every `--since` boundary. `ts` stays in RESERVED_META_KEYS so a
  *   *payload* still cannot inject it — this explicit channel is the only way in.
  */
-export function emit(event, payload = {}, overrides = {}) {
+/** Build the JSONL line + target path for an event, or null when logging is disabled. Shared by {@link emit} and {@link emitAsync}. */
+function prepareEventWrite(event, payload, overrides) {
     if (isDisabled())
-        return;
+        return null;
+    ensureLogsDir();
+    const caller = detectCaller();
+    const safePayload = sanitizePayload(payload);
+    const record = {
+        // Provenance floor first: env-sourced defaults an explicit payload overrides.
+        ...stampProvenance(),
+        ...safePayload,
+        ts: overrides.ts ?? new Date().toISOString(),
+        tz: getTimezoneOffset(),
+        tzName: getTimezoneName(),
+        hostname: os.hostname(),
+        platform: os.platform(),
+        arch: os.arch(),
+        pid: process.pid,
+        ppid: process.ppid,
+        event,
+        level: levelFor(event),
+        caller: caller.kind,
+        ...(caller.session ? { session: caller.session } : {}),
+    };
+    const line = JSON.stringify(record) + '\n';
+    const logPath = eventsPath();
+    const isNew = !fs.existsSync(logPath);
+    ensureLockTarget(logPath, '', DIR_MODE);
+    return { logPath, line, isNew };
+}
+/** The under-lock append + chmod + rotate/prune. Tiny local writes (µs), safe inside either the sync or async lock. */
+function appendEventLocked(logPath, line, isNew) {
+    fs.appendFileSync(logPath, line, { mode: FILE_MODE });
+    if (isNew || logPath !== _chmoddedPath) {
+        _chmoddedPath = logPath;
+        try {
+            fs.chmodSync(logPath, FILE_MODE);
+        }
+        catch {
+            // May fail if not owner
+        }
+    }
+    const rotated = maybeGzipRotateLocked(logPath);
+    maybePruneLocked(rotated);
+}
+export function emit(event, payload = {}, overrides = {}) {
     try {
-        ensureLogsDir();
-        const caller = detectCaller();
-        const safePayload = sanitizePayload(payload);
-        const record = {
-            // Provenance floor first: env-sourced defaults an explicit payload overrides.
-            ...stampProvenance(),
-            ...safePayload,
-            ts: overrides.ts ?? new Date().toISOString(),
-            tz: getTimezoneOffset(),
-            tzName: getTimezoneName(),
-            hostname: os.hostname(),
-            platform: os.platform(),
-            arch: os.arch(),
-            pid: process.pid,
-            ppid: process.ppid,
-            event,
-            level: levelFor(event),
-            caller: caller.kind,
-            ...(caller.session ? { session: caller.session } : {}),
-        };
-        const line = JSON.stringify(record) + '\n';
-        const logPath = eventsPath();
-        const isNew = !fs.existsSync(logPath);
-        ensureLockTarget(logPath, '', DIR_MODE);
-        withFileLock(logPath, () => {
-            fs.appendFileSync(logPath, line, { mode: FILE_MODE });
-            if (isNew || logPath !== _chmoddedPath) {
-                _chmoddedPath = logPath;
-                try {
-                    fs.chmodSync(logPath, FILE_MODE);
-                }
-                catch {
-                    // May fail if not owner
-                }
-            }
-            const rotated = maybeGzipRotateLocked(logPath);
-            maybePruneLocked(rotated);
-        });
+        const prepared = prepareEventWrite(event, payload, overrides);
+        if (!prepared)
+            return;
+        withFileLock(prepared.logPath, () => appendEventLocked(prepared.logPath, prepared.line, prepared.isNew));
+    }
+    catch {
+        // Silent failure - logging should never break the CLI
+    }
+}
+/**
+ * Async, non-blocking counterpart of {@link emit} for callers on the daemon's
+ * shared event loop (PHNX-3695). `emit` acquires the event-log lock with
+ * `withFileLock` → `sleepSync` (`Atomics.wait`), which HALTS the loop for up to
+ * 30s under contention (a peer appending to the same log). `emitAsync` acquires
+ * it with `withFileLockAsync`, so the loop keeps turning. The under-lock body is
+ * identical (a µs-scale append + a rare rotate). Best-effort like `emit`: never
+ * throws; a caller on a tick fires it and moves on.
+ */
+export async function emitAsync(event, payload = {}, overrides = {}) {
+    try {
+        const prepared = prepareEventWrite(event, payload, overrides);
+        if (!prepared)
+            return;
+        await withFileLockAsync(prepared.logPath, () => appendEventLocked(prepared.logPath, prepared.line, prepared.isNew));
     }
     catch {
         // Silent failure - logging should never break the CLI
@@ -558,8 +587,8 @@ export function emitStart(startEvent, payload = {}) {
         emit(startEvent.replace('.start', '.end'), { ...payload, ...endPayload, durationMs: Date.now() - startTime });
     };
 }
-export function emitRoutineEnd(meta) {
-    emit('routine.end', {
+function routineEndPayload(meta) {
+    return {
         module: 'routine',
         name: meta.jobName,
         status: meta.status,
@@ -567,7 +596,18 @@ export function emitRoutineEnd(meta) {
         ...(meta.duration != null ? { durationMs: meta.duration } : {}),
         ...(meta.exitCode != null ? { exitCode: meta.exitCode } : {}),
         ...(meta.detail ? { detail: meta.detail } : {}),
-    });
+    };
+}
+export function emitRoutineEnd(meta) {
+    emit('routine.end', routineEndPayload(meta));
+}
+/**
+ * Async, non-blocking `routine.end` for the daemon heartbeat tick (PHNX-3695):
+ * the reaper (`reapExitedRunningJobs`) runs on the shared event loop, so it emits
+ * through {@link emitAsync} rather than the `sleepSync`-locked {@link emit}.
+ */
+export async function emitRoutineEndAsync(meta) {
+    await emitAsync('routine.end', routineEndPayload(meta));
 }
 // ─── Timing Utilities ─────────────────────────────────────────────────────────
 /**

package/dist/lib/fleet-shared-state.d.ts

@@ -25,14 +25,21 @@ export interface FleetSharedStateReadResult {
 }
 /** Path owned by one device in the conflict-free tracked device-doc tree. */
 export declare function fleetSharedStatePath(device: string, userAgentsDir?: string): string;
-/**
- * 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 declare function updateFleetSharedDeviceState(device: string, patch: FleetSharedStatePatch, userAgentsDir?: string): {
     changed: boolean;
     path: string;
 };
+/**
+ * Async, non-blocking twin of {@link updateFleetSharedDeviceState} for the
+ * daemon's usage-sync / auth-sync ticks (PHNX-3695). The sync version acquires
+ * the file lock with `sleepSync` (`Atomics.wait`), freezing the shared event
+ * loop for up to 30s under contention on EVERY tick; this uses
+ * `withFileLockAsync`. The under-lock read is async; the atomic write is a tiny
+ * bounded write held inside the lock.
+ */
+export declare function updateFleetSharedDeviceStateAsync(device: string, patch: FleetSharedStatePatch, userAgentsDir?: string): Promise<{
+    changed: boolean;
+    path: string;
+}>;
 /** Read every valid peer-owned state file; malformed peers fail separately. */
 export declare function readFleetSharedDeviceStates(userAgentsDir?: string): FleetSharedStateReadResult;

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

@@ -8,9 +8,10 @@
  * remains the one path that may carry secret material.
  */
 import * as fs from 'node:fs';
+import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
 import { assertValidDeviceName } from './devices/registry.js';
-import { atomicWriteFileSync, ensureLockTarget, withFileLock } from './fs-atomic.js';
+import { atomicWriteFileSync, ensureLockTarget, withFileLock, withFileLockAsync } 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';
@@ -43,32 +44,61 @@ function parseFleetSharedDeviceState(raw, owner) {
  * inter-process lock. Stable serialization avoids dirtying the user repo when
  * neither usage nor auth state changed.
  */
+/** Merge `patch` onto the current on-disk state; returns the serialized next state, or null when unchanged. Shared by the sync and async writers. */
+function mergeFleetState(currentRaw, device, patch) {
+    let current = { version: FLEET_SHARED_STATE_VERSION, device };
+    const trimmed = currentRaw.trim();
+    if (trimmed) {
+        try {
+            current = parseFleetSharedDeviceState(trimmed, device);
+        }
+        catch { /* owning device repairs its own malformed file; peers are never repaired here */ }
+    }
+    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`;
+    return { serialized, changed: currentRaw !== serialized };
+}
 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,
-        };
+        let raw = '';
         try {
-            const raw = fs.readFileSync(file, 'utf-8').trim();
-            if (raw)
-                current = parseFleetSharedDeviceState(raw, device);
+            raw = fs.readFileSync(file, 'utf-8');
         }
-        catch {
-            // The owning device repairs its own malformed file from authoritative
-            // local state. Peer files are never repaired by this writer.
+        catch { /* missing → treat as empty */ }
+        const { serialized, changed } = mergeFleetState(raw, device, patch);
+        if (!changed)
+            return { changed: false, path: file };
+        atomicWriteFileSync(file, serialized, 'utf-8');
+        return { changed: true, path: file };
+    });
+}
+/**
+ * Async, non-blocking twin of {@link updateFleetSharedDeviceState} for the
+ * daemon's usage-sync / auth-sync ticks (PHNX-3695). The sync version acquires
+ * the file lock with `sleepSync` (`Atomics.wait`), freezing the shared event
+ * loop for up to 30s under contention on EVERY tick; this uses
+ * `withFileLockAsync`. The under-lock read is async; the atomic write is a tiny
+ * bounded write held inside the lock.
+ */
+export async function updateFleetSharedDeviceStateAsync(device, patch, userAgentsDir = getUserAgentsDir()) {
+    const file = fleetSharedStatePath(device, userAgentsDir);
+    ensureLockTarget(file, '');
+    return withFileLockAsync(file, async () => {
+        let raw = '';
+        try {
+            raw = await fsp.readFile(file, 'utf-8');
         }
-        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)
+        catch { /* missing → treat as empty */ }
+        const { serialized, changed } = mergeFleetState(raw, device, patch);
+        if (!changed)
             return { changed: false, path: file };
         atomicWriteFileSync(file, serialized, 'utf-8');
         return { changed: true, path: file };

package/dist/lib/fs-atomic.d.ts

@@ -42,3 +42,14 @@ export interface FileLockOptions {
     acquireTimeoutMs?: number;
 }
 export declare function withFileLock<T>(filePath: string, fn: (heartbeat: () => void) => T, opts?: FileLockOptions): T;
+/**
+ * Async counterpart of {@link withFileLock} for callers on the daemon's shared
+ * event loop (PHNX-3695). The sync version retries acquisition with
+ * {@link sleepSync} (`Atomics.wait`), which HALTS the thread for up to
+ * {@link LOCK_ACQUIRE_TIMEOUT_MS} on contention — on a daemon tick that freezes
+ * every service and the browser IPC server. This variant awaits proper-lockfile's
+ * async `lock()` and yields with a real timer between retries, so the loop keeps
+ * turning while a peer holds the lock. Same stale-break, same acquire budget,
+ * same compromised-lock surfacing.
+ */
+export declare function withFileLockAsync<T>(filePath: string, fn: (heartbeat: () => void) => Promise<T> | T, opts?: FileLockOptions): Promise<T>;

package/dist/lib/fs-atomic.js

@@ -126,3 +126,63 @@ export function withFileLock(filePath, fn, opts = {}) {
         catch { /* already gone */ }
     }
 }
+/**
+ * Async counterpart of {@link withFileLock} for callers on the daemon's shared
+ * event loop (PHNX-3695). The sync version retries acquisition with
+ * {@link sleepSync} (`Atomics.wait`), which HALTS the thread for up to
+ * {@link LOCK_ACQUIRE_TIMEOUT_MS} on contention — on a daemon tick that freezes
+ * every service and the browser IPC server. This variant awaits proper-lockfile's
+ * async `lock()` and yields with a real timer between retries, so the loop keeps
+ * turning while a peer holds the lock. Same stale-break, same acquire budget,
+ * same compromised-lock surfacing.
+ */
+export async function withFileLockAsync(filePath, fn, opts = {}) {
+    let release = null;
+    let lastError;
+    let compromised = null;
+    const staleMs = opts.staleMs ?? LOCK_STALE_MS;
+    const acquireTimeoutMs = opts.acquireTimeoutMs ?? LOCK_ACQUIRE_TIMEOUT_MS;
+    const deadline = Date.now() + acquireTimeoutMs;
+    for (let attempt = 0;; attempt++) {
+        try {
+            release = await lockfile.lock(filePath, {
+                stale: staleMs,
+                onCompromised: (err) => { compromised = err; },
+            });
+            break;
+        }
+        catch (err) {
+            lastError = err;
+            if (Date.now() >= deadline)
+                break;
+            const backoff = Math.min(LOCK_RETRY_MIN_MS * (attempt + 1), LOCK_RETRY_MAX_MS);
+            await new Promise((r) => setTimeout(r, Math.min(backoff, Math.max(0, deadline - Date.now()))));
+        }
+    }
+    if (!release) {
+        const message = lastError instanceof Error ? lastError.message : String(lastError);
+        throw new Error(`Could not acquire lock for ${filePath} after ${acquireTimeoutMs}ms: ${message}`);
+    }
+    const lockDir = `${filePath}.lock`;
+    const heartbeat = () => {
+        try {
+            const now = new Date();
+            fs.utimesSync(lockDir, now, now);
+        }
+        catch { /* best effort */ }
+    };
+    try {
+        const result = await fn(heartbeat);
+        if (compromised) {
+            throw new Error(`Lock for ${filePath} was broken by another process while held: ` +
+                `${compromised.message}`);
+        }
+        return result;
+    }
+    finally {
+        try {
+            await release();
+        }
+        catch { /* already gone */ }
+    }
+}

package/dist/lib/hosts/reconcile.d.ts

@@ -30,18 +30,25 @@ export type RemoteExitState = {
  * empty stdout, and a truncate-then-write mid-race is a sub-ms empty window).
  */
 export declare function classifyExit(res: Pick<SshExecResult, 'code' | 'stdout' | 'timedOut'>): RemoteExitState;
+export declare function readRemoteExit(target: string, remoteExit: string, timeoutMs?: number, identityFile?: string, remoteShell?: 'posix' | 'powershell'): RemoteExitState;
 /**
- * Read a task's remote `.exit` over ssh and classify it. `remoteExit` is a
- * $HOME-prefixed path with a safe (hex) basename — intentionally unquoted so the
- * remote shell expands $HOME (same contract as progress.ts's fetch).
+ * Async twin of {@link readRemoteExit} for the daemon's heartbeat tick — the ssh
+ * read runs on the shared event loop, so it MUST NOT block it with a synchronous
+ * `spawnSync('ssh', …)` (PHNX-3695). `sshExecAsync` applies the same
+ * timeout/kill-grace bound.
  */
-export declare function readRemoteExit(target: string, remoteExit: string, timeoutMs?: number, identityFile?: string, remoteShell?: 'posix' | 'powershell'): RemoteExitState;
+export declare function readRemoteExitAsync(target: string, remoteExit: string, timeoutMs?: number, identityFile?: string, remoteShell?: 'posix' | 'powershell'): Promise<RemoteExitState>;
 /**
  * Heal one record. Terminal records are immutable (and never re-probed); a
  * `running` record is resolved to completed/failed only when the remote `.exit`
  * holds a code. Returns the (possibly updated) task.
  */
 export declare function reconcileTask(task: HostTask): HostTask;
+/**
+ * Async twin of {@link reconcileTask} for the daemon heartbeat tick (PHNX-3695):
+ * identical healing logic, non-blocking ssh read via {@link readRemoteExitAsync}.
+ */
+export declare function reconcileTaskAsync(task: HostTask): Promise<HostTask>;
 /**
  * Heal a list of records for a listing (`agents devices ps`). Only `running` tasks
  * are probed; each host is reachability-checked ONCE (deduped by target) so a

package/dist/lib/hosts/reconcile.js

@@ -10,7 +10,7 @@
  * record. We only ever CONFIRM completion; an unreachable host or an absent
  * `.exit` leaves the record `running` (we never guess failure).
  */
-import { sshExec } from '../ssh-exec.js';
+import { sshExec, sshExecAsync } from '../ssh-exec.js';
 import { updateTask, terminalPatch } from './tasks.js';
 import { encodePowershell } from './remote-cmd.js';
 /**
@@ -36,15 +36,29 @@ export function classifyExit(res) {
  * $HOME-prefixed path with a safe (hex) basename — intentionally unquoted so the
  * remote shell expands $HOME (same contract as progress.ts's fetch).
  */
-export function readRemoteExit(target, remoteExit, timeoutMs = 6000, identityFile, remoteShell = 'posix') {
-    const command = remoteShell === 'powershell'
+function remoteExitCommand(remoteExit, remoteShell) {
+    return remoteShell === 'powershell'
         ? `powershell -NoProfile -EncodedCommand ${encodePowershell(`$path = Join-Path $HOME '${remoteExit.replace(/^\$HOME\//, '').replace(/'/g, "''")}'; if (Test-Path -LiteralPath $path) { Get-Content -LiteralPath $path -Raw }`)}`
         : `cat ${remoteExit} 2>/dev/null`;
-    return classifyExit(sshExec(target, command, {
+}
+function remoteExitSshOpts(timeoutMs, identityFile) {
+    return {
         timeoutMs,
         multiplex: true,
         extraSshArgs: identityFile ? ['-i', identityFile, '-o', 'IdentitiesOnly=yes'] : undefined,
-    }));
+    };
+}
+export function readRemoteExit(target, remoteExit, timeoutMs = 6000, identityFile, remoteShell = 'posix') {
+    return classifyExit(sshExec(target, remoteExitCommand(remoteExit, remoteShell), remoteExitSshOpts(timeoutMs, identityFile)));
+}
+/**
+ * Async twin of {@link readRemoteExit} for the daemon's heartbeat tick — the ssh
+ * read runs on the shared event loop, so it MUST NOT block it with a synchronous
+ * `spawnSync('ssh', …)` (PHNX-3695). `sshExecAsync` applies the same
+ * timeout/kill-grace bound.
+ */
+export async function readRemoteExitAsync(target, remoteExit, timeoutMs = 6000, identityFile, remoteShell = 'posix') {
+    return classifyExit(await sshExecAsync(target, remoteExitCommand(remoteExit, remoteShell), remoteExitSshOpts(timeoutMs, identityFile)));
 }
 /**
  * Heal one record. Terminal records are immutable (and never re-probed); a
@@ -59,6 +73,18 @@ export function reconcileTask(task) {
         return task;
     return updateTask(task.id, terminalPatch(st.code)) ?? task;
 }
+/**
+ * Async twin of {@link reconcileTask} for the daemon heartbeat tick (PHNX-3695):
+ * identical healing logic, non-blocking ssh read via {@link readRemoteExitAsync}.
+ */
+export async function reconcileTaskAsync(task) {
+    if (task.status !== 'running')
+        return task;
+    const st = await readRemoteExitAsync(task.target, task.remoteExit, 6000, task.identityFile, task.remoteShell);
+    if (st.state !== 'done')
+        return task;
+    return updateTask(task.id, terminalPatch(st.code)) ?? task;
+}
 /**
  * Heal a list of records for a listing (`agents devices ps`). Only `running` tasks
  * are probed; each host is reachability-checked ONCE (deduped by target) so a

package/dist/lib/project-resources.d.ts

@@ -5,6 +5,18 @@ export interface ProjectResourceSyncResult {
 }
 export declare function projectAgentRoot(projectRoot: string, agent: AgentId): string;
 export declare function syncProjectResourcesToAgent(agent: AgentId, version: string, projectAgentsDir: string): ProjectResourceSyncResult;
+/**
+ * Turn the manifest's managed paths (relative to agentRoot) into anchored,
+ * POSIX, projectRoot-relative `.gitignore` entries. Two guards keep it honest:
+ *   - drop any path that escapes the harness config dir (e.g. grok writes
+ *     commands back into the tracked `.agents/` tree via a `../` subdir —
+ *     ignoring that would hide tracked source; separate bug, PHNX-3718);
+ *   - the manifest only ever holds paths the sync itself generated (pre-existing
+ *     user/committed files are skipped and never recorded), so ignoring exactly
+ *     these never masks a hand-authored or committed file (e.g. a repo that
+ *     commits its own `.claude/CLAUDE.md` keeps it — it is not in the manifest).
+ */
+export declare function managedGitignoreEntries(agentRoot: string, projectRoot: string, managed: string[]): string[];
 /**
  * One human line for the files a project sync left alone because you already
  * wrote them. This is the normal steady state — every sync of a project whose