@phnx-labs/agents-cli 1.20.88 → 1.20.89

package/dist/lib/menubar/install-menubar.js

@@ -19,6 +19,7 @@ import { execFileSync, spawnSync } from 'child_process';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+import { sleepSync } from '../fs-atomic.js';
 import { getRuntimeStateDir, getHelpersDir } from '../state.js';
 import { getCliVersion, resolveAgentsBin, resolveInstalledLayout } from '../version.js';
 const APP_BUNDLE_NAME = 'MenubarHelper.app';
@@ -149,6 +150,27 @@ function copyAppBundle(src, dest) {
         throw new Error(`Failed to copy ${src} -> ${dest}: ${msg || 'unknown error'}`);
     }
 }
+/**
+ * Register the freshly-installed bundle with LaunchServices.
+ *
+ * The helper is copied to ~/Library/Application Support (not /Applications) and
+ * launched only via launchd, so LaunchServices may never discover it on its own.
+ * A daemon notification posted by the one-shot `MenubarHelper --notify` process is
+ * attributed to this bundle, and macOS resolves the notification's LEFT-hand app
+ * icon from the bundle's LaunchServices record — so a bundle LS doesn't know about
+ * shows a blank app icon there (the right-hand contentImage is unaffected;
+ * appIconImage reads the `.icns` directly). `lsregister -f` registers the bundle at
+ * its current path so the OS can resolve its AppIcon for that slot. Best-effort:
+ * LaunchServices is advisory, and a failure here must never block install.
+ */
+function refreshBundleIconRegistration(appPath) {
+    const lsregister = '/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister';
+    const bin = fs.existsSync(lsregister) ? lsregister : 'lsregister';
+    const r = spawnSync(bin, ['-f', appPath], { stdio: ['ignore', 'ignore', 'ignore'] });
+    if (r.error) {
+        /* lsregister missing / moved — advisory only, ignore. */
+    }
+}
 /** True when the bundle carries a signature the kernel will accept at launch. */
 export function codesignVerifies(appPath) {
     const r = spawnSync('codesign', ['--verify', '--strict', appPath], { stdio: ['ignore', 'ignore', 'ignore'] });
@@ -200,6 +222,10 @@ export function ensureMenubarAppInstalled(opts = {}) {
     }
     copyAppBundle(src, dest);
     ensureValidSignature(dest);
+    // A fresh copy is exactly when the bundle's icon can be new (first install) or
+    // superseded (upgrade) — register it so LaunchServices knows the bundle and can
+    // resolve its AppIcon for the left-hand slot of daemon notifications.
+    refreshBundleIconRegistration(dest);
     return installedExecutablePath();
 }
 function xmlEscape(s) {
@@ -299,24 +325,34 @@ export function enableMenubarService(opts = { clearOptOut: true }) {
         process.stderr.write('agents: menu-bar helper has no valid code signature; skipping launch to avoid a crash loop.\n');
         return false;
     }
-    if (opts.clearOptOut) {
-        try {
-            fs.rmSync(disabledSentinelPath(), { force: true });
-        }
-        catch { /* already gone */ }
+    if (opts.clearOptOut)
+        clearMenubarOptOut();
+    installAndStartService(exec);
+    return true;
+}
+/** Drop the sticky `agents menubar disable` sentinel. */
+function clearMenubarOptOut() {
+    try {
+        fs.rmSync(disabledSentinelPath(), { force: true });
     }
+    catch { /* already gone */ }
+}
+/**
+ * Write the launchd plist for `exec`, restart the job, and stamp the installed
+ * version. Shared by `enableMenubarService` and `runMenubarSetup` so the two
+ * cannot drift on what "installed and started" means — the version stamp in
+ * particular is what the upgrade self-heal reads to decide staleness, and a
+ * path that skipped it would make every later `agents` invocation reinstall.
+ */
+function installAndStartService(exec) {
     const plist = servicePlistPath();
     fs.mkdirSync(path.dirname(plist), { recursive: true });
     fs.writeFileSync(plist, generateServicePlist(exec));
-    const uid = process.getuid?.() ?? 0;
-    restartMenubarLaunchAgent(uid, plist);
-    // Stamp the version we just installed so the upgrade self-heal can tell when
-    // a later release ships a newer helper that needs reinstalling.
+    restartMenubarLaunchAgent(process.getuid?.() ?? 0, plist);
     try {
         fs.writeFileSync(installedVersionMarkerPath(), getCliVersion());
     }
     catch { /* best effort */ }
-    return true;
 }
 /**
  * Pure staleness decision (no I/O) so the truth table is unit-testable. The
@@ -441,6 +477,117 @@ export function installMenubarLaunchAgentOnUpgrade() {
         /* never block startup on the menu bar */
     }
 }
+/**
+ * Decide which live helper processes must be ended so exactly one status item
+ * survives. Pure so the choice is unit-testable without a live menu bar.
+ *
+ * EVERY current process is ended, including the wanted one: the caller
+ * re-kickstarts the launchd service straight after, so the survivor is the one
+ * launchd owns (RunAtLoad + KeepAlive), not whichever copy happened to win a
+ * race. Picking a survivor from a `ps` listing cannot do this — the list says
+ * nothing about which pid launchd will keep alive, so leaving one alive risks
+ * keeping the un-managed copy and re-creating the duplicate on next login.
+ */
+export function processesToEnd(status) {
+    return [...status.instances, ...status.foreignInstances];
+}
+function endProcess(pid) {
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch { /* already gone */ }
+}
+/**
+ * `agents menubar setup` — configure the menu bar end-to-end, idempotently.
+ *
+ * The one command that gets a machine to the intended state: exactly one status
+ * item, owned by a launchd service that starts it at login and restarts it if it
+ * dies. Each concern is a reported step, so a partial failure names itself
+ * instead of hiding behind "enabled".
+ *
+ *   1. bundle      — install/refresh the .app at the stable App Support path
+ *   2. signature   — a valid code identity (macOS 26+ SIGKILLs an invalid one)
+ *   3. duplicates  — end every live helper, so the only survivor is launchd's
+ *   4. login item  — write the plist (RunAtLoad + KeepAlive) and bootstrap it
+ *   5. single      — verify exactly one helper came back up
+ */
+export function runMenubarSetup() {
+    const steps = [];
+    const step = (name, outcome, detail) => {
+        steps.push({ name, outcome, detail });
+    };
+    if (!onDarwin()) {
+        step('platform', 'failed', `the menu bar helper is macOS only (this is ${process.platform})`);
+        return { steps, configured: false, status: getMenubarStatus() };
+    }
+    const before = getMenubarStatus();
+    if (!sourceAppPath()) {
+        step('bundle', 'failed', 'no menu-bar helper bundle ships with this install');
+        return { steps, configured: false, status: before };
+    }
+    // 3 before 1: end the running copies BEFORE swapping the bundle underneath
+    // them, so no helper keeps a status item alive on a binary that no longer
+    // exists on disk.
+    const doomed = processesToEnd(before);
+    for (const p of doomed)
+        endProcess(p.pid);
+    if (doomed.length > 1) {
+        step('duplicates', 'changed', `ended ${doomed.length} running helpers (${doomed.map((p) => p.pid).join(', ')}) — launchd restarts exactly one`);
+    }
+    else if (doomed.length === 1) {
+        step('duplicates', 'ok', 'one helper was running; restarting it under launchd');
+    }
+    else {
+        step('duplicates', 'ok', 'no helper was running');
+    }
+    const exec = ensureMenubarAppInstalled({ forceReinstall: true });
+    if (!exec) {
+        step('bundle', 'failed', 'could not install the helper bundle');
+        return { steps, configured: false, status: getMenubarStatus() };
+    }
+    step('bundle', before.installedVersion === getCliVersion() ? 'ok' : 'changed', `${installedAppPath()} (${getCliVersion()})`);
+    if (!codesignVerifies(installedAppPath())) {
+        step('signature', 'failed', 'no valid code signature — refusing to start it (launchd KeepAlive would crash-loop)');
+        return { steps, configured: false, status: getMenubarStatus() };
+    }
+    step('signature', 'ok', 'valid');
+    // Clear the sticky opt-out: running `setup` is an explicit request for the
+    // menu bar, so a stale `menubar disable` must not silently win.
+    clearMenubarOptOut();
+    installAndStartService(exec);
+    step('login item', before.serviceInstalled ? 'ok' : 'changed', `${SERVICE_LABEL} — starts at login, restarts if it dies`);
+    // launchd's bootstrap+kickstart is asynchronous; give the status item a beat
+    // to claim the lock before counting instances, or `setup` reports zero on a
+    // machine that is in fact coming up correctly.
+    const after = waitForSingleInstance();
+    if (after.instances.length === 1 && after.foreignInstances.length === 0) {
+        step('single instance', 'ok', `pid ${after.instances[0].pid}`);
+    }
+    else if (after.instances.length === 0) {
+        step('single instance', 'failed', 'the helper did not come back up — see `agents menubar status`');
+    }
+    else {
+        const extra = [...after.instances.slice(1), ...after.foreignInstances];
+        step('single instance', 'failed', `${after.instances.length + after.foreignInstances.length} helpers running (${extra.map((p) => p.pid).join(', ')} are extra)`);
+    }
+    return {
+        steps,
+        configured: steps.every((s) => s.outcome !== 'failed'),
+        status: after,
+    };
+}
+/**
+ * Poll (up to ~3s) for launchd to bring the single helper back. Returns the
+ * last status read either way — the caller decides what a miss means.
+ */
+function waitForSingleInstance() {
+    let status = getMenubarStatus();
+    for (let i = 0; i < 15 && status.instances.length !== 1; i++) {
+        sleepSync(200);
+        status = getMenubarStatus();
+    }
+    return status;
+}
 /** Parse `ps -axo pid=,<field>=` into pid -> field. The field is the rest of the
  *  line, so a path containing spaces (App Support does) survives intact. */
 function parsePsLines(psOutput) {
@@ -454,21 +601,28 @@ function parsePsLines(psOutput) {
 }
 /**
  * Split the live MenubarHelper processes into the installed bundle's own
- * (`running`) and every other copy (`foreign`).
+ * (`own`) and every other copy (`foreign`).
  *
  * `pgrep -f MenubarHelper` conflated the two, so a stray dev build could hold
  * the global Cmd-Shift-V chord (RegisterEventHotKey is first-come) while status
  * still reported a healthy `running: yes` — the paste was dead and nothing said
  * so. A foreign copy is the thing to look for, so name it.
  *
+ * `own` is a LIST, not a boolean: two copies of the INSTALLED bundle can run at
+ * once (launchd's KeepAlive service plus a LaunchServices/`open` launch of the
+ * same .app), which is the duplicate the user actually sees — two agents marks
+ * in the menu bar. Collapsing them to `running: true` reported that state as
+ * healthy. The helper now refuses to be the second (SingleInstance.swift), and
+ * `agents menubar setup` ends any duplicate a pre-fix helper left behind.
+ *
  * Identity comes from `comm` (the resolved executable), never from a substring
  * of the command line: matching the latter flags any shell that merely mentions
  * MenubarHelper. `command` is consulted only to drop `--notify` one-shots.
  */
 export function classifyMenubarProcesses(commOutput, commandOutput, installedExec) {
     const commands = parsePsLines(commandOutput);
+    const own = [];
     const foreign = [];
-    let running = false;
     for (const [pid, executable] of parsePsLines(commOutput)) {
         if (path.basename(executable) !== 'MenubarHelper')
             continue;
@@ -477,26 +631,26 @@ export function classifyMenubarProcesses(commOutput, commandOutput, installedExe
         if ((commands.get(pid) || '').includes('--notify'))
             continue;
         if (executable === installedExec)
-            running = true;
+            own.push({ pid, executable });
         else
             foreign.push({ pid, executable });
     }
-    return { running, foreign };
+    return { own, foreign };
+}
+/** Live MenubarHelper processes, split by whether they are the installed bundle. */
+function liveMenubarProcesses() {
+    if (!onDarwin())
+        return { own: [], foreign: [] };
+    const ps = (format) => spawnSync('ps', ['-axo', format], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8' });
+    const comm = ps('pid=,comm=');
+    const command = ps('pid=,command=');
+    if (comm.status !== 0 || command.status !== 0)
+        return { own: [], foreign: [] };
+    return classifyMenubarProcesses(comm.stdout || '', command.stdout || '', installedExecutablePath());
 }
 export function getMenubarStatus() {
     const dest = installedAppPath();
-    let running = false;
-    let foreignInstances = [];
-    if (onDarwin()) {
-        const ps = (format) => spawnSync('ps', ['-axo', format], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8' });
-        const comm = ps('pid=,comm=');
-        const command = ps('pid=,command=');
-        if (comm.status === 0 && command.status === 0) {
-            const c = classifyMenubarProcesses(comm.stdout || '', command.stdout || '', installedExecutablePath());
-            running = c.running;
-            foreignInstances = c.foreign;
-        }
-    }
+    const { own, foreign } = liveMenubarProcesses();
     const serviceInstalled = menubarServiceInstalled();
     return {
         platform: process.platform,
@@ -506,8 +660,9 @@ export function getMenubarStatus() {
         currentVersion: getCliVersion(),
         stale: onDarwin() && serviceInstalled && menubarSetupStale(),
         serviceInstalled,
-        running,
-        foreignInstances,
+        running: own.length > 0,
+        instances: own,
+        foreignInstances: foreign,
         disabledByUser: menubarDisabledByUser(),
     };
 }

package/dist/lib/platform/process.d.ts

@@ -34,9 +34,11 @@ export declare function killTree(pid: number): void;
  *   sites pass their own `windowsHide` with piped stdio.
  */
 export declare function backgroundSpawnOptions(opts?: {
+    cwd?: string;
     fdStdio?: boolean;
     platform?: NodeJS.Platform;
 }): {
+    cwd: string;
     detached: boolean;
     windowsHide: boolean;
 };

package/dist/lib/platform/process.js

@@ -3,6 +3,7 @@
  */
 import { execFileSync } from 'child_process';
 import { readFileSync } from 'fs';
+import * as os from 'os';
 import { sleepSync } from '../fs-atomic.js';
 /**
  * Forcefully terminate a process AND its descendant tree.
@@ -56,12 +57,13 @@ export function killTree(pid) {
  */
 export function backgroundSpawnOptions(opts = {}) {
     const platform = opts.platform ?? process.platform;
+    const cwd = opts.cwd ?? os.homedir();
     if (platform === 'win32') {
         return opts.fdStdio
-            ? { detached: true, windowsHide: true }
-            : { detached: false, windowsHide: true };
+            ? { cwd, detached: true, windowsHide: true }
+            : { cwd, detached: false, windowsHide: true };
     }
-    return { detached: true, windowsHide: false };
+    return { cwd, detached: true, windowsHide: false };
 }
 /**
  * Is a process with this PID currently alive?

package/dist/lib/resources.d.ts

@@ -17,6 +17,14 @@ export interface ResolvedResource {
      */
     source: string;
 }
+/**
+ * True when `rawName` (a filename with its extension already stripped) names a
+ * directory doc rather than a resource of `kind`. Exported so every enumerator
+ * shares one definition — `listCentralCommands` and `discoverCommands` in
+ * `commands.ts` do their own `readdirSync` scans, and without this they would
+ * list a `README` that `resolveResource` then refuses to open.
+ */
+export declare function isDirectoryDoc(kind: ResourceKind, rawName: string): boolean;
 /**
  * Resolve a single resource by kind + name using project > user > system precedence.
  * For file-based resources the path ends in `.md`, `.yaml`, or `.yml` as appropriate.

package/dist/lib/resources.js

@@ -35,6 +35,30 @@ function resourceIsActive(kind, name, source) {
     const activeKind = profiledKind(kind);
     return activeKind ? isNameActiveInResourceProfile(activeKind, name, source) : true;
 }
+/**
+ * Documentation filenames that live *beside* resources, describing the directory
+ * rather than being a resource in it. A DotAgents repo keeps a `README.md` (for
+ * humans) and an `AGENTS.md` (for agents) in each resource dir, with
+ * `CLAUDE.md`/`GEMINI.md` symlinked to the latter. Without this filter every one
+ * of them materializes as a resource — `commands/README.md` installs a bogus
+ * `/README` slash command into every agent home.
+ *
+ * `rules` is exempt: there `AGENTS.md` IS the resource (the composed ruleset that
+ * syncs as each agent's memory file), not documentation about the directory.
+ */
+const DOC_BASENAMES = new Set(['readme', 'agents', 'claude', 'gemini']);
+/**
+ * True when `rawName` (a filename with its extension already stripped) names a
+ * directory doc rather than a resource of `kind`. Exported so every enumerator
+ * shares one definition — `listCentralCommands` and `discoverCommands` in
+ * `commands.ts` do their own `readdirSync` scans, and without this they would
+ * list a `README` that `resolveResource` then refuses to open.
+ */
+export function isDirectoryDoc(kind, rawName) {
+    if (kind === 'rules')
+        return false;
+    return DOC_BASENAMES.has(rawName.toLowerCase());
+}
 /**
  * Resolve a single resource by kind + name using project > user > system precedence.
  * For file-based resources the path ends in `.md`, `.yaml`, or `.yml` as appropriate.
@@ -62,7 +86,10 @@ export function resolveResource(kind, name, cwd) {
             }
             continue;
         }
-        // Try with common file extensions
+        // Try with common file extensions. A directory doc (README/AGENTS/CLAUDE/
+        // GEMINI) describes the directory and is never itself a resource.
+        if (isDirectoryDoc(kind, name))
+            continue;
         for (const ext of ['.md', '.yaml', '.yml']) {
             const withExt = exactPath + ext;
             if (fs.existsSync(withExt)) {
@@ -105,6 +132,12 @@ export function listResources(kind, cwd) {
             if (entry.name.startsWith('.'))
                 continue;
             const rawName = entry.name.replace(/\.(md|yaml|yml)$/, '');
+            // Not isFile(): a Dirent for a symlink reports isFile() === false, and
+            // CLAUDE.md/GEMINI.md are symlinks to AGENTS.md by convention. Anything
+            // that is not a directory is a candidate doc; a resource directory that
+            // happens to be named `agents/` is still a real resource.
+            if (!entry.isDirectory() && isDirectoryDoc(kind, rawName))
+                continue;
             if (seen.has(rawName))
                 continue;
             if (!resourceIsActive(kind, rawName, source))

package/dist/lib/routines-placement.d.ts

@@ -10,6 +10,7 @@
  * pin for fleet/host/cloud strategies (applied at add/sync time).
  */
 import type { JobConfig } from './routines.js';
+import { type DevicePlatform } from './devices/registry.js';
 export type PlacementTarget = {
     mode: 'local';
 } | {
@@ -30,7 +31,7 @@ export type PlacementTarget = {
  * the double-fire pin (`devices: [self]`) would collapse fleet placement to
  * always-local. Control / offline / no-address devices are never chosen.
  */
-export declare function pickFleetDevice(_config?: Pick<JobConfig, 'devices'>): string | null;
+export declare function pickFleetDevice(_config?: Pick<JobConfig, 'devices'>, platform?: DevicePlatform): string | null;
 /**
  * Resolve where a fired job's body should execute.
  * Throws a human-readable Error when placement cannot be satisfied.

package/dist/lib/routines-placement.js

@@ -25,7 +25,7 @@ import { planFleetTargets } from './devices/fleet.js';
  * the double-fire pin (`devices: [self]`) would collapse fleet placement to
  * always-local. Control / offline / no-address devices are never chosen.
  */
-export function pickFleetDevice(_config) {
+export function pickFleetDevice(_config, platform) {
     let reg;
     try {
         reg = loadDevicesSync();
@@ -34,11 +34,15 @@ export function pickFleetDevice(_config) {
         return null;
     }
     const planned = planFleetTargets(reg);
-    const candidates = planned.filter((t) => !t.skip).map((t) => t.device.name);
+    const candidates = planned
+        .filter((t) => !t.skip && (!platform || t.device.platform === platform))
+        .map((t) => t.device.name);
     if (candidates.length === 0) {
         // No registry / nothing online: fall back to self so a single-box fleet
-        // without a registry entry still runs locally.
-        return machineId();
+        // without a registry entry still runs locally. Only when no platform filter
+        // was requested — an unmet filter must fail loud so e.g. `fleet/linux` never
+        // silently lands on a macOS box.
+        return platform ? null : machineId();
     }
     const self = machineId();
     const selfMatch = candidates.find((n) => normalizeHost(n) === self);

package/dist/lib/routines.d.ts

@@ -78,6 +78,10 @@ export interface LinearJobTrigger {
     teamKey?: string;
     /** Required issue label name. */
     label?: string;
+    /** Current Linear state name that must match (e.g. `Plan`). */
+    stateTo?: string;
+    /** Previous Linear state name that must match (e.g. `Triage`). */
+    stateFrom?: string;
 }
 export type JobTrigger = GithubJobTrigger | LinearJobTrigger;
 /**
@@ -118,6 +122,12 @@ export interface JobConfig {
      * overdue; everywhere else it is inert and `run` refuses with a pointer.
      */
     devices?: string[];
+    /**
+     * Environment variables injected into the spawned run, on top of the sandbox
+     * overlay's own. Merged by `buildSpawnEnv`, so it applies to both the
+     * foreground and detached execution paths.
+     */
+    env?: Record<string, string>;
     /**
      * Execution placement — run the job body on this machine over SSH (a
      * registered host, device, capability tag, or user@host) instead of locally.
@@ -360,8 +370,54 @@ export declare function oneShotScheduleFireDate(schedule: string | undefined | n
 export declare function isPastOneShotRoutine(config: Pick<JobConfig, 'schedule' | 'runOnce' | 'timezone'>, now?: Date): boolean;
 export declare function hasCompletedOneShotRun(config: Pick<JobConfig, 'name' | 'schedule' | 'runOnce' | 'timezone'>, now?: Date): boolean;
 export declare function shouldPurgeCompletedOneShotRoutine(config: Pick<JobConfig, 'name' | 'schedule' | 'runOnce' | 'timezone'>, now?: Date): boolean;
+/**
+ * Context passed to `resolveJobPrompt` when a job is fired by a webhook. Lets
+ * prompts use `{{issue.identifier}}`, `{{updatedFrom.state.name}}`, etc.
+ */
+export interface WebhookContext {
+    source: string;
+    event: string;
+    action?: string;
+    issue?: unknown;
+    updatedFrom?: unknown;
+    pull_request?: unknown;
+    repository?: unknown;
+}
+/**
+ * Substitute `{{dotted.path}}` placeholders in a string using a webhook context.
+ * Missing values are replaced with an empty string.
+ */
+export declare function substituteWebhookPrompt(prompt: string, context: WebhookContext): string;
+/**
+ * Substitute `{{dotted.path}}` placeholders in a string destined for a SHELL,
+ * quoting every substituted value so payload content cannot break out of it.
+ *
+ * `run.command` is executed through a shell, and its context is built from an
+ * external webhook payload — `issue.title`, `issue.description`, and the GitHub
+ * `pull_request` fields are free text any outside contributor can set. Pasting
+ * those in raw (as {@link substituteWebhookPrompt} does, correctly, for prompts)
+ * turns an operator's `echo {{issue.title}}` into a command-injection sink.
+ *
+ * The template itself is operator-authored and stays unquoted, so pipes,
+ * redirects, and `&&` in the configured command keep working. Only the
+ * interpolated values are quoted.
+ *
+ * POSIX `sh` quoting: wrap in single quotes and close/escape/reopen for any
+ * embedded single quote. `exec` uses `cmd.exe` on Windows, which does not
+ * honour these rules — see `assertShellSubstitutionSupported`.
+ */
+export declare function substituteWebhookCommand(command: string, context: WebhookContext): string;
+/**
+ * Refuse a `run.command` carrying placeholders on a platform whose shell we
+ * cannot safely quote for. `child_process.exec` runs through `cmd.exe` on
+ * Windows, where POSIX single-quoting is not a quoting mechanism at all, so
+ * {@link substituteWebhookCommand} would not contain a hostile value.
+ *
+ * Fail loud rather than execute something we cannot prove is safe.
+ */
+export declare function assertShellSubstitutionSupported(command: string, platform?: NodeJS.Platform): void;
 /** Expand built-in and user-defined template variables in a job's prompt string. */
-export declare function resolveJobPrompt(config: JobConfig): string;
+export declare function resolveJobPrompt(config: JobConfig, context?: WebhookContext): string;
 /** Parse a human-readable timeout string (e.g. "10m", "2h", "1h30m", "3d", "1w") into milliseconds.
  *  Accepts combinations of w (weeks), d (days), h (hours), m (minutes).
  *  Returns null if the string is empty, matches nothing, totals zero, or exceeds 1 week.

package/dist/lib/routines.js

@@ -569,6 +569,12 @@ export function validateTrigger(trigger) {
     if (linear.label !== undefined && typeof linear.label !== 'string') {
         errors.push('trigger.label must be a string');
     }
+    if (linear.stateTo !== undefined && typeof linear.stateTo !== 'string') {
+        errors.push('trigger.stateTo must be a string');
+    }
+    if (linear.stateFrom !== undefined && typeof linear.stateFrom !== 'string') {
+        errors.push('trigger.stateFrom must be a string');
+    }
     return errors;
 }
 function isParseableDate(value) {
@@ -702,8 +708,71 @@ export function hasCompletedOneShotRun(config, now = new Date()) {
 export function shouldPurgeCompletedOneShotRoutine(config, now = new Date()) {
     return hasCompletedOneShotRun(config, now);
 }
+function getPath(obj, path) {
+    const parts = path.split('.');
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || current === undefined)
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+/**
+ * Substitute `{{dotted.path}}` placeholders in a string using a webhook context.
+ * Missing values are replaced with an empty string.
+ */
+export function substituteWebhookPrompt(prompt, context) {
+    return prompt.replace(/\{\{([^{}]+)\}\}/g, (_, rawPath) => {
+        const value = getPath(context, rawPath.trim());
+        if (value === undefined || value === null)
+            return '';
+        return String(value);
+    });
+}
+/**
+ * Substitute `{{dotted.path}}` placeholders in a string destined for a SHELL,
+ * quoting every substituted value so payload content cannot break out of it.
+ *
+ * `run.command` is executed through a shell, and its context is built from an
+ * external webhook payload — `issue.title`, `issue.description`, and the GitHub
+ * `pull_request` fields are free text any outside contributor can set. Pasting
+ * those in raw (as {@link substituteWebhookPrompt} does, correctly, for prompts)
+ * turns an operator's `echo {{issue.title}}` into a command-injection sink.
+ *
+ * The template itself is operator-authored and stays unquoted, so pipes,
+ * redirects, and `&&` in the configured command keep working. Only the
+ * interpolated values are quoted.
+ *
+ * POSIX `sh` quoting: wrap in single quotes and close/escape/reopen for any
+ * embedded single quote. `exec` uses `cmd.exe` on Windows, which does not
+ * honour these rules — see `assertShellSubstitutionSupported`.
+ */
+export function substituteWebhookCommand(command, context) {
+    return command.replace(/\{\{([^{}]+)\}\}/g, (_, rawPath) => {
+        const value = getPath(context, rawPath.trim());
+        if (value === undefined || value === null)
+            return "''";
+        return `'${String(value).replace(/'/g, `'\\''`)}'`;
+    });
+}
+/**
+ * Refuse a `run.command` carrying placeholders on a platform whose shell we
+ * cannot safely quote for. `child_process.exec` runs through `cmd.exe` on
+ * Windows, where POSIX single-quoting is not a quoting mechanism at all, so
+ * {@link substituteWebhookCommand} would not contain a hostile value.
+ *
+ * Fail loud rather than execute something we cannot prove is safe.
+ */
+export function assertShellSubstitutionSupported(command, platform = process.platform) {
+    if (platform === 'win32' && /\{\{[^{}]+\}\}/.test(command)) {
+        throw new Error('run.command with {{…}} placeholders is not supported on Windows: the values come from an ' +
+            'untrusted webhook payload and cmd.exe cannot be quoted safely. Use run.prompt, or a ' +
+            'command with no placeholders.');
+    }
+}
 /** Expand built-in and user-defined template variables in a job's prompt string. */
-export function resolveJobPrompt(config) {
+export function resolveJobPrompt(config, context) {
     const now = new Date();
     const tz = config.timezone || Intl.DateTimeFormat().resolvedOptions().timeZone;
     const days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
@@ -725,6 +794,10 @@ export function resolveJobPrompt(config) {
             prompt = prompt.replace(new RegExp(`\\{${key}\\}`, 'g'), value);
         }
     }
+    // Webhook-driven variables ({{issue.identifier}}, {{updatedFrom.state.name}}, ...)
+    if (context) {
+        prompt = substituteWebhookPrompt(prompt, context);
+    }
     // Last report (special handling). Only a COMPLETED run's report is injected —
     // a failed run's report.md is the agent's error text (e.g. a login prompt on
     // an auth failure), and feeding that into the next prompt poisons every

package/dist/lib/runner.d.ts

@@ -26,6 +26,8 @@ export interface RunResult {
 /** Agents the daemon can actually run, derived from the command table above
  * so the `--agent` help and any validation can never drift from it. */
 export declare const ROUTINE_AGENT_IDS: readonly string[];
+/** Stable working directory for routine children, independent of the daemon's launch cwd. */
+export declare function routineSpawnCwd(config: Pick<JobConfig, 'repo'>, configuredRoot?: string | undefined): string;
 /** Build the full CLI argv for executing a job, applying mode, model, and permission flags. */
 export declare function buildJobCommand(config: JobConfig, resolvedPrompt: string): string[];
 export declare function archiveRoutineTranscripts(meta: Pick<RunMeta, 'jobName' | 'runId' | 'agent'>, runDir: string, overlayHome?: string): void;