@phnx-labs/agents-cli 1.20.88 → 1.20.90

package/dist/lib/profiles.d.ts

@@ -29,6 +29,18 @@ export interface Profile {
     description?: string;
     preset?: string;
     provider?: string;
+    /**
+     * Human-facing label for the harness — what `agents view` prints as the
+     * agent-type header, the same slot `AGENTS[id].name` fills for a native
+     * harness. Defaults to the profile name when unset.
+     */
+    label?: string;
+    /**
+     * Name of the harness this one was forked from — either a native agent id
+     * (`claude`, `opencode`) or another custom harness. Display-only lineage:
+     * the fork is a full copy, so deleting the source never affects it.
+     */
+    forkedFrom?: string;
     /**
      * Optional secondary model retried on the same host when the primary model
      * env value hits a rate limit. Reuses the `--fallback` cascade in
@@ -45,12 +57,19 @@ export interface Profile {
  */
 export interface ProfileSummary {
     name: string;
+    /** Human-facing header label — `label` when set, else the profile name. */
+    label: string;
     agent: AgentId;
     host: string;
+    /** Host version pin, or null when the harness follows the host's default. */
+    hostVersion: string | null;
     provider: string;
     model: string;
     auth: string;
     path: string;
+    description: string | null;
+    /** Native agent id or custom harness this one was forked from, if recorded. */
+    forkedFrom: string | null;
 }
 /** Get the directory where profile YAML files are stored. */
 export declare function getProfilesDir(): string;
@@ -91,6 +110,11 @@ export declare function profileModelEnvKey(profile: Profile): string | null;
  * - No auth at all: provider only.
  */
 export declare function profileAuthLabel(profile: Profile): string;
+/**
+ * Header label for the harness — the slot `AGENTS[id].name` fills for a native
+ * harness, so `agents view` can print custom and native harnesses the same way.
+ */
+export declare function profileLabel(profile: Profile): string;
 /** Build a stable, machine-readable summary for list and view surfaces. */
 export declare function profileSummary(profile: Profile): ProfileSummary;
 /**
@@ -115,6 +139,8 @@ export interface HostModelOptions {
     /** Env var the host reads its auth token from; pair with `provider` to attach keychain auth. */
     authEnvVar?: string;
     description?: string;
+    /** Human-facing header label; defaults to the harness name. */
+    label?: string;
 }
 /**
  * Build a custom-harness profile from a host CLI + model in one shot, without a
@@ -123,6 +149,28 @@ export interface HostModelOptions {
  * (hosts that manage their own login — e.g. opencode — need neither).
  */
 export declare function profileFromHostModel(name: string, host: AgentId, model: string, opts?: HostModelOptions): Profile;
+/** Overrides applied on top of the source when forking a harness. */
+export interface ForkProfileOptions {
+    /** Swap the pinned model. Written onto the source's model env key when it has
+     *  one, else onto the host's canonical model var. */
+    model?: string;
+    /** Swap the endpoint. Only applied for hosts with a known base-URL var. */
+    baseUrl?: string;
+    /** Repoint auth at a different provider's keychain item. */
+    provider?: string;
+    /** Env var the host reads its token from; pair with `provider`. */
+    authEnvVar?: string;
+    /** Re-pin (or unpin, with an empty string) the host CLI version. */
+    version?: string;
+    label?: string;
+    description?: string;
+}
+/**
+ * Copy an existing harness under a new name, applying overrides. The fork is a
+ * full copy — env, auth binding, and fallback model all carry over — so the two
+ * diverge from here and deleting the source never affects the fork.
+ */
+export declare function forkProfile(source: Profile, name: string, opts?: ForkProfileOptions): Profile;
 /**
  * Resolve a profile into the env block that should be injected into the
  * spawned agent process. Reads the token from keychain at exec time so the

package/dist/lib/profiles.js

@@ -197,16 +197,27 @@ export function profileAuthLabel(profile) {
     }
     return provider;
 }
+/**
+ * Header label for the harness — the slot `AGENTS[id].name` fills for a native
+ * harness, so `agents view` can print custom and native harnesses the same way.
+ */
+export function profileLabel(profile) {
+    return profile.label || profile.name;
+}
 /** Build a stable, machine-readable summary for list and view surfaces. */
 export function profileSummary(profile) {
     return {
         name: profile.name,
+        label: profileLabel(profile),
         agent: profile.host.agent,
         host: profileHostLabel(profile),
+        hostVersion: profile.host.version ?? null,
         provider: profileProviderLabel(profile),
         model: profileModelLabel(profile),
         auth: profileAuthLabel(profile),
         path: getProfilePath(profile.name),
+        description: profile.description ?? null,
+        forkedFrom: profile.forkedFrom ?? null,
     };
 }
 /**
@@ -227,6 +238,7 @@ export function profileFromPreset(profileName, preset, version) {
         description: preset.description,
         preset: preset.name,
         provider: preset.provider,
+        forkedFrom: preset.host,
     };
 }
 /**
@@ -285,13 +297,68 @@ export function profileFromHostModel(name, host, model, opts = {}) {
         env,
         description: opts.description ?? `Custom harness: ${host} + ${model}`,
         provider: opts.provider ?? host,
+        forkedFrom: host,
     };
+    if (opts.label)
+        profile.label = opts.label;
     if (opts.provider && opts.authEnvVar) {
         profile.auth = { envVar: opts.authEnvVar, keychainItem: keychainItemName(opts.provider) };
         profile.authOptional = false;
     }
     return profile;
 }
+/**
+ * Copy an existing harness under a new name, applying overrides. The fork is a
+ * full copy — env, auth binding, and fallback model all carry over — so the two
+ * diverge from here and deleting the source never affects the fork.
+ */
+export function forkProfile(source, name, opts = {}) {
+    validateProfileName(name);
+    const host = source.host.agent;
+    const env = { ...source.env };
+    if (opts.model) {
+        env[profileModelEnvKey(source) ?? modelEnvKeyForHost(host)] = opts.model;
+    }
+    if (opts.baseUrl) {
+        const key = baseUrlEnvKeyForHost(host);
+        if (!key) {
+            throw new Error(`Host '${host}' has no known base-URL env var; drop --base-url or fork onto a claude/codex host.`);
+        }
+        env[key] = opts.baseUrl;
+    }
+    const forked = {
+        ...source,
+        name,
+        host: { agent: host, ...(opts.version ? { version: opts.version } : source.host.version ? { version: source.host.version } : {}) },
+        env,
+        // The source's description names the source's model, so inheriting it
+        // across a model swap would describe the fork wrongly.
+        description: opts.description ?? (opts.model ? `Forked from ${source.name}: ${opts.model}` : source.description),
+        forkedFrom: source.name,
+    };
+    // `label` is the header `agents view` prints, so an inherited one would make
+    // the fork and its source visually identical — the ambiguity a per-harness
+    // block exists to remove. A fork carries a label only when it is given one;
+    // otherwise `profileLabel` falls back to the fork's own name.
+    if (opts.label)
+        forked.label = opts.label;
+    else
+        delete forked.label;
+    // A fork that repoints the model or endpoint is no longer that preset — keep
+    // the preset link only while the fork still matches what the preset defines.
+    if (opts.model || opts.baseUrl)
+        delete forked.preset;
+    if (opts.provider) {
+        const envVar = opts.authEnvVar ?? source.auth?.envVar ?? authEnvKeyForHost(host);
+        if (!envVar) {
+            throw new Error(`Host '${host}' has no known auth env var; --provider cannot be attached to this fork.`);
+        }
+        forked.provider = opts.provider;
+        forked.auth = { envVar, keychainItem: keychainItemName(opts.provider) };
+        forked.authOptional = source.authOptional ?? false;
+    }
+    return forked;
+}
 /**
  * Resolve a profile into the env block that should be injected into the
  * spawned agent process. Reads the token from keychain at exec time so the

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

@@ -35,6 +35,12 @@ export interface RotateResult {
     healthy: RotateCandidate[];
     /** Candidates excluded (not signed in, or out of credits). */
     excluded: RotateCandidate[];
+    /**
+     * True when NO candidate on this machine had usage data fresh enough to decide
+     * on, so the pick was made from unverified snapshots. Callers surface it —
+     * routing blind is a fact the operator needs, not an internal detail.
+     */
+    usageUnverified?: boolean;
 }
 export declare const RUN_STRATEGIES: RunStrategy[];
 /**
@@ -60,6 +66,22 @@ export declare function getProjectRunStrategy(agent: AgentId, startPath: string)
 export declare function getConfiguredRunStrategy(agent: AgentId, startPath?: string): RunStrategy;
 /** Persist the global run strategy used by bare `agents run <agent>`. */
 export declare function setGlobalRunStrategy(agent: AgentId, strategy: RunStrategy): void;
+/**
+ * How old a usage snapshot may be and still settle a routing DECISION.
+ *
+ * Deliberately far tighter than the 24h stale-while-revalidate window the
+ * display paths use (`USAGE_CACHE_SWR_MS`): `agents view` rendering a slightly
+ * old bar costs nothing, but the router choosing an account from one costs the
+ * whole run. Measured case — `yosemite-s1` held snapshots 26h to 2.7 days old
+ * with a failing refresh, so balanced read `muqsit@getrush.ai` as 48% used and
+ * launched into it while the account was actually at its weekly cap.
+ */
+export declare const USAGE_DECISION_MAX_AGE_MS: number;
+/**
+ * Whether this candidate's usage number is recent enough to route on. A missing
+ * snapshot is unverified by definition — there is no number to trust.
+ */
+export declare function isUsageVerified(candidate: RotateCandidate, nowMs?: number): boolean;
 /**
  * Whether a specific account can serve a run right now, and — when it can't —
  * why. `signed_out` covers a missing usable credential; `rate_limited` and
@@ -118,13 +140,13 @@ export declare function checkRunAccountReadiness(agent: AgentId, version: string
  * Returns null if no candidate is eligible — callers fall back to the pinned
  * version so behavior stays predictable.
  */
-export declare function pickBalancedCandidate(candidates: RotateCandidate[]): RotateResult | null;
+export declare function pickBalancedCandidate(candidates: RotateCandidate[], nowMs?: number): RotateResult | null;
 /**
  * Pick an available candidate. Prefers the configured pinned version when that
  * version has usage available; otherwise routes to the candidate with the most
  * usage headroom.
  */
-export declare function pickAvailableCandidate(candidates: RotateCandidate[], preferredVersion?: string | null): RotateResult | null;
+export declare function pickAvailableCandidate(candidates: RotateCandidate[], preferredVersion?: string | null, nowMs?: number): RotateResult | null;
 export declare function collectRunCandidates(agent: AgentId): Promise<RotateCandidate[]>;
 /**
  * Resolve an account identity to the installed version slot that holds it, over

package/dist/lib/rotate.js

@@ -70,6 +70,27 @@ function isRotationEligible(candidate) {
 function isAvailableEligible(candidate) {
     return isRotationEligible(candidate);
 }
+/**
+ * How old a usage snapshot may be and still settle a routing DECISION.
+ *
+ * Deliberately far tighter than the 24h stale-while-revalidate window the
+ * display paths use (`USAGE_CACHE_SWR_MS`): `agents view` rendering a slightly
+ * old bar costs nothing, but the router choosing an account from one costs the
+ * whole run. Measured case — `yosemite-s1` held snapshots 26h to 2.7 days old
+ * with a failing refresh, so balanced read `muqsit@getrush.ai` as 48% used and
+ * launched into it while the account was actually at its weekly cap.
+ */
+export const USAGE_DECISION_MAX_AGE_MS = 5 * 60 * 1000;
+/**
+ * Whether this candidate's usage number is recent enough to route on. A missing
+ * snapshot is unverified by definition — there is no number to trust.
+ */
+export function isUsageVerified(candidate, nowMs = Date.now()) {
+    const capturedAt = candidate.usageSnapshot?.capturedAt;
+    if (!capturedAt)
+        return false;
+    return nowMs - capturedAt.getTime() <= USAGE_DECISION_MAX_AGE_MS;
+}
 function hasUsageAvailable(candidate) {
     const snapshot = candidate.usageSnapshot;
     if (snapshot && snapshot.windows.length > 0) {
@@ -199,7 +220,7 @@ function dedupeAndSortCandidates(candidates) {
  * Returns null if no candidate is eligible — callers fall back to the pinned
  * version so behavior stays predictable.
  */
-export function pickBalancedCandidate(candidates) {
+export function pickBalancedCandidate(candidates, nowMs = Date.now()) {
     const healthy = [];
     const excluded = [];
     for (const c of candidates) {
@@ -217,8 +238,31 @@ export function pickBalancedCandidate(candidates) {
         if (!deduped.has(c))
             excluded.push(c);
     }
-    const picked = weightedRandomByCapacity(sorted);
-    return { picked, healthy: sorted, excluded };
+    const { picked, usageUnverified } = preferVerified(sorted, nowMs, weightedRandomByCapacity);
+    return { picked, healthy: sorted, excluded, usageUnverified };
+}
+/**
+ * Choose from the VERIFIED candidates when any exist, else from the whole pool.
+ *
+ * An eligible account whose usage we could not confirm is a guess, not a green
+ * light: the snapshot reads "48% used" with equal confidence whether it was
+ * captured a minute or three days ago, and a box whose refresh is failing stays
+ * wrong indefinitely. Confirmed headroom therefore beats apparent headroom, even
+ * when the unconfirmed number looks better.
+ *
+ * `healthy` deliberately keeps every eligible candidate rather than just the
+ * verified ones. Declining to *pick* an account on stale data and declining to
+ * *fail over to* it after the primary has already hit a 429 are different risks:
+ * by then the alternative is not launching at all, so the failover chain
+ * (rotationFailoverChain, which reads `healthy`) keeps its full safety net —
+ * exactly on the machines this guard is protecting.
+ */
+function preferVerified(pool, nowMs, choose) {
+    const verified = pool.filter((c) => isUsageVerified(c, nowMs));
+    return {
+        picked: choose(verified.length > 0 ? verified : pool),
+        usageUnverified: verified.length === 0,
+    };
 }
 /**
  * Pick one candidate from `sorted` using weights proportional to remaining
@@ -250,7 +294,7 @@ function weightedRandomByCapacity(sorted) {
  * version has usage available; otherwise routes to the candidate with the most
  * usage headroom.
  */
-export function pickAvailableCandidate(candidates, preferredVersion) {
+export function pickAvailableCandidate(candidates, preferredVersion, nowMs = Date.now()) {
     const healthy = [];
     const excluded = [];
     for (const c of candidates) {
@@ -268,10 +312,17 @@ export function pickAvailableCandidate(candidates, preferredVersion) {
         if (!deduped.has(c))
             excluded.push(c);
     }
+    // `available` sorts by apparent headroom and takes the front of the list, so an
+    // unconfirmed "48% used" outranks an accurate "90% used" — the same inversion
+    // that put a launch on an exhausted account under `balanced`. It routes on the
+    // same cache, so it gets the same rule: confirmed headroom first.
+    const { picked: bestVerified, usageUnverified } = preferVerified(sorted, nowMs, (from) => from[0]);
+    // An explicit version preference is an instruction, not a ranking signal, so it
+    // still wins — but only while that version is actually eligible.
     const preferred = preferredVersion
         ? sorted.find((candidate) => candidate.version === preferredVersion)
         : undefined;
-    return { picked: preferred ?? sorted[0], healthy: sorted, excluded };
+    return { picked: preferred ?? bestVerified, healthy: sorted, excluded, usageUnverified };
 }
 export async function collectRunCandidates(agent) {
     const versions = listInstalledVersions(agent);
@@ -299,12 +350,18 @@ export async function collectRunCandidates(agent) {
             lastActive: info.lastActive,
         };
     }));
+    // These candidates feed a routing decision, so cap how stale their usage may
+    // be (see USAGE_DECISION_MAX_AGE_MS). Past that the fetch blocks on a live
+    // read instead of serving the cache — one bounded, parallel round trip per
+    // account, and none at all inside the 2-minute fresh window that back-to-back
+    // launches hit. A failed read still falls back to the cache; the pick then
+    // routes around it via isUsageVerified rather than trusting the old number.
     const { usageByKey } = await getUsageInfoByIdentity(rows.map(({ home, info, version }) => ({
         agentId: agent,
         home,
         cliVersion: version,
         info,
-    })));
+    })), { maxAgeMs: USAGE_DECISION_MAX_AGE_MS });
     return rows.map(({ home: _home, info, ...candidate }) => {
         const usageKey = getUsageLookupKey(info);
         const usage = usageKey ? usageByKey.get(usageKey) : undefined;

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;