@phnx-labs/agents-cli 1.22.53 → 1.22.55

package/dist/lib/help.js

@@ -7,6 +7,27 @@ const commandGroupRegistry = new WeakMap();
 export function registerCommandGroups(parent, groups) {
     commandGroupRegistry.set(parent, groups);
 }
+/**
+ * Front-door command groups shown on `agents --help`. Derived from measured
+ * reach: tier 1 = setup/run/sessions/view, tier 2 = teams/browser/secrets/
+ * devices/accounts/add. The remaining groups stay discoverable through the
+ * pointer rendered below these groups.
+ */
+export const FRONT_DOOR_COMMAND_GROUPS = [
+    {
+        title: 'Quick start',
+        names: ['setup', 'view', 'run', 'sessions'],
+    },
+    {
+        title: 'Most-used',
+        names: ['teams', 'browser', 'secrets', 'devices', 'accounts', 'add'],
+    },
+];
+const compactRootHelp = new WeakMap();
+/** Mark the root program so its help only renders front-door groups + a pointer. */
+export function setCompactRootHelp(program) {
+    compactRootHelp.set(program, true);
+}
 const helpSectionRegistry = new WeakMap();
 /**
  * Attach an Examples block (rendered between the description and Arguments)
@@ -136,7 +157,14 @@ function formatHelpCommandsFirst(cmd, helper) {
             output = output.concat([`${title}:`, formatList(subs.map(renderCommand)), '']);
         }
         const remaining = visibleCommands.filter((s) => !placed.has(s.name()));
-        if (remaining.length > 0) {
+        if (compactRootHelp.get(cmd)) {
+            output = output.concat([
+                'Commands:',
+                `  See "${cmd.name()} --help-all" for every command.`,
+                '',
+            ]);
+        }
+        else if (remaining.length > 0) {
             output = output.concat(['Commands:', formatList(remaining.map(renderCommand)), '']);
         }
     }

package/dist/lib/hosts/passthrough.d.ts

@@ -17,7 +17,7 @@
  * "not supported" message — never commander's raw `unknown option`.
  */
 import { type Host } from './types.js';
-import { type DeviceProfile, type DeviceRegistry } from '../devices/registry.js';
+import { type DeviceRegistry } from '../devices/registry.js';
 import { runLocalCommand, runOnDevice } from '../devices/fleet.js';
 /** Re-export for callers that historically imported flagValue from this module. */
 export { flagValue, hasHostRoutingFlag } from './routing-flag.js';
@@ -69,15 +69,6 @@ export interface FleetPassthroughOptions {
     /** Override this machine's id (tests). Defaults to `machineId()`. */
     self?: string;
 }
-/**
- * Prefix a fan-out remote command so the far side sees AGENTS_FLEET_REMOTE=1 —
- * the same marker the single-target dispatch sets via env. `wrapRemoteCommand`
- * joins the argv with spaces (POSIX) or base64-encodes it for PowerShell, so a
- * shell-appropriate leading token rides through both: `env VAR=1 …` on POSIX,
- * `$env:VAR='1'; …` on PowerShell. Only remote (non-self) targets get it; the
- * self target runs locally and must stay ungated.
- */
-export declare function markFleetRemote(cmd: string[], device: DeviceProfile): string[];
 /** Run `agents <command> …` across every registered device and render the roster. */
 export declare function runFleetPassthrough(command: string, allArgs: string[], spec: RemoteSpec, opts?: FleetPassthroughOptions): Promise<boolean>;
 /**

package/dist/lib/hosts/passthrough.js

@@ -32,6 +32,7 @@ import { isDeviceInteractive, resolveInteractiveDevice, interactiveUnsetError, }
 import { flagValue, hasHostRoutingFlag } from './routing-flag.js';
 import { loadDevices } from '../devices/registry.js';
 import { isSelfHost } from '../devices/self-host.js';
+import { markFleetRemote } from '../devices/connect.js';
 import { fanOutDevices, planFleetTargets, runLocalCommand, runOnDevice, } from '../devices/fleet.js';
 import { platformGroupLabel } from '../devices/health-report.js';
 import { isKnownTopLevelCommand } from '../startup/command-registry.js';
@@ -368,19 +369,6 @@ function renderFleetRoster(command, forwarded, results, self) {
         console.log(chalk.gray(summaryParts.join(' · ')));
     }
 }
-/**
- * Prefix a fan-out remote command so the far side sees AGENTS_FLEET_REMOTE=1 —
- * the same marker the single-target dispatch sets via env. `wrapRemoteCommand`
- * joins the argv with spaces (POSIX) or base64-encodes it for PowerShell, so a
- * shell-appropriate leading token rides through both: `env VAR=1 …` on POSIX,
- * `$env:VAR='1'; …` on PowerShell. Only remote (non-self) targets get it; the
- * self target runs locally and must stay ungated.
- */
-export function markFleetRemote(cmd, device) {
-    return device.shell === 'powershell'
-        ? [`$env:AGENTS_FLEET_REMOTE='1';`, ...cmd]
-        : ['env', 'AGENTS_FLEET_REMOTE=1', ...cmd];
-}
 /** Run `agents <command> …` across every registered device and render the roster. */
 export async function runFleetPassthrough(command, allArgs, spec, opts = {}) {
     const self = opts.self ?? machineId();

package/dist/lib/installations/versions.js

@@ -49,7 +49,7 @@ import { emit } from '../feed/events.js';
 import { safeJoin } from '../paths.js';
 import { readSkillSourceCommandMarker, shouldAlsoInstallCommandAsSkill, shouldInstallCommandAsSkill, } from '../command-skills.js';
 import { getWriter, getDetector } from '../staleness/registry.js';
-import { syncMemoryToVersionHome } from '../memory.js';
+import { syncMemoryToVersionHome, syncClaudeProjectMemoryDir } from '../memory.js';
 import { listPluginSkillNames, resolveCommandSource, resolveSkillSource } from '../staleness/writers/sources.js';
 import { syncProjectResourcesToAgent } from '../project-resources.js';
 import { installClaudeStatusLine } from '../claude-statusline.js';
@@ -2860,6 +2860,14 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     if (supports(agent, 'memory', version).ok) {
         syncMemoryToVersionHome(agent, versionHome, cwd);
     }
+    // Claude Code's own NATIVE per-project auto-memory (.claude/projects/<key>/memory/,
+    // PHNX-2817) is a separate, unmanaged directory Claude writes into itself — make it
+    // version-independent the same way project-level rules already are, via a shared
+    // symlink, so a note survives an agent version upgrade instead of vanishing into a
+    // fresh, empty version home.
+    if (agent === 'claude') {
+        syncClaudeProjectMemoryDir(versionHome, cwd);
+    }
     // Prune resources deleted from source (RUSH-2438). Runs only on a repo-scope
     // reconcile (`options.prune`) with a caller selection — a full sync
     // (`!userPassedSelection`) already sweeps orphans above, and an additive

package/dist/lib/linux-userns.d.ts

@@ -0,0 +1,58 @@
+/** Path of the AppArmor knob that gates unprivileged userns on Ubuntu 23.10+. */
+export declare const APPARMOR_USERNS_SYSCTL_PATH = "/proc/sys/kernel/apparmor_restrict_unprivileged_userns";
+export type UsernsState = 
+/** A new user namespace with a uid map can be created — Codex's sandbox works. */
+'ok'
+/** Unprivileged userns is restricted — Codex's bwrap sandbox cannot start. */
+ | 'blocked'
+/** Could not determine (non-Linux, or the probe could not run). */
+ | 'unknown';
+export interface UsernsStatus {
+    state: UsernsState;
+    /** One-line human reason, present when `blocked` or `unknown`. */
+    reason?: string;
+}
+/** The raw signals the pure interpreter reasons over. */
+export interface UsernsInputs {
+    platform: NodeJS.Platform;
+    /**
+     * Contents of {@link APPARMOR_USERNS_SYSCTL_PATH} trimmed, or null when the
+     * file is absent (older kernels / no AppArmor userns mediation).
+     */
+    apparmorRestrict: string | null;
+    /**
+     * Result of actually attempting to create a user namespace with a uid map:
+     *   - 'ok'      → the probe created the namespace and mapped root.
+     *   - 'denied'  → the kernel refused the uid_map write (the restricted case).
+     *   - 'no-tool' → the probe binary (`unshare`) was missing or failed to spawn.
+     */
+    unshareProbe: 'ok' | 'denied' | 'no-tool';
+}
+/**
+ * Decide userns availability from raw signals. Pure — no I/O.
+ *
+ * The definitive signal is the actual probe: if we successfully created a userns
+ * and wrote a uid map, the sandbox works regardless of the sysctl (an AppArmor
+ * profile may grant a specific binary `userns` even while the global knob is 1).
+ * A denied probe is a hard `blocked`. When the probe tool is missing we fall back
+ * to the sysctl: `1` → `blocked`, `0`/absent → `unknown` (we could not prove it,
+ * and refuse to claim `ok` we did not observe).
+ */
+export declare function interpretUsernsInputs(inputs: UsernsInputs): UsernsStatus;
+/** Read the AppArmor userns sysctl, or null when the file is absent. */
+export declare function readApparmorRestrict(sysctlPath?: string): string | null;
+/**
+ * Actually try to create a user namespace and map root inside it — the same
+ * operation bwrap performs (`unshare --user --map-root-user`). This is the ground
+ * truth: it observes exactly what the kernel/AppArmor policy permits for *this*
+ * process, rather than inferring from the sysctl alone.
+ */
+export declare function probeUnshare(): 'ok' | 'denied' | 'no-tool';
+/**
+ * Resolve whether an unprivileged user namespace can be created on this host,
+ * cached for the process (the answer is a stable property of the box). Non-Linux
+ * short-circuits to `ok` without spawning anything.
+ */
+export declare function probeUnprivilegedUserns(platform?: NodeJS.Platform): UsernsStatus;
+/** Test-only: drop the process cache so a test can re-probe. */
+export declare function resetUsernsCacheForTests(): void;

package/dist/lib/linux-userns.js

@@ -0,0 +1,116 @@
+/**
+ * Unprivileged user-namespace availability on Linux — the capability Codex's
+ * Linux sandbox needs, and the one Ubuntu 23.10+ restricts by default.
+ *
+ * Codex ≥0.146 implements its `read-only` and `workspace-write` sandbox modes on
+ * Linux with a bundled **bubblewrap** (`bwrap`), extracted per-run to
+ * `$CODEX_HOME/tmp/arg0/codex-XXXX/` and exec'd from a memfd. bwrap sets up its
+ * mounts inside a fresh **unprivileged user namespace** (`--unshare-user`, then a
+ * write to `/proc/self/uid_map`). Ubuntu 24.04 ships
+ * `kernel.apparmor_restrict_unprivileged_userns=1`, which denies that to an
+ * unconfined binary — so bwrap dies with `bwrap: setting up uid map: Permission
+ * denied` and a headless Codex run lands zero tools (no file writes, no shell).
+ * `danger-full-access` (our `skip` mode) drops the sandbox and is the only mode
+ * that avoids bwrap; the legacy Landlock backend is gone (`use_linux_sandbox_bwrap`
+ * is `removed`, `use_legacy_landlock` panics under the permission-profile model).
+ *
+ * This module is the single detector. It is pure at its core
+ * ({@link interpretUsernsInputs}) so the decision is unit-testable without a
+ * shell, and {@link probeUnprivilegedUserns} gathers the real inputs once per
+ * process. See PHNX-3285.
+ */
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+/** Path of the AppArmor knob that gates unprivileged userns on Ubuntu 23.10+. */
+export const APPARMOR_USERNS_SYSCTL_PATH = '/proc/sys/kernel/apparmor_restrict_unprivileged_userns';
+/**
+ * Decide userns availability from raw signals. Pure — no I/O.
+ *
+ * The definitive signal is the actual probe: if we successfully created a userns
+ * and wrote a uid map, the sandbox works regardless of the sysctl (an AppArmor
+ * profile may grant a specific binary `userns` even while the global knob is 1).
+ * A denied probe is a hard `blocked`. When the probe tool is missing we fall back
+ * to the sysctl: `1` → `blocked`, `0`/absent → `unknown` (we could not prove it,
+ * and refuse to claim `ok` we did not observe).
+ */
+export function interpretUsernsInputs(inputs) {
+    if (inputs.platform !== 'linux')
+        return { state: 'ok' };
+    if (inputs.unshareProbe === 'ok')
+        return { state: 'ok' };
+    if (inputs.unshareProbe === 'denied') {
+        const via = inputs.apparmorRestrict === '1'
+            ? ' (kernel.apparmor_restrict_unprivileged_userns=1)'
+            : '';
+        return {
+            state: 'blocked',
+            reason: `the kernel denied creating an unprivileged user namespace${via}`,
+        };
+    }
+    // Probe tool unavailable — lean on the AppArmor knob.
+    if (inputs.apparmorRestrict === '1') {
+        return {
+            state: 'blocked',
+            reason: 'unprivileged user namespaces are AppArmor-restricted ' +
+                '(kernel.apparmor_restrict_unprivileged_userns=1) and `unshare` was not available to confirm',
+        };
+    }
+    return {
+        state: 'unknown',
+        reason: '`unshare` was not available to probe user-namespace support',
+    };
+}
+/** Read the AppArmor userns sysctl, or null when the file is absent. */
+export function readApparmorRestrict(sysctlPath = APPARMOR_USERNS_SYSCTL_PATH) {
+    try {
+        return fs.readFileSync(sysctlPath, 'utf8').trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Actually try to create a user namespace and map root inside it — the same
+ * operation bwrap performs (`unshare --user --map-root-user`). This is the ground
+ * truth: it observes exactly what the kernel/AppArmor policy permits for *this*
+ * process, rather than inferring from the sysctl alone.
+ */
+export function probeUnshare() {
+    try {
+        execFileSync('unshare', ['--user', '--map-root-user', 'true'], {
+            stdio: 'ignore',
+            timeout: 5000,
+        });
+        return 'ok';
+    }
+    catch (err) {
+        // ENOENT / spawn failure → the tool isn't here; anything else (nonzero exit
+        // from the denied uid_map write) is the restricted case.
+        const code = err?.code;
+        if (code === 'ENOENT')
+            return 'no-tool';
+        return 'denied';
+    }
+}
+let cached = null;
+/**
+ * Resolve whether an unprivileged user namespace can be created on this host,
+ * cached for the process (the answer is a stable property of the box). Non-Linux
+ * short-circuits to `ok` without spawning anything.
+ */
+export function probeUnprivilegedUserns(platform = process.platform) {
+    if (platform !== 'linux')
+        return { state: 'ok' };
+    if (cached)
+        return cached;
+    cached = interpretUsernsInputs({
+        platform,
+        apparmorRestrict: readApparmorRestrict(),
+        unshareProbe: probeUnshare(),
+    });
+    return cached;
+}
+/** Test-only: drop the process cache so a test can re-probe. */
+export function resetUsernsCacheForTests() {
+    cached = null;
+}

package/dist/lib/memory.d.ts

@@ -53,3 +53,29 @@ export declare function rebuildMemoryIndex(dir: string): void;
 export declare function memoryTargetDir(agent: AgentId): string;
 /** Copy canonical layered memory into one version home. Returns fact names written. */
 export declare function syncMemoryToVersionHome(agent: AgentId, versionHome: string, cwd?: string): string[];
+/**
+ * Canonical shared dir for Claude Code's NATIVE per-project auto-memory —
+ * `<versionHome>/.claude/projects/<project-key>/memory/*.md`, the freeform
+ * notes Claude writes for itself during a session. Distinct from the layered
+ * `memory` resource above (~/.agents/memory/ facts synced into
+ * `.claude/memory/`): this dir is keyed by project (via
+ * {@link claudeProjectDirName}), not by agent version, and Claude Code itself
+ * decides what goes in it — agents-cli only makes the directory
+ * version-independent, never writes into it.
+ */
+export declare function getClaudeProjectMemoryDir(cwd: string): string;
+/**
+ * Make Claude Code's native per-project memory dir version-independent by
+ * symlinking `<versionHome>/.claude/projects/<project-key>/memory/` into the
+ * one canonical dir every installed Claude version's home shares for this
+ * project (PHNX-2817). Without this, `getVersionHomePath` gives every
+ * installed version its own isolated HOME, so a note written under one
+ * version is invisible under another — the directory is just empty there.
+ *
+ * Idempotent and safe to call on every sync: a dir already linked to the
+ * canonical target is left alone; a PRE-EXISTING real directory with content
+ * (the common case today, since this bug has always left one behind) has its
+ * files migrated into the canonical dir first — never discarded — before
+ * being replaced by the symlink.
+ */
+export declare function syncClaudeProjectMemoryDir(versionHome: string, cwd?: string): void;

package/dist/lib/memory.js

@@ -13,9 +13,10 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, ensureAgentsDir, } from './state.js';
+import { getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, ensureAgentsDir, getRuntimeStateDir, } from './state.js';
 import { agentConfigDirName } from './agents.js';
 import { supports } from './capabilities.js';
+import { claudeProjectDirName } from './project-key.js';
 /** User-layer memory root (~/.agents/memory/). */
 export function getUserMemoryDir() {
     return path.join(getUserAgentsDir(), 'memory');
@@ -273,3 +274,81 @@ export function syncMemoryToVersionHome(agent, versionHome, cwd = process.cwd())
     catch { /* best-effort */ }
     return written;
 }
+/**
+ * Canonical shared dir for Claude Code's NATIVE per-project auto-memory —
+ * `<versionHome>/.claude/projects/<project-key>/memory/*.md`, the freeform
+ * notes Claude writes for itself during a session. Distinct from the layered
+ * `memory` resource above (~/.agents/memory/ facts synced into
+ * `.claude/memory/`): this dir is keyed by project (via
+ * {@link claudeProjectDirName}), not by agent version, and Claude Code itself
+ * decides what goes in it — agents-cli only makes the directory
+ * version-independent, never writes into it.
+ */
+export function getClaudeProjectMemoryDir(cwd) {
+    const projectKey = claudeProjectDirName(path.resolve(cwd));
+    return path.join(getRuntimeStateDir(), 'claude-project-memory', projectKey);
+}
+/**
+ * Make Claude Code's native per-project memory dir version-independent by
+ * symlinking `<versionHome>/.claude/projects/<project-key>/memory/` into the
+ * one canonical dir every installed Claude version's home shares for this
+ * project (PHNX-2817). Without this, `getVersionHomePath` gives every
+ * installed version its own isolated HOME, so a note written under one
+ * version is invisible under another — the directory is just empty there.
+ *
+ * Idempotent and safe to call on every sync: a dir already linked to the
+ * canonical target is left alone; a PRE-EXISTING real directory with content
+ * (the common case today, since this bug has always left one behind) has its
+ * files migrated into the canonical dir first — never discarded — before
+ * being replaced by the symlink.
+ */
+export function syncClaudeProjectMemoryDir(versionHome, cwd = process.cwd()) {
+    const projectKey = claudeProjectDirName(path.resolve(cwd));
+    const canonicalDir = path.join(getRuntimeStateDir(), 'claude-project-memory', projectKey);
+    const projectDir = path.join(versionHome, agentConfigDirName('claude'), 'projects', projectKey);
+    const nativeMemoryDir = path.join(projectDir, 'memory');
+    fs.mkdirSync(canonicalDir, { recursive: true, mode: 0o700 });
+    let existing;
+    try {
+        existing = fs.lstatSync(nativeMemoryDir);
+    }
+    catch { /* nothing there yet */ }
+    if (existing?.isSymbolicLink()) {
+        let currentTarget;
+        try {
+            currentTarget = fs.readlinkSync(nativeMemoryDir);
+        }
+        catch { /* dangling link */ }
+        if (currentTarget === canonicalDir)
+            return; // already wired correctly
+        fs.unlinkSync(nativeMemoryDir); // stale/foreign link — replace below
+    }
+    else if (existing?.isDirectory()) {
+        // Migrate first (never clobber content already promoted to canonical by
+        // an earlier-synced version home), then remove the now-redundant copy.
+        fs.cpSync(nativeMemoryDir, canonicalDir, { recursive: true, force: false, errorOnExist: false });
+        fs.rmSync(nativeMemoryDir, { recursive: true, force: true });
+    }
+    else if (existing) {
+        return; // an unexpected file at this path — leave it alone rather than destroy it
+    }
+    fs.mkdirSync(projectDir, { recursive: true });
+    try {
+        fs.symlinkSync(canonicalDir, nativeMemoryDir, process.platform === 'win32' ? 'junction' : undefined);
+    }
+    catch (err) {
+        // A concurrent sync (e.g. two `agents run claude` launches racing on a
+        // first-ever project) can win this exact link between our lstat above
+        // and this call. If it landed the same canonical target, that's the
+        // outcome we wanted — treat it as success rather than throwing.
+        if (err?.code !== 'EEXIST')
+            throw err;
+        let racedTarget;
+        try {
+            racedTarget = fs.readlinkSync(nativeMemoryDir);
+        }
+        catch { /* not even a symlink — fall through to rethrow */ }
+        if (racedTarget !== canonicalDir)
+            throw err;
+    }
+}

package/dist/lib/monitors/config.d.ts

@@ -84,6 +84,17 @@ export interface ActionConfig {
     notifyChannel?: string;
     /** webhook-out: URL to POST the event to. */
     url?: string;
+    /**
+     * Shell command that must exit 0 after a `run`/`routine` action settles.
+     * Asserts the stated effect actually happened (PHNX-2842) — e.g.
+     * `gh pr view 1682 --json state --jq .state | grep -qx MERGED`. `{event}` is
+     * replaced with the fired event summary, same as the prompt. Evaluated once
+     * the dispatched run is no longer `running`; a failed check makes the fire
+     * `ok: false` with effect `none` (`postcondition not met`), not a healthy
+     * `completed`. Notify/webhook-out already have a synchronous ok and refuse
+     * this field.
+     */
+    postcondition?: string;
 }
 /** Full monitor configuration (persisted as YAML in ~/.agents/monitors/). */
 export interface MonitorConfig {

package/dist/lib/monitors/config.js

@@ -238,6 +238,14 @@ export function validateMonitor(config) {
                 errors.push(`action.url must be an absolute URL (got ${JSON.stringify(action.url)})`);
             }
         }
+        if (action.postcondition !== undefined) {
+            if (action.type !== 'run' && action.type !== 'routine') {
+                errors.push("action.postcondition only applies to run or routine actions");
+            }
+            else if (typeof action.postcondition !== 'string' || action.postcondition.trim() === '') {
+                errors.push('action.postcondition must be a non-empty shell command');
+            }
+        }
     }
     // ─── PLACEMENT ───────────────────────────────────────────────────────────────
     if (config.device !== undefined && config.devices !== undefined) {

package/dist/lib/monitors/engine.d.ts

@@ -13,6 +13,8 @@
  */
 import { type MonitorConfig, type MonitorEvent } from './config.js';
 import { type Observation } from './sources/index.js';
+/** How often the engine wakes to check which monitors are due. */
+export declare const MONITOR_ENGINE_TICK_MS = 5000;
 /** Poll-model source types the engine actually evaluates on a cadence; ws/webhook are push-only and inert here. */
 export declare const POLL_SOURCE_TYPES: Set<string>;
 /**
@@ -58,7 +60,9 @@ export declare class MonitorEngine {
     private ticking;
     constructor(logFn?: LogFn);
     /** Load owned+enabled monitors and start the tick loop. */
-    start(): void;
+    start(options?: {
+        externalScheduler?: boolean;
+    }): void;
     /** Reload monitor configs (SIGHUP). */
     reload(): void;
     /** Stop the tick loop. */

package/dist/lib/monitors/engine.js

@@ -14,11 +14,11 @@
 import { listMonitors, monitorRunsOnThisDevice, parseInterval, setMonitorEnabled, } from './config.js';
 import { evaluateSource } from './sources/index.js';
 import { hasChanged, readState, writeState, recordFireTime, writeFireRecord, recordCheck, markDroughtNotified, } from './state.js';
-import { dispatchAction } from './dispatch.js';
+import { dispatchAction, injectEvent } from './dispatch.js';
 import { sendToOwner } from '../notify.js';
 import { readRunMeta } from '../scheduling/routines.js';
 /** How often the engine wakes to check which monitors are due. */
-const TICK_MS = 5_000;
+export const MONITOR_ENGINE_TICK_MS = 5_000;
 /** Default evaluation cadence for sources that carry no explicit interval. */
 const DEFAULT_INTERVAL_MS = 60_000;
 /**
@@ -126,10 +126,12 @@ export class MonitorEngine {
         this.logFn = logFn;
     }
     /** Load owned+enabled monitors and start the tick loop. */
-    start() {
+    start(options = {}) {
         this.loadAll();
         this.logFn('INFO', `Monitor engine started (${this.monitors.length} monitor(s) on this device)`);
-        this.timer = setInterval(() => void this.tick(), TICK_MS);
+        if (!options.externalScheduler) {
+            this.timer = setInterval(() => void this.tick(), MONITOR_ENGINE_TICK_MS);
+        }
     }
     /** Reload monitor configs (SIGHUP). */
     reload() {
@@ -282,12 +284,19 @@ export class MonitorEngine {
         // exactly the fires whose `ok` needs revisiting; `resolveFireOutcome`
         // (state.ts) never trusts this field — it re-reads the run fresh instead.
         const runStatusAtFire = result.runId ? readRunMeta(monitor.name, result.runId)?.status : undefined;
+        // Snapshot the postcondition with `{event}` already interpolated so a later
+        // `resolveFireOutcome` can assert the stated effect without re-reading YAML
+        // (PHNX-2842). Notify/webhook-out have no run to settle, so they skip this.
+        const postcondition = (result.kind === 'run' || result.kind === 'routine') && monitor.action.postcondition
+            ? injectEvent(monitor.action.postcondition, event)
+            : undefined;
         writeFireRecord(event, {
             ...(result.runId ? { runId: result.runId } : {}),
             action: result.kind,
             ok: result.ok,
             ...(result.error ? { error: result.error } : {}),
             ...(runStatusAtFire ? { runStatusAtFire } : {}),
+            ...(postcondition ? { postcondition } : {}),
         });
         writeState(monitor.name, decision.value, decision.dedupeKey, { lastFiredAt: event.firedAt, fireTimes });
         this.logFn(result.ok ? 'INFO' : 'ERROR', `monitor '${monitor.name}' fired → ${result.kind}` +

package/dist/lib/monitors/state.d.ts

@@ -118,6 +118,16 @@ export interface FireRecord extends MonitorEvent {
      * run fresh on every call instead of trusting this snapshot.
      */
     runStatusAtFire?: RunMeta['status'];
+    /**
+     * The action's postcondition command, snapshotted at fire time with `{event}`
+     * already interpolated (PHNX-2842). `resolveFireOutcome` runs this once the
+     * dispatched run has settled `completed`.
+     */
+    postcondition?: string;
+    /** Result of the postcondition check, persisted after the first evaluation. */
+    postconditionOk?: boolean;
+    /** stderr/stdout snippet when `postconditionOk` is false. */
+    postconditionError?: string;
 }
 /** List a monitor's fire history, chronologically ascending. */
 export declare function listFires(name: string): FireRecord[];
@@ -127,10 +137,28 @@ export interface ReconciledFireOutcome {
     ok: boolean;
     /** The run's live terminal status, when a runId is present and resolvable. */
     runStatus?: RunMeta['status'];
+    /**
+     * Present when a `completed` run had a postcondition to assert (PHNX-2842).
+     * `met` = the command exited 0; `none` = ran but the intended effect did not
+     * happen (the fire must not read as `ok`).
+     */
+    effect?: 'met' | 'none';
+    /** Why the fire is not ok, when the postcondition failed. */
+    error?: string;
 }
+/**
+ * Run a fire's postcondition command. Exit 0 means the intended effect happened;
+ * anything else (nonzero, timeout, spawn error, empty command) is "no effect".
+ * Real `/bin/sh -c` (or `cmd /c`) — the same seam command sources use.
+ */
+export declare function evaluatePostcondition(command: string): {
+    ok: boolean;
+    error?: string;
+};
 /**
  * Reconcile a fire's frozen `ok` against its dispatched run's REAL, current
- * status — the render-time fix for RUSH-2690.
+ * status — the render-time fix for RUSH-2690 — and, when the run has settled
+ * `completed`, against a declared postcondition (PHNX-2842).
  *
  * `writeFireRecord` (this module) persists `ok` once, at fire time, from
  * `dispatchAction`'s synchronous return. For a `run`/`routine` action that
@@ -146,5 +174,13 @@ export interface ReconciledFireOutcome {
  * A fire with no `runId` (a `notify`/`webhook-out` action, or a `run`/`routine`
  * dispatch that never got a runId at all) has nothing to reconcile against —
  * its frozen `ok` is the only signal and is returned as-is.
+ *
+ * `completed` is not success by itself. An agent that exits 0 without doing
+ * the job (merge-on-green that never merged) used to record `ok` because
+ * `OK_RUN_STATUSES` treated `completed` as healthy. When the fire carries a
+ * `postcondition` command, this function runs it once the run has settled and
+ * returns `ok: false, effect: 'none'` when it fails — distinguishing "ran but
+ * no effect" from a working fire. The result is persisted on the fire record
+ * so later listings do not re-exec the command.
  */
 export declare function resolveFireOutcome(jobName: string, fire: FireRecord): ReconciledFireOutcome;