@hyperdrive.bot/paseo-cli 0.3.42 → 0.3.43

package/dist/commands/agent/archive.js

@@ -1,4 +1,4 @@
-import { connectToDaemon, getDaemonHost, resolveAgentId } from "../../utils/client.js";
+import { connectToDaemon, getDaemonHost, resolveAgentViaDaemon } from "../../utils/client.js";
 /** Schema for archive command output */
 export const archiveSchema = {
     idField: "agentId",
@@ -39,21 +39,20 @@ export async function runArchiveCommand(agentIdArg, options, _command) {
         throw error;
     }
     try {
-        const agentsPayload = await client.fetchAgents({ filter: { includeArchived: true } });
-        const agents = agentsPayload.entries.map((entry) => entry.agent);
-        const agentId = resolveAgentId(agentIdArg, agents);
-        if (!agentId) {
+        // Resolve through the daemon, not through a page of `fetchAgents`: that rpc
+        // caps a page at 200 entries, so matching client-side against one page could
+        // not see agents outside the newest 200 and failed for most valid IDs here.
+        const resolution = await resolveAgentViaDaemon(client, agentIdArg);
+        if (!resolution.ok) {
             const error = {
                 code: "AGENT_NOT_FOUND",
                 message: `Agent not found: ${agentIdArg}`,
-                details: 'Use "paseo ls" to list available agents',
+                details: `${resolution.error}\nUse "paseo ls" to list available agents`,
             };
             throw error;
         }
-        const agent = agents.find((entry) => entry.id === agentId);
-        if (!agent) {
-            throw new Error(`Resolved agent missing from fetched agents: ${agentId}`);
-        }
+        const agent = resolution.agent;
+        const agentId = agent.id;
         // Check if agent is already archived
         if (agent.archivedAt) {
             const error = {

package/dist/commands/agent/reload.js

@@ -1,4 +1,4 @@
-import { connectToDaemon, getDaemonHost, resolveAgentId } from "../../utils/client.js";
+import { connectToDaemon, getDaemonHost, resolveAgentViaDaemon } from "../../utils/client.js";
 export const reloadSchema = {
     idField: "agentId",
     columns: [
@@ -36,17 +36,19 @@ export async function runReloadCommand(agentIdArg, options, _command) {
         throw error;
     }
     try {
-        const agentsPayload = await client.fetchAgents({ filter: { includeArchived: true } });
-        const agents = agentsPayload.entries.map((entry) => entry.agent);
-        const agentId = resolveAgentId(agentIdArg, agents);
-        if (!agentId) {
+        // Resolve through the daemon, not through a page of `fetchAgents`: that rpc
+        // caps a page at 200 entries, so matching client-side against one page could
+        // not see agents outside the newest 200 and failed for most valid IDs here.
+        const resolution = await resolveAgentViaDaemon(client, agentIdArg);
+        if (!resolution.ok) {
             const error = {
                 code: "AGENT_NOT_FOUND",
                 message: `Agent not found: ${agentIdArg}`,
-                details: 'Use "paseo ls" to list available agents',
+                details: `${resolution.error}\nUse "paseo ls" to list available agents`,
             };
             throw error;
         }
+        const agentId = resolution.agent.id;
         const result = await client.refreshAgent(agentId);
         await client.close();
         return {

package/dist/commands/daemon/index.js

@@ -32,6 +32,7 @@ export function createDaemonCommand() {
         .option("--home <path>", "Paseo home directory (default: ~/.paseo)")
         .option("--timeout <seconds>", "Wait timeout before force step (default: 15)")
         .option("--force", "Send SIGKILL if graceful stop times out")
+        .option("--force-detached", "Restart detached even when the daemon is managed by an init system (systemd)")
         .option("--listen <listen>", "Listen target for restarted daemon (host:port, port, or unix socket)")
         .option("--port <port>", "Port for restarted daemon listen target")
         .option("--no-relay", "Disable relay on restarted daemon")

package/dist/commands/daemon/restart.js

@@ -1,4 +1,5 @@
-import { startLocalDaemonDetached, stopLocalDaemon, DEFAULT_STOP_TIMEOUT_MS, } from "./local-daemon.js";
+import { startLocalDaemonDetached, stopLocalDaemon, resolveLocalDaemonState, DEFAULT_STOP_TIMEOUT_MS, } from "./local-daemon.js";
+import { detectServiceManagement } from "./service-manager.js";
 const restartResultSchema = {
     idField: "action",
     columns: [
@@ -47,10 +48,53 @@ function toStartOptions(options) {
     }
     return startOptions;
 }
+/**
+ * Refuse to restart a daemon that an init system owns.
+ *
+ * `stop` + `startLocalDaemonDetached` is wrong twice under a service manager:
+ * the clean stop is not a failure, so a `Restart=on-failure` unit never fires
+ * and the replacement runs detached OUTSIDE the unit (systemd then reports the
+ * service as stopped while a daemon is in fact running); and the detached
+ * process inherits the invoking shell's environment instead of the unit's
+ * `Environment=`/`EnvironmentFile=`, so variables like PASEO_HOME are silently
+ * lost. Losing PASEO_HOME disables PTY recording with no diagnostic at all.
+ */
+function assertNotServiceManaged(startOptions) {
+    const state = resolveLocalDaemonState({ home: startOptions.home });
+    if (!state.running || !state.pidInfo) {
+        return;
+    }
+    const managed = detectServiceManagement(state.pidInfo.pid);
+    if (!managed) {
+        return;
+    }
+    const error = {
+        code: "DAEMON_SERVICE_MANAGED",
+        message: `Daemon PID ${state.pidInfo.pid} is managed by ${managed.manager} unit ${managed.unit}`,
+        details: [
+            `Restart it through its service manager instead:`,
+            `  ${managed.restartCommand}`,
+            "",
+            "Restarting it here would stop the unit cleanly (so the unit's Restart= policy",
+            "never fires) and spawn a detached replacement outside it. The service manager",
+            "would report the service as stopped while a daemon kept running, and the",
+            "replacement would inherit this shell's environment rather than the unit's",
+            "Environment=/EnvironmentFile= settings, silently dropping variables such as",
+            "PASEO_HOME.",
+            "",
+            "Pass --force-detached to restart detached anyway.",
+        ].join("\n"),
+    };
+    throw error;
+}
 export async function runRestartCommand(options, _command) {
     const timeoutMs = parseTimeoutMs(options.timeout);
     const force = options.force === true;
+    const forceDetached = options.forceDetached === true;
     const startOptions = toStartOptions(options);
+    if (!forceDetached) {
+        assertNotServiceManaged(startOptions);
+    }
     try {
         let stopResult;
         try {
@@ -88,6 +132,9 @@ export async function runRestartCommand(options, _command) {
         };
     }
     catch (err) {
+        if (err && typeof err === "object" && "code" in err) {
+            throw err;
+        }
         const message = err instanceof Error ? err.message : String(err);
         const error = {
             code: "RESTART_FAILED",

package/dist/commands/daemon/service-manager.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Describes an init-system unit that owns the running daemon process.
+ */
+export interface ServiceManagement {
+    manager: "systemd";
+    /** Leaf unit name, e.g. "paseo.service". */
+    unit: string;
+    /** True when the unit is a per-user unit, i.e. `systemctl --user`. */
+    userScoped: boolean;
+    /** The command that restarts the daemon through its service manager. */
+    restartCommand: string;
+}
+/**
+ * Parse a `/proc/<pid>/cgroup` body into the service unit that owns the process.
+ *
+ * Handles both cgroup layouts, since the path is always the last colon-delimited
+ * field:
+ *   v2: `0::/system.slice/paseo.service`
+ *   v1: `1:name=systemd:/system.slice/paseo.service`
+ *
+ * Only a `.service` leaf counts as managed. A daemon the CLI started detached
+ * from a shell lands in a `.scope` (`session-5.scope`, `app-*.scope`) or the root
+ * cgroup, so it is never mistaken for a service.
+ */
+export declare function parseServiceManagementFromCgroup(raw: string): ServiceManagement | null;
+export interface DetectServiceManagementDeps {
+    /** Overridable for tests. Defaults to querying systemd. */
+    readUnitMainPid?: (unit: string, userScoped: boolean) => number | null;
+    /** Overridable for tests. Defaults to reading `/proc/<pid>/cgroup`. */
+    readCgroup?: (pid: number) => string | null;
+}
+/**
+ * Detect whether `pid` is the process an init-system unit manages, rather than a
+ * detached process this CLI owns.
+ *
+ * The cgroup alone is NOT sufficient. Every child inherits its parent's cgroup,
+ * so a daemon started from a shell that is itself running inside a unit (an
+ * agent shell under `paseo.service`, a CI job under a service) would report that
+ * unit even though the daemon is an ordinary detached process. The unit's
+ * MainPID is the discriminator, so a candidate from the cgroup is confirmed
+ * against it and dropped when it does not match.
+ *
+ * Returns null on anything less than a positive confirmation: a non-Linux
+ * platform, an unreadable cgroup, a non-service cgroup, or a host where
+ * `systemctl` cannot answer. Refusing to restart is the disruptive outcome, so
+ * uncertainty resolves to "not managed" and the normal path proceeds.
+ */
+export declare function detectServiceManagement(pid: number, deps?: DetectServiceManagementDeps): ServiceManagement | null;
+//# sourceMappingURL=service-manager.d.ts.map

package/dist/commands/daemon/service-manager.js

@@ -0,0 +1,97 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+/** A `user@<uid>.service` segment is the per-user manager, never the daemon's own unit. */
+const USER_MANAGER_UNIT = /^user@\d+\.service$/;
+const SERVICE_UNIT = /^[A-Za-z0-9@:_.-]+\.service$/;
+/**
+ * Parse a `/proc/<pid>/cgroup` body into the service unit that owns the process.
+ *
+ * Handles both cgroup layouts, since the path is always the last colon-delimited
+ * field:
+ *   v2: `0::/system.slice/paseo.service`
+ *   v1: `1:name=systemd:/system.slice/paseo.service`
+ *
+ * Only a `.service` leaf counts as managed. A daemon the CLI started detached
+ * from a shell lands in a `.scope` (`session-5.scope`, `app-*.scope`) or the root
+ * cgroup, so it is never mistaken for a service.
+ */
+export function parseServiceManagementFromCgroup(raw) {
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const pathPart = trimmed.slice(trimmed.lastIndexOf(":") + 1);
+        if (!pathPart.startsWith("/"))
+            continue;
+        const segments = pathPart.split("/").filter(Boolean);
+        const userScoped = segments.some((segment) => USER_MANAGER_UNIT.test(segment));
+        // Walk from the leaf inward: the daemon's own unit is the innermost one.
+        for (let i = segments.length - 1; i >= 0; i--) {
+            const segment = segments[i];
+            if (!SERVICE_UNIT.test(segment) || USER_MANAGER_UNIT.test(segment))
+                continue;
+            return {
+                manager: "systemd",
+                unit: segment,
+                userScoped,
+                restartCommand: userScoped
+                    ? `systemctl --user restart ${segment}`
+                    : `sudo systemctl restart ${segment}`,
+            };
+        }
+    }
+    return null;
+}
+function defaultReadCgroup(pid) {
+    try {
+        return readFileSync(`/proc/${pid}/cgroup`, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/** Ask systemd for a unit's MainPID. Returns null when systemd cannot answer. */
+function readUnitMainPid(unit, userScoped) {
+    const args = userScoped
+        ? ["--user", "show", unit, "--property=MainPID", "--value"]
+        : ["show", unit, "--property=MainPID", "--value"];
+    const result = spawnSync("systemctl", args, { encoding: "utf8", timeout: 2000 });
+    if (result.error || result.status !== 0) {
+        return null;
+    }
+    const parsed = Number.parseInt((result.stdout ?? "").trim(), 10);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+}
+/**
+ * Detect whether `pid` is the process an init-system unit manages, rather than a
+ * detached process this CLI owns.
+ *
+ * The cgroup alone is NOT sufficient. Every child inherits its parent's cgroup,
+ * so a daemon started from a shell that is itself running inside a unit (an
+ * agent shell under `paseo.service`, a CI job under a service) would report that
+ * unit even though the daemon is an ordinary detached process. The unit's
+ * MainPID is the discriminator, so a candidate from the cgroup is confirmed
+ * against it and dropped when it does not match.
+ *
+ * Returns null on anything less than a positive confirmation: a non-Linux
+ * platform, an unreadable cgroup, a non-service cgroup, or a host where
+ * `systemctl` cannot answer. Refusing to restart is the disruptive outcome, so
+ * uncertainty resolves to "not managed" and the normal path proceeds.
+ */
+export function detectServiceManagement(pid, deps = {}) {
+    if (process.platform !== "linux" || !Number.isInteger(pid) || pid <= 0) {
+        return null;
+    }
+    const readCgroup = deps.readCgroup ?? defaultReadCgroup;
+    const raw = readCgroup(pid);
+    if (!raw) {
+        return null;
+    }
+    const candidate = parseServiceManagementFromCgroup(raw);
+    if (!candidate) {
+        return null;
+    }
+    const lookup = deps.readUnitMainPid ?? readUnitMainPid;
+    return lookup(candidate.unit, candidate.userScoped) === pid ? candidate : null;
+}
+//# sourceMappingURL=service-manager.js.map

package/dist/commands/schedule/create.d.ts

@@ -2,6 +2,7 @@ import type { Command } from "commander";
 import type { SingleResult } from "../../output/index.js";
 import { type ScheduleCommandOptions, type ScheduleRow } from "./shared.js";
 export interface ScheduleCreateOptions extends ScheduleCommandOptions {
+    at?: string;
     every?: string;
     cron?: string;
     timezone?: string;

package/dist/commands/schedule/create.js

@@ -5,6 +5,7 @@ export async function runCreateCommand(prompt, options, command) {
     const runNow = runNowSource === "cli" ? Boolean(options.runNow) : undefined;
     const input = parseScheduleCreateInput({
         prompt,
+        at: options.at,
         every: options.every,
         cron: options.cron,
         timezone: options.timezone,

package/dist/commands/schedule/index.js

@@ -16,7 +16,8 @@ export function createScheduleCommand() {
         .command("create")
         .description("Create a schedule")
         .argument("<prompt>", "Prompt to run on the schedule")
-        .option("--every <duration>", "Fixed interval cadence (for example: 5m, 1h)")
+        .option("--at <when>", "Run once at an instant: ISO 8601 (2026-08-21T21:30:00-03:00) or a duration from now (90m)")
+        .option("--every <duration>", "Fixed interval cadence (for example: 5m, 1h, 1d)")
         .option("--cron <expr>", "Cron cadence expression")
         .option("--timezone <iana>", "IANA time zone for cron cadence (default: UTC)")
         .option("--name <name>", "Optional schedule name")

package/dist/commands/schedule/shared.d.ts

@@ -13,6 +13,7 @@ export declare function formatTarget(target: ScheduleTarget | ScheduleListItem["
 export declare function formatDurationMs(durationMs: number): string;
 export declare function parseScheduleCreateInput(options: {
     prompt: string;
+    at?: string;
     every?: string;
     cron?: string;
     timezone?: string;

package/dist/commands/schedule/shared.js

@@ -102,13 +102,7 @@ export function parseScheduleCreateInput(options) {
             message: "Schedule prompt cannot be empty",
         };
     }
-    const cadence = parseCadenceFromFlags(options.every, options.cron, options.timezone);
-    if (!cadence) {
-        throw {
-            code: "INVALID_CADENCE",
-            message: "Specify exactly one of --every or --cron",
-        };
-    }
+    const { cadence, oneOff } = parseCreateCadence(options);
     const cwdInput = options.cwd?.trim();
     if (options.host !== undefined && !cwdInput) {
         throw {
@@ -116,7 +110,7 @@ export function parseScheduleCreateInput(options) {
             message: "--cwd is required when --host is specified (the local working directory will not exist on the remote daemon)",
         };
     }
-    const runOnCreate = resolveRunOnCreate(options.runNow, cadence.type);
+    const { maxRuns, runOnCreate } = resolveCreateRunLimits(options, cadence, oneOff);
     const targetValue = options.target?.trim();
     const modeId = options.mode?.trim();
     const hasExplicitNewAgentOption = options.provider !== undefined || options.mode !== undefined;
@@ -139,7 +133,6 @@ export function parseScheduleCreateInput(options) {
         hasExplicitNewAgentOption,
         createNewAgentTarget,
     });
-    const maxRuns = options.maxRuns === undefined ? undefined : parsePositiveInt(options.maxRuns, "--max-runs");
     const expiresAt = options.expiresIn === undefined
         ? undefined
         : new Date(Date.now() + parseDuration(options.expiresIn)).toISOString();
@@ -153,6 +146,33 @@ export function parseScheduleCreateInput(options) {
         ...(expiresAt ? { expiresAt } : {}),
     };
 }
+// Split out of parseScheduleCreateInput to keep its branch count under the
+// complexity cap: a one-off pins both limits, everything else defers to the
+// existing --run-now rules.
+function resolveCreateRunLimits(options, cadence, oneOff) {
+    const explicitMaxRuns = options.maxRuns === undefined ? undefined : parsePositiveInt(options.maxRuns, "--max-runs");
+    if (!oneOff) {
+        return {
+            maxRuns: explicitMaxRuns,
+            runOnCreate: resolveRunOnCreate(options.runNow, cadence.type),
+        };
+    }
+    if (options.runNow !== undefined) {
+        throw {
+            code: "REDUNDANT_RUN_NOW",
+            message: "--run-now/--no-run-now cannot be combined with --at",
+            details: "An --at schedule runs exactly once, at its instant",
+        };
+    }
+    if (explicitMaxRuns !== undefined && explicitMaxRuns !== 1) {
+        throw {
+            code: "INVALID_MAX_RUNS",
+            message: "--max-runs cannot be combined with --at",
+            details: "An --at schedule runs exactly once",
+        };
+    }
+    return { maxRuns: 1, runOnCreate: false };
+}
 function resolveRunOnCreate(runNow, cadenceType) {
     if (runNow === true && cadenceType === "every") {
         throw {
@@ -205,6 +225,65 @@ export function parseScheduleUpdateInput(options) {
         ...(expiresAt !== undefined ? { expiresAt } : {}),
     };
 }
+// A duration ("90m", "2h30m", "45" seconds) rather than a timestamp. Checked
+// first so --at can accept both without Date parsing guessing at bare numbers.
+const AT_DURATION_ONLY = /^(?:\d+|(?:\d+[smhd])+)$/;
+function resolveAtInstant(at) {
+    if (AT_DURATION_ONLY.test(at)) {
+        return new Date(Date.now() + parseDuration(at));
+    }
+    const parsed = new Date(at);
+    if (Number.isNaN(parsed.getTime())) {
+        throw {
+            code: "INVALID_AT",
+            message: `Invalid --at value: ${at}`,
+            details: "Use an ISO 8601 instant (2026-08-21T21:30:00-03:00) or a duration from now (90m)",
+        };
+    }
+    return parsed;
+}
+/**
+ * `--at` is a one-off. It lowers to an `every` cadence sized to the distance to
+ * the instant, pinned to a single run, deliberately NOT to a pinned cron: an
+ * `every` schedule stores its computed nextRunAt, so a daemon that was down at
+ * that moment fires it late on the next tick, which is what a reminder wants.
+ * A pinned cron would skip silently to the next calendar match a year out.
+ * Mirrors the MCP `at` input added in 0.3.41.
+ */
+function parseCreateCadence(options) {
+    const at = options.at?.trim();
+    if (at) {
+        if (options.every !== undefined || options.cron !== undefined) {
+            throw {
+                code: "INVALID_CADENCE",
+                message: "Specify exactly one of --at, --every or --cron",
+            };
+        }
+        if (parseTimeZoneFlag(options.timezone) !== undefined) {
+            throw {
+                code: "INVALID_TIME_ZONE",
+                message: "--timezone can only be used with --cron",
+            };
+        }
+        const instant = resolveAtInstant(at);
+        const everyMs = instant.getTime() - Date.now();
+        if (everyMs <= 0) {
+            throw {
+                code: "INVALID_AT",
+                message: `--at must be in the future: ${instant.toISOString()} has already passed`,
+            };
+        }
+        return { cadence: { type: "every", everyMs }, oneOff: true };
+    }
+    const cadence = parseCadenceFromFlags(options.every, options.cron, options.timezone);
+    if (!cadence) {
+        throw {
+            code: "INVALID_CADENCE",
+            message: "Specify exactly one of --at, --every or --cron",
+        };
+    }
+    return { cadence, oneOff: false };
+}
 function parseCadenceFromFlags(every, cron, timezone) {
     if (every !== undefined && cron !== undefined) {
         throw {

package/dist/commands/workflow/definition-file.d.ts

@@ -0,0 +1,49 @@
+import type { LoopParamField, LoopParamValues } from "@hyperdrive.bot/paseo-protocol/fleet/params";
+import type { WorkflowDefinitionIssue } from "@hyperdrive.bot/paseo-protocol/workflow/definition";
+/**
+ * Reading the file `paseo workflow start` was pointed at, and turning `--input KEY=value`
+ * flags into typed values.
+ *
+ * Both jobs live here rather than in `start.ts` so they are testable without a daemon,
+ * a socket or a Commander instance. This module imports no daemon-connection helper at
+ * all, and must not start: every error it raises is raised before the CLI has any reason
+ * to talk to a daemon, which is what makes "a bad file never opens a socket" a property
+ * of the code rather than of the call order in `start.ts`. The import list above is the
+ * whole guarantee, and a grep for the connection helper is what enforces it.
+ */
+export type WorkflowStartFile = {
+    kind: "definition";
+    raw: unknown;
+} | {
+    kind: "task-graph";
+    raw: unknown;
+};
+/**
+ * Read and parse the file, and decide which of the two shapes it is.
+ *
+ * ONE parser. JSON is a subset of YAML 1.2, so a `.json` file needs no branch of its
+ * own, and the file extension is never consulted: a definition committed as `.json` and
+ * a task graph committed as `.yaml` both have to work, and an extension check would get
+ * each of them wrong in the direction that produces an error about the wrong thing.
+ */
+export declare function readWorkflowStartFile(filePath: string): WorkflowStartFile;
+export interface ParsedInputFlags {
+    values: LoopParamValues;
+    issues: WorkflowDefinitionIssue[];
+}
+/**
+ * Turn `--input KEY=VALUE` flags into values typed per the definition's declared inputs.
+ *
+ * Returns every issue rather than throwing on the first, mirroring `validateLoopParams`:
+ * an author with three bad flags fixes them once instead of re-running to discover the
+ * next one. Never returns early.
+ *
+ * It owns exactly three failure classes - flag syntax, undeclared key, and coercion to
+ * the declared type. It deliberately does NOT call `validateLoopParams`: `required`,
+ * `min`, `max` and `enum` membership are the compiler's single pass, and running them
+ * here as well would report the same mistake twice in one run. For the same reason an
+ * undeclared key is reported here AND withheld from `values`, so the compiler's own
+ * undeclared-key check never sees it and cannot double-report it.
+ */
+export declare function parseInputFlags(flags: string[], fields: LoopParamField[]): ParsedInputFlags;
+//# sourceMappingURL=definition-file.d.ts.map

package/dist/commands/workflow/definition-file.js

@@ -0,0 +1,154 @@
+import { readFileSync } from "node:fs";
+import YAML from "yaml";
+/**
+ * Read and parse the file, and decide which of the two shapes it is.
+ *
+ * ONE parser. JSON is a subset of YAML 1.2, so a `.json` file needs no branch of its
+ * own, and the file extension is never consulted: a definition committed as `.json` and
+ * a task graph committed as `.yaml` both have to work, and an extension check would get
+ * each of them wrong in the direction that produces an error about the wrong thing.
+ */
+export function readWorkflowStartFile(filePath) {
+    let parsed;
+    try {
+        const raw = readFileSync(filePath, "utf-8");
+        parsed = YAML.parse(raw);
+    }
+    catch (error) {
+        // An unreadable or unparseable file has no top-level `version` key, so the rule
+        // below already classifies it as a task graph. Raising the pre-existing task-graph
+        // error here is what keeps today's behaviour for the malformed-JSON case.
+        throw {
+            code: "WORKFLOW_GRAPH_INVALID",
+            message: `Could not read/parse task graph at ${filePath}: ${error instanceof Error ? error.message : String(error)}`,
+            details: "Expected a JSON file matching the daemon's task-graph shape.",
+        };
+    }
+    // `Object.hasOwn`, never truthiness: `version: 0`, `version: null` and `version: "1"`
+    // are all definitions their author got wrong, and they must reach the definition
+    // parser's version gate. A truthiness check would send them down the task-graph
+    // branch, which reports a graph-shape error about a file nobody wrote as a graph.
+    const isDefinition = typeof parsed === "object" &&
+        parsed !== null &&
+        !Array.isArray(parsed) &&
+        Object.hasOwn(parsed, "version");
+    return isDefinition ? { kind: "definition", raw: parsed } : { kind: "task-graph", raw: parsed };
+}
+/** The six spellings `boolean` accepts, listed once so the check and the message agree. */
+const TRUE_SPELLINGS = ["true", "1", "yes"];
+const FALSE_SPELLINGS = ["false", "0", "no"];
+/**
+ * Turn `--input KEY=VALUE` flags into values typed per the definition's declared inputs.
+ *
+ * Returns every issue rather than throwing on the first, mirroring `validateLoopParams`:
+ * an author with three bad flags fixes them once instead of re-running to discover the
+ * next one. Never returns early.
+ *
+ * It owns exactly three failure classes - flag syntax, undeclared key, and coercion to
+ * the declared type. It deliberately does NOT call `validateLoopParams`: `required`,
+ * `min`, `max` and `enum` membership are the compiler's single pass, and running them
+ * here as well would report the same mistake twice in one run. For the same reason an
+ * undeclared key is reported here AND withheld from `values`, so the compiler's own
+ * undeclared-key check never sees it and cannot double-report it.
+ */
+export function parseInputFlags(flags, fields) {
+    const values = {};
+    const issues = [];
+    const byKey = new Map(fields.map((field) => [field.key, field]));
+    // Sorted once: the declared-key list is embedded in an error message, and a message
+    // whose word order depends on declaration order is not assertable.
+    const declaredKeys = [...byKey.keys()].sort();
+    const declaredSuffix = declaredKeys.length > 0
+        ? `Declared inputs are: ${declaredKeys.join(", ")}.`
+        : "This definition declares no inputs.";
+    for (const flag of flags) {
+        // First `=` only, so a value containing `=` survives intact: NOTE=a=b is "a=b".
+        const eq = flag.indexOf("=");
+        if (eq === -1) {
+            issues.push({
+                path: "--input",
+                message: `"${flag}" is not KEY=VALUE. Pass an input as --input KEY=VALUE.`,
+            });
+            continue;
+        }
+        const key = flag.slice(0, eq).trim();
+        const text = flag.slice(eq + 1);
+        const field = byKey.get(key);
+        if (!field) {
+            issues.push({
+                path: `inputs[${key}]`,
+                message: `"${key}" is not an input this definition declares. ${declaredSuffix}`,
+            });
+            continue;
+        }
+        const coerced = coerceInputValue(field, text);
+        if (!coerced.ok) {
+            issues.push({ path: `inputs[${key}]`, message: coerced.message });
+            continue;
+        }
+        // Last wins on a repeated key, by plain assignment. Repeating a flag is how every
+        // other repeatable option in this CLI behaves and is not an issue on its own.
+        values[key] = coerced.value;
+    }
+    return { values, issues };
+}
+/**
+ * Coerce one flag's text to one field's declared type.
+ *
+ * A `switch` over the closed type vocabulary rather than a chain of `if`s, so every
+ * branch is forced to name its own failure text and a new param type fails to compile
+ * here instead of silently falling through to "string".
+ */
+function coerceInputValue(field, text) {
+    switch (field.type) {
+        case "string":
+            // Verbatim, not trimmed: leading or trailing space in a value destined for a
+            // prompt is the author's business, not the CLI's.
+            return { ok: true, value: text };
+        case "enum":
+            // Also verbatim. Membership against `options` is the compiler's check, so a bad
+            // choice is reported once, there, with the allowed values listed.
+            return { ok: true, value: text };
+        case "number":
+            return coerceNumber(field, text);
+        case "boolean":
+            return coerceBoolean(field, text);
+        case "string-list":
+            return {
+                ok: true,
+                value: text
+                    .trim()
+                    .split(",")
+                    .map((entry) => entry.trim())
+                    .filter((entry) => entry.length > 0),
+            };
+    }
+}
+function coerceNumber(field, text) {
+    const trimmed = text.trim();
+    // The empty check comes FIRST and that ordering is the whole point: `Number("")` is
+    // `0`, so `--input COUNT=` would otherwise launch a workflow with a count of zero the
+    // author never typed. An empty number is not a value; an omitted flag is.
+    if (trimmed.length === 0) {
+        return { ok: false, message: `${field.label} was passed with no value; expected a number.` };
+    }
+    const parsed = Number(trimmed);
+    if (!Number.isFinite(parsed)) {
+        return { ok: false, message: `${field.label} must be a number; got "${text}".` };
+    }
+    return { ok: true, value: parsed };
+}
+function coerceBoolean(field, text) {
+    const normalized = text.trim().toLowerCase();
+    if (TRUE_SPELLINGS.includes(normalized)) {
+        return { ok: true, value: true };
+    }
+    if (FALSE_SPELLINGS.includes(normalized)) {
+        return { ok: true, value: false };
+    }
+    return {
+        ok: false,
+        message: `${field.label} must be one of: ${[...TRUE_SPELLINGS, ...FALSE_SPELLINGS].join(", ")}; got "${text}".`,
+    };
+}
+//# sourceMappingURL=definition-file.js.map

package/dist/commands/workflow/start.d.ts

@@ -12,6 +12,7 @@ export interface WorkflowStartOptions extends CommandOptions {
     cwd?: string;
     title?: string;
     detach?: boolean;
+    input?: string[];
 }
 export declare function addWorkflowStartOptions(command: Command): Command;
 /**
@@ -21,6 +22,6 @@ export declare function addWorkflowStartOptions(command: Command): Command;
  */
 export declare function buildWorkflowStatusUrl(host: string, workflowId: string): string;
 export type WorkflowStartResult = SingleResult<StartRow>;
-export declare function runWorkflowStartCommand(graphPath: string, options: WorkflowStartOptions, _command: Command): Promise<WorkflowStartResult>;
+export declare function runWorkflowStartCommand(filePath: string, options: WorkflowStartOptions, _command: Command): Promise<WorkflowStartResult>;
 export {};
 //# sourceMappingURL=start.d.ts.map

package/dist/commands/workflow/start.js

@@ -1,6 +1,11 @@
-import { readFileSync } from "node:fs";
-import { WorkflowTaskGraphSchema } from "@hyperdrive.bot/paseo-protocol/messages";
+import { randomUUID } from "node:crypto";
+import { WorkflowTaskGraphSchema, } from "@hyperdrive.bot/paseo-protocol/messages";
+import { defaultLoopParams } from "@hyperdrive.bot/paseo-protocol/fleet/params";
+import { parseWorkflowDefinition, WorkflowDefinitionError, } from "@hyperdrive.bot/paseo-protocol/workflow/definition";
+import { compileWorkflowDefinition } from "@hyperdrive.bot/paseo-protocol/workflow/compile";
 import { connectToDaemon, getDaemonHost } from "../../utils/client.js";
+import { collectMultiple } from "../../utils/command-options.js";
+import { parseInputFlags, readWorkflowStartFile } from "./definition-file.js";
 const startSchema = {
     idField: "workflowId",
     columns: [
@@ -16,8 +21,9 @@ const startSchema = {
 };
 export function addWorkflowStartOptions(command) {
     return command
-        .description("Launch a pre-built task-graph into the daemon (thin client)")
-        .argument("<graph>", "Path to a task-graph JSON file")
+        .description("Launch a workflow definition (compiled here) or a pre-built task-graph into the daemon")
+        .argument("<file>", "Path to a workflow definition (YAML or JSON) or a pre-built task-graph JSON file")
+        .option("--input <key=value>", "Definition input value (repeatable)", collectMultiple, [])
         .option("--provider <provider>", "Agent provider each child runs (default: claude)")
         .option("--model <model>", "Optional provider model each child is spawned with")
         .option("--cwd <dir>", "Working directory all child agents inherit (default: cwd)")
@@ -46,21 +52,95 @@ export function buildWorkflowStatusUrl(host, workflowId) {
     const scheme = trimmed.includes("ssl=true") ? "https" : "http";
     return `${scheme}://${authority}/api/workflows/${workflowId}`;
 }
-export async function runWorkflowStartCommand(graphPath, options, _command) {
-    // Parse + validate the task-graph file client-side for a clean error message;
-    // the daemon re-validates against the same schema at the parse boundary.
-    let graph;
+/** One rendering of an issue list into `CommandError.details`, so the throw sites cannot drift. */
+function issuesToDetails(issues) {
+    return issues.map((issue) => `${issue.path}: ${issue.message}`);
+}
+/**
+ * The pre-built path: today's behaviour, unchanged, plus one refusal.
+ *
+ * `--input` here is an error rather than a no-op. A task graph has no `inputs:`
+ * vocabulary, so accepting the flag and discarding it would read as configured and
+ * behave as absent — the exact silent acceptance this command exists to refuse.
+ */
+function resolveTaskGraph(filePath, raw, inputFlags) {
+    if (inputFlags.length > 0) {
+        throw {
+            code: "WORKFLOW_INPUT_INVALID",
+            message: `--input is only supported for workflow definitions; ${filePath} is a pre-built task graph (no top-level "version" key).`,
+            details: inputFlags,
+        };
+    }
     try {
-        const raw = readFileSync(graphPath, "utf-8");
-        graph = WorkflowTaskGraphSchema.parse(JSON.parse(raw));
+        return { graph: WorkflowTaskGraphSchema.parse(raw) };
     }
     catch (error) {
         throw {
             code: "WORKFLOW_GRAPH_INVALID",
-            message: `Could not read/parse task graph at ${graphPath}: ${error instanceof Error ? error.message : String(error)}`,
+            message: `Could not read/parse task graph at ${filePath}: ${error instanceof Error ? error.message : String(error)}`,
             details: "Expected a JSON file matching the daemon's task-graph shape.",
         };
     }
+}
+/** Parse the definition, read the flags, compile — in that order, each reporting every issue. */
+function resolveDefinition(filePath, raw, inputFlags, options) {
+    const parsed = parseWorkflowDefinition(raw);
+    if (!parsed.ok) {
+        throw {
+            code: "WORKFLOW_DEFINITION_INVALID",
+            message: `Workflow definition at ${filePath} is invalid (${parsed.issues.length} issue(s)).`,
+            details: issuesToDetails(parsed.issues),
+        };
+    }
+    const definition = parsed.definition;
+    const flags = parseInputFlags(inputFlags, definition.inputs);
+    if (flags.issues.length > 0) {
+        throw {
+            code: "WORKFLOW_INPUT_INVALID",
+            message: `Could not read --input values for ${filePath} (${flags.issues.length} issue(s)).`,
+            details: issuesToDetails(flags.issues),
+        };
+    }
+    // Flags on the RIGHT: a supplied --input always beats a declared default.
+    const values = { ...defaultLoopParams({ fields: definition.inputs }), ...flags.values };
+    try {
+        // The compiler is pure by contract, so the three ambient values it needs are
+        // stamped here — the CLI is the only layer allowed to read a clock, a uuid or the
+        // process cwd. `session.id` is NOT the workflow id; the daemon mints its own.
+        return compileWorkflowDefinition({
+            definition,
+            values,
+            session: {
+                id: randomUUID(),
+                createdAt: new Date().toISOString(),
+                outputDirectory: options.cwd ?? process.cwd(),
+            },
+        });
+    }
+    catch (error) {
+        // Anything that is not a definition error is a genuine bug and must keep its stack
+        // trace rather than be relabelled as user error.
+        if (!(error instanceof WorkflowDefinitionError))
+            throw error;
+        // One deterministic routing rule: all-`inputs[` paths means the values were wrong,
+        // anything else means the definition was. Either way every issue lands in `details`.
+        const allInputIssues = error.issues.every((issue) => issue.path.startsWith("inputs["));
+        throw {
+            code: allInputIssues ? "WORKFLOW_INPUT_INVALID" : "WORKFLOW_DEFINITION_INVALID",
+            message: `Could not compile workflow definition at ${filePath} (${error.issues.length} issue(s)).`,
+            details: issuesToDetails(error.issues),
+        };
+    }
+}
+export async function runWorkflowStartCommand(filePath, options, _command) {
+    // Read, compile and validate entirely client-side, BEFORE any socket is opened: a bad
+    // definition must fail with its issue list even when the daemon is down. The daemon
+    // re-validates the graph against the same schema at its own parse boundary.
+    const file = readWorkflowStartFile(filePath);
+    const inputFlags = options.input ?? [];
+    const { graph, agentPresets } = file.kind === "task-graph"
+        ? resolveTaskGraph(filePath, file.raw, inputFlags)
+        : resolveDefinition(filePath, file.raw, inputFlags, options);
     const host = getDaemonHost({ host: options.host });
     let client;
     try {
@@ -81,6 +161,8 @@ export async function runWorkflowStartCommand(graphPath, options, _command) {
             cwd: options.cwd ?? process.cwd(),
             ...(options.model ? { model: options.model } : {}),
             ...(options.title ? { title: options.title } : {}),
+            // Conditional so the task-graph branch's payload stays identical to today's.
+            ...(agentPresets && Object.keys(agentPresets).length > 0 ? { agentPresets } : {}),
         });
         await client.close();
         return {

package/dist/utils/client.d.ts

@@ -1,3 +1,4 @@
+import type { AgentSnapshotPayload } from "@hyperdrive.bot/paseo-protocol/messages";
 import { DaemonClient } from "@hyperdrive.bot/paseo-client/internal/daemon-client";
 export interface ConnectOptions {
     host?: string;
@@ -40,5 +41,37 @@ interface AgentLike {
  * Returns the full agent ID if found, null otherwise.
  */
 export declare function resolveAgentId(idOrName: string, agents: AgentLike[]): string | null;
+/** Minimal surface of `DaemonClient` needed to resolve an agent identifier. */
+export interface DaemonAgentFetcher {
+    fetchAgent(options: {
+        agentId: string;
+    }): Promise<{
+        agent: AgentSnapshotPayload;
+    } | null>;
+}
+/** Outcome of resolving an agent identifier through the daemon. */
+export type DaemonAgentResolution = {
+    ok: true;
+    agent: AgentSnapshotPayload;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Resolve an agent identifier (full ID, unambiguous ID prefix, or exact title)
+ * through the daemon and return the matching snapshot.
+ *
+ * Always prefer this over `fetchAgents()` + `resolveAgentId()`. `fetch_agents`
+ * is a PAGED rpc and the daemon caps a page at 200 entries by default
+ * (`request.page?.limit ?? 200` in the server session handler), so matching an
+ * identifier against a single unpaged response only ever searches the 200 most
+ * recently updated agents for that filter. On a host with more than 200 agents
+ * most valid IDs then resolve to "not found", and asking for
+ * `includeArchived: true` makes it strictly worse rather than better, because
+ * archived agents compete for the same 200 slots and push live ones out of the
+ * window. `fetch_agent` resolves server-side across the whole agent store with
+ * no cap, which is why `paseo agent inspect` never had this bug.
+ */
+export declare function resolveAgentViaDaemon(client: DaemonAgentFetcher, idOrName: string): Promise<DaemonAgentResolution>;
 export {};
 //# sourceMappingURL=client.d.ts.map

package/dist/utils/client.js

@@ -327,4 +327,39 @@ export function resolveAgentId(idOrName, agents) {
     }
     return null;
 }
+/**
+ * Resolve an agent identifier (full ID, unambiguous ID prefix, or exact title)
+ * through the daemon and return the matching snapshot.
+ *
+ * Always prefer this over `fetchAgents()` + `resolveAgentId()`. `fetch_agents`
+ * is a PAGED rpc and the daemon caps a page at 200 entries by default
+ * (`request.page?.limit ?? 200` in the server session handler), so matching an
+ * identifier against a single unpaged response only ever searches the 200 most
+ * recently updated agents for that filter. On a host with more than 200 agents
+ * most valid IDs then resolve to "not found", and asking for
+ * `includeArchived: true` makes it strictly worse rather than better, because
+ * archived agents compete for the same 200 slots and push live ones out of the
+ * window. `fetch_agent` resolves server-side across the whole agent store with
+ * no cap, which is why `paseo agent inspect` never had this bug.
+ */
+export async function resolveAgentViaDaemon(client, idOrName) {
+    const trimmed = idOrName.trim();
+    if (!trimmed) {
+        return { ok: false, error: "Agent identifier cannot be empty" };
+    }
+    try {
+        const result = await client.fetchAgent({ agentId: trimmed });
+        if (!result) {
+            return { ok: false, error: `Agent not found: ${trimmed}` };
+        }
+        return { ok: true, agent: result.agent };
+    }
+    catch (err) {
+        // The daemon reports "not found" AND "ambiguous prefix/title" as an error
+        // payload on fetch_agent_response, which the client rethrows. Surfacing its
+        // message verbatim is an improvement on the old client-side resolver, which
+        // silently picked the first match for an ambiguous prefix.
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
 //# sourceMappingURL=client.js.map

package/dist/utils/duration.d.ts

@@ -1,6 +1,6 @@
 /**
  * Parse duration string to milliseconds.
- * Supports formats like: 5m, 30s, 1h, 2h30m, 90, etc.
+ * Supports formats like: 5m, 30s, 1h, 2h30m, 1d, 90, etc.
  * If no unit is specified, assumes seconds.
  */
 export declare function parseDuration(input: string): number;

package/dist/utils/duration.js

@@ -1,6 +1,6 @@
 /**
  * Parse duration string to milliseconds.
- * Supports formats like: 5m, 30s, 1h, 2h30m, 90, etc.
+ * Supports formats like: 5m, 30s, 1h, 2h30m, 1d, 90, etc.
  * If no unit is specified, assumes seconds.
  */
 export function parseDuration(input) {
@@ -11,7 +11,7 @@ export function parseDuration(input) {
     }
     // Parse duration with units
     let totalMs = 0;
-    const regex = /(\d+)([smh])/g;
+    const regex = /(\d+)([smhd])/g;
     let match;
     let hasMatch = false;
     while ((match = regex.exec(trimmed)) !== null) {
@@ -28,10 +28,13 @@ export function parseDuration(input) {
             case "h":
                 totalMs += value * 60 * 60 * 1000;
                 break;
+            case "d":
+                totalMs += value * 24 * 60 * 60 * 1000;
+                break;
         }
     }
     if (!hasMatch) {
-        throw new Error(`Invalid duration format: ${input}. Use formats like: 5m, 30s, 1h, 2h30m`);
+        throw new Error(`Invalid duration format: ${input}. Use formats like: 5m, 30s, 1h, 2h30m, 1d`);
     }
     return totalMs;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperdrive.bot/paseo-cli",
-  "version": "0.3.42",
+  "version": "0.3.43",
   "description": "Paseo CLI - control your AI coding agents from the command line",
   "bin": {
     "paseo": "bin/paseo"
@@ -27,9 +27,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.0.0",
-    "@hyperdrive.bot/paseo-client": "0.3.42",
-    "@hyperdrive.bot/paseo-protocol": "0.3.42",
-    "@hyperdrive.bot/paseo-server": "0.3.42",
+    "@hyperdrive.bot/paseo-client": "0.3.43",
+    "@hyperdrive.bot/paseo-protocol": "0.3.43",
+    "@hyperdrive.bot/paseo-server": "0.3.43",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "mime-types": "^2.1.35",