@phnx-labs/agents-cli 1.22.10 → 1.22.12

package/dist/lib/migrate.js

@@ -1633,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
@@ -2013,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/project-probe.d.ts

@@ -1,5 +1,5 @@
 /**
- * Project workspace probing — the drift signal behind `projects status --fleet`.
+ * Project workspace probing — the drift signal behind `projects status`.
  *
  * Projects are natively multi-device: the same definition (home-relative paths)
  * re-roots on every fleet machine, and the question is whether the project's

package/dist/lib/project-probe.js

@@ -1,5 +1,5 @@
 /**
- * Project workspace probing — the drift signal behind `projects status --fleet`.
+ * Project workspace probing — the drift signal behind `projects status`.
  *
  * Projects are natively multi-device: the same definition (home-relative paths)
  * re-roots on every fleet machine, and the question is whether the project's

package/dist/lib/projects.d.ts

@@ -36,7 +36,7 @@ export interface ProjectRepo {
     /**
      * Optional home-relative local checkout of this repo. The def's `root` only
      * knows the primary repo on disk; `path` opts an additional repo into
-     * workspace probing (`projects status --fleet`).
+     * workspace probing (`projects status`).
      */
     path?: string;
 }

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/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/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/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/types.d.ts

@@ -79,7 +79,7 @@ export interface BudgetConfig {
     require_confirm_over?: number;
 }
 /** Preview features that users can opt into via `agents beta`. */
-export type BetaFeatureName = 'factory' | 'projects';
+export type BetaFeatureName = 'factory';
 /** Subset of chalk color names used for agent-specific terminal output. */
 export type ChalkColor = 'magenta' | 'green' | 'blue' | 'cyan' | 'yellowBright' | 'redBright' | 'whiteBright' | 'blueBright' | 'greenBright' | 'magentaBright' | 'cyanBright';
 /** Static configuration for a single agent -- paths, capabilities, and format conventions. */

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.10",
+  "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",