fix(tasks)!: contain the server filesystem tasks by default

BREAKING CHANGE: `registerCommonTasks()` in the node and electron builds no
longer registers `FileGrepTask`, `FileLoaderTask` or `FileSedTask`. Call the
new `registerFileSystemTasks()` to restore them. Separately, a local path now
has to resolve inside `config.roots`, which defaults to `[process.cwd()]`
rather than to "anywhere"; pass explicit `roots`, or `allowAnyRoot: true`, to
read outside the working directory. The classes are exported unchanged — only
ambient registry availability and the containment default moved.

Two states existed and neither contained anything. `resolveLocalFilePath`
skipped containment whenever `roots` was `undefined`, on the stated grounds
that "the enforced control is the `filesystem:read` entitlement". It is not:
`TaskGraphRunner` consults an enforcer only under `enforceEntitlements`, and
`ENTITLEMENT_ENFORCER` has no default factory, so the flag without a
registered enforcer throws. Neither is a default. An embedder that called
`registerCommonTasks()` and ran a graph therefore had a task in the ambient
registry that read any path the process could open, and
`assertResolvedPathDeclared` did not narrow it — it recomputes the path from
the same input through the same resolver, so with no roots both sides agree
and every path passes.

`FileLoaderTask.server` was worse than the other two and is why the fix cannot
stop at `roots`: it declared no entitlement at all, honoured no roots, and
reached the filesystem through `url.slice(7)`, which neither percent-decodes
nor rejects a `file://` host. It now runs the same resolver and carries the
same `configSchema()` / static + instance `entitlements()` pair its siblings
do, with `metadata.url` still the caller's path so the output shape is
unchanged.

The registration split is the half that survives untrusted input. A serialized
node is built as `{...item.config, id, defaults}`, so a graph that names
`FileGrepTask` supplies its own config and can state `roots: ["/"]` itself —
no default this package picks constrains it. The only control left is the type
not resolving. The cwd default is the defence for the other case, a trusting
embedder that authored the graph itself.

Root resolution is also order-independent now. `realpathSync(root)` ran inside
the `some()` predicate, which short-circuits: `[good, missing]` returned true
without ever resolving the broken root while `[missing, good]` threw, on
identical input. Every root is resolved before any containment verdict, so a
misconfigured one fails always rather than sometimes — the deterministic
direction and the safer one.

The ~35 existing server tests that constructed these tasks with no `roots`
now state `roots: [testDir]`. That churn is the point: each one says which
directory it means to read.

Author: claude

packages/tasks/README.md

@@ -15,6 +15,7 @@ A package of task types for common operations, workflow management, and data pro
   - [LambdaTask](#lambdatask)
   - [JsonTask](#jsontask)
   - [ArrayTask](#arraytask)
+- [Filesystem Tasks (server builds)](#filesystem-tasks-server-builds)
 - [Workflow Integration](#workflow-integration)
 - [Error Handling](#error-handling)
 - [Configuration](#configuration)
@@ -563,6 +564,58 @@ const result = await task.run();
 - Combination generation for multiple array inputs
 - Seamless single-value and array handling
 
+## Filesystem Tasks (server builds)
+
+The Node and Electron builds ship three tasks that read the local filesystem —
+`FileGrepTask`, `FileLoaderTask` and `FileSedTask`.
+
+**They are not registered by default.** `registerCommonTasks()` deliberately
+leaves them out of `TaskRegistry`, because the registry is what a _deserialized_
+graph resolves a task type through, and a serialized node supplies its own
+`config` — so a graph naming `FileGrepTask` also names its own `roots`, and no
+default this package picks can constrain it. The only control that survives
+untrusted graph JSON is the task not being resolvable at all.
+
+A host that intends to expose them opts in:
+
+```typescript
+import { registerCommonTasks, registerFileSystemTasks } from "@workglow/tasks";
+
+registerCommonTasks();
+// Only where every graph reaching the registry is trusted:
+registerFileSystemTasks();
+```
+
+The classes are exported either way, so constructing one directly needs no
+registration:
+
+```typescript
+import { FileGrepTask } from "@workglow/tasks";
+
+const result = await new FileGrepTask({
+  roots: ["/srv/data"], // defaults to [process.cwd()]
+  defaults: { url: "/srv/data/app.log", pattern: "ERROR" },
+}).run();
+```
+
+### Root containment
+
+Each task resolves and `realpath`s a local path before opening it, then
+requires the result to sit inside one of `config.roots`. Omitting `roots` means
+`[process.cwd()]` — **not** "anywhere on the host". The `filesystem:read`
+entitlement is not a substitute: it is only consulted when the embedder both
+runs the graph with `enforceEntitlements` and registers an
+`ENTITLEMENT_ENFORCER`, and neither is the default.
+
+Set `allowAnyRoot: true` to read any path the process can open. It has to be
+said explicitly; leaving `roots` unset never implies it.
+
+```typescript
+new FileGrepTask({ allowAnyRoot: true, defaults: { url, pattern } });
+```
+
+An unresolvable entry in `roots` fails the call wherever it sits in the array.
+
 ## Workflow Integration
 
 All tasks can be used standalone or integrated into workflows:

packages/tasks/src/electron.ts

@@ -22,10 +22,37 @@ import { FileGrepTask } from "./task/FileGrepTask.server";
 import { FileLoaderTask } from "./task/FileLoaderTask.server";
 import { FileSedTask } from "./task/FileSedTask.server";
 
+/**
+ * Registers the tasks that are safe to have in the ambient registry on a
+ * server.
+ *
+ * The three filesystem tasks are NOT among them, and their absence is the
+ * point. `TaskRegistry` is what a deserialized graph resolves a task type
+ * through, and a serialized node carries its own `config` — so a graph that
+ * names `FileGrepTask` also states its own `roots`, and no default this
+ * package picks can constrain it. The only control that survives untrusted
+ * JSON is the task not being resolvable at all.
+ *
+ * A host that intends to expose them opts in with
+ * {@link registerFileSystemTasks}. The classes are exported either way, so
+ * constructing one directly is unchanged.
+ */
 export const registerCommonTasks = () => {
-  const tasks = registerCommonTasksFn();
+  return registerCommonTasksFn();
+};
+
+/**
+ * Adds the filesystem tasks to the ambient registry, making them resolvable by
+ * type name — including from graph JSON the host did not author.
+ *
+ * Call it only where every graph that can reach the registry is trusted. Each
+ * task still contains reads to its `config.roots`, which defaults to
+ * `process.cwd()`, but a serialized node supplies its own config: registration
+ * is the boundary, containment is the backstop behind it.
+ */
+export const registerFileSystemTasks = () => {
   TaskRegistry.registerTask(FileGrepTask);
   TaskRegistry.registerTask(FileLoaderTask);
   TaskRegistry.registerTask(FileSedTask);
-  return [...tasks, FileGrepTask, FileLoaderTask, FileSedTask];
+  return [FileGrepTask, FileLoaderTask, FileSedTask];
 };

packages/tasks/src/node.ts

@@ -24,10 +24,37 @@ import { FileGrepTask } from "./task/FileGrepTask.server";
 import { FileLoaderTask } from "./task/FileLoaderTask.server";
 import { FileSedTask } from "./task/FileSedTask.server";
 
+/**
+ * Registers the tasks that are safe to have in the ambient registry on a
+ * server.
+ *
+ * The three filesystem tasks are NOT among them, and their absence is the
+ * point. `TaskRegistry` is what a deserialized graph resolves a task type
+ * through, and a serialized node carries its own `config` — so a graph that
+ * names `FileGrepTask` also states its own `roots`, and no default this
+ * package picks can constrain it. The only control that survives untrusted
+ * JSON is the task not being resolvable at all.
+ *
+ * A host that intends to expose them opts in with
+ * {@link registerFileSystemTasks}. The classes are exported either way, so
+ * constructing one directly is unchanged.
+ */
 export const registerCommonTasks = () => {
-  const tasks = registerCommonTasksFn();
+  return registerCommonTasksFn();
+};
+
+/**
+ * Adds the filesystem tasks to the ambient registry, making them resolvable by
+ * type name — including from graph JSON the host did not author.
+ *
+ * Call it only where every graph that can reach the registry is trusted. Each
+ * task still contains reads to its `config.roots`, which defaults to
+ * `process.cwd()`, but a serialized node supplies its own config: registration
+ * is the boundary, containment is the backstop behind it.
+ */
+export const registerFileSystemTasks = () => {
   TaskRegistry.registerTask(FileGrepTask);
   TaskRegistry.registerTask(FileLoaderTask);
   TaskRegistry.registerTask(FileSedTask);
-  return [...tasks, FileGrepTask, FileLoaderTask, FileSedTask];
+  return [FileGrepTask, FileLoaderTask, FileSedTask];
 };

packages/tasks/src/task/FileGrepTask.server.ts

@@ -44,7 +44,14 @@ const fileGrepTaskConfigSchema = {
       type: "array",
       items: { type: "string" },
       title: "Roots",
-      description: "Directories a local path must resolve inside (after symlink resolution)",
+      description:
+        "Directories a local path must resolve inside (after symlink resolution). Defaults to the process working directory",
+      "x-ui-hidden": true,
+    },
+    allowAnyRoot: {
+      type: "boolean",
+      title: "Allow Any Root",
+      description: "Skip root containment entirely and read any path the process can open",
       "x-ui-hidden": true,
     },
   },
@@ -61,8 +68,10 @@ const fileGrepTaskConfigSchema = {
  * so a file with no line terminator cannot exhaust memory.
  *
  * A local path is resolved and realpath'd before it is opened, and constrained
- * to `config.roots` when the embedder sets them. Reading requires the
- * `filesystem:read` entitlement, declared scoped to the resolved path.
+ * to `config.roots` — which defaults to the process working directory, so a
+ * task with no stated root reads from there and nowhere else. Set
+ * `config.allowAnyRoot` to opt out. Reading requires the `filesystem:read`
+ * entitlement, declared scoped to the resolved path.
  *
  * Only available in Node.js and Bun environments. For cross-platform grep
  * (including browser), use FileGrepTask with an http(s) URL.
@@ -112,7 +121,12 @@ export class FileGrepTask extends BaseFileGrepTask<FileGrepTaskConfig> {
           {
             id: Entitlements.FILESYSTEM_READ,
             reason: "Reads a local file from disk",
-            resources: [resolveLocalFilePath(url, { roots: this.config.roots })],
+            resources: [
+              resolveLocalFilePath(url, {
+                roots: this.config.roots,
+                allowAnyRoot: this.config.allowAnyRoot,
+              }),
+            ],
           },
         ],
       };
@@ -189,7 +203,10 @@ export class FileGrepTask extends BaseFileGrepTask<FileGrepTaskConfig> {
     }
     await context.updateProgress(0, "Opening file");
 
-    const file = resolveLocalFilePath(url, { roots: this.config.roots });
+    const file = resolveLocalFilePath(url, {
+      roots: this.config.roots,
+      allowAnyRoot: this.config.allowAnyRoot,
+    });
     this.assertResolvedPathDeclared(file);
 
     if (context.signal.aborted) {

packages/tasks/src/task/FileGrepTask.ts

@@ -694,13 +694,21 @@ export class FileGrepTask<Config extends TaskConfig = TaskConfig> extends Task<
 export interface FileGrepTaskConfig extends TaskConfig {
   /**
    * Directories a local path must resolve inside, checked after symlinks are
-   * resolved. Omitted means unrestricted: the enforced control is the
-   * `filesystem:read` entitlement, and this is the embedder's extra fence.
+   * resolved. Omitted means `[process.cwd()]`, NOT unrestricted — the
+   * `filesystem:read` entitlement is only consulted when the embedder runs
+   * with `enforceEntitlements` and a registered enforcer, so it cannot stand
+   * in as the default fence. State {@link allowAnyRoot} to opt out.
    *
    * Honored only by the server build — the cross-platform class reaches
    * http(s) through `FetchUrlTask` and touches no filesystem.
    */
   readonly roots?: readonly string[] | undefined;
+  /**
+   * Read any path the process can open, skipping containment entirely. Only
+   * the literal `true` does so, and it is never implied by leaving `roots`
+   * unset.
+   */
+  readonly allowAnyRoot?: boolean | undefined;
 }
 
 export const fileGrep = (input: FileGrepTaskInput, config?: FileGrepTaskConfig) => {