@phnx-labs/agents-cli 1.22.15 → 1.22.17

package/dist/lib/permissions.js

@@ -122,9 +122,9 @@ export function convertDenyToCodexRules(deny) {
  * Ensure central permissions directory exists.
  */
 function ensurePermissionsDir() {
-    const dir = getUserPermissionsDir();
-    if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true });
+    const groupsDir = path.join(getUserPermissionsDir(), 'groups');
+    if (!fs.existsSync(groupsDir)) {
+        fs.mkdirSync(groupsDir, { recursive: true });
     }
 }
 /**
@@ -350,7 +350,8 @@ export function listInstalledPermissions() {
     ensureAgentsDir();
     const seen = new Set();
     const results = [];
-    for (const dir of [getUserPermissionsDir(), getPermissionsDir()]) {
+    for (const baseDir of [getUserPermissionsDir(), getPermissionsDir()]) {
+        const dir = path.join(baseDir, 'groups');
         if (!fs.existsSync(dir))
             continue;
         try {
@@ -377,10 +378,11 @@ export function listInstalledPermissions() {
     return results;
 }
 /**
- * Get a specific permission set by name. Searches user dir first, then system.
+ * Get a specific permission set by name. Searches user groups/ dir first, then system groups/.
  */
 function getPermissionSet(name) {
-    for (const dir of [getUserPermissionsDir(), getPermissionsDir()]) {
+    for (const baseDir of [getUserPermissionsDir(), getPermissionsDir()]) {
+        const dir = path.join(baseDir, 'groups');
         for (const ext of ['.yml', '.yaml']) {
             const filePath = safeJoin(dir, name + ext);
             if (fs.existsSync(filePath)) {
@@ -402,7 +404,7 @@ export function installPermissionSet(sourcePath, name) {
     if (!set) {
         return { success: false, error: 'Invalid permission file' };
     }
-    const targetPath = safeJoin(getUserPermissionsDir(), name + '.yml');
+    const targetPath = safeJoin(path.join(getUserPermissionsDir(), 'groups'), name + '.yml');
     try {
         fs.copyFileSync(sourcePath, targetPath);
         return { success: true };
@@ -416,9 +418,9 @@ export function installPermissionSet(sourcePath, name) {
  * sets are intentionally not deletable from user commands.
  */
 export function removePermissionSet(name) {
-    const dir = getUserPermissionsDir();
+    const groupsDir = path.join(getUserPermissionsDir(), 'groups');
     for (const ext of ['.yml', '.yaml']) {
-        const filePath = safeJoin(dir, name + ext);
+        const filePath = safeJoin(groupsDir, name + ext);
         if (fs.existsSync(filePath)) {
             try {
                 fs.unlinkSync(filePath);
@@ -2025,7 +2027,7 @@ export function exportPermissionsFromPath(filePath) {
  */
 function savePermissionSet(set) {
     ensurePermissionsDir();
-    const filePath = safeJoin(getUserPermissionsDir(), set.name + '.yml');
+    const filePath = safeJoin(path.join(getUserPermissionsDir(), 'groups'), set.name + '.yml');
     try {
         const content = yaml.stringify({
             name: set.name,

package/dist/lib/placement.d.ts

@@ -2,7 +2,7 @@
  * Placement — one model for "where does the body run?"
  *
  * The CLI grew several doors that all mean execution target:
- *   run --host / --device / --lease / --box
+ *   run --host / --device / --lease / --box / --cloud
  *   routines --placement / --run-on / hostStrategy
  *   monitors --run-on (body) vs --device (owner — NOT placement)
  *   teams --device (teammate pin)
@@ -41,6 +41,10 @@ export interface RunPlacementFlags {
     computer?: string;
     lease?: string | boolean;
     box?: string;
+    /** --cloud: vendor cloud placement (the agent's native cloud provider). */
+    cloud?: boolean;
+    /** --provider: refines the cloud placement; not a placement on its own. */
+    provider?: string;
 }
 export declare class PlacementError extends Error {
     constructor(message: string);
@@ -68,10 +72,10 @@ export declare function placementFromRunFlags(flags: RunPlacementFlags): Placeme
  * Expand a resolved placement into the concrete run option fields the
  * existing dispatch paths already understand. Pure — does not mutate input.
  *
- * `cloud` and `fleet` are not valid for a bare `agents run` (use `cloud run`
- * / routines); they throw so callers fail loud.
+ * `fleet` is not valid for a bare `agents run` (it is a routines placement);
+ * it throws so callers fail loud.
  */
-export declare function expandPlacementToRunFlags(placement: Placement): Pick<RunPlacementFlags, 'host' | 'device' | 'lease' | 'box'>;
+export declare function expandPlacementToRunFlags(placement: Placement): Pick<RunPlacementFlags, 'host' | 'device' | 'lease' | 'box' | 'cloud' | 'provider'>;
 /** Map routines hostStrategy (+ optional host) onto the shared Placement. */
 export declare function placementFromHostStrategy(strategy: 'local' | 'host' | 'fleet' | 'cloud', host?: string): Placement;
 /** One-line human form for logs / help. */

package/dist/lib/placement.js

@@ -2,7 +2,7 @@
  * Placement — one model for "where does the body run?"
  *
  * The CLI grew several doors that all mean execution target:
- *   run --host / --device / --lease / --box
+ *   run --host / --device / --lease / --box / --cloud
  *   routines --placement / --run-on / hostStrategy
  *   monitors --run-on (body) vs --device (owner — NOT placement)
  *   teams --device (teammate pin)
@@ -93,6 +93,7 @@ export function placementFromRunFlags(flags) {
     const hostT = hostFamilyTarget(flags);
     const hasLease = flags.lease !== undefined && flags.lease !== false;
     const hasBox = !!flags.box;
+    const hasCloud = flags.cloud === true;
     const placementFlags = [];
     if (where)
         placementFlags.push('--where');
@@ -102,12 +103,16 @@ export function placementFromRunFlags(flags) {
         placementFlags.push('--lease');
     if (hasBox)
         placementFlags.push('--box');
+    if (hasCloud)
+        placementFlags.push('--cloud');
     if (placementFlags.length > 1) {
         throw new PlacementError(`Conflicting placement flags: ${placementFlags.join(' + ')}. ` +
-            `Use one door — prefer --where (device:<name> | auto | lease | local).`);
+            `Use one door — prefer --where (device:<name> | auto | lease | cloud | local).`);
     }
     if (where)
         return parseWhereSpec(where, '--where');
+    if (hasCloud)
+        return { kind: 'cloud', target: flags.provider, source: '--cloud' };
     if (hasBox)
         return { kind: 'lease', target: flags.box, source: '--box' };
     if (hasLease) {
@@ -122,8 +127,8 @@ export function placementFromRunFlags(flags) {
  * Expand a resolved placement into the concrete run option fields the
  * existing dispatch paths already understand. Pure — does not mutate input.
  *
- * `cloud` and `fleet` are not valid for a bare `agents run` (use `cloud run`
- * / routines); they throw so callers fail loud.
+ * `fleet` is not valid for a bare `agents run` (it is a routines placement);
+ * it throws so callers fail loud.
  */
 export function expandPlacementToRunFlags(placement) {
     switch (placement.kind) {
@@ -140,12 +145,13 @@ export function expandPlacementToRunFlags(placement) {
             if (placement.source === '--box')
                 return { box: placement.target };
             return placement.target ? { lease: placement.target } : { lease: true };
+        case 'cloud':
+            // Vendor cloud placement — `--where cloud[:provider]` expands to the
+            // --cloud flag (+ --provider refinement) the run action dispatches on.
+            return placement.target ? { cloud: true, provider: placement.target } : { cloud: true };
         case 'fleet':
             throw new PlacementError(`fleet placement is for routines (agents routines add … --placement fleet), not agents run. ` +
                 `Use --where device:auto for an affinity pick, or --where device:<name>.`);
-        case 'cloud':
-            throw new PlacementError(`cloud placement is agents cloud run (vendor cloud), not agents run. ` +
-                `For a disposable box use --where lease; for your fleet use --where device:<name>.`);
     }
 }
 /** Map routines hostStrategy (+ optional host) onto the shared Placement. */
@@ -180,9 +186,9 @@ export const PLACEMENT_MATRIX = `
   Affinity pick (14d usage)      --where auto            (= --device auto)
   Disposable cloud box           --where lease           (= --lease)
   Reuse warm crabbox             --box <slug>
+  Vendor cloud task              --cloud   (= --where cloud[:provider])
   Routines: body on one box      --run-on <name> / --placement host
   Routines: pick any online      --placement fleet
-  Vendor cloud task              agents cloud run …
   Monitors: who evaluates        --device <owner>   (NOT body placement)
   Monitors: where action runs    --run-on <host>
 `.trim();

package/dist/lib/projects.d.ts

@@ -132,9 +132,9 @@ export declare function validateProjectDef(raw: unknown, sourceName?: string): P
  */
 export declare function loadProjectDef(name: string): ProjectDef | undefined;
 /**
- * List every defined project, sorted by name. Skips (does not throw on) a
- * malformed file so one bad definition can't break `projects list`; the loader
- * for a single named project stays strict.
+ * List every defined project, sorted by name. A missing projects directory is
+ * the empty state; malformed definitions and filesystem failures stay loud so
+ * CLI callers (including Factory) can show the actual error.
  */
 export declare function listProjectDefs(): ProjectDef[];
 /**

package/dist/lib/projects.js

@@ -187,15 +187,18 @@ export function loadProjectDef(name) {
     try {
         raw = fs.readFileSync(projectDefPath(name), 'utf8');
     }
-    catch {
-        return undefined; // absent — not a defined project
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return undefined; // absent — not a defined project
+        }
+        throw error;
     }
     return validateProjectDef(yaml.parse(raw), name);
 }
 /**
- * List every defined project, sorted by name. Skips (does not throw on) a
- * malformed file so one bad definition can't break `projects list`; the loader
- * for a single named project stays strict.
+ * List every defined project, sorted by name. A missing projects directory is
+ * the empty state; malformed definitions and filesystem failures stay loud so
+ * CLI callers (including Factory) can show the actual error.
  */
 export function listProjectDefs() {
     let files;
@@ -205,20 +208,17 @@ export function listProjectDefs() {
         // loader and silently drop the project. One extension, one code path.
         files = fs.readdirSync(getProjectsDir()).filter((f) => f.endsWith('.yaml'));
     }
-    catch {
-        return [];
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
     }
     const out = [];
     for (const f of files) {
         const name = f.replace(/\.yaml$/, '');
-        try {
-            const def = loadProjectDef(name);
-            if (def)
-                out.push(def);
-        }
-        catch {
-            /* malformed — skip in the listing */
-        }
+        const def = loadProjectDef(name);
+        if (def)
+            out.push(def);
     }
     return out.sort((a, b) => a.name.localeCompare(b.name));
 }
@@ -255,8 +255,10 @@ export function removeProjectDef(name) {
         fs.unlinkSync(projectDefPath(name));
         return true;
     }
-    catch {
-        return false;
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
     }
 }
 /**

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

@@ -178,6 +178,17 @@ export declare function shouldEvictAfterBundleWrite(skipRequested: boolean, noAg
 export declare function writeBundle(bundle: SecretsBundle, opts?: WriteBundleOptions): void;
 export declare function writeBundleWithItems(bundle: SecretsBundle, items: Map<string, string>, opts?: WriteBundleOptions): void;
 export declare function deleteBundle(name: string): boolean;
+declare function readBundleMetaIndex(): string[] | null;
+declare function writeBundleMetaIndex(services: string[]): void;
+declare function addBundleToMetaIndex(name: string): void;
+declare function removeBundleFromMetaIndex(name: string): void;
+/** Test-only accessors for the metadata-name index. Never called in production. */
+export declare const __metaIndexForTest: {
+    read: typeof readBundleMetaIndex;
+    write: typeof writeBundleMetaIndex;
+    add: typeof addBundleToMetaIndex;
+    remove: typeof removeBundleFromMetaIndex;
+};
 /**
  * Re-write already-read keychain bundle metadata items WITHOUT the biometry ACL.
  * `metaJsonByName` maps bundle name → the exact metadata JSON listBundles just

package/dist/lib/secrets/bundles.js

@@ -468,6 +468,8 @@ export function writeBundle(bundle, opts = {}) {
     // un-updated pinned helper this write fails loudly (the no-ACL command is
     // missing) rather than silently landing an ACL'd item.
     itemStore(prepared.backend).set(prepared.metadataItem, prepared.metadataJson, { noAcl: true });
+    if (prepared.backend === 'keychain')
+        addBundleToMetaIndex(bundle.name);
     finishBundleWrite(bundle, opts);
 }
 export function writeBundleWithItems(bundle, items, opts = {}) {
@@ -485,6 +487,7 @@ export function writeBundleWithItems(bundle, items, opts = {}) {
             store.setBatch(new Map(items), { noAcl: bundle.policy === 'never' });
         }
         store.set(prepared.metadataItem, prepared.metadataJson, { noAcl: true });
+        addBundleToMetaIndex(bundle.name);
     }
     else {
         // file / vault: no ACL concept (noAcl is ignored), so one batched write is
@@ -497,8 +500,11 @@ export function writeBundleWithItems(bundle, items, opts = {}) {
 }
 export function deleteBundle(name) {
     validateBundleName(name);
-    const deleted = itemStore(bundleBackend(name)).delete(bundleMetaItem(name));
+    const backend = bundleBackend(name);
+    const deleted = itemStore(backend).delete(bundleMetaItem(name));
     if (deleted) {
+        if (backend === 'keychain')
+            removeBundleFromMetaIndex(name);
         emit('secrets.delete', { module: 'secrets', bundle: name });
         if (shouldEvictAfterBundleWrite(false, process.env.AGENTS_SECRETS_NO_AGENT, isKeychainBackendOverridden())) {
             agentEvictSync(name);
@@ -581,6 +587,104 @@ function markBundleMetadataAclHealed() {
         // on the next broker-miss listing.
     }
 }
+// ── No-ACL bundle-metadata name index (kills the enumeration Touch ID storm) ──
+// listBundles cannot ask the keychain for "just the metadata items": with hashed
+// service names (#316) the metadata names are opaque (`agents-cli.h.<ns>.m`), so
+// listKeychainItems(BUNDLE_META_PREFIX) falls back to a BROAD `agents-cli.` scan
+// that also MATCHES the ACL'd secret VALUE items. On some machines macOS
+// evaluates those value ACLs during that attributes-only scan and pops a generic
+// "Agents CLI needs to authenticate" sheet — on EVERY launch (session-title
+// generation, `agents devices list`, every agent run), because listBundles runs
+// on essentially every secrets touch. Neither UIFail nor LAContext can list the
+// no-ACL items while skipping the ACL'd ones (both return nothing), so the fix is
+// to NOT do the broad scan: keep a per-machine index of the metadata items'
+// STORAGE names in the regenerable helpers dir and read THAT (a silent file read)
+// instead. The index holds opaque hashes only — no cleartext bundle names, so it
+// leaks nothing #316 didn't already. It self-heals: absent/unbuilt → listBundles
+// rebuilds it from the one-time broad scan; a stale entry only makes `secrets
+// list` cosmetically incomplete and never affects a resolve-by-name (which
+// computes the hashed name directly, never through this index).
+function bundleMetaIndexPath() {
+    // Test-only override (mirrors AGENTS_DAEMON_DIR): redirect to a fork-private
+    // temp so unit tests never touch the real helpers dir. Never set in prod.
+    return (process.env.AGENTS_SECRETS_META_INDEX_FILE ||
+        path.join(getHelpersDir(), 'secrets-agent', 'bundle-meta-index.json'));
+}
+// Changes iff the service-name hashing key changes (the #316 re-key, or a
+// cleartext<->hashed transition). Stamped into the index so an index built under
+// an OLD key reads as absent and is rebuilt — otherwise a re-key would leave
+// stale hashed names that resolve to nothing and make every bundle "vanish".
+function metaIndexFingerprint() {
+    return keychainServiceAlias(`${BUNDLE_META_PREFIX}meta-index-fingerprint`);
+}
+function readBundleMetaIndex() {
+    // A test-installed in-memory keychain is NOT the real store this index mirrors;
+    // reading (and later writing) the real ~/.agents index from a mock-backend test
+    // would leak fixture bundle names into a developer's live cache. Same guard the
+    // sibling healKeychainBundleMetadataAclOnce uses — treat the index as absent so
+    // listBundles falls back to the (mock) scan.
+    if (isKeychainBackendOverridden())
+        return null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(bundleMetaIndexPath(), 'utf-8'));
+        if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.services))
+            return null;
+        if (parsed.fp !== metaIndexFingerprint())
+            return null; // built under a different hashing key
+        return parsed.services.every((s) => typeof s === 'string') ? parsed.services : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeBundleMetaIndex(services) {
+    if (isKeychainBackendOverridden())
+        return; // never write the real index from a mock-backend test
+    try {
+        const file = bundleMetaIndexPath();
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const payload = { fp: metaIndexFingerprint(), services: [...new Set(services)].sort() };
+        // Atomic write (unique temp + rename) so a concurrent reader/writer never
+        // sees a half-written file. The read-modify-write in add/remove can still
+        // race two concurrent BUNDLE mutations and drop an entry, but that only makes
+        // a `secrets list` cosmetically incomplete (never a resolve-by-name) and
+        // self-heals on the next rebuild — an acceptable trade for rare bundle edits.
+        const tmp = `${file}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(payload), 'utf8');
+        fs.renameSync(tmp, file);
+    }
+    catch {
+        // Best effort — a missing index just means listBundles rebuilds it from the
+        // one-time broad scan on the next enumeration.
+    }
+}
+// Append a metadata item's STORAGE name to an ALREADY-BUILT index. No-op when the
+// index has not been built yet (null): never create a one-entry index that would
+// hide every OTHER bundle — listBundles builds the complete index on its first
+// scan, and this newly-written bundle is included in that scan.
+function addBundleToMetaIndex(name) {
+    const cur = readBundleMetaIndex();
+    if (cur === null)
+        return;
+    const svc = keychainServiceAlias(bundleMetaItem(name));
+    if (!cur.includes(svc))
+        writeBundleMetaIndex([...cur, svc]);
+}
+function removeBundleFromMetaIndex(name) {
+    const cur = readBundleMetaIndex();
+    if (cur === null)
+        return;
+    const svc = keychainServiceAlias(bundleMetaItem(name));
+    if (cur.includes(svc))
+        writeBundleMetaIndex(cur.filter((s) => s !== svc));
+}
+/** Test-only accessors for the metadata-name index. Never called in production. */
+export const __metaIndexForTest = {
+    read: readBundleMetaIndex,
+    write: writeBundleMetaIndex,
+    add: addBundleToMetaIndex,
+    remove: removeBundleFromMetaIndex,
+};
 /**
  * Re-write already-read keychain bundle metadata items WITHOUT the biometry ACL.
  * `metaJsonByName` maps bundle name → the exact metadata JSON listBundles just
@@ -643,11 +747,24 @@ export function listBundles() {
     // file store is the single source of truth, so the block below covers all.
     if (!keychainUsesFileFallback()) {
         let keychainServices = [];
-        try {
-            keychainServices = listKeychainItems(BUNDLE_META_PREFIX);
+        // Prefer the no-ACL metadata-name index (a silent file read) over the broad
+        // `agents-cli.` keychain scan — that scan also matches ACL'd secret VALUE
+        // items and pops Touch ID on every launch (see the index helpers above).
+        // Absent index (first list after upgrade / a cache wipe) → do the one broad
+        // scan and build the index from it, so that scan is the LAST one this machine
+        // performs.
+        const indexedServices = readBundleMetaIndex();
+        if (indexedServices !== null) {
+            keychainServices = indexedServices;
         }
-        catch {
-            keychainServices = [];
+        else {
+            try {
+                keychainServices = listKeychainItems(BUNDLE_META_PREFIX);
+                writeBundleMetaIndex(keychainServices);
+            }
+            catch {
+                keychainServices = [];
+            }
         }
         // With hashed service names (macOS, #316) the enumerated services are
         // opaque (`agents-cli.h.<ns>.m`) — the display name is recovered from the

package/dist/lib/session/actor-sidecar.d.ts

@@ -1,9 +1,12 @@
+import type { SessionRunMode } from './types.js';
 export interface SessionActorRecord {
     sessionId: string;
     /** Resolved actor id (`resolveActor().id`) — the responsible human/agent. */
-    actor: string;
+    actor?: string;
     /** Actor kind (`resolveActor().kind`). */
-    initiatedBy: 'human' | 'agent';
+    initiatedBy?: 'human' | 'agent';
+    /** Effective permissions mode used by the launcher. */
+    mode?: SessionRunMode;
     startedAtMs: number;
 }
 /**

package/dist/lib/session/actor-sidecar.js

@@ -62,7 +62,8 @@ export function readSessionActorRecord(sessionId) {
     }
     try {
         const parsed = JSON.parse(raw);
-        if (parsed && typeof parsed === 'object' && typeof parsed.sessionId === 'string' && typeof parsed.actor === 'string') {
+        if (parsed && typeof parsed === 'object' && typeof parsed.sessionId === 'string' &&
+            (typeof parsed.actor === 'string' || typeof parsed.mode === 'string')) {
             return parsed;
         }
     }
@@ -89,7 +90,8 @@ export function loadSessionActorIndex() {
     for (const f of files) {
         try {
             const parsed = JSON.parse(fs.readFileSync(path.join(sidecarDir(), f), 'utf8'));
-            if (parsed && typeof parsed === 'object' && typeof parsed.sessionId === 'string' && typeof parsed.actor === 'string') {
+            if (parsed && typeof parsed === 'object' && typeof parsed.sessionId === 'string' &&
+                (typeof parsed.actor === 'string' || typeof parsed.mode === 'string')) {
                 out.set(parsed.sessionId, parsed);
             }
         }

package/dist/lib/session/db.d.ts

@@ -12,7 +12,7 @@ import { type IndexedToolCall } from './tool-calls.js';
 /** Current schema version; bumped when migrations are added. Exported so tests
  * assert against the constant instead of hardcoding a number that every bump
  * then has to chase (docs/05-sessions.md calls the constant the source of truth). */
-export declare const SCHEMA_VERSION = 31;
+export declare const SCHEMA_VERSION = 32;
 /**
  * Bump to force `agents sessions backfill resources` to re-derive every
  * session's skill/slash-command tallies on its next run (resource_scan_ledger
@@ -30,6 +30,7 @@ export interface SessionRow {
     routine_run_id: string | null;
     version: string | null;
     account: string | null;
+    mode: string | null;
     timestamp: string;
     last_activity: string | null;
     project: string | null;

package/dist/lib/session/db.js

@@ -25,7 +25,7 @@ const DB_PATH = getSessionsDbPath();
 /** Current schema version; bumped when migrations are added. Exported so tests
  * assert against the constant instead of hardcoding a number that every bump
  * then has to chase (docs/05-sessions.md calls the constant the source of truth). */
-export const SCHEMA_VERSION = 31;
+export const SCHEMA_VERSION = 32;
 /**
  * Bump to force `agents sessions backfill resources` to re-derive every
  * session's skill/slash-command tallies on its next run (resource_scan_ledger
@@ -67,6 +67,7 @@ CREATE TABLE IF NOT EXISTS sessions (
   routine_run_id TEXT,
   version TEXT,
   account TEXT,
+  mode TEXT,
   timestamp TEXT NOT NULL,
   last_activity TEXT,
   project TEXT,
@@ -721,6 +722,14 @@ function migrateSchema(db, fromVersion) {
       );
     `);
     }
+    if (fromVersion < 32) {
+        // v31 → v32: persist the effective managed launch mode so resume can
+        // restore the same permission boundary instead of falling back to a CLI
+        // default that may be more or less permissive.
+        const cols = new Set(db.prepare(`PRAGMA table_info(sessions)`).all().map((column) => column.name));
+        if (!cols.has('mode'))
+            db.exec(`ALTER TABLE sessions ADD COLUMN mode TEXT`);
+    }
 }
 /** Open (or return the cached) sessions database, applying migrations as needed. */
 export function getDB() {
@@ -1115,7 +1124,7 @@ export function recordDirScans(entries) {
 const upsertSessionStmt = (db) => db.prepare(`
   INSERT INTO sessions (
     id, short_id, agent, origin, routine_name, routine_run_id,
-    version, account, timestamp, last_activity,
+    version, account, mode, timestamp, last_activity,
     project, cwd, git_branch, topic, label, message_count, token_count,
     output_tokens, cost_usd, duration_ms, model, tool_call_count,
     file_path, file_mtime_ms, file_size, scanned_at, is_team_origin,
@@ -1124,7 +1133,7 @@ const upsertSessionStmt = (db) => db.prepare(`
     actor, initiated_by, used_browser, used_computer
   ) VALUES (
     @id, @short_id, @agent, @origin, @routine_name, @routine_run_id,
-    @version, @account, @timestamp, @last_activity,
+    @version, @account, @mode, @timestamp, @last_activity,
     @project, @cwd, @git_branch, @topic, @label, @message_count, @token_count,
     @output_tokens, @cost_usd, @duration_ms, @model, @tool_call_count,
     @file_path, @file_mtime_ms, @file_size, @scanned_at, @is_team_origin,
@@ -1140,6 +1149,7 @@ const upsertSessionStmt = (db) => db.prepare(`
     routine_run_id = excluded.routine_run_id,
     version = excluded.version,
     account = excluded.account,
+    mode = COALESCE(excluded.mode, sessions.mode),
     timestamp = excluded.timestamp,
     last_activity = excluded.last_activity,
     project = excluded.project,
@@ -1382,6 +1392,7 @@ export function upsertSession(meta, content, scan) {
         routine_run_id: meta.routineRunId ?? null,
         version: meta.version ?? null,
         account: meta.account ?? null,
+        mode: meta.mode ?? actorRec?.mode ?? null,
         timestamp: meta.timestamp,
         last_activity: resolveLastActivity(meta, scan),
         project: meta.project ?? null,
@@ -1545,6 +1556,7 @@ export function upsertSessionsBatch(entries) {
                     routine_run_id: meta.routineRunId ?? null,
                     version: meta.version ?? null,
                     account: meta.account ?? null,
+                    mode: meta.mode ?? actorIndex.get(meta.id)?.mode ?? null,
                     timestamp: meta.timestamp,
                     last_activity: resolveLastActivity(meta, scan),
                     project: meta.project ?? null,
@@ -1768,6 +1780,7 @@ function rowToMeta(row) {
         toolCallCount: row.tool_call_count ?? undefined,
         version: row.version ?? undefined,
         account: row.account ?? undefined,
+        mode: isSessionRunMode(row.mode) ? row.mode : undefined,
         topic: row.topic ?? undefined,
         label: row.label ?? undefined,
         isTeamOrigin: row.is_team_origin === 1,
@@ -1793,6 +1806,9 @@ function rowToMeta(row) {
         usedComputer: row.used_computer === null ? undefined : row.used_computer === 1,
     };
 }
+function isSessionRunMode(value) {
+    return value === 'plan' || value === 'edit' || value === 'auto' || value === 'skip';
+}
 function parseJsonColumn(value) {
     if (!value)
         return undefined;

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

@@ -8,6 +8,8 @@
  */
 /** Agents that store session data on disk and can be discovered by `agents sessions`. */
 export type SessionAgentId = 'claude' | 'codex' | 'gemini' | 'antigravity' | 'opencode' | 'openclaw' | 'rush' | 'hermes' | 'grok' | 'kimi' | 'droid' | 'cursor';
+/** Effective permissions mode used to launch a managed agent session. */
+export type SessionRunMode = 'plan' | 'edit' | 'auto' | 'skip';
 /** All agents with session discovery support, in display order. */
 export declare const SESSION_AGENTS: SessionAgentId[];
 /**
@@ -151,6 +153,8 @@ export interface SessionMeta {
     toolCallCount?: number;
     version?: string;
     account?: string;
+    /** Effective normalized launch mode captured by the SessionStart hook. */
+    mode?: SessionRunMode;
     topic?: string;
     /**
      * The session's human-readable name — one field, several sources with a plain

package/dist/lib/settings-manifest.js

@@ -30,7 +30,13 @@ const SETTINGS_MANIFEST = {
             strategy: 'toml-merge',
             stateKeys: ['notice', 'windows_wsl_setup_acknowledged'],
         },
-        { rel: '.codex/auth.json', strategy: 'copy-if-absent', restrictMode: true },
+        // `.codex/auth.json` is deliberately NOT carried forward. Copying it seeded
+        // every new Codex version with the current default's ChatGPT token, so two
+        // installed versions always reported the same account and could never sign
+        // into separate accounts. Claude omits its credential (`.claude.json`) for
+        // the same reason — a version home holds its own login, keeping accounts
+        // per-version. A fresh Codex version installs signed-out; run `codex login`
+        // (or `agents run codex --version <v>`) inside it to authenticate.
         { rel: '.codex/instructions.md', strategy: 'copy-if-absent' },
         { rel: '.codex/hooks.json', strategy: 'copy-if-absent' },
         { rel: '.codex/prompts', strategy: 'dir-entries' },

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

@@ -19,7 +19,12 @@ export declare function listPluginSkillNames(options?: {
     agent?: AgentId;
     plugins?: Set<string>;
 }): string[];
-/** Find the trusted source file for a hook by name. */
+/**
+ * Find the trusted source for a hook by name.
+ * - File basename (`04-session-identity.sh`) or relative path
+ *   (`session-starts/04-session-identity.sh`) → script file
+ * - Directory basename (`tests`) → directory bundle (fixtures-only etc.)
+ */
 export declare function resolveHookSource(name: string): string | null;
 /** All trusted command-skill source roots, used to dedup name collisions for commands-as-skills writes. */
 export declare function trustedSkillRoots(): string[];