@phnx-labs/agents-cli 1.20.63 → 1.20.64

package/dist/lib/session/sync/sync.js

@@ -18,10 +18,10 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { R2Client } from './r2.js';
 import { loadR2Config, machineId } from './config.js';
-import { SYNC_AGENTS, listLocalTranscripts, localSessionIds, mirrorPath, objectKey, manifestKey, SESSIONS_PREFIX, } from './agents.js';
+import { SYNC_AGENTS, listLocalTranscripts, localSessionIds, mirrorPath, objectKey, manifestKey, isMergeableFile, SESSIONS_PREFIX, } from './agents.js';
 import { mergeTranscripts, transcriptStats } from './crdt.js';
 import { resolveSyncEncKey, encryptTranscript, decryptTranscriptBody } from './transcript-crypto.js';
-import { emptyManifest, parseManifest, hashContent, loadLedger, saveLedger, ledgerUnchanged, ledgerRecord, loadLocalManifest, saveLocalManifest, loadPullState, savePullState, sourceSignature, } from './manifest.js';
+import { emptyManifest, parseManifest, hashContent, loadLedger, saveLedger, ledgerUnchanged, ledgerRecord, loadLocalManifest, saveLocalManifest, loadPullState, savePullState, sourceSignature, manifestEntries, } from './manifest.js';
 const nowIso = () => new Date().toISOString();
 function specById(id) {
     return SYNC_AGENTS.find(s => s.id === id);
@@ -42,45 +42,59 @@ async function pushOwn(r2, me, encKey, opts, result) {
     for (const spec of SYNC_AGENTS) {
         const agentManifest = {};
         for (const t of listLocalTranscripts(spec)) {
-            let stat;
-            try {
-                stat = fs.statSync(t.absPath);
-            }
-            catch {
-                continue;
-            }
-            const prevEntry = prev?.agents?.[spec.id]?.[t.sessionId];
-            if (prevEntry && ledgerUnchanged(ledger, t.absPath, stat.size, stat.mtimeMs)) {
-                agentManifest[t.sessionId] = prevEntry; // unchanged: reuse, no read, no upload
-                result.pushSkipped++;
-                continue;
-            }
-            let content;
-            try {
-                content = fs.readFileSync(t.absPath, 'utf-8');
-            }
-            catch {
-                continue;
-            }
-            // Identity for CRDT merge is the PLAINTEXT hash (ciphertext is
-            // non-deterministic), so hash + manifest are computed on cleartext; only
-            // the stored object body is sealed.
-            const hash = hashContent(content);
-            const { lastTs } = transcriptStats(content);
-            const entry = { relKey: t.relKey, size: stat.size, hash, lastTs };
-            const body = encKey ? encryptTranscript(content, encKey) : content;
-            const contentType = encKey ? 'application/json' : 'application/x-ndjson';
-            try {
-                await r2.put(objectKey(me, spec.id, t.sessionId), body, contentType);
-                ledgerRecord(ledger, t.absPath, stat.size, stat.mtimeMs, hash);
-                agentManifest[t.sessionId] = entry;
-                result.pushed++;
-                if (opts.verbose)
-                    opts.log?.(`  push ${spec.id}/${t.sessionId.slice(0, 8)} (${stat.size}B)`);
-            }
-            catch (err) {
-                result.errors.push(`push ${spec.id}/${t.sessionId}: ${err.message}`);
+            // A session is one file (file-shaped) or many (dir-shaped). Push each file
+            // that changed, reusing the prior manifest entry (keyed by relKey) for the
+            // ones the ledger shows unchanged. Object keys nest under the session id for
+            // dir-shaped agents and stay flat for file-shaped ones (unchanged keys).
+            const prevVal = prev?.agents?.[spec.id]?.[t.sessionId];
+            const prevByRel = new Map((prevVal ? manifestEntries(prevVal) : []).map(e => [e.relKey, e]));
+            const entries = [];
+            for (const f of t.files) {
+                let stat;
+                try {
+                    stat = fs.statSync(f.absPath);
+                }
+                catch {
+                    continue;
+                }
+                const prevEntry = prevByRel.get(f.relKey);
+                if (prevEntry && ledgerUnchanged(ledger, f.absPath, stat.size, stat.mtimeMs)) {
+                    entries.push(prevEntry); // unchanged: reuse, no read, no upload
+                    result.pushSkipped++;
+                    continue;
+                }
+                let content;
+                try {
+                    content = fs.readFileSync(f.absPath, 'utf-8');
+                }
+                catch {
+                    continue;
+                }
+                // Identity for CRDT merge is the PLAINTEXT hash (ciphertext is
+                // non-deterministic), so hash + manifest are computed on cleartext; only
+                // the stored object body is sealed.
+                const hash = hashContent(content);
+                const lastTs = deriveLastTs(spec, f.relKey, content, stat.mtimeMs);
+                const entry = { relKey: f.relKey, size: stat.size, hash, lastTs };
+                const body = encKey ? encryptTranscript(content, encKey) : content;
+                const contentType = encKey ? 'application/json' : 'application/x-ndjson';
+                try {
+                    await r2.put(objectKey(me, spec.id, t.sessionId, spec.dirShaped ? f.relKey : undefined), body, contentType);
+                    ledgerRecord(ledger, f.absPath, stat.size, stat.mtimeMs, hash);
+                    entries.push(entry);
+                    result.pushed++;
+                    const label = spec.dirShaped ? `${t.sessionId.slice(0, 8)}/${f.relKey}` : t.sessionId.slice(0, 8);
+                    if (opts.verbose)
+                        opts.log?.(`  push ${spec.id}/${label} (${stat.size}B)`);
+                }
+                catch (err) {
+                    result.errors.push(`push ${spec.id}/${t.sessionId}/${f.relKey}: ${err.message}`);
+                }
             }
+            // File-shaped: store the single entry (byte-identical to the old format so
+            // older CLIs read it unchanged). Dir-shaped: store the per-file array.
+            if (entries.length > 0)
+                agentManifest[t.sessionId] = spec.dirShaped ? entries : entries[0];
         }
         if (Object.keys(agentManifest).length > 0)
             manifest.agents[spec.id] = agentManifest;
@@ -115,17 +129,60 @@ export function selectSessionsToFetch(copies, localIdsByAgent, pullState) {
     return pending;
 }
 /**
- * Resolve the mirror destination + merged content for one session. Pure.
+ * Resolve the mirror destination + reconciled content for ONE file across its
+ * copies (every copy here is the same file — same relKey — held by a different
+ * machine). Pure.
+ *
  * The canonical path comes from the lexicographically-smallest machine so every
- * puller derives an identical location; the content is the CRDT union of copies.
+ * puller derives an identical location. The content depends on the file's kind
+ * (see `isMergeableFile`):
+ *  - append-only logs (a transcript `.jsonl`) take the CRDT G-Set union — every
+ *    machine converges to byte-identical output regardless of order.
+ *  - mutable blobs (Kimi `state.json`) can't be line-unioned without corruption,
+ *    so they resolve **last-writer-wins**: the copy with the latest event
+ *    timestamp, tie-broken by content hash so the pick is deterministic fleet-wide.
  */
+/**
+ * The `lastTs` a manifest entry carries for one file. Append-only logs (a
+ * conversation `.jsonl`) embed per-line event timestamps, so their recency is
+ * the latest line timestamp (`transcriptStats`). Mutable blobs (Kimi
+ * `state.json`, the per-tool `tasks/*.json` sidecars) carry no event timestamp —
+ * their own `updatedAt`/`createdAt` fields are agent-specific and unreliable — so
+ * their "last written" signal is the file mtime. Without this, `transcriptStats`
+ * returns `''` for every blob and the last-writer-wins branch in
+ * `resolveMirrorWrite` silently degrades to "highest-hash-wins", which can pick a
+ * stale copy over the genuinely newer one.
+ */
+export function deriveLastTs(spec, relKey, content, mtimeMs) {
+    if (isMergeableFile(spec, relKey))
+        return transcriptStats(content).lastTs;
+    return new Date(mtimeMs).toISOString();
+}
 export function resolveMirrorWrite(spec, copies, contents) {
     const canonical = [...copies].sort((a, b) => (a.machine < b.machine ? -1 : a.machine > b.machine ? 1 : 0))[0];
-    const content = contents.length === 1 ? contents[0] : mergeTranscripts(contents);
+    let content;
+    if (contents.length === 1) {
+        content = contents[0];
+    }
+    else if (isMergeableFile(spec, canonical.entry.relKey)) {
+        content = mergeTranscripts(contents);
+    }
+    else {
+        // Last-writer-wins: highest (lastTs, hash) among the copies.
+        let win = 0;
+        for (let i = 1; i < copies.length; i++) {
+            const a = copies[i].entry, b = copies[win].entry;
+            if (a.lastTs > b.lastTs || (a.lastTs === b.lastTs && a.hash > b.hash))
+                win = i;
+        }
+        content = contents[win];
+    }
     return {
         dest: mirrorPath(spec, canonical.machine, canonical.entry.relKey),
         content,
-        merged: contents.length > 1,
+        // "merged" means an actual CRDT line-union happened — not a last-writer-wins
+        // pick of one mutable blob over another (that discards a copy, it doesn't merge).
+        merged: contents.length > 1 && isMergeableFile(spec, canonical.entry.relKey),
     };
 }
 /**
@@ -176,9 +233,13 @@ async function pullAndReconcile(r2, me, encKey, opts, result) {
             let byAgent = copies.get(agentId);
             if (!byAgent)
                 copies.set(agentId, (byAgent = new Map()));
-            for (const [sessionId, entry] of Object.entries(sessions)) {
+            for (const [sessionId, value] of Object.entries(sessions)) {
                 const list = byAgent.get(sessionId) ?? [];
-                list.push({ machine: m, entry });
+                // One RemoteCopy per (machine, file): file-shaped sessions contribute one,
+                // dir-shaped ones contribute an entry per constituent file. `manifestEntries`
+                // also normalizes a single-object entry written by an older CLI.
+                for (const entry of manifestEntries(value))
+                    list.push({ machine: m, entry });
                 byAgent.set(sessionId, list);
             }
         }
@@ -197,43 +258,85 @@ async function pullAndReconcile(r2, me, encKey, opts, result) {
     result.pullSkipped += candidates - pending.length; // local-owned or unchanged
     for (const { agentId, sessionId, copies: list, sig } of pending) {
         const spec = specById(agentId);
-        // Download each copy (could be a fork across >1 machine), keeping the
-        // result positionally aligned to `list` — null marks a copy we couldn't
-        // fetch this tick (404 / consistency lag / error).
-        const fetched = [];
+        // A dir-shaped session spans several files; reconcile each file independently
+        // (its copies across machines share one relKey). File-shaped sessions have a
+        // single group, so this collapses to the original one-file path.
+        const byRel = new Map();
         for (const c of list) {
-            try {
-                const body = await r2.get(objectKey(c.machine, agentId, sessionId));
-                // Decrypt before the body reaches the CRDT union — the merge and the
-                // mirror always operate on plaintext. A legacy plaintext object passes
-                // through untouched; an envelope without a key throws (surfaced below).
-                fetched.push(body === null ? null : decryptTranscriptBody(body, encKey));
-            }
-            catch (err) {
-                result.errors.push(`get ${c.machine}/${sessionId}: ${err.message}`);
-                fetched.push(null);
+            const g = byRel.get(c.entry.relKey);
+            if (g)
+                g.push(c);
+            else
+                byRel.set(c.entry.relKey, [c]);
+        }
+        // Resolve every file's write before touching disk. If ANY file's fetch is
+        // incomplete (a copy 404s / consistency lag), abandon the WHOLE session this
+        // tick — no writes, no pull-state stamp — so it retries intact next time
+        // rather than materializing half a session and stamping it done.
+        const writes = [];
+        let incomplete = false;
+        try {
+            for (const group of byRel.values()) {
+                const fetched = [];
+                for (const c of group) {
+                    try {
+                        const body = await r2.get(objectKey(c.machine, agentId, sessionId, spec.dirShaped ? c.entry.relKey : undefined));
+                        // Decrypt before the body reaches the CRDT union — merge + mirror always
+                        // operate on plaintext. A legacy plaintext object passes through
+                        // untouched; an envelope without a key throws (surfaced below).
+                        fetched.push(body === null ? null : decryptTranscriptBody(body, encKey));
+                    }
+                    catch (err) {
+                        result.errors.push(`get ${c.machine}/${sessionId}/${c.entry.relKey}: ${err.message}`);
+                        fetched.push(null);
+                    }
+                }
+                const resolved = reconcileCopies(spec, group, fetched);
+                if (!resolved) {
+                    incomplete = true;
+                    break;
+                }
+                writes.push(resolved);
             }
         }
-        // null ⇒ an incomplete fetch: skip the write AND the pull-state stamp so we
-        // retry next tick instead of persisting a partial union / abandoning a branch.
-        const resolved = reconcileCopies(spec, list, fetched);
-        if (!resolved)
+        catch (err) {
+            // `reconcileCopies` -> `mirrorPath` now rejects unsafe peer-controlled
+            // machine/relKey (C1 containment). That rejection must stay scoped to this
+            // one session: without this catch a single malicious/malformed manifest
+            // entry would throw out of the whole `pending` loop, skip the
+            // `savePullState` below, and re-throw every tick — a peer-triggered DoS on
+            // everyone else's session-sync. Record it and skip; never stamp pull-state
+            // for a rejected entry (so nothing marks the bad session "done").
+            result.errors.push(`resolve mirror ${agentId}/${sessionId}: ${err.message}`);
             continue;
-        const { dest, content, merged } = resolved;
+        }
+        if (incomplete)
+            continue; // retry next tick, session intact
         try {
-            let existing = null;
-            try {
-                existing = fs.readFileSync(dest, 'utf-8');
+            let changed = false;
+            let mergedAny = false;
+            for (const { dest, content, merged } of writes) {
+                let existing = null;
+                try {
+                    existing = fs.readFileSync(dest, 'utf-8');
+                }
+                catch { /* not present yet */ }
+                if (existing !== content) {
+                    fs.mkdirSync(path.dirname(dest), { recursive: true });
+                    fs.writeFileSync(dest, content, 'utf-8');
+                    changed = true;
+                    if (merged)
+                        mergedAny = true;
+                }
             }
-            catch { /* not present yet */ }
-            if (existing !== content) {
-                fs.mkdirSync(path.dirname(dest), { recursive: true });
-                fs.writeFileSync(dest, content, 'utf-8');
-                if (merged)
+            if (changed) {
+                if (mergedAny)
                     result.merged++;
                 result.pulled++;
                 if (opts.verbose) {
-                    opts.log?.(`  pull ${agentId}/${sessionId.slice(0, 8)} <- ${list.map(c => c.machine).join('+')}`);
+                    const machines = [...new Set(list.map(c => c.machine))].join('+');
+                    const files = byRel.size > 1 ? ` (${byRel.size} files)` : '';
+                    opts.log?.(`  pull ${agentId}/${sessionId.slice(0, 8)}${files} <- ${machines}`);
                 }
             }
             else {

package/dist/lib/ssh-tunnel.js

@@ -24,7 +24,7 @@ import { fileURLToPath } from 'url';
 import { randomBytes, createHash } from 'crypto';
 import { Readable } from 'stream';
 import { pipeline } from 'stream/promises';
-import { sshExec, SSH_OPTS } from './ssh-exec.js';
+import { sshExec, SSH_OPTS, assertValidSshTarget } from './ssh-exec.js';
 import { backgroundSpawnOptions } from './platform/process.js';
 import { encodePowerShell } from './browser/drivers/ssh.js';
 import { getDevice } from './devices/registry.js';
@@ -57,6 +57,18 @@ export function buildTunnelArgs(user, host, localPort, remotePort) {
  */
 export function startSSHTunnel(user, host, localPort, remotePort, opts = {}) {
     return new Promise((resolve, reject) => {
+        // `user`/`host` can originate from a browser ssh:// profile or a device
+        // record. buildTunnelArgs places `${user}@${host}` before `-N`/SSH_OPTS, so
+        // a `-`-leading user would be parsed as an ssh option flag (option
+        // injection). Validate at the spawn sink so every caller is covered; reject
+        // (rather than throw synchronously) to keep the Promise contract.
+        try {
+            assertValidSshTarget(`${user}@${host}`);
+        }
+        catch (err) {
+            reject(err);
+            return;
+        }
         const args = buildTunnelArgs(user, host, localPort, remotePort);
         const tunnel = spawn('ssh', args, {
             stdio: opts.detached ? 'ignore' : ['ignore', 'ignore', 'pipe'],

package/dist/lib/staleness/detectors/subagents.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Subagents detector. The installed-name enumeration for every agent's on-disk
+ * layout is declared once in the subagent registry; this detector is generic
+ * and delegates to `listInstalledSubagentNames` instead of a per-agent builder.
+ */
 import type { AgentId } from '../../types.js';
 import type { ResourceDetector } from './types.js';
 export declare const subagentsDetectors: Partial<Record<AgentId, ResourceDetector>>;

package/dist/lib/staleness/detectors/subagents.js

@@ -1,205 +1,18 @@
-/**
- * Subagents detector. Claude/Gemini/Grok: flat .md files under `<agentDir>/agents/`.
- * Codex: flat .toml files under `<versionHome>/.codex/agents/`.
- * Droid: flat .md files under `<versionHome>/.factory/droids/`.
- * Cursor: flat .md files under `<versionHome>/.cursor/agents/`.
- * ForgeCode: flat .md files under `<versionHome>/.forge/agents/`.
- * OpenClaw: subdirectories containing AGENTS.md under `<versionHome>/.openclaw/`.
- * Mirrors versions.ts:521-539.
- */
-import * as fs from 'fs';
-import * as path from 'path';
 import { capableAgents } from '../../capabilities.js';
+import { listInstalledSubagentNames } from '../../subagents-registry.js';
 import { lazyAgentMap } from '../writers/lazy-map.js';
-function buildFlatMdAgentsDetector(agent, agentsRoot) {
+function buildSubagentsDetector(agent) {
     return {
         kind: 'subagents',
         agent,
         list({ versionHome }) {
-            const agentsDir = path.join(versionHome, agentsRoot, 'agents');
-            if (!fs.existsSync(agentsDir))
-                return [];
-            return fs.readdirSync(agentsDir)
-                .filter(f => f.endsWith('.md'))
-                .map(f => f.replace('.md', ''));
+            return listInstalledSubagentNames(agent, versionHome);
         },
     };
 }
-function buildClaudeDetector() {
-    return buildFlatMdAgentsDetector('claude', '.claude');
-}
-function buildGrokDetector() {
-    return buildFlatMdAgentsDetector('grok', '.grok');
-}
-function buildGeminiDetector() {
-    return buildFlatMdAgentsDetector('gemini', '.gemini');
-}
-function buildCodexDetector() {
-    return {
-        kind: 'subagents',
-        agent: 'codex',
-        list({ versionHome }) {
-            const agentsDir = path.join(versionHome, '.codex', 'agents');
-            if (!fs.existsSync(agentsDir))
-                return [];
-            return fs.readdirSync(agentsDir)
-                .filter(f => f.endsWith('.toml'))
-                .map(f => f.replace(/\.toml$/, ''));
-        },
-    };
-}
-function buildDroidDetector() {
-    return {
-        kind: 'subagents',
-        agent: 'droid',
-        list({ versionHome }) {
-            const droidsDir = path.join(versionHome, '.factory', 'droids');
-            if (!fs.existsSync(droidsDir))
-                return [];
-            return fs.readdirSync(droidsDir)
-                .filter(f => f.endsWith('.md'))
-                .map(f => f.replace('.md', ''));
-        },
-    };
-}
-function buildCopilotDetector() {
-    return {
-        kind: 'subagents',
-        agent: 'copilot',
-        list({ versionHome }) {
-            const agentsDir = path.join(versionHome, '.copilot', 'agents');
-            if (!fs.existsSync(agentsDir))
-                return [];
-            return fs.readdirSync(agentsDir)
-                .filter(f => f.endsWith('.agent.md'))
-                .map(f => f.replace('.agent.md', ''));
-        },
-    };
-}
-function buildCursorDetector() {
-    return {
-        kind: 'subagents',
-        agent: 'cursor',
-        list({ versionHome }) {
-            const agentsDir = path.join(versionHome, '.cursor', 'agents');
-            if (!fs.existsSync(agentsDir))
-                return [];
-            return fs.readdirSync(agentsDir)
-                .filter(f => f.endsWith('.md'))
-                .map(f => f.replace(/\.md$/, ''));
-        },
-    };
-}
-function buildOpenclawDetector() {
-    return {
-        kind: 'subagents',
-        agent: 'openclaw',
-        list({ versionHome }) {
-            const openclawDir = path.join(versionHome, '.openclaw');
-            if (!fs.existsSync(openclawDir))
-                return [];
-            return fs.readdirSync(openclawDir, { withFileTypes: true })
-                .filter(d => d.isDirectory() && fs.existsSync(path.join(openclawDir, d.name, 'AGENTS.md')))
-                .map(d => d.name);
-        },
-    };
-}
-function buildKimiDetector() {
-    return {
-        kind: 'subagents',
-        agent: 'kimi',
-        list({ versionHome }) {
-            const agentsDir = path.join(versionHome, '.kimi-code', 'agents');
-            if (!fs.existsSync(agentsDir))
-                return [];
-            // Parent is `_agents-cli.yaml` (underscore-prefixed reserved name).
-            return fs.readdirSync(agentsDir)
-                .filter(f => f.endsWith('.yaml') && !f.startsWith('_'))
-                .map(f => f.replace(/\.yaml$/, ''));
-        },
-    };
-}
-function buildKiroDetector() {
-    return {
-        kind: 'subagents',
-        agent: 'kiro',
-        list({ versionHome }) {
-            const agentsDir = path.join(versionHome, '.kiro', 'agents');
-            if (!fs.existsSync(agentsDir))
-                return [];
-            return fs.readdirSync(agentsDir)
-                .filter(f => f.endsWith('.json'))
-                .map(f => f.replace(/\.json$/, ''));
-        },
-    };
-}
-function buildForgeDetector() {
-    return buildFlatMdAgentsDetector('forge', '.forge');
-}
-function buildGooseDetector() {
-    return {
-        kind: 'subagents',
-        agent: 'goose',
-        list({ versionHome }) {
-            const agentsDir = path.join(versionHome, '.config', 'goose', 'agents');
-            if (!fs.existsSync(agentsDir))
-                return [];
-            return fs.readdirSync(agentsDir)
-                .filter(f => f.endsWith('.yaml'))
-                .map(f => f.replace(/\.yaml$/, ''));
-        },
-    };
-}
-function buildOpenCodeDetector() {
-    return {
-        kind: 'subagents',
-        agent: 'opencode',
-        list({ versionHome }) {
-            const agentsDir = path.join(versionHome, '.config', 'opencode', 'agents');
-            if (!fs.existsSync(agentsDir))
-                return [];
-            return fs.readdirSync(agentsDir)
-                .filter(f => f.endsWith('.md'))
-                .map(f => f.replace(/\.md$/, ''));
-        },
-    };
-}
-function buildAntigravityDetector() {
-    return {
-        kind: 'subagents',
-        agent: 'antigravity',
-        list({ versionHome }) {
-            const agentsDir = path.join(versionHome, '.gemini', 'config', 'agents');
-            if (!fs.existsSync(agentsDir))
-                return [];
-            return fs.readdirSync(agentsDir, { withFileTypes: true })
-                .filter(d => d.isDirectory() && fs.existsSync(path.join(agentsDir, d.name, 'agent.md')))
-                .map(d => d.name);
-        },
-    };
-}
-const handlers = {
-    claude: buildClaudeDetector,
-    copilot: buildCopilotDetector,
-    gemini: buildGeminiDetector,
-    grok: buildGrokDetector,
-    codex: buildCodexDetector,
-    kimi: buildKimiDetector,
-    opencode: buildOpenCodeDetector,
-    antigravity: buildAntigravityDetector,
-    droid: buildDroidDetector,
-    openclaw: buildOpenclawDetector,
-    kiro: buildKiroDetector,
-    cursor: buildCursorDetector,
-    forge: buildForgeDetector,
-    goose: buildGooseDetector,
-};
 export const subagentsDetectors = lazyAgentMap(() => {
     const m = {};
-    for (const agent of capableAgents('subagents')) {
-        const f = handlers[agent];
-        if (f)
-            m[agent] = f();
-    }
+    for (const agent of capableAgents('subagents'))
+        m[agent] = buildSubagentsDetector(agent);
     return m;
 });

package/dist/lib/staleness/writers/subagents.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Subagents writer. Every agent's on-disk layout (target dir, file/dir shape,
+ * transform, and any post-sync finalize such as Kimi's parent index) is
+ * declared once in the subagent registry; this writer is generic and iterates
+ * the registry instead of a per-agent `else if` chain.
+ *
+ * Source-side discovery is `listInstalledSubagents` from lib/subagents.ts —
+ * it reads user + system layers only (project layer excluded for the same
+ * defense as commands/skills/hooks).
+ */
 import type { AgentId } from '../../types.js';
 import type { ResourceWriter } from './types.js';
 export declare const subagentsWriters: Partial<Record<AgentId, ResourceWriter<string[]>>>;