@phnx-labs/agents-cli 1.22.10 → 1.22.12

package/dist/lib/events.js

@@ -1,8 +1,8 @@
 /**
  * Centralized event logging for agents-cli.
  *
- * Structured JSONL audit log at ~/.agents/events.jsonl with lossless numbered
- * gzip rotation at 10 MB and rich metadata for debugging/auditing.
+ * Structured JSONL audit logs at ~/.agents/.history/events/YYYY-MM-DD/events.jsonl with
+ * lossless numbered gzip rotation at 10 MiB and bounded retention.
  *
  * Features:
  * - Rich metadata: hostname, platform, arch, pid, timezone
@@ -47,14 +47,42 @@ function recordPerfTiming(payload) {
 // unlike _resetForTest it survives a bare reset AND propagates to CLI subprocesses
 // a test spawns, so fixture events can never land in the user's real log (#910).
 let _eventsPath;
-function eventsPath() {
-    return (_eventsPath ??= process.env.AGENTS_EVENTS_PATH || path.join(getUserAgentsDir(), 'events.jsonl'));
+let _eventsPathOverride = false;
+let _legacyMigrationChecked = false;
+let _userAgentsDirOverride;
+function userAgentsDir() {
+    return _userAgentsDirOverride ?? getUserAgentsDir();
 }
-function eventsDir() {
-    return path.dirname(eventsPath());
+function localDateKey(date = new Date()) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+}
+function eventsRoot() {
+    if (_eventsPathOverride && _eventsPath)
+        return path.dirname(_eventsPath);
+    return path.join(userAgentsDir(), '.history', 'events');
+}
+function eventsPath(date = new Date()) {
+    if (_eventsPathOverride && _eventsPath)
+        return _eventsPath;
+    const override = _userAgentsDirOverride ? undefined : process.env.AGENTS_EVENTS_PATH;
+    if (override) {
+        _eventsPathOverride = true;
+        return (_eventsPath = override);
+    }
+    return path.join(eventsRoot(), localDateKey(date), 'events.jsonl');
+}
+function eventsDir(date = new Date()) {
+    return path.dirname(eventsPath(date));
 }
 /** Default retention period in days. */
 const DEFAULT_RETENTION_DAYS = 7;
+/** Default total footprint for the active log plus gzip archives (50 MiB). */
+const DEFAULT_MAX_STORAGE_BYTES = 50 * 1024 * 1024;
+/** Cross-process marker used to avoid a full archive scan on every append. */
+const PRUNE_MARKER = '.last-prune';
 /** Default max length for truncated strings. */
 const DEFAULT_TRUNCATE_LENGTH = 500;
 /** Gzip rotation threshold in bytes (10 MB). */
@@ -154,6 +182,8 @@ function getTimezoneName() {
     }
 }
 function ensureLogsDir() {
+    eventsPath(); // Resolve an explicit AGENTS_EVENTS_PATH before migration checks.
+    migrateLegacyEventLogs();
     if (!fs.existsSync(eventsDir())) {
         fs.mkdirSync(eventsDir(), { recursive: true, mode: DIR_MODE });
     }
@@ -167,6 +197,102 @@ function ensureLogsDir() {
         }
     }
 }
+/**
+ * Move root-level and interim flat-history event families into dated directories.
+ *
+ * The common case is a whole-family rename into an empty destination. A
+ * Each segment is assigned to the local calendar day of its filesystem mtime;
+ * new writes are split by day at source. A partially completed migration keeps
+ * the destination active file authoritative and assigns a fresh archive number,
+ * so no record is overwritten or silently discarded. The legacy active-file
+ * lock serializes this with older installed processes that still append there.
+ */
+export function migrateLegacyEventLogs(userDir = userAgentsDir()) {
+    if (_eventsPathOverride || _legacyMigrationChecked)
+        return 0;
+    _legacyMigrationChecked = true;
+    const destinationRoot = path.join(userDir, '.history', 'events');
+    const legacyActive = path.join(userDir, 'events.jsonl');
+    const interimActive = path.join(destinationRoot, 'events.jsonl');
+    const listArchives = (dir) => {
+        try {
+            return fs.readdirSync(dir)
+                .map((file) => ({ file, match: file.match(/^events\.(\d+)\.jsonl\.gz$/) }))
+                .filter((entry) => entry.match !== null)
+                .map((entry) => ({ file: entry.file, number: Number(entry.match[1]) }))
+                .sort((a, b) => a.number - b.number);
+        }
+        catch {
+            return [];
+        }
+    };
+    const hasSourceFiles = fs.existsSync(legacyActive) || fs.existsSync(interimActive) ||
+        listArchives(userDir).length > 0 || listArchives(destinationRoot).length > 0;
+    if (!hasSourceFiles)
+        return 0;
+    try {
+        fs.mkdirSync(destinationRoot, { recursive: true, mode: DIR_MODE });
+        ensureLockTarget(legacyActive, '', DIR_MODE);
+        return withFileLock(legacyActive, () => {
+            ensureLockTarget(interimActive, '', DIR_MODE);
+            return withFileLock(interimActive, () => {
+                const sourceFamilies = [
+                    { dir: userDir, active: legacyActive, archives: listArchives(userDir) },
+                    { dir: destinationRoot, active: interimActive, archives: listArchives(destinationRoot) },
+                ];
+                let moved = 0;
+                const nextArchiveNumber = (dir) => {
+                    const numbers = fs.readdirSync(dir)
+                        .map((file) => file.match(/^events\.(\d+)\.jsonl\.gz$/))
+                        .filter((match) => match !== null)
+                        .map((match) => Number(match[1]));
+                    return (numbers.length ? Math.max(...numbers) : 0) + 1;
+                };
+                const withDestinationLock = (dayDir, fn) => {
+                    const destinationActive = path.join(dayDir, 'events.jsonl');
+                    fs.mkdirSync(dayDir, { recursive: true, mode: DIR_MODE });
+                    ensureLockTarget(destinationActive, '', DIR_MODE);
+                    return withFileLock(destinationActive, fn);
+                };
+                for (const family of sourceFamilies) {
+                    const activeBytes = fs.existsSync(family.active) ? fs.statSync(family.active).size : 0;
+                    if (activeBytes > 0) {
+                        const activeStat = fs.statSync(family.active);
+                        const dayDir = path.join(destinationRoot, localDateKey(activeStat.mtime));
+                        withDestinationLock(dayDir, () => {
+                            const archivePath = path.join(dayDir, `events.${nextArchiveNumber(dayDir)}.jsonl.gz`);
+                            fs.writeFileSync(archivePath, gzipSync(fs.readFileSync(family.active)), { mode: FILE_MODE });
+                            fs.utimesSync(archivePath, activeStat.atime, activeStat.mtime);
+                            fs.truncateSync(family.active, 0);
+                        });
+                        moved++;
+                    }
+                    for (const archive of family.archives) {
+                        const source = path.join(family.dir, archive.file);
+                        const dayDir = path.join(destinationRoot, localDateKey(fs.statSync(source).mtime));
+                        withDestinationLock(dayDir, () => {
+                            const destination = path.join(dayDir, `events.${nextArchiveNumber(dayDir)}.jsonl.gz`);
+                            fs.renameSync(source, destination);
+                        });
+                        moved++;
+                    }
+                    try {
+                        if (fs.existsSync(family.active) && fs.statSync(family.active).size === 0)
+                            fs.unlinkSync(family.active);
+                    }
+                    catch { /* an older process may have reopened it */ }
+                }
+                return moved;
+            });
+        });
+    }
+    catch {
+        // Audit logging must remain fail-soft. Files stay at the legacy path and a
+        // later process retries because this guard is process-local.
+        _legacyMigrationChecked = false;
+        return 0;
+    }
+}
 // ─── Redaction ────────────────────────────────────────────────────────────────
 /**
  * Replace a prompt string with length + short SHA so we can correlate runs
@@ -380,7 +506,8 @@ export function emit(event, payload = {}, overrides = {}) {
                     // May fail if not owner
                 }
             }
-            maybeGzipRotateLocked(logPath);
+            const rotated = maybeGzipRotateLocked(logPath);
+            maybePruneLocked(rotated);
         });
     }
     catch {
@@ -657,7 +784,7 @@ export function emitFriction(surface, failureId, payload = {}) {
 function maybeGzipRotateLocked(logPath) {
     const stat = fs.statSync(logPath);
     if (stat.size < GZIP_ROTATION_BYTES)
-        return;
+        return false;
     const raw = fs.readFileSync(logPath);
     const tmpArchive = path.join(eventsDir(), `.events.1.jsonl.gz.${process.pid}.tmp`);
     fs.writeFileSync(tmpArchive, gzipSync(raw), { mode: FILE_MODE });
@@ -672,6 +799,7 @@ function maybeGzipRotateLocked(logPath) {
         }
         fs.renameSync(tmpArchive, path.join(eventsDir(), 'events.1.jsonl.gz'));
         fs.truncateSync(logPath, 0);
+        return true;
     }
     catch (err) {
         try {
@@ -681,45 +809,179 @@ function maybeGzipRotateLocked(logPath) {
         throw err;
     }
 }
-// ─── Rotation ─────────────────────────────────────────────────────────────────
-/**
- * Remove log files older than the retention period.
- * Removes numbered gzip archives whose filesystem mtime exceeds retention.
- *
- * @param retentionDays - Number of days to keep (default 7, from DEFAULT_RETENTION_DAYS)
- * @returns Number of files removed
- */
-export function rotate(retentionDays = DEFAULT_RETENTION_DAYS) {
-    try {
-        if (!fs.existsSync(eventsDir()))
-            return 0;
-        const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1000;
-        const files = fs.readdirSync(eventsDir()).filter(f => /^events\.\d+\.jsonl\.gz$/.test(f));
-        let removed = 0;
-        for (const file of files) {
-            const filePath = path.join(eventsDir(), file);
-            if (fs.statSync(filePath).mtimeMs < cutoff) {
-                fs.unlinkSync(filePath);
-                removed++;
+function listEventLogFiles() {
+    const current = eventsPath();
+    const files = [];
+    const addFile = (filePath, gzip) => {
+        try {
+            const stat = fs.statSync(filePath);
+            files.push({
+                path: filePath,
+                gzip,
+                currentActive: filePath === current,
+                mtimeMs: stat.mtimeMs,
+                size: stat.size,
+            });
+        }
+        catch { /* file may rotate while an unlocked reader enumerates */ }
+    };
+    const addDirectory = (dir) => {
+        let names = [];
+        try {
+            names = fs.readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            if (name !== 'events.jsonl' && !/^events\.\d+\.jsonl\.gz$/.test(name))
+                continue;
+            addFile(path.join(dir, name), name.endsWith('.gz'));
+        }
+    };
+    if (_eventsPathOverride) {
+        if (path.basename(current) !== 'events.jsonl') {
+            addFile(current, false);
+            let names = [];
+            try {
+                names = fs.readdirSync(eventsDir());
+            }
+            catch {
+                return files;
+            }
+            for (const name of names) {
+                if (/^events\.\d+\.jsonl\.gz$/.test(name))
+                    addFile(path.join(eventsDir(), name), true);
             }
+            return files;
         }
-        return removed;
+        addDirectory(eventsDir());
+        return files;
+    }
+    let days = [];
+    try {
+        days = fs.readdirSync(eventsRoot()).filter((name) => /^\d{4}-\d{2}-\d{2}$/.test(name));
     }
     catch {
-        return 0;
+        return files;
     }
+    for (const day of days)
+        addDirectory(path.join(eventsRoot(), day));
+    return files;
 }
-/**
- * Lazy rotation - runs at most once per day per process.
- */
-let lastRotationCheck = 0;
-export function maybeRotate() {
-    const now = Date.now();
+function removeEmptyDayDirectories() {
+    if (_eventsPathOverride)
+        return;
+    let days = [];
+    try {
+        days = fs.readdirSync(eventsRoot()).filter((name) => /^\d{4}-\d{2}-\d{2}$/.test(name));
+    }
+    catch {
+        return;
+    }
+    for (const day of days) {
+        const dir = path.join(eventsRoot(), day);
+        try {
+            if (fs.readdirSync(dir).length === 0)
+                fs.rmdirSync(dir);
+        }
+        catch { /* best effort */ }
+    }
+}
+function finalizePastDayLogs() {
+    if (_eventsPathOverride)
+        return;
+    const currentDay = localDateKey();
+    for (const file of listEventLogFiles()) {
+        if (path.basename(file.path) !== 'events.jsonl')
+            continue;
+        if (path.basename(path.dirname(file.path)) === currentDay)
+            continue;
+        try {
+            withFileLock(file.path, () => {
+                const dir = path.dirname(file.path);
+                const numbers = fs.readdirSync(dir)
+                    .map((name) => name.match(/^events\.(\d+)\.jsonl\.gz$/))
+                    .filter((match) => match !== null)
+                    .map((match) => Number(match[1]));
+                const next = (numbers.length ? Math.max(...numbers) : 0) + 1;
+                const target = path.join(dir, `events.${next}.jsonl.gz`);
+                const sourceStat = fs.statSync(file.path);
+                fs.writeFileSync(target, gzipSync(fs.readFileSync(file.path)), { mode: FILE_MODE });
+                fs.utimesSync(target, sourceStat.atime, sourceStat.mtime);
+                fs.unlinkSync(file.path);
+            });
+        }
+        catch { /* retry on the next prune */ }
+    }
+}
+function pruneEventLogsLocked(retentionDays = DEFAULT_RETENTION_DAYS, maxStorageBytes = DEFAULT_MAX_STORAGE_BYTES) {
+    finalizePastDayLogs();
+    const result = { removedByAge: 0, removedBySize: 0, bytesReclaimed: 0 };
+    const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1000;
+    let files = listEventLogFiles();
+    for (const file of files) {
+        if (file.currentActive || file.mtimeMs >= cutoff)
+            continue;
+        try {
+            fs.unlinkSync(file.path);
+            result.removedByAge++;
+            result.bytesReclaimed += file.size;
+        }
+        catch { /* another process may already have removed it */ }
+    }
+    files = listEventLogFiles();
+    let totalBytes = files.reduce((sum, file) => sum + file.size, 0);
+    const oldestFirst = files
+        .filter((file) => !file.currentActive)
+        .sort((a, b) => a.mtimeMs - b.mtimeMs || a.path.localeCompare(b.path));
+    for (const file of oldestFirst) {
+        if (totalBytes <= maxStorageBytes)
+            break;
+        try {
+            fs.unlinkSync(file.path);
+            totalBytes -= file.size;
+            result.removedBySize++;
+            result.bytesReclaimed += file.size;
+        }
+        catch { /* another process may already have removed it */ }
+    }
+    removeEmptyDayDirectories();
+    return result;
+}
+/** Apply age retention and the total-size ceiling immediately. */
+export function rotate(retentionDays = DEFAULT_RETENTION_DAYS, maxStorageBytes = DEFAULT_MAX_STORAGE_BYTES) {
+    try {
+        ensureLogsDir();
+        const active = eventsPath();
+        ensureLockTarget(active, '', DIR_MODE);
+        return withFileLock(active, () => pruneEventLogsLocked(retentionDays, maxStorageBytes));
+    }
+    catch {
+        return { removedByAge: 0, removedBySize: 0, bytesReclaimed: 0 };
+    }
+}
+/** Prune daily across processes, and immediately after a size rotation. */
+function maybePruneLocked(force) {
+    const marker = path.join(eventsRoot(), PRUNE_MARKER);
     const oneDayMs = 24 * 60 * 60 * 1000;
-    if (now - lastRotationCheck > oneDayMs) {
-        lastRotationCheck = now;
-        rotate();
+    let due = force;
+    try {
+        due ||= Date.now() - fs.statSync(marker).mtimeMs > oneDayMs;
     }
+    catch {
+        due = true;
+    }
+    if (!due)
+        return;
+    const maxBytes = force
+        ? DEFAULT_MAX_STORAGE_BYTES - GZIP_ROTATION_BYTES
+        : DEFAULT_MAX_STORAGE_BYTES;
+    pruneEventLogsLocked(DEFAULT_RETENTION_DAYS, maxBytes);
+    try {
+        fs.writeFileSync(marker, '', { mode: FILE_MODE });
+    }
+    catch { /* retry next append */ }
 }
 // ─── Query ────────────────────────────────────────────────────────────────────
 /**
@@ -731,19 +993,9 @@ export function maybeRotate() {
 export function query(options) {
     const { startDate, endDate = new Date(), eventTypes, level, agent, sessionId, caller, command, module, bundle, limit } = options;
     const results = [];
-    if (!fs.existsSync(eventsDir()))
-        return results;
-    const files = [];
-    if (fs.existsSync(eventsPath()))
-        files.push({ path: eventsPath(), gzip: false });
-    const archives = fs.readdirSync(eventsDir())
-        .map((file) => ({ file, match: file.match(/^events\.(\d+)\.jsonl\.gz$/) }))
-        .filter((entry) => entry.match !== null)
-        .map((entry) => ({ file: entry.file, number: Number(entry.match[1]) }))
-        .sort((a, b) => a.number - b.number);
-    for (const archive of archives) {
-        files.push({ path: path.join(eventsDir(), archive.file), gzip: true });
-    }
+    eventsPath(); // Resolve AGENTS_EVENTS_PATH before deciding whether to migrate.
+    migrateLegacyEventLogs();
+    const files = listEventLogFiles().sort((a, b) => Number(b.currentActive) - Number(a.currentActive) || b.mtimeMs - a.mtimeMs || b.path.localeCompare(a.path));
     const startMs = startDate?.getTime();
     const endMs = endDate?.getTime();
     for (const file of files) {
@@ -849,16 +1101,9 @@ export function stats(options = {}) {
     let fileCount = 0;
     let totalBytes = 0;
     try {
-        if (fs.existsSync(eventsDir())) {
-            const files = fs.readdirSync(eventsDir()).filter(f => f === 'events.jsonl' || /^events\.\d+\.jsonl\.gz$/.test(f));
-            fileCount = files.length;
-            for (const f of files) {
-                try {
-                    totalBytes += fs.statSync(path.join(eventsDir(), f)).size;
-                }
-                catch { /* skip */ }
-            }
-        }
+        const files = listEventLogFiles();
+        fileCount = files.length;
+        totalBytes = files.reduce((sum, file) => sum + file.size, 0);
     }
     catch { /* skip */ }
     return {
@@ -876,9 +1121,11 @@ export function stats(options = {}) {
 export function getLogsPath() {
     return eventsPath();
 }
-export function _resetForTest(overrideEventsPath) {
+export function _resetForTest(overrideEventsPath, overrideUserAgentsDir) {
     _eventsPath = overrideEventsPath;
+    _eventsPathOverride = Boolean(overrideEventsPath);
+    _userAgentsDirOverride = overrideUserAgentsDir;
+    _legacyMigrationChecked = false;
     resetEventProvenanceForTest();
     _chmoddedPath = undefined;
-    lastRotationCheck = 0;
 }

package/dist/lib/exec.js

@@ -14,7 +14,7 @@ import { parseTimeout } from './routines.js';
 import { getBinaryPath, getVersionHomePath, isVersionInstalled, resolveVersion } from './versions.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
 import { isTierToken, resolveTier } from './model-tiers.js';
-import { maybeRotate, createTimer, redactPrompt, redactArgs } from './events.js';
+import { createTimer, redactPrompt, redactArgs } from './events.js';
 import { sanitizeProcessEnv } from './secrets/bundles.js';
 import { resolveActor, actorEnv } from './actor.js';
 import { getShimsDir, getHistoryDir, getUserAgentsDir } from './state.js';
@@ -1399,7 +1399,6 @@ async function spawnAgent(options) {
     const runId = launchId;
     options = { ...options, env: { ...options.env, AGENT_LAUNCH_ID: launchId } };
     const watcherState = await setupBudgetWatcher(options, cwd, runId);
-    maybeRotate();
     const timer = createTimer('agent.run', {
         agent: options.agent,
         version: options.version,

package/dist/lib/feed-broadcast.d.ts

@@ -48,8 +48,14 @@ export interface FeedBroadcastContext {
     class?: string;
     /** Block-only: cost-of-delay tag used by the urgency filter. */
     cost?: string;
-    /** Block-only: the literal `agents focus <id>` command that unblocks it. */
+    /** Block-only: the literal `agents focus <id>` command (for a `{focus}` sink). */
     focus?: string;
+    /** Block-only: the answer choices the operator can pick, in order. */
+    options?: string[];
+    /** Block-only: the fallback applied if nobody answers in time. */
+    safeDefault?: string;
+    /** Block-only: minutes before `safeDefault` applies. */
+    timeoutMinutes?: number;
 }
 /**
  * Map an open block onto the broadcast context, so a block reaches the same sinks
@@ -69,9 +75,14 @@ export declare function blockBroadcastContext(block: {
     host?: string;
     questions?: Array<{
         text?: string;
+        options?: Array<{
+            label?: string;
+        }>;
     }>;
     blockClass?: string;
     costOfDelay?: string;
+    safeDefault?: string;
+    timeoutMinutes?: number;
     ticket?: string;
     pr?: string;
 }, extras?: {
@@ -137,14 +148,17 @@ export declare function composeBroadcastFooter(ctx: FeedBroadcastContext): strin
  * Title in a few words
  *
  * Body of what happened or the ask.
+ * Options: publish / wait          (blocks with choices)
+ * Default in 15 min: wait          (blocks with a safe default)
  *
  * Sent from grok/a02da0e2 on mac-mini
- * agents focus a02da0e2          (blocks only)
- * https://…                      (optional attach URL)
+ * https://…                        (optional attach URL)
  * ```
  *
- * Title first (scannable subject). Blank line. Body. Footer provenance so a
- * fleet of agents is attributable without crowding the ask. Prefer `{message}`
+ * Title first (scannable subject). Blank line. Body. Then the phone-actionable
+ * choices + default (a block that has stopped for the human), then footer
+ * provenance. No `agents focus <id>` line: a CLI command is unusable from a phone,
+ * so the safe default is the fallback and the message carries it. Prefer `{message}`
  * over bare `{text}` in messaging sinks.
  */
 export declare function composeBroadcastMessage(ctx: FeedBroadcastContext): string;

package/dist/lib/feed-broadcast.js

@@ -62,6 +62,12 @@ export function parseFeedPostLevel(raw) {
 export function blockBroadcastContext(block, extras = {}) {
     const ask = block.questions?.[0]?.text?.trim() || 'agent is blocked';
     const links = [block.pr].filter((l) => !!l && /^https?:\/\//i.test(l));
+    // The answer choices + the safe default are what make the phone message
+    // actionable: the operator sees the options and what happens if they do not
+    // reply, instead of a `agents focus <id>` CLI command they cannot run from a phone.
+    const options = (block.questions?.[0]?.options ?? [])
+        .map((o) => o?.label?.trim())
+        .filter((l) => !!l);
     // Prefer explicit title/body from the feed post; fall back to the ask as body.
     const title = extras.title?.trim() || undefined;
     const text = extras.body?.trim() || ask;
@@ -78,8 +84,12 @@ export function blockBroadcastContext(block, extras = {}) {
         class: block.blockClass,
         cost: block.costOfDelay,
         // Short id: `agents focus` matches on a prefix, and a full uuid in a phone
-        // message is noise the operator has to skip past to reach the verb.
+        // message is noise. Kept for a `{focus}` sink; the human message no longer
+        // shows it (a CLI command is unusable from a phone).
         focus: `agents focus ${block.sessionId.slice(0, 8)}`,
+        ...(options.length ? { options } : {}),
+        ...(block.safeDefault ? { safeDefault: block.safeDefault } : {}),
+        ...(block.timeoutMinutes ? { timeoutMinutes: block.timeoutMinutes } : {}),
         ...(links.length ? { links } : {}),
     };
 }
@@ -179,14 +189,17 @@ export function composeBroadcastFooter(ctx) {
  * Title in a few words
  *
  * Body of what happened or the ask.
+ * Options: publish / wait          (blocks with choices)
+ * Default in 15 min: wait          (blocks with a safe default)
  *
  * Sent from grok/a02da0e2 on mac-mini
- * agents focus a02da0e2          (blocks only)
- * https://…                      (optional attach URL)
+ * https://…                        (optional attach URL)
  * ```
  *
- * Title first (scannable subject). Blank line. Body. Footer provenance so a
- * fleet of agents is attributable without crowding the ask. Prefer `{message}`
+ * Title first (scannable subject). Blank line. Body. Then the phone-actionable
+ * choices + default (a block that has stopped for the human), then footer
+ * provenance. No `agents focus <id>` line: a CLI command is unusable from a phone,
+ * so the safe default is the fallback and the message carries it. Prefer `{message}`
  * over bare `{text}` in messaging sinks.
  */
 export function composeBroadcastMessage(ctx) {
@@ -197,9 +210,21 @@ export function composeBroadcastMessage(ctx) {
     const mid = title && body && title !== body ? body : undefined;
     const footer = composeBroadcastFooter(ctx);
     const link = ctx.links?.find((l) => /^https?:\/\//i.test(l));
-    // Block focus and link trail after the "Sent from" footer so the human
-    // sentence stays at the top and the action/link are still one glance away.
-    const trail = [footer, ctx.focus, link].filter(Boolean);
+    // The action block: the one thing the operator can act on from a phone. Show the
+    // choices, then what happens if they do not answer. Deliberately NOT a CLI command
+    // (`agents focus <id>` is unusable from a phone) -- the safe default is the real
+    // fallback, so a block meant for a phone should always carry one.
+    const choices = ctx.options?.length
+        ? `Options: ${ctx.options.map((o) => scrubOutboundDashes(o)).join(' / ')}`
+        : undefined;
+    const fallback = ctx.safeDefault
+        ? (ctx.timeoutMinutes && ctx.timeoutMinutes > 0
+            ? `Default in ${ctx.timeoutMinutes} min: ${scrubOutboundDashes(ctx.safeDefault)}`
+            : `Default: ${scrubOutboundDashes(ctx.safeDefault)}`)
+        : undefined;
+    const action = [choices, fallback].filter(Boolean).join('\n') || undefined;
+    // Link trail after the "Sent from" footer so the human sentence stays at the top.
+    const trail = [footer, link].filter(Boolean);
     const parts = [];
     if (head)
         parts.push(head);
@@ -208,6 +233,12 @@ export function composeBroadcastMessage(ctx) {
         parts.push('');
         parts.push(mid);
     }
+    if (action) {
+        // The choices/default hug the ask under a blank line so they read as the reply.
+        if (parts.length)
+            parts.push('');
+        parts.push(action);
+    }
     if (trail.length) {
         // Blank line before the footer block (iPhone "Sent from my iPhone" spacing).
         if (parts.length)
@@ -233,6 +264,8 @@ function templateVars(ctx) {
         class: ctx.class,
         cost: ctx.cost,
         focus: ctx.focus,
+        options: ctx.options?.length ? ctx.options.join(' / ') : undefined,
+        default: ctx.safeDefault,
     };
 }
 /**

package/dist/lib/migrate.d.ts

@@ -133,5 +133,13 @@ export declare function migrateRoutineDeviceToDevices(routinesDir?: string): voi
  * real routines dir (and without racing the routine module's own tests).
  */
 export declare function migrateWatchdogSentinelToRoutine(sentinelPath?: string, ensure?: (enabled: boolean) => void): void;
+/**
+ * Rename cli/ → clis/ in each of the given `.agents/` directories.
+ *
+ * One-way, idempotent: no-op when src is absent. Throws when both
+ * `<dir>/cli` and `<dir>/clis` exist — the user must resolve the conflict
+ * manually before proceeding. Exported for unit-testing with temp dirs.
+ */
+export declare function migrateCliDirToClis(agentsDirs: string[]): void;
 /** Run all idempotent migrations. Safe to call multiple times. */
 export declare function runMigration(): Promise<void>;