@phnx-labs/agents-cli 1.20.72 → 1.20.73

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

@@ -0,0 +1,32 @@
+import type { OpenBlock, FeedAskStats } from './feed.js';
+import type { Classification } from './ask-classifier.js';
+import type { ActiveSession } from './session/active.js';
+import type { SessionMeta } from './session/types.js';
+export interface FeedSessionSignal {
+    sessionId?: string;
+    mailboxId?: string;
+    kind?: string;
+    host?: string;
+    context?: ActiveSession['context'];
+    runtime?: string;
+    pid?: number;
+    cwd?: string;
+    startedAtMs?: number;
+    status?: ActiveSession['status'];
+    tokPerSec?: number;
+    costUsd?: number;
+    durationMs?: number;
+    cloudProvider?: string;
+    cloudTaskId?: string;
+}
+export interface RankedFeedBlock extends OpenBlock {
+    delayRank: NonNullable<OpenBlock['delayRank']>;
+}
+export declare function buildSessionSignals(active: ActiveSession[], metas?: SessionMeta[]): FeedSessionSignal[];
+export declare function decisionIrreducibility(c: Classification): number;
+export declare function burnUsdPerHour(signal: FeedSessionSignal | undefined, block: OpenBlock): number;
+export declare function rankFeedBlocks(blocks: OpenBlock[], signals?: FeedSessionSignal[], now?: Date): RankedFeedBlock[];
+export declare function recentAskCount(stats: FeedAskStats, now?: Date): number;
+export declare function needyControlCards(stats: FeedAskStats[], signals?: FeedSessionSignal[], now?: Date, threshold?: number): OpenBlock[];
+export declare function runawayControlCards(signals: FeedSessionSignal[], now?: Date): OpenBlock[];
+export declare function synthesizeControlCards(signals: FeedSessionSignal[], stats: FeedAskStats[], now?: Date): OpenBlock[];

package/dist/lib/feed-ranking.js

@@ -0,0 +1,224 @@
+import { classifyBlock } from './ask-classifier.js';
+import { outcomeForBlock } from './feed-outcome.js';
+const MINUTES_PER_HOUR = 60;
+const NEEDY_ASKS_PER_HOUR = 6;
+const RUNAWAY_TOK_PER_SEC = 250;
+const RUNAWAY_BURN_USD_PER_HOUR = 25;
+const RELAUNCH_LOOP_COUNT = 3;
+const RELAUNCH_LOOP_WINDOW_MS = 10 * 60_000;
+function finiteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function signalKey(signal) {
+    return [signal.mailboxId, signal.sessionId, signal.cloudTaskId].filter((v) => !!v);
+}
+export function buildSessionSignals(active, metas = []) {
+    const metaById = new Map(metas.map((m) => [m.id, m]));
+    return active.map((s) => {
+        const sessionId = s.sessionId;
+        const meta = sessionId ? metaById.get(sessionId) : undefined;
+        return {
+            sessionId,
+            mailboxId: s.agentId ?? s.sessionId ?? s.cloudTaskId,
+            kind: s.kind,
+            host: s.machine ?? s.provenance?.host ?? s.host,
+            context: s.context,
+            runtime: s.context,
+            pid: s.pid,
+            cwd: s.cwd,
+            startedAtMs: s.startedAtMs,
+            status: s.status,
+            tokPerSec: s.tokPerSec,
+            costUsd: meta?.costUsd,
+            durationMs: meta?.durationMs,
+            cloudProvider: s.cloudProvider,
+            cloudTaskId: s.cloudTaskId,
+        };
+    });
+}
+function indexSignals(signals) {
+    const out = new Map();
+    for (const signal of signals) {
+        for (const key of signalKey(signal)) {
+            if (!out.has(key))
+                out.set(key, signal);
+        }
+    }
+    return out;
+}
+function signalForBlock(block, signals) {
+    return signals.get(block.mailboxId) ?? signals.get(block.sessionId);
+}
+export function decisionIrreducibility(c) {
+    switch (c.class) {
+        case 'decision': return 1;
+        case 'approval': return 0.8;
+        case 'clarification': return 0.6;
+        case 'stall':
+        case 'fyi':
+            return 0;
+    }
+}
+function fallbackBurnRate(block) {
+    switch (block.costOfDelay) {
+        case 'high': return 10;
+        case 'medium': return 3;
+        case 'low': return 1;
+        default: return 1;
+    }
+}
+export function burnUsdPerHour(signal, block) {
+    const cost = finiteNumber(signal?.costUsd);
+    const duration = finiteNumber(signal?.durationMs);
+    if (cost !== undefined && duration !== undefined && duration > 0) {
+        return cost / (duration / 3_600_000);
+    }
+    const existing = finiteNumber(block.delayRank?.burnUsdPerHour);
+    if (existing !== undefined)
+        return existing;
+    return fallbackBurnRate(block);
+}
+function idleMinutes(block, nowMs) {
+    const ts = Date.parse(block.ts);
+    if (!Number.isFinite(ts))
+        return 0;
+    return Math.max(0, (nowMs - ts) / 60_000);
+}
+function blastRadii(blocks) {
+    const counts = new Map();
+    for (const block of blocks) {
+        const key = outcomeForBlock(block).key;
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    const out = new Map();
+    for (const block of blocks) {
+        out.set(block.blockId, Math.max(1, finiteNumber(block.downstreamAgents) ?? counts.get(outcomeForBlock(block).key) ?? 1));
+    }
+    return out;
+}
+export function rankFeedBlocks(blocks, signals = [], now = new Date()) {
+    const bySignal = indexSignals(signals);
+    const radii = blastRadii(blocks);
+    const nowMs = now.getTime();
+    return blocks
+        .map((block) => {
+        const c = classifyBlock(block);
+        const idle = idleMinutes(block, nowMs);
+        const blastRadius = radii.get(block.blockId) ?? 1;
+        const burn = burnUsdPerHour(signalForBlock(block, bySignal), block);
+        const irreducible = finiteNumber(block.delayRank?.decisionIrreducibility) ?? decisionIrreducibility(c);
+        const score = idle * blastRadius * burn * irreducible;
+        return {
+            ...block,
+            delayRank: {
+                score,
+                idleMinutes: idle,
+                blastRadius,
+                burnUsdPerHour: burn,
+                decisionIrreducibility: irreducible,
+            },
+        };
+    })
+        .sort((a, b) => {
+        if (b.delayRank.score !== a.delayRank.score)
+            return b.delayRank.score - a.delayRank.score;
+        return Date.parse(a.ts) - Date.parse(b.ts);
+    });
+}
+export function recentAskCount(stats, now = new Date()) {
+    const cutoff = now.getTime() - 60 * 60_000;
+    return stats.recentAskTimestamps.filter((ts) => {
+        const parsed = Date.parse(ts);
+        return Number.isFinite(parsed) && parsed >= cutoff;
+    }).length;
+}
+export function needyControlCards(stats, signals = [], now = new Date(), threshold = NEEDY_ASKS_PER_HOUR) {
+    const bySignal = indexSignals(signals);
+    const cards = [];
+    for (const row of stats) {
+        const count = recentAskCount(row, now);
+        if (count < threshold)
+            continue;
+        const signal = bySignal.get(row.mailboxId) ?? bySignal.get(row.sessionId);
+        cards.push({
+            blockId: `control-needy-${row.sessionId.replace(/[^A-Za-z0-9._-]/g, '-')}`,
+            sessionId: row.sessionId,
+            mailboxId: row.mailboxId,
+            host: signal?.host ?? 'local',
+            runtime: signal?.runtime ?? signal?.context ?? 'unknown',
+            ts: row.lastAskAt,
+            kind: 'control',
+            questions: [{
+                    header: 'Needy agent',
+                    text: `${row.mailboxId} asked ${count} times in the last hour. Inspect the session; this is likely a loop bug, not ${count} separate decisions.`,
+                }],
+            needy: {
+                askCountLastHour: count,
+                threshold,
+                totalAskCount: row.totalAskCount,
+            },
+        });
+    }
+    return cards;
+}
+function relaunchLoopCount(signal, signals, nowMs) {
+    if (!signal.cwd || !signal.kind || !signal.startedAtMs)
+        return 0;
+    return signals.filter((candidate) => candidate.kind === signal.kind &&
+        candidate.cwd === signal.cwd &&
+        candidate.startedAtMs !== undefined &&
+        nowMs - candidate.startedAtMs <= RELAUNCH_LOOP_WINDOW_MS).length;
+}
+export function runawayControlCards(signals, now = new Date()) {
+    const nowMs = now.getTime();
+    const cards = [];
+    const seen = new Set();
+    for (const signal of signals) {
+        const tokPerSec = finiteNumber(signal.tokPerSec);
+        const cost = finiteNumber(signal.costUsd);
+        const duration = finiteNumber(signal.durationMs);
+        const burn = cost !== undefined && duration !== undefined && duration > 0
+            ? cost / (duration / 3_600_000)
+            : undefined;
+        const loopCount = relaunchLoopCount(signal, signals, nowMs);
+        const reasons = [];
+        if (tokPerSec !== undefined && tokPerSec >= RUNAWAY_TOK_PER_SEC)
+            reasons.push(`${Math.round(tokPerSec)} tok/s`);
+        if (burn !== undefined && burn >= RUNAWAY_BURN_USD_PER_HOUR)
+            reasons.push(`$${burn.toFixed(2)}/hr`);
+        if (loopCount >= RELAUNCH_LOOP_COUNT)
+            reasons.push(`${loopCount} launches in 10 minutes`);
+        if (reasons.length === 0)
+            continue;
+        const id = signal.mailboxId ?? signal.sessionId ?? signal.cloudTaskId;
+        if (!id || seen.has(id))
+            continue;
+        seen.add(id);
+        cards.push({
+            blockId: `control-runaway-${id.replace(/[^A-Za-z0-9._-]/g, '-')}`,
+            sessionId: signal.sessionId ?? id,
+            mailboxId: signal.mailboxId ?? id,
+            host: signal.host ?? 'local',
+            runtime: signal.runtime ?? signal.context ?? 'unknown',
+            ts: new Date(signal.startedAtMs ?? nowMs).toISOString(),
+            kind: 'control',
+            questions: [{
+                    header: 'Runaway agent',
+                    text: `${id} is burning abnormally (${reasons.join(', ')}). Pause or kill it before it burns more parallel capacity.`,
+                }],
+            runaway: {
+                reason: reasons.join(', '),
+                tokPerSec,
+                burnUsdPerHour: burn,
+                relaunchesPerTenMinutes: loopCount || undefined,
+            },
+        });
+    }
+    return cards;
+}
+export function synthesizeControlCards(signals, stats, now = new Date()) {
+    return [
+        ...runawayControlCards(signals, now),
+        ...needyControlCards(stats, signals, now),
+    ];
+}

package/dist/lib/feed.d.ts

@@ -38,7 +38,7 @@ export interface OpenBlock {
     runtime: string;
     ts: string;
     questions: BlockQuestion[];
-    kind?: 'question' | 'notification';
+    kind?: 'question' | 'notification' | 'control';
     notificationType?: string;
     ticket?: string;
     pr?: string;
@@ -58,6 +58,29 @@ export interface OpenBlock {
     safeDefault?: string;
     /** Cost-of-delay for notification routing: low/medium/high. */
     costOfDelay?: 'low' | 'medium' | 'high';
+    /** Number of agents downstream of this blocked agent, when known. */
+    downstreamAgents?: number;
+    /** Computed cost-of-delay rank metadata, stamped by `agents feed`. */
+    delayRank?: {
+        score: number;
+        idleMinutes: number;
+        blastRadius: number;
+        burnUsdPerHour: number;
+        decisionIrreducibility: number;
+    };
+    /** Token/cost runaway signal for synthetic feed control cards. */
+    runaway?: {
+        reason: string;
+        tokPerSec?: number;
+        burnUsdPerHour?: number;
+        relaunchesPerTenMinutes?: number;
+    };
+    /** Chronic-ask signal for synthetic feed control cards. */
+    needy?: {
+        askCountLastHour: number;
+        threshold: number;
+        totalAskCount: number;
+    };
     /** Set once the block has been answered; see `recordAnswer`. */
     answer?: AnswerRecord;
     /** Per-message delivery receipts for answers to this block. */
@@ -71,6 +94,14 @@ export interface OpenBlock {
     /** ISO-8601 timestamp when a decision block was hard-parked. */
     parkedAt?: string;
 }
+export interface FeedAskStats {
+    sessionId: string;
+    mailboxId: string;
+    firstAskAt: string;
+    lastAskAt: string;
+    totalAskCount: number;
+    recentAskTimestamps: string[];
+}
 /**
  * Stable block id for a session. One block per session -- a new question
  * replaces the previous one (the agent can only ask one question at a time).
@@ -132,6 +163,8 @@ export declare function clearBlockLifecycle(blockId: string, root?: string): voi
 export declare function publishBlock(block: OpenBlock, root?: string): void;
 /** Read all block records. Returns them sorted by stable block filename. */
 export declare function listBlocks(root?: string): OpenBlock[];
+/** Read per-session ask history written by the feed publish hook. */
+export declare function listAskStats(root?: string): FeedAskStats[];
 /** Remove a block record and its lifecycle sidecars. Returns true if the file was deleted. */
 export declare function removeBlock(blockId: string, root?: string): boolean;
 /**
@@ -139,7 +172,7 @@ export declare function removeBlock(blockId: string, root?: string): boolean;
  * Embedded so it ships with the compiled CLI and can be installed to the
  * CLI-writable user hooks dir without a separate file in the npm tarball.
  */
-export declare const FEED_PUBLISH_HOOK_SCRIPT = "#!/usr/bin/env python3\n\"\"\"Publish and clear open-block records for `agents feed`.\n\nThe manifest invokes this script for top-level AskUserQuestion calls, waiting\nnotifications, question answers, and session lifecycle events. One atomic file\nper session means a new block replaces the previous block. Answer/resume/stop\nevents remove it so `agents feed` only lists decisions that are still open.\n\nSub-agent gate: when the PreToolUse payload carries `agent_type`, this is a\nTask/Agent subagent -- skip. Only the top-level agent publishes. Verified on\nClaude Code 2.1.170 (2026-07).\n\nFail-open: ANY error is swallowed so a feed hiccup never blocks a tool call.\n\"\"\"\nimport os\nimport sys\nimport json\nimport re\nimport socket\nimport tempfile\nfrom datetime import datetime, timezone\n\nWAITING_NOTIFICATION_TYPES = {\n    \"permission_prompt\",\n    \"idle_prompt\",\n    \"elicitation_dialog\",\n}\nCLEAR_EVENTS = {\n    \"PostToolUse\",\n    \"Stop\",\n    \"SessionEnd\",\n}\n\n\ndef read_json(path):\n    try:\n        with open(path) as f:\n            return json.load(f)\n    except Exception:\n        return None\n\n\ndef write_json(path, value):\n    dir_name = os.path.dirname(path)\n    os.makedirs(dir_name, exist_ok=True)\n    fd, tmp = tempfile.mkstemp(dir=dir_name, suffix=\".tmp\")\n    try:\n        with os.fdopen(fd, \"w\") as f:\n            json.dump(value, f, indent=2)\n        os.replace(tmp, path)\n    except Exception:\n        try:\n            os.unlink(tmp)\n        except Exception:\n            pass\n\n\ndef main():\n    raw = sys.stdin.read()\n    try:\n        payload = json.loads(raw) if raw.strip() else {}\n    except Exception:\n        return\n\n    # Sub-agent gate.\n    if payload.get(\"agent_type\"):\n        return\n\n    session_id = payload.get(\"session_id\", \"\")\n    if not session_id:\n        return\n\n    safe_session_id = re.sub(r\"[^A-Za-z0-9._-]\", \"-\", session_id)\n    block_id = f\"block-{safe_session_id}\"\n    home = os.environ.get(\"HOME\") or os.path.expanduser(\"~\")\n    feed_dir = os.path.join(home, \".agents\", \".history\", \"feed\")\n    answered_dir = os.path.join(feed_dir, \"answered\")\n    target = os.path.join(feed_dir, f\"{block_id}.json\")\n    hook_event = payload.get(\"hook_event_name\", \"PreToolUse\")\n\n    if hook_event in CLEAR_EVENTS:\n        try:\n            os.unlink(target)\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        # Also clear the answered marker so a future question for this session\n        # is not permanently locked.\n        try:\n            os.unlink(os.path.join(answered_dir, f\"{block_id}.json\"))\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        return\n\n    # Terminal answers (human typed in the TUI) record an answered marker and\n    # remove the block file so the feed stops showing it within one poll cycle.\n    # The marker stays behind so a concurrent surface cannot double-answer.\n    if hook_event == \"UserPromptSubmit\":\n        os.makedirs(answered_dir, exist_ok=True)\n        marker = os.path.join(answered_dir, f\"{block_id}.json\")\n        try:\n            fd = os.open(marker, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644)\n            record = {\n                \"answeredAt\": datetime.now(timezone.utc).isoformat(),\n                \"answeredFrom\": \"terminal\",\n            }\n            with os.fdopen(fd, \"w\") as f:\n                json.dump(record, f, indent=2)\n        except FileExistsError:\n            pass\n        except Exception:\n            pass\n        # Remove the visible block so the feed drops the answered question.\n        try:\n            os.unlink(target)\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        return\n\n    notification_type = None\n    if hook_event == \"Notification\":\n        notification_type = payload.get(\"notification_type\", \"\")\n        if notification_type not in WAITING_NOTIFICATION_TYPES:\n            return\n        # Claude emits a generic permission notification after presenting an\n        # AskUserQuestion. Keep the structured questions and options already\n        # published for this session instead of replacing them with that less\n        # useful notification text.\n        try:\n            with open(target) as existing_file:\n                existing = json.load(existing_file)\n            if existing.get(\"kind\") == \"question\":\n                return\n        except Exception:\n            pass\n        message = payload.get(\"message\", \"\")\n        if not message:\n            return\n        normalized_questions = [{\n            \"text\": message,\n            \"header\": payload.get(\"title\") or notification_type.replace(\"_\", \" \").title(),\n            \"multiSelect\": False,\n        }]\n        kind = \"notification\"\n    else:\n        tool_input = payload.get(\"tool_input\", {})\n        questions = tool_input.get(\"questions\", [])\n        if not questions:\n            return\n        normalized_questions = []\n        for q in questions:\n            if not isinstance(q, dict):\n                continue\n            question = {\n                \"text\": q.get(\"question\", q.get(\"header\", \"\")),\n                \"header\": q.get(\"header\"),\n                \"multiSelect\": q.get(\"multiSelect\", False),\n            }\n            raw_opts = q.get(\"options\", [])\n            if raw_opts:\n                question[\"options\"] = [\n                    {\"label\": o.get(\"label\", \"\"), \"description\": o.get(\"description\")}\n                    for o in raw_opts\n                    if isinstance(o, dict)\n                ]\n            normalized_questions.append(question)\n        if not normalized_questions:\n            return\n        kind = \"question\"\n\n    # Identity from env (set by agents-cli at spawn).\n    mailbox_id = os.path.basename(\n        os.environ.get(\"AGENTS_MAILBOX_DIR\", \"\").rstrip(\"/\")\n    ) or session_id\n\n    hostname = os.environ.get(\"AGENTS_SYNC_MACHINE_ID\") or socket.gethostname()\n    host = hostname.split(\".\")[0].strip().lower()\n    host = re.sub(r\"[^a-z0-9_-]\", \"-\", host) or \"unknown\"\n\n    runtime = os.environ.get(\"AGENTS_RUNTIME\", \"headless\")\n\n    block = {\n        \"blockId\": block_id,\n        \"sessionId\": session_id,\n        \"mailboxId\": mailbox_id,\n        \"host\": host,\n        \"runtime\": runtime,\n        \"ts\": datetime.now(timezone.utc).isoformat(),\n        \"questions\": normalized_questions,\n        \"kind\": kind,\n    }\n    if notification_type:\n        block[\"notificationType\"] = notification_type\n\n    # Optional multi-operator control metadata passed by the agent in the\n    # AskUserQuestion tool_input. Defaults keep the existing behavior.\n    controls = payload.get(\"tool_input\", {}) if hook_event != \"Notification\" else {}\n    block_class = controls.get(\"blockClass\") if isinstance(controls, dict) else None\n    if block_class in (\"approval\", \"decision\"):\n        block[\"blockClass\"] = block_class\n    consequence = controls.get(\"consequence\") if isinstance(controls, dict) else None\n    if consequence:\n        block[\"consequence\"] = consequence\n    allowed = controls.get(\"allowedOperators\") if isinstance(controls, dict) else None\n    if isinstance(allowed, list):\n        block[\"allowedOperators\"] = [str(a) for a in allowed]\n    timeout = controls.get(\"timeoutMinutes\") if isinstance(controls, dict) else None\n    if isinstance(timeout, (int, float)) and timeout > 0:\n        block[\"timeoutMinutes\"] = int(timeout)\n    safe_default = controls.get(\"safeDefault\") if isinstance(controls, dict) else None\n    if isinstance(safe_default, str):\n        block[\"safeDefault\"] = safe_default\n    cost = controls.get(\"costOfDelay\") if isinstance(controls, dict) else None\n    if cost in (\"low\", \"medium\", \"high\"):\n        block[\"costOfDelay\"] = cost\n\n    # Publishing a new question clears any stale answered marker from the\n    # previous question in this session.\n    try:\n        os.unlink(os.path.join(answered_dir, f\"{block_id}.json\"))\n    except FileNotFoundError:\n        pass\n    except Exception:\n        pass\n\n    # Python's expanduser() ignores HOME on Windows, while agents-cli honors a\n    # HOME override on every platform. Use the same anchor so hooks and the CLI\n    # always read/write one feed store (including temp-home and sandbox runs).\n    os.makedirs(feed_dir, exist_ok=True)\n\n    fd, tmp = tempfile.mkstemp(dir=feed_dir, suffix=\".tmp\")\n    try:\n        with os.fdopen(fd, \"w\") as f:\n            json.dump(block, f, indent=2)\n        os.replace(tmp, target)\n    except Exception:\n        try:\n            os.unlink(tmp)\n        except Exception:\n            pass\n\n\nif __name__ == \"__main__\":\n    try:\n        main()\n    except Exception:\n        pass  # fail open\n";
+export declare const FEED_PUBLISH_HOOK_SCRIPT = "#!/usr/bin/env python3\n\"\"\"Publish and clear open-block records for `agents feed`.\n\nThe manifest invokes this script for top-level AskUserQuestion calls, waiting\nnotifications, question answers, and session lifecycle events. One atomic file\nper session means a new block replaces the previous block. Answer/resume/stop\nevents remove it so `agents feed` only lists decisions that are still open.\n\nSub-agent gate: when the PreToolUse payload carries `agent_type`, this is a\nTask/Agent subagent -- skip. Only the top-level agent publishes. Verified on\nClaude Code 2.1.170 (2026-07).\n\nFail-open: ANY error is swallowed so a feed hiccup never blocks a tool call.\n\"\"\"\nimport os\nimport sys\nimport json\nimport re\nimport socket\nimport tempfile\nfrom datetime import datetime, timezone\n\nWAITING_NOTIFICATION_TYPES = {\n    \"permission_prompt\",\n    \"idle_prompt\",\n    \"elicitation_dialog\",\n}\nCLEAR_EVENTS = {\n    \"PostToolUse\",\n    \"Stop\",\n    \"SessionEnd\",\n}\n\n\ndef read_json(path):\n    try:\n        with open(path) as f:\n            return json.load(f)\n    except Exception:\n        return None\n\n\ndef write_json(path, value):\n    dir_name = os.path.dirname(path)\n    os.makedirs(dir_name, exist_ok=True)\n    fd, tmp = tempfile.mkstemp(dir=dir_name, suffix=\".tmp\")\n    try:\n        with os.fdopen(fd, \"w\") as f:\n            json.dump(value, f, indent=2)\n        os.replace(tmp, path)\n    except Exception:\n        try:\n            os.unlink(tmp)\n        except Exception:\n            pass\n\n\ndef main():\n    raw = sys.stdin.read()\n    try:\n        payload = json.loads(raw) if raw.strip() else {}\n    except Exception:\n        return\n\n    # Sub-agent gate.\n    if payload.get(\"agent_type\"):\n        return\n\n    session_id = payload.get(\"session_id\", \"\")\n    if not session_id:\n        return\n\n    safe_session_id = re.sub(r\"[^A-Za-z0-9._-]\", \"-\", session_id)\n    block_id = f\"block-{safe_session_id}\"\n    home = os.environ.get(\"HOME\") or os.path.expanduser(\"~\")\n    feed_dir = os.path.join(home, \".agents\", \".history\", \"feed\")\n    answered_dir = os.path.join(feed_dir, \"answered\")\n    asks_dir = os.path.join(feed_dir, \"asks\")\n    target = os.path.join(feed_dir, f\"{block_id}.json\")\n    hook_event = payload.get(\"hook_event_name\", \"PreToolUse\")\n\n    if hook_event in CLEAR_EVENTS:\n        try:\n            os.unlink(target)\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        # Also clear the answered marker so a future question for this session\n        # is not permanently locked.\n        try:\n            os.unlink(os.path.join(answered_dir, f\"{block_id}.json\"))\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        return\n\n    # Terminal answers (human typed in the TUI) record an answered marker and\n    # remove the block file so the feed stops showing it within one poll cycle.\n    # The marker stays behind so a concurrent surface cannot double-answer.\n    if hook_event == \"UserPromptSubmit\":\n        os.makedirs(answered_dir, exist_ok=True)\n        marker = os.path.join(answered_dir, f\"{block_id}.json\")\n        try:\n            fd = os.open(marker, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644)\n            record = {\n                \"answeredAt\": datetime.now(timezone.utc).isoformat(),\n                \"answeredFrom\": \"terminal\",\n            }\n            with os.fdopen(fd, \"w\") as f:\n                json.dump(record, f, indent=2)\n        except FileExistsError:\n            pass\n        except Exception:\n            pass\n        # Remove the visible block so the feed drops the answered question.\n        try:\n            os.unlink(target)\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        return\n\n    notification_type = None\n    if hook_event == \"Notification\":\n        notification_type = payload.get(\"notification_type\", \"\")\n        if notification_type not in WAITING_NOTIFICATION_TYPES:\n            return\n        # Claude emits a generic permission notification after presenting an\n        # AskUserQuestion. Keep the structured questions and options already\n        # published for this session instead of replacing them with that less\n        # useful notification text.\n        try:\n            with open(target) as existing_file:\n                existing = json.load(existing_file)\n            if existing.get(\"kind\") == \"question\":\n                return\n        except Exception:\n            pass\n        message = payload.get(\"message\", \"\")\n        if not message:\n            return\n        normalized_questions = [{\n            \"text\": message,\n            \"header\": payload.get(\"title\") or notification_type.replace(\"_\", \" \").title(),\n            \"multiSelect\": False,\n        }]\n        kind = \"notification\"\n    else:\n        tool_input = payload.get(\"tool_input\", {})\n        questions = tool_input.get(\"questions\", [])\n        if not questions:\n            return\n        normalized_questions = []\n        for q in questions:\n            if not isinstance(q, dict):\n                continue\n            question = {\n                \"text\": q.get(\"question\", q.get(\"header\", \"\")),\n                \"header\": q.get(\"header\"),\n                \"multiSelect\": q.get(\"multiSelect\", False),\n            }\n            raw_opts = q.get(\"options\", [])\n            if raw_opts:\n                question[\"options\"] = [\n                    {\"label\": o.get(\"label\", \"\"), \"description\": o.get(\"description\")}\n                    for o in raw_opts\n                    if isinstance(o, dict)\n                ]\n            normalized_questions.append(question)\n        if not normalized_questions:\n            return\n        kind = \"question\"\n\n    # Identity from env (set by agents-cli at spawn).\n    mailbox_id = os.path.basename(\n        os.environ.get(\"AGENTS_MAILBOX_DIR\", \"\").rstrip(\"/\")\n    ) or session_id\n\n    now_iso = datetime.now(timezone.utc).isoformat()\n    stats_path = os.path.join(asks_dir, f\"{safe_session_id}.json\")\n    stats = read_json(stats_path) or {}\n    recent = stats.get(\"recentAskTimestamps\") if isinstance(stats, dict) else []\n    if not isinstance(recent, list):\n        recent = []\n    recent.append(now_iso)\n    # Keep enough history for rolling one-hour needy detection without unbounded\n    # per-session files. The TypeScript reader applies the exact time window.\n    recent = recent[-200:]\n    write_json(stats_path, {\n        \"sessionId\": session_id,\n        \"mailboxId\": mailbox_id,\n        \"firstAskAt\": stats.get(\"firstAskAt\") or now_iso,\n        \"lastAskAt\": now_iso,\n        \"totalAskCount\": int(stats.get(\"totalAskCount\") or 0) + 1,\n        \"recentAskTimestamps\": recent,\n    })\n\n    hostname = os.environ.get(\"AGENTS_SYNC_MACHINE_ID\") or socket.gethostname()\n    host = hostname.split(\".\")[0].strip().lower()\n    host = re.sub(r\"[^a-z0-9_-]\", \"-\", host) or \"unknown\"\n\n    runtime = os.environ.get(\"AGENTS_RUNTIME\", \"headless\")\n\n    block = {\n        \"blockId\": block_id,\n        \"sessionId\": session_id,\n        \"mailboxId\": mailbox_id,\n        \"host\": host,\n        \"runtime\": runtime,\n        \"ts\": now_iso,\n        \"questions\": normalized_questions,\n        \"kind\": kind,\n    }\n    if notification_type:\n        block[\"notificationType\"] = notification_type\n\n    # Optional multi-operator control metadata passed by the agent in the\n    # AskUserQuestion tool_input. Defaults keep the existing behavior.\n    controls = payload.get(\"tool_input\", {}) if hook_event != \"Notification\" else {}\n    block_class = controls.get(\"blockClass\") if isinstance(controls, dict) else None\n    if block_class in (\"approval\", \"decision\"):\n        block[\"blockClass\"] = block_class\n    consequence = controls.get(\"consequence\") if isinstance(controls, dict) else None\n    if consequence:\n        block[\"consequence\"] = consequence\n    allowed = controls.get(\"allowedOperators\") if isinstance(controls, dict) else None\n    if isinstance(allowed, list):\n        block[\"allowedOperators\"] = [str(a) for a in allowed]\n    timeout = controls.get(\"timeoutMinutes\") if isinstance(controls, dict) else None\n    if isinstance(timeout, (int, float)) and timeout > 0:\n        block[\"timeoutMinutes\"] = int(timeout)\n    safe_default = controls.get(\"safeDefault\") if isinstance(controls, dict) else None\n    if isinstance(safe_default, str):\n        block[\"safeDefault\"] = safe_default\n    cost = controls.get(\"costOfDelay\") if isinstance(controls, dict) else None\n    if cost in (\"low\", \"medium\", \"high\"):\n        block[\"costOfDelay\"] = cost\n\n    # Publishing a new question clears any stale answered marker from the\n    # previous question in this session.\n    try:\n        os.unlink(os.path.join(answered_dir, f\"{block_id}.json\"))\n    except FileNotFoundError:\n        pass\n    except Exception:\n        pass\n\n    # Python's expanduser() ignores HOME on Windows, while agents-cli honors a\n    # HOME override on every platform. Use the same anchor so hooks and the CLI\n    # always read/write one feed store (including temp-home and sandbox runs).\n    os.makedirs(feed_dir, exist_ok=True)\n\n    fd, tmp = tempfile.mkstemp(dir=feed_dir, suffix=\".tmp\")\n    try:\n        with os.fdopen(fd, \"w\") as f:\n            json.dump(block, f, indent=2)\n        os.replace(tmp, target)\n    except Exception:\n        try:\n            os.unlink(tmp)\n        except Exception:\n            pass\n\n\nif __name__ == \"__main__\":\n    try:\n        main()\n    except Exception:\n        pass  # fail open\n";
 /** Manifest entry for the feed-publish hook, matching the ManifestHook shape. */
 export declare const FEED_PUBLISH_HOOK_MANIFEST: {
     name: string;

package/dist/lib/feed.js

@@ -25,7 +25,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { getFeedDir, getUserAgentsDir } from './state.js';
-import { isHighConsequenceAllowed } from './operator.js';
+import { isAdmin, isHighConsequenceAllowed, isKnownOperator } from './operator.js';
 /**
  * Stable block id for a session. One block per session -- a new question
  * replaces the previous one (the agent can only ask one question at a time).
@@ -42,6 +42,7 @@ function blockPath(root, blockId) {
 }
 function answeredDir(root) { return path.join(root, 'answered'); }
 function receiptDir(root) { return path.join(root, 'receipts'); }
+function askStatsDir(root) { return path.join(root, 'asks'); }
 function ensureDir(dir) {
     fs.mkdirSync(dir, { recursive: true });
 }
@@ -80,13 +81,29 @@ export function recordAnswer(blockId, answer, root) {
     const operatorId = answer.operatorId;
     if (block?.consequence && block.consequence !== 'normal') {
         // Operators live in ~/.agents/operators.yaml — never the feed store root.
-        if (!operatorId || answer.verified !== true || !isHighConsequenceAllowed(block.consequence, operatorId)) {
+        if (!operatorId || answer.verified !== true || !isKnownOperator(operatorId)) {
             return {
                 ok: false,
                 unauthorized: true,
                 reason: `High-consequence block '${block.consequence}' requires a verified, authorized operator.`,
             };
         }
+        const allowedByBlock = block.allowedOperators?.includes(operatorId) ?? false;
+        const allowedByCapability = isHighConsequenceAllowed(block.consequence, operatorId);
+        if (!allowedByBlock && !allowedByCapability) {
+            return {
+                ok: false,
+                unauthorized: true,
+                reason: `High-consequence block '${block.consequence}' requires a verified, authorized operator.`,
+            };
+        }
+        if (block.allowedOperators?.length && !allowedByBlock && !isAdmin(operatorId)) {
+            return {
+                ok: false,
+                unauthorized: true,
+                reason: `High-consequence block '${block.consequence}' is restricted to: ${block.allowedOperators.join(', ')}.`,
+            };
+        }
     }
     ensureDir(answeredDir(dir));
     const marker = path.join(answeredDir(dir), `${blockId}.json`);
@@ -253,6 +270,32 @@ export function listBlocks(root) {
     }
     return blocks;
 }
+/** Read per-session ask history written by the feed publish hook. */
+export function listAskStats(root) {
+    const dir = askStatsDir(root ?? getFeedDir());
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const stats = [];
+    for (const name of names.filter(n => n.endsWith('.json')).sort()) {
+        const parsed = safeReadJson(path.join(dir, name));
+        if (!parsed?.sessionId || !parsed.mailboxId || !parsed.lastAskAt)
+            continue;
+        stats.push({
+            sessionId: parsed.sessionId,
+            mailboxId: parsed.mailboxId,
+            firstAskAt: parsed.firstAskAt ?? parsed.lastAskAt,
+            lastAskAt: parsed.lastAskAt,
+            totalAskCount: parsed.totalAskCount ?? parsed.recentAskTimestamps?.length ?? 0,
+            recentAskTimestamps: Array.isArray(parsed.recentAskTimestamps) ? parsed.recentAskTimestamps : [],
+        });
+    }
+    return stats;
+}
 /** Remove a block record and its lifecycle sidecars. Returns true if the file was deleted. */
 export function removeBlock(blockId, root) {
     const dir = root ?? getFeedDir();
@@ -350,6 +393,7 @@ def main():
     home = os.environ.get("HOME") or os.path.expanduser("~")
     feed_dir = os.path.join(home, ".agents", ".history", "feed")
     answered_dir = os.path.join(feed_dir, "answered")
+    asks_dir = os.path.join(feed_dir, "asks")
     target = os.path.join(feed_dir, f"{block_id}.json")
     hook_event = payload.get("hook_event_name", "PreToolUse")
 
@@ -453,6 +497,25 @@ def main():
         os.environ.get("AGENTS_MAILBOX_DIR", "").rstrip("/")
     ) or session_id
 
+    now_iso = datetime.now(timezone.utc).isoformat()
+    stats_path = os.path.join(asks_dir, f"{safe_session_id}.json")
+    stats = read_json(stats_path) or {}
+    recent = stats.get("recentAskTimestamps") if isinstance(stats, dict) else []
+    if not isinstance(recent, list):
+        recent = []
+    recent.append(now_iso)
+    # Keep enough history for rolling one-hour needy detection without unbounded
+    # per-session files. The TypeScript reader applies the exact time window.
+    recent = recent[-200:]
+    write_json(stats_path, {
+        "sessionId": session_id,
+        "mailboxId": mailbox_id,
+        "firstAskAt": stats.get("firstAskAt") or now_iso,
+        "lastAskAt": now_iso,
+        "totalAskCount": int(stats.get("totalAskCount") or 0) + 1,
+        "recentAskTimestamps": recent,
+    })
+
     hostname = os.environ.get("AGENTS_SYNC_MACHINE_ID") or socket.gethostname()
     host = hostname.split(".")[0].strip().lower()
     host = re.sub(r"[^a-z0-9_-]", "-", host) or "unknown"
@@ -465,7 +528,7 @@ def main():
         "mailboxId": mailbox_id,
         "host": host,
         "runtime": runtime,
-        "ts": datetime.now(timezone.utc).isoformat(),
+        "ts": now_iso,
         "questions": normalized_questions,
         "kind": kind,
     }

package/dist/lib/fleet/auth-sync.d.ts

@@ -29,6 +29,59 @@ export declare const FLEET_AUTH_FILES: Record<string, AuthFileSpec[]>;
 export declare const KEYCHAIN_BOUND_ON_MAC: ReadonlySet<string>;
 /** Which agents `apply` can propagate auth for at all. */
 export declare function isPropagatableAgent(agent: string): boolean;
+/**
+ * The shape of a login flow — enough for `agents fleet login` to drive a remote
+ * box's device-code OAuth over SSH and scrape the verification URL + user code.
+ *
+ * `flowType` decides remotability:
+ *  - `device-code` — the remote box prints a URL + short code the human enters in
+ *    a browser on THIS machine. The only flow `fleet login` can orchestrate.
+ *  - `loopback`    — the CLI opens a browser and listens on 127.0.0.1 on the
+ *    remote box; the redirect must reach that box's own loopback, so it can only
+ *    be completed with a browser on the same machine. Non-remotable.
+ *  - `api-key`     — a pasted key, not an OAuth handshake. Non-remotable.
+ *  - `unknown`     — flow not yet characterized (no captured output). Non-remotable
+ *    until someone captures the real pattern and fills the regexes.
+ */
+export type LoginFlowType = 'device-code' | 'loopback' | 'api-key' | 'unknown';
+export interface LoginFlow {
+    /**
+     * The exact command that starts the login flow on the remote box, run as
+     * `ssh -tt <box> <loginCommand>`. Bare `<cli>` for agents whose device flow
+     * starts on launch (droid, kimi, gemini, antigravity), `<cli> login` for
+     * codex/grok, `<cli> auth login` for opencode.
+     */
+    loginCommand: string;
+    flowType: LoginFlowType;
+    /**
+     * Keystrokes sent after launch to force the device-code path when the CLI
+     * presents a menu (codex: pick "Sign in with Device Code") or requires a
+     * sub-command inside a TUI (kimi: `/login`). Sent verbatim through the PTY,
+     * so it must include the submitting CR (`\r`). Absent when the flow needs no
+     * steering.
+     */
+    deviceCodeSelect?: string;
+    /** Captures the verification URL from scraped login output (group 1 preferred). */
+    verificationUrlRegex?: RegExp;
+    /** Captures the user code from scraped login output (group 1 preferred). */
+    userCodeRegex?: RegExp;
+    /**
+     * Home-relative credential file that appears / bumps mtime on success — the
+     * completion signal. Mirrors {@link FLEET_AUTH_FILES} (first entry for agents
+     * with several).
+     */
+    successFile: string;
+}
+/**
+ * Per-agent login flows, populated from live login-output captures (the only
+ * ground truth — no fixtures exist upstream). Agents whose real device-code
+ * output has not been captured are marked honestly (`unknown` / no regexes) so
+ * `fleet login` flags them non-remotable instead of guessing.
+ *
+ * Only the `device-code` entries are ones `fleet login` drives; the rest are
+ * carried so the command can explain WHY a logged-out pair is not remotable.
+ */
+export declare const FLEET_LOGIN_FLOWS: Record<string, LoginFlow>;
 export interface SnapshotOptions {
     /** Home directory to read credential files from. */
     home: string;

package/dist/lib/fleet/auth-sync.js

@@ -39,6 +39,98 @@ export const KEYCHAIN_BOUND_ON_MAC = new Set(['claude', 'antigravity']);
 export function isPropagatableAgent(agent) {
     return agent in FLEET_AUTH_FILES;
 }
+/** The success-file for an agent — the primary portable credential (first spec). */
+function successFileFor(agent) {
+    const specs = FLEET_AUTH_FILES[agent];
+    if (!specs || specs.length === 0)
+        throw new Error(`no auth file spec for agent '${agent}'`);
+    return specs[0].rel;
+}
+/**
+ * Per-agent login flows, populated from live login-output captures (the only
+ * ground truth — no fixtures exist upstream). Agents whose real device-code
+ * output has not been captured are marked honestly (`unknown` / no regexes) so
+ * `fleet login` flags them non-remotable instead of guessing.
+ *
+ * Only the `device-code` entries are ones `fleet login` drives; the rest are
+ * carried so the command can explain WHY a logged-out pair is not remotable.
+ */
+export const FLEET_LOGIN_FLOWS = {
+    // droid: launches its TUI and prints, verbatim:
+    //   "If the link does not open automatically, please visit
+    //    https://auth.factory.ai/device and enter code MJQW-NQRM to complete
+    //    authentication." then "Waiting for authentication to complete...".
+    droid: {
+        loginCommand: 'droid',
+        flowType: 'device-code',
+        verificationUrlRegex: /please visit\s+(https:\/\/\S+?)\s+and enter code/i,
+        userCodeRegex: /enter code\s+([A-Z0-9]{4}-[A-Z0-9]{4})/i,
+        successFile: successFileFor('droid'),
+    },
+    // codex login shows a numbered menu; option 2 ("Sign in with Device Code",
+    // "Sign in from another device with a one-time code") is the remotable one.
+    // The post-selection URL/code output was not captured this session, so the
+    // regexes are best-effort generic device-code patterns — TODO: tighten once a
+    // real codex device-code screen is captured.
+    codex: {
+        loginCommand: 'codex login',
+        flowType: 'device-code',
+        deviceCodeSelect: '\x1b[B\r', // down-arrow once (to option 2) + Enter
+        verificationUrlRegex: /(https:\/\/\S*(?:device|activate|login|auth)\S*)/i,
+        userCodeRegex: /\b([A-Z0-9]{4}-[A-Z0-9]{4})\b/,
+        successFile: successFileFor('codex'),
+    },
+    // kimi: launch bare `kimi`, then `/login` inside the TUI, which prints
+    // "Select a platform and authenticate". Post-selection URL/code not captured —
+    // best-effort regexes, TODO: tighten with a real capture.
+    kimi: {
+        loginCommand: 'kimi',
+        flowType: 'device-code',
+        deviceCodeSelect: '/login\r',
+        verificationUrlRegex: /(https:\/\/\S+)/i,
+        userCodeRegex: /\b([A-Z0-9]{4}-[A-Z0-9]{4})\b/,
+        successFile: successFileFor('kimi'),
+    },
+    // grok: `grok login`. No captured pattern this session — flowType is
+    // device-code (best guess for the remotable path) but regexes are left unset
+    // (TODO: capture grok's login output), so scrapeLogin yields nothing until a
+    // real pattern is added and driveRemoteLogin will time out rather than guess.
+    grok: {
+        loginCommand: 'grok login',
+        flowType: 'device-code',
+        successFile: successFileFor('grok'),
+    },
+    // antigravity: bare `agy`, Google OAuth. Keychain-bound on macOS and loopback
+    // (browser + 127.0.0.1 listener on the box itself) — non-remotable.
+    antigravity: {
+        loginCommand: 'agy',
+        flowType: 'loopback',
+        successFile: successFileFor('antigravity'),
+    },
+    // gemini: bare `gemini`, Google login on launch. Not characterized as a
+    // device-code flow (typically loopback) and no captured pattern — mark unknown
+    // so it is flagged non-remotable rather than mis-driven.
+    gemini: {
+        loginCommand: 'gemini',
+        flowType: 'unknown',
+        successFile: successFileFor('gemini'),
+    },
+    // opencode: `opencode auth login`. No captured pattern — unknown/non-remotable.
+    opencode: {
+        loginCommand: 'opencode auth login',
+        flowType: 'unknown',
+        successFile: successFileFor('opencode'),
+    },
+    // claude: interactive `/login` inside the TUI is a loopback browser flow, and
+    // the token is keychain-bound on macOS. A headless `claude setup-token` device
+    // variant exists (TODO: wire as a device-code flow with a captured pattern);
+    // until then claude is flagged non-remotable.
+    claude: {
+        loginCommand: 'claude',
+        flowType: 'loopback',
+        successFile: successFileFor('claude'),
+    },
+};
 /**
  * Capture portable credential files for the given agents from a source home.
  * Returns the readable file payloads plus the list of agents whose auth is