@phnx-labs/agents-cli 1.20.57 → 1.20.59

package/dist/lib/permissions.js

@@ -440,6 +440,37 @@ export function convertToClaudeFormat(set) {
     }
     return { permissions };
 }
+/**
+ * Map a canonical rule to Cursor CLI syntax.
+ * Cursor uses Shell(...) instead of Bash(...); other tools keep TitleCase names.
+ * https://cursor.com/docs/cli/reference/permissions
+ */
+function canonicalToCursorRule(perm) {
+    if (perm === 'Bash' || perm.startsWith('Bash(')) {
+        return perm.replace(/^Bash/, 'Shell');
+    }
+    // Canonical WebSearch maps to WebFetch family for network allow.
+    if (perm.startsWith('WebSearch(')) {
+        return perm.replace(/^WebSearch/, 'WebFetch');
+    }
+    // Cursor has no Edit prefix — file writes use Write(...).
+    if (perm === 'Edit' || perm.startsWith('Edit(')) {
+        return perm.replace(/^Edit/, 'Write');
+    }
+    return perm;
+}
+/**
+ * Convert canonical permission set to Cursor CLI format
+ * (`~/.cursor/cli-config.json` permissions.allow/deny).
+ */
+export function convertToCursorFormat(set) {
+    return {
+        permissions: {
+            allow: set.allow.map(canonicalToCursorRule),
+            deny: (set.deny ?? []).map(canonicalToCursorRule),
+        },
+    };
+}
 /**
  * Parse canonical permission pattern to extract tool and pattern.
  * "Bash(git *)" -> { tool: "bash", pattern: "git *" }
@@ -494,6 +525,26 @@ function normalizeBashPattern(pattern) {
         return pattern.slice(0, -2) + ' *';
     return pattern;
 }
+/** Convert canonical Bash rules into Droid's command arrays. */
+export function convertToDroidFormat(set) {
+    const commands = (permissions) => {
+        const result = new Set();
+        for (const permission of permissions) {
+            if (BLANKET_BASH_FORMS.has(permission)) {
+                result.add('*');
+                continue;
+            }
+            const parsed = parseCanonicalPattern(permission);
+            if (parsed?.tool === 'bash')
+                result.add(normalizeBashPattern(parsed.pattern));
+        }
+        return Array.from(result);
+    };
+    return {
+        commandAllowlist: commands(set.allow),
+        commandDenylist: commands(set.deny ?? []),
+    };
+}
 /**
  * Convert canonical permission set to Antigravity format.
  * Antigravity reads ~/.gemini/antigravity-cli/settings.json with
@@ -592,6 +643,57 @@ function canonicalToGrokRule(perm, action) {
     }
     return { action, tool, pattern };
 }
+/**
+ * Convert canonical permissions to Kiro CLI v3 capability rules.
+ * Kiro stores these rules in ~/.kiro/settings/permissions.yaml.
+ */
+export function convertToKiroFormat(set) {
+    const rules = [];
+    for (const perm of set.allow) {
+        const rule = canonicalToKiroRule(perm, 'allow');
+        if (rule)
+            rules.push(rule);
+    }
+    for (const perm of set.deny ?? []) {
+        const rule = canonicalToKiroRule(perm, 'deny');
+        if (rule)
+            rules.push(rule);
+    }
+    return { rules };
+}
+function canonicalToKiroRule(perm, effect) {
+    if (BLANKET_BASH_FORMS.has(perm)) {
+        return { capability: 'shell', effect };
+    }
+    const parsed = parseCanonicalPreserveCase(perm);
+    const capability = KIRO_CAPABILITY_BY_TOOL[parsed.tool.toLowerCase()];
+    if (!capability)
+        return null;
+    if (parsed.pattern === null || parsed.pattern === '*' || parsed.pattern === '**') {
+        return { capability, effect };
+    }
+    const lowerTool = parsed.tool.toLowerCase();
+    const pattern = lowerTool === 'bash'
+        ? normalizeBashPattern(parsed.pattern)
+        : (lowerTool === 'webfetch' || lowerTool === 'websearch') && parsed.pattern.startsWith('domain:')
+            ? parsed.pattern.slice('domain:'.length)
+            : parsed.pattern;
+    return { capability, effect, match: [pattern] };
+}
+const KIRO_CAPABILITY_BY_TOOL = {
+    bash: 'shell',
+    read: 'fs_read',
+    grep: 'fs_read',
+    glob: 'fs_read',
+    write: 'fs_write',
+    edit: 'fs_write',
+    notebookedit: 'fs_write',
+    webfetch: 'web_fetch',
+    websearch: 'web_search',
+    mcp: 'mcp',
+    subagent: 'subagent',
+    skill: 'skill',
+};
 /**
  * Parse a canonical permission string preserving the tool's original casing.
  * `parseCanonicalPattern` lowercases the tool name, which is fine for Grok
@@ -837,9 +939,7 @@ function readClaudePermissions(scope = 'user', cwd, options) {
  */
 function readOpenCodePermissions(scope = 'user', cwd, options) {
     const home = options?.home || HOME;
-    const configPath = scope === 'user'
-        ? path.join(home, '.opencode', 'opencode.jsonc')
-        : path.join(cwd || process.cwd(), '.opencode', 'opencode.jsonc');
+    const configPath = openCodeConfigPath(scope, cwd, home);
     if (!fs.existsSync(configPath)) {
         return null;
     }
@@ -949,14 +1049,36 @@ export function applyClaudePermissions(set, scope = 'user', cwd, merge = true) {
         return { success: false, error: err.message };
     }
 }
+/**
+ * Path OpenCode actually loads for global config:
+ *   ~/.config/opencode/opencode.jsonc  (or .json)
+ * Project: <cwd>/opencode.jsonc (or .json) at project root — not .opencode/.
+ * See https://opencode.ai/docs/config/
+ */
+export function openCodeConfigPath(scope, cwd, home = HOME) {
+    if (scope === 'project') {
+        const root = cwd || process.cwd();
+        for (const name of ['opencode.jsonc', 'opencode.json']) {
+            const candidate = path.join(root, name);
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+        return path.join(root, 'opencode.jsonc');
+    }
+    const globalDir = path.join(home, '.config', 'opencode');
+    for (const name of ['opencode.jsonc', 'opencode.json']) {
+        const candidate = path.join(globalDir, name);
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return path.join(globalDir, 'opencode.jsonc');
+}
 /**
  * Apply a permission set to OpenCode's opencode.jsonc.
  */
 function applyOpenCodePermissions(set, scope = 'user', cwd, merge = true) {
-    const configDir = scope === 'user'
-        ? path.join(HOME, '.opencode')
-        : path.join(cwd || process.cwd(), '.opencode');
-    const configPath = path.join(configDir, 'opencode.jsonc');
+    const configPath = openCodeConfigPath(scope, cwd);
+    const configDir = path.dirname(configPath);
     try {
         // Ensure directory exists
         if (!fs.existsSync(configDir)) {
@@ -1090,7 +1212,10 @@ export function applyPermissionsToVersion(agentId, set, versionHome, merge = tru
             return { success: true };
         }
         if (agentId === 'opencode') {
-            const configPath = path.join(configDir, 'opencode.jsonc');
+            // OpenCode loads ~/.config/opencode/opencode.jsonc under the version home
+            // (HOME isolation), not ~/.opencode/opencode.jsonc.
+            const configPath = openCodeConfigPath('user', undefined, versionHome);
+            fs.mkdirSync(path.dirname(configPath), { recursive: true });
             let config = {};
             if (fs.existsSync(configPath)) {
                 const content = stripJsonComments(fs.readFileSync(configPath, 'utf-8'));
@@ -1258,6 +1383,82 @@ export function applyPermissionsToVersion(agentId, set, versionHome, merge = tru
             fs.writeFileSync(configPath, TOML.stringify(config), 'utf-8');
             return { success: true };
         }
+        if (agentId === 'cursor') {
+            // Cursor CLI permissions live in ~/.cursor/cli-config.json
+            const configPath = path.join(configDir, 'cli-config.json');
+            let config = {};
+            if (fs.existsSync(configPath)) {
+                try {
+                    config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+                }
+                catch { /* start fresh */ }
+            }
+            const converted = convertToCursorFormat(set);
+            if (merge && config.permissions && typeof config.permissions === 'object') {
+                const existing = config.permissions;
+                const allow = new Set([...(existing.allow || []), ...converted.permissions.allow]);
+                const deny = new Set([...(existing.deny || []), ...converted.permissions.deny]);
+                config.permissions = { allow: [...allow], deny: [...deny] };
+            }
+            else {
+                config.permissions = converted.permissions;
+            }
+            fs.mkdirSync(path.dirname(configPath), { recursive: true });
+            fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+            return { success: true };
+        }
+        if (agentId === 'droid') {
+            const configPath = path.join(versionHome, '.factory', 'settings.json');
+            let config = {};
+            if (fs.existsSync(configPath)) {
+                config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+            }
+            const converted = convertToDroidFormat(set);
+            if (merge) {
+                const existingAllow = Array.isArray(config.commandAllowlist) ? config.commandAllowlist : [];
+                const existingDeny = Array.isArray(config.commandDenylist) ? config.commandDenylist : [];
+                config.commandAllowlist = Array.from(new Set([...existingAllow, ...converted.commandAllowlist]));
+                config.commandDenylist = Array.from(new Set([...existingDeny, ...converted.commandDenylist]));
+            }
+            else {
+                config.commandAllowlist = converted.commandAllowlist;
+                config.commandDenylist = converted.commandDenylist;
+            }
+            fs.mkdirSync(path.dirname(configPath), { recursive: true });
+            fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+            return { success: true };
+        }
+        if (agentId === 'kiro') {
+            const permissionsPath = path.join(versionHome, '.kiro', 'settings', 'permissions.yaml');
+            let config = {};
+            if (fs.existsSync(permissionsPath)) {
+                const parsed = yaml.parse(fs.readFileSync(permissionsPath, 'utf-8'));
+                if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                    config = parsed;
+                }
+            }
+            const newRules = convertToKiroFormat(set).rules;
+            if (merge) {
+                const existingRules = Array.isArray(config.rules) ? config.rules : [];
+                const seen = new Set();
+                config.rules = [...existingRules, ...newRules].filter((rule) => {
+                    if (!rule || typeof rule !== 'object' || Array.isArray(rule))
+                        return false;
+                    const record = rule;
+                    const key = `${String(record.effect)}|${String(record.capability)}|${JSON.stringify(record.match ?? [])}|${JSON.stringify(record.exclude ?? [])}`;
+                    if (seen.has(key))
+                        return false;
+                    seen.add(key);
+                    return true;
+                });
+            }
+            else {
+                config.rules = newRules;
+            }
+            fs.mkdirSync(path.dirname(permissionsPath), { recursive: true });
+            fs.writeFileSync(permissionsPath, yaml.stringify(config), 'utf-8');
+            return { success: true };
+        }
         return { success: false, error: `Agent '${agentId}' does not support permissions` };
     }
     catch (err) {
@@ -1359,7 +1560,7 @@ export function exportPermissionsFromPath(filePath) {
     if (fileName === 'settings.json' && parentDir === '.claude') {
         agentId = 'claude';
     }
-    else if (fileName === 'opencode.jsonc' || parentDir === '.opencode') {
+    else if (fileName === 'opencode.jsonc' || fileName === 'opencode.json' || parentDir === 'opencode' || parentDir === '.opencode') {
         agentId = 'opencode';
     }
     else if (fileName === 'config.toml' && parentDir === '.codex') {

package/dist/lib/project-root.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Projects-root resolution for the `agents run --project <slug>` shorthand.
+ *
+ * Projects follow a predictable layout — `<root>/<repo>` (e.g.
+ * `~/src/github.com/<user>/<repo>`), with git worktrees under
+ * `<repo>/.agents/worktrees/<slug>`. The root is auto-inferred from the repo you
+ * launch inside (the directory ABOVE the git root) and cached in `agents.yaml`
+ * so later runs resolve a bare slug from anywhere. It is stored home-relative
+ * (`~/…`) when it sits under `$HOME`, so the SAME value resolves on a remote
+ * host whose home differs (`/home/<user>` vs `/Users/<user>`): a `--host` run
+ * keeps the `~` and lets the remote login shell expand it (see `remoteCdPrefix`
+ * in `hosts/dispatch.ts`), while a local run expands `~` against the local home.
+ */
+/** Rewrite an absolute path under the local home to a `~/`-relative string; pass others through. */
+export declare function toHomeRelative(abs: string): string;
+/** Expand a leading `~`/`$HOME` against the LOCAL home. Other paths pass through unchanged. */
+export declare function expandLocalHome(p: string): string;
+/**
+ * Make a `--cwd`/`--project` value portable to a remote host: an absolute path
+ * under the LOCAL home (which the local shell already expanded from `~`) becomes
+ * `~/…` so the *remote* shell re-roots it at its own home. Paths already anchored
+ * at `~`/`$HOME` pass through; other absolute or relative paths are left as-is
+ * (used verbatim on the host). Explicit `--remote-cwd` is NOT run through this —
+ * it is a literal remote path by contract.
+ */
+export declare function toRemotePortable(p: string): string;
+/** The configured projects root (home-relative or absolute), or undefined when unset. */
+export declare function getProjectRoot(): string | undefined;
+/** Set (override) the cached projects root. Stored home-relative when under `$HOME`. */
+export declare function setProjectRoot(rootPath: string): string;
+/**
+ * Infer the projects root from `cwd`: the directory ABOVE the git repo root
+ * (cwd inside `~/src/github.com/user/repo` → `~/src/github.com/user`). Returns a
+ * home-relative string when under `$HOME`; undefined when `cwd` is not in a repo.
+ */
+export declare function inferProjectRoot(cwd: string): Promise<string | undefined>;
+/**
+ * Resolve the projects root, auto-inferring and caching on first use. Throws an
+ * actionable error when it is neither configured nor inferrable from `cwd`.
+ */
+export declare function ensureProjectRoot(cwd: string): Promise<string>;
+export interface ProjectRef {
+    slug: string;
+    worktree?: string;
+}
+/** Parse a `--project` value of the form `<slug>[@<worktree>]`. */
+export declare function parseProjectRef(ref: string): ProjectRef;
+/**
+ * Join a root + `--project` ref into a working directory. Pure (no I/O) so the
+ * slug/worktree layout is unit-testable. `forRemote` keeps the path
+ * home-relative (`~/…`) for the remote shell to expand; otherwise it is expanded
+ * against the local home into an absolute path.
+ */
+export declare function buildProjectPath(root: string, ref: string, forRemote: boolean): string;
+/**
+ * Resolve a `--project` ref to a working directory, inferring/caching the root.
+ *
+ * `forRemote: true` returns a home-relative path (`~/…`) so the REMOTE login
+ * shell expands `~`/`$HOME` to its own home. `forRemote: false` returns an
+ * absolute local path and verifies it exists (so a mistyped slug fails loudly).
+ */
+export declare function resolveProjectRef(ref: string, opts: {
+    forRemote: boolean;
+    cwd?: string;
+}): Promise<string>;

package/dist/lib/project-root.js

@@ -0,0 +1,134 @@
+/**
+ * Projects-root resolution for the `agents run --project <slug>` shorthand.
+ *
+ * Projects follow a predictable layout — `<root>/<repo>` (e.g.
+ * `~/src/github.com/<user>/<repo>`), with git worktrees under
+ * `<repo>/.agents/worktrees/<slug>`. The root is auto-inferred from the repo you
+ * launch inside (the directory ABOVE the git root) and cached in `agents.yaml`
+ * so later runs resolve a bare slug from anywhere. It is stored home-relative
+ * (`~/…`) when it sits under `$HOME`, so the SAME value resolves on a remote
+ * host whose home differs (`/home/<user>` vs `/Users/<user>`): a `--host` run
+ * keeps the `~` and lets the remote login shell expand it (see `remoteCdPrefix`
+ * in `hosts/dispatch.ts`), while a local run expands `~` against the local home.
+ */
+import * as os from 'os';
+import * as path from 'path';
+import * as fs from 'fs';
+import { readMeta, updateMeta } from './state.js';
+import { getMainRepoRoot } from './git.js';
+import { toPosix } from './platform/index.js';
+const HOME = process.env.HOME ?? os.homedir();
+/** Rewrite an absolute path under the local home to a `~/`-relative string; pass others through. */
+export function toHomeRelative(abs) {
+    const rel = path.relative(HOME, abs);
+    if (rel === '')
+        return '~';
+    if (!rel.startsWith('..') && !path.isAbsolute(rel))
+        return `~/${toPosix(rel)}`;
+    return abs;
+}
+/** Expand a leading `~`/`$HOME` against the LOCAL home. Other paths pass through unchanged. */
+export function expandLocalHome(p) {
+    if (p === '~' || p === '$HOME')
+        return HOME;
+    if (p.startsWith('~/'))
+        return path.join(HOME, p.slice(2));
+    if (p.startsWith('$HOME/'))
+        return path.join(HOME, p.slice(6));
+    return p;
+}
+/**
+ * Make a `--cwd`/`--project` value portable to a remote host: an absolute path
+ * under the LOCAL home (which the local shell already expanded from `~`) becomes
+ * `~/…` so the *remote* shell re-roots it at its own home. Paths already anchored
+ * at `~`/`$HOME` pass through; other absolute or relative paths are left as-is
+ * (used verbatim on the host). Explicit `--remote-cwd` is NOT run through this —
+ * it is a literal remote path by contract.
+ */
+export function toRemotePortable(p) {
+    if (p.startsWith('~') || p.startsWith('$HOME'))
+        return p;
+    if (path.isAbsolute(p))
+        return toHomeRelative(p);
+    return p;
+}
+/** The configured projects root (home-relative or absolute), or undefined when unset. */
+export function getProjectRoot() {
+    return readMeta().projectRoot;
+}
+/** Set (override) the cached projects root. Stored home-relative when under `$HOME`. */
+export function setProjectRoot(rootPath) {
+    const stored = toHomeRelative(path.resolve(expandLocalHome(rootPath)));
+    updateMeta({ projectRoot: stored });
+    return stored;
+}
+/**
+ * Infer the projects root from `cwd`: the directory ABOVE the git repo root
+ * (cwd inside `~/src/github.com/user/repo` → `~/src/github.com/user`). Returns a
+ * home-relative string when under `$HOME`; undefined when `cwd` is not in a repo.
+ */
+export async function inferProjectRoot(cwd) {
+    try {
+        const mainRoot = await getMainRepoRoot(cwd);
+        return toHomeRelative(path.dirname(mainRoot));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve the projects root, auto-inferring and caching on first use. Throws an
+ * actionable error when it is neither configured nor inferrable from `cwd`.
+ */
+export async function ensureProjectRoot(cwd) {
+    const existing = getProjectRoot();
+    if (existing)
+        return existing;
+    const inferred = await inferProjectRoot(cwd);
+    if (!inferred) {
+        throw new Error('Could not determine your projects root. Run once from inside a project ' +
+            '(a git repo under your projects dir) so it can be inferred, or set it:\n' +
+            '  agents defaults project-root ~/src/github.com/<you>');
+    }
+    updateMeta({ projectRoot: inferred });
+    process.stderr.write(`[project] cached projects root: ${inferred}\n`);
+    return inferred;
+}
+/** Parse a `--project` value of the form `<slug>[@<worktree>]`. */
+export function parseProjectRef(ref) {
+    const at = ref.indexOf('@');
+    if (at === -1)
+        return { slug: ref };
+    return { slug: ref.slice(0, at), worktree: ref.slice(at + 1) || undefined };
+}
+/**
+ * Join a root + `--project` ref into a working directory. Pure (no I/O) so the
+ * slug/worktree layout is unit-testable. `forRemote` keeps the path
+ * home-relative (`~/…`) for the remote shell to expand; otherwise it is expanded
+ * against the local home into an absolute path.
+ */
+export function buildProjectPath(root, ref, forRemote) {
+    const { slug, worktree } = parseProjectRef(ref);
+    if (!slug)
+        throw new Error(`Invalid --project value: "${ref}"`);
+    let rel = `${root}/${slug}`;
+    if (worktree)
+        rel += `/.agents/worktrees/${worktree}`;
+    return forRemote ? rel : path.resolve(expandLocalHome(rel));
+}
+/**
+ * Resolve a `--project` ref to a working directory, inferring/caching the root.
+ *
+ * `forRemote: true` returns a home-relative path (`~/…`) so the REMOTE login
+ * shell expands `~`/`$HOME` to its own home. `forRemote: false` returns an
+ * absolute local path and verifies it exists (so a mistyped slug fails loudly).
+ */
+export async function resolveProjectRef(ref, opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    const root = await ensureProjectRoot(cwd);
+    const resolved = buildProjectPath(root, ref, opts.forRemote);
+    if (!opts.forRemote && !fs.existsSync(resolved)) {
+        throw new Error(`Project path not found: ${resolved}`);
+    }
+    return resolved;
+}

package/dist/lib/resources/mcp.js

@@ -111,7 +111,7 @@ export function getMcpConfigPath(agent, versionHome) {
         case 'codex':
             return path.join(versionHome, '.codex', 'config.toml');
         case 'opencode':
-            return path.join(versionHome, '.opencode', 'opencode.jsonc');
+            return path.join(versionHome, '.config', 'opencode', 'opencode.jsonc');
         case 'cursor':
             return path.join(versionHome, '.cursor', 'mcp.json');
         case 'gemini':

package/dist/lib/resources/permissions.js

@@ -66,9 +66,13 @@ function getAgentConfigPath(agent, versionHome) {
         case 'codex':
             return path.join(versionHome, '.codex', 'config.toml');
         case 'opencode':
-            return path.join(versionHome, '.opencode', 'opencode.jsonc');
+            return path.join(versionHome, '.config', 'opencode', 'opencode.jsonc');
         case 'kimi':
             return path.join(versionHome, '.kimi-code', 'config.toml');
+        case 'droid':
+            return path.join(versionHome, '.factory', 'settings.json');
+        case 'kiro':
+            return path.join(versionHome, '.kiro', 'settings', 'permissions.yaml');
         default:
             return null;
     }

package/dist/lib/resources/skills.js

@@ -5,7 +5,7 @@
  * Format is the same for all agents. Resolution order: project > user > system.
  */
 import * as fs from 'fs';
-import { agentConfigDirName } from '../agents.js';
+import { AGENTS, agentConfigDirName } from '../agents.js';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { getSystemSkillsDir, getUserSkillsDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../state.js';
@@ -201,6 +201,11 @@ export function createSkillsHandler(provider = defaultProvider) {
             return null;
         },
         sync(agent, versionHome, cwd) {
+            // Agents that read directly from central ~/.agents/skills/ (e.g. Gemini,
+            // Goose via the Summon extension) should not get a per-version copy.
+            if (AGENTS[agent]?.nativeAgentsSkillsDir) {
+                return;
+            }
             const targetDir = path.join(versionHome, agentConfigDirName(agent), 'skills');
             // Ensure target directory exists
             if (!fs.existsSync(targetDir)) {

package/dist/lib/resources/types.d.ts

@@ -5,7 +5,7 @@
  * - Union: All resources from all layers are combined
  * - Override on name conflict: Higher layer wins (project > user > system)
  */
-export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'antigravity' | 'grok' | 'kimi' | 'hermes' | 'forge';
+export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'kiro' | 'antigravity' | 'grok' | 'kimi' | 'droid' | 'hermes' | 'forge';
 export type Layer = 'system' | 'user' | 'project';
 export type ResourceKind = 'command' | 'hook' | 'skill' | 'rule' | 'mcp' | 'permission' | 'subagent' | 'workflow' | 'memory';
 /** A resolved resource with its origin layer. */

package/dist/lib/secrets/agent.d.ts

@@ -74,23 +74,23 @@ export interface AgentStatusEntry {
     expiresAt: number;
     keyCount: number;
 }
-/** True if the launchd plist for the persistent broker is installed. */
+/** True if a legacy standalone-broker launchd plist is still installed. */
 export declare function secretsAgentServiceInstalled(): boolean;
 /**
- * Install + start the persistent broker as a launchd user service (idempotent).
- * Writes the plist, bootstraps it into the GUI domain, and waits for the socket.
- * `ProcessType: Interactive` asks launchd to schedule it at foreground priority
- * so it can boot even when the machine is loaded. Returns true once reachable.
+ * Retire the legacy standalone secrets-agent launchd service: bootout the job
+ * (falling back to the legacy `unload`) and remove its plist so the always-on
+ * daemon owns the broker socket. Idempotent and best-effort — a no-op when no
+ * legacy plist is present. Does NOT wipe held bundles: the booted-out process's
+ * memory is gone anyway, and the daemon-hosted broker starts fresh.
  */
-export declare function installSecretsAgentService(timeoutMs?: number): Promise<boolean>;
+export declare function retireLegacySecretsAgentService(): void;
 /**
- * Kickstart the already-installed persistent broker so launchd relaunches it
- * onto the current on-disk code. Used by postinstall heal-on-upgrade. No-op if
- * the service isn't installed; never rewrites the plist or waits, so it's safe
- * and fast to call from an installer.
+ * Stop the persistent broker for `agents secrets stop`: wipe whatever the broker
+ * holds (forces Touch ID again on the next read), then retire any legacy
+ * standalone service. The daemon-hosted broker itself is left running — it is
+ * the always-on backbone, and stopping it would take down unrelated background
+ * work (routines, browser IPC, session-sync).
  */
-export declare function kickstartSecretsAgentService(): void;
-/** Stop + remove the persistent broker service, and wipe whatever it held. */
 export declare function uninstallSecretsAgentService(): Promise<void>;
 export type Request = {
     cmd: 'ping';
@@ -171,7 +171,9 @@ export declare function shouldWipeOnWatchEvent(chunk: string): boolean;
  */
 export declare function runSecretsAgent(opts?: {
     service?: boolean;
-}): Promise<void>;
+}): Promise<{
+    close(): void;
+} | null>;
 /**
  * Host the secrets broker inside the always-on daemon (#416).
  *
@@ -184,11 +186,11 @@ export declare function runSecretsAgent(opts?: {
  *     (those would kill the daemon — the daemon is the always-on backbone and
  *     manages its own version/lifecycle). The sweep only TTL-evicts.
  *
- * The caller (`runDaemon`) must only invoke this when NO broker is already
- * reachable (ping first) — this function clears a stale socket before binding,
- * so calling it while a live standalone broker holds the socket would orphan
- * that broker's clients. Returns a handle the daemon closes on shutdown, or
- * null off-darwin (nothing to broker without biometry).
+ * The caller (`runDaemon`) normally invokes this only when no broker answers
+ * its initial ping. Binding still arbitrates ownership through the same shared
+ * path as the standalone service: a live owner wins, while only an unreachable
+ * stale socket is reclaimed. Returns a handle the daemon closes on shutdown,
+ * or null off-darwin (nothing to broker without biometry).
  */
 export declare function startHostedBroker(): Promise<{
     close(): void;
@@ -277,10 +279,11 @@ export declare function agentPing(): Promise<{
  * Ensure a broker is running and reachable. Returns true once the socket answers
  * a ping. macOS only.
  *
- * Prefers the persistent launchd service: if it isn't installed we install it
- * (which makes the broker survive for the whole login session, so subsequent
- * reads never cold-start); if it's installed but unreachable we kickstart it.
- * Only when the service path can't be used do we fall back to a one-off detached
- * broker — that's the model that gets starved under heavy load, so it's last.
+ * Prefers the always-on daemon, which hosts the broker socket (#416): retire any
+ * legacy standalone launchd service so the daemon owns the socket, then bring the
+ * daemon up (Path 0) — one supervised backbone that survives the whole login
+ * session, so subsequent reads never cold-start. Only when the daemon can't be
+ * used do we fall back to a one-off detached broker (Path 1) — the model that
+ * gets starved under heavy load, so it's last.
  */
 export declare function ensureAgentRunning(timeoutMs?: number): Promise<boolean>;