@zeph-to/cli 1.14.0 → 1.15.1

package/dist/agent-rules-fetch.d.ts

@@ -0,0 +1,33 @@
+import { type DetectionManifest } from './agent-state.js';
+export declare const RULES_CACHE_FILE: string;
+export declare const RULES_REFRESH_INTERVAL_MS: number;
+/**
+ * Structural validation of an untrusted manifest. Engine-version gate
+ * included: a manifest authored for a future engine is rejected whole —
+ * partial interpretation of unknown semantics is worse than falling
+ * back to bundled rules.
+ */
+export declare const validateManifest: (value: unknown) => DetectionManifest | null;
+export type ManifestSource = 'remote' | 'cache' | 'bundled';
+export declare const getActiveManifest: () => DetectionManifest;
+export declare const getActiveManifestSource: () => ManifestSource;
+/** Test hook. */
+export declare const resetActiveManifest: () => void;
+/**
+ * Startup path (synchronous): promote the disk cache if it validates,
+ * else stay on bundled. Never throws — detection must work offline.
+ */
+export declare const loadManifestFromCache: () => ManifestSource;
+export declare const rulesUrl: () => string;
+export interface RefreshResult {
+    source: ManifestSource;
+    /** 'updated' | 'not-modified' | 'invalid' | 'error' — for verbose logs. */
+    outcome: string;
+    version?: string;
+}
+/**
+ * One refresh attempt: conditional GET, validate, persist, activate.
+ * All failure modes degrade to the current active manifest.
+ */
+export declare const refreshManifest: (fetchImpl?: typeof fetch) => Promise<RefreshResult>;
+//# sourceMappingURL=agent-rules-fetch.d.ts.map

package/dist/agent-rules-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-rules-fetch.d.ts","sourceRoot":"","sources":["../src/agent-rules-fetch.ts"],"names":[],"mappings":"AAeA,OAAO,EAEH,KAAK,iBAAiB,EACzB,MAAM,kBAAkB,CAAC;AAG1B,eAAO,MAAM,gBAAgB,QAAuC,CAAC;AACrE,eAAO,MAAM,yBAAyB,QAAqB,CAAC;AA6C5D;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,OAAO,KAAG,iBAAiB,GAAG,IAWrE,CAAC;AAIF,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAK5D,eAAO,MAAM,iBAAiB,QAAO,iBAAmC,CAAC;AACzE,eAAO,MAAM,uBAAuB,QAAO,cAA8B,CAAC;AAS1E,iBAAiB;AACjB,eAAO,MAAM,mBAAmB,QAAO,IAEtC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,QAAO,cAWxC,CAAC;AAWF,eAAO,MAAM,QAAQ,QAAO,MAK3B,CAAC;AAEF,MAAM,WAAW,aAAa;IAC1B,MAAM,EAAE,cAAc,CAAC;IACvB,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAU,YAAW,OAAO,KAAa,KAAG,OAAO,CAAC,aAAa,CAsC5F,CAAC"}

package/dist/agent-rules-fetch.js

@@ -0,0 +1,190 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.refreshManifest = exports.rulesUrl = exports.loadManifestFromCache = exports.resetActiveManifest = exports.getActiveManifestSource = exports.getActiveManifest = exports.validateManifest = exports.RULES_REFRESH_INTERVAL_MS = exports.RULES_CACHE_FILE = void 0;
+/**
+ * OTA delivery for agent detection rules (SPEC-AGENT-AWARENESS §S7).
+ *
+ * Agent UIs change on their release cadence, not ours: when Claude
+ * Code reshapes its status line, detection must be fixable by shipping
+ * DATA, not a new daemon. The listener therefore resolves its manifest
+ * as: valid remote fetch → valid disk cache → bundled defaults. Every
+ * tier fails closed to the next — a dead endpoint, corrupt cache, or
+ * hostile payload can never leave the listener without rules, and
+ * `disabledRuleIds` in a fetched manifest acts as a same-day
+ * kill-switch for a misfiring rule (no release, no restart).
+ */
+const fs_1 = require("fs");
+const path_1 = require("path");
+const config_js_1 = require("./config.js");
+const agent_state_js_1 = require("./agent-state.js");
+const agent_rules_default_js_1 = require("./agent-rules.default.js");
+exports.RULES_CACHE_FILE = (0, path_1.join)(config_js_1.CONFIG_DIR, 'agent-rules.json');
+exports.RULES_REFRESH_INTERVAL_MS = 6 * 60 * 60 * 1000;
+// Fallback only — the manifest path normally derives from the resolved
+// API base so the stage prefix (prod /v1, dev /d1) follows the user's
+// config instead of being hardcoded here.
+const DEFAULT_API_BASE = 'https://api.zeph.to/v1';
+// Matches the server-side serving cap; anything bigger is not a manifest.
+const MAX_MANIFEST_BYTES = 256 * 1024;
+const FETCH_TIMEOUT_MS = 10_000;
+const VALID_STATES = new Set(['working', 'blocked', 'idle', 'unknown']);
+const isStringArray = (v) => Array.isArray(v) && v.every((s) => typeof s === 'string');
+const isCondition = (v) => {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const c = v;
+    if (c.contains !== undefined && !isStringArray(c.contains))
+        return false;
+    if (c.regex !== undefined && !isStringArray(c.regex))
+        return false;
+    return true;
+};
+const isRule = (v) => {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const r = v;
+    if (typeof r.id !== 'string' || r.id.length === 0)
+        return false;
+    if (typeof r.state !== 'string' || !VALID_STATES.has(r.state))
+        return false;
+    if (typeof r.priority !== 'number' || !Number.isFinite(r.priority))
+        return false;
+    if (r.region !== undefined && r.region !== 'tail' && r.region !== 'whole')
+        return false;
+    if (r.tailLines !== undefined && (typeof r.tailLines !== 'number' || r.tailLines < 1 || r.tailLines > 200))
+        return false;
+    if (r.contains !== undefined && !isStringArray(r.contains))
+        return false;
+    if (r.regex !== undefined && !isStringArray(r.regex))
+        return false;
+    if (r.any !== undefined && (!Array.isArray(r.any) || !r.any.every(isCondition)))
+        return false;
+    if (r.not !== undefined && (!Array.isArray(r.not) || !r.not.every(isCondition)))
+        return false;
+    if (r.skipStateUpdate !== undefined && typeof r.skipStateUpdate !== 'boolean')
+        return false;
+    return true;
+};
+/**
+ * Structural validation of an untrusted manifest. Engine-version gate
+ * included: a manifest authored for a future engine is rejected whole —
+ * partial interpretation of unknown semantics is worse than falling
+ * back to bundled rules.
+ */
+const validateManifest = (value) => {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const m = value;
+    if (m.engineVersion !== agent_state_js_1.ENGINE_VERSION)
+        return null;
+    if (typeof m.version !== 'string' || m.version.length === 0)
+        return null;
+    if (m.disabledRuleIds !== undefined && !isStringArray(m.disabledRuleIds))
+        return null;
+    if (typeof m.agents !== 'object' || m.agents === null)
+        return null;
+    for (const rules of Object.values(m.agents)) {
+        if (!Array.isArray(rules) || !rules.every(isRule))
+            return null;
+    }
+    return value;
+};
+exports.validateManifest = validateManifest;
+let activeManifest = agent_rules_default_js_1.DEFAULT_MANIFEST;
+let activeSource = 'bundled';
+const getActiveManifest = () => activeManifest;
+exports.getActiveManifest = getActiveManifest;
+const getActiveManifestSource = () => activeSource;
+exports.getActiveManifestSource = getActiveManifestSource;
+const activateManifest = (manifest, source) => {
+    activeManifest = manifest;
+    activeSource = source;
+    // Old manifest's compiled patterns must not pin memory forever.
+    (0, agent_state_js_1.clearRegexCache)();
+};
+/** Test hook. */
+const resetActiveManifest = () => {
+    activateManifest(agent_rules_default_js_1.DEFAULT_MANIFEST, 'bundled');
+};
+exports.resetActiveManifest = resetActiveManifest;
+/**
+ * Startup path (synchronous): promote the disk cache if it validates,
+ * else stay on bundled. Never throws — detection must work offline.
+ */
+const loadManifestFromCache = () => {
+    try {
+        const cache = JSON.parse((0, fs_1.readFileSync)(exports.RULES_CACHE_FILE, 'utf-8'));
+        const manifest = (0, exports.validateManifest)(cache.manifest);
+        if (manifest) {
+            activateManifest(manifest, 'cache');
+        }
+    }
+    catch {
+        // Missing/corrupt cache — bundled rules carry the session.
+    }
+    return activeSource;
+};
+exports.loadManifestFromCache = loadManifestFromCache;
+const readCachedEtag = () => {
+    try {
+        const cache = JSON.parse((0, fs_1.readFileSync)(exports.RULES_CACHE_FILE, 'utf-8'));
+        return typeof cache.etag === 'string' ? cache.etag : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+const rulesUrl = () => {
+    const override = (0, config_js_1.resolvedEnv)('ZEPH_AGENT_RULES_URL');
+    if (override)
+        return override;
+    const base = (0, config_js_1.resolvedEnv)('ZEPH_BASE_URL') ?? (0, config_js_1.loadConfig)().baseUrl ?? DEFAULT_API_BASE;
+    return `${base.replace(/\/$/, '')}/agent-detection/manifest`;
+};
+exports.rulesUrl = rulesUrl;
+/**
+ * One refresh attempt: conditional GET, validate, persist, activate.
+ * All failure modes degrade to the current active manifest.
+ */
+const refreshManifest = async (fetchImpl = fetch) => {
+    try {
+        const etag = readCachedEtag();
+        const res = await fetchImpl((0, exports.rulesUrl)(), {
+            headers: etag ? { 'If-None-Match': etag } : {},
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+        if (res.status === 304) {
+            return { source: activeSource, outcome: 'not-modified', version: activeManifest.version };
+        }
+        if (!res.ok) {
+            return { source: activeSource, outcome: 'error' };
+        }
+        const body = await res.text();
+        if (Buffer.byteLength(body, 'utf-8') > MAX_MANIFEST_BYTES) {
+            return { source: activeSource, outcome: 'invalid' };
+        }
+        const manifest = (0, exports.validateManifest)(JSON.parse(body));
+        if (!manifest) {
+            return { source: activeSource, outcome: 'invalid' };
+        }
+        const cache = {
+            etag: res.headers.get('etag') ?? undefined,
+            fetchedAt: new Date().toISOString(),
+            manifest,
+        };
+        try {
+            (0, fs_1.mkdirSync)(config_js_1.CONFIG_DIR, { recursive: true });
+            (0, fs_1.writeFileSync)(exports.RULES_CACHE_FILE, JSON.stringify(cache, null, 2) + '\n');
+        }
+        catch {
+            // Cache write failure is non-fatal: the manifest still
+            // activates for this process lifetime.
+        }
+        activateManifest(manifest, 'remote');
+        return { source: 'remote', outcome: 'updated', version: manifest.version };
+    }
+    catch {
+        return { source: activeSource, outcome: 'error' };
+    }
+};
+exports.refreshManifest = refreshManifest;

package/dist/agent-rules.default.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Bundled default detection rules — the fallback when no OTA manifest
+ * has been fetched (or the fetched one fails validation, §S7).
+ *
+ * Rule content is authored HERE, from observation of each agent's UI.
+ * Do not import or transcribe rules from third-party projects: the
+ * bundled set is original work under this repo's license.
+ *
+ * Claude Code observations behind these rules (UI as of mid-2026):
+ * - While running, the status line shows an "esc to interrupt" hint
+ *   next to the spinner/progress text.
+ * - Blocking dialogs (permission requests, plan approval, question
+ *   forms) render a numbered/arrow-key option list with "esc" as the
+ *   cancel affordance and Enter as the confirm affordance.
+ * - At rest, the input box renders a `❯` prompt and the footer offers
+ *   "? for shortcuts".
+ * - The transcript viewer (ctrl+o) overlays the pane; the agent may
+ *   still be working underneath, so it must not change the state.
+ *
+ * codex/gemini start with no rules: they report `unknown` until a
+ * vetted rule set ships via OTA. Honest ignorance beats guessed state.
+ */
+import { type DetectionManifest } from './agent-state.js';
+export declare const DEFAULT_MANIFEST: DetectionManifest;
+//# sourceMappingURL=agent-rules.default.d.ts.map

package/dist/agent-rules.default.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-rules.default.d.ts","sourceRoot":"","sources":["../src/agent-rules.default.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAkB,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1E,eAAO,MAAM,gBAAgB,EAAE,iBAiF9B,CAAC"}

package/dist/agent-rules.default.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MANIFEST = void 0;
+/**
+ * Bundled default detection rules — the fallback when no OTA manifest
+ * has been fetched (or the fetched one fails validation, §S7).
+ *
+ * Rule content is authored HERE, from observation of each agent's UI.
+ * Do not import or transcribe rules from third-party projects: the
+ * bundled set is original work under this repo's license.
+ *
+ * Claude Code observations behind these rules (UI as of mid-2026):
+ * - While running, the status line shows an "esc to interrupt" hint
+ *   next to the spinner/progress text.
+ * - Blocking dialogs (permission requests, plan approval, question
+ *   forms) render a numbered/arrow-key option list with "esc" as the
+ *   cancel affordance and Enter as the confirm affordance.
+ * - At rest, the input box renders a `❯` prompt and the footer offers
+ *   "? for shortcuts".
+ * - The transcript viewer (ctrl+o) overlays the pane; the agent may
+ *   still be working underneath, so it must not change the state.
+ *
+ * codex/gemini start with no rules: they report `unknown` until a
+ * vetted rule set ships via OTA. Honest ignorance beats guessed state.
+ */
+const agent_state_js_1 = require("./agent-state.js");
+exports.DEFAULT_MANIFEST = {
+    engineVersion: agent_state_js_1.ENGINE_VERSION,
+    version: '2026.07.04.2',
+    agents: {
+        claude: [
+            {
+                // Transcript / verbose-output overlay: freeze state.
+                id: 'claude-transcript-overlay',
+                state: 'unknown',
+                priority: 1000,
+                skipStateUpdate: true,
+                any: [
+                    { contains: ['showing detailed transcript'] },
+                    { contains: ['ctrl+o to toggle'] },
+                ],
+            },
+            {
+                // Blocking dialog: an option list waiting on the user.
+                // "esc" alone is ambiguous (working shows "esc to
+                // interrupt"), so require a selection affordance too.
+                id: 'claude-blocked-dialog',
+                state: 'blocked',
+                priority: 900,
+                contains: ['esc'],
+                any: [
+                    { contains: ['do you want'] },
+                    { contains: ['enter to select'] },
+                    { contains: ['enter to confirm'] },
+                    { contains: ['to navigate'] },
+                ],
+                not: [{ contains: ['esc to interrupt'] }],
+            },
+            {
+                id: 'claude-working-interrupt-hint',
+                state: 'working',
+                priority: 800,
+                contains: ['esc to interrupt'],
+            },
+            {
+                // Newer CC skins drop the "esc to interrupt" hint; the
+                // live token counter on the spinner line
+                // ("✶ Churning… (1m 2s · ↓ 1.2k tokens)") only renders
+                // while the agent is actually running.
+                id: 'claude-working-token-counter',
+                state: 'working',
+                priority: 790,
+                regex: ['[↓↑]\\s?[\\d.,]+k? tokens'],
+            },
+            {
+                // Elapsed-time spinner suffix ("(12s · ..." / "(1m 2s ·")
+                // — second fallback for skins that hide the token counter
+                // early in a turn.
+                id: 'claude-working-elapsed-spinner',
+                state: 'working',
+                priority: 780,
+                regex: ['…\\s*\\((?:\\d+m )?\\d+s ·'],
+            },
+            {
+                // Idle prompt: `❯` at line start in the tail, with no
+                // dialog affordances around it.
+                id: 'claude-idle-prompt',
+                state: 'idle',
+                priority: 600,
+                regex: ['^\\s*❯'],
+                not: [
+                    { contains: ['do you want'] },
+                    { contains: ['enter to select'] },
+                ],
+            },
+            {
+                // Fallback idle signal when the prompt glyph is themed
+                // away: the shortcuts footer only renders at rest.
+                id: 'claude-idle-shortcuts-footer',
+                state: 'idle',
+                priority: 500,
+                contains: ['? for shortcuts'],
+            },
+        ],
+        codex: [],
+        gemini: [],
+    },
+};

package/dist/agent-state.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Agent state detection engine — classifies a tmux pane's visible text
+ * into `working | blocked | idle | unknown` using declarative rules.
+ *
+ * Design constraints (see zeph/docs/SPEC-AGENT-AWARENESS.md §S1):
+ * - Rules are DATA, not code: they ship bundled but are replaceable
+ *   over the air (§S7), so agent UI changes never require a daemon
+ *   release. Everything here must therefore survive hostile or
+ *   malformed manifests: pattern-length caps, input-size caps, and
+ *   per-rule isolation of regex compile failures.
+ * - Pure functions only. The listener owns timing, tmux, and I/O;
+ *   this module owns classification and flap suppression so both are
+ *   unit-testable without a terminal.
+ * - `done` is deliberately NOT a wire state: "finished but unseen" is
+ *   per-user view state, derived client-side. The daemon reports only
+ *   what it can observe.
+ */
+import type { AgentKind } from './remote-agents.js';
+export type AgentState = 'working' | 'blocked' | 'idle' | 'unknown';
+export interface RuleCondition {
+    /** All strings must appear (case-insensitive). */
+    contains?: string[];
+    /** All patterns must match. */
+    regex?: string[];
+}
+export interface DetectionRule {
+    id: string;
+    state: AgentState;
+    /** Higher wins; first match ends evaluation. */
+    priority: number;
+    /** 'tail' = last N non-empty lines (default), 'whole' = full capture. */
+    region?: 'tail' | 'whole';
+    /** Lines for region 'tail'. Default 10. */
+    tailLines?: number;
+    contains?: string[];
+    regex?: string[];
+    /** At least one condition group must match (OR). */
+    any?: RuleCondition[];
+    /** No condition group may match (exclusion). */
+    not?: RuleCondition[];
+    /**
+     * On match, keep the previous state instead of this rule's state.
+     * For overlay screens (transcript viewer, menus) that would
+     * otherwise pollute the state while the agent is still working.
+     */
+    skipStateUpdate?: boolean;
+}
+export interface DetectionManifest {
+    engineVersion: number;
+    /** Date.revision, e.g. "2026.07.04.1" — for OTA freshness compare. */
+    version: string;
+    /** Kill-switch: rule ids to ignore without shipping a new manifest shape. */
+    disabledRuleIds?: string[];
+    agents: Partial<Record<AgentKind, DetectionRule[]>>;
+}
+export declare const ENGINE_VERSION = 1;
+export interface EvaluationResult {
+    state: AgentState;
+    /** Rule that decided the state — for verbose logs and rule debugging. */
+    ruleId?: string;
+}
+/** Test hook: manifest swaps call this so stale patterns don't pin memory. */
+export declare const clearRegexCache: () => void;
+/**
+ * Classify one pane capture. `prev` feeds skipStateUpdate rules — an
+ * overlay match returns the previous confirmed state unchanged.
+ */
+export declare const evaluateState: (paneText: string, agentKind: AgentKind, manifest: DetectionManifest, prev?: AgentState) => EvaluationResult;
+/**
+ * Safe one-pattern probe for output-match watches (§S5 v2). Same caps
+ * as rule evaluation — user-authored watch patterns are exactly as
+ * untrusted as OTA rules. Returns the matched line for the push body.
+ */
+export declare const findPatternMatch: (pattern: string, paneText: string) => {
+    line: string;
+} | null;
+export interface StateTracker {
+    /** Last CONFIRMED state — what gets reported to the server. */
+    confirmed: AgentState;
+    confirmedAt: number;
+    ruleId?: string;
+    /** Pending different observation awaiting its second sighting. */
+    candidate?: AgentState;
+    candidateRuleId?: string;
+    /** Hash of the pane text behind the last evaluation (skip re-eval). */
+    contentHash?: string;
+}
+/**
+ * Consecutive-confirmation debounce: a NEW state must be observed on
+ * two consecutive cycles (~10 s at the 5 s report interval) before it
+ * replaces the confirmed one. Menus flashed open, mid-render frames,
+ * and scroll artifacts all last one cycle and die as candidates.
+ *
+ * The very first observation confirms immediately — a fresh tracker
+ * has no baseline to protect, and the server treats a session's first
+ * reported state as baseline, not as a transition (§S2).
+ */
+export declare const advanceState: (tracker: StateTracker | undefined, observed: EvaluationResult, now: number) => StateTracker;
+//# sourceMappingURL=agent-state.d.ts.map

package/dist/agent-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-state.d.ts","sourceRoot":"","sources":["../src/agent-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAEpE,MAAM,WAAW,aAAa;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,+BAA+B;IAC/B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,UAAU,CAAC;IAClB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,oDAAoD;IACpD,GAAG,CAAC,EAAE,aAAa,EAAE,CAAC;IACtB,gDAAgD;IAChD,GAAG,CAAC,EAAE,aAAa,EAAE,CAAC;IACtB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,iBAAiB;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC;CACvD;AAED,eAAO,MAAM,cAAc,IAAI,CAAC;AAUhC,MAAM,WAAW,gBAAgB;IAC7B,KAAK,EAAE,UAAU,CAAC;IAClB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAqBD,8EAA8E;AAC9E,eAAO,MAAM,eAAe,QAAO,IAElC,CAAC;AA8BF;;;GAGG;AACH,eAAO,MAAM,aAAa,GACtB,UAAU,MAAM,EAChB,WAAW,SAAS,EACpB,UAAU,iBAAiB,EAC3B,OAAM,UAAsB,KAC7B,gBAuBF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,MAAM,EAAE,UAAU,MAAM,KAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAavF,CAAC;AAIF,MAAM,WAAW,YAAY;IACzB,+DAA+D;IAC/D,SAAS,EAAE,UAAU,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,SAAS,CAAC,EAAE,UAAU,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GACrB,SAAS,YAAY,GAAG,SAAS,EACjC,UAAU,gBAAgB,EAC1B,KAAK,MAAM,KACZ,YAaF,CAAC"}

package/dist/agent-state.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.advanceState = exports.findPatternMatch = exports.evaluateState = exports.clearRegexCache = exports.ENGINE_VERSION = void 0;
+exports.ENGINE_VERSION = 1;
+// OTA manifests are semi-trusted: schema-validated but authored by
+// humans and fetched over the network. Caps bound the worst case of a
+// pathological regex (ReDoS) — a 200-char pattern over ≤8 KiB input
+// keeps even catastrophic backtracking in the low milliseconds.
+const MAX_PATTERN_LENGTH = 200;
+const MAX_INPUT_BYTES = 8 * 1024;
+const DEFAULT_TAIL_LINES = 10;
+// Compiled-regex cache. Rules are static between manifest swaps, so
+// compiling once per (pattern) is enough; a failed compile is cached as
+// null so a bad OTA pattern logs once, not every 5-second cycle.
+const regexCache = new Map();
+const compilePattern = (pattern) => {
+    if (regexCache.has(pattern))
+        return regexCache.get(pattern) ?? null;
+    let compiled = null;
+    if (pattern.length <= MAX_PATTERN_LENGTH) {
+        try {
+            compiled = new RegExp(pattern, 'im');
+        }
+        catch {
+            compiled = null;
+        }
+    }
+    regexCache.set(pattern, compiled);
+    return compiled;
+};
+/** Test hook: manifest swaps call this so stale patterns don't pin memory. */
+const clearRegexCache = () => {
+    regexCache.clear();
+};
+exports.clearRegexCache = clearRegexCache;
+const conditionMatches = (cond, text, lowerText) => {
+    for (const needle of cond.contains ?? []) {
+        if (!lowerText.includes(needle.toLowerCase()))
+            return false;
+    }
+    for (const pattern of cond.regex ?? []) {
+        const compiled = compilePattern(pattern);
+        // A pattern that failed to compile can never be satisfied —
+        // fail the condition rather than silently passing it, so a
+        // broken OTA rule becomes inert instead of over-matching.
+        if (!compiled || !compiled.test(text))
+            return false;
+    }
+    return true;
+};
+const ruleMatches = (rule, text, lowerText) => {
+    if (!conditionMatches({ contains: rule.contains, regex: rule.regex }, text, lowerText))
+        return false;
+    if (rule.any && rule.any.length > 0) {
+        if (!rule.any.some((c) => conditionMatches(c, text, lowerText)))
+            return false;
+    }
+    for (const excluded of rule.not ?? []) {
+        if (conditionMatches(excluded, text, lowerText))
+            return false;
+    }
+    return true;
+};
+const tailOf = (lines, count) => lines.filter((l) => l.trim().length > 0).slice(-count).join('\n');
+/**
+ * Classify one pane capture. `prev` feeds skipStateUpdate rules — an
+ * overlay match returns the previous confirmed state unchanged.
+ */
+const evaluateState = (paneText, agentKind, manifest, prev = 'unknown') => {
+    // Truncate from the FRONT: the bottom of the pane is where every
+    // agent renders its live status, so the tail is the signal.
+    let text = paneText;
+    if (Buffer.byteLength(text, 'utf-8') > MAX_INPUT_BYTES) {
+        text = text.slice(-MAX_INPUT_BYTES);
+    }
+    const lines = text.split('\n');
+    const disabled = new Set(manifest.disabledRuleIds ?? []);
+    const rules = (manifest.agents[agentKind] ?? [])
+        .filter((r) => !disabled.has(r.id))
+        .sort((a, b) => b.priority - a.priority);
+    for (const rule of rules) {
+        const scope = rule.region === 'whole'
+            ? text
+            : tailOf(lines, rule.tailLines ?? DEFAULT_TAIL_LINES);
+        if (ruleMatches(rule, scope, scope.toLowerCase())) {
+            if (rule.skipStateUpdate)
+                return { state: prev, ruleId: rule.id };
+            return { state: rule.state, ruleId: rule.id };
+        }
+    }
+    return { state: 'unknown' };
+};
+exports.evaluateState = evaluateState;
+/**
+ * Safe one-pattern probe for output-match watches (§S5 v2). Same caps
+ * as rule evaluation — user-authored watch patterns are exactly as
+ * untrusted as OTA rules. Returns the matched line for the push body.
+ */
+const findPatternMatch = (pattern, paneText) => {
+    let text = paneText;
+    if (Buffer.byteLength(text, 'utf-8') > MAX_INPUT_BYTES) {
+        text = text.slice(-MAX_INPUT_BYTES);
+    }
+    const compiled = compilePattern(pattern);
+    if (!compiled)
+        return null;
+    const match = compiled.exec(text);
+    if (!match)
+        return null;
+    const start = text.lastIndexOf('\n', match.index) + 1;
+    const endIdx = text.indexOf('\n', match.index);
+    const line = text.slice(start, endIdx === -1 ? undefined : endIdx).trim();
+    return { line };
+};
+exports.findPatternMatch = findPatternMatch;
+/**
+ * Consecutive-confirmation debounce: a NEW state must be observed on
+ * two consecutive cycles (~10 s at the 5 s report interval) before it
+ * replaces the confirmed one. Menus flashed open, mid-render frames,
+ * and scroll artifacts all last one cycle and die as candidates.
+ *
+ * The very first observation confirms immediately — a fresh tracker
+ * has no baseline to protect, and the server treats a session's first
+ * reported state as baseline, not as a transition (§S2).
+ */
+const advanceState = (tracker, observed, now) => {
+    if (!tracker) {
+        return { confirmed: observed.state, confirmedAt: now, ruleId: observed.ruleId };
+    }
+    if (observed.state === tracker.confirmed) {
+        // Re-confirmation clears any pending candidate.
+        return { ...tracker, candidate: undefined, candidateRuleId: undefined, ruleId: observed.ruleId ?? tracker.ruleId };
+    }
+    if (observed.state === tracker.candidate) {
+        // Second consecutive sighting — promote.
+        return { confirmed: observed.state, confirmedAt: now, ruleId: observed.ruleId };
+    }
+    return { ...tracker, candidate: observed.state, candidateRuleId: observed.ruleId };
+};
+exports.advanceState = advanceState;

package/dist/listener.d.ts

@@ -21,6 +21,7 @@
  * backoff on transient failures; gives up on auth failures (4001/4002/4003).
  */
 import { type AgentKind, type RegisteredRemoteAgent } from './remote-agents.js';
+import { type AgentState } from './agent-state.js';
 interface AgentSession {
     name: string;
     attached: boolean;
@@ -30,6 +31,15 @@ interface AgentSession {
     label?: string | null;
     createdAt?: string;
     lastActivityAt?: string;
+    /**
+     * Detected agent state (wire contract — flows to the server and the
+     * phone's Agents tab). Absent when the pane can't be captured or
+     * detection is unavailable. `done` never appears here: it's derived
+     * client-side (SPEC-AGENT-AWARENESS §S1/§S6).
+     */
+    state?: AgentState;
+    stateChangedAt?: string;
+    stateRuleId?: string;
 }
 export declare const AUTH_FAILURE_CODES: ReadonlySet<number>;
 export declare const checkRateLimit: (session: string, now?: number) => boolean;
@@ -71,6 +81,62 @@ interface PaneInfo {
  * remote-agents.ts are accepted as a match.
  */
 export declare const detectRemoteAgent: (info: PaneInfo) => RegisteredRemoteAgent | null;
+/** Test hook. */
+export declare const resetSessionStates: () => void;
+/**
+ * Fold one pane capture into the per-session state machine and return
+ * the wire fields for this report cycle. Exported (with `paneText`
+ * injected) so tests can drive it without tmux.
+ *
+ * Hash short-circuit: an unchanged screen skips rule evaluation but
+ * still replays the previous observation through the debounce — cheap
+ * cycles stay cheap without wedging candidate promotion.
+ */
+export declare const deriveSessionState: (name: string, agentKind: AgentKind, paneText: string | null, now?: number) => Pick<AgentSession, "state" | "stateChangedAt" | "stateRuleId">;
+export interface PatternWatch {
+    sessionName: string;
+    pattern: string;
+}
+/** Ack payload → active watch list. Prunes fired-markers for dead watches. */
+export declare const setPatternWatches: (raw: unknown) => void;
+/** Test hook. */
+export declare const resetPatternWatches: () => void;
+export interface WatchHit {
+    sessionName: string;
+    pattern: string;
+    matchedLine: string;
+}
+/**
+ * Probe every un-fired watch whose session is live. `capture` is
+ * injectable for tests; production passes capturePaneText.
+ */
+export declare const collectWatchHits: (liveNames: ReadonlySet<string>, capture?: (session: string) => string | null) => WatchHit[];
+export interface ScreenRequest {
+    subtype?: string;
+    targetDeviceId?: string;
+    sessionName?: string;
+    requestId?: string;
+}
+export interface ScreenSnapshot {
+    subtype: 'agent.screen.snapshot';
+    requestId: string;
+    sessionName: string;
+    content?: string;
+    truncated?: boolean;
+    error?: string;
+    capturedAt: string;
+}
+/**
+ * Answer a phone's screen-peek request for one of OUR sessions.
+ * Returns null when the message isn't addressed to this machine (other
+ * ephemeral traffic — clipboard, mirrors — flows through constantly).
+ *
+ * Security posture: only sessions the inventory already exposes are
+ * readable — the phone can see exactly the panes it can already send
+ * commands into, nothing else. Rate-limited with the same per-session
+ * token bucket as command injection.
+ */
+export declare const handleScreenRequest: (req: ScreenRequest) => ScreenSnapshot | null;
 export interface CollectResult {
     sessions: AgentSession[];
     /** Diagnostic notes per rejected session — surfaced under `--verbose`. */

package/dist/listener.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"listener.d.ts","sourceRoot":"","sources":["../src/listener.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"listener.d.ts","sourceRoot":"","sources":["../src/listener.ts"],"names":[],"mappings":"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"}

package/dist/listener.js

@@ -25,7 +25,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleListener = exports.computeListenerDeviceId = exports.computeBackoff = exports.handlePush = exports.gcAttachments = exports.setAttachmentContext = exports.collectSessions = exports.collectSessionsVerbose = exports.detectRemoteAgent = exports.parseSessionName = exports.invalidateTmuxSocketCache = exports.paneCurrentCommand = exports.checkRateLimit = exports.AUTH_FAILURE_CODES = void 0;
+exports.handleListener = exports.computeListenerDeviceId = exports.computeBackoff = exports.handlePush = exports.gcAttachments = exports.setAttachmentContext = exports.collectSessions = exports.collectSessionsVerbose = exports.handleScreenRequest = exports.collectWatchHits = exports.resetPatternWatches = exports.setPatternWatches = exports.deriveSessionState = exports.resetSessionStates = exports.detectRemoteAgent = exports.parseSessionName = exports.invalidateTmuxSocketCache = exports.paneCurrentCommand = exports.checkRateLimit = exports.AUTH_FAILURE_CODES = void 0;
 const child_process_1 = require("child_process");
 const crypto_1 = require("crypto");
 const fs_1 = require("fs");
@@ -34,6 +34,8 @@ const path_1 = require("path");
 const ws_1 = __importDefault(require("ws"));
 const config_js_1 = require("./config.js");
 const remote_agents_js_1 = require("./remote-agents.js");
+const agent_state_js_1 = require("./agent-state.js");
+const agent_rules_fetch_js_1 = require("./agent-rules-fetch.js");
 const PING_INTERVAL_MS = 25_000;
 const PONG_TIMEOUT_MS = 10_000;
 const RECONNECT_BASE_MS = 1_000;
@@ -466,6 +468,166 @@ const epochToIso = (epoch) => {
         return undefined;
     return new Date(n * 1000).toISOString();
 };
+// ─── Agent state detection (SPEC-AGENT-AWARENESS §S1) ──────────────
+// How many pane lines the state rules see. The live status area every
+// agent renders sits in the last handful of lines; 40 leaves margin for
+// tall dialogs without hauling whole scrollbacks through regex.
+const STATE_CAPTURE_LINES = 40;
+const sessionStates = new Map();
+/** Test hook. */
+const resetSessionStates = () => {
+    sessionStates.clear();
+};
+exports.resetSessionStates = resetSessionStates;
+const capturePaneText = (session) => {
+    const r = (0, child_process_1.spawnSync)('tmux', tmuxArgs(['capture-pane', '-p', '-t', session, '-S', `-${STATE_CAPTURE_LINES}`]), {
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (r.status !== 0)
+        return null;
+    return r.stdout ?? '';
+};
+/**
+ * Fold one pane capture into the per-session state machine and return
+ * the wire fields for this report cycle. Exported (with `paneText`
+ * injected) so tests can drive it without tmux.
+ *
+ * Hash short-circuit: an unchanged screen skips rule evaluation but
+ * still replays the previous observation through the debounce — cheap
+ * cycles stay cheap without wedging candidate promotion.
+ */
+const deriveSessionState = (name, agentKind, paneText, now = Date.now()) => {
+    if (paneText === null) {
+        // Pane unreadable this cycle (session racing shutdown, tmux
+        // hiccup) — report nothing rather than a stale confident state.
+        sessionStates.delete(name);
+        return {};
+    }
+    const contentHash = (0, crypto_1.createHash)('sha1').update(paneText).digest('hex');
+    const entry = sessionStates.get(name);
+    const observed = entry && entry.contentHash === contentHash
+        ? entry.lastObserved
+        : (0, agent_state_js_1.evaluateState)(paneText, agentKind, (0, agent_rules_fetch_js_1.getActiveManifest)(), entry?.tracker.confirmed ?? 'unknown');
+    const tracker = (0, agent_state_js_1.advanceState)(entry?.tracker, observed, now);
+    sessionStates.set(name, { tracker, lastObserved: observed, contentHash });
+    return {
+        state: tracker.confirmed,
+        stateChangedAt: new Date(tracker.confirmedAt).toISOString(),
+        stateRuleId: tracker.ruleId,
+    };
+};
+exports.deriveSessionState = deriveSessionState;
+/** Drop trackers for sessions gone from the inventory. */
+const pruneSessionStates = (liveNames) => {
+    for (const name of sessionStates.keys()) {
+        if (!liveNames.has(name))
+            sessionStates.delete(name);
+    }
+};
+let patternWatches = [];
+// One-shot: after a hit we stop re-evaluating that watch locally. The
+// server deletes the record on hit, and the next ack prunes it here —
+// the fired-set only bridges the gap between hit and ack.
+const firedWatchKeys = new Set();
+const patternWatchKey = (w) => `${w.sessionName}${w.pattern}`;
+/** Ack payload → active watch list. Prunes fired-markers for dead watches. */
+const setPatternWatches = (raw) => {
+    patternWatches = Array.isArray(raw)
+        ? raw.filter((w) => typeof w === 'object' && w !== null
+            && typeof w.sessionName === 'string'
+            && typeof w.pattern === 'string')
+        : [];
+    const live = new Set(patternWatches.map(patternWatchKey));
+    for (const key of firedWatchKeys) {
+        if (!live.has(key))
+            firedWatchKeys.delete(key);
+    }
+};
+exports.setPatternWatches = setPatternWatches;
+/** Test hook. */
+const resetPatternWatches = () => {
+    patternWatches = [];
+    firedWatchKeys.clear();
+};
+exports.resetPatternWatches = resetPatternWatches;
+/**
+ * Probe every un-fired watch whose session is live. `capture` is
+ * injectable for tests; production passes capturePaneText.
+ */
+const collectWatchHits = (liveNames, capture = capturePaneText) => {
+    const hits = [];
+    const textCache = new Map();
+    for (const w of patternWatches) {
+        if (!liveNames.has(w.sessionName))
+            continue;
+        const key = patternWatchKey(w);
+        if (firedWatchKeys.has(key))
+            continue;
+        if (!textCache.has(w.sessionName))
+            textCache.set(w.sessionName, capture(w.sessionName));
+        const text = textCache.get(w.sessionName);
+        if (text === null || text === undefined)
+            continue;
+        const match = (0, agent_state_js_1.findPatternMatch)(w.pattern, text);
+        if (!match)
+            continue;
+        firedWatchKeys.add(key);
+        hits.push({ sessionName: w.sessionName, pattern: w.pattern, matchedLine: match.line });
+    }
+    return hits;
+};
+exports.collectWatchHits = collectWatchHits;
+// ─── Screen peek (SPEC-AGENT-AWARENESS §S4) ────────────────────────
+// Pane lines returned to the phone. Taller than the state-detection
+// capture — the user wants to READ this, not regex it.
+const SCREEN_PEEK_LINES = 60;
+// Ephemeral frames ride API Gateway WS (32KB frame limit); stay well
+// under it after JSON envelope overhead.
+const SCREEN_PEEK_MAX_BYTES = 24 * 1024;
+/**
+ * Answer a phone's screen-peek request for one of OUR sessions.
+ * Returns null when the message isn't addressed to this machine (other
+ * ephemeral traffic — clipboard, mirrors — flows through constantly).
+ *
+ * Security posture: only sessions the inventory already exposes are
+ * readable — the phone can see exactly the panes it can already send
+ * commands into, nothing else. Rate-limited with the same per-session
+ * token bucket as command injection.
+ */
+const handleScreenRequest = (req) => {
+    if (req.subtype !== 'agent.screen.request')
+        return null;
+    if (!req.requestId || !req.sessionName)
+        return null;
+    if (req.targetDeviceId !== (0, exports.computeListenerDeviceId)())
+        return null;
+    const capturedAt = new Date().toISOString();
+    const base = { subtype: 'agent.screen.snapshot', requestId: req.requestId, sessionName: req.sessionName, capturedAt };
+    if (!(0, exports.checkRateLimit)(`screen:${req.sessionName}`)) {
+        return { ...base, error: 'rate_limited' };
+    }
+    if (!(0, exports.collectSessions)().some((s) => s.name === req.sessionName)) {
+        return { ...base, error: 'unknown_session' };
+    }
+    const r = (0, child_process_1.spawnSync)('tmux', tmuxArgs(['capture-pane', '-p', '-t', req.sessionName, '-S', `-${SCREEN_PEEK_LINES}`]), {
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (r.status !== 0) {
+        return { ...base, error: 'capture_failed' };
+    }
+    let content = r.stdout ?? '';
+    let truncated = false;
+    while (Buffer.byteLength(content, 'utf-8') > SCREEN_PEEK_MAX_BYTES) {
+        // Cut from the top — the bottom of the pane is what the user needs.
+        const cut = content.indexOf('\n', Math.floor(content.length / 8));
+        content = cut > 0 ? content.slice(cut + 1) : content.slice(-SCREEN_PEEK_MAX_BYTES);
+        truncated = true;
+    }
+    return { ...base, content, truncated };
+};
+exports.handleScreenRequest = handleScreenRequest;
 /**
  * Inventory pass that also records *why* each `zeph-*` session was
  * skipped. The verbose log uses the rejection notes to explain empty
@@ -530,8 +692,10 @@ const collectSessionsVerbose = () => {
             label: parsed.label,
             createdAt: epochToIso(created),
             lastActivityAt: epochToIso(activity),
+            ...(0, exports.deriveSessionState)(name, agent.kind, capturePaneText(name)),
         });
     }
+    pruneSessionStates(new Set(sessions.map((s) => s.name)));
     return { sessions, rejected };
 };
 exports.collectSessionsVerbose = collectSessionsVerbose;
@@ -822,11 +986,20 @@ const streamSession = (wsUrl, apiKey) => {
                 return;
             const { sessions, rejected } = (0, exports.collectSessionsVerbose)();
             sock.send(JSON.stringify({ type: 'listener.sessions', data: { sessions } }));
+            // Output-match watches (§S5 v2): probe watched panes and
+            // report hits. One-shot per watch; the server consumes the
+            // record and the next ack prunes it locally.
+            for (const hit of (0, exports.collectWatchHits)(new Set(sessions.map((s) => s.name)))) {
+                sock.send(JSON.stringify({ type: 'listener.watch.hit', data: hit }));
+                log(`🔔 watch hit: ${hit.sessionName} ~ /${hit.pattern}/`);
+            }
             // One line per cycle gives the user immediate feedback on
             // what the phone picker will see — particularly important
             // during setup, when an empty picker has no other observable
             // cause.
-            const names = sessions.map((s) => s.name).join(', ') || '∅';
+            const names = sessions
+                .map((s) => (s.state ? `${s.name}[${s.state}]` : s.name))
+                .join(', ') || '∅';
             log(`reported ${sessions.length} session(s): ${names}`);
             // Explain skipped zeph-* sessions so the most common
             // confusion (pane lost its claude start_command after a
@@ -916,6 +1089,15 @@ const streamSession = (wsUrl, apiKey) => {
                 // logged, never thrown into the socket handler.
                 void (0, exports.handlePush)(m.data).catch((err) => log(`! handlePush: ${err.message}`));
             }
+            if (m.type === 'ephemeral' && m.data) {
+                // Screen peek (§S4): the phone asks for this machine's live
+                // pane content over the ephemeral relay; the reply rides the
+                // same channel. Nothing is persisted server-side.
+                const reply = (0, exports.handleScreenRequest)(m.data);
+                if (reply && sock.readyState === ws_1.default.OPEN) {
+                    sock.send(JSON.stringify({ type: 'ephemeral', data: reply }));
+                }
+            }
             // Surface server-side errors from listener.sessions reports.
             // Without this the daemon happily logs "reported N session(s)"
             // even when the server is silently dropping every message —
@@ -926,6 +1108,8 @@ const streamSession = (wsUrl, apiKey) => {
             if (m.type === 'listener.sessions.ack') {
                 const d = m.data;
                 log(`✓ server persisted ${d?.count ?? '?'} session(s)`);
+                // Pattern watches ride the ack (§S5 v2) — refresh ours.
+                (0, exports.setPatternWatches)(d?.watches);
             }
             // `push.sync` (offline batch on $connect) and other types ignored.
         });
@@ -1050,6 +1234,17 @@ const handleListener = async (args) => {
     sweepAttachments();
     const gcTimer = setInterval(sweepAttachments, 60 * 60 * 1000);
     gcTimer.unref();
+    // Agent detection rules: disk cache immediately (offline-safe),
+    // then a background OTA refresh now and every 6 h (§S7).
+    (0, agent_rules_fetch_js_1.loadManifestFromCache)();
+    const refreshRules = () => {
+        void (0, agent_rules_fetch_js_1.refreshManifest)().then((r) => {
+            log(`rules: source=${r.source} outcome=${r.outcome}${r.version ? ` version=${r.version}` : ''}`);
+        });
+    };
+    refreshRules();
+    const rulesTimer = setInterval(refreshRules, agent_rules_fetch_js_1.RULES_REFRESH_INTERVAL_MS);
+    rulesTimer.unref();
     let shuttingDown = false;
     let activeHandle = null;
     const stop = (sig) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeph-to/cli",
-  "version": "1.14.0",
+  "version": "1.15.1",
   "description": "Zeph CLI + push notification SDK for AI agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",