@4fu/arbor-workspace-dir 2026.1106.0 → 2026.1107.0

package/README.md

@@ -27,9 +27,11 @@ everything that takes judgment, such as git, merges and conflicts, to the agent.
   guarantees what an agent cannot guarantee for itself - the record, isolation,
   exactly-once effects, the checks, dispatch. Everything that takes judgment,
   such as git, merges and conflicts, is the agent's.
-- **A directory per window.** Each window gets its own directory, and a
-  continuation keeps working in its predecessor's directory in place. It is not
-  bound to a repository; the agent clones and pushes what it needs.
+- **A shared workspace with per-window checkouts.** The default workspace is
+  ovnfs: one shared folder every window reads, and a window opens its own
+  copy-on-write checkout of the project it needs, works there and merges back
+  with `apply`. It falls back to a plain directory per window when ovnfs is not
+  installed. It is not a sandbox: ovnfs isolates files, not processes.
 - **A self-changing environment.** The model adds and changes skills, MCP
   servers and resident services itself; a `reload` validates the change and
   broadcasts it to every live window as a delta of names and descriptions.
@@ -54,7 +56,9 @@ npm install @4fu/arbor-core @4fu/arbor-journal-sqlite @4fu/arbor-notes-sqlite \
 ```
 
 `@4fu/arbor-plugin-http` is optional; it is the example plugin below.
-`@4fu/arbor-segmenter-jieba` is an optional peer of the journal.
+`@4fu/arbor-segmenter-jieba` is an optional peer of the lexical package, and
+`@4fu/arbor-search-zvec` an optional peer of the journal: absent either one, the
+journal searches lexically and nothing else changes.
 
 ## A minimal host
 
@@ -118,7 +122,10 @@ window gets, and how a continuation keeps working in it, are in
 | [`@4fu/arbor-journal-sqlite`](packages/journal-sqlite) | the default `Journal` and `BlobStore` on SQLite |
 | [`@4fu/arbor-notes-sqlite`](packages/notes-sqlite) | the default `NoteStore` on SQLite, beside the journal |
 | [`@4fu/arbor-segmenter-jieba`](packages/segmenter-jieba) | the default `Segmenter`: jieba's dictionary segmentation for the word index, optional |
-| [`@4fu/arbor-workspace-dir`](packages/workspace-dir) | the default `Workspace`: one directory per window, with a continuation working in its predecessor's directory in place |
+| [`@4fu/arbor-lexical`](packages/lexical) | the lexical search the journal and notes share: word segmentation, the FTS5 helpers and the merge order |
+| [`@4fu/arbor-search-zvec`](packages/search-zvec) | the optional semantic channel: event text embedded and searched by meaning with zvec |
+| [`@4fu/arbor-workspace-dir`](packages/workspace-dir) | the fallback `Workspace`: one directory per window, with a continuation working in its predecessor's directory in place |
+| [`@4fu/arbor-workspace-ovnfs`](packages/workspace-ovnfs) | the default `Workspace` when ovnfs is installed: one shared folder, per-window copy-on-write checkouts the model opens and applies back |
 | [`@4fu/arbor-environment-dir`](packages/environment-dir) | the default `Environment`: one `/env` directory, a revision per item, validation and deltas |
 | [`@4fu/arbor-supervisor-process`](packages/supervisor-process) | the default `Supervisor`: one host process per service, restart with backoff, logs |
 | [`@4fu/arbor-judge-jev`](packages/judge-jev) | the default `Judge`: Jev, TypeSafe AI's System One classifier, answering the dispatch decisions |
@@ -151,7 +158,7 @@ deployment can see what it would be taking on before it adopts one.
 | [docs/coordination.md](docs/coordination.md) | the board, expectations, deliveries and broadcasts, staying current, effects |
 | [docs/environment.md](docs/environment.md) | skills, MCP servers and services: using, changing, reload, built-in skills, deltas |
 | [docs/memory.md](docs/memory.md) | notes, the active set, anchors, links |
-| [docs/workspaces.md](docs/workspaces.md) | per-window directories: isolation, continuity, what the agent does |
+| [docs/workspaces.md](docs/workspaces.md) | the shared folder and per-window checkouts: isolation, continuity, what the agent does |
 | [docs/tools.md](docs/tools.md) | direct tools and code mode modules |
 | [docs/prompting.md](docs/prompting.md) | how every model-facing text is written: layers, notes, deliveries, errors, judge questions, terms |
 | [docs/release.md](docs/release.md) | calendar versioning, the manual release steps, how a package is published |
@@ -168,6 +175,7 @@ tarball would contain ([docs/release.md](docs/release.md)).
 | `packages/errors` | the error shape every refusal uses: the rule and the next action |
 | `packages/journal-sqlite` | the default `Journal` and `BlobStore` on SQLite |
 | `packages/segmenter-jieba` | the default `Segmenter`: jieba's dictionary segmentation for the word index, optional |
+| `packages/lexical` | the lexical search the journal and notes share: word segmentation, the FTS5 helpers and the merge order |
 | `packages/notes-sqlite` | the default `NoteStore` on SQLite, beside the journal |
 | `packages/judge-jev` | the default `Judge`: Jev, TypeSafe AI's System One classifier, answering the dispatch decisions |
 | `packages/workspace-dir` | the default `Workspace`: one directory per window, with a continuation working in its predecessor's directory in place, and the lookup of another window's directory it contributes to the catalog |

package/directory-workspace.d.ts

@@ -3,10 +3,12 @@
  *
  * A workspace is a plain directory, not bound to any repository: the framework
  * gives isolation and continuity, and the agent does the rest. This
- * implementation keeps every window's directory under one root:
+ * implementation keeps every window's directory under one root, and beside
+ * them the persistent directories a window asks to keep:
  *
  * ```text
  * <root>/ws3/                    the window's own directory
+ * <root>/keep/notes/             a persistent directory, kept past the window
  * ```
  *
  * A new window gets a directory of its own, created on first use. A
@@ -15,6 +17,14 @@
  * so in place is safe, and the chain is in the journal, so a restart recovers
  * which directory a continuation uses.
  *
+ * A window's own directory ends with its chain: after `workspaces.retentionMs`
+ * the host reclaims it. Content that has to outlive that is a **persistent
+ * directory** - `workspace.keep(name)`, or a plain `mkdir` under the same root -
+ * which lives outside the windows' own directories, so reclaim never touches it
+ * and a restart finds it where it was. It is recorded in the journal with the
+ * window that made it, so a continuation is told which ones its chain has and
+ * `journal.search` finds the rest.
+ *
  * It isolates by directory only. Another window's directory is a path on this
  * host, which a command may name and `read`, `write` and `edit` may open and
  * change; nothing here refuses a path outside the window's own directory, and
@@ -23,14 +33,26 @@
  * implementation enforces. That is not a security boundary, and the docs say
  * so: real isolation comes from an implementation that owns its execution
  * environment.
+ *
+ * It reports no open work: a window works in place and its continuation keeps
+ * working in the same directory, so there is no step between the two where work
+ * could be left unapplied, and `Workspace.openWork` is left out rather than
+ * answered empty (docs/workspaces.md#open-work).
  */
-import type { TextTable, ToolGroup, WindowRef, Workspace, WorkspaceMount, WorkspaceQuota, WorkspaceRef } from "@4fu/arbor-interfaces";
+import type { Journal, PromptSection, TextTable, ToolGroup, WindowRef, Workspace, WorkspaceKeep, WorkspaceMount, WorkspaceQuota, WorkspaceRef } from "@4fu/arbor-interfaces";
 export interface DirectoryWorkspaceOptions {
     /** The root every workspace lives under. */
     root: string;
+    /**
+     * The journal, for the events a persistent directory records and for chain
+     * resolution. Absent leaves those off: a persistent directory still works,
+     * and a continuation is then told only about the ones on disk.
+     */
+    journal?: Journal;
 }
 export declare class DirectoryWorkspace implements Workspace {
     private readonly root;
+    private readonly journal;
     constructor(options: DirectoryWorkspaceOptions);
     /**
      * The directory a window works in, created on first use. Idempotent: the
@@ -47,6 +69,12 @@ export declare class DirectoryWorkspace implements Workspace {
     pathOfWindow(window: WindowRef): Promise<string | undefined>;
     mount(ref: WorkspaceRef): Promise<WorkspaceMount>;
     quota(workspace: WorkspaceRef): Promise<WorkspaceQuota>;
+    /**
+     * Reclaim a window's own directory. A persistent directory is not one: it
+     * lives under `keep`, beside the windows' directories, so reclaiming a
+     * window's own directory leaves every persistent directory where it is
+     * (docs/workspaces.md#lifecycle).
+     */
     reclaim(workspace: WorkspaceRef): Promise<void>;
     /**
      * The workspace a window's chain already has, or `undefined` when it has
@@ -57,16 +85,52 @@ export declare class DirectoryWorkspace implements Workspace {
     /** The directory a window works in, for the file tools. */
     pathOf(ref: WorkspaceRef): string;
     /**
-     * What this implementation adds to the catalog: another window's directory,
-     * by its window. The core declares no such capability of its own
-     * (docs/workspaces.md).
+     * The persistent directory `name` names, created on first use, and its path
+     * on this host. Idempotent: the name that is already there is handed back as
+     * it is, so a later window that wants the same place gets the same directory
+     * instead of a second one. The write is recorded in the journal with the
+     * window that made it, which is how a continuation learns which ones its
+     * chain has.
+     */
+    keep(window: WindowRef, name: string): Promise<string>;
+    /**
+     * The persistent directories on disk, by name, or only the ones a window's
+     * chain created when a window is named. The directory is the truth: one the
+     * model removed with `rm` is gone from the answer, and the journal only says
+     * who made which.
+     */
+    keeps(window?: WindowRef): Promise<readonly WorkspaceKeep[]>;
+    /** Every persistent directory under the keep root, by name. */
+    private keepsOnDisk;
+    /** The names a window's chain recorded a persistent directory under. */
+    private keptNames;
+    /** Every `workspace_keep` event one window recorded, paged to the end. */
+    private keepEvents;
+    /** The window and every window it continues from, newest first. */
+    private chainWindows;
+    private record;
+    /**
+     * What this implementation adds to the catalog: another window's directory by
+     * its window, and the persistent directories. The core declares no such
+     * capability of its own (docs/workspaces.md).
      */
     groups(table: TextTable): readonly ToolGroup[];
+    /**
+     * This implementation's own prompt text: work in your own directory in place,
+     * keep what has to outlive the window in a persistent directory, and treat
+     * another window's directory as read-only by convention. Its own, different
+     * from the ovnfs workspace's, so a host never shows the ovnfs method when it
+     * fell back here (docs/workspaces.md).
+     */
+    promptSection(): PromptSection;
     private workspacePath;
+    /** Where a persistent directory's name puts it, refusing a name that escapes. */
+    private keepPath;
     /**
      * The ref a window's directory has: the one it already has, or the next
      * number nothing has taken. A window's number only grows, so a directory is
-     * never handed to a second window.
+     * never handed to a second window. The keep root is not a window's directory
+     * and is not one of the candidates.
      */
     private allocate;
     /** Resolve a ref a model may pass back into a path on this host. */

package/directory-workspace.js

@@ -3,10 +3,12 @@
  *
  * A workspace is a plain directory, not bound to any repository: the framework
  * gives isolation and continuity, and the agent does the rest. This
- * implementation keeps every window's directory under one root:
+ * implementation keeps every window's directory under one root, and beside
+ * them the persistent directories a window asks to keep:
  *
  * ```text
  * <root>/ws3/                    the window's own directory
+ * <root>/keep/notes/             a persistent directory, kept past the window
  * ```
  *
  * A new window gets a directory of its own, created on first use. A
@@ -15,6 +17,14 @@
  * so in place is safe, and the chain is in the journal, so a restart recovers
  * which directory a continuation uses.
  *
+ * A window's own directory ends with its chain: after `workspaces.retentionMs`
+ * the host reclaims it. Content that has to outlive that is a **persistent
+ * directory** - `workspace.keep(name)`, or a plain `mkdir` under the same root -
+ * which lives outside the windows' own directories, so reclaim never touches it
+ * and a restart finds it where it was. It is recorded in the journal with the
+ * window that made it, so a continuation is told which ones its chain has and
+ * `journal.search` finds the rest.
+ *
  * It isolates by directory only. Another window's directory is a path on this
  * host, which a command may name and `read`, `write` and `edit` may open and
  * change; nothing here refuses a path outside the window's own directory, and
@@ -23,15 +33,30 @@
  * implementation enforces. That is not a security boundary, and the docs say
  * so: real isolation comes from an implementation that owns its execution
  * environment.
+ *
+ * It reports no open work: a window works in place and its continuation keeps
+ * working in the same directory, so there is no step between the two where work
+ * could be left unapplied, and `Workspace.openWork` is left out rather than
+ * answered empty (docs/workspaces.md#open-work).
  */
 import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, normalize, resolve } from "node:path";
 import { arborError } from "@4fu/arbor-errors";
-import { WorkspacePathGroup } from "./path-module.js";
+import { textOf } from "@4fu/arbor-prompt";
+import { WorkspaceDirGroup } from "./module.js";
+import { directorySection, directoryText } from "./section.js";
+/** The directory under the root that holds the persistent directories. */
+const KEEP_DIR = "keep";
+/** How many `workspace_keep` events one read of the journal takes. */
+const KEEP_PAGE = 200;
+/** The longest a persistent directory's name may be. */
+const KEEP_NAME_MAX = 64;
 export class DirectoryWorkspace {
     root;
+    journal;
     constructor(options) {
         this.root = options.root;
+        this.journal = options.journal;
     }
     /**
      * The directory a window works in, created on first use. Idempotent: the
@@ -60,8 +85,8 @@ export class DirectoryWorkspace {
             path: resolved,
             readFile: async (path) => {
                 // A relative path is inside this workspace. An absolute one is read
-                // where it is on this host, which is how another window's directory is
-                // read (docs/workspaces.md).
+                // where it is on this host, which is how another window's directory and
+                // a persistent directory are read (docs/workspaces.md).
                 return readFile(hostPath(resolved, path), "utf8").catch(() => null);
             },
             writeFile: async (path, text) => {
@@ -83,6 +108,12 @@ export class DirectoryWorkspace {
             bytes += size;
         return { bytes, used: bytes, files: files.size };
     }
+    /**
+     * Reclaim a window's own directory. A persistent directory is not one: it
+     * lives under `keep`, beside the windows' directories, so reclaiming a
+     * window's own directory leaves every persistent directory where it is
+     * (docs/workspaces.md#lifecycle).
+     */
     async reclaim(workspace) {
         await rm(this.workspacePath(workspace), { recursive: true, force: true });
     }
@@ -102,21 +133,149 @@ export class DirectoryWorkspace {
     pathOf(ref) {
         return this.workspacePath(ref);
     }
+    // ---- persistent directories -------------------------------------------
+    /**
+     * The persistent directory `name` names, created on first use, and its path
+     * on this host. Idempotent: the name that is already there is handed back as
+     * it is, so a later window that wants the same place gets the same directory
+     * instead of a second one. The write is recorded in the journal with the
+     * window that made it, which is how a continuation learns which ones its
+     * chain has.
+     */
+    async keep(window, name) {
+        const path = this.keepPath(name);
+        await mkdir(path, { recursive: true });
+        await this.record("workspace_keep", window, { name, path });
+        return path;
+    }
+    /**
+     * The persistent directories on disk, by name, or only the ones a window's
+     * chain created when a window is named. The directory is the truth: one the
+     * model removed with `rm` is gone from the answer, and the journal only says
+     * who made which.
+     */
+    async keeps(window) {
+        const onDisk = await this.keepsOnDisk();
+        if (window === undefined)
+            return onDisk;
+        const created = await this.keptNames(window);
+        return onDisk.filter((keep) => created.has(keep.name));
+    }
+    /** Every persistent directory under the keep root, by name. */
+    async keepsOnDisk() {
+        const root = join(this.root, KEEP_DIR);
+        let entries;
+        try {
+            entries = await readdir(root, { withFileTypes: true });
+        }
+        catch {
+            return [];
+        }
+        const keeps = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            keeps.push({ name: entry.name, path: join(root, entry.name) });
+        }
+        // A listing reaches the prompt and a result line, so it is ordered rather
+        // than left to the filesystem.
+        return keeps.sort((one, other) => one.name.localeCompare(other.name));
+    }
+    /** The names a window's chain recorded a persistent directory under. */
+    async keptNames(window) {
+        const names = new Set();
+        if (this.journal === undefined)
+            return names;
+        for (const one of await this.chainWindows(window)) {
+            for (const name of await this.keepEvents(one))
+                names.add(name);
+        }
+        return names;
+    }
+    /** Every `workspace_keep` event one window recorded, paged to the end. */
+    async keepEvents(window) {
+        const journal = this.journal;
+        const names = [];
+        if (journal === undefined)
+            return names;
+        for (let offset = 0; offset < 10_000; offset += KEEP_PAGE) {
+            const page = await journal
+                .list({ window, kinds: ["workspace_keep"], limit: KEEP_PAGE, offset })
+                .catch(() => null);
+            if (page === null || page.items.length === 0)
+                return names;
+            for (const event of page.items) {
+                const name = keptName(event.body);
+                if (name !== undefined)
+                    names.push(name);
+            }
+            if (offset + page.items.length >= page.total)
+                return names;
+        }
+        return names;
+    }
+    /** The window and every window it continues from, newest first. */
+    async chainWindows(window) {
+        const chain = [window];
+        const seen = new Set([window]);
+        let current = window;
+        for (let depth = 0; depth < 1000; depth += 1) {
+            if (this.journal === undefined)
+                break;
+            const page = await this.journal.list({ window: current, kinds: ["window_start"], limit: 1 });
+            const previous = continuedWindow(page.items[0]?.body);
+            if (previous === undefined || seen.has(previous))
+                break;
+            seen.add(previous);
+            chain.push(previous);
+            current = previous;
+        }
+        return chain;
+    }
+    async record(kind, window, body) {
+        if (this.journal === undefined)
+            return;
+        await this.journal.append({ kind, window, body: JSON.stringify(body) }).catch(() => { });
+    }
+    // ---- what this implementation adds ------------------------------------
     /**
-     * What this implementation adds to the catalog: another window's directory,
-     * by its window. The core declares no such capability of its own
-     * (docs/workspaces.md).
+     * What this implementation adds to the catalog: another window's directory by
+     * its window, and the persistent directories. The core declares no such
+     * capability of its own (docs/workspaces.md).
      */
     groups(table) {
-        return [new WorkspacePathGroup(this, table)];
+        return [new WorkspaceDirGroup(this, { ...table, ...directoryText })];
+    }
+    /**
+     * This implementation's own prompt text: work in your own directory in place,
+     * keep what has to outlive the window in a persistent directory, and treat
+     * another window's directory as read-only by convention. Its own, different
+     * from the ovnfs workspace's, so a host never shows the ovnfs method when it
+     * fell back here (docs/workspaces.md).
+     */
+    promptSection() {
+        return directorySection(this.root);
     }
     workspacePath(ref) {
         return join(this.root, ref);
     }
+    /** Where a persistent directory's name puts it, refusing a name that escapes. */
+    keepPath(name) {
+        if (!/^[a-z0-9][a-z0-9._-]*$/.test(name) || name.length > KEEP_NAME_MAX) {
+            throw arborError({
+                code: "invalid",
+                rule: "workspace.keep.name",
+                message: textOf(directoryText, "refused.workspace.keep.name", { name }),
+                nextAction: textOf(directoryText, "next.workspace.keep.name"),
+            });
+        }
+        return join(this.root, KEEP_DIR, name);
+    }
     /**
      * The ref a window's directory has: the one it already has, or the next
      * number nothing has taken. A window's number only grows, so a directory is
-     * never handed to a second window.
+     * never handed to a second window. The keep root is not a window's directory
+     * and is not one of the candidates.
      */
     async allocate(window) {
         const wanted = windowNumber(window);
@@ -222,3 +381,28 @@ async function listFiles(root) {
     await walk(root);
     return files;
 }
+/** The window a `window_start` body names as the one it continues. */
+function continuedWindow(body) {
+    if (body === undefined || body === null)
+        return undefined;
+    try {
+        const parsed = JSON.parse(body);
+        const previous = parsed.continuation;
+        return typeof previous === "string" && /^c\d+$/.test(previous) ? previous : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The name a `workspace_keep` body records, when it records one. */
+function keptName(body) {
+    if (body === undefined || body === null)
+        return undefined;
+    try {
+        const parsed = JSON.parse(body);
+        return typeof parsed.name === "string" ? parsed.name : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/index.d.ts

@@ -3,8 +3,10 @@
  *
  * One directory per window, under one root, created on first use; a
  * continuation works in its predecessor's directory in place, under the same
- * ref. It is the only `Workspace` the framework ships, and it needs nothing a
- * host does not already have (docs/workspaces.md).
+ * ref. Beside them, the persistent directories a window asks to keep, which
+ * outlive the window, the retention period and a host restart. It needs nothing
+ * a host does not already have (docs/workspaces.md).
  */
 export { DirectoryWorkspace, type DirectoryWorkspaceOptions } from "./directory-workspace.ts";
-export { WorkspacePathGroup } from "./path-module.ts";
+export { WorkspaceDirGroup } from "./module.ts";
+export { directorySection, directoryText, DIRECTORY_METHOD_BLOCK } from "./section.ts";

package/index.js

@@ -3,8 +3,10 @@
  *
  * One directory per window, under one root, created on first use; a
  * continuation works in its predecessor's directory in place, under the same
- * ref. It is the only `Workspace` the framework ships, and it needs nothing a
- * host does not already have (docs/workspaces.md).
+ * ref. Beside them, the persistent directories a window asks to keep, which
+ * outlive the window, the retention period and a host restart. It needs nothing
+ * a host does not already have (docs/workspaces.md).
  */
 export { DirectoryWorkspace } from "./directory-workspace.js";
-export { WorkspacePathGroup } from "./path-module.js";
+export { WorkspaceDirGroup } from "./module.js";
+export { directorySection, directoryText, DIRECTORY_METHOD_BLOCK } from "./section.js";

package/module.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The module functions the plain-directory workspace contributes
+ * (docs/workspaces.md#persistent-directories).
+ *
+ * `keep` and `keeps` give the model the persistent directories: a named place
+ * whose content outlives the window that made it, the retention period and a
+ * host restart, which a later window finds by name. `path` answers another
+ * window's own directory, by its window. The core knows nothing about either:
+ * a window reaches a persistent directory through these, through `journal`, or
+ * plainly by its path - `mkdir -p <root>/keep/<name>` makes the same directory.
+ *
+ * Every result and refusal is one text-table entry naming the rule and the next
+ * action. These functions live in the `workspace` module beside the core's
+ * `grep`, `find` and `ls`.
+ */
+import type { CallContext, ModuleSpec, TextTable, ToolCall, ToolGroup, ToolResult } from "@4fu/arbor-interfaces";
+import type { DirectoryWorkspace } from "./directory-workspace.ts";
+/** `workspace.keep`, `workspace.keeps` and `workspace.path`. */
+export declare class WorkspaceDirGroup implements ToolGroup {
+    readonly id = "workspace.dir";
+    private readonly workspace;
+    private readonly table;
+    constructor(workspace: DirectoryWorkspace, table: TextTable);
+    tools(): readonly [];
+    modules(): readonly ModuleSpec[];
+    call(request: ToolCall, context: CallContext): Promise<ToolResult>;
+    private keep;
+    private keeps;
+    private path;
+    private ok;
+    /**
+     * One refusal the workspace answered with, in the core's error shape. The rule
+     * names the table entry that carries its wording, exactly the way a note
+     * store's refusal reaches the model.
+     */
+    private refusalOf;
+    private notOwned;
+}

package/module.js

@@ -0,0 +1,148 @@
+/**
+ * The module functions the plain-directory workspace contributes
+ * (docs/workspaces.md#persistent-directories).
+ *
+ * `keep` and `keeps` give the model the persistent directories: a named place
+ * whose content outlives the window that made it, the retention period and a
+ * host restart, which a later window finds by name. `path` answers another
+ * window's own directory, by its window. The core knows nothing about either:
+ * a window reaches a persistent directory through these, through `journal`, or
+ * plainly by its path - `mkdir -p <root>/keep/<name>` makes the same directory.
+ *
+ * Every result and refusal is one text-table entry naming the rule and the next
+ * action. These functions live in the `workspace` module beside the core's
+ * `grep`, `find` and `ls`.
+ */
+import { textOf } from "@4fu/arbor-prompt";
+/** `workspace.keep`, `workspace.keeps` and `workspace.path`. */
+export class WorkspaceDirGroup {
+    id = "workspace.dir";
+    workspace;
+    table;
+    constructor(workspace, table) {
+        this.workspace = workspace;
+        this.table = table;
+    }
+    tools() {
+        return [];
+    }
+    modules() {
+        return [
+            {
+                name: "workspace",
+                description: textOf(this.table, "module.workspace"),
+                functions: [
+                    {
+                        name: "workspace.keep",
+                        signature: "workspace.keep(name)",
+                        description: textOf(this.table, "function.workspace.keep"),
+                    },
+                    {
+                        name: "workspace.keeps",
+                        signature: "workspace.keeps()",
+                        description: textOf(this.table, "function.workspace.keeps"),
+                    },
+                    {
+                        name: "workspace.path",
+                        signature: "workspace.path(window)",
+                        description: textOf(this.table, "function.workspace.path"),
+                    },
+                ],
+            },
+        ];
+    }
+    async call(request, context) {
+        switch (request.name) {
+            case "workspace.keep":
+                return this.keep(request, context);
+            case "workspace.keeps":
+                return this.keeps(request);
+            case "workspace.path":
+                return this.path(request);
+            default:
+                return this.notOwned(request);
+        }
+    }
+    async keep(request, context) {
+        const name = stringArg(request.args, "name");
+        try {
+            const path = await this.workspace.keep(context.window, name);
+            return this.ok(request, textOf(this.table, "result.workspace.keep", { name, path }));
+        }
+        catch (error) {
+            return this.refusalOf(request, error);
+        }
+    }
+    async keeps(request) {
+        const keeps = await this.workspace.keeps();
+        if (keeps.length === 0) {
+            return this.ok(request, textOf(this.table, "result.workspace.keeps.empty"));
+        }
+        const lines = keeps
+            .map((keep) => textOf(this.table, "result.workspace.keeps.line", { name: keep.name, path: keep.path }))
+            .join("\n");
+        return this.ok(request, textOf(this.table, "result.workspace.keeps", { lines }));
+    }
+    async path(request) {
+        const window = windowArg(request.args.window);
+        const path = await this.workspace.pathOfWindow(window);
+        if (path === undefined) {
+            return {
+                callId: request.callId,
+                ok: false,
+                content: "",
+                error: {
+                    rule: "workspace.not_found",
+                    message: textOf(this.table, "refused.workspace.path", { window }),
+                    nextAction: textOf(this.table, "next.workspace.path"),
+                },
+            };
+        }
+        return {
+            callId: request.callId,
+            ok: true,
+            content: textOf(this.table, "result.workspace.path", { window, path }),
+        };
+    }
+    ok(request, content) {
+        return { callId: request.callId, ok: true, content };
+    }
+    /**
+     * One refusal the workspace answered with, in the core's error shape. The rule
+     * names the table entry that carries its wording, exactly the way a note
+     * store's refusal reaches the model.
+     */
+    refusalOf(request, error) {
+        const info = error;
+        return {
+            callId: request.callId,
+            ok: false,
+            content: "",
+            error: {
+                rule: info.rule ?? "workspace.keep.failed",
+                message: info.message ?? String(error),
+                ...(info.nextAction === undefined ? {} : { nextAction: info.nextAction }),
+            },
+        };
+    }
+    notOwned(request) {
+        return {
+            callId: request.callId,
+            ok: false,
+            content: "",
+            error: {
+                rule: "module.function.unknown",
+                message: textOf(this.table, "refused.unknown_function", { module: "workspace", name: request.name }),
+                nextAction: textOf(this.table, "next.unknown_function"),
+            },
+        };
+    }
+}
+function stringArg(args, name) {
+    const value = args[name];
+    return typeof value === "string" ? value : "";
+}
+/** The window an argument names, or `c0` when it names none. */
+function windowArg(value) {
+    return typeof value === "string" && /^c\d+$/.test(value) ? value : "c0";
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@4fu/arbor-workspace-dir",
-  "version": "2026.1106.0",
+  "version": "2026.1107.0",
   "type": "module",
-  "description": "The plain-directory Workspace: one directory per window, with a continuation working in its predecessor's directory in place.",
+  "description": "The plain-directory Workspace: one directory per window, with a continuation working in its predecessor's directory in place, plus the persistent directories a window asks to keep.",
   "exports": {
     ".": {
       "types": "./index.d.ts",
@@ -16,8 +16,10 @@
     "directory-workspace.js",
     "index.d.ts",
     "index.js",
-    "path-module.d.ts",
-    "path-module.js"
+    "module.d.ts",
+    "module.js",
+    "section.d.ts",
+    "section.js"
   ],
   "engines": {
     "node": ">=24"
@@ -32,8 +34,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@4fu/arbor-errors": "2026.1106.0",
-    "@4fu/arbor-interfaces": "2026.1106.0",
-    "@4fu/arbor-prompt": "2026.1106.0"
+    "@4fu/arbor-errors": "2026.1107.0",
+    "@4fu/arbor-interfaces": "2026.1107.0",
+    "@4fu/arbor-prompt": "2026.1107.0"
   }
 }

package/section.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The prompt section and the model-facing text the plain-directory workspace
+ * contributes (docs/workspaces.md#persistent-directories).
+ *
+ * Every fixed string this implementation writes lives here, in Chinese, one
+ * entry per string: the prompt section that carries the method, the module
+ * functions' descriptions and their results and refusals. The host merges this
+ * table over its own when this implementation is the active workspace, so a
+ * host that runs ovnfs never shows this method - the ovnfs workspace carries
+ * its own, different text (packages/workspace-ovnfs/src/text.ts).
+ *
+ * Identifiers stay as they are: `workspace.keep`, `workspace.keeps`,
+ * `workspace.path`, `keep`.
+ */
+import type { BlockKindSpec, PromptSection, TextTable } from "@4fu/arbor-interfaces";
+/** The plain-directory workspace's own fixed strings. */
+export declare const directoryText: TextTable;
+/** The one block kind the section renders: its lines, no tag, not data. */
+export declare const DIRECTORY_METHOD_BLOCK: BlockKindSpec;
+/**
+ * The plain-directory workspace's prompt section, with the root its
+ * directories live under filled into the lines that name it - the same way the
+ * ovnfs section fills in the shared folder.
+ */
+export declare function directorySection(root: string): PromptSection;

package/section.js

@@ -0,0 +1,74 @@
+/**
+ * The prompt section and the model-facing text the plain-directory workspace
+ * contributes (docs/workspaces.md#persistent-directories).
+ *
+ * Every fixed string this implementation writes lives here, in Chinese, one
+ * entry per string: the prompt section that carries the method, the module
+ * functions' descriptions and their results and refusals. The host merges this
+ * table over its own when this implementation is the active workspace, so a
+ * host that runs ovnfs never shows this method - the ovnfs workspace carries
+ * its own, different text (packages/workspace-ovnfs/src/text.ts).
+ *
+ * Identifiers stay as they are: `workspace.keep`, `workspace.keeps`,
+ * `workspace.path`, `keep`.
+ */
+/** The plain-directory workspace's own fixed strings. */
+export const directoryText = {
+    // ---- the prompt section the implementation contributes -----------------
+    "workspace.method.directory": "你的工作区是本主机上的一个目录，随窗口创建；续窗口在原处继续用它，克隆的仓库、装好的依赖和未完成的工作都留着。",
+    "workspace.method.persistent": "要留下跨窗口的内容，就用 workspace.keep(\"<名称>\") 建一个常驻目录：它在本主机的 {root}/keep/<名称>，不随窗口结束、回收和主机重启删除，后来的窗口用同一个名称找到它。",
+    "workspace.method.persistent.plain": "常驻目录也可以用 bash 直接建：mkdir -p {root}/keep/<名称>；模块函数只是给出路径，并把它记进记录。",
+    "workspace.method.persistent.shared": "常驻目录按约定共享：按名称写入它该放的内容，不要覆盖别人的东西。",
+    "workspace.method.persistent.find": "用 workspace.keeps() 列出所有常驻目录，用 read、write、edit 和 bash 按路径直接用它；续窗口的首次输入会列出本窗口链建过的常驻目录。",
+    "workspace.method.readonly": "按约定，别的窗口的目录只读，不要修改；要协作就靠仓库自己的流程（push、review、CI），框架不替你合并文件。",
+    "workspace.method.means": "read、write、edit 和 bash 都在这个目录里工作，bash 也在这里跑后台作业。",
+    // ---- the module functions this implementation adds --------------------
+    "function.workspace.keep": "建一个常驻目录并返回它的路径：名称已存在时返回原来那个；里面的内容不随窗口结束、回收和主机重启删除。",
+    "function.workspace.keeps": "列出所有常驻目录：名称和路径，按名称排序。",
+    "function.workspace.path": "按窗口引用查询它的工作区目录：该目录属于其他窗口，只读，不要修改。",
+    // ---- results ----------------------------------------------------------
+    "result.workspace.keep": "常驻目录 {name}：{path}。它不随窗口结束、回收和主机重启删除，后来的窗口用同一个名称找到它。",
+    "result.workspace.keeps": "常驻目录：{lines}",
+    "result.workspace.keeps.empty": "还没有常驻目录；用 workspace.keep 建一个。",
+    "result.workspace.keeps.line": "{name} {path}",
+    "result.workspace.path": "{path}（窗口 {window} 的工作区，属于其他窗口：只读，不要修改）",
+    // ---- refusals ---------------------------------------------------------
+    "refused.workspace.keep.name": "常驻目录名 {name} 不符合约定：用小写字母或数字开头，只用小写字母、数字、.、_ 和 -，最长 64 个字符。",
+    "refused.workspace.path": "窗口 {window} 没有工作区。",
+    // ---- next actions -----------------------------------------------------
+    "next.workspace.keep.name": "换一个名称，例如 build-cache 或 shared-notes。",
+    "next.workspace.path": "该窗口没有操作过文件；用 windows.list 查看当前的窗口。",
+    // ---- the continuation's first input -----------------------------------
+    "continuation.keeps": "上个窗口链建过的常驻目录：{keeps}。它们不随窗口结束、回收和主机重启删除，按路径直接读写。",
+};
+/** The method's points, one text-table key per line, in order. */
+const METHOD_LINES = [
+    "workspace.method.directory",
+    "workspace.method.persistent",
+    "workspace.method.persistent.plain",
+    "workspace.method.persistent.shared",
+    "workspace.method.persistent.find",
+    "workspace.method.readonly",
+    "workspace.method.means",
+];
+/** The one block kind the section renders: its lines, no tag, not data. */
+export const DIRECTORY_METHOD_BLOCK = {
+    kind: "directory_method",
+    data: false,
+    fields: [{ name: "root", type: "string", required: true }],
+    lines: [...METHOD_LINES],
+};
+/**
+ * The plain-directory workspace's prompt section, with the root its
+ * directories live under filled into the lines that name it - the same way the
+ * ovnfs section fills in the shared folder.
+ */
+export function directorySection(root) {
+    const block = { kind: "directory_method", fields: { root } };
+    return {
+        tag: "workspace",
+        blocks: [DIRECTORY_METHOD_BLOCK],
+        text: directoryText,
+        content: () => [block],
+    };
+}

package/path-module.d.ts

@@ -1,25 +0,0 @@
-/**
- * The capability the built-in directory workspace contributes: another
- * window's directory, by its window (docs/workspaces.md).
- *
- * The core knows nothing about it. A window reads another window's directory
- * through `read`, by the path this answers, and both the description and the
- * result say the directory belongs to another window and must not be modified.
- * Nothing here enforces that, because the built-in workspace isolates by
- * directory only: another window's directory is a path on the same host, which
- * a command may name. It is not a security boundary, and real isolation comes
- * from an implementation that owns its execution environment.
- */
-import type { ModuleSpec, TextTable, ToolCall, ToolGroup, ToolResult } from "@4fu/arbor-interfaces";
-import type { DirectoryWorkspace } from "./directory-workspace.ts";
-/** `workspace.path`: the directory of a window's workspace, by its window. */
-export declare class WorkspacePathGroup implements ToolGroup {
-    readonly id = "workspace.path";
-    private readonly workspace;
-    private readonly table;
-    constructor(workspace: DirectoryWorkspace, table: TextTable);
-    tools(): readonly [];
-    modules(): readonly ModuleSpec[];
-    call(request: ToolCall): Promise<ToolResult>;
-    private notOwned;
-}

package/path-module.js

@@ -1,80 +0,0 @@
-/**
- * The capability the built-in directory workspace contributes: another
- * window's directory, by its window (docs/workspaces.md).
- *
- * The core knows nothing about it. A window reads another window's directory
- * through `read`, by the path this answers, and both the description and the
- * result say the directory belongs to another window and must not be modified.
- * Nothing here enforces that, because the built-in workspace isolates by
- * directory only: another window's directory is a path on the same host, which
- * a command may name. It is not a security boundary, and real isolation comes
- * from an implementation that owns its execution environment.
- */
-import { textOf } from "@4fu/arbor-prompt";
-/** `workspace.path`: the directory of a window's workspace, by its window. */
-export class WorkspacePathGroup {
-    id = "workspace.path";
-    workspace;
-    table;
-    constructor(workspace, table) {
-        this.workspace = workspace;
-        this.table = table;
-    }
-    tools() {
-        return [];
-    }
-    modules() {
-        return [
-            {
-                name: "workspace",
-                description: textOf(this.table, "module.workspace"),
-                functions: [
-                    {
-                        name: "workspace.path",
-                        signature: "workspace.path(window)",
-                        description: textOf(this.table, "function.workspace.path"),
-                    },
-                ],
-            },
-        ];
-    }
-    async call(request) {
-        if (request.name !== "workspace.path")
-            return this.notOwned(request);
-        const window = windowArg(request.args.window);
-        const path = await this.workspace.pathOfWindow(window);
-        if (path === undefined) {
-            return {
-                callId: request.callId,
-                ok: false,
-                content: "",
-                error: {
-                    rule: "workspace.not_found",
-                    message: textOf(this.table, "refused.workspace.path", { window }),
-                    nextAction: textOf(this.table, "next.workspace.path"),
-                },
-            };
-        }
-        return {
-            callId: request.callId,
-            ok: true,
-            content: textOf(this.table, "result.workspace.path", { window, path }),
-        };
-    }
-    notOwned(request) {
-        return {
-            callId: request.callId,
-            ok: false,
-            content: "",
-            error: {
-                rule: "module.function.unknown",
-                message: textOf(this.table, "refused.unknown_function", { module: "workspace", name: request.name }),
-                nextAction: textOf(this.table, "next.unknown_function"),
-            },
-        };
-    }
-}
-/** The window an argument names, or `c0` when it names none. */
-function windowArg(value) {
-    return typeof value === "string" && /^c\d+$/.test(value) ? value : "c0";
-}