@phnx-labs/agents-cli 1.22.14 → 1.22.16

package/dist/lib/routines.js

@@ -17,6 +17,7 @@ import { ALL_AGENT_IDS } from './agents.js';
 import { machineId, normalizeHost } from './machine-id.js';
 import { resolveActor } from './actor.js';
 import { percentile } from './percentile.js';
+import { enabledRoutineNames, replaceEnabledRoutines, routineEnabledOnThisDevice, setRoutineEnabledOnThisDevice, } from './routine-activation.js';
 export const HOST_STRATEGIES = ['local', 'host', 'fleet', 'cloud'];
 /** Canonical set of accepted GitHub trigger events — single source for validation. */
 export const GITHUB_TRIGGER_EVENTS = [
@@ -82,6 +83,9 @@ export function finalizeRunMeta(meta, status, exitCode, opts) {
  * catchup/overdue, manual run) gates on this.
  */
 export function jobRunsOnThisDevice(config) {
+    const activated = routineEnabledOnThisDevice(config.name);
+    if (activated !== null)
+        return activated;
     const owner = routineOwnerDevice(config);
     // Unrestricted: no pin means fleet-wide by design (`watchdog`, `check-updates`).
     if (owner === null)
@@ -260,7 +264,7 @@ export function listJobs(cwd) {
             jobs.push(job);
         }
     }
-    return jobs;
+    return jobs.map(applyDeviceActivation);
 }
 /**
  * Read a single job config by name, checking project > user > system.
@@ -286,12 +290,16 @@ export function readJob(name, cwd) {
         const job = readJobFromDir(dir, name);
         if (job) {
             if (scope === 'project')
-                return overlayUserRoutineDevices(job, readJobFromDir(userDir, name));
-            return job;
+                return applyDeviceActivation(overlayUserRoutineDevices(job, readJobFromDir(userDir, name)));
+            return applyDeviceActivation(job);
         }
     }
     return null;
 }
+function applyDeviceActivation(job) {
+    const activated = routineEnabledOnThisDevice(job.name);
+    return activated === null ? job : { ...job, enabled: activated };
+}
 function readJobFromDir(dir, name) {
     for (const ext of ['.yml', '.yaml']) {
         const filePath = safeJoin(dir, name + ext);
@@ -327,6 +335,10 @@ function readJobFile(filePath) {
             ...JOB_DEFAULTS,
             ...parsed,
             name: parsed.name || path.basename(filePath).replace(/\.ya?ml$/, ''),
+            // Before a device manifest exists, preserve only explicit legacy state.
+            // A new built-in definition with no `enabled:` field stays opt-in until
+            // setup materializes this host's routines list.
+            enabled: Object.prototype.hasOwnProperty.call(parsed, 'enabled') ? parsed.enabled !== false : false,
         };
     }
     catch {
@@ -368,15 +380,12 @@ export function writeJob(config) {
         delete output.effort;
     if (output.timeout === '10m')
         delete output.timeout;
-    if (output.enabled === true)
-        delete output.enabled;
+    delete output.enabled;
     if (output.runOnce === false || output.runOnce === undefined)
         delete output.runOnce;
     if (output.catchup === true || output.catchup === undefined)
         delete output.catchup;
-    const devArr = output.devices;
-    if (!devArr || devArr.length === 0)
-        delete output.devices;
+    delete output.devices;
     let existingText = null;
     if (ymlExists || yamlExists) {
         try {
@@ -441,8 +450,20 @@ export function setJobEnabled(name, enabled) {
     const job = readJob(name);
     if (!job)
         throw new Error(`Job '${name}' not found`);
-    job.enabled = enabled;
-    writeJob(job);
+    const legacyEnabled = enabledRoutineNames() === null
+        ? listJobs().filter((candidate) => candidate.enabled && jobRunsOnThisDevice(candidate)).map((candidate) => candidate.name)
+        : [];
+    setRoutineEnabledOnThisDevice(name, enabled, legacyEnabled);
+}
+/** Materialize legacy definition state into this device's activation manifest. */
+export function migrateLegacyRoutineActivation() {
+    if (enabledRoutineNames() !== null)
+        return false;
+    const jobs = listJobs();
+    if (!jobs.some((job) => job.enabled || Array.isArray(job.devices)))
+        return false;
+    replaceEnabledRoutines(jobs.filter((job) => job.enabled && jobRunsOnThisDevice(job)).map((job) => job.name));
+    return true;
 }
 /** Validate a partial job config, returning a list of human-readable errors. */
 export function validateJob(config) {
@@ -606,15 +627,6 @@ export function validateJob(config) {
     if (config.catchup !== undefined && typeof config.catchup !== 'boolean') {
         errors.push('catchup must be a boolean (false to skip running a missed fire late)');
     }
-    // Off-box placement without a devices pin fires on every fleet daemon and
-    // each dispatches once (RUSH-1980). Enforce the pin at validation so hand
-    // edits and devices --clear cannot re-open the hole.
-    if (placementRequiresFiringPin(strategy)) {
-        if (!config.devices || config.devices.length === 0) {
-            errors.push(`hostStrategy: ${strategy} requires devices: [<name>] to pin which daemon may fire ` +
-                '(otherwise every fleet daemon dispatches once). Pin to one machine, e.g. devices: [this-host]');
-        }
-    }
     return errors;
 }
 /** Validate a job trigger block, returning a list of human-readable errors. */
@@ -1155,6 +1167,7 @@ export function installJobFromSource(sourcePath, name) {
             return { success: false, error: errors.join(', ') };
         }
         writeJob(config);
+        setJobEnabled(config.name, config.enabled);
         return { success: true };
     }
     catch (err) {

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/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[];

package/dist/lib/staleness/writers/sources.js

@@ -10,7 +10,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { getUserAgentsDir, getAgentsDir, getEnabledExtraRepos, getCommandsDir, getSkillsDir, getHooksDir } from '../../state.js';
-import { safeJoin } from '../../paths.js';
+import { isSafeSegmentName, safeJoin } from '../../paths.js';
 /** Trusted source bases for content-like kinds. Project layer excluded. */
 export function trustedSourceBases() {
     return [
@@ -119,14 +119,100 @@ export function listPluginSkillNames(options = {}) {
     }
     return Array.from(names);
 }
-/** Find the trusted source file for a hook by name. */
+/**
+ * Subdirectories under hooks/ that are never group dirs.
+ * Must stay in lockstep with HOOK_GROUP_SKIP_DIRS in hooks.ts.
+ */
+const HOOK_GROUP_SKIP_DIRS = new Set(['node_modules', '.git', '.cache']);
+const HOOK_SCRIPT_EXTS = new Set([
+    '.sh', '.bash', '.zsh', '.py', '.js', '.ts', '.mjs', '.cjs', '.rb', '.pl', '.ps1', '.cmd', '.bat',
+]);
+function dirHasTopLevelScripts(groupDir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(groupDir);
+    }
+    catch {
+        return false;
+    }
+    for (const name of entries) {
+        if (name.startsWith('.'))
+            continue;
+        const ext = path.extname(name).toLowerCase();
+        if (!HOOK_SCRIPT_EXTS.has(ext))
+            continue;
+        if (isLiveFile(path.join(groupDir, name)))
+            return true;
+    }
+    return false;
+}
+function findNestedHookFile(hooksRoot, basename) {
+    if (!isLiveDir(hooksRoot))
+        return null;
+    let entries;
+    try {
+        entries = fs.readdirSync(hooksRoot).sort();
+    }
+    catch {
+        return null;
+    }
+    for (const name of entries) {
+        if (name.startsWith('.') || HOOK_GROUP_SKIP_DIRS.has(name))
+            continue;
+        const groupDir = path.join(hooksRoot, name);
+        if (!isLiveDir(groupDir))
+            continue;
+        // Only group dirs (those with scripts) contribute nested scripts.
+        if (!dirHasTopLevelScripts(groupDir))
+            continue;
+        const candidate = path.join(groupDir, basename);
+        if (isLiveFile(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * 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 function resolveHookSource(name) {
-    const candidates = [
-        safeJoin(path.join(getUserAgentsDir(), 'hooks'), name),
-        safeJoin(getHooksDir(), name),
-        ...getEnabledExtraRepos().map((e) => safeJoin(path.join(e.dir, 'hooks'), name)),
+    const roots = [
+        path.join(getUserAgentsDir(), 'hooks'),
+        getHooksDir(),
+        ...getEnabledExtraRepos().map((e) => path.join(e.dir, 'hooks')),
     ];
-    return candidates.find(isLiveFile) ?? null;
+    const base = path.basename(name);
+    for (const hooksRoot of roots) {
+        // Exact relative path (top-level or group/name) — multi-segment needs
+        // path.join + containment, not safeJoin (single-segment only).
+        if (name.includes('/') || name.includes('\\')) {
+            const candidate = path.resolve(hooksRoot, name);
+            const rootResolved = path.resolve(hooksRoot);
+            if ((candidate === rootResolved || candidate.startsWith(rootResolved + path.sep)) &&
+                isLiveFile(candidate)) {
+                return candidate;
+            }
+        }
+        else if (isSafeSegmentName(name)) {
+            try {
+                const top = safeJoin(hooksRoot, name);
+                // File script first; then directory bundle (e.g. tests/ fixtures).
+                if (isLiveFile(top))
+                    return top;
+                if (isLiveDir(top) && !dirHasTopLevelScripts(top))
+                    return top;
+            }
+            catch {
+                /* invalid segment */
+            }
+        }
+        const nested = findNestedHookFile(hooksRoot, base);
+        if (nested)
+            return nested;
+    }
+    return null;
 }
 /** All trusted command-skill source roots, used to dedup name collisions for commands-as-skills writes. */
 export function trustedSkillRoots() {

package/dist/lib/startup/command-registry.d.ts

@@ -46,6 +46,7 @@ export declare const loadRoutines: ModuleLoader;
 export declare const loadMonitors: ModuleLoader;
 export declare const loadProjects: ModuleLoader;
 export declare const loadRun: ModuleLoader;
+export declare const loadResume: ModuleLoader;
 export declare const loadFork: ModuleLoader;
 export declare const loadDefaults: ModuleLoader;
 export declare const loadSet: ModuleLoader;
@@ -104,6 +105,7 @@ export declare const loadShare: ModuleLoader;
 export declare const loadAudit: ModuleLoader;
 export declare const loadWebhook: ModuleLoader;
 export declare const loadFunnel: ModuleLoader;
+export declare const loadHumans: ModuleLoader;
 /**
  * Commands whose modules pull in the SQLite-backed session/cloud stack. They are
  * registered AFTER `applyGlobalHelpConventions` (mirroring main's order: help

package/dist/lib/startup/command-registry.js

@@ -24,6 +24,7 @@ export const loadRoutines = async () => (await import('../../commands/routines.j
 export const loadMonitors = async () => (await import('../../commands/monitors.js')).registerMonitorsCommands;
 export const loadProjects = async () => (await import('../../commands/projects.js')).registerProjectsCommands;
 export const loadRun = async () => (await import('../../commands/exec.js')).registerRunCommand;
+export const loadResume = async () => (await import('../../commands/resume.js')).registerResumeCommand;
 export const loadFork = async () => (await import('../../commands/fork.js')).registerForkCommand;
 export const loadDefaults = async () => (await import('../../commands/defaults.js')).registerDefaultsCommands;
 export const loadSet = async () => (await import('../../commands/set.js')).registerSetCommand;
@@ -82,6 +83,7 @@ export const loadShare = async () => (await import('../../commands/share.js')).r
 export const loadAudit = async () => (await import('../../commands/audit.js')).registerAuditCommands;
 export const loadWebhook = async () => (await import('../../commands/webhook.js')).registerWebhookCommand;
 export const loadFunnel = async () => (await import('../../commands/funnel.js')).registerFunnelCommand;
+export const loadHumans = async () => (await import('../../commands/humans.js')).registerHumansCommands;
 /**
  * Commands whose modules pull in the SQLite-backed session/cloud stack. They are
  * registered AFTER `applyGlobalHelpConventions` (mirroring main's order: help
@@ -93,6 +95,7 @@ export const loadFunnel = async () => (await import('../../commands/funnel.js'))
 // same SQLite stack, same post-help registration order as sessions.
 export const LAZY_COMMAND_NAMES = new Set([
     'sessions',
+    'resume',
     'roster',
     'teams',
     'cloud',
@@ -145,6 +148,7 @@ export const COMMAND_LOADERS = {
     monitors: [loadMonitors],
     projects: [loadProjects],
     run: [loadRun],
+    resume: [loadResume],
     fork: [loadFork],
     defaults: [loadDefaults],
     set: [loadSet],
@@ -221,4 +225,5 @@ export const COMMAND_LOADERS = {
     audit: [loadAudit],
     webhook: [loadWebhook],
     funnel: [loadFunnel],
+    humans: [loadHumans],
 };

package/dist/lib/state.d.ts

@@ -23,6 +23,8 @@
  * and leaves a back-compat symlink at the old path.
  */
 import type { Meta } from './types.js';
+/** Return the absolute path to the humans.yaml file. */
+export declare function getHumansFilePath(): string;
 /**
  * Header prepended to every agents.yaml the CLI writes (central and per-device
  * docs). Carries the yaml-language-server schema hint so editors validate the