@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/daemon/self-heal-service.d.ts

@@ -1,21 +1,22 @@
-/**
- * Resource self-heal tick as a `PeriodicService` (RUSH-3193 P3).
- *
- * Fills missing resources, repairs invalid manifests, and fast-forwards
- * pristine stale plugins. Conservative 'safe' mode: never overwrites
- * hand-edited content. Does not run when the daemon's state directory no
- * longer exists — that is the state-dir self-check's signal to shut down;
- * background maintenance must not recreate the tree while it is mid-exit.
- *
- * The pre-migration inline timer also delayed its first fire by
- * `SELF_HEAL_KICKOFF_MS` (30s) so shims/PATH could settle shortly after daemon
- * start, without making launch itself busy. `startupDelayMs` below reproduces
- * that stagger through the supervisor's generic per-service contract
- * (`service.ts`) — every other tick still fires on the normal `intervalMs`
- * cadence; only self-heal's boot-time tick is deliberately staggered.
- */
 import { BasePeriodicService, type DaemonContext } from './service.js';
 import type { DaemonServiceId } from '../daemon-services.js';
+import { type CooperativeChildResult } from './harness-update-service.js';
+import { type SelfHealChildSummary } from '../self-heal/child.js';
+export declare function readLastSelfHealAttempt(): Promise<number | null>;
+export interface SelfHealDeps {
+    runChild(signal: AbortSignal): Promise<CooperativeChildResult>;
+    now(): number;
+}
+export type SelfHealTickOutcome = {
+    ran: false;
+    reason: 'no-daemon-dir' | 'recent' | 'stamp-unwritable';
+} | {
+    ran: true;
+    exitCode: number | null;
+    cancelled: boolean;
+    summary?: SelfHealChildSummary;
+};
+export declare function runSelfHealTick(ctx: DaemonContext, signal: AbortSignal, deps?: SelfHealDeps): Promise<SelfHealTickOutcome>;
 export declare class SelfHealService extends BasePeriodicService {
     readonly id: DaemonServiceId;
     readonly intervalMs: number;
@@ -23,5 +24,5 @@ export declare class SelfHealService extends BasePeriodicService {
     readonly startupDelayMs = 30000;
     protected onStart(_ctx: DaemonContext): Promise<void>;
     protected onStop(): Promise<void>;
-    protected onTick(ctx: DaemonContext): Promise<void>;
+    protected onTick(ctx: DaemonContext, signal: AbortSignal): Promise<void>;
 }

package/dist/lib/daemon/self-heal-service.js

@@ -1,23 +1,16 @@
-/**
- * Resource self-heal tick as a `PeriodicService` (RUSH-3193 P3).
- *
- * Fills missing resources, repairs invalid manifests, and fast-forwards
- * pristine stale plugins. Conservative 'safe' mode: never overwrites
- * hand-edited content. Does not run when the daemon's state directory no
- * longer exists — that is the state-dir self-check's signal to shut down;
- * background maintenance must not recreate the tree while it is mid-exit.
- *
- * The pre-migration inline timer also delayed its first fire by
- * `SELF_HEAL_KICKOFF_MS` (30s) so shims/PATH could settle shortly after daemon
- * start, without making launch itself busy. `startupDelayMs` below reproduces
- * that stagger through the supervisor's generic per-service contract
- * (`service.ts`) — every other tick still fires on the normal `intervalMs`
- * cadence; only self-heal's boot-time tick is deliberately staggered.
- */
+import * as fsp from 'fs/promises';
+import * as path from 'path';
 import { BasePeriodicService } from './service.js';
 import { getDaemonDir } from '../state.js';
-import * as fsp from 'fs/promises';
-/** Async `existsSync` — never a synchronous stat on the daemon tick loop (PHNX-3695). */
+import { getCliLaunch, getAgentsBinPath } from '../cli-entry.js';
+import { driveCooperativeChild } from './harness-update-service.js';
+import { SELF_HEAL_CHILD_CMD, selfHealCancelMessage } from '../self-heal/child.js';
+const SELF_HEAL_TICK_MS = 6 * 60 * 60_000;
+const SELF_HEAL_DEADLINE_MS = 10 * 60_000;
+const SELF_HEAL_KICKOFF_MS = 30_000;
+const SELF_HEAL_CANCEL_GRACE_MS = 30_000;
+const LAST_ATTEMPT_FILE = 'self-heal-last-attempt';
+const SELF_HEAL_SKIP_SLACK_MS = 5 * 60_000;
 async function pathExists(p) {
     try {
         await fsp.access(p);
@@ -27,32 +20,85 @@ async function pathExists(p) {
         return false;
     }
 }
-/** Matches the historical inline interval (daemon.ts SELF_HEAL_TICK_MS). Runs ~every 6h. */
-const SELF_HEAL_TICK_MS = 6 * 60 * 60_000;
-/** Hard cap per tick — a full resource repair sweep across every version home, short enough a hang never freezes the service for long relative to its 6h cadence. */
-const SELF_HEAL_DEADLINE_MS = 10 * 60_000;
-/** Matches the historical inline kickoff delay (daemon.ts SELF_HEAL_KICKOFF_MS). Staggers self-heal's first tick after shims/PATH settle, so launch itself isn't made busy. */
-const SELF_HEAL_KICKOFF_MS = 30_000;
+function lastAttemptPath() {
+    return path.join(getDaemonDir(), LAST_ATTEMPT_FILE);
+}
+export async function readLastSelfHealAttempt() {
+    try {
+        const ms = Number((await fsp.readFile(lastAttemptPath(), 'utf-8')).trim());
+        return Number.isFinite(ms) && ms > 0 ? ms : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function recordSelfHealAttempt(nowMs) {
+    await fsp.writeFile(lastAttemptPath(), String(nowMs), 'utf-8');
+}
+function defaultSelfHealDeps() {
+    return {
+        runChild(signal) {
+            const { command, args } = getCliLaunch([SELF_HEAL_CHILD_CMD], getAgentsBinPath());
+            return driveCooperativeChild(command, args, signal, SELF_HEAL_CANCEL_GRACE_MS, {
+                cancelMsg: selfHealCancelMessage(),
+                label: 'self-heal',
+            });
+        },
+        now: () => Date.now(),
+    };
+}
+export async function runSelfHealTick(ctx, signal, deps = defaultSelfHealDeps()) {
+    if (!(await pathExists(getDaemonDir())))
+        return { ran: false, reason: 'no-daemon-dir' };
+    const now = deps.now();
+    const last = await readLastSelfHealAttempt();
+    if (last !== null && now - last < SELF_HEAL_TICK_MS - SELF_HEAL_SKIP_SLACK_MS)
+        return { ran: false, reason: 'recent' };
+    try {
+        await recordSelfHealAttempt(now);
+    }
+    catch (err) {
+        ctx.log('ERROR', `self-heal: cannot record the attempt in ${lastAttemptPath()}, skipping the pass: ${err instanceof Error ? err.message : String(err)}`);
+        return { ran: false, reason: 'stamp-unwritable' };
+    }
+    let result;
+    try {
+        result = await deps.runChild(signal);
+    }
+    catch (err) {
+        ctx.log('ERROR', `self-heal: pass failed to run: ${err instanceof Error ? err.message : String(err)}`);
+        return { ran: true, exitCode: null, cancelled: signal.aborted };
+    }
+    if (result.cancelled) {
+        ctx.log('INFO', 'self-heal: pass cancelled (deadline or daemon shutdown)');
+        return { ran: true, exitCode: result.exitCode, cancelled: true };
+    }
+    if (result.exitCode !== 0) {
+        ctx.log('WARN', `self-heal: pass exited ${result.exitCode}: ${result.stdout.slice(0, 2000)}`);
+        return { ran: true, exitCode: result.exitCode, cancelled: false };
+    }
+    let summary;
+    try {
+        summary = JSON.parse(result.stdout);
+    }
+    catch {
+        ctx.log('WARN', `self-heal: pass printed no summary: ${result.stdout.slice(0, 500)}`);
+        return { ran: true, exitCode: 0, cancelled: false };
+    }
+    if (summary.changed || summary.needsAttention)
+        ctx.log('INFO', `self-heal: ${summary.summary}`);
+    return { ran: true, exitCode: 0, cancelled: false, summary };
+}
 export class SelfHealService extends BasePeriodicService {
     id = 'self-heal';
     intervalMs = SELF_HEAL_TICK_MS;
     deadlineMs = SELF_HEAL_DEADLINE_MS;
     startupDelayMs = SELF_HEAL_KICKOFF_MS;
     async onStart(_ctx) {
-        // No connections/handles to open — each tick re-checks the state dir itself.
     }
     async onStop() {
-        // Nothing to release — the supervisor's timer teardown is the only cleanup needed.
-    }
-    async onTick(ctx) {
-        if (!(await pathExists(getDaemonDir())))
-            return;
-        const { runSelfHeal, selfHealChangedAnything, selfHealNeedsAttention, summarizeSelfHeal } = await import('../self-heal/registry.js');
-        if (!(await pathExists(getDaemonDir())))
-            return;
-        const report = await runSelfHeal({ mode: 'safe' });
-        if (selfHealChangedAnything(report) || selfHealNeedsAttention(report)) {
-            ctx.log('INFO', `self-heal: ${summarizeSelfHeal(report)}`);
-        }
+    }
+    async onTick(ctx, signal) {
+        await runSelfHealTick(ctx, signal);
     }
 }

package/dist/lib/daemon/self-update-service.d.ts

@@ -1,38 +1,3 @@
-/**
- * Daemon self-update service (PHNX-3695, "Fix 2").
- *
- * The daemon (`agents __daemon-run`) is a long-running background process that
- * historically opted OUT of the CLI's interactive auto-update: `bootstrap.ts`
- * force-sets `AGENTS_CLI_DISABLE_AUTO_UPDATE=1` for `__daemon-run`, so a
- * running daemon never picked up new agents-cli code until a human ran
- * `agents daemon restart`. R5 in the root CLAUDE.md ("An installed CLI and its
- * installed helpers auto-update from the public channel") is binding for the
- * interactive CLI path (`self-update.ts` / `agents upgrade`) but was silently
- * NOT held for the one process that runs unattended for days. This service
- * closes that gap for the daemon specifically, reusing the exact same
- * verified-install primitives `agents upgrade` already uses — it does not
- * fork or reimplement them.
- *
- * Model: verify-then-exit, not swap-in-place. A daemon cannot safely hot-swap
- * its own loaded JS mid-process (in-flight ticks, open sockets, a live
- * ServiceSupervisor). Instead this tick installs + BYTE-VERIFIES the new
- * package on disk, and only once that succeeds does it `process.exit(0)` —
- * the OS supervisor (launchd `KeepAlive` / systemd `Restart=always`, see
- * `daemon/AGENTS.md`'s crash-recovery model) relaunches the daemon, which
- * then boots the new code. Clients do not need to be told anything: a socket
- * client re-probes and reconnects when the daemon relaunches, and the
- * scheduler's atomic `(routine, scheduledFor)` claim (see
- * `docs/specifications.md` §Scheduling & execution singularity) means a routine
- * mid-fire at the moment of exit is deduped safely across the restart rather
- * than double-fired.
- *
- * Fail-closed is the whole point: every step below that can fail — the
- * registry check, the install, the post-install verify — leaves the OLD
- * daemon running untouched and logs a WARN/ERROR for the next tick to retry.
- * The daemon must never exit into code it has not proven is the real,
- * verified, requested version; an unverified exit would let the OS supervisor
- * relaunch-loop on a broken install.
- */
 import { BasePeriodicService, type DaemonContext } from './service.js';
 import type { DaemonServiceId } from '../daemon-services.js';
 interface SelfUpdateOutcome {
@@ -44,19 +9,9 @@ interface NpmLatestMetadata {
     integrity: string;
     tarball: string;
 }
-/**
- * Dependency seam so `self-update-service.test.ts` can drive a REAL install
- * against a fixture npm prefix/tarball without touching the real npm
- * registry or the real running install. Production code always uses
- * {@link defaultSelfUpdateDeps} (the default parameter below) — no test-only
- * branch exists in the exported logic itself.
- */
 export interface SelfUpdateDeps {
-    /** The version this process BOOTED with (memoized at startup). */
     currentVersion(): string;
-    /** The version of the install on disk right now — differs from `currentVersion` once another process upgraded it. */
     installedVersion(): string;
-    /** True when the install on disk looks complete (see `installLooksSettled`) — the gate before relaunching onto a version another process wrote. */
     installedIsSettled(): boolean;
     isDevBuild(): boolean;
     detectShadow(): boolean;
@@ -66,96 +21,10 @@ export interface SelfUpdateDeps {
     syncSystemRepo(): Promise<void>;
     syncLocal(): Promise<void>;
 }
-/**
- * Install + byte-verify `metadata` into `packageRoot`'s install, exactly the
- * sequence `bootstrap.ts`'s `installResolvedPackage` runs for `agents
- * upgrade` (download+integrity-verify -> sweep stale staging -> package-
- * manager install -> verify installed version -> refresh alias shims).
- * `bootstrap.ts` cannot be imported here — it runs side-effecting top-level
- * code (argv parsing, command registration) on import, which the daemon must
- * never trigger — so this is the same primitives from `self-update.ts`
- * composed directly, not a fork of the upgrade logic.
- *
- * `signal` is threaded into EVERY step's own `signal` option
- * (`downloadVerifiedTarball` / `installPackageIntoPrefix` /
- * `installPackageWithBun`, all in `self-update.ts`) rather than raced against
- * from the outside: those primitives kill the underlying fetch/child process
- * on abort and their promise rejects only once that real cancellation has
- * happened. A wrapper that merely stopped AWAITING an unkillable operation
- * (the prior approach here) left an orphaned `npm install -g`/`bun add -g`
- * writing into the shared global prefix — which the very next tick's fresh
- * install (started as soon as the supervisor's backoff fires, seconds later)
- * would then race into the same directory. Real cancellation is what makes
- * `attemptSelfUpdateAndExit`'s `inFlightAttempt` dedupe (below) an actual
- * guarantee instead of a guard whose lifetime is shorter than the operation
- * it's guarding (found in review, PHNX-3695).
- */
 export declare function installAndVerifyDefault(metadata: NpmLatestMetadata, packageRoot: string, signal: AbortSignal): Promise<void>;
-/**
- * Core self-update decision + action, shared by the periodic tick
- * ({@link SelfUpdateService.onTick}) and the on-demand trigger
- * ({@link triggerSelfUpdateInBackground}) — one implementation, so a
- * version-skew "update now" caller runs exactly the same fail-closed logic as the
- * scheduled sweep. Returns rather than throws so callers decide their own exit
- * timing (the periodic service exits immediately; an on-demand caller that must
- * respond to a client BEFORE exiting delays via {@link scheduleSelfUpdateExit}).
- * Concurrent callers share one in-flight attempt rather than racing separate
- * installs.
- */
 export declare function attemptSelfUpdateAndExit(ctx: DaemonContext, signal: AbortSignal, deps?: SelfUpdateDeps): Promise<SelfUpdateOutcome>;
-/**
- * Schedule the process exit for a verified self-update, exactly once, no
- * matter how many callers observe `outcome.updated` on the shared
- * `inFlightAttempt` promise. The periodic tick and an on-demand caller can both
- * be awaiting that SAME promise — if the tick's continuation ran an immediate
- * `process.exit(0)` while an on-demand caller's continuation had not yet flushed
- * its response to a client, the tick's exit could win the race and the client
- * would see a closed socket before any response (found in review, PHNX-3695).
- * Routing every caller through this one guarded, always-delayed scheduling point
- * means the delay protects EVERY caller's in-flight response.
- */
 export declare function scheduleSelfUpdateExit(): void;
-/**
- * Fire an on-demand self-update in the BACKGROUND and return its (bounded)
- * promise WITHOUT the caller having to await it — the reusable primitive for a
- * "update now" trigger that must respond to a client before the daemon exits.
- * Awaiting the full check→download→install→verify inline would park the caller
- * for tens of seconds (worst case ~15 min), the client-stall PHNX-3605 was
- * written to prevent; instead a trigger responds "triggered" immediately and
- * lets this run in the background — the daemon does install→verify→exit(0) on its
- * own, the OS supervisor relaunches it, and the client reconnects.
- *
- * (Its one former production caller was the `request-self-update` verb on the
- * daemon's browser IPC socket, removed with the standalone `browser` CLI in
- * PHNX-4101. The primitive stays — tested and reusable — for a future on-demand
- * trigger; the periodic tick does not use it, exiting inline instead.)
- *
- * The work still shares the module-level {@link attemptSelfUpdateAndExit}
- * `inFlightAttempt` guard, so a concurrent trigger (or the periodic tick) can't
- * race a second install into the same prefix. It is bounded by
- * {@link SELF_UPDATE_DEADLINE_MS} via an `AbortController` nobody awaits (the
- * timer is `unref`'d so it never keeps the daemon alive on its own and never
- * dangles in a test). Fail-closed is preserved end to end:
- * `runSelfUpdateAttempt` already turns an install/verify failure into a
- * not-updated outcome that leaves the running daemon untouched. The caller
- * schedules the one decoupled {@link scheduleSelfUpdateExit} off the returned
- * promise once `updated` is true, so the exit still fires after the caller's
- * response has flushed.
- */
 export declare function triggerSelfUpdateInBackground(ctx: DaemonContext, deps?: SelfUpdateDeps): Promise<SelfUpdateOutcome>;
-/**
- * The subset of self-update decline checks that are INSTANT and network-free —
- * a dev build, or a shadowed install. The on-demand IPC handler
- * (`request-self-update`) runs these SYNCHRONOUSLY so a version-skewed browser
- * client gets the PHNX-3605 "nothing changed, not evicting" advisory
- * immediately, instead of a "triggered" it would never act on. The remaining
- * checks (registry probe, already-current, install/verify) stay inside the
- * backgrounded {@link attemptSelfUpdateAndExit} so the handler never blocks on
- * the network or the install. This is the single source of the two instant
- * decline reasons — {@link runSelfUpdateAttempt} calls it too, so the on-demand
- * decline text can never drift from the periodic tick's. Returns the decline
- * reason, or `null` to proceed to the (backgrounded) install path.
- */
 export declare function selfUpdateSyncDeclineReason(deps?: SelfUpdateDeps): string | null;
 export declare class SelfUpdateService extends BasePeriodicService {
     readonly id: DaemonServiceId;
@@ -166,4 +35,5 @@ export declare class SelfUpdateService extends BasePeriodicService {
     protected onStop(): Promise<void>;
     protected onTick(ctx: DaemonContext, signal: AbortSignal): Promise<void>;
 }
+export declare function upgradeHostClis(ctx: DaemonContext, signal: AbortSignal, deadlineAt: number, cwd?: string): Promise<void>;
 export {};