@phnx-labs/agents-cli 1.22.34 → 1.22.37

package/dist/lib/state.d.ts

@@ -29,7 +29,7 @@ export declare function getHumansFilePath(): string;
  * Header prepended to every agents.yaml the CLI writes (central and per-device
  * docs). Carries the yaml-language-server schema hint so editors validate the
  * file against `schema/agents-yaml.schema.json`. Exported so
- * `lib/device-config.ts` writes a sibling device's doc with the same header.
+ * `lib/devices/config-migration.ts` rewrites a device doc with the same header.
  */
 export declare const META_HEADER = "# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agents-cli\n# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agents-cli/main/apps/cli/schema/agents-yaml.schema.json\n\n";
 /** Root of the system data directory (~/.agents/.system/). */
@@ -140,6 +140,8 @@ export declare function getPackagesDir(): string;
 export declare function getRoutinesDir(): string;
 /** Path to named project definitions (~/.agents/projects/). */
 export declare function getProjectsDir(): string;
+/** Path to daemon config directory (~/.agents/daemon/). Holds service toggles. */
+export declare function getDaemonConfigDir(): string;
 /**
  * Path to webhook handler YAML definitions (~/.agents/webhooks/). Handlers are
  * one-off triggers for agents/workflows/commands/routines, layered the same way
@@ -164,12 +166,12 @@ export declare function getSystemWebhooksDir(): string;
  * or null when no project `.agents/` is found by walking up from cwd.
  *
  * Project routines participate in `list`/`view` for inspection always. Daemon
- * firing requires an explicit opt-in via `agents routines enable-project`
- * (writes `meta.routines.projects`); after opt-in, `agents routines sync`
- * materialises them into the user layer with `source:` provenance so the
- * daemon (which loads user + system only) can fire them safely. A project's
- * own `agents.yaml` `routines.enable: true` is a documentation signal only —
- * it does not auto-enable firing. See `lib/routines-project.ts`.
+ * firing requires `agents routines enable <name>`, which materialises the
+ * routine into the user layer with `source:` provenance (so the daemon, which
+ * loads user + system only, can see it) and turns on the device flag in one
+ * step. Enablement lives solely in `meta.deviceRoutines`; a project YAML's own
+ * `enabled:` field never turns firing on, so a cloned repo cannot auto-run.
+ * See `lib/routines-project.ts`.
  */
 export declare function getProjectRoutinesDir(cwd?: string): string | null;
 /**
@@ -182,6 +184,16 @@ export declare function getProjectWebhooksDir(cwd?: string): string | null;
 export declare function getRunsDir(): string;
 /** Path to monitor YAML definitions (~/.agents/monitors/). */
 export declare function getMonitorsDir(): string;
+/**
+ * Path to built-in monitor definitions shipped in the system repo
+ * (`~/.agents/.system/monitors/`). Unioned under the user monitors dir by
+ * listMonitors()/readMonitor(): a monitor shipped here is available on every
+ * install, and a user monitor of the same name overrides it. A built-in with no
+ * `enabled:` field is opt-in — it stays disabled until the user enables it,
+ * which materializes a user copy (writes never touch this pull-only mirror). The
+ * directory need not exist.
+ */
+export declare function getSystemMonitorsDir(): string;
 /** Path to the durable per-monitor state-diff store + fire history
  * (~/.agents/.history/monitors/). */
 export declare function getMonitorsHistoryDir(): string;
@@ -238,7 +250,7 @@ export declare function getTeamsRegistryPath(): string;
 export declare function getDevicesRegistryPath(): string;
 /** Path to the device ignore-list — tailscale node names the user dismissed, so auto-discovery never re-suggests them. Per-machine, same dir as the registry. */
 export declare function getDevicesIgnoredPath(): string;
-/** Path to the device auto-launch preference file — which registered devices are eligible/preferred for Factory's auto-host selection. Per-machine, same dir as the registry. */
+/** Path to the LEGACY device auto-launch preference file — which registered devices are eligible/preferred for the ext's auto-host selection. Superseded by the central `fleet.devices.<name>.config` block; only lib/devices/config-migration.ts still reads it (to fold + remove it). */
 export declare function getDevicesAutoLaunchPath(): string;
 /** Dir of "pending device" sentinels (~/.agents/.cache/state/devices-pending/) — one empty-ish file per newly-discovered, not-yet-approved tailnet node. Written by the daemon probe, read by the menu-bar helper (mirrors the attention sentinel dir). */
 export declare function getDevicesPendingDir(): string;
@@ -266,7 +278,22 @@ export declare function getPerfDir(): string;
 export declare function getPerfDbPath(): string;
 /** Path to the hook-shim NDJSON spool drained into perf.db on open. */
 export declare function getPerfSpoolPath(): string;
-/** Path to per-process runtime state (~/.agents/.cache/state/). */
+/**
+ * Path to per-process runtime state (~/.agents/.cache/state/).
+ *
+ * `AGENTS_STATE_DIR` redirects it in tests — the same test-isolation escape
+ * hatch as `AGENTS_DEVICES_DIR` / `AGENTS_LOGS_DIR`, and resolved at call time
+ * for the same reason (a suite pins it after this module is imported).
+ *
+ * Without it the suite writes into the operator's LIVE state. Concretely: the
+ * device registry and ignore-list already redirect via `AGENTS_DEVICES_DIR`, so
+ * under test both read empty — and any code path reaching
+ * `reconcilePendingSentinels` then computed "every tailnet node is new" and
+ * wrote those sentinels into the real `devices-pending/`, which is exactly what
+ * the menu bar renders. Running the suite on a dev machine surfaced all 20
+ * tailnet nodes as NEW DEVICES, including registered and explicitly ignored
+ * ones, and looked like the operator's ignore list had been lost.
+ */
 export declare function getRuntimeStateDir(): string;
 /** Path to companion-extension scratch (~/.agents/.cache/companion/). */
 export declare function getCompanionDir(): string;

package/dist/lib/state.js

@@ -26,6 +26,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'yaml';
+import { stringifyDoc } from './yaml-io.js';
 import { execFileSync } from 'child_process';
 import { ensureLockTarget, atomicWriteFileSync, withFileLock } from './fs-atomic.js';
 import { DEFAULT_SYSTEM_REPO, systemRepoSlug } from './types.js';
@@ -78,6 +79,11 @@ const SYSTEM_PLUGINS_DIR = path.join(SYSTEM_AGENTS_DIR, 'plugins');
 // Unioned under user routines by listJobs()/readJob() so a routine shipped here
 // fires for every install, while a user routine of the same name overrides it.
 const SYSTEM_ROUTINES_DIR = path.join(SYSTEM_AGENTS_DIR, 'routines');
+// Built-in monitors shipped in the system repo (gh:phnx-labs/.agents-system).
+// Unioned under user monitors by listMonitors()/readMonitor() so a monitor
+// shipped here is available on every install, while a user monitor of the same
+// name overrides it (a built-in with no `enabled:` field stays opt-in).
+const SYSTEM_MONITORS_DIR = path.join(SYSTEM_AGENTS_DIR, 'monitors');
 const SYSTEM_WEBHOOKS_DIR = path.join(SYSTEM_AGENTS_DIR, 'webhooks');
 const SYSTEM_PROMPTCUTS_FILE = path.join(SYSTEM_AGENTS_DIR, 'hooks', 'promptcuts.yaml');
 const SYSTEM_MCP_CONFIG_FILE = path.join(SYSTEM_AGENTS_DIR, 'mcp.json');
@@ -97,6 +103,9 @@ const TEAMS_DIR = path.join(USER_AGENTS_DIR, 'teams');
 // Named project definitions (the layer above the --project convention). Sibling
 // of ROUTINES_DIR/TEAMS_DIR: hand-editable YAML, synced across machines by push/pull.
 const PROJECTS_DIR = path.join(USER_AGENTS_DIR, 'projects');
+// Daemon service toggles and persistent daemon config. Top-level config/definitions
+// dir like routines/webhooks; runtime state (pid/heartbeat/logs) stays in .cache.
+const DAEMON_CONFIG_DIR = path.join(USER_AGENTS_DIR, 'daemon');
 // History bucket (durable).
 const SESSIONS_DIR = path.join(HISTORY_DIR, 'sessions');
 const SESSIONS_DB_PATH = path.join(SESSIONS_DIR, 'sessions.db');
@@ -154,7 +163,7 @@ const USER_PROMPTCUTS_FILE = path.join(USER_AGENTS_DIR, 'hooks', 'promptcuts.yam
  * Header prepended to every agents.yaml the CLI writes (central and per-device
  * docs). Carries the yaml-language-server schema hint so editors validate the
  * file against `schema/agents-yaml.schema.json`. Exported so
- * `lib/device-config.ts` writes a sibling device's doc with the same header.
+ * `lib/devices/config-migration.ts` rewrites a device doc with the same header.
  */
 export const META_HEADER = `# agents-cli metadata
 # Auto-generated - do not edit manually
@@ -411,6 +420,8 @@ export function getPackagesDir() { return PACKAGES_DIR; }
 export function getRoutinesDir() { return process.env.AGENTS_ROUTINES_DIR ?? ROUTINES_DIR; }
 /** Path to named project definitions (~/.agents/projects/). */
 export function getProjectsDir() { return process.env.AGENTS_PROJECTS_DIR ?? PROJECTS_DIR; }
+/** Path to daemon config directory (~/.agents/daemon/). Holds service toggles. */
+export function getDaemonConfigDir() { return process.env.AGENTS_DAEMON_CONFIG_DIR ?? DAEMON_CONFIG_DIR; }
 /**
  * Path to webhook handler YAML definitions (~/.agents/webhooks/). Handlers are
  * one-off triggers for agents/workflows/commands/routines, layered the same way
@@ -435,12 +446,12 @@ export function getSystemWebhooksDir() { return process.env.AGENTS_SYSTEM_WEBHOO
  * or null when no project `.agents/` is found by walking up from cwd.
  *
  * Project routines participate in `list`/`view` for inspection always. Daemon
- * firing requires an explicit opt-in via `agents routines enable-project`
- * (writes `meta.routines.projects`); after opt-in, `agents routines sync`
- * materialises them into the user layer with `source:` provenance so the
- * daemon (which loads user + system only) can fire them safely. A project's
- * own `agents.yaml` `routines.enable: true` is a documentation signal only —
- * it does not auto-enable firing. See `lib/routines-project.ts`.
+ * firing requires `agents routines enable <name>`, which materialises the
+ * routine into the user layer with `source:` provenance (so the daemon, which
+ * loads user + system only, can see it) and turns on the device flag in one
+ * step. Enablement lives solely in `meta.deviceRoutines`; a project YAML's own
+ * `enabled:` field never turns firing on, so a cloned repo cannot auto-run.
+ * See `lib/routines-project.ts`.
  */
 export function getProjectRoutinesDir(cwd = process.cwd()) {
     const projectAgentsDir = getProjectAgentsDir(cwd);
@@ -462,7 +473,17 @@ export function getProjectWebhooksDir(cwd = process.cwd()) {
 /** Path to routine execution logs (~/.agents/.history/runs/). */
 export function getRunsDir() { return RUNS_DIR; }
 /** Path to monitor YAML definitions (~/.agents/monitors/). */
-export function getMonitorsDir() { return MONITORS_DIR; }
+export function getMonitorsDir() { return process.env.AGENTS_MONITORS_DIR ?? MONITORS_DIR; }
+/**
+ * Path to built-in monitor definitions shipped in the system repo
+ * (`~/.agents/.system/monitors/`). Unioned under the user monitors dir by
+ * listMonitors()/readMonitor(): a monitor shipped here is available on every
+ * install, and a user monitor of the same name overrides it. A built-in with no
+ * `enabled:` field is opt-in — it stays disabled until the user enables it,
+ * which materializes a user copy (writes never touch this pull-only mirror). The
+ * directory need not exist.
+ */
+export function getSystemMonitorsDir() { return process.env.AGENTS_SYSTEM_MONITORS_DIR ?? SYSTEM_MONITORS_DIR; }
 /** Path to the durable per-monitor state-diff store + fire history
  * (~/.agents/.history/monitors/). */
 export function getMonitorsHistoryDir() { return MONITORS_HISTORY_DIR; }
@@ -543,10 +564,10 @@ function getDevicesDir() {
 export function getDevicesRegistryPath() { return path.join(getDevicesDir(), 'registry.json'); }
 /** Path to the device ignore-list — tailscale node names the user dismissed, so auto-discovery never re-suggests them. Per-machine, same dir as the registry. */
 export function getDevicesIgnoredPath() { return path.join(getDevicesDir(), 'ignored.json'); }
-/** Path to the device auto-launch preference file — which registered devices are eligible/preferred for Factory's auto-host selection. Per-machine, same dir as the registry. */
+/** Path to the LEGACY device auto-launch preference file — which registered devices are eligible/preferred for the ext's auto-host selection. Superseded by the central `fleet.devices.<name>.config` block; only lib/devices/config-migration.ts still reads it (to fold + remove it). */
 export function getDevicesAutoLaunchPath() { return path.join(getDevicesDir(), 'auto-launch.json'); }
 /** Dir of "pending device" sentinels (~/.agents/.cache/state/devices-pending/) — one empty-ish file per newly-discovered, not-yet-approved tailnet node. Written by the daemon probe, read by the menu-bar helper (mirrors the attention sentinel dir). */
-export function getDevicesPendingDir() { return path.join(RUNTIME_STATE_DIR, 'devices-pending'); }
+export function getDevicesPendingDir() { return path.join(getRuntimeStateDir(), 'devices-pending'); }
 /** Path to cloud dispatch cache (~/.agents/.cache/cloud/). */
 export function getCloudDir() { return CLOUD_DIR; }
 /** Path to terminal session metadata (~/.agents/.cache/terminals/). */
@@ -575,8 +596,23 @@ export function getPerfDir() {
 export function getPerfDbPath() { return path.join(getPerfDir(), 'perf.db'); }
 /** Path to the hook-shim NDJSON spool drained into perf.db on open. */
 export function getPerfSpoolPath() { return path.join(getPerfDir(), 'spool.jsonl'); }
-/** Path to per-process runtime state (~/.agents/.cache/state/). */
-export function getRuntimeStateDir() { return RUNTIME_STATE_DIR; }
+/**
+ * Path to per-process runtime state (~/.agents/.cache/state/).
+ *
+ * `AGENTS_STATE_DIR` redirects it in tests — the same test-isolation escape
+ * hatch as `AGENTS_DEVICES_DIR` / `AGENTS_LOGS_DIR`, and resolved at call time
+ * for the same reason (a suite pins it after this module is imported).
+ *
+ * Without it the suite writes into the operator's LIVE state. Concretely: the
+ * device registry and ignore-list already redirect via `AGENTS_DEVICES_DIR`, so
+ * under test both read empty — and any code path reaching
+ * `reconcilePendingSentinels` then computed "every tailnet node is new" and
+ * wrote those sentinels into the real `devices-pending/`, which is exactly what
+ * the menu bar renders. Running the suite on a dev machine surfaced all 20
+ * tailnet nodes as NEW DEVICES, including registered and explicitly ignored
+ * ones, and looked like the operator's ignore list had been lost.
+ */
+export function getRuntimeStateDir() { return process.env.AGENTS_STATE_DIR ?? RUNTIME_STATE_DIR; }
 /** Path to companion-extension scratch (~/.agents/.cache/companion/). */
 export function getCompanionDir() { return COMPANION_CACHE_DIR; }
 /** Path to browser runtime data — chrome-data, pids (~/.agents/.cache/browser/). */
@@ -787,9 +823,10 @@ function writeIfChanged(filePath, content) {
 /**
  * Partition the in-memory Meta across three files by sync-domain:
  *   - central  `~/.agents/agents.yaml`             — portable, everything else
- *              (including the user-scope `config:` block)
+ *              (including the user-scope `config:` block and the per-device
+ *              operator config under `fleet.devices.<name>.config`)
  *   - device   `~/.agents/devices/<machine>/agents.yaml` — `agents:` pins +
- *              `defaultBrowserProfile:` + device-scope `config:` (all per-device)
+ *              `routines:` (all per-machine)
  *   - history  `~/.agents/.history/version-resources.json` — `versions:` (machine-local)
  * All callers funnel through writeMeta → here, so nothing else changes. Empty
  * `agents:` / `versions:` are not written (no empty committed files).
@@ -810,10 +847,11 @@ const META_KEY_SCOPE = {
     agents: 'device',
     isolatedAgents: 'device',
     versions: 'device',
-    defaultBrowserProfile: 'device',
-    deviceConfig: 'device',
     deviceRoutines: 'device',
+    deviceConfig: 'device',
+    deviceBrowser: 'device',
     // Central — synced via agents.yaml.
+    accounts: 'central',
     run: 'central',
     model: 'central',
     watchdog: 'central',
@@ -825,7 +863,7 @@ const META_KEY_SCOPE = {
     registries: 'central',
     profiles: 'central',
     source: 'central',
-    projectRoot: 'central',
+    projectRoot: 'device',
     extraRepos: 'central',
     brands: 'central',
     actors: 'central',
@@ -837,7 +875,6 @@ const META_KEY_SCOPE = {
     fleet: 'central',
     share: 'central',
     notify: 'central',
-    routines: 'central',
 };
 /**
  * Every key this version models (central + device). serializeCentral deletes an
@@ -903,14 +940,16 @@ function serializeCentral(central) {
     if (!changed)
         return existing;
     // Everything cleared → header only (never leave a flow `{}` behind).
-    // Otherwise force BLOCK style: an existing flow root (e.g. a legacy `{}`) would
-    // otherwise make the edited nodes render flow (`disabledCommands: [ teams ]`
-    // instead of a `- teams` block list). collectionStyle pins the whole doc block
-    // while parseDocument still preserves comments + key ordering.
-    return isEmpty ? META_HEADER : doc.toString({ collectionStyle: 'block' });
+    // Otherwise stringifyDoc: it still normalizes a legacy flow root (`{}`) to
+    // block, so edited nodes do not render flow (`disabledCommands: [ teams ]`
+    // instead of a `- teams` block list), but it no longer forces block on a
+    // normal document — that flattened committed flow sequences and made this
+    // writer disagree with feed.ts/activity.ts/migrate.ts on the same file
+    // (RUSH-2505). parseDocument still preserves comments + key ordering.
+    return isEmpty ? META_HEADER : stringifyDoc(doc);
 }
 function writeMetaUnlocked(meta) {
-    const { agents, isolatedAgents, versions, defaultBrowserProfile, deviceConfig, deviceRoutines, ...central } = meta;
+    const { agents, isolatedAgents, versions, deviceRoutines, deviceConfig, deviceBrowser, projectRoot, ...central } = meta;
     // Write the machine-local files FIRST, then strip central — so a crash mid-write
     // never removes pins/versions from central before they're persisted elsewhere.
     const devicePath = getDeviceMetaPath();
@@ -920,26 +959,32 @@ function writeMetaUnlocked(meta) {
     // central doc that syncs — otherwise another machine inherits a pointer to a copy
     // it does not have.
     const hasIsolatedAgents = !!isolatedAgents && Object.keys(isolatedAgents).length > 0;
-    const hasDefaultBrowser = !!defaultBrowserProfile;
-    // Device-scope config (`maxAgents`, `schedulerEnabled`, …) is per-machine, so it
-    // rides the device doc under `config:` — never the central doc that syncs.
-    const hasDeviceConfig = !!deviceConfig && Object.keys(deviceConfig).length > 0;
     const hasDeviceRoutines = Array.isArray(deviceRoutines);
-    if (hasAgents || hasIsolatedAgents || hasDefaultBrowser || hasDeviceConfig || hasDeviceRoutines) {
-        // Device-local doc carries `agents:` pins, `defaultBrowserProfile:`, and the
-        // device-scope `config:` — all per-machine and must never land in central
-        // agents.yaml (which syncs).
+    // Machine-visibility operator config. Lives here rather than in the synced
+    // central file because nothing off-box reads it — and because
+    // browser.remote-control is a consent flag that must not propagate on pull.
+    const hasDeviceConfig = !!deviceConfig && Object.keys(deviceConfig).length > 0;
+    const hasDeviceBrowser = !!deviceBrowser && Object.keys(deviceBrowser).length > 0;
+    // An inferred local filesystem path — machine state, never fleet policy.
+    const hasProjectRoot = typeof projectRoot === 'string' && projectRoot.length > 0;
+    if (hasAgents || hasIsolatedAgents || hasDeviceRoutines || hasDeviceConfig || hasDeviceBrowser || hasProjectRoot) {
+        // Device-local doc carries `agents:` pins and `routines:` — per-machine and
+        // must never land in central agents.yaml (which syncs). Operator config
+        // used to ride this doc under `config:`; it now lives centrally under
+        // `fleet.devices.<name>.config` (see lib/device-config.ts).
         const deviceDoc = {};
         if (hasAgents)
             deviceDoc.agents = agents;
         if (hasIsolatedAgents)
             deviceDoc.isolatedAgents = isolatedAgents;
-        if (hasDefaultBrowser)
-            deviceDoc.defaultBrowserProfile = defaultBrowserProfile;
-        if (hasDeviceConfig)
-            deviceDoc.config = deviceConfig;
         if (hasDeviceRoutines)
             deviceDoc.routines = deviceRoutines;
+        if (hasDeviceConfig)
+            deviceDoc.config = deviceConfig;
+        if (hasDeviceBrowser)
+            deviceDoc.browser = deviceBrowser;
+        if (hasProjectRoot)
+            deviceDoc.projectRoot = projectRoot;
         fs.mkdirSync(path.dirname(devicePath), { recursive: true });
         writeIfChanged(devicePath, META_HEADER + yaml.stringify(deviceDoc));
     }
@@ -963,14 +1008,15 @@ function writeMetaUnlocked(meta) {
  *   - `agents:` and `isolatedAgents:` from the device file (device wins; the union
  *     both preserves the one-level merge and self-heals a pre-migration central that
  *     still has pins)
- *   - `defaultBrowserProfile:` from the device file (device is the sole source;
- *     the field is stripped from central on write, so nothing to merge against)
- *   - `config:` from the device file into `deviceConfig` (device is the sole
- *     source for device-scope config, same routing as `defaultBrowserProfile`;
- *     the in-memory field is named `deviceConfig` so it can never collide with
- *     the user-scope `config:` central carries)
+ *   - `routines:` from the device file into `deviceRoutines` (device-local
+ *     routine activation)
  *   - `versions:` from the history JSON (wholesale replace; falls back to
  *     whatever central carried when the history file doesn't exist yet)
+ *
+ * (Device operator config is NOT overlaid here: it lives centrally under
+ * `fleet.devices.<name>.config` — see lib/device-config.ts. The legacy
+ * `config:`/`defaultBrowserProfile:` keys in a device doc are folded into the
+ * central block by lib/devices/config-migration.ts.)
  */
 function overlayMachineLocal(meta) {
     const devicePath = getDeviceMetaPath();
@@ -985,10 +1031,14 @@ function overlayMachineLocal(meta) {
                 meta.agents = { ...meta.agents, ...dm.agents };
             if (dm?.isolatedAgents)
                 meta.isolatedAgents = { ...meta.isolatedAgents, ...dm.isolatedAgents };
-            if (dm?.defaultBrowserProfile)
-                meta.defaultBrowserProfile = dm.defaultBrowserProfile;
-            if (dm?.config)
-                meta.deviceConfig = dm.config;
+            if (typeof dm?.projectRoot === 'string')
+                meta.projectRoot = dm.projectRoot;
+            if (dm?.browser && typeof dm.browser === 'object' && !Array.isArray(dm.browser)) {
+                meta.deviceBrowser = { ...meta.deviceBrowser, ...dm.browser };
+            }
+            if (dm?.config && typeof dm.config === 'object' && !Array.isArray(dm.config)) {
+                meta.deviceConfig = { ...meta.deviceConfig, ...dm.config };
+            }
             if (dm && Object.prototype.hasOwnProperty.call(dm, 'routines')) {
                 if (!Array.isArray(dm.routines) || dm.routines.some((name) => typeof name !== 'string')) {
                     throw new Error(`Device config corrupted at ${devicePath}: routines must be a string list.`);

package/dist/lib/subagents-registry.d.ts

@@ -27,15 +27,8 @@ export interface SubagentTarget {
     names(dir: string): string[];
     /** On-disk paths subagent `name` occupies (for removal / soft-delete). */
     occupied(dir: string, name: string): OccupiedEntry[];
-    /** Cross-item files this target owns outside any one subagent's occupied paths. */
-    finalizeOccupied?(dir: string): OccupiedEntry[];
     /** Rich metadata for `name`; `null` skips it from the listing. */
     read(dir: string, name: string): SubagentMeta | null;
-    /** Optional post-sync pass over the just-synced subagents (Kimi's parent index). */
-    finalize?(dir: string, synced: Array<{
-        name: string;
-        path: string;
-    }>): void;
 }
 /**
  * Copy every file in `src` into `dest` (created if missing), applying

package/dist/lib/subagents-registry.js

@@ -14,16 +14,16 @@
  * every current agent, so most entries are a single call:
  *
  *   - `flatFile`  one `<name><ext>` file, body from a `transform` fn.
- *                 (claude, grok, droid, codex, opencode, copilot,
- *                  cursor, kiro, goose)
+ *                 (claude, grok, pi, droid, codex, opencode, copilot,
+ *                  cursor, kiro, goose, kimi)
  *   - `dirFile`   a `<name>/` directory holding one generated `<file>`.
  *                 (antigravity: `<name>/agent.md`)
  *   - `dirCopy`   copy the whole source directory to `<name>/`, applying
  *                 renames, detected by a `marker` file. (openclaw)
  *
- * Genuinely-bespoke agents keep an explicit handler in the same table -- Kimi
- * writes two files per subagent plus a managed parent index, so it is a hand
- * -written `SubagentTarget` rather than a builder call.
+ * Every agent now uses a builder; there are no bespoke handlers left. Legacy
+ * on-disk layouts are folded once by `lib/migrate.ts`, never by a target --
+ * a target describes the CURRENT shape and nothing else.
  *
  * The per-agent `transform`/metadata parsers are the escape hatch: they live in
  * `subagents.ts` and are referenced by the table, so the generic engine has zero
@@ -31,11 +31,12 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import * as TOML from 'smol-toml';
 import * as yaml from 'yaml';
 import { safeJoin } from './paths.js';
-import { parseSubagentFrontmatter, transformSubagentForClaude, transformSubagentForCodex, transformSubagentForCopilot, transformSubagentForCursor, transformSubagentForDroid, transformSubagentForGoose, transformSubagentForKiro, transformSubagentForOpenCode, transformSubagentForAntigravity, writeKimiSubagentFiles, buildKimiSubagentsParentYaml, KIMI_SUBAGENTS_PARENT_FILE, } from './subagents.js';
+import { parseSubagentFrontmatter, transformSubagentForClaude, transformSubagentForCodex, transformSubagentForCopilot, transformSubagentForCursor, transformSubagentForDroid, transformSubagentForGoose, transformSubagentForKiro, transformSubagentForOpenCode, transformSubagentForAntigravity, } from './subagents.js';
 // ── metadata readers (the per-format escape hatch) ───────────────────────────
-/** Frontmatter, skipping files that lack a valid block (claude/grok/droid/codex). */
+/** Frontmatter, skipping files that lack a valid block (claude/grok/droid). */
 function metaFrontmatterSkip(filePath) {
     return parseSubagentFrontmatter(filePath);
 }
@@ -63,6 +64,24 @@ function metaGooseYaml(filePath, name) {
         return null;
     }
 }
+/**
+ * Codex custom-agent TOML: name / description / model (optional).
+ * Codex writes no YAML frontmatter — without this reader, `flatFile.read`
+ * drops every installed `.toml` and `agents subagents list` reports codex
+ * targets as `missing` even when the files are present and Codex loads them.
+ */
+function metaToml(filePath, name) {
+    try {
+        const cfg = TOML.parse(fs.readFileSync(filePath, 'utf-8'));
+        const tomlName = typeof cfg.name === 'string' ? cfg.name : '';
+        const description = typeof cfg.description === 'string' ? cfg.description : '';
+        const model = typeof cfg.model === 'string' ? cfg.model : undefined;
+        return { name: tomlName || name, description, model };
+    }
+    catch {
+        return null;
+    }
+}
 // ── shared fs primitive ──────────────────────────────────────────────────────
 /**
  * Copy every file in `src` into `dest` (created if missing), applying
@@ -187,61 +206,6 @@ function dirCopy(opts) {
         },
     };
 }
-/**
- * Kimi (genuinely bespoke): each subagent is a `<name>.yaml` + sibling
- * `<name>.system.md`, and a managed `_agents-cli.yaml` parent lists them all for
- * `kimi --agent-file`. The parent index is a cross-item concern, so it is built
- * in `finalize`, not per-item.
- */
-const kimiTarget = {
-    dir: (home) => path.join(home, '.kimi-code', 'agents'),
-    write(dir, sub) {
-        writeKimiSubagentFiles(dir, sub.path, sub.name);
-    },
-    names(dir) {
-        if (!fs.existsSync(dir))
-            return [];
-        // The parent is `_agents-cli.yaml` (underscore-prefixed, reserved).
-        return fs
-            .readdirSync(dir)
-            .filter((f) => f.endsWith('.yaml') && !f.startsWith('_'))
-            .map((f) => f.slice(0, -'.yaml'.length));
-    },
-    occupied(dir, name) {
-        return [
-            { path: safeJoin(dir, `${name}.yaml`), kind: 'file' },
-            { path: safeJoin(dir, `${name}.system.md`), kind: 'file' },
-        ];
-    },
-    finalizeOccupied(dir) {
-        return [{ path: safeJoin(dir, KIMI_SUBAGENTS_PARENT_FILE), kind: 'file' }];
-    },
-    read(dir, name) {
-        const yamlPath = path.join(dir, `${name}.yaml`);
-        if (!fs.existsSync(yamlPath) || !fs.statSync(yamlPath).isFile())
-            return null;
-        let description = '';
-        try {
-            const parsed = yaml.parse(fs.readFileSync(yamlPath, 'utf-8'));
-            description = parsed?.agent?.description ?? '';
-        }
-        catch {
-            /* leave description empty */
-        }
-        const files = [`${name}.yaml`];
-        const promptFile = `${name}.system.md`;
-        if (fs.existsSync(path.join(dir, promptFile)))
-            files.push(promptFile);
-        return { frontmatter: { name, description }, files, path: yamlPath };
-    },
-    finalize(dir, synced) {
-        const entries = synced.map((sub) => {
-            const fm = parseSubagentFrontmatter(path.join(sub.path, 'AGENT.md'));
-            return { name: sub.name, description: fm?.description ?? sub.name, relativePath: `./${sub.name}.yaml` };
-        });
-        fs.writeFileSync(safeJoin(dir, KIMI_SUBAGENTS_PARENT_FILE), buildKimiSubagentsParentYaml(entries));
-    },
-};
 // ── the registry ─────────────────────────────────────────────────────────────
 /**
  * Single source of truth for how each subagents-capable agent stores subagents.
@@ -257,7 +221,12 @@ export const SUBAGENT_TARGETS = {
     pi: flatFile({ subdir: ['.omp', 'agent', 'agents'], ext: '.md', transform: transformSubagentForClaude, readMeta: metaFrontmatterFallback }),
     droid: flatFile({ subdir: ['.factory', 'droids'], ext: '.md', transform: transformSubagentForDroid }),
     // Bespoke frontmatter/format, still one flat file.
-    codex: flatFile({ subdir: ['.codex', 'agents'], ext: '.toml', transform: transformSubagentForCodex }),
+    codex: flatFile({
+        subdir: ['.codex', 'agents'],
+        ext: '.toml',
+        transform: transformSubagentForCodex,
+        readMeta: metaToml,
+    }),
     opencode: flatFile({
         subdir: ['.config', 'opencode', 'agents'],
         ext: '.md',
@@ -295,8 +264,12 @@ export const SUBAGENT_TARGETS = {
         transform: transformSubagentForAntigravity,
     }),
     openclaw: dirCopy({ subdir: ['.openclaw'], marker: 'AGENTS.md', rename: { 'AGENT.md': 'AGENTS.md' } }),
-    // Bespoke multi-file + parent index.
-    kimi: kimiTarget,
+    // Kimi discovers Claude-shaped agent markdown from its brand home's `agents/`
+    // dir (`USER_BRAND_DIRS = ["agents"]`, kimi-code >= 0.29.0). Frontmatter
+    // name/description + body, kebab-case name -- the same shape as claude/grok.
+    // The pre-markdown files agents-cli used to write here are swept once by
+    // `migrateKimiSubagentsToMarkdown` (lib/migrate.ts), not by this target.
+    kimi: flatFile({ subdir: ['.kimi-code', 'agents'], ext: '.md', transform: transformSubagentForClaude, readMeta: metaFrontmatterFallback }),
 };
 /** The registry entry for `agent`, or undefined if it stores no subagents. */
 export function subagentTarget(agent) {

package/dist/lib/subagents.d.ts

@@ -97,39 +97,6 @@ export declare function transformSubagentForAntigravity(subagentDir: string): st
  * https://opencode.ai/docs/agents/
  */
 export declare function transformSubagentForOpenCode(subagentDir: string): string;
-/** Managed parent agent file for Kimi (underscore prefix avoids clobbering a user subagent named agents-cli). */
-export declare const KIMI_SUBAGENTS_PARENT_FILE = "_agents-cli.yaml";
-export interface KimiSubagentFiles {
-    /** Agent YAML content (uses system_prompt_path, not inline system_prompt). */
-    yaml: string;
-    /** Markdown body written next to the YAML and referenced by system_prompt_path. */
-    systemPrompt: string;
-    /** Sibling prompt filename, e.g. `reviewer.system.md`. */
-    systemPromptFileName: string;
-}
-/**
- * Transform a subagent into Kimi Code agent files.
- *
- * Kimi's schema (agentspec) only accepts `system_prompt_path` (path relative to
- * the agent YAML) — there is no inline `system_prompt` key. We write:
- *   ~/.kimi-code/agents/<name>.yaml          — agent YAML
- *   ~/.kimi-code/agents/<name>.system.md     — system prompt body
- * plus a managed parent `_agents-cli.yaml` that lists them under agent.subagents
- * for `kimi --agent-file …/_agents-cli.yaml`.
- * https://moonshotai.github.io/kimi-cli/en/customization/agents.html
- */
-export declare function transformSubagentForKimi(subagentDir: string, fileBaseName: string): KimiSubagentFiles;
-/**
- * Build the managed parent agent YAML that declares all installed subagents
- * so `kimi --agent-file ~/.kimi-code/agents/_agents-cli.yaml` can launch them.
- */
-export declare function buildKimiSubagentsParentYaml(entries: Array<{
-    name: string;
-    description: string;
-    relativePath: string;
-}>): string;
-/** Write a Kimi subagent YAML + sibling system-prompt md into agentsDir. */
-export declare function writeKimiSubagentFiles(agentsDir: string, subagentDir: string, name: string): void;
 /**
  * Transform a subagent into a Codex custom-agent TOML file.
  *