@phnx-labs/agents-cli 1.22.112 → 1.22.114

package/dist/lib/daemon/daemon.js

@@ -1,3 +1,4 @@
+import { daemonProcessViewAllowed, recordDaemonProcessView } from '../session/process-view.js';
 /**
  * Daemon lifecycle management for the routines scheduler.
  *
@@ -22,7 +23,6 @@ import { detectOverdueJobs, notifyOverdue } from '../overdue.js';
 import { runCatchup } from '../catchup.js';
 import { notifyRoutineStart, notifyRoutineFinish, notifyRoutineStartFailed } from '../routine-notify.js';
 import { notifyOwnerRoutineFinish, notifyOwnerRoutineStartFailed } from '../routine-notify-owner.js';
-import { BrowserService } from '../browser/service.js';
 import { getSocketPath as getBrowserIpcSocketPath } from '../browser/ipc.js';
 import { redactSecrets } from '../redact.js';
 import { getAgentsBinPath, getCliLaunch, BUN_VIRTUAL_ROOT } from '../cli-entry.js';
@@ -30,27 +30,6 @@ import { localBinDir } from '../platform/posixpath.js';
 import { isSchedulerEnabled, assertSchedulerEnabled, isDaemonEnabled } from '../device-config.js';
 import { recordSubsystemOk, recordSubsystemError, recordSubsystemErrorReason, readSubsystemHealth, SUBSYSTEM_DAEMON_START } from '../daemon-health.js';
 import { ServiceSupervisor } from './supervisor.js';
-import { SessionIndexService } from './session-index-service.js';
-import { SessionSummarizerService } from './session-summarizer-service.js';
-import { SessionTitleService } from './session-title-service.js';
-import { MonitorEngineService } from './monitor-engine-service.js';
-import { AccountUsageService, AccountAuthService } from './account-state-daemon-service.js';
-import { CatchupService } from './catchup-service.js';
-import { BrowserIPCService } from './browser-ipc-service.js';
-import { WatchdogService } from './watchdog-service.js';
-import { DeviceProbeService } from './device-probe-service.js';
-import { SelfHealService } from './self-heal-service.js';
-import { SelfUpdateService } from './self-update-service.js';
-import { HarnessUpdateService } from './harness-update-service.js';
-import { AuthSyncService } from './auth-sync-service.js';
-import { UsageSyncService } from './usage-sync-service.js';
-import { StateDirCheckService } from './state-dir-check-service.js';
-import { SessionStateService } from './session-state-service.js';
-import { AttentionNotifyService } from './attention-notify-service.js';
-import { WebhookReceiverService } from './webhook-receiver-service.js';
-import { HeartbeatService } from './heartbeat-service.js';
-import { TmuxReapService } from './tmux-reap-service.js';
-import { BrowserTaskReapService } from './browser-task-reap-service.js';
 import { emit, emitAsync, emitRoutineEnd } from '../feed/events.js';
 import { readDaemonServicesConfig, drainDaemonServiceRestartQueue } from '../daemon-services.js';
 import { sleepSync } from '../fs-atomic.js';
@@ -478,6 +457,12 @@ export function isDaemonRunning() {
  * liveness check and the write.
  */
 export function claimDaemonInstance() {
+    // A nested caller cannot interpret legacy numeric lock/PID files. Authenticate
+    // before acquiring the lock (whose stale-PID cleanup itself mutates state).
+    if (!daemonProcessViewAllowed()) {
+        console.error('Daemon startup requires the owning process namespace. Automatic reuse of a private-container HOME across namespaces is unsupported; run in its owning namespace or use a fresh HOME.');
+        return false;
+    }
     // A stop owns this same lock through teardown. Waiting here is load-bearing:
     // returning false while stopDaemon() holds it lets this replacement exit 0,
     // then the stop completes with no singleton left alive. The bounded lifecycle
@@ -488,6 +473,10 @@ export function claimDaemonInstance() {
     if (!release)
         return false;
     try {
+        // Recheck under lifecycle serialization; invocation is not provenance.
+        if (!daemonProcessViewAllowed())
+            return false;
+        recordDaemonProcessView();
         // Do not overwrite a live-but-uninspectable owner. This is the non-
         // destructive side of the same fail-closed rule stopDaemon applies.
         if (unverifiedLiveDaemonPid() !== null)
@@ -887,6 +876,32 @@ export async function runDaemon() {
     // HOME override must refuse to run against the operator's real state rather than
     // schedule against the real host. No-op in production (the marker is never set).
     assertTestDaemonHome();
+    // Lifecycle readers and launchers do not run services. Load their code only
+    // in the daemon process, before it claims or publishes lifecycle state.
+    const [{ BrowserService }, { SessionIndexService }, { SessionSummarizerService }, { SessionTitleService }, { MonitorEngineService }, { AccountUsageService, AccountAuthService }, { CatchupService }, { BrowserIPCService }, { WatchdogService }, { DeviceProbeService }, { SelfHealService }, { SelfUpdateService }, { HarnessUpdateService }, { AuthSyncService }, { UsageSyncService }, { StateDirCheckService }, { SessionStateService }, { AttentionNotifyService }, { WebhookReceiverService }, { HeartbeatService }, { TmuxReapService }, { BrowserTaskReapService },] = await Promise.all([
+        import('../browser/service.js'),
+        import('./session-index-service.js'),
+        import('./session-summarizer-service.js'),
+        import('./session-title-service.js'),
+        import('./monitor-engine-service.js'),
+        import('./account-state-daemon-service.js'),
+        import('./catchup-service.js'),
+        import('./browser-ipc-service.js'),
+        import('./watchdog-service.js'),
+        import('./device-probe-service.js'),
+        import('./self-heal-service.js'),
+        import('./self-update-service.js'),
+        import('./harness-update-service.js'),
+        import('./auth-sync-service.js'),
+        import('./usage-sync-service.js'),
+        import('./state-dir-check-service.js'),
+        import('./session-state-service.js'),
+        import('./attention-notify-service.js'),
+        import('./webhook-receiver-service.js'),
+        import('./heartbeat-service.js'),
+        import('./tmux-reap-service.js'),
+        import('./browser-task-reap-service.js'),
+    ]);
     // Install the shared-daemon reload signal boundary BEFORE publishing our PID
     // in claimDaemonInstance(). Browser/routines clients use that PID to decide a
     // daemon exists and may request a service reload immediately. POSIX otherwise
@@ -1211,7 +1226,7 @@ export async function runDaemon() {
             }
             catch { /* best-effort */ }
             // RUSH-2288: the pre-spawn failure (e.g. auth_failed) is exactly the one the
-            // per-routine `agents notify` prompt can never send — its agent never ran —
+            // per-routine `agents send --to owner` prompt can never send — its agent never ran —
             // so the daemon reaches the owner directly.
             void notifyOwnerRoutineStartFailed(config, message)
                 .then((r) => {
@@ -1739,6 +1754,10 @@ function assertDaemonLaunchHomeAllowed() {
 }
 /** Start the daemon via launchd, systemd, or as a detached process. */
 export function startDaemon(agentsBin) {
+    // The public launcher must obey the same namespace boundary as its child:
+    // even probing/repairing legacy PID state or pruning a lock can mutate it.
+    if (!daemonProcessViewAllowed())
+        throw new Error('Daemon startup requires the owning process namespace. Automatic reuse of a private-container HOME across namespaces is unsupported; run in its owning namespace or use a fresh HOME.');
     if (isDaemonRunning()) {
         const pid = readDaemonPid();
         return { pid, method: 'already-running' };

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

@@ -33,24 +33,7 @@
  */
 import { BasePeriodicService, type DaemonContext } from './service.js';
 import type { DaemonServiceId } from '../daemon-services.js';
-/**
- * Cancellation deadline per tick. A real pass can touch several installations, each an npm
- * install (`INSTALL_TIMEOUT_MS` = 120s in strategies.ts) plus two launch
- * probes; 10 minutes leaves headroom for a handful of harnesses in one pass
- * while staying comfortably under the 15-minute cadence above.
- */
-export declare const HARNESS_UPDATE_DEADLINE_MS: number;
-/**
- * How long to wait for the child to exit AFTER a cooperative cancel before
- * force-reaping it as an orphan backstop. The child's own work is bounded — one
- * npm install (`INSTALL_TIMEOUT_MS` = 120s in strategies.ts) plus two launch
- * probes, then a fast synchronous swap — so a healthy child stops well within
- * this window. A slow staging/postinstall can also exhaust it, but a delivered
- * cancel prevents that stage from committing. The backstop kills the process
- * group on POSIX and the worker on Windows; the tick reports a failure.
- */
-export declare const HARNESS_UPDATE_CANCEL_GRACE_MS: number;
-export interface HarnessUpdateOutcome {
+interface HarnessUpdateOutcome {
     ran: boolean;
     reason?: string;
     exitCode?: number | null;
@@ -72,7 +55,6 @@ export interface CooperativeChildResult {
 export interface HarnessUpdateDeps {
     runAutoUpdatePass(signal: AbortSignal): Promise<CooperativeChildResult>;
 }
-export declare function defaultHarnessUpdateDeps(): HarnessUpdateDeps;
 /**
  * Spawn `command args` as a child over a Node IPC channel and drive it to a TRUE
  * completion, requesting a cooperative stop (never a kill) when `signal` aborts —
@@ -108,3 +90,4 @@ export declare class HarnessUpdateService extends BasePeriodicService {
     protected onStop(): Promise<void>;
     protected onTick(ctx: DaemonContext, signal: AbortSignal): Promise<void>;
 }
+export {};

package/dist/lib/daemon/harness-update-service.js

@@ -43,7 +43,7 @@ const HARNESS_UPDATE_TICK_MS = 15 * 60_000;
  * probes; 10 minutes leaves headroom for a handful of harnesses in one pass
  * while staying comfortably under the 15-minute cadence above.
  */
-export const HARNESS_UPDATE_DEADLINE_MS = 10 * 60_000;
+const HARNESS_UPDATE_DEADLINE_MS = 10 * 60_000;
 /** First tick fires 60 seconds after daemon boot — long enough for shims/PATH to settle, short enough that a fresh box doesn't wait a full interval for its first check. */
 const HARNESS_UPDATE_STARTUP_DELAY_MS = 60_000;
 /**
@@ -55,8 +55,8 @@ const HARNESS_UPDATE_STARTUP_DELAY_MS = 60_000;
  * cancel prevents that stage from committing. The backstop kills the process
  * group on POSIX and the worker on Windows; the tick reports a failure.
  */
-export const HARNESS_UPDATE_CANCEL_GRACE_MS = 3 * 60_000;
-export function defaultHarnessUpdateDeps() {
+const HARNESS_UPDATE_CANCEL_GRACE_MS = 3 * 60_000;
+function defaultHarnessUpdateDeps() {
     return {
         runAutoUpdatePass(signal) {
             const { command, args } = getCliLaunch([HARNESS_UPDATE_CHILD_CMD], getAgentsBinPath());

package/dist/lib/daemon/runner.d.ts

@@ -54,7 +54,7 @@ export declare function activeRunSkipStreak(runs: RunMeta[]): number;
  */
 export declare function launcherClaimPid(): number | null;
 /** How a routine attempt was triggered, plus the schedule slot it belongs to. */
-export interface RoutineTrigger {
+interface RoutineTrigger {
     kind: NonNullable<RunMeta['triggerKind']>;
     /** UTC fire time for a schedule/catchup attempt; keys the single-fire slot claim. */
     scheduledFor?: Date | string;
@@ -103,7 +103,7 @@ export declare function buildJobCommand(config: JobConfig, resolvedPrompt: strin
 export declare function snapshotRoutineTranscriptBase(meta: Pick<RunMeta, 'jobName' | 'agent' | 'version'>, runDir: string, overlayHome?: string): void;
 export declare function archiveRoutineTranscripts(meta: Pick<RunMeta, 'jobName' | 'runId' | 'agent' | 'version'>, runDir: string, overlayHome?: string): void;
 /** Pre-flight version/account selection for a routine job. */
-export interface RoutineLaunchPlan {
+interface RoutineLaunchPlan {
     /** Ordered attempts: primary first, then same-agent failover accounts. */
     chain: FallbackEntry[];
     /** Full rotation result when strategy selected among healthy accounts; null when pinned. */
@@ -219,7 +219,7 @@ declare function executeJobOnHost(config: JobConfig, opts: {
  * observes the live running→terminal transition (the monitor tick would already
  * see a finalized record and skip it). Never let a hook throw into finalization.
  */
-export interface RoutineHooks {
+interface RoutineHooks {
     /** Called once with the finalized meta when the run reaches a terminal state. */
     onFinish?: (meta: RunMeta) => void;
 }

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

@@ -35,16 +35,7 @@
  */
 import { BasePeriodicService, type DaemonContext } from './service.js';
 import type { DaemonServiceId } from '../daemon-services.js';
-/**
- * Hard cap per tick: a real download + npm/bun install + verify can
- * legitimately take minutes on a slow link. 15 minutes matches the task's
- * stated budget and is short relative to the ~75min cadence. Exported so the
- * on-demand `request-self-update` IPC handler (`browser/ipc.ts`) can bound
- * its own `AbortController` on the SAME budget the periodic tick runs under —
- * one deadline, not two independently-tuned numbers that could drift apart.
- */
-export declare const SELF_UPDATE_DEADLINE_MS: number;
-export interface SelfUpdateOutcome {
+interface SelfUpdateOutcome {
     updated: boolean;
     reason?: string;
 }
@@ -75,7 +66,6 @@ export interface SelfUpdateDeps {
     syncSystemRepo(): Promise<void>;
     syncLocal(): Promise<void>;
 }
-export declare function fetchLatestNpmMetadata(signal: AbortSignal): Promise<NpmLatestMetadata>;
 /**
  * Install + byte-verify `metadata` into `packageRoot`'s install, exactly the
  * sequence `bootstrap.ts`'s `installResolvedPackage` runs for `agents
@@ -101,7 +91,6 @@ export declare function fetchLatestNpmMetadata(signal: AbortSignal): Promise<Npm
  * it's guarding (found in review, PHNX-3695).
  */
 export declare function installAndVerifyDefault(metadata: NpmLatestMetadata, packageRoot: string, signal: AbortSignal): Promise<void>;
-export declare function defaultSelfUpdateDeps(): SelfUpdateDeps;
 /**
  * Core self-update decision + action, shared by the periodic tick
  * ({@link SelfUpdateService.onTick}) and the on-demand IPC path
@@ -167,10 +156,6 @@ export declare function triggerSelfUpdateInBackground(ctx: DaemonContext, deps?:
  * reason, or `null` to proceed to the (backgrounded) install path.
  */
 export declare function selfUpdateSyncDeclineReason(deps?: SelfUpdateDeps): string | null;
-export declare const DEV_BUILD_DECLINE = "dev build \u2014 self-update is a no-op";
-export declare const SHADOW_DECLINE = "another agents binary shadows this install \u2014 self-update is a no-op";
-/** True when the package on disk is a strictly newer release than the one this process booted with. */
-export declare function installedIsNewerThanRunning(installed: string, running: string): boolean;
 export declare class SelfUpdateService extends BasePeriodicService {
     readonly id: DaemonServiceId;
     readonly intervalMs: number;

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

@@ -56,7 +56,7 @@ const SELF_UPDATE_TICK_MS = 75 * 60_000;
  * its own `AbortController` on the SAME budget the periodic tick runs under —
  * one deadline, not two independently-tuned numbers that could drift apart.
  */
-export const SELF_UPDATE_DEADLINE_MS = 15 * 60_000;
+const SELF_UPDATE_DEADLINE_MS = 15 * 60_000;
 /**
  * First tick fires 5 minutes after daemon boot — deliberately longer than
  * self-heal's 30s stagger (`self-heal-service.ts`): self-heal repairs local
@@ -67,7 +67,7 @@ export const SELF_UPDATE_DEADLINE_MS = 15 * 60_000;
  * a restart). Every later tick still fires on the normal cadence.
  */
 const SELF_UPDATE_STARTUP_DELAY_MS = 5 * 60_000;
-export async function fetchLatestNpmMetadata(signal) {
+async function fetchLatestNpmMetadata(signal) {
     const response = await fetch(`https://registry.npmjs.org/${NPM_PACKAGE_NAME}/latest`, { signal });
     if (!response.ok) {
         throw new Error(`registry.npmjs.org responded ${response.status}`);
@@ -148,7 +148,7 @@ export async function installAndVerifyDefault(metadata, packageRoot, signal) {
         }
     }
 }
-export function defaultSelfUpdateDeps() {
+function defaultSelfUpdateDeps() {
     return {
         currentVersion: () => getCliVersion(),
         installedVersion: () => getCliVersionFresh(),
@@ -362,10 +362,10 @@ export function selfUpdateSyncDeclineReason(deps = defaultSelfUpdateDeps()) {
     }
     return null;
 }
-export const DEV_BUILD_DECLINE = 'dev build — self-update is a no-op';
-export const SHADOW_DECLINE = 'another agents binary shadows this install — self-update is a no-op';
+const DEV_BUILD_DECLINE = 'dev build — self-update is a no-op';
+const SHADOW_DECLINE = 'another agents binary shadows this install — self-update is a no-op';
 /** True when the package on disk is a strictly newer release than the one this process booted with. */
-export function installedIsNewerThanRunning(installed, running) {
+function installedIsNewerThanRunning(installed, running) {
     if (installed === 'unknown' || running === 'unknown')
         return false;
     return compareVersions(installed, running) > 0;

package/dist/lib/daemon/state-dir-check-service.d.ts

@@ -24,7 +24,7 @@
  */
 import { BasePeriodicService, type DaemonContext } from './service.js';
 import type { DaemonServiceId } from '../daemon-services.js';
-export interface StateDirCheckServiceOptions {
+interface StateDirCheckServiceOptions {
     lifetimePath: string;
     lifetimeToken: string;
     onMissing: () => void;
@@ -41,3 +41,4 @@ export declare class StateDirCheckService extends BasePeriodicService {
     protected onStop(): Promise<void>;
     protected onTick(ctx: DaemonContext): Promise<void>;
 }
+export {};

package/dist/lib/daemon/supervisor.d.ts

@@ -32,7 +32,7 @@
  */
 import type { DaemonServiceId } from '../daemon-services.js';
 import type { DaemonContext, DaemonService, ServiceHealth } from './service.js';
-export interface ServiceSupervisorOptions {
+interface ServiceSupervisorOptions {
     /** Consecutive thrown tick failures before a service is parked. Deadline breaches park immediately. Default 3. */
     parkAfterFailures?: number;
     /** First restart backoff delay, doubled on each further failed restart attempt. Default 5s. */
@@ -48,7 +48,7 @@ export interface ServiceSupervisorOptions {
      */
     lifecycleDeadlineMs?: number;
 }
-export interface RegisterServiceOptions {
+interface RegisterServiceOptions {
     /** Register the lifecycle owner but leave it stopped until a live enable. */
     enabled?: boolean;
 }
@@ -135,3 +135,4 @@ export declare class ServiceSupervisor {
     private recordFailure;
     private finishTick;
 }
+export {};

package/dist/lib/daemon/testdata/process-view-daemon.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/daemon/testdata/process-view-daemon.js

@@ -0,0 +1,14 @@
+// Runs the production daemon entrypoint against an isolated HOME. No installed
+// CLI, service manager, scheduler, or production socket participates.
+import { runDaemon, startDaemon } from '../daemon.js';
+if (process.argv[2] === '__start-daemon') {
+    try {
+        startDaemon();
+    }
+    catch (error) {
+        console.log(error.message);
+        process.exitCode = 2;
+    }
+}
+else
+    await runDaemon();

package/dist/lib/daemon/testdata/process-view-start.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/daemon/testdata/process-view-start.js

@@ -0,0 +1,43 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import net from 'node:net';
+import { spawn } from 'node:child_process';
+import { serviceManagerRegistrationAllowed } from '../../service-manifest.js';
+import { startDaemon, stopDaemon } from '../daemon.js';
+import { getDaemonDir, getTerminalsDir, getCacheDir } from '../../state.js';
+// Tripwire precedes ALL lifecycle calls. Some older Bun versions return HOME
+// from os.userInfo(), which would incorrectly allow the real service manager.
+assert.equal(serviceManagerRegistrationAllowed().allowed, false, 'isolated fixture must never access the production service manager');
+const cold = process.argv[3] === 'cold';
+const child = cold ? spawn('bun', [process.argv[4], '__daemon-run'], { stdio: 'ignore', env: process.env }) : undefined;
+const started = child ? { pid: child.pid, method: 'detached' } : startDaemon(process.argv[2]);
+assert.equal(started.method, 'detached');
+assert.ok(started.pid);
+fs.writeFileSync(path.join(process.env.HOME, 'test-child.pid'), String(started.pid));
+try {
+    if (!cold)
+        assert.ok(fs.existsSync(path.join(getDaemonDir(), 'health.json')), 'ordinary launcher publishes health before daemon starts');
+    const socket = path.join(getCacheDir(), 'helpers', 'browser', 'browser.sock');
+    let ready = false;
+    for (let i = 0; i < 80 && !ready; i++) {
+        ready = await new Promise(resolve => {
+            const client = net.createConnection(socket);
+            const done = (value) => { client.destroy(); resolve(value); };
+            client.setTimeout(100, () => done(false));
+            client.once('connect', () => done(true));
+            client.once('error', () => done(false));
+        });
+        if (!ready)
+            await new Promise(resolve => setTimeout(resolve, 100));
+    }
+    assert.ok(ready, 'ordinary fresh-home daemon must serve its actual browser socket');
+    assert.equal(fs.readFileSync(path.join(getDaemonDir(), 'daemon.pid'), 'utf8').trim(), String(started.pid));
+    const owner = JSON.parse(fs.readFileSync(path.join(getTerminalsDir(), 'process-view.json'), 'utf8'));
+    assert.equal(owner.pidNamespace, fs.readlinkSync('/proc/self/ns/pid'));
+    assert.equal(owner.bootId, fs.readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim());
+    console.log(`${cold ? 'cold runDaemon' : 'ordinary startDaemon: health published'}; canonical socket ready; namespace owner verified`);
+}
+finally {
+    stopDaemon();
+}

package/dist/lib/daemon-services.d.ts

@@ -9,7 +9,7 @@
 /** Every service the daemon can host. IDs are kebab-case and stable. */
 export type DaemonServiceId = 'scheduler' | 'catchup' | 'monitors' | 'browser-ipc' | 'webhook-receiver' | 'self-heal' | 'self-update' | 'account-state' | 'account-auth' | 'watchdog' | 'device-probe' | 'state-dir-check' | 'session-index' | 'session-title' | 'auth-sync' | 'usage-sync' | 'daemon-heartbeat' | 'tmux-reap' | 'browser-task-reap' | 'session-state' | 'session-summarizer' | 'attention-notify' | 'harness-update';
 /** Human-readable metadata for each service. */
-export interface DaemonServiceDef {
+interface DaemonServiceDef {
     id: DaemonServiceId;
     title: string;
     description: string;
@@ -55,3 +55,4 @@ export declare function queueDaemonServiceRestart(id: DaemonServiceId): void;
  * daemon; never throws. Clears the file so a request is applied at most once.
  */
 export declare function drainDaemonServiceRestartQueue(): DaemonServiceId[];
+export {};

package/dist/lib/daemon-webhooks.d.ts

@@ -35,7 +35,7 @@ export interface HostedReceiverConfig {
     /** Public Funnel exposure; omit to bind localhost only. */
     funnel?: HostedReceiverFunnel;
 }
-export interface DaemonWebhooksConfig {
+interface DaemonWebhooksConfig {
     receivers: HostedReceiverConfig[];
 }
 /** Path to `~/.agents/daemon/webhooks.yaml`. */

package/dist/lib/deeplink/register.d.ts

@@ -1,6 +1,5 @@
 export declare const AGENTS_URL_SCHEME = "agents";
-export declare const MAC_BUNDLE_ID = "dev.agents.urlhandler";
-export interface SchemeStatus {
+interface SchemeStatus {
     registered: boolean;
     platform: NodeJS.Platform;
     /** One human line: where the handler is, or why it is not registered. */
@@ -11,15 +10,6 @@ export interface SchemeStatus {
  * out of the handler command.
  */
 export declare function shQuote(p: string): string;
-/**
- * Resolve how the OS handler should invoke this CLI, as an already-quoted
- * command prefix (without the `open <url>` suffix).
- *
- * A macOS GUI app does NOT inherit the shell PATH, so the handler must use an
- * absolute path. Prefer the `agents` shim on PATH (directly executable); fall
- * back to `<node> <entry>` for a bare JS install.
- */
-export declare function resolveAgentsInvocation(platform?: NodeJS.Platform): string;
 /** The freedesktop `.desktop` entry that claims `x-scheme-handler/agents`. */
 export declare function linuxDesktopEntry(invocation: string): string;
 /**
@@ -33,10 +23,9 @@ export declare function macPlistBuddyCommands(plistPath: string): string[][];
 /** `reg add` argv lists that register the scheme under HKCU on Windows. */
 export declare function windowsRegistryCommands(invocation: string): string[][];
 export declare function linuxDesktopPath(home?: string): string;
-export declare function macAppPath(home?: string): string;
 /** Whether the handler artifact exists on disk (a cheap, side-effect-free check). */
 export declare function agentsUrlSchemeStatus(platform?: NodeJS.Platform, home?: string): SchemeStatus;
-export interface RegisterOptions {
+interface RegisterOptions {
     platform?: NodeJS.Platform;
     home?: string;
     /** Skip if already present (used by best-effort callers like setup). */
@@ -47,3 +36,4 @@ export declare function unregisterAgentsUrlScheme(opts?: {
     platform?: NodeJS.Platform;
     home?: string;
 }): SchemeStatus;
+export {};

package/dist/lib/deeplink/register.js

@@ -23,7 +23,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { getAgentsBinPath } from '../cli-entry.js';
 export const AGENTS_URL_SCHEME = 'agents';
-export const MAC_BUNDLE_ID = 'dev.agents.urlhandler';
+const MAC_BUNDLE_ID = 'dev.agents.urlhandler';
 const LINUX_DESKTOP_FILE = 'agents-url-handler.desktop';
 const MAC_APP_NAME = 'AgentsURLHandler.app';
 // ---------------------------------------------------------------------------
@@ -44,7 +44,7 @@ export function shQuote(p) {
  * absolute path. Prefer the `agents` shim on PATH (directly executable); fall
  * back to `<node> <entry>` for a bare JS install.
  */
-export function resolveAgentsInvocation(platform = os.platform()) {
+function resolveAgentsInvocation(platform = os.platform()) {
     const onPath = whichAgents(platform);
     if (onPath)
         return platform === 'win32' ? `"${onPath}"` : shQuote(onPath);
@@ -123,7 +123,7 @@ export function windowsRegistryCommands(invocation) {
 export function linuxDesktopPath(home = os.homedir()) {
     return path.join(home, '.local', 'share', 'applications', LINUX_DESKTOP_FILE);
 }
-export function macAppPath(home = os.homedir()) {
+function macAppPath(home = os.homedir()) {
     return path.join(home, 'Applications', MAC_APP_NAME);
 }
 // ---------------------------------------------------------------------------

package/dist/lib/deeplink/url.d.ts

@@ -16,14 +16,14 @@
  *   agents://session/<id>              — resume <id>, owner host resolved from the id
  *   agents://session/<id>?host=<name>  — the same, with a routing hint
  */
-export interface AgentsSessionLink {
+interface AgentsSessionLink {
     kind: 'session';
     /** The session id (or short-id/alias) to resume. */
     id: string;
     /** Optional owning-host hint; resume self-resolves the owner from the id regardless. */
     host?: string;
 }
-export interface AgentsUrlError {
+interface AgentsUrlError {
     error: string;
 }
 export declare function isDeepLinkSessionId(raw: string): boolean;
@@ -32,3 +32,4 @@ export declare function isDeepLinkSessionId(raw: string): boolean;
  * {@link AgentsUrlError} with a human reason. Never throws.
  */
 export declare function parseAgentsUrl(input: string): AgentsSessionLink | AgentsUrlError;
+export {};

package/dist/lib/device-config.d.ts

@@ -44,7 +44,7 @@ export type ConfigScope = 'user' | 'device';
  */
 export type ConfigVisibility = 'shared' | 'machine';
 /** Value type of a config key — drives validation and `--json` rendering. */
-export type ConfigType = 'string' | 'int' | 'bool' | 'string-list';
+type ConfigType = 'string' | 'int' | 'bool' | 'string-list';
 /** Fields every key carries, regardless of scope. */
 interface ConfigKeySpecBase {
     /** CLI dotted name, e.g. `interactive.host`. */
@@ -81,7 +81,7 @@ export interface ConfigEntry {
     source: ConfigSource;
 }
 /** Options scoping a read/write: a specific device (default: this machine), or the fleet-defaults layer. */
-export interface ConfigTarget {
+interface ConfigTarget {
     device?: string;
     /** Write/read the fleet-wide defaults layer (central fleet.defaults.config). */
     fleet?: boolean;
@@ -92,16 +92,8 @@ declare const DEVICE_ROLES: readonly ["worker", "personal", "desktop"];
 declare const AUTO_POOL_MODES: readonly ["workers", "all"];
 export declare const CONFIG_KEYS: readonly ConfigKeySpec[];
 export declare function configKeySpec(name: string): ConfigKeySpec;
-/**
- * Fold the legacy config/pins stores into the current layout, once per
- * process. A failure is loud but non-fatal — config reads must keep working,
- * and the next process retries the fold. Honors AGENTS_SKIP_MIGRATION=1, the
- * same gate bootstrap's runMigration uses (tests pin it so a fork never folds
- * the developer's real ~/.agents as a side effect).
- */
-export declare function ensureDeviceConfigMigrated(): void;
-/** The fleet-defaults config layer (central `fleet.defaults.config`; {} when unset). */
-export declare function readFleetConfigDefaults(): Record<string, unknown>;
+/** Throw when `value` does not match the key's declared type or validation. */
+export declare function assertValidValue(spec: ConfigKeySpec, value: unknown): void;
 /**
  * The effective device-scope config block for `device`: fleet.defaults.config
  * overlaid with the per-device doc's config:. This is the single read path
@@ -130,9 +122,6 @@ export declare function getConfigValueAsync(name: string, opts?: ConfigTarget):
  * must not hard-fail. Asking for such a key by name still errors.
  */
 export declare function listConfig(opts?: ConfigTarget): ConfigEntry[];
-/** List user-scope config keys with their values. Used to show inherited settings
- * in per-device views without implying those keys are device-local. */
-export declare function listUserConfig(): ConfigEntry[];
 /**
  * Set a config key (validated). Device-scope keys target this machine unless
  * `opts.device` names a peer; `opts.fleet` writes the fleet-wide defaults layer