@openclaw/lobster 2026.9.5 → 2026.9.7

package/dist/index.js

@@ -1,12 +1,12 @@
 import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
-import { optionalNonNegativeIntegerSchema, optionalPositiveIntegerSchema } from "openclaw/plugin-sdk/channel-actions";
-import { readNonNegativeIntegerParam, readPositiveIntegerParam } from "openclaw/plugin-sdk/param-readers";
+import { optionalPositiveIntegerSchema } from "openclaw/plugin-sdk/channel-actions";
+import { readPositiveIntegerParam } from "openclaw/plugin-sdk/param-readers";
 import { jsonResult } from "openclaw/plugin-sdk/tool-results";
 import { Type } from "typebox";
 import { stat } from "node:fs/promises";
 import path from "node:path";
 import { Readable, Writable } from "node:stream";
-import { toErrorObject } from "openclaw/plugin-sdk/error-runtime";
+import { extractErrorCode, toErrorObject } from "openclaw/plugin-sdk/error-runtime";
 import { isPathInside } from "openclaw/plugin-sdk/file-access-runtime";
 //#region extensions/lobster/src/lobster-runner.ts
 const workflowExts = /* @__PURE__ */ new Set([
@@ -53,9 +53,6 @@ function normalizeEnvelope(envelope, maxStdoutBytes) {
 	if (Buffer.byteLength(JSON.stringify(normalized, null, 2), "utf8") > maxStdoutBytes) throw new Error("lobster runtime result exceeded maxStdoutBytes");
 	return normalized;
 }
-function isMissingPathError(error) {
-	return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
-}
 async function detectWorkflowFile(candidate, cwd) {
 	const trimmed = candidate.trim();
 	if (!trimmed || trimmed.includes("|") || !workflowExts.has(path.extname(trimmed).toLowerCase())) return null;
@@ -64,7 +61,7 @@ async function detectWorkflowFile(candidate, cwd) {
 		if (!(await stat(resolved)).isFile()) throw new Error("Workflow path is not a file");
 		return resolved;
 	} catch (error) {
-		if (/\s/.test(trimmed) && isMissingPathError(error)) return null;
+		if (/\s/.test(trimmed) && extractErrorCode(error) === "ENOENT") return null;
 		throw error;
 	}
 }
@@ -153,257 +150,7 @@ function createEmbeddedLobsterRunner(options) {
 	} };
 }
 //#endregion
-//#region extensions/lobster/src/lobster-taskflow.ts
-function toJsonLike(value, seen = /* @__PURE__ */ new WeakSet()) {
-	if (value === null) return null;
-	if (typeof value === "number") return Number.isFinite(value) ? value : String(value);
-	if (typeof value === "bigint") return value.toString();
-	if (typeof value === "boolean" || typeof value === "string") return value;
-	if (typeof value !== "object") return null;
-	if (value instanceof Date) return value.toISOString();
-	if (seen.has(value)) return "[Circular]";
-	seen.add(value);
-	if (Array.isArray(value)) {
-		const jsonArray = value.map((item) => toJsonLike(item, seen));
-		seen.delete(value);
-		return jsonArray;
-	}
-	const jsonObject = {};
-	for (const [key, entry] of Object.entries(value)) {
-		if (entry === void 0 || typeof entry === "function" || typeof entry === "symbol") continue;
-		jsonObject[key] = toJsonLike(entry, seen);
-	}
-	seen.delete(value);
-	return jsonObject;
-}
-function buildApprovalWaitState(envelope) {
-	const approval = envelope.requiresApproval;
-	return {
-		kind: "lobster_approval",
-		prompt: approval ? approval.prompt : "",
-		items: approval ? approval.items.map((item) => toJsonLike(item)) : [],
-		...approval?.resumeToken ? { resumeToken: approval.resumeToken } : {},
-		...approval?.approvalId ? { approvalId: approval.approvalId } : {}
-	};
-}
-async function executeManagedLobsterFlow(params, flow) {
-	try {
-		const envelope = await params.runner.run(params.runnerParams);
-		if (envelope.ok && envelope.status === "cancelled") try {
-			const mutation = await params.taskFlow.cancel({
-				flowId: flow.flowId,
-				cfg: params.config
-			});
-			return mutation.cancelled ? {
-				ok: true,
-				envelope,
-				flow,
-				mutation
-			} : {
-				ok: false,
-				flow,
-				mutation,
-				error: /* @__PURE__ */ new Error(`TaskFlow cancellation failed: ${mutation.reason ?? "unknown"}`)
-			};
-		} catch (error) {
-			return {
-				ok: false,
-				flow,
-				error: error instanceof Error ? error : new Error(String(error))
-			};
-		}
-		const flowMutation = {
-			flowId: flow.flowId,
-			expectedRevision: flow.revision
-		};
-		if (!envelope.ok) return {
-			ok: false,
-			flow,
-			mutation: await params.taskFlow.fail(flowMutation),
-			error: new Error(envelope.error.message)
-		};
-		return {
-			ok: true,
-			envelope,
-			flow,
-			mutation: envelope.status === "needs_approval" ? await params.taskFlow.setWaiting({
-				...flowMutation,
-				currentStep: params.waitingStep ?? "await_lobster_approval",
-				waitJson: buildApprovalWaitState(envelope)
-			}) : await params.taskFlow.finish(flowMutation)
-		};
-	} catch (error) {
-		const err = error instanceof Error ? error : new Error(String(error));
-		try {
-			return {
-				ok: false,
-				flow,
-				mutation: await params.taskFlow.fail({
-					flowId: flow.flowId,
-					expectedRevision: flow.revision
-				}),
-				error: err
-			};
-		} catch {
-			return {
-				ok: false,
-				flow,
-				error: err
-			};
-		}
-	}
-}
-async function runManagedLobsterFlow(params) {
-	const createFlowParams = {
-		controllerId: params.controllerId,
-		goal: params.goal,
-		currentStep: params.currentStep ?? "run_lobster",
-		...params.stateJson !== void 0 ? { stateJson: params.stateJson } : {}
-	};
-	const flow = await params.taskFlow.tryCreateManaged(createFlowParams);
-	if (!flow) return {
-		ok: false,
-		error: /* @__PURE__ */ new Error("TaskFlow persistence failed.")
-	};
-	return await executeManagedLobsterFlow(params, flow);
-}
-async function resumeManagedLobsterFlow(params) {
-	const saved = await params.taskFlow.get(params.flowId);
-	if (!saved || saved.syncMode !== "managed" || saved.endedAt !== void 0 || saved.cancelRequestedAt !== void 0 || saved.status !== "waiting" && saved.status !== "blocked") return {
-		ok: false,
-		error: /* @__PURE__ */ new Error("TaskFlow has no resumable Lobster checkpoint.")
-	};
-	const wait = saved.waitJson;
-	if (!wait || typeof wait !== "object" || Array.isArray(wait) || wait.kind !== "lobster_approval") return {
-		ok: false,
-		error: /* @__PURE__ */ new Error("TaskFlow is not waiting for Lobster approval.")
-	};
-	const token = typeof wait.resumeToken === "string" ? wait.resumeToken : void 0;
-	const approvalId = typeof wait.approvalId === "string" ? wait.approvalId : void 0;
-	if (!token && !approvalId || params.runnerParams.token !== void 0 && params.runnerParams.token.trim() !== token || params.runnerParams.approvalId !== void 0 && params.runnerParams.approvalId.trim() !== approvalId) return {
-		ok: false,
-		error: /* @__PURE__ */ new Error("Lobster checkpoint does not match the selected TaskFlow.")
-	};
-	const runnerParams = {
-		...params.runnerParams,
-		...params.runnerParams.token || params.runnerParams.approvalId ? {} : token ? { token } : { approvalId }
-	};
-	if (saved.revision !== params.expectedRevision) return {
-		ok: false,
-		error: /* @__PURE__ */ new Error("TaskFlow resume failed: revision_conflict")
-	};
-	const resumed = await params.taskFlow.resume({
-		flowId: params.flowId,
-		expectedRevision: params.expectedRevision,
-		status: "running",
-		currentStep: params.currentStep ?? "resume_lobster"
-	});
-	if (!resumed.applied) return {
-		ok: false,
-		mutation: resumed,
-		error: /* @__PURE__ */ new Error(`TaskFlow resume failed: ${resumed.code}`)
-	};
-	return await executeManagedLobsterFlow({
-		...params,
-		runnerParams
-	}, resumed.flow);
-}
-//#endregion
 //#region extensions/lobster/src/lobster-tool.ts
-function readOptionalTrimmedString(value, fieldName) {
-	if (value === void 0) return;
-	if (typeof value !== "string") throw new Error(`${fieldName} must be a string`);
-	const trimmed = value.trim();
-	return trimmed ? trimmed : void 0;
-}
-function readOptionalNumber(value, fieldName) {
-	return readNonNegativeIntegerParam({ [fieldName]: value }, fieldName, { message: `${fieldName} must be a non-negative integer` });
-}
-function readOptionalBoolean(value, fieldName) {
-	if (value === void 0) return;
-	if (typeof value !== "boolean") throw new Error(`${fieldName} must be a boolean`);
-	return value;
-}
-function parseOptionalFlowStateJson(value) {
-	if (value === void 0) return;
-	if (typeof value !== "string") throw new Error("flowStateJson must be a JSON string");
-	const trimmed = value.trim();
-	if (!trimmed) return;
-	try {
-		return JSON.parse(trimmed);
-	} catch {
-		throw new Error("flowStateJson must be valid JSON");
-	}
-}
-function isEmptyJsonObject(value) {
-	return value !== void 0 && value !== null && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length === 0;
-}
-function parseManagedFlowParams(action, params, runnerParams) {
-	if (action === "run") {
-		const controllerId = readOptionalTrimmedString(params.flowControllerId, "flowControllerId");
-		const goal = readOptionalTrimmedString(params.flowGoal, "flowGoal");
-		const currentStep = readOptionalTrimmedString(params.flowCurrentStep, "flowCurrentStep");
-		const waitingStep = readOptionalTrimmedString(params.flowWaitingStep, "flowWaitingStep");
-		const stateJson = parseOptionalFlowStateJson(params.flowStateJson);
-		const resumeFlowId = readOptionalTrimmedString(params.flowId, "flowId");
-		const resumeRevision = readOptionalNumber(params.flowExpectedRevision, "flowExpectedRevision");
-		const stateJsonSignalsRunMode = stateJson !== void 0 && !isEmptyJsonObject(stateJson);
-		if (resumeFlowId !== void 0 || resumeRevision !== void 0 && resumeRevision !== 0) throw new Error("run action does not accept flowId or flowExpectedRevision");
-		if (controllerId === void 0 && goal === void 0 && currentStep === void 0 && waitingStep === void 0 && !stateJsonSignalsRunMode) return null;
-		if (!controllerId) throw new Error("flowControllerId required when using managed TaskFlow run mode");
-		if (!goal) throw new Error("flowGoal required when using managed TaskFlow run mode");
-		return {
-			action,
-			controllerId,
-			goal,
-			...currentStep ? { currentStep } : {},
-			...waitingStep ? { waitingStep } : {},
-			...stateJson !== void 0 ? { stateJson } : {}
-		};
-	}
-	const flowId = readOptionalTrimmedString(params.flowId, "flowId");
-	const expectedRevision = readOptionalNumber(params.flowExpectedRevision, "flowExpectedRevision");
-	const currentStep = readOptionalTrimmedString(params.flowCurrentStep, "flowCurrentStep");
-	const waitingStep = readOptionalTrimmedString(params.flowWaitingStep, "flowWaitingStep");
-	const token = readOptionalTrimmedString(params.token, "token");
-	const approvalId = readOptionalTrimmedString(params.approvalId, "approvalId");
-	const approve = readOptionalBoolean(params.approve, "approve");
-	const runControllerId = readOptionalTrimmedString(params.flowControllerId, "flowControllerId");
-	const runGoal = readOptionalTrimmedString(params.flowGoal, "flowGoal");
-	const stateJson = parseOptionalFlowStateJson(params.flowStateJson);
-	const stateJsonDisallowed = stateJson !== void 0 && !isEmptyJsonObject(stateJson);
-	if (runControllerId !== void 0 || runGoal !== void 0 || stateJsonDisallowed) throw new Error("resume action does not accept flowControllerId, flowGoal, or flowStateJson");
-	if (!(flowId !== void 0 || expectedRevision !== void 0 && expectedRevision !== 0 || currentStep !== void 0 || waitingStep !== void 0)) return null;
-	if (!flowId) throw new Error("flowId required when using managed TaskFlow resume mode");
-	if (expectedRevision === void 0) throw new Error("flowExpectedRevision required when using managed TaskFlow resume mode");
-	const credentialParams = token ? { token: runnerParams.token ?? token } : approvalId ? { approvalId: runnerParams.approvalId ?? approvalId } : null;
-	if (approve === void 0) throw new Error("approve required when using managed TaskFlow resume mode");
-	return {
-		action,
-		flowId,
-		expectedRevision,
-		...currentStep ? { currentStep } : {},
-		...waitingStep ? { waitingStep } : {},
-		runnerParams: {
-			...runnerParams,
-			...credentialParams,
-			action,
-			approve
-		}
-	};
-}
-function resolveManagedFlowToolResult(result) {
-	if (!result.ok) throw result.error;
-	return jsonResult({
-		...result.envelope,
-		flow: result.flow,
-		mutation: result.mutation
-	});
-}
-function requireTaskFlowRuntime(taskFlow, action) {
-	if (!taskFlow) throw new Error(`Managed TaskFlow ${action} mode requires a bound taskFlow runtime`);
-	return taskFlow;
-}
 function createLobsterTool(api, options) {
 	const runner = options?.runner ?? createEmbeddedLobsterRunner();
 	return {
@@ -419,14 +166,7 @@ function createLobsterTool(api, options) {
 			approve: Type.Optional(Type.Boolean()),
 			cwd: Type.Optional(Type.String({ description: "Relative working directory (optional). Must stay within the gateway working directory." })),
 			timeoutMs: optionalPositiveIntegerSchema(),
-			maxStdoutBytes: optionalPositiveIntegerSchema(),
-			flowControllerId: Type.Optional(Type.String()),
-			flowGoal: Type.Optional(Type.String()),
-			flowStateJson: Type.Optional(Type.String()),
-			flowId: Type.Optional(Type.String({ description: "Managed flow to resume. Its saved approval checkpoint is used when token and approvalId are omitted." })),
-			flowExpectedRevision: optionalNonNegativeIntegerSchema(),
-			flowCurrentStep: Type.Optional(Type.String()),
-			flowWaitingStep: Type.Optional(Type.String())
+			maxStdoutBytes: optionalPositiveIntegerSchema()
 		}),
 		async execute(_id, params) {
 			const action = typeof params.action === "string" ? params.action.trim() : "";
@@ -447,29 +187,6 @@ function createLobsterTool(api, options) {
 				timeoutMs,
 				maxStdoutBytes
 			};
-			const taskFlow = options?.taskFlow;
-			const flowParams = parseManagedFlowParams(action, params, runnerParams);
-			if (flowParams?.action === "run") return resolveManagedFlowToolResult(await runManagedLobsterFlow({
-				taskFlow: requireTaskFlowRuntime(taskFlow, "run"),
-				config: api.config,
-				runner,
-				runnerParams,
-				controllerId: flowParams.controllerId,
-				goal: flowParams.goal,
-				...flowParams.stateJson !== void 0 ? { stateJson: flowParams.stateJson } : {},
-				...flowParams.currentStep ? { currentStep: flowParams.currentStep } : {},
-				...flowParams.waitingStep ? { waitingStep: flowParams.waitingStep } : {}
-			}));
-			if (flowParams?.action === "resume") return resolveManagedFlowToolResult(await resumeManagedLobsterFlow({
-				taskFlow: requireTaskFlowRuntime(taskFlow, "resume"),
-				config: api.config,
-				runner,
-				runnerParams: flowParams.runnerParams,
-				flowId: flowParams.flowId,
-				expectedRevision: flowParams.expectedRevision,
-				...flowParams.currentStep ? { currentStep: flowParams.currentStep } : {},
-				...flowParams.waitingStep ? { waitingStep: flowParams.waitingStep } : {}
-			}));
 			const envelope = await runner.run(runnerParams);
 			if (!envelope.ok) throw new Error(envelope.error.message);
 			return jsonResult(envelope);
@@ -483,13 +200,10 @@ var lobster_default = definePluginEntry({
 	name: "Lobster",
 	description: "Optional local shell helper tools",
 	register(api) {
-		api.registerTool(((ctx) => {
+		api.registerTool((ctx) => {
 			if (ctx.sandboxed) return null;
-			return createLobsterTool(api, { taskFlow: api.runtime && ctx.sessionKey ? {
-				...api.runtime.tasks.async.managedFlows.fromToolContext(ctx),
-				cancel: api.runtime.tasks.managedFlows.fromToolContext(ctx).cancel
-			} : void 0 });
-		}), { optional: true });
+			return createLobsterTool(api);
+		}, { optional: true });
 	}
 });
 //#endregion

package/node_modules/@clawdbot/lobster/README.md

@@ -2,139 +2,20 @@
 
 ![Lobster banner](docs/assets/readme-banner.jpg)
 
-An OpenClaw-native workflow shell: typed (JSON-first) pipelines, jobs, and approval gates.
+An OpenClaw-native workflow shell: typed (JSON-first) pipelines and approval gates.
 
+## Example
 
-## Example of Lobster at work
-OpenClaw (or any other AI agent) can use `lobster` as a workflow engine and avoid re-planning every step — saving tokens while improving determinism and resumability.
+A named workflow fetches a pull request with `gh`, compares it with the saved snapshot, and returns a notification only when it changes:
 
-### Watching a PR that hasn't had changes
-```
-node bin/lobster.js "workflows.run --name github.pr.monitor --args-json '{\"repo\":\"openclaw/openclaw\",\"pr\":1152}'"
-[
-  {
-    "kind": "github.pr.monitor",
-    "repo": "openclaw/openclaw",
-    "prNumber": 1152,
-    "key": "github.pr:openclaw/openclaw#1152",
-    "changed": false,
-    "summary": {
-      "changedFields": [],
-      "changes": {}
-    },
-    "prSnapshot": {
-      "author": {
-        "id": "MDQ6VXNlcjE0MzY4NTM=",
-        "is_bot": false,
-        "login": "vignesh07",
-        "name": "Vignesh"
-      },
-      "baseRefName": "main",
-      "headRefName": "feat/lobster-plugin",
-      "isDraft": false,
-      "mergeable": "MERGEABLE",
-      "number": 1152,
-      "reviewDecision": "",
-      "state": "OPEN",
-      "title": "feat: Add optional lobster plugin tool (typed workflows, approvals/resume)",
-      "updatedAt": "2026-01-18T20:16:56Z",
-      "url": "https://github.com/openclaw/openclaw/pull/1152"
-    }
-  }
-]
+```bash
+node bin/lobster.js run --mode tool "workflows.run --name github.pr.monitor.notify --args-json '{\"repo\":\"openclaw/lobster\",\"pr\":167}'"
 ```
-### And a PR that has a state change (in this case an approved PR)
 
-```
- node bin/lobster.js "workflows.run --name github.pr.monitor --args-json '{\"repo\":\"openclaw/openclaw\",\"pr\":1200}'"
-[
-  {
-    "kind": "github.pr.monitor",
-    "repo": "openclaw/openclaw",
-    "prNumber": 1200,
-    "key": "github.pr:openclaw/openclaw#1200",
-    "changed": true,
-    "summary": {
-      "changedFields": [
-        "number",
-        "title",
-        "url",
-        "state",
-        "isDraft",
-        "mergeable",
-        "reviewDecision",
-        "updatedAt",
-        "baseRefName",
-        "headRefName"
-      ],
-      "changes": {
-        "number": {
-          "from": null,
-          "to": 1200
-        },
-        "title": {
-          "from": null,
-          "to": "feat(tui): add syntax highlighting for code blocks"
-        },
-        "url": {
-          "from": null,
-          "to": "https://github.com/openclaw/openclaw/pull/1200"
-        },
-        "state": {
-          "from": null,
-          "to": "MERGED"
-        },
-        "isDraft": {
-          "from": null,
-          "to": false
-        },
-        "mergeable": {
-          "from": null,
-          "to": "UNKNOWN"
-        },
-        "reviewDecision": {
-          "from": null,
-          "to": ""
-        },
-        "updatedAt": {
-          "from": null,
-          "to": "2026-01-19T05:06:09Z"
-        },
-        "baseRefName": {
-          "from": null,
-          "to": "main"
-        },
-        "headRefName": {
-          "from": null,
-          "to": "feat/tui-syntax-highlighting"
-        }
-      }
-    },
-    "prSnapshot": {
-      "author": {
-        "id": "MDQ6VXNlcjE0MzY4NTM=",
-        "is_bot": false,
-        "login": "vignesh07",
-        "name": "Vignesh"
-      },
-      "baseRefName": "main",
-      "headRefName": "feat/tui-syntax-highlighting",
-      "isDraft": false,
-      "mergeable": "UNKNOWN",
-      "number": 1200,
-      "reviewDecision": "",
-      "state": "MERGED",
-      "title": "feat(tui): add syntax highlighting for code blocks",
-      "updatedAt": "2026-01-19T05:06:09Z",
-      "url": "https://github.com/openclaw/openclaw/pull/1200"
-    }
-  }
-]
-```
+For repeatable automation, put shell commands, native pipeline steps, and explicit approval/input gates in a workflow file. OpenClaw presents the gate to the user and resumes with their decision.
 
 ## Goals
 
-
 - Typed pipelines (objects/arrays), not text pipes.
 - Local-first execution.
 - No new auth surface: Lobster must not own OAuth/tokens.
@@ -142,9 +23,10 @@ node bin/lobster.js "workflows.run --name github.pr.monitor --args-json '{\"repo
 
 ## Quick start
 
-From this folder:
+Requires Node.js 22 or newer and the pnpm version pinned in `package.json`. From this folder:
 
-- `pnpm install`
+- `pnpm install --frozen-lockfile`
+- `pnpm build`
 - `pnpm test`
 - `pnpm lint`
 - `node ./bin/lobster.js --help`
@@ -154,7 +36,9 @@ From this folder:
 ### Notes
 
 - `pnpm test` runs `tsc` and then executes tests against `dist/`.
-- `bin/lobster.js` prefers the compiled entrypoint in `dist/` when present.
+- `bin/lobster.js` runs the compiled entrypoint in `dist/`; build after changing source files.
+Invalid explicit workflow file paths are reported as input errors (exit code 2). In `--mode tool`, these failures use the same JSON error envelope as other parsing errors.
+
 ## Process output limits
 
 Captured process stdout and stderr remain unlimited by default. Set
@@ -187,20 +71,16 @@ keep pipes open after overflow. Calls without an AbortSignal relay terminal
 interrupts to that group and retain the host's existing signal handlers or
 conventional interrupt exit status.
 
-
 ## Commands
 
 - `exec`: run OS commands
 - `exec --json <command...>`: parse subprocess stdout as JSON before the next stage
 - `exec --stdin raw|json|jsonl`: feed pipeline input into subprocess stdin
+- Explicit quoted empty arguments are retained by both pipeline `exec` and SDK `exec`. Invocation shims preserve argument punctuation without shell expansion.
 - `where`, `pick`, `head`: data shaping
 - `json`, `table`: renderers
 - `approve`: approval gate (TTY prompt or `--emit` for OpenClaw integration)
 
-## Next steps
-
-- OpenClaw integration: ship as an optional OpenClaw plugin tool.
-
 ## SDK cancellation
 
 Pass an `AbortSignal` to `new Lobster({ signal })` to cancel SDK `exec()` stages,
@@ -303,6 +183,7 @@ Commands are re-run on resume, so they must be idempotent until `requestInput` r
 Use `lobster graph` to inspect workflow structure before execution.
 
 ```bash
+lobster graph --help
 lobster graph --file path/to/workflow.lobster
 lobster graph --file path/to/workflow.lobster --format mermaid
 lobster graph --file path/to/workflow.lobster --format dot
@@ -462,3 +343,9 @@ The limit counts bytes read from the response stream, including decompressed
 content. A declared Content-Length over the limit is also rejected immediately.
 Tool dispatch remains non-retryable after an overflow, as with other
 post-dispatch errors; `llm.invoke` retains its existing retry policy.
+
+## Development
+
+The source is one TypeScript package. `src/core` contains the embeddable tool API, cost tracking, and LLM accounting; `src/sdk` provides pipeline composition; `src/commands` holds the command registry and standard library. Workflow loading, expressions, dry-run rendering, and execution live under `src/workflows`. `src/state` owns atomic file persistence, locks, and resume capabilities. GitHub SDK recipes and built-in workflows share transport and snapshot helpers.
+
+Run `pnpm test`, `pnpm typecheck`, and `pnpm lint` before submitting changes. Tests compile into `dist/test` and use Node's test runner; platform-specific process tests run only where their OS primitives exist. Dependencies observe the two-day release-age policy in `pnpm-workspace.yaml`.