@phnx-labs/agents-cli 1.22.11 → 1.22.12

package/dist/lib/migrate.js

@@ -998,7 +998,6 @@ function migrateRuntimeToHistory() {
     moveDirOnce(path.join(USER_DIR, '.backups'), path.join(HISTORY_DIR, 'backups'));
     moveDirOnce(path.join(USER_DIR, 'routines', 'runs'), path.join(HISTORY_DIR, 'runs'));
     moveDirOnce(path.join(USER_DIR, 'teams', 'agents'), path.join(HISTORY_DIR, 'teams', 'agents'));
-    migrateEventLogsToHistory();
     // Drop any empty leftover skeletons created mid-rename (e.g. `versions/<agent>/<v>/home/`
     // recreated by a concurrent process). The real data is already under .history/.
     rmEmptyDirTree(path.join(USER_DIR, 'versions'));
@@ -1014,66 +1013,6 @@ function migrateRuntimeToHistory() {
         catch { /* best-effort */ }
     }
 }
-/** Move the operational event stream out of the git-backed user-repo root. */
-function migrateEventLogsToHistory() {
-    const destination = path.join(HISTORY_DIR, 'events');
-    let files = [];
-    try {
-        files = fs.readdirSync(USER_DIR).filter((file) => file === 'events.jsonl' || /^events\.\d+\.jsonl\.gz$/.test(file));
-    }
-    catch {
-        return;
-    }
-    try {
-        fs.mkdirSync(destination, { recursive: true, mode: 0o700 });
-    }
-    catch {
-        return;
-    }
-    const active = files.find((file) => file === 'events.jsonl');
-    if (active) {
-        const src = path.join(USER_DIR, active);
-        const dest = path.join(destination, active);
-        if (!fs.existsSync(dest)) {
-            moveFileOnce(src, dest);
-        }
-        else {
-            try {
-                const lines = [fs.readFileSync(src, 'utf-8'), fs.readFileSync(dest, 'utf-8')]
-                    .flatMap((content) => content.split('\n').filter(Boolean))
-                    .map((line, index) => {
-                    try {
-                        const timestamp = Date.parse(JSON.parse(line).ts ?? '');
-                        return { line, index, timestamp: Number.isNaN(timestamp) ? Number.MAX_SAFE_INTEGER : timestamp };
-                    }
-                    catch {
-                        return { line, index, timestamp: Number.MAX_SAFE_INTEGER };
-                    }
-                })
-                    .sort((a, b) => a.timestamp - b.timestamp || a.index - b.index)
-                    .map(({ line }) => line);
-                atomicWriteFileSync(dest, `${lines.join('\n')}\n`, { mode: 0o600 });
-                fs.unlinkSync(src);
-            }
-            catch { /* preserve the source for a later retry */ }
-        }
-    }
-    const archives = files
-        .map((file) => ({ file, match: file.match(/^events\.(\d+)\.jsonl\.gz$/) }))
-        .filter((entry) => entry.match !== null)
-        .sort((a, b) => Number(a.match[1]) - Number(b.match[1]));
-    let nextArchive = fs.readdirSync(destination).reduce((max, file) => {
-        const match = file.match(/^events\.(\d+)\.jsonl\.gz$/);
-        return match ? Math.max(max, Number(match[1])) : max;
-    }, 0) + 1;
-    for (const archive of archives) {
-        const preferred = path.join(destination, archive.file);
-        const dest = fs.existsSync(preferred)
-            ? path.join(destination, `events.${nextArchive++}.jsonl.gz`)
-            : preferred;
-        moveFileOnce(path.join(USER_DIR, archive.file), dest);
-    }
-}
 /**
  * Restore plugins from the cache bucket back to the user-root.
  *
@@ -1694,7 +1633,7 @@ function containsOnlyDsStore(dir) {
 function warnSystemOrphans() {
     const SHIPPED_ALLOWLIST = new Set([
         // resource directories shipped by the npm package
-        'commands', 'hooks', 'skills', 'rules', 'mcp', 'cli', 'permissions', 'subagents', 'profiles', 'agents', 'routines',
+        'commands', 'hooks', 'skills', 'rules', 'mcp', 'clis', 'permissions', 'subagents', 'profiles', 'agents', 'routines',
         // top-level metadata files
         'agents.yaml', 'hooks.yaml', 'README.md', 'CHANGELOG.md',
         // git + repo metadata
@@ -2074,10 +2013,35 @@ export function migrateWatchdogSentinelToRoutine(sentinelPath = path.join(CACHE_
     catch { /* already gone */ }
     console.error('Migrated watchdog: legacy enable sentinel → watchdog routine (kept enabled)');
 }
+/**
+ * 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 function migrateCliDirToClis(agentsDirs) {
+    for (const agentsDir of agentsDirs) {
+        const src = path.join(agentsDir, 'cli');
+        const dest = path.join(agentsDir, 'clis');
+        if (!fs.existsSync(src))
+            continue;
+        if (fs.existsSync(dest)) {
+            throw new Error(`Migration conflict: both ${src} and ${dest} exist. ` +
+                `Remove or merge the old cli/ directory into clis/ manually.`);
+        }
+        fs.renameSync(src, dest);
+    }
+}
 /** Run all idempotent migrations. Safe to call multiple times. */
 export async function runMigration() {
     // MUST run first: every other migrator reads SYSTEM_DIR (the new path).
     foldLegacySystemRepo();
+    const cliMigrateDirs = [USER_DIR, SYSTEM_DIR];
+    const projectDotAgents = path.join(process.cwd(), '.agents');
+    if (fs.existsSync(projectDotAgents))
+        cliMigrateDirs.push(projectDotAgents);
+    migrateCliDirToClis(cliMigrateDirs);
     migrateAgentsYaml();
     deleteSystemPromptsJson();
     migrateSystemConfigJson();

package/dist/lib/resources.d.ts

@@ -5,7 +5,7 @@
 import type { AgentId } from './types.js';
 import { type SkillParseError } from './skills.js';
 /** Resource kind — matches the subdirectory name under each repo root. */
-export type ResourceKind = 'commands' | 'skills' | 'hooks' | 'rules' | 'mcp' | 'cli' | 'permissions' | 'subagents' | 'workflows' | 'profiles' | 'secrets';
+export type ResourceKind = 'commands' | 'skills' | 'hooks' | 'rules' | 'mcp' | 'clis' | 'permissions' | 'subagents' | 'workflows' | 'profiles' | 'secrets';
 /** A resource resolved with its origin. */
 export interface ResolvedResource {
     name: string;

package/dist/lib/runner.js

@@ -21,7 +21,7 @@ import { resolveJobPrompt, parseTimeout, writeRunMeta, listRuns, getJobRunsDir,
 import { getRunsDir } from './state.js';
 import { prepareJobHome, buildSpawnEnv, getJobHomePath } from './sandbox.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
-import { createTimer, maybeRotate, redactPrompt } from './events.js';
+import { createTimer, redactPrompt } from './events.js';
 import { normalizeMode, resolveHeadlessMode, buildExecEnv, detectRateLimit, detectAuthFailure, isAuthFailureFromLog, authFailureReason, } from './exec.js';
 import { resolveActor } from './actor.js';
 import { loadTask as loadHostTask } from './hosts/tasks.js';
@@ -691,7 +691,6 @@ export async function executeJob(config, deps) {
     if (config.command) {
         return executeCommandJobForeground(config);
     }
-    maybeRotate();
     const launch = await resolveRoutineLaunch(config);
     const primaryVersion = launch.chain[0]?.version ?? config.version;
     const timer = createTimer('agent.run', {

package/dist/lib/secrets/audit.js

@@ -4,7 +4,7 @@
  * This is the ONE write path for secret events. Every path that creates,
  * imports, exports, views, reads a VALUE from, or unlocks a bundle funnels its
  * audit through here, so the operational event stream — `agents events`, backed
- * by the append-only `~/.agents/.history/events/events.jsonl` audit log — carries a uniform,
+ * by the dated append-only `~/.agents/.history/events/` audit log — carries a uniform,
  * value-free provenance record: bundle, key NAMES, the resolving agent/harness
  * identity, operation, source, status. The ts / host / session / caller fields
  * are filled in by `emit()` itself. The secret VALUE is never part of the

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

@@ -124,7 +124,7 @@ export const COMMAND_LOADERS = {
     memory: [loadMemory],
     permissions: [loadPermissions],
     mcp: [loadMcp],
-    cli: [loadCli],
+    clis: [loadCli],
     subagents: [loadSubagents],
     plugins: [loadPlugins],
     workflows: [loadWorkflows],

package/dist/lib/state.d.ts

@@ -113,7 +113,7 @@ export declare function getUserSecretsDir(): string;
  * value-free usage telemetry (which bundle was created/imported/exported/viewed/
  * accessed/unlocked, when, by whom), never a secret value. It is a derived index
  * fed FROM the emitSecretAudit chokepoint alongside the append-only
- * ~/.agents/.history/events/events.jsonl audit log — the same way sessions.db indexes session
+ * ~/.agents/.history/events/YYYY-MM-DD audit log — the same way sessions.db indexes session
  * metadata off the real session flow — not a second write path.
  */
 export declare function getSecretsDbPath(): string;

package/dist/lib/state.js

@@ -372,7 +372,7 @@ export function getUserSecretsDir() { return USER_SECRETS_DIR; }
  * value-free usage telemetry (which bundle was created/imported/exported/viewed/
  * accessed/unlocked, when, by whom), never a secret value. It is a derived index
  * fed FROM the emitSecretAudit chokepoint alongside the append-only
- * ~/.agents/.history/events/events.jsonl audit log — the same way sessions.db indexes session
+ * ~/.agents/.history/events/YYYY-MM-DD audit log — the same way sessions.db indexes session
  * metadata off the real session flow — not a second write path.
  */
 export function getSecretsDbPath() {
@@ -794,6 +794,59 @@ function writeIfChanged(filePath, content) {
  * All callers funnel through writeMeta → here, so nothing else changes. Empty
  * `agents:` / `versions:` are not written (no empty committed files).
  */
+/**
+ * Every `Meta` key, classified as `central` (synced via agents.yaml) or `device`
+ * (routed to the per-machine device file by {@link writeMetaUnlocked}). The
+ * `Record<keyof Meta, …>` type makes this EXHAUSTIVE: adding a field to `Meta`
+ * without classifying it here is a compile error. That guarantee is what lets
+ * `serializeCentral` delete only keys THIS version models — a key a newer CLI
+ * version added (absent from this map) is preserved verbatim instead of being
+ * dropped and synced fleet-wide as data loss. This is the fix for the recurring
+ * agents.yaml key-loss (beta flags, `notify.owner`, and `feed:` all vanished
+ * this way when an older-versioned CLI on the fleet rewrote the file).
+ */
+const META_KEY_SCOPE = {
+    // Device-local — writeMetaUnlocked destructures these out; never in central.
+    agents: 'device',
+    isolatedAgents: 'device',
+    versions: 'device',
+    defaultBrowserProfile: 'device',
+    deviceConfig: 'device',
+    // Central — synced via agents.yaml.
+    run: 'central',
+    model: 'central',
+    watchdog: 'central',
+    lease: 'central',
+    secrets: 'central',
+    budget: 'central',
+    feed: 'central',
+    beta: 'central',
+    registries: 'central',
+    profiles: 'central',
+    source: 'central',
+    projectRoot: 'central',
+    extraRepos: 'central',
+    brands: 'central',
+    actors: 'central',
+    seededPresets: 'central',
+    hooks: 'central',
+    browser: 'central',
+    config: 'central',
+    hosts: 'central',
+    fleet: 'central',
+    share: 'central',
+    notify: 'central',
+    routines: 'central',
+};
+/**
+ * Every key this version models (central + device). serializeCentral deletes an
+ * on-disk key only when it is KNOWN and absent from the write's in-memory object:
+ * a central key the caller cleared, OR a device key that is legacy cruft in the
+ * synced file (device keys are routed to the per-machine file, so one lingering
+ * in central is stale and must be migrated out). A key NOT listed here — e.g. one
+ * a newer CLI version added — is preserved verbatim, never dropped + synced away.
+ */
+const KNOWN_META_KEYS = new Set(Object.keys(META_KEY_SCOPE));
 /**
  * Serialize the central (synced) meta to `agents.yaml` WITHOUT destroying the
  * hand-written comments in the committed file.
@@ -834,7 +887,12 @@ function serializeCentral(central) {
         }
     }
     for (const k of Object.keys(current)) {
-        if (!(k in central)) {
+        // Only delete a key THIS version knows about. A key not in KNOWN_META_KEYS
+        // (e.g. one a newer CLI version added) is preserved verbatim — deleting it
+        // here would drop it and sync the deletion fleet-wide (the agents.yaml
+        // config data-loss bug). A known device key lingering in the synced file is
+        // still removed — it belongs in the per-machine file, not here.
+        if (!(k in central) && KNOWN_META_KEYS.has(k)) {
             doc.delete(k);
             changed = true;
         }

package/dist/lib/watchdog/runner.d.ts

@@ -97,6 +97,11 @@ export interface WatchdogTickOptions {
         dryRun?: boolean;
         enter?: boolean;
     }) => Promise<InjectResult>;
+    /**
+     * Publish a declared block on the owner's feed. Default publishBlock() — tests
+     * inject a collector so no real feed dir is touched.
+     */
+    publishBlockFn?: (block: OpenBlock) => void;
     /** Override the canonical watchdog.log path (tests point at a tmp file). */
     logPath?: string;
     /**
@@ -195,6 +200,14 @@ export interface NudgeDecision {
     nudge: boolean;
     reason: string;
     text?: string;
+    /**
+     * Set to `true` when the brain (smart decider) explicitly concluded the session
+     * needs the human — as opposed to a cheap deterministic skip (session is done,
+     * not stalled, etc.). Only `true` when the brain escalation path ran and returned
+     * `nudge: false`. The watchdog uses this to gate the self-file reminder: a
+     * "session is done" skip does NOT trigger a reminder.
+     */
+    needsHuman?: boolean;
 }
 /**
  * The smart brain. Resolves a `watchdog` workflow for the session's cwd

package/dist/lib/watchdog/runner.js

@@ -44,7 +44,7 @@ import { withFileLock, atomicWriteFileSync, ensureLockTarget } from '../fs-atomi
 import { resolveAnswerRoute, isOpenQuestionBlock } from '../answer-router.js';
 import { enqueue, mailboxDir } from '../mailbox.js';
 import { mailboxIdForActiveSession } from '../mailbox-target.js';
-import { readBlock, blockIdForSession } from '../feed.js';
+import { readBlock, blockIdForSession, buildDeclaredBlock, publishBlock } from '../feed.js';
 import { summarizeWatchdogTail } from './watchdogTail.js';
 import { appendWatchdogEvents } from './log.js';
 import { buildRotateLaunchCommand, buildRotateReplayText, classifyTailForRotate, defaultRotateGate, defaultTuiLiveFor, exitSequenceFor, isInflightPhase, isWatchdogRotateEnabled, listInflightRotates, readRotateState, recordRotateSkip, shouldLogRotateSkip, writeRotateState, DEFAULT_ROTATE_READINESS_MS, DEFAULT_ROTATE_SKIP_COOLDOWN_MS, DEFAULT_ROTATE_FAILED_COOLDOWN_MS, } from './rotate.js';
@@ -353,6 +353,7 @@ export async function runWatchdogTick(opts = {}) {
     const smartDecider = opts.smartDecider ?? makeDefaultSmartDecider(opts.smartAgent ?? 'claude');
     const openBlockFor = opts.openBlockFor ?? defaultOpenBlockFor;
     const injectFn = opts.injectFn ?? injectIntoTerminal;
+    const publishBlockFn = opts.publishBlockFn ?? publishBlock;
     // Rotate seams (watchdog/rotate.ts). The config is read fresh per tick
     // (readMeta is mtime-cached), so a `watchdog.rotate` flip is honored on the
     // next pass. The default readiness probe (defaultTuiLiveFor) treats the
@@ -645,13 +646,21 @@ export async function runWatchdogTick(opts = {}) {
         // forces every stalled candidate through the brain.
         let decision;
         if (opts.smart) {
-            decision = await smartDecider(session, candidate);
+            const d = await smartDecider(session, candidate);
+            // Mark needsHuman when the brain explicitly concluded "leave for human".
+            decision = d.nudge ? d : { ...d, needsHuman: true };
         }
         else {
             const det = deterministicDecision(session, candidate);
-            decision = det.kind === 'escalate'
-                ? await smartDecider(session, candidate)
-                : { nudge: det.kind === 'nudge', reason: det.reason };
+            if (det.kind === 'escalate') {
+                const d = await smartDecider(session, candidate);
+                // Mark needsHuman when the brain escalation path concluded "leave for human".
+                decision = d.nudge ? d : { ...d, needsHuman: true };
+            }
+            else {
+                // Cheap deterministic path — completion or clear stall. Never "needs human".
+                decision = { nudge: det.kind === 'nudge', reason: det.reason };
+            }
         }
         const chosenText = decision.text ?? nudgeText;
         // Log the decision for the Factory watchdog card.
@@ -670,6 +679,53 @@ export async function runWatchdogTick(opts = {}) {
             lastAssistantMessage: summary.lastAssistantMessage,
         });
         if (!decision.nudge) {
+            // Brain explicitly concluded "leave for human" (needsHuman === true). Inject a
+            // self-file reminder into the agent's terminal so it knows to post a feed block.
+            // Cheap deterministic skips (session done, no stall) are NOT reminder-worthy —
+            // guard on needsHuman so a finished session is never poked.
+            // Gated by the same cooldown as a nudge to prevent re-firing every 2-minute tick.
+            if (decision.needsHuman) {
+                const lastNudgeMs = ledger[session.sessionId ?? ''] ?? 0;
+                const cooldownMs = thresholds.cooldownMs;
+                const withinCooldown = nowMs - lastNudgeMs < cooldownMs;
+                if (opts.nudge && session.sessionId && !withinCooldown) {
+                    const existingBlock = openBlockFor(session);
+                    if (existingBlock === null) {
+                        // Determine addressability without planning the full nudge (no text needed).
+                        const resolution = resolveInjectTargetForSession(session, { allowGhosttyFocus: opts.allowGhosttyFocus });
+                        if (resolution.addressable) {
+                            // Addressable → inject a reminder asking the agent to self-file a feed block.
+                            const reminderText = 'You appear stuck. If you genuinely need Muqsit, file it: ' +
+                                'agents feed post "<one-line ask>" --blocked --default "<safe default>". ' +
+                                'Otherwise keep going.';
+                            try {
+                                await injectFn(resolution.target, reminderText, { dryRun: opts.injectDryRun });
+                            }
+                            catch {
+                                // Swallow inject errors — reminder is best-effort; flag set below.
+                            }
+                            ledgerUpdates[session.sessionId] = nowMs;
+                        }
+                        else {
+                            // Un-addressable → we can't reach the terminal to remind it, so the ONLY
+                            // way to reach Muqsit is to file a declared block on the agent's behalf.
+                            // This is the most important case: the session genuinely needs the human
+                            // AND the watchdog can't even nudge it. Never let it silently vanish.
+                            const mailboxId = mailboxIdForActiveSession(session) ?? session.sessionId;
+                            const machineHost = session.provenance?.host ?? 'unknown';
+                            const runtime = session.kind;
+                            try {
+                                const declaredBlock = buildDeclaredBlock({ sessionId: session.sessionId, mailboxId, host: machineHost, runtime, cwd: session.cwd }, { text: `Session genuinely needs Muqsit and is un-addressable — ${decision.reason}. Needs attention.` });
+                                publishBlockFn(declaredBlock);
+                                ledgerUpdates[session.sessionId] = nowMs;
+                            }
+                            catch {
+                                // publishBlock failure is non-fatal — best-effort owner page.
+                            }
+                        }
+                    }
+                }
+            }
             outcomes.push({ ...base, decision: 'skip', reason: decision.reason });
             continue;
         }
@@ -682,6 +738,12 @@ export async function runWatchdogTick(opts = {}) {
         const addressable = plan.via === 'inject' ? true : undefined;
         if (plan.via === 'refuse') {
             // No addressable rail and not headless-resumable — flag, NEVER guess.
+            // This branch is reached ONLY for a nudge-worthy (decision.nudge === true)
+            // drive-forward poke, which is NEVER needsHuman (needsHuman is set only when
+            // decision.nudge === false). So we do NOT page the owner here — a short "just
+            // needs a poke" stall must not text Muqsit's phone. Owner-paging for an
+            // un-addressable session happens only on the confirmed needsHuman skip path
+            // above. Here we only flag it for the tray.
             flags[session.sessionId] = { reason: plan.reason, host: session.host, atMs: nowMs };
             outcomes.push({
                 ...base, decision: 'skip', addressable: false,
@@ -690,7 +752,14 @@ export async function runWatchdogTick(opts = {}) {
             });
             continue;
         }
-        // handsoff = detect + flag, but never deliver.
+        // handsoff = detect + flag, but never deliver via inject/mailbox.
+        // This branch is reached ONLY for a nudge-worthy (decision.nudge === true)
+        // drive-forward poke, which is NEVER needsHuman. A hands-off policy means "don't
+        // nudge it forward" — it must NOT translate into paging Muqsit for a poke. So we
+        // only flag it for the tray, no owner page. A genuinely needs-human session (even
+        // under hands-off) is paged by the confirmed-needsHuman skip path above, which
+        // does not consult policy — hands-off silences the forward nudge, not the
+        // "it's actually stuck" signal.
         if (policy === 'handsoff') {
             flags[session.sessionId] = {
                 reason: `handsoff: would nudge via ${viaLabel(plan)} but policy is hands-off`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.11",
+  "version": "1.22.12",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",