@phnx-labs/agents-cli 1.22.106 → 1.22.109

package/dist/commands/run-account-picker.js

@@ -204,6 +204,16 @@ export async function pickSwitchAccount(agent, rows) {
         throw err;
     }
 }
+/**
+ * The two-condition "human-facing" gate behind signInLaunchDecision and
+ * noVerifiedUsageDecision: a real TTY and no `--json`. Off a TTY nobody can
+ * answer a prompt, and `--json` marks a MACHINE consumer, which must never be
+ * handed a picker or dropped into a login TUI. Mirrors the canonical
+ * `Surface.interactive = tty && !json` in `commands/utils.ts`.
+ */
+export function isHumanFacingRun(input) {
+    return input.tty && !input.json;
+}
 /**
  * Whether a zero-healthy run may recover by launching for a login, or must keep
  * failing loud. Three inputs, all of which have to hold:
@@ -217,7 +227,7 @@ export async function pickSwitchAccount(agent, rows) {
  *   gets the parseable fail-loud error instead.
  */
 export function signInLaunchDecision(input) {
-    const humanPresent = input.tty && !input.json;
+    const humanPresent = isHumanFacingRun(input);
     return input.recoverable > 0 && humanPresent ? 'launch' : 'fail-loud';
 }
 /**

package/dist/commands/sessions-backup-setup.d.ts

@@ -0,0 +1,12 @@
+import type { Command } from 'commander';
+interface BackupSetupOptions {
+    bundle: string;
+    worker: string;
+    bucket: string;
+    account?: string;
+    token?: string;
+    domain: string;
+}
+export declare function handleSessionsBackupSetup(opts: BackupSetupOptions): Promise<void>;
+export declare function registerSessionsBackupSetupCommand(sessionsCmd: Command): void;
+export {};

package/dist/commands/sessions-backup-setup.js

@@ -0,0 +1,65 @@
+// `agents sessions backup-setup` — the OPERATOR command that provisions the
+// managed session-backup endpoint (`sessions.agents-cli.sh`): the Cloudflare
+// Worker + R2 bucket a signed-in user's `sessions export --to-r2` talks to with
+// NO `r2.backups` bucket of their own. It is the deploy producer for that
+// endpoint — first-party infrastructure, not a per-user step. The zero-knowledge
+// `--byo` backup path uses the user's own R2 bucket directly and never touches
+// this Worker, so there is nothing here for an ordinary user to run.
+//
+// Mirrors `agents traces setup`: the same `readCloudflareCreds` bundle plumbing,
+// the same idempotent `deployWorker`/`createBucket` primitives. Provisioning is
+// idempotent — re-running redeploys the current Worker template in place.
+import chalk from 'chalk';
+import { DEFAULT_CF_BUNDLE, readCloudflareCreds } from '../lib/share/config.js';
+import { PHOENIX_ID_BASE } from '../lib/identity/client.js';
+import { provisionSessions } from '../lib/session/sync/provision.js';
+import { DEFAULT_SESSIONS_BUCKET_NAME, DEFAULT_SESSIONS_DOMAIN, DEFAULT_SESSIONS_WORKER_NAME, } from '../lib/session/sync/managed-config.js';
+import { setHelpSections } from '../lib/help.js';
+export async function handleSessionsBackupSetup(opts) {
+    const { input } = await import('@inquirer/prompts');
+    const { apiToken, accountId: bundledAccountId } = readCloudflareCreds(opts.bundle, {
+        apiToken: opts.token,
+        accountId: opts.account,
+    });
+    const accountId = opts.account ?? bundledAccountId ?? await input({ message: 'Cloudflare account id' });
+    if (!accountId)
+        throw new Error('A Cloudflare account id is required.');
+    const result = await provisionSessions({
+        apiToken,
+        accountId,
+        workerName: opts.worker,
+        bucketName: opts.bucket,
+        domain: opts.domain,
+        phoenixIdBase: PHOENIX_ID_BASE,
+    });
+    console.log(chalk.green(`Managed session-backup endpoint ready → ${chalk.bold(result.baseUrl)}`));
+    console.log(chalk.dim('Signed-in users now back up with `agents sessions export --to-r2` — no r2.backups bucket.'));
+}
+const BACKUP_SETUP_EXAMPLES = `
+  $ agents secrets exec cloudflare -- agents sessions backup-setup
+  Provision the managed session-backup Worker + R2 bucket (creds from the bundle).
+
+  $ agents sessions backup-setup --account <id> --domain sessions.example.com
+  Provision against a private account service and custom domain.
+`.trimStart();
+export function registerSessionsBackupSetupCommand(sessionsCmd) {
+    const cmd = sessionsCmd
+        .command('backup-setup')
+        .description('(operator) Provision the managed session-backup Worker + R2 bucket — NOT a per-user step; signing in with `agents auth login` backs sessions up with zero setup')
+        .option('--bundle <name>', 'secrets bundle holding the Cloudflare API token', DEFAULT_CF_BUNDLE)
+        .option('--worker <name>', 'Worker name', DEFAULT_SESSIONS_WORKER_NAME)
+        .option('--bucket <name>', 'R2 bucket name', DEFAULT_SESSIONS_BUCKET_NAME)
+        .option('--account <id>', 'Cloudflare account id (else read from the bundle / prompt)')
+        .option('--token <token>', 'Cloudflare API token (else read from the --bundle)')
+        .option('--domain <host>', 'custom domain to map', DEFAULT_SESSIONS_DOMAIN)
+        .action(async (opts) => {
+        try {
+            await handleSessionsBackupSetup(opts);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exitCode = 1;
+        }
+    });
+    setHelpSections(cmd, { examples: BACKUP_SETUP_EXAMPLES });
+}

package/dist/commands/sessions-resume.d.ts

@@ -1,6 +1,6 @@
 import type { Command } from 'commander';
 import { type SessionMeta } from '../lib/session/types.js';
-import { type Backend, type EngineContext, type Packing } from '../lib/terminal/index.js';
+import { type Backend, type SurfaceItem, type EngineContext, type Packing } from '../lib/terminal/index.js';
 import { type StrictResumeOptions } from './resume.js';
 /** Opening more than this many live sessions at once asks for confirmation first. */
 export declare const CONFIRM_THRESHOLD = 5;
@@ -33,6 +33,15 @@ export declare function isDirectResumeSelector(query: string): boolean;
 /** Re-enter through sessions resume so fleet routing and harness policy
  * stay centralized. The child inherits this terminal for a real interactive resume. */
 export declare function resumeSelectorInPlace(selector: string): Promise<void>;
+/**
+ * Local preflight cannot inspect a peer's files or index. Leave peer validation
+ * to the existing origin-device recovery hop. --here without a remote surface
+ * opts into local recovery and therefore uses the local transcript guard.
+ */
+export declare function partitionResumableSelections(chosen: SessionMeta[], options?: Pick<ResumeOptions, 'here' | 'device'>): {
+    resumable: SessionMeta[];
+    skipped: SessionMeta[];
+};
 /** Direct identities use focus as the lifecycle dispatcher: it rechecks the
  * live fleet, attaches a healthy pane, and falls through to `agents resume`
  * only when the process is no longer attachable. */
@@ -42,6 +51,10 @@ export declare function resumeUsesLifecycleDispatch(query: string | undefined, p
 export declare function dispatchSessionLifecycleInPlace(selector: string, hosts?: string[], attachOnly?: boolean, local?: boolean): Promise<void>;
 export declare function buildSessionLifecycleArgs(selector: string, hosts?: string[], attachOnly?: boolean, local?: boolean): string[];
 export declare function resolveResumePacking(options: Pick<ResumeOptions, 'splits'>): Packing;
+/** Surface commands use shell words; spawnCliInPlace keeps the original argv. */
+export declare function buildSelectedResumeSurface(session: SessionMeta, prompt: string | undefined, options: ResumeOptions): SurfaceItem & {
+    session: SessionMeta;
+};
 export declare function resumeHostMismatch(session: Pick<SessionMeta, 'shortId' | 'machine'>, requestedHost: string, self?: string): string | null;
 /**
  * Decide which backend to launch into. Returns a concrete backend, `'inplace'`

package/dist/commands/sessions-resume.js

@@ -19,15 +19,16 @@ import { multiItemPicker, itemPicker } from '../lib/picker.js';
 import { buildPreview } from './sessions-picker.js';
 import { formatPickerLabel, pickerColumnsFor, resolveSessionMetadataValue, parseAgentFilter, } from './sessions.js';
 import { sessionMatchesQuery } from './sessions-browser.js';
-import { openSurfaces, availableBackends, detectCurrentBackend, currentContext, } from '../lib/terminal/index.js';
+import { openSurfaces, availableBackends, detectCurrentBackend, currentContext, shellQuote, } from '../lib/terminal/index.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { setHelpSections } from '../lib/help.js';
 import { confirm } from '@inquirer/prompts';
 import { spawn } from 'node:child_process';
 import { looksLikeSessionId } from '../lib/session/discover.js';
 import { machineId } from '../lib/session/sync/config.js';
-import { sessionOriginDevice, sessionRecoveryDestinationMatches } from '../lib/session/recovery.js';
+import { sessionOriginDevice, sessionRecoveryDestinationMatches, sessionRecoveryPeer, sessionTranscriptReadable } from '../lib/session/recovery.js';
 import { buildResumeRemoteArgs, runStrictResume, wantsStrictResume } from './resume.js';
+import { toRemotePortable } from '../lib/project-root.js';
 import { attachLocalLiveSelector } from '../lib/session/local-tmux-attach.js';
 /** Opening more than this many live sessions at once asks for confirmation first. */
 export const CONFIRM_THRESHOLD = 5;
@@ -98,6 +99,7 @@ export function registerSessionsResumeCommand(sessionsCmd) {
       - --vscodium opens each session as an agent terminal tab in VSCodium via the swarm-ext extension (works with --device too).
       - --device <alias> opens the terminal surface on that device only when it is the selected sessions' origin; recovery never migrates a session to another device.
       - Recovery uses the installed harness and the conversation's account on its origin device. Context replay requires an explicit choice.
+      - Local picks without transcripts are skipped before opening a tab. Remote picks are validated on their origin device.
       - agents run claude --resume opens this same picker; claude#work filters it with --account work.
     `,
     });
@@ -232,12 +234,16 @@ export async function sessionsResumeAction(query, prompt, options) {
         }
     }
     // 2. Route every selection through the owning device's recovery resolver.
-    const items = [];
-    for (const s of chosen) {
-        const command = ['agents', ...buildSelectedResumeArgs(s.id, prompt, options)];
-        const cwd = s.cwd && fs.existsSync(s.cwd) ? s.cwd : process.cwd();
-        items.push({ session: s, cwd, command });
+    const { resumable, skipped } = partitionResumableSelections(chosen, options);
+    for (const s of skipped) {
+        console.log(chalk.yellow(`Skipping ${s.shortId} — nothing to resume (no transcript was written).`));
     }
+    if (resumable.length === 0) {
+        console.error(chalk.red('Nothing to resume — no selected session has a transcript.'));
+        process.exitCode = 1;
+        return;
+    }
+    const items = resumable.map((session) => buildSelectedResumeSurface(session, prompt, options));
     // 3. Resolve the backend (and host).
     const ctx = currentContext();
     const backend = await resolveBackend(options, ctx, items.length);
@@ -294,6 +300,8 @@ export async function sessionsResumeAction(query, prompt, options) {
         }
     });
     console.log(chalk.gray(`\nOpened ${opened}/${items.length} in ${where}.`));
+    if (opened !== items.length)
+        process.exitCode = 1;
 }
 /** Preserve run options and lifecycle intent when the picker opens its selected rows. */
 export function buildSelectedResumeArgs(id, prompt, options) {
@@ -307,6 +315,7 @@ export function buildSelectedResumeArgs(id, prompt, options) {
         // The outer surface already placed this terminal on the selected device.
         if (options.device) {
             let remoteCwd;
+            let localCwd;
             for (let i = 0; i < args.length && args[i] !== '--'; i++) {
                 if (args[i] === '--remote-cwd') {
                     remoteCwd = args[i + 1];
@@ -316,6 +325,14 @@ export function buildSelectedResumeArgs(id, prompt, options) {
                     remoteCwd = args[i].slice('--remote-cwd='.length);
                     args.splice(i--, 1);
                 }
+                else if (args[i] === '--cwd') {
+                    localCwd = args[i + 1];
+                    args.splice(i--, 2);
+                }
+                else if (args[i].startsWith('--cwd=')) {
+                    localCwd = args[i].slice('--cwd='.length);
+                    args.splice(i--, 1);
+                }
                 else if (['-D', '--device', '--host', '--where', '--on', '--computer'].includes(args[i])) {
                     args.splice(i, 2);
                     i--;
@@ -325,9 +342,10 @@ export function buildSelectedResumeArgs(id, prompt, options) {
                     i--;
                 }
             }
-            if (remoteCwd !== undefined) {
+            const effectiveCwd = remoteCwd ?? options.cwd ?? (localCwd ? toRemotePortable(localCwd) : undefined);
+            if (effectiveCwd !== undefined) {
                 const end = args.indexOf('--');
-                args.splice(end < 0 ? args.length : end, 0, '--cwd', remoteCwd);
+                args.splice(end < 0 ? args.length : end, 0, '--cwd', effectiveCwd);
             }
         }
         return args;
@@ -352,6 +370,20 @@ export function isDirectResumeSelector(query) {
 export async function resumeSelectorInPlace(selector) {
     await spawnCliInPlace(['sessions', 'resume', selector]);
 }
+/**
+ * Local preflight cannot inspect a peer's files or index. Leave peer validation
+ * to the existing origin-device recovery hop. --here without a remote surface
+ * opts into local recovery and therefore uses the local transcript guard.
+ */
+export function partitionResumableSelections(chosen, options = {}) {
+    const resumable = [];
+    const skipped = [];
+    for (const s of chosen) {
+        const deferredToPeer = (!options.here || !!options.device) && sessionRecoveryPeer(s);
+        (deferredToPeer || sessionTranscriptReadable(s) ? resumable : skipped).push(s);
+    }
+    return { resumable, skipped };
+}
 /** Direct identities use focus as the lifecycle dispatcher: it rechecks the
  * live fleet, attaches a healthy pane, and falls through to `agents resume`
  * only when the process is no longer attachable. */
@@ -395,6 +427,21 @@ async function spawnCliInPlace(args) {
 export function resolveResumePacking(options) {
     return options.splits ? 'two-per-tab' : 'tabs';
 }
+/** Surface commands use shell words; spawnCliInPlace keeps the original argv. */
+export function buildSelectedResumeSurface(session, prompt, options) {
+    const requestedCwd = options.cwd || session.cwd;
+    if (options.device && !requestedCwd) {
+        throw new Error(`Cannot open ${session.shortId} on ${options.device} without a recorded working directory. Pass --cwd <path>.`);
+    }
+    const cwd = options.device
+        ? requestedCwd
+        : requestedCwd && fs.existsSync(requestedCwd) ? requestedCwd : process.cwd();
+    return {
+        session,
+        cwd,
+        command: ['agents', ...buildSelectedResumeArgs(session.id, prompt, options)].map(shellQuote),
+    };
+}
 export function resumeHostMismatch(session, requestedHost, self = machineId()) {
     const origin = sessionOriginDevice(session, self);
     return sessionRecoveryDestinationMatches(session, requestedHost, self)

package/dist/commands/sessions.js

@@ -75,6 +75,7 @@ import { registerSessionsRenderCommand } from './sessions-render.js';
 import { registerSessionsTraceCommand } from './sessions-trace.js';
 import { registerSessionsShareCommand } from './sessions-share.js';
 import { registerSessionsImportCommand } from './sessions-import.js';
+import { registerSessionsBackupSetupCommand } from './sessions-backup-setup.js';
 import { registerSessionsMigrateCommand, registerSessionsMigrationsCommand } from './sessions-migrate.js';
 import { registerSessionsBackfillCommand } from './sessions-backfill.js';
 import { registerSessionsStatsCommand } from './sessions-stats.js';
@@ -5387,6 +5388,7 @@ export function registerSessionsCommands(program) {
     registerSessionsTraceCommand(sessionsCmd);
     registerSessionsShareCommand(sessionsCmd);
     registerSessionsImportCommand(sessionsCmd);
+    registerSessionsBackupSetupCommand(sessionsCmd);
     registerSessionsMigrateCommand(sessionsCmd);
     registerSessionsMigrationsCommand(sessionsCmd);
     registerSessionsBackfillCommand(sessionsCmd);

package/dist/commands/share.js

@@ -10,13 +10,13 @@ import { formatBytes } from '../lib/format.js';
 import { Argument, Option } from 'commander';
 import chalk from 'chalk';
 import { DEFAULT_BUCKET_NAME, DEFAULT_CF_BUNDLE, DEFAULT_SHARE_DOMAIN, DEFAULT_WORKER_NAME, generateWriteToken, readCloudflareCreds, readShareConfig, readWriteToken, readWriteTokenEnv, readWriteTokenFromBundle, storeWriteToken, writeShareConfig, } from '../lib/share/config.js';
-import { addCustomDomain, configureBucketLifecycle, createBucket, deployWorker, enableWorkersDev, findZoneId, hashWorkerScript, putWorkerSecret, updateWorker, WORKER_PHOENIX_ID_BASE_SECRET, setWorkerSecret, } from '../lib/share/provision.js';
+import { addCustomDomain, configureBucketLifecycle, createBucket, deployWorker, enableWorkersDev, findZoneId, hashWorkerScript, putWorkerSecret, updateWorker, WORKER_PHOENIX_ID_BASE_SECRET, WORKER_COLLAB_BASE_SECRET, WORKER_COLLAB_SERVICE_TOKEN_SECRET, setWorkerSecret, } from '../lib/share/provision.js';
 import { publishFile, resolveShareUsername, parseMetaEntries, sanitizeLabel, scanShareContent, formatSensitiveContentError, unlistedNotPrivateWarning, SHARE_VISIBILITY_LEVELS, PUBLISH_VISIBILITY_LEVELS, } from '../lib/share/publish.js';
 import { deleteShare, resolveDeleteTarget } from '../lib/share/delete.js';
 import { renderWorkerBundle } from '../lib/share/worker-template.js';
 import { analyticsEnabled } from '../lib/share/analytics.js';
 import { extractShareHttpError, formatShareHttpErrorDetail } from '../lib/share/http-error.js';
-import { phoenixIdBaseForDeploy, resolveShareBackend, shouldUseManaged, } from '../lib/share/backend.js';
+import { collabConfigForDeploy, phoenixIdBaseForDeploy, resolveShareBackend, shouldUseManaged, } from '../lib/share/backend.js';
 import { publishVisibility } from '../lib/storage/visibility.js';
 import { resolveGitHubUsername } from '../lib/git.js';
 import { refreshSessionAvatar } from '../lib/identity/index.js';
@@ -1271,6 +1271,15 @@ export async function runShareProvision(opts) {
             await putWorkerSecret(apiToken, accountId, workerName, WORKER_PHOENIX_ID_BASE_SECRET, phoenixIdBase, provisionOpts);
             spin.text = `Worker '${workerName}' Phoenix ID base set`;
         }
+        // Managed collaboration backend (PHNX-3835). Dormant unless BOTH
+        // PRIX_ARTIFACT_COLLAB_BASE and ARTIFACT_COLLAB_SERVICE_TOKEN are set in the
+        // deploy env; the service token rides the Secrets API, never rendered HTML.
+        const collab = collabConfigForDeploy({ managed: opts.managed }, { baseUrl, domain });
+        if (collab.collabBase && collab.collabServiceToken) {
+            await putWorkerSecret(apiToken, accountId, workerName, WORKER_COLLAB_BASE_SECRET, collab.collabBase, provisionOpts);
+            await putWorkerSecret(apiToken, accountId, workerName, WORKER_COLLAB_SERVICE_TOKEN_SECRET, collab.collabServiceToken, provisionOpts);
+            spin.text = `Worker '${workerName}' collaboration backend set`;
+        }
         spin.succeed('Provisioned');
         const cfg = {
             baseUrl,
@@ -1336,10 +1345,14 @@ export async function runShareUpdate(opts = {}) {
     }
     const writeToken = readWriteToken();
     const phoenixIdBase = phoenixIdBaseForDeploy({ managed: opts.managed }, cfg);
+    const collab = collabConfigForDeploy({ managed: opts.managed }, cfg);
     const provisionOpts = {
         ...(opts.request ? { request: opts.request } : {}),
         force: opts.force,
         ...(phoenixIdBase !== undefined ? { phoenixIdBase } : {}),
+        ...(collab.collabBase !== undefined
+            ? { collabBase: collab.collabBase, collabServiceToken: collab.collabServiceToken }
+            : {}),
     };
     const result = await updateWorker(apiToken, accountId, cfg.workerName, cfg.bucketName, worker, writeToken, cfg.templateHash, provisionOpts);
     if (!result.skipped) {

package/dist/commands/sync.js

@@ -190,7 +190,7 @@ export function registerSyncCommand(program) {
         .option('-y, --yes', 'Skip the interactive preview and auto-sync all detected resources', false)
         .option('--force', 'Re-sync even if no changes are detected since the last sync', false)
         .option('--quiet', 'Suppress all output (exit code indicates success)', false)
-        .option('--dry-run', 'Show what would be synced without making any changes', false)
+        .option('--dry-run', 'Show what would be synced without making any changes — requires an agent scope (e.g. agents sync claude --dry-run); the umbrella verb refuses it', false)
         .option('--allow-exec-surfaces', 'Allow syncing plugin exec surfaces (scripts, binaries) — off by default for safety', false)
         .option('--json', 'Emit machine-readable JSON (also accepted so fleet fan-out via --device all can parse each peer)', false)
         // Umbrella verb (no agent given): make this machine current.
@@ -480,6 +480,35 @@ function evictCentralBrowserProfilesForSync(quiet, json, outLog, errLog) {
  * a one-line summary. Stage failures are non-fatal and surfaced as warnings.
  */
 async function runUmbrella(opts, quiet, outLog, errLog, json = false) {
+    // `--dry-run` on the umbrella verb is NOT supported and must fail LOUD before
+    // touching anything (PHNX-3923). The umbrella composes stages that only exist
+    // as mutating operations — repo `git pull`, a full `refresh()` reconcile into
+    // every installed version home, central browser-profile eviction, device sync,
+    // and `repairAfterSync` — none of which carry a non-mutating preview mode. The
+    // old code ignored `opts.dryRun` entirely, ran `runUmbrellaSync` + evict +
+    // repair, and so MUTATED every native home despite `--dry-run`. Rather than
+    // ship a partial preview that silently skips the stages it cannot model (a
+    // lying "would sync" that contradicts the flag's promise), refuse here and
+    // point at the scoped path, which DOES honor `--dry-run` non-destructively.
+    if (opts.dryRun) {
+        const installed = MANAGED_AGENT_IDS.filter((id) => listInstalledVersions(id).length > 0);
+        const example = installed[0] ?? 'claude';
+        const error = '`agents sync --dry-run` has no umbrella preview: the machine-wide sync pulls repos, ' +
+            'reconciles every installed version, syncs devices, and repairs homes — stages that ' +
+            'cannot be previewed without making changes.';
+        const hint = `Preview one agent instead (this is non-destructive): agents sync ${example} --dry-run [--repo <repo>]`;
+        if (json) {
+            emitJson({ ok: false, mode: 'umbrella', dryRun: true, error, hint, installedAgents: installed });
+        }
+        else {
+            errLog(chalk.red(error));
+            errLog(chalk.gray(hint));
+            if (installed.length > 0)
+                errLog(chalk.gray(`Installed agents: ${installed.join(', ')}`));
+        }
+        process.exitCode = 1;
+        return;
+    }
     // Interactive bare `agents sync` (a TTY, no --yes, no scope flag) drops into
     // the two-checklist picker: which repos to sync from, which agents to sync
     // into. Any explicit flag, --yes, or --json keeps the non-interactive path.

package/dist/lib/accounts/slots.js

@@ -15,6 +15,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { agentConfigDirName } from '../agents.js';
 import { harnessAuth, harnessWorkerIsPerDevice } from '../harness-auth-capabilities.js';
+import { installSessionTrackerHookSync } from '../hooks/install.js';
 import { getGlobalDefault, getVersionHomePath, listInstalledVersions } from '../installations/store.js';
 import { carryForwardSettings } from '../settings-manifest.js';
 import { getHistoryDir, readMeta, updateMeta } from '../state.js';
@@ -71,6 +72,12 @@ function projectResources(harness, version, destHome, fromHome) {
             continue;
         writer.write({ version, versionHome: destHome, selection: names, cwd });
     }
+    if (supports(harness, 'hooks', version).ok) {
+        const tracker = installSessionTrackerHookSync(harness, version, destHome);
+        if (!tracker.installed && tracker.error) {
+            console.warn(`agents: SessionStart hook not installed for ${harness} account home ${destHome}: ${tracker.error}`);
+        }
+    }
 }
 /**
  * Remove slot artifacts whose source name is gone. Only the name-keyed kinds

package/dist/lib/agent-spec/agents.d.ts

@@ -355,25 +355,77 @@ export declare function antigravityOsKeyringProbe(platform?: NodeJS.Platform): {
 } | null;
 /** @internal test hook — clear the per-process keyring probe cache. */
 export declare function __resetAntigravityKeychainCacheForTest(): void;
+/** The XDG base dirs OpenCode reads, and the env var that overrides each. */
+declare const OPENCODE_XDG_DIRS: {
+    readonly data: {
+        readonly env: "XDG_DATA_HOME";
+        readonly fallback: readonly [".local", "share"];
+    };
+    readonly state: {
+        readonly env: "XDG_STATE_HOME";
+        readonly fallback: readonly [".local", "state"];
+    };
+};
+/**
+ * Resolve one of OpenCode's (sst/opencode) XDG-rooted files.
+ *
+ * OpenCode keeps provider credentials under `$XDG_DATA_HOME/opencode/` and TUI
+ * state under `$XDG_STATE_HOME/opencode/`, defaulting to `~/.local/share` and
+ * `~/.local/state` on EVERY platform — its `xdg-basedir` dependency does not
+ * special-case macOS, so there is no `~/Library/Application Support` variant.
+ * Both roots are account-global (not per-version), matching how
+ * `session/discover.ts` already resolves `~/.local/share/opencode/opencode.db`.
+ *
+ * Resolution order, first existing wins:
+ *   1. `<base>/<fallback>/opencode/<file>` — the passed per-version home. This is
+ *      primarily a test hook (suites write a hermetic file under a temp home)
+ *      but also covers any relocated install.
+ *   2. `$XDG_<KIND>_HOME/opencode/<file>` — an explicit XDG override, exactly
+ *      what OpenCode itself honours.
+ *   3. `<realHome>/<fallback>/opencode/<file>` — the active default, under
+ *      `AGENTS_REAL_HOME` or `os.homedir()`, so every installed version reflects
+ *      the one account-global state (same fallback shape as
+ *      resolveAccountCredentialPath).
+ * Returns the first existing path, or null. Never throws.
+ */
+export declare function resolveOpenCodeXdgPath(base: string, kind: keyof typeof OPENCODE_XDG_DIRS, file: string): string | null;
+/** OpenCode's signed-in identity, as far as `auth.json` can describe it. */
+export interface OpenCodeIdentity {
+    /** Sorted, "+"-joined provider ids holding a valid credential. */
+    providers: string;
+    /** Account email, when some OAuth credential's token carries the claim. */
+    email: string | null;
+    /** Plan tier from the same token (e.g. `Pro`), when present. */
+    plan: string | null;
+}
 /**
- * OpenCode's account identity: the sorted, "+"-joined list of provider ids
- * that hold a valid credential in `auth.json` (e.g. `"anthropic+muse-spark"`).
- * `auth.json` carries no email/identity claim (see `isValidOpenCodeCredential`),
- * so this join is the closest thing to "which account is this" available — the
- * same value `agents view`/`agents doctor` show for OpenCode's signed-in state.
+ * OpenCode's account identity, read from `auth.json`.
+ *
+ * The provider join (`"meta+openai+opencode-go"`) is the stable key: OpenCode is
+ * a multi-provider harness, so "which providers are configured" is what actually
+ * identifies an install, and `session/discover.ts` indexes sessions by it.
+ * Providers that sign in over OAuth additionally hand OpenCode a token with real
+ * identity claims, so the email and plan are surfaced alongside it instead of
+ * leaving `agents view` showing a bare `id:` key for a login that knows exactly
+ * whose it is. Providers are walked in sorted order so a multi-OAuth install
+ * resolves to the same email on every machine.
  *
  * This is the ONLY correct source for an OpenCode "account". OpenCode's SQLite
  * `opencode.db` also carries `account`/`account_state`/`control_account` tables,
  * but on a real, actively-used install (yosemite-s1, 1.16.0, 35 applied
  * migrations) all three are permanently empty — no migration ever populates
  * them, and no session has ever written a row. Reading from them instead of
- * `auth.json` always yields `undefined`, credential or not; `session/discover.ts`
- * uses this function rather than duplicating a sqlite lookup against those
- * dead tables.
+ * `auth.json` always yields `undefined`, credential or not.
  *
  * Sync (`fs.readFileSync`), no network. Returns undefined when `auth.json` is
  * missing, unreadable, or carries no valid credential.
  */
+export declare function resolveOpenCodeIdentity(base: string): OpenCodeIdentity | undefined;
+/**
+ * The provider join alone — the value `session/discover.ts` indexes sessions by,
+ * kept as its own entry point so callers that only need the key do not have to
+ * know about the OAuth claim walk.
+ */
 export declare function resolveOpenCodeAccountId(base: string): string | undefined;
 /**
  * Whether a Claude version home's credential file is present but carries no