@phnx-labs/agents-cli 1.22.30 → 1.22.32

package/dist/commands/focus.js

@@ -32,7 +32,7 @@ const INHERITED_FOCUS_OPTIONS = [
     'local', 'host', 'device', 'active', 'agent',
     'claude', 'codex', 'kimi', 'antigravity', 'grok', 'opencode',
     'all', 'teams', 'inTeam', 'routine', 'project', 'skill', 'plugin',
-    'since', 'until', 'limit', 'favorites', 'unmanaged', 'sort',
+    'since', 'until', 'limit', 'bookmarks', 'unmanaged', 'sort',
     'working', 'idle', 'waiting', 'orphan', 'orphaned', 'crashed',
     'closed', 'abandoned', 'queued', 'unknown',
 ];
@@ -93,7 +93,7 @@ export function registerFocusCommand(program) {
         .option('--since <time>', 'Only sessions newer than this (for example 7d)')
         .option('--until <time>', 'Only sessions older than this timestamp')
         .option('-n, --limit <n>', 'Maximum candidates to load', '500')
-        .option('--favorites', 'Only favorited sessions')
+        .option('--bookmarks', 'Only bookmarked sessions')
         .option('--unmanaged', 'Also include native-home sessions outside managed versions')
         .option('--sort <field>', 'Order candidates by recent, cost, or duration', 'recent')
         .option('--working', 'Only live sessions currently doing work')
@@ -184,7 +184,7 @@ export async function focusAction(id, opts) {
             agent: agentSelector ?? focusOptionAgent(opts),
             teams: opts.teams === true,
             team: opts.inTeam,
-            favorites: opts.favorites === true,
+            bookmarks: opts.bookmarks === true,
             projectScope: opts.all || hosts.length > 0 || !!opts.project || idLookup ? 'all' : 'repo',
             project: opts.project,
             window: opts.since ?? (opts.all || idLookup ? undefined : '30d'),
@@ -304,7 +304,7 @@ function looksLikeIdentitySelector(selector) {
 function hasFocusFilters(opts, statuses) {
     return statuses.length > 0 || !!(opts.active || opts.local || opts.host?.length || opts.device?.length || focusOptionAgent(opts) ||
         opts.all || opts.teams || opts.inTeam || opts.routine || opts.project || opts.skill || opts.plugin ||
-        opts.since || opts.until || opts.favorites || opts.unmanaged || (opts.sort && opts.sort !== 'recent'));
+        opts.since || opts.until || opts.bookmarks || opts.unmanaged || (opts.sort && opts.sort !== 'recent'));
 }
 function focusSort(value) {
     if (!value || value === 'recent')
@@ -370,6 +370,21 @@ async function focusResolvedSession(meta, liveById, self, fallback, attachOnly)
     }
     await resumeSessionInPlace(meta);
 }
+/** Focus one row selected by the shared session browser through the same
+ * attach/recover decision as `agents sessions focus <id>`. */
+export async function focusSelectedSession(meta, active, self) {
+    if (active && !active.sessionId) {
+        if (isAttachableLiveSession(active)) {
+            await jumpTo(active, self, resumeInNewTab);
+            return;
+        }
+        console.log(chalk.yellow('This live session has no session id or living attach rail to focus.'));
+        process.exitCode = 1;
+        return;
+    }
+    const liveById = active ? new Map([[meta.id, active]]) : new Map();
+    await focusResolvedSession(meta, liveById, self, resumeInNewTab, false);
+}
 function activeFromMeta(meta) {
     return {
         context: 'headless',

package/dist/commands/routines.js

@@ -16,6 +16,7 @@ import { resolveAgentName, isAgentHardDeprecated, hardDeprecationError, ROUTINE_
 import { humanizeCron, humanizeNextRun, formatRepoLink, REPO_DISPLAY_MAX } from '../lib/routines-format.js';
 import { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, routineStats, getLatestRun, getRunDir, getJobPath, parseAtTime, hasCompletedOneShotRun, isOneShotLikeSchedule, isOneShotRoutine, isPastOneShotRoutine, jobRunsOnThisDevice, checkJobDeviceEligibility, normalizeTriggerEvent, parseHostStrategy, resolveHostStrategy, HOST_STRATEGIES, computeProjectGroup, computeProjectGroupKind, projectGroupKey, projectGroupTitle, projectGroupOrder, normalizeProjects, } from '../lib/routines.js';
 import { listProjectDefs, isSafeProjectName } from '../lib/projects.js';
+import { evaluateActivationReadinessLive } from '../lib/routine-readiness.js';
 import { discoverProjectRoutinesAt, enableProjectRoutines, disableProjectRoutines, syncProjectRoutines, syncAllProjectRoutines, listEnabledProjectRoots, resolveProjectRoot, displayProjectPath, listProjectRoutineFiles, } from '../lib/routines-project.js';
 import { fireWebhookJobs, matchJobsToWebhook } from '../lib/triggers/webhook.js';
 import { getRoutinesDir } from '../lib/state.js';
@@ -724,6 +725,8 @@ export function registerRoutinesCommands(program) {
         .option('--resume <sessionId>', 'At fire time, resume this existing session id (via `agents run <agent> --resume`) instead of starting fresh — the actual session reopens with full context and the prompt becomes its next turn. Powers self-scheduled wake-ups (e.g. /hibernate). Requires --agent claude or codex; runs un-sandboxed (the session store lives in the real home, not the job overlay).')
         .option('--project <name>', 'Associate with a named project (repeatable; use --all-projects for all)', collectProject, [])
         .option('--all-projects', 'Associate this routine with all defined projects (sets projects: ["*"])')
+        .option('--project-anchor <name>', 'Singular EXECUTION anchor: the named project whose base directory the run lands in (distinct from --project, which is grouping metadata). Rootless (Linear-imported) projects anchor a relative --cwd at the target home.')
+        .option('--cwd <path>', 'Portable execution directory. Relative values resolve under --project-anchor when usable, otherwise under the execution target $HOME. Supersedes --run-cwd/remoteCwd.')
         .option('--json', 'Emit machine-readable JSON with the created routine id and status')
         .action(async (nameOrPath, options) => {
         // Check if inline mode (has flags) or file mode
@@ -852,6 +855,8 @@ export function registerRoutinesCommands(program) {
                 ...(options.runOn ? { host: options.runOn } : {}),
                 ...(hostStrategy ? { hostStrategy } : {}),
                 ...(options.runCwd ? { remoteCwd: options.runCwd } : {}),
+                ...(options.projectAnchor ? { project: options.projectAnchor } : {}),
+                ...(options.cwd ? { cwd: options.cwd } : {}),
                 ...(runOnce ? { runOnce: true } : {}),
                 ...(options.catchup === false ? { catchup: false } : {}),
                 ...(options.endAt ? { endAt: options.endAt } : {}),
@@ -867,7 +872,23 @@ export function registerRoutinesCommands(program) {
                 process.exit(1);
             }
             writeJob(config);
-            setJobEnabled(config.name, config.enabled && (!devices || devices.map(normalizeHost).includes(normalizeHost(machineId()))));
+            // Readiness gate: a routine only activates when its execution context
+            // resolves and the harness is available. A proven blocker saves the
+            // definition PAUSED with a stable code + repair, so a broken routine can
+            // never fire (and storm) — the plan's save-paused contract.
+            const deviceMatch = !devices || devices.map(normalizeHost).includes(normalizeHost(machineId()));
+            const readiness = await evaluateActivationReadinessLive(config);
+            const activate = config.enabled && deviceMatch && readiness.ready;
+            setJobEnabled(config.name, activate);
+            if (config.enabled && deviceMatch && !readiness.ready) {
+                const r = readiness.readiness;
+                if (!options.json) {
+                    console.log(chalk.yellow(`Saved paused — not ready to activate: ${r.code}`));
+                    console.log(chalk.gray(`  ${r.message}`));
+                    if (r.repair)
+                        console.log(chalk.gray(`  repair: ${r.repair}`));
+                }
+            }
             if (options.json) {
                 writeJson({
                     ok: true,
@@ -875,8 +896,11 @@ export function registerRoutinesCommands(program) {
                     job: config,
                     jobId: config.name,
                     name: config.name,
-                    status: 'added',
+                    status: activate ? 'added' : 'added_paused',
                     enabled: config.enabled,
+                    activated: activate,
+                    ready: readiness.ready,
+                    ...(readiness.readiness ? { readiness: readiness.readiness } : {}),
                     schedule: config.schedule ?? null,
                     trigger: config.trigger ?? null,
                 });
@@ -933,7 +957,17 @@ export function registerRoutinesCommands(program) {
                 console.error(chalk.yellow(`Schedule "${config.schedule}" pins minute, hour, day, and month; treating it as one-shot. Prefer --at for one-time routines.`));
             }
             writeJob(config);
-            setJobEnabled(config.name, config.enabled && (!config.devices || config.devices.map(normalizeHost).includes(normalizeHost(machineId()))));
+            const deviceMatch = !config.devices || config.devices.map(normalizeHost).includes(normalizeHost(machineId()));
+            const readiness = await evaluateActivationReadinessLive(config);
+            const activate = config.enabled && deviceMatch && readiness.ready;
+            setJobEnabled(config.name, activate);
+            if (config.enabled && deviceMatch && !readiness.ready && !options.json) {
+                const r = readiness.readiness;
+                console.log(chalk.yellow(`Saved paused — not ready to activate: ${r.code}`));
+                console.log(chalk.gray(`  ${r.message}`));
+                if (r.repair)
+                    console.log(chalk.gray(`  repair: ${r.repair}`));
+            }
             if (options.json) {
                 writeJson({
                     ok: true,
@@ -941,8 +975,11 @@ export function registerRoutinesCommands(program) {
                     job: config,
                     jobId: config.name,
                     name: config.name,
-                    status: 'added',
+                    status: activate ? 'added' : 'added_paused',
                     enabled: config.enabled,
+                    activated: activate,
+                    ready: readiness.ready,
+                    ...(readiness.readiness ? { readiness: readiness.readiness } : {}),
                     schedule: config.schedule ?? null,
                     trigger: config.trigger ?? null,
                 });
@@ -1029,7 +1066,8 @@ export function registerRoutinesCommands(program) {
     });
     routinesCmd
         .command('edit [name]')
-        .description('Open a routine in $EDITOR. Creates a new YAML template if the routine does not exist.')
+        .description('Edit a prefilled routine transactionally; invalid YAML never replaces the live definition.')
+        .option('--yaml', 'Open the raw YAML in $EDITOR (the current edit surface)')
         .option('--state-to <name>', 'Update the Linear current-state filter before opening the editor')
         .option('--state-from <name>', 'Update the Linear previous-state filter before opening the editor')
         .action(async (name, options) => {
@@ -1048,53 +1086,55 @@ export function registerRoutinesCommands(program) {
                 existing.trigger.stateTo = options.stateTo || undefined;
             if (options.stateFrom !== undefined)
                 existing.trigger.stateFrom = options.stateFrom || undefined;
-            writeJob(existing);
         }
         const jobPath = getJobPath(name);
-        if (!jobPath) {
-            // Job doesn't exist - create a new one
-            const cronDir = getRoutinesDir();
-            const newPath = safeJoin(cronDir, `${name}.yml`);
-            // Create template
-            const template = yaml.stringify({
+        const cronDir = getRoutinesDir();
+        fs.mkdirSync(cronDir, { recursive: true });
+        const targetPath = jobPath || safeJoin(cronDir, `${name}.yml`);
+        const editPath = safeJoin(cronDir, `.${name}.edit-${process.pid}.yml`);
+        const initial = existing
+            ? yaml.stringify(existing)
+            : yaml.stringify({
                 name,
                 schedule: '0 9 * * *',
                 agent: 'claude',
                 prompt: 'Your prompt here',
             });
-            fs.writeFileSync(newPath, template, 'utf-8');
-            console.log(chalk.gray(`Created new job file: ${newPath}`));
-        }
-        const targetPath = jobPath || path.join(getRoutinesDir(), `${name}.yml`);
+        fs.writeFileSync(editPath, initial, { encoding: 'utf-8', mode: 0o600 });
         const editor = process.env.EDITOR || process.env.VISUAL || (IS_WINDOWS ? 'notepad' : 'vi');
         const editorParts = editor.split(/\s+/).filter(Boolean);
         const editorBin = editorParts[0];
-        const editorArgs = [...editorParts.slice(1), targetPath];
+        const editorArgs = [...editorParts.slice(1), editPath];
         const { spawn: spawnSync } = await import('child_process');
         const child = spawnSync(editorBin, editorArgs, {
             stdio: 'inherit',
         });
-        child.on('close', (code) => {
-            if (code === 0) {
-                // Validate the edited file
-                const job = readJob(name);
-                if (job) {
-                    const errors = validateJob(job);
-                    if (errors.length > 0) {
-                        console.log(chalk.yellow('\nWarning: Job has validation errors:'));
-                        for (const err of errors) {
-                            console.log(chalk.yellow(`  - ${err}`));
-                        }
-                    }
-                    else {
-                        console.log(chalk.green(`\nJob '${name}' saved`));
-                        if (isDaemonRunning()) {
-                            signalDaemonReload();
-                            console.log(chalk.gray('Daemon reloaded'));
-                        }
-                    }
+        child.on('close', async (code) => {
+            if (code !== 0) {
+                fs.rmSync(editPath, { force: true });
+                return;
+            }
+            try {
+                const raw = fs.readFileSync(editPath, 'utf-8');
+                const job = yaml.parse(raw);
+                const errors = validateJob(job);
+                if (errors.length > 0)
+                    throw new Error(errors.join('\n'));
+                const readiness = await evaluateActivationReadinessLive(job);
+                fs.renameSync(editPath, targetPath);
+                if (!readiness.ready)
+                    setJobEnabled(job.name, false);
+                console.log(chalk.green(`\nJob '${name}' saved${readiness.ready ? '' : ' paused (not ready)'}`));
+                if (isDaemonRunning()) {
+                    signalDaemonReload();
+                    console.log(chalk.gray('Daemon reloaded'));
                 }
             }
+            catch (err) {
+                fs.rmSync(editPath, { force: true });
+                console.error(chalk.red(`\nRoutine not saved: ${err.message}`));
+                process.exitCode = 1;
+            }
         });
     });
     routinesCmd
@@ -1498,6 +1538,79 @@ export function registerRoutinesCommands(program) {
         console.log(chalk.gray(`Run: ${runId}\n`));
         console.log(fs.readFileSync(reportPath, 'utf-8'));
     });
+    routinesCmd
+        .command('doctor [name]')
+        .description('Check a routine\'s execution-context and harness readiness. Bare or --all checks every routine; --fix applies safe activation repairs (activate a now-ready paused routine; pause a broken active one).')
+        .option('--all', 'Check every routine (the default when no name is given)')
+        .option('--fix', 'Apply safe, deterministic activation repairs')
+        .option('--json', 'Machine-readable output')
+        .action(async (name, options) => {
+        const all = options.all || !name;
+        let targets;
+        if (all) {
+            targets = listAllJobs();
+        }
+        else {
+            const job = readJob(name);
+            if (!job) {
+                if (options.json) {
+                    writeJson({ ok: false, error: `routine '${name}' not found` });
+                    return;
+                }
+                console.error(chalk.red(`Routine '${name}' not found`));
+                process.exit(1);
+            }
+            targets = [job];
+        }
+        const thisDevice = normalizeHost(machineId());
+        const results = await Promise.all(targets.map(async (job) => {
+            const deviceMatch = !job.devices || job.devices.map(normalizeHost).includes(thisDevice);
+            const readiness = await evaluateActivationReadinessLive(job);
+            // `job.enabled` reflects THIS device's activation state (applyDeviceActivation).
+            let action;
+            if (options.fix && deviceMatch) {
+                if (readiness.ready && !job.enabled) {
+                    setJobEnabled(job.name, true);
+                    action = 'activated';
+                }
+                else if (!readiness.ready && job.enabled) {
+                    setJobEnabled(job.name, false);
+                    action = 'paused';
+                }
+            }
+            return {
+                name: job.name,
+                ready: readiness.ready,
+                active: job.enabled,
+                deviceScoped: deviceMatch,
+                ...(readiness.readiness ? { readiness: readiness.readiness } : {}),
+                ...(action ? { action } : {}),
+            };
+        }));
+        if (options.fix && results.some((r) => r.action) && isDaemonRunning()) {
+            signalDaemonReload();
+        }
+        if (options.json) {
+            writeJson({ ok: true, results });
+            return;
+        }
+        const blocked = results.filter((r) => !r.ready);
+        for (const r of results) {
+            if (r.ready) {
+                console.log(`${chalk.green('✓')} ${r.name}${r.action === 'activated' ? chalk.gray(' (activated)') : ''}`);
+            }
+            else {
+                const rd = r.readiness;
+                console.log(`${chalk.red('✗')} ${r.name} — ${chalk.yellow(rd.code)}${r.action === 'paused' ? chalk.gray(' (paused)') : ''}`);
+                console.log(chalk.gray(`    ${rd.message}`));
+                if (rd.repair)
+                    console.log(chalk.gray(`    repair: ${rd.repair}`));
+            }
+        }
+        if (blocked.length > 0 && !options.fix) {
+            console.log(chalk.gray(`\n${blocked.length} routine${blocked.length === 1 ? '' : 's'} blocked — re-run with --fix to pause them, or apply each repair above.`));
+        }
+    });
     routinesCmd
         .command('resume [name]')
         .description('Re-enable a paused routine so the daemon schedules it again')
@@ -1509,6 +1622,21 @@ export function registerRoutinesCommands(program) {
                 return;
         }
         try {
+            // Resume re-runs readiness — it can never bypass a proven blocker (the
+            // plan: "resume cannot bypass readiness"). A blocked routine stays paused.
+            const job = readJob(name);
+            if (job) {
+                const readiness = await evaluateActivationReadinessLive(job);
+                if (!readiness.ready) {
+                    const r = readiness.readiness;
+                    console.log(chalk.red(`Cannot resume '${name}' — not ready: ${r.code}`));
+                    console.log(chalk.gray(`  ${r.message}`));
+                    if (r.repair)
+                        console.log(chalk.gray(`  repair: ${r.repair}`));
+                    console.log(chalk.gray(`  fix it, then: agents routines doctor ${name} --fix`));
+                    process.exit(1);
+                }
+            }
             setJobEnabled(name, true);
             console.log(chalk.green(`Job '${name}' resumed`));
             if (isDaemonRunning()) {

package/dist/commands/secrets.d.ts

@@ -12,6 +12,7 @@ import { bundleEnvToDotenv } from '../lib/secrets/push.js';
 export { bundleEnvToDotenv };
 import { type SecretsBackend, type SecretsBundle, type SecretsPolicy } from '../lib/secrets/bundles.js';
 import { type SecretsListFilterOpts } from '../lib/secrets/list-filter.js';
+import { type SecretLease } from '../lib/secrets/lease.js';
 import { type BundleUsageSummary } from '../lib/secrets/usage-db.js';
 /** Read all available data from stdin synchronously, trimmed. */
 /**
@@ -51,6 +52,25 @@ export declare function parseImportSource(opts: {
  * without a live SSH session.
  */
 export declare function resolveUnlockTtlMs(ttl: string | undefined, until: string | undefined, now?: number): number;
+/**
+ * Decide what an `unlock` holds: the whole bundle env, or — with --keys — only
+ * the resolved subset behind a lease that scopes the broker entry (agent.ts
+ * re-selects on load) and its own expiry. Fails closed: createSecretLease throws
+ * on an unknown or empty key subset. The unlock action's single scoping seam,
+ * exported so the whole-bundle vs scoped-subset decision is unit-testable without
+ * a live broker.
+ */
+export declare function scopeHeldEnv(input: {
+    bundle: string;
+    env: Record<string, string>;
+    keys: string | null;
+    ttlMs: number;
+    harness: string;
+    sleepPersist: boolean;
+}): {
+    heldEnv: Record<string, string>;
+    lease?: SecretLease;
+};
 export declare function buildRemoteUnlockArgs(names: string[], opts: {
     all?: boolean;
     ttl?: string;

package/dist/commands/secrets.js

@@ -25,8 +25,8 @@ import { getKeychainToken, hasKeychainToken, secretsKeychainItem, setKeychainTok
 import { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
 import { GLOBAL_HARNESS } from '../lib/secrets/scope.js';
 import { createSecretLease, selectLeasedEnv } from '../lib/secrets/lease.js';
-import { secretsHoldMs, secretsAgentDurable, agentLoad, agentLock, agentPing, agentSocketExists, agentStatus, agentRevoke, ensureAgentRunning, runAgentLoadFromStdin, runSecretsAgent, uninstallSecretsAgentService, } from '../lib/secrets/agent.js';
-import { activeLeaseSessions, saveSession, deleteBundleSessions, deleteAllSessions, deleteLeaseSession } from '../lib/secrets/session-store.js';
+import { secretsHoldMs, secretsAgentDurable, agentLoad, agentLock, agentPing, agentStatus, ensureAgentRunning, runAgentLoadFromStdin, runSecretsAgent, uninstallSecretsAgentService, } from '../lib/secrets/agent.js';
+import { saveSession, deleteBundleSessions, deleteAllSessions } from '../lib/secrets/session-store.js';
 import { getCliVersionFresh } from '../lib/version.js';
 import { readMeta } from '../lib/state.js';
 import { parseDuration } from '../lib/hooks/cache.js';
@@ -287,6 +287,30 @@ export function resolveUnlockTtlMs(ttl, until, now = Date.now()) {
     }
     return secretsHoldMs();
 }
+/**
+ * Decide what an `unlock` holds: the whole bundle env, or — with --keys — only
+ * the resolved subset behind a lease that scopes the broker entry (agent.ts
+ * re-selects on load) and its own expiry. Fails closed: createSecretLease throws
+ * on an unknown or empty key subset. The unlock action's single scoping seam,
+ * exported so the whole-bundle vs scoped-subset decision is unit-testable without
+ * a live broker.
+ */
+export function scopeHeldEnv(input) {
+    // null = no --keys → hold the whole bundle. An empty-string --keys is a
+    // deliberate (if empty) scope request and falls through to createSecretLease,
+    // which fails closed ('requires at least one key') rather than holding it all.
+    if (input.keys === null)
+        return { heldEnv: input.env };
+    const lease = createSecretLease({
+        bundle: input.bundle,
+        keys: input.keys.split(','),
+        availableKeys: Object.keys(input.env),
+        ttlMs: input.ttlMs,
+        harness: input.harness,
+        sleepPersist: input.sleepPersist,
+    });
+    return { heldEnv: selectLeasedEnv(lease, input.env), lease };
+}
 export function buildRemoteUnlockArgs(names, opts) {
     return [
         'unlock',
@@ -2442,89 +2466,6 @@ Examples:
             console.log(password);
         }
     });
-    cmd
-        .command('lease <bundle>')
-        .description('Hold only an explicit subset of a bundle until an independent expiry.')
-        .requiredOption('--keys <keys>', 'Comma-separated key subset')
-        .requiredOption('--ttl <duration>', 'How long to hold it (e.g. 30m, 8h, 3d)')
-        .option('--agent <agent>', 'Narrow the lease to one harness; default is global')
-        .option('--durable', 'Keep the lease across sleep as well as broker restart')
-        .action(async (name, opts) => {
-        if (process.platform !== 'darwin') {
-            throw new Error('Scoped lease brokering is not available on this platform yet.');
-        }
-        const seconds = parseDuration(opts.ttl);
-        if (seconds === null)
-            throw new Error(`Invalid lease duration '${opts.ttl}'.`);
-        const ttlMs = seconds * 1000;
-        const harness = opts.agent || GLOBAL_HARNESS;
-        const { bundle, env } = readAndResolveBundleEnv(name, {
-            noAgent: true,
-            interactiveUnlock: true,
-            caller: 'lease secrets',
-            agent: harness,
-            keyMode: 'storage',
-        });
-        const lease = createSecretLease({
-            bundle: name,
-            keys: opts.keys.split(','),
-            availableKeys: Object.keys(env),
-            ttlMs,
-            harness,
-            sleepPersist: opts.durable,
-        });
-        const leasedEnv = selectLeasedEnv(lease, env);
-        if (!(await ensureAgentRunning()) || !(await agentLoad(name, bundle, leasedEnv, ttlMs, harness, lease))) {
-            throw new Error('Could not load the scoped lease into the secrets broker.');
-        }
-        ensureDaemonStarted();
-        saveSession(name, {
-            bundle,
-            env: leasedEnv,
-            expiresAt: lease.expiresAt,
-            sleepPersist: lease.sleepPersist,
-            harness,
-            lease,
-        });
-        emitSecretAudit({
-            event: 'secrets.unlocked', bundle: name, operation: 'lease', source: lease.sleepPersist ? 'broker+durable' : 'broker',
-            status: 'success', keys: lease.keys, keyCount: lease.keys.length, agent: harness, ttlMs: lease.expiresAt - lease.createdAt,
-        });
-        console.log(`${chalk.green('leased')} ${chalk.cyan(lease.id)} ${chalk.gray(`(${name}: ${lease.keys.join(', ')}, ${humanRemaining(lease.expiresAt)})`)}`);
-    });
-    cmd
-        .command('leases')
-        .description('List active scoped secret leases.')
-        .action(async () => {
-        const brokerLeases = (await agentStatus()).filter((entry) => entry.leaseId);
-        const byId = new Map(brokerLeases.map((entry) => [entry.leaseId, entry]));
-        for (const { name, lease } of activeLeaseSessions()) {
-            if (!byId.has(lease.id))
-                byId.set(lease.id, { name, expiresAt: lease.expiresAt, keyCount: lease.keys.length, harness: lease.harness, leaseId: lease.id, keys: lease.keys });
-        }
-        const leases = [...byId.values()];
-        if (leases.length === 0) {
-            console.log(chalk.gray('No active secret leases.'));
-            return;
-        }
-        console.log(`${'ID'.padEnd(24)} ${'BUNDLE'.padEnd(24)} ${'KEYS'.padEnd(24)} EXPIRES IN`);
-        for (const lease of leases) {
-            console.log(`${lease.leaseId.padEnd(24)} ${lease.name.padEnd(24)} ${(lease.keys ?? []).join(',').padEnd(24)} ${humanRemaining(lease.expiresAt)}`);
-        }
-    });
-    cmd
-        .command('revoke <lease-id>')
-        .description('Revoke one scoped secret lease immediately.')
-        .action(async (leaseId) => {
-        if (agentSocketExists() && !(await agentPing()).reachable) {
-            throw new Error('Cannot revoke while the secrets broker is using an incompatible protocol. Restart the broker and retry.');
-        }
-        const persisted = deleteLeaseSession(leaseId);
-        const wiped = await agentRevoke(leaseId);
-        if (wiped + persisted === 0)
-            throw new Error(`Secret lease '${leaseId}' is not active.`);
-        console.log(chalk.green(`Revoked secret lease ${leaseId}.`));
-    });
     cmd
         .command('unlock [names...]')
         .description('Hold a bundle in the secrets-agent after one Touch ID, so concurrent runs read it without re-prompting (macOS). With --host, unlock FILE-backed bundle(s) on a remote (the passphrase prompt surfaces over the SSH TTY); keychain/biometry bundles are GUI-only and can\'t be remote-unlocked.')
@@ -2532,6 +2473,7 @@ Examples:
         .option('--until <date>', 'Hold until this absolute date or timestamp (for example 2026-08-06T12:00:00Z). Mutually exclusive with --ttl.')
         .option('--durable', 'Keep the unlock across sleep + reboot too (default: survives upgrade/restart but re-locks on sleep). Set secrets.agent.durable in agents.yaml to make this the default.')
         .option('--agent <agent>', 'Narrow the unlock to ONE harness type (for example claude, codex, or kimi). Default: the grant is global — every harness and a plain shell can read it, so one Touch ID covers them all.')
+        .option('--keys <keys>', 'Hold ONLY this comma-separated subset of the bundle\'s keys instead of the whole bundle. Scopes exactly one bundle; fails closed on an unknown key. `secrets status` shows which keys a scoped hold covers.')
         .option('--all', 'Unlock every configured bundle')
         .option('--host <target>', 'Unlock the bundle(s) on this remote machine over SSH instead of locally (file-backed bundles only — the remote\'s passphrase prompt surfaces on your terminal over a -tt session). Single-valued (NOT variadic) so it never swallows the bundle name: `unlock <name> --host <machine>`.')
         .action(async (names, opts) => {
@@ -2539,6 +2481,19 @@ Examples:
             console.error(chalk.red('--ttl and --until are mutually exclusive.'));
             process.exit(1);
         }
+        if (opts.keys !== undefined) {
+            // --keys scopes ONE bundle to an explicit subset. It is local-only (a
+            // remote --host unlock holds the whole file-backed bundle) and cannot
+            // combine with --all, which would hold every bundle whole.
+            if (opts.host) {
+                console.error(chalk.red('--keys is local-only; a remote (--host) unlock holds the whole file-backed bundle.'));
+                process.exit(1);
+            }
+            if (opts.all || !names || names.length !== 1) {
+                console.error(chalk.red('--keys scopes ONE bundle to a subset of its keys: name exactly one bundle (not --all).'));
+                process.exit(1);
+            }
+        }
         // Single-valued (not variadic): a variadic --host greedily consumes the
         // positional bundle name (`unlock --host mac wztest` -> host=[mac,wztest],
         // names=[]). Unlock targets one remote at a time anyway.
@@ -2623,6 +2578,7 @@ Examples:
         // agent happened to launch the shell, leaving the grant unreadable to
         // every other reader for its whole TTL.
         const harness = opts.agent || GLOBAL_HARNESS;
+        const durable = opts.durable ?? secretsAgentDurable();
         for (const name of targets) {
             try {
                 // noAgent: read the real keychain (one Touch ID) rather than the
@@ -2639,17 +2595,23 @@ Examples:
                 // ACL heal can rewrite that already-read value without another read.
                 maybeAutoRekey();
                 healKeychainBundleMetadataAclOnce(new Map([[bundle.name, JSON.stringify(bundle)]]));
-                if (await agentLoad(name, bundle, env, ttlMs, harness)) {
+                // With --keys, hold ONLY the resolved subset behind a lease that scopes
+                // the broker entry and its own expiry; without it, the whole bundle is
+                // held exactly as before. scopeHeldEnv fails closed on an unknown key.
+                const { heldEnv, lease } = scopeHeldEnv({ bundle: name, env, keys: opts.keys ?? null, ttlMs, harness, sleepPersist: durable });
+                const heldExpiresAt = lease ? lease.expiresAt : expiresAt;
+                if (await agentLoad(name, bundle, heldEnv, ttlMs, harness, lease)) {
                     loaded++;
                     // Persist a durable session snapshot so the unlock survives a daemon
                     // restart / upgrade (and sleep too, with --durable). session-store.ts.
-                    const durable = opts.durable ?? secretsAgentDurable();
+                    // A scoped hold persists its lease so it rehydrates scoped.
                     saveSession(name, {
                         bundle,
-                        env,
-                        expiresAt,
+                        env: heldEnv,
+                        expiresAt: heldExpiresAt,
                         sleepPersist: durable,
                         harness,
+                        lease,
                     });
                     // Audit the GRANT itself — the broker + durable session now serve this
                     // bundle prompt-free for the whole TTL, to every reader in `harness`
@@ -2661,12 +2623,13 @@ Examples:
                         operation: 'unlock',
                         source: durable ? 'broker+durable' : 'broker',
                         status: 'success',
-                        keyCount: Object.keys(env).length,
-                        keys: Object.keys(env).sort(),
+                        keyCount: Object.keys(heldEnv).length,
+                        keys: Object.keys(heldEnv).sort(),
                         agent: harness,
                         ttlMs,
                     });
-                    console.log(`${chalk.green('unlocked')} ${chalk.cyan(name)} ${chalk.gray(`(${Object.keys(env).length} keys, ${humanRemaining(expiresAt)})`)}`);
+                    const scoped = lease ? chalk.gray(` scoped to ${lease.keys.join(', ')}`) : '';
+                    console.log(`${chalk.green('unlocked')} ${chalk.cyan(name)} ${chalk.gray(`(${Object.keys(heldEnv).length} keys, ${humanRemaining(heldExpiresAt)})`)}${scoped}`);
                 }
                 else {
                     console.error(chalk.red(`Failed to load '${name}' into the agent.`));
@@ -2748,7 +2711,10 @@ Examples:
         else {
             console.log(chalk.bold(`${'BUNDLE'.padEnd(24)} ${'KEYS'.padEnd(5)} LOCKS IN`));
             for (const e of entries) {
-                console.log(`${chalk.cyan(e.name.padEnd(24))} ${String(e.keyCount).padEnd(5)} ${humanRemaining(e.expiresAt)}`);
+                // A scoped hold (unlock --keys) carries the held key names, so name them
+                // rather than leave the bundle looking whole.
+                const scoped = e.keys?.length ? chalk.gray(`  scoped: ${e.keys.join(', ')}`) : '';
+                console.log(`${chalk.cyan(e.name.padEnd(24))} ${String(e.keyCount).padEnd(5)} ${humanRemaining(e.expiresAt)}${scoped}`);
             }
             console.log(chalk.gray('Reads of held bundles are silent; any bundle not listed prompts once on its next read.'));
         }

package/dist/commands/{sessions-favorite.d.ts → sessions-bookmark.d.ts}

@@ -1,20 +1,20 @@
 /**
- * `agents sessions favorite` — the non-TTY half of the favorite hotkey.
+ * `agents sessions bookmark` — the non-TTY half of the bookmark hotkey.
  *
- * The `*` hotkey in the interactive browser is how a human favorites a session;
+ * The `*` hotkey in the interactive browser is how a human bookmarks a session;
  * this is how a script, an agent, or a machine without a TTY does the same thing,
  * and it is what makes the feature testable end to end without driving a terminal
- * UI. Both write the one store in `lib/session/favorites.ts`.
+ * UI. Both write the one store in `lib/session/bookmarks.ts`.
  */
 import type { Command } from 'commander';
 /**
  * Resolve one user-typed id (usually the 8-char short id the listing prints) to
- * a full session id. Ambiguity is an ERROR, not a silent first-match: favoriting
- * the wrong session is invisible until the user wonders where their favorite went.
+ * a full session id. Ambiguity is an ERROR, not a silent first-match: bookmarking
+ * the wrong session is invisible until the user wonders where their bookmark went.
  */
-export declare function resolveFavoriteTarget(idQuery: string): {
+export declare function resolveBookmarkTarget(idQuery: string): {
     id: string;
 } | {
     error: string;
 };
-export declare function registerSessionsFavoriteCommand(sessionsCmd: Command): void;
+export declare function registerSessionsBookmarkCommand(sessionsCmd: Command): void;