@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/summarizer/summarize.d.ts

@@ -1,39 +1,13 @@
-/**
- * The one model call behind the session summarizer (PHNX-3939).
- *
- * A pure boundary: given the session's first user turn (the goal source) and its
- * live progress (todos / plan / phase off the state engine), it asks a local
- * Anthropic-wire endpoint (Ollama / vLLM / LiteLLM) for a strict JSON
- * `{goal, checkpoints, checklist}`
- * and validates the shape. On ANY failure — network, non-2xx, non-JSON, wrong
- * shape — it returns `undefined`, and the caller records `summaryState: 'skipped'`.
- *
- * NEVER called on the request path: only the background SessionSummarizerService
- * invokes it, debounced and reader-gated.
- */
-import type { TodoProgress } from '../session/types.js';
-/** Live progress fed to the model alongside the goal-bearing prompt. */
+import type { TodoProgress } from '@phnx-labs/sessions-cli/reader';
 interface SummarizeProgress {
-    /** Latest checklist write (TodoWrite / update_plan), when the session has one. */
     todos?: TodoProgress;
-    /** Plan markdown from the last ExitPlanMode, when present. */
     plan?: string;
-    /** Coarse lifecycle phase (running / waiting / idle / …), when known. */
     phase?: string;
-    /**
-     * The agent's own narration headlines, oldest first — the last K steps the
-     * daemon's timeline fold produced (PHNX-3939). Optional: many sessions never
-     * write a checklist, so this is often the only evidence of progress the model
-     * gets, but a row with no folded timeline simply passes none.
-     */
     steps?: string[];
 }
-/** The validated model output. `at` timestamps are stamped by the caller. */
 interface SummarizeResult {
     goal: string;
-    /** Progress checkpoints, newest last (short lines). */
     checkpoints: string[];
-    /** Detailed checklist. */
     checklist: {
         text: string;
         done: boolean;
@@ -43,34 +17,12 @@ interface SummarizeOptions {
     baseUrl: string;
     model: string;
     maxTokens?: number;
-    /**
-     * API key for the endpoint. Deliberately NOT resolved from `ANTHROPIC_API_KEY`:
-     * the summarizer targets an operator-configured local/remote endpoint
-     * (Ollama/vLLM/LiteLLM) that typically ignores the key, so forwarding the real
-     * Anthropic credential there would leak it. Only an explicit
-     * `AGENTS_SUMMARIZER_API_KEY` (or this option) is ever sent; otherwise the
-     * header is empty.
-     */
     apiKey?: string;
-    /** Injectable for tests; defaults to the global fetch. */
     fetchImpl?: typeof fetch;
-    /** Abort the request when the daemon tick's deadline elapses. */
     signal?: AbortSignal;
 }
-/** Compose the user message from the goal-bearing prompt and the live progress. */
 export declare function buildSummarizeUserMessage(prompt: string, progress: SummarizeProgress): string;
-/**
- * Coerce an untrusted parsed object into a {@link SummarizeResult}, or undefined
- * when the shape is wrong. Extra/missing optional arrays degrade to `[]` rather
- * than failing, but a non-string goal is a hard reject — a summary with no goal
- * is not a summary.
- */
 export declare function validateSummarizeResult(parsed: unknown): SummarizeResult | undefined;
-/** Strip ``` fences and pull the first {...} block so a chatty model still parses. */
 export declare function extractJsonObject(text: string): string | undefined;
-/**
- * Run one summarization. Returns the validated result, or `undefined` on any
- * failure (the caller then marks the session `summaryState: 'skipped'`).
- */
 export declare function summarize(prompt: string, progress: SummarizeProgress, opts: SummarizeOptions): Promise<SummarizeResult | undefined>;
 export {};

package/dist/lib/summarizer/summarize.js

@@ -1,23 +1,3 @@
-/**
- * The one model call behind the session summarizer (PHNX-3939).
- *
- * A pure boundary: given the session's first user turn (the goal source) and its
- * live progress (todos / plan / phase off the state engine), it asks a local
- * Anthropic-wire endpoint (Ollama / vLLM / LiteLLM) for a strict JSON
- * `{goal, checkpoints, checklist}`
- * and validates the shape. On ANY failure — network, non-2xx, non-JSON, wrong
- * shape — it returns `undefined`, and the caller records `summaryState: 'skipped'`.
- *
- * NEVER called on the request path: only the background SessionSummarizerService
- * invokes it, debounced and reader-gated.
- */
-/**
- * The `anthropic-version` header this request sends. Declared here because this
- * is now its only caller: it used to be imported from the computer subsystem's
- * model client, which left with the standalone `computer` engine (PHNX-4075).
- * A shared constants module for one string used in one request would be more
- * indirection than the string.
- */
 const ANTHROPIC_VERSION = '2023-06-01';
 const SYSTEM_PROMPT = [
     'You summarize a coding-agent session for an operator dashboard.',
@@ -28,7 +8,6 @@ const SYSTEM_PROMPT = [
     '- checklist: the detailed steps to finish the goal, each with a done flag; [] if unknown.',
     'Do not invent progress that is not evidenced by the provided context.',
 ].join('\n');
-/** Compose the user message from the goal-bearing prompt and the live progress. */
 export function buildSummarizeUserMessage(prompt, progress) {
     const parts = [`USER REQUEST:\n${prompt.trim()}`];
     if (progress.phase)
@@ -44,12 +23,6 @@ export function buildSummarizeUserMessage(prompt, progress) {
     }
     return parts.join('\n\n');
 }
-/**
- * Coerce an untrusted parsed object into a {@link SummarizeResult}, or undefined
- * when the shape is wrong. Extra/missing optional arrays degrade to `[]` rather
- * than failing, but a non-string goal is a hard reject — a summary with no goal
- * is not a summary.
- */
 export function validateSummarizeResult(parsed) {
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
         return undefined;
@@ -67,7 +40,6 @@ export function validateSummarizeResult(parsed) {
         : [];
     return { goal: obj.goal.trim(), checkpoints, checklist };
 }
-/** Extract the assistant text from an Anthropic Messages response body. */
 function textFromBody(body) {
     const content = body.content;
     if (!Array.isArray(content))
@@ -78,7 +50,6 @@ function textFromBody(body) {
         .map((b) => b.text)
         .join('');
 }
-/** Strip ``` fences and pull the first {...} block so a chatty model still parses. */
 export function extractJsonObject(text) {
     const unfenced = text.replace(/```(?:json)?/gi, '').trim();
     const start = unfenced.indexOf('{');
@@ -87,17 +58,11 @@ export function extractJsonObject(text) {
         return undefined;
     return unfenced.slice(start, end + 1);
 }
-/**
- * Run one summarization. Returns the validated result, or `undefined` on any
- * failure (the caller then marks the session `summaryState: 'skipped'`).
- */
 export async function summarize(prompt, progress, opts) {
     if (!prompt.trim())
         return undefined;
     const baseUrl = opts.baseUrl.replace(/\/+$/, '');
     const doFetch = opts.fetchImpl ?? fetch;
-    // Only an explicit summarizer key is ever forwarded — never the ambient
-    // ANTHROPIC_API_KEY, which would leak to the operator's local endpoint.
     const apiKey = opts.apiKey ?? process.env.AGENTS_SUMMARIZER_API_KEY ?? '';
     try {
         const res = await doFetch(`${baseUrl}/v1/messages`, {

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

@@ -1,28 +1,12 @@
-/** The current variable for transport/sync passphrases. */
 export declare const SYNC_PASSPHRASE_ENV = "AGENTS_SYNC_PASSPHRASE";
-/** The file-store master key, honoured for sync only as a deprecated fallback. */
 export declare const LEGACY_PASSPHRASE_ENV = "AGENTS_SECRETS_PASSPHRASE";
-/** Reset the one-shot warning latches. Tests only — production never re-warns. */
 export declare function resetSyncPassphraseWarnings(): void;
-/** Where a resolved sync passphrase came from, so callers can report honestly. */
 type SyncPassphraseSource = 'sync-env' | 'legacy-env' | null;
 interface ResolvedSyncPassphrase {
     value: string | null;
     source: SyncPassphraseSource;
 }
-/**
- * Read the transport passphrase from the environment, preferring the current
- * variable and falling back to the deprecated one with a single warning.
- * Returns `{ value: null }` when neither is set — the caller decides whether to
- * prompt (TTY) or fail (headless). Never prompts, never throws.
- */
 export declare function resolveSyncPassphraseFromEnv(): ResolvedSyncPassphrase;
-/**
- * The one-shot reminder that an env-sourced passphrase is readable by other
- * same-user processes. Separate from the deprecation notice above so a caller
- * using the CURRENT variable still gets the readability warning exactly once.
- */
 export declare function warnEnvPassphraseReadableOnce(): void;
-/** The message a headless caller shows when no passphrase is available. */
 export declare function missingSyncPassphraseMessage(): string;
 export {};

package/dist/lib/sync-passphrase.js

@@ -1,3 +1,4 @@
+// Sync transport passphrases are distinct from the file-store master key; the latter is deprecated fallback only.
 /**
  * The passphrase that seals a bundle for TRANSPORT — `secrets push`/`pull` and
  * the portable `export --to-file` / `import --from-file` envelope.
@@ -23,26 +24,14 @@
  * across the upgrade; it is not a second supported spelling.
  */
 import chalk from 'chalk';
-/** The current variable for transport/sync passphrases. */
 export const SYNC_PASSPHRASE_ENV = 'AGENTS_SYNC_PASSPHRASE';
-/** The file-store master key, honoured for sync only as a deprecated fallback. */
 export const LEGACY_PASSPHRASE_ENV = 'AGENTS_SECRETS_PASSPHRASE';
-/** Warn at most once per process: a `--all` push over many bundles must not
- *  flood stderr with the same notice. */
 let deprecatedVarWarned = false;
-/** Same, for the "this came from an env var at all" readability notice. */
 let envPassphraseWarned = false;
-/** Reset the one-shot warning latches. Tests only — production never re-warns. */
 export function resetSyncPassphraseWarnings() {
     deprecatedVarWarned = false;
     envPassphraseWarned = false;
 }
-/**
- * Read the transport passphrase from the environment, preferring the current
- * variable and falling back to the deprecated one with a single warning.
- * Returns `{ value: null }` when neither is set — the caller decides whether to
- * prompt (TTY) or fail (headless). Never prompts, never throws.
- */
 export function resolveSyncPassphraseFromEnv() {
     const current = process.env[SYNC_PASSPHRASE_ENV];
     if (current)
@@ -60,11 +49,6 @@ export function resolveSyncPassphraseFromEnv() {
     }
     return { value: null, source: null };
 }
-/**
- * The one-shot reminder that an env-sourced passphrase is readable by other
- * same-user processes. Separate from the deprecation notice above so a caller
- * using the CURRENT variable still gets the readability warning exactly once.
- */
 export function warnEnvPassphraseReadableOnce() {
     if (envPassphraseWarned)
         return;
@@ -72,7 +56,6 @@ export function warnEnvPassphraseReadableOnce() {
     process.stderr.write(chalk.yellow('warn: using a sync passphrase from the environment. Env vars are readable by other ' +
         'same-user processes (/proc, ps, crash dumps, CI logs) — rotate after CI use.\n'));
 }
-/** The message a headless caller shows when no passphrase is available. */
 export function missingSyncPassphraseMessage() {
     return `A sync passphrase is required. Run from a TTY, or set ${SYNC_PASSPHRASE_ENV}.`;
 }

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

@@ -1,33 +1,6 @@
-/**
- * Unified sync-status engine — the SINGLE source of truth for "is this resource
- * synced to this agent version?" consumed by `agents doctor`, `agents view`, the
- * menu-bar app, and any Agency surface.
- *
- * Why this exists: before this module there were four different notions of
- * "synced" living in four files:
- *   - doctor:  isStale() vs .sync-manifest.json  — catches SOURCE drift only.
- *   - view:    git working-tree state of ~/.agents/ — a resource can show green
- *              while its installed copy is stale/deleted/corrupted (false positive).
- *   - lists:   file-exists-in-home — never reports content drift at all.
- *   - menubar: read doctor --json (so it inherited doctor's source-only blind spot).
- *
- * The reliable signal is diffVersionResources() (src/lib/doctor-diff.ts): it reads
- * the ACTUAL version home and compares it to the resolved sources, so it catches
- * every drift class — source-side changes AND home-side rot (deleted / corrupted /
- * hand-edited installed copies) AND orphans. This module wraps it once, maps its
- * per-resource DiffStatus onto one stable enum, folds in `.system` repo freshness,
- * and lets every surface render the same warnings instead of re-deriving them.
- */
 import { AgentId } from './types.js';
 import { type DoctorKind } from './doctor-diff.js';
 import { type ConfigDrift } from './config-drift.js';
-/**
- * One stable status per resource, unified across every surface.
- *  - `synced`  — installed copy matches the resolved source (DiffStatus 'ok').
- *  - `drifted` — installed copy exists but differs from source (DiffStatus 'diff').
- *  - `missing` — source exists, nothing installed in the version home ('missing').
- *  - `orphan`  — installed in the home with no source ('extra'); prune's job, not sync's.
- */
 type ResourceSyncStatus = 'synced' | 'drifted' | 'missing' | 'orphan';
 export interface ResourceStatusRow {
     agent: AgentId;
@@ -35,14 +8,12 @@ export interface ResourceStatusRow {
     kind: DoctorKind;
     name: string;
     status: ResourceSyncStatus;
-    /** Human-readable specifics for a drifted row (e.g. plugin version delta). */
     detail?: string;
 }
 export interface AgentVersionStatus {
     agent: AgentId;
     version: string;
     isDefault: boolean;
-    /** False = no .sync-manifest.json: this version was never synced (cold). */
     everSynced: boolean;
     counts: {
         synced: number;
@@ -50,89 +21,46 @@ export interface AgentVersionStatus {
         missing: number;
         orphan: number;
     };
-    /** drifted + missing > 0 — a real reconcile is owed. Orphans do NOT set this
-     * (heal never deletes; orphan removal is `agents prune cleanup`). */
     needsSync: boolean;
     resources: ResourceStatusRow[];
 }
 export interface SystemRepoStatus {
     dir: string;
-    /** Commits the local `.system` checkout is behind its tracking branch, as of
-     * the last background fetch (no network is performed here). 0 = up to date. */
     behind: number;
     ahead: number;
     branch: string | null;
-    /** True when the dir isn't a git repo or has no upstream — behind is unknown. */
     unknown: boolean;
 }
 export interface UserRepoStatus {
     dir: string;
-    /**
-     * True when `~/.agents` exists but is not a git repo (or is a repo with no
-     * `origin`) — a partial install `agents repo sync user` will adopt in place
-     * (PHNX-3301). A DISTINCT drift state, not a per-agent "N missing" count.
-     */
     notGitRepo: boolean;
 }
 export interface UnifiedSyncStatus {
     system: SystemRepoStatus;
     user: UserRepoStatus;
-    /** Config drift: has this box drained its device-scoped state, or is it still
-     *  carrying per-box state in the shared top-level agents.yaml? (PHNX-3315) */
     config: ConfigDrift;
     agents: AgentVersionStatus[];
     totals: {
         drifted: number;
         missing: number;
         orphan: number;
-        /** Versions with a manifest that are behind on content. */
         versionsNeedingSync: number;
-        /** Versions that were never synced at all. */
         versionsNeverSynced: number;
-        /** Distinct agent ids that own at least one version needing sync. */
         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[];
-/**
- * The rows behind a "N drifted" count, one line each, for the human renderers.
- * A count alone cannot be acted on; the name says which skill or hook to look
- * at, and `detail` says what differs when the differ knows.
- */
 export declare function formatDriftRows(v: AgentVersionStatus): string[];
 interface SyncStatusOptions {
     cwd?: string;
-    /** Restrict to specific agent ids; undefined = every supported agent. */
     agents?: AgentId[];
-    /** Restrict to specific resource kinds; undefined = all. */
     kinds?: DoctorKind[];
 }
-/**
- * Compute unified sync status across the fleet. Resolves against non-project
- * layers only (`excludeProject: true`) — the GLOBAL version home is never
- * reconciled against per-cwd `<cwd>/.agents/` resources, so counting them as
- * "missing" there would be a false gap (matches doctor's overview semantics).
- */
 export declare function computeSyncStatus(options?: SyncStatusOptions): Promise<UnifiedSyncStatus>;
 export {};

package/dist/lib/sync-status.js

@@ -1,23 +1,3 @@
-/**
- * Unified sync-status engine — the SINGLE source of truth for "is this resource
- * synced to this agent version?" consumed by `agents doctor`, `agents view`, the
- * menu-bar app, and any Agency surface.
- *
- * Why this exists: before this module there were four different notions of
- * "synced" living in four files:
- *   - doctor:  isStale() vs .sync-manifest.json  — catches SOURCE drift only.
- *   - view:    git working-tree state of ~/.agents/ — a resource can show green
- *              while its installed copy is stale/deleted/corrupted (false positive).
- *   - lists:   file-exists-in-home — never reports content drift at all.
- *   - menubar: read doctor --json (so it inherited doctor's source-only blind spot).
- *
- * The reliable signal is diffVersionResources() (src/lib/doctor-diff.ts): it reads
- * the ACTUAL version home and compares it to the resolved sources, so it catches
- * every drift class — source-side changes AND home-side rot (deleted / corrupted /
- * hand-edited installed copies) AND orphans. This module wraps it once, maps its
- * per-resource DiffStatus onto one stable enum, folds in `.system` repo freshness,
- * and lets every surface render the same warnings instead of re-deriving them.
- */
 import simpleGit from 'simple-git';
 import { ALL_AGENT_IDS } from './agents.js';
 import { diffVersionResources, } from './doctor-diff.js';
@@ -27,14 +7,6 @@ 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)
@@ -43,7 +15,6 @@ export function verifyVersionConverged(agent, version, cwd = process.cwd()) {
         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) {
@@ -54,11 +25,6 @@ export function formatResidualDrift(residual) {
     }
     return lines;
 }
-/**
- * The rows behind a "N drifted" count, one line each, for the human renderers.
- * A count alone cannot be acted on; the name says which skill or hook to look
- * at, and `detail` says what differs when the differ knows.
- */
 export function formatDriftRows(v) {
     return v.resources
         .filter((r) => r.status === 'drifted' || r.status === 'missing')
@@ -87,12 +53,6 @@ function rowsFromReport(agent, version, report) {
     }
     return out;
 }
-/**
- * Read `.system` repo freshness WITHOUT touching the network. `git status`
- * reports ahead/behind against the remote-tracking ref, which the detached
- * auto-pull worker keeps warm via periodic `git fetch`. This is the same number
- * the menu-bar surfaces; we read it once, here, so every surface agrees.
- */
 async function getSystemRepoStatus() {
     const dir = getSystemAgentsDir();
     const base = { dir, behind: 0, ahead: 0, branch: null, unknown: true };
@@ -105,7 +65,6 @@ async function getSystemRepoStatus() {
             behind: status.behind ?? 0,
             ahead: status.ahead ?? 0,
             branch: status.tracking ?? status.current ?? null,
-            // Without a tracking branch there's no upstream to compare against.
             unknown: !status.tracking,
         };
     }
@@ -113,28 +72,14 @@ async function getSystemRepoStatus() {
         return base;
     }
 }
-/**
- * Detect whether `~/.agents` (the user config layer) is git-backed. A partial
- * install — runtime state present but no `.git` (or no `origin`) — is a distinct
- * drift state that `agents repo sync user` heals by adopting in place (PHNX-3301),
- * surfaced separately from per-version resource gaps. Purely local; no network.
- */
 async function getUserRepoStatus() {
     const dir = getUserAgentsDir();
     if (!fs.existsSync(dir))
         return { dir, notGitRepo: false };
     if (!isGitRepo(dir))
         return { dir, notGitRepo: true };
-    // A repo with no `origin` is just as partial for adopt's purposes — reuse the
-    // single origin-URL reader rather than a second remote check.
     return { dir, notGitRepo: readOriginUrl(dir) === null };
 }
-/**
- * Compute unified sync status across the fleet. Resolves against non-project
- * layers only (`excludeProject: true`) — the GLOBAL version home is never
- * reconciled against per-cwd `<cwd>/.agents/` resources, so counting them as
- * "missing" there would be a false gap (matches doctor's overview semantics).
- */
 export async function computeSyncStatus(options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const agentIds = options.agents ?? ALL_AGENT_IDS;

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

@@ -1,46 +1,15 @@
-/**
- * Umbrella `agents sync` orchestration — "make this machine current".
- *
- * Bare `agents sync` fetches the config repos then reconciles them into every
- * installed agent's version home. Secrets are an opt-in stage (`--secrets`) —
- * see `planUmbrellaStages` for why it's off by default. Each stage is an
- * existing exported library function; this module only sequences them and
- * decides — from the flags — which stages run. The planner is pure so the
- * flag matrix is unit-tested without any I/O.
- *
- * Stage backends:
- *   repos    -> git pull of ~/.agents + enabled ~/.agents-* extras (pullRepo)
- *   secrets  -> listRemoteBundles + pullBundle (needs a passphrase; skipped
- *               cleanly when none is available — tokenized non-interactive auth
- *               arrives with `agents secrets vault unlock`, #366/#367)
- *   reconcile-> refresh({ skipPrompts }) — re-materialize resources into homes
- */
 import type { ResourceSelection } from './installations/versions.js';
-/** The umbrella flags off `agents sync`. */
 export interface UmbrellaFlags {
     repos?: boolean;
     secrets?: boolean;
     cloud?: boolean;
     local?: boolean;
 }
-/** Which stages a given flag combination runs. */
 interface UmbrellaPlan {
     fetchRepos: boolean;
     fetchSecrets: boolean;
     reconcile: boolean;
 }
-/**
- * Decide which stages run. Pure — no I/O. Semantics:
- *   bare (no flags)        fetch repos, then reconcile
- *   --local                reconcile only, no fetch
- *   --cloud                fetch repos (or the selected subset), skip reconcile
- *   --repos/--secrets      fetch only the selected types, then reconcile
- * `--local` wins over everything; `--cloud` suppresses reconcile.
- *
- * Secrets are NOT part of the bare default — they are opt-in via `--secrets`.
- * Pulling every secret bundle onto the machine on a bare `agents sync` is more
- * blast radius than the verb should carry by default.
- */
 export declare function planUmbrellaStages(f: UmbrellaFlags): UmbrellaPlan;
 interface UmbrellaResult {
     plan: UmbrellaPlan;
@@ -60,16 +29,7 @@ interface UmbrellaResult {
         skipped: boolean;
     };
     reconciled: boolean;
-    /**
-     * Resources the reconcile stage refused to write, as user-facing sentences.
-     * 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;
@@ -77,26 +37,12 @@ interface UmbrellaResult {
 }
 interface RunUmbrellaArgs {
     flags: UmbrellaFlags;
-    /** Progress sink (already quiet-aware in the caller). */
     log: (msg: string) => void;
-    /** Pass `skipPrompts` through to reconcile / non-interactive behavior. */
     yes: boolean;
-    /** Secrets passphrase, if available (env var or prompt). Undefined => skip secrets. */
     passphrase?: string;
-    /**
-     * Suppress human progress from the reconcile stage (`refresh`). Required so
-     * `agents sync --json` / fleet fan-out leave stdout as a single JSON object.
-     */
     quiet?: boolean;
-    /** Optional resource-only reconcile across installed versions. */
     selection?: ResourceSelection;
-    /** Explicit consent for selected plugins that add executable surfaces. */
     allowExecSurfaces?: boolean;
 }
-/**
- * Execute the planned stages in order: repos -> secrets -> reconcile.
- * A failure in one fetch stage is recorded and does not abort the others or the
- * reconcile — `agents sync` should make as much current as it can in one pass.
- */
 export declare function runUmbrellaSync(args: RunUmbrellaArgs): Promise<UmbrellaResult>;
 export {};

package/dist/lib/sync-umbrella.js

@@ -1,36 +1,7 @@
-/**
- * Umbrella `agents sync` orchestration — "make this machine current".
- *
- * Bare `agents sync` fetches the config repos then reconciles them into every
- * installed agent's version home. Secrets are an opt-in stage (`--secrets`) —
- * see `planUmbrellaStages` for why it's off by default. Each stage is an
- * existing exported library function; this module only sequences them and
- * decides — from the flags — which stages run. The planner is pure so the
- * flag matrix is unit-tested without any I/O.
- *
- * Stage backends:
- *   repos    -> git pull of ~/.agents + enabled ~/.agents-* extras (pullRepo)
- *   secrets  -> listRemoteBundles + pullBundle (needs a passphrase; skipped
- *               cleanly when none is available — tokenized non-interactive auth
- *               arrives with `agents secrets vault unlock`, #366/#367)
- *   reconcile-> refresh({ skipPrompts }) — re-materialize resources into homes
- */
 import { pullRepo, adoptUserRepoIfNeeded } from './git.js';
 import { getUserAgentsDir, getEnabledExtraRepos } from './state.js';
 import { listRemoteBundles, pullBundle } from './secrets-client.js';
 import { SYNC_PASSPHRASE_ENV } from './sync-passphrase.js';
-/**
- * Decide which stages run. Pure — no I/O. Semantics:
- *   bare (no flags)        fetch repos, then reconcile
- *   --local                reconcile only, no fetch
- *   --cloud                fetch repos (or the selected subset), skip reconcile
- *   --repos/--secrets      fetch only the selected types, then reconcile
- * `--local` wins over everything; `--cloud` suppresses reconcile.
- *
- * Secrets are NOT part of the bare default — they are opt-in via `--secrets`.
- * Pulling every secret bundle onto the machine on a bare `agents sync` is more
- * blast radius than the verb should carry by default.
- */
 export function planUmbrellaStages(f) {
     if (f.local) {
         return { fetchRepos: false, fetchSecrets: false, reconcile: true };
@@ -43,15 +14,8 @@ export function planUmbrellaStages(f) {
             reconcile: !f.cloud,
         };
     }
-    // No per-type selector: bare = repos + reconcile; --cloud = repos, no
-    // reconcile. Secrets stay off unless explicitly selected above.
     return { fetchRepos: true, fetchSecrets: false, reconcile: !f.cloud };
 }
-/**
- * Execute the planned stages in order: repos -> secrets -> reconcile.
- * A failure in one fetch stage is recorded and does not abort the others or the
- * reconcile — `agents sync` should make as much current as it can in one pass.
- */
 export async function runUmbrellaSync(args) {
     const { flags, log, yes, passphrase, quiet = false, selection, allowExecSurfaces = false } = args;
     const plan = planUmbrellaStages(flags);
@@ -64,13 +28,6 @@ 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) {
@@ -141,11 +98,6 @@ export async function runUmbrellaSync(args) {
         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
-        // tailscale is a clean no-op, never a sync failure. First-run population is
-        // `agents setup` / manual `agents devices sync` (bootstrap).
         if (!selection) {
             const { runDeviceSync } = await import('./devices/sync.js');
             const { reconcilePendingSentinels } = await import('./devices/pending.js');

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

@@ -1,12 +1,7 @@
 import type { AgentId } from './types.js';
 interface SystemRunSyncResult {
-    /** Names rewritten per kind; empty when the sentinel matched (skip-fast). */
     skills: string[];
     subagents: string[];
 }
-/**
- * Refresh the system layer's skills and subagents into the version home when
- * their source directories changed since the last run for (agent, version).
- */
 export declare function applySystemResourcesAtRun(agent: AgentId, version: string, versionHome: string): SystemRunSyncResult;
 export {};