@akira-tl/forgerelay 0.8.2 → 0.8.4

package/dist/subagents/sessions/capability.js

@@ -19,6 +19,9 @@ export class SubagentSessionCapability {
         this.ownerAliveOverride = options.ownerAlive;
     }
     async run(input, context, options) {
+        if (!context.workspaceRoot) {
+            throw new CapabilityError("capability_unavailable", "subagent.session requires a filesystem-backed Workspace.");
+        }
         const manager = new SubagentSessionManager(this.config, {
             launch: (request) => this.launch(request),
         });

package/dist/workspace-task-reminders.js

@@ -0,0 +1,42 @@
+const TASK_REMINDER = "Reminder: this Workspace has unfinished active Tasks. Review workspace.tasks and update Task state when material progress, requirements, blockers, or conclusions changed.";
+export class WorkspaceTaskReminderTracker {
+    interval;
+    tasks;
+    callsSinceUpdate = new Map();
+    constructor(interval, tasks) {
+        this.interval = interval;
+        this.tasks = tasks;
+    }
+    reset(workspaceId) {
+        this.callsSinceUpdate.delete(workspaceId);
+    }
+    forget(workspaceId) {
+        this.callsSinceUpdate.delete(workspaceId);
+    }
+    recordWork(workspaceId) {
+        if (this.interval === 0)
+            return undefined;
+        let summary;
+        try {
+            summary = this.tasks.readSummary(workspaceId);
+        }
+        catch {
+            // Reminder delivery is advisory. Invalid external Task state must still be
+            // surfaced by workspace.tasks itself, not turn unrelated work into failure.
+            this.callsSinceUpdate.delete(workspaceId);
+            return undefined;
+        }
+        const hasUnfinishedActiveTasks = summary.lists.some((list) => list.state === "active" && list.unfinishedTaskCount > 0);
+        if (!hasUnfinishedActiveTasks) {
+            this.callsSinceUpdate.delete(workspaceId);
+            return undefined;
+        }
+        const next = (this.callsSinceUpdate.get(workspaceId) ?? 0) + 1;
+        if (next < this.interval) {
+            this.callsSinceUpdate.set(workspaceId, next);
+            return undefined;
+        }
+        this.callsSinceUpdate.set(workspaceId, 0);
+        return TASK_REMINDER;
+    }
+}

package/dist/workspace-tasks.js

@@ -0,0 +1,420 @@
+import { createHash, randomBytes } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, rmSync, rmdirSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import * as z from "zod/v4";
+const TASK_STATE_VERSION = 1;
+const MAX_TASK_STATE_BYTES = 2 * 1024 * 1024;
+const MAX_TASK_LISTS = 100;
+const MAX_TASKS_PER_LIST = 500;
+const MAX_LIST_NAME_LENGTH = 120;
+const MAX_TASK_SUBJECT_LENGTH = 240;
+const MAX_TASK_CONTENT_LENGTH = 64 * 1024;
+const workspaceTaskSchema = z.object({
+    id: z.string().regex(/^tsk_[a-f0-9]{10}$/),
+    status: z.enum(["pending", "in_progress", "completed"]),
+    subject: z.string().min(1).max(MAX_TASK_SUBJECT_LENGTH),
+    content: z.string().max(MAX_TASK_CONTENT_LENGTH),
+}).strict();
+const workspaceTaskListSchema = z.object({
+    id: z.string().regex(/^tl_[a-f0-9]{10}$/),
+    name: z.string().min(1).max(MAX_LIST_NAME_LENGTH),
+    state: z.enum(["active", "archived"]),
+    revision: z.number().int().positive(),
+    tasks: z.array(workspaceTaskSchema).max(MAX_TASKS_PER_LIST),
+}).strict();
+const workspaceTaskStateSchema = z.object({
+    version: z.literal(TASK_STATE_VERSION),
+    revision: z.number().int().nonnegative(),
+    lists: z.array(workspaceTaskListSchema).max(MAX_TASK_LISTS),
+}).strict().superRefine((state, context) => {
+    const listIds = new Set();
+    const taskIds = new Set();
+    state.lists.forEach((list, listIndex) => {
+        if (listIds.has(list.id)) {
+            context.addIssue({
+                code: "custom",
+                path: ["lists", listIndex, "id"],
+                message: `Duplicate Task List id ${list.id}.`,
+            });
+        }
+        listIds.add(list.id);
+        list.tasks.forEach((task, taskIndex) => {
+            if (taskIds.has(task.id)) {
+                context.addIssue({
+                    code: "custom",
+                    path: ["lists", listIndex, "tasks", taskIndex, "id"],
+                    message: `Duplicate Task id ${task.id}.`,
+                });
+            }
+            taskIds.add(task.id);
+        });
+    });
+});
+export class WorkspaceTaskStore {
+    stateDir;
+    constructor(stateDir) {
+        this.stateDir = stateDir;
+    }
+    ensureWorkspace(workspaceId) {
+        const id = normalizeWorkspaceId(workspaceId);
+        const loaded = this.tryReadState(id);
+        if (loaded)
+            return snapshot(loaded.state, loaded.fingerprint);
+        return this.writeState(id, emptyState());
+    }
+    initializeWorkspace(workspaceId) {
+        const id = normalizeWorkspaceId(workspaceId);
+        const directory = this.workspaceStateDir(id);
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        try {
+            writeFileSync(this.statePath(id), `${JSON.stringify(emptyState(), null, 2)}\n`, {
+                mode: 0o600,
+                flag: "wx",
+            });
+        }
+        catch (error) {
+            if (!isErrno(error, "EEXIST"))
+                throw error;
+        }
+    }
+    read(workspaceId) {
+        return this.ensureWorkspace(workspaceId);
+    }
+    readSummary(workspaceId) {
+        return taskSummary(this.ensureWorkspace(workspaceId));
+    }
+    inspectSummary(workspaceId) {
+        const id = normalizeWorkspaceId(workspaceId);
+        const loaded = this.tryReadState(id);
+        return loaded ? taskSummary(snapshot(loaded.state, loaded.fingerprint)) : undefined;
+    }
+    readHeaders(workspaceId, listId) {
+        return taskHeaders(this.ensureWorkspace(workspaceId), listId);
+    }
+    readTaskDetail(workspaceId, listId, taskId) {
+        return taskDetail(this.ensureWorkspace(workspaceId), listId, taskId);
+    }
+    createList(workspaceId, input) {
+        return this.mutate(workspaceId, (state) => {
+            if (state.lists.length >= MAX_TASK_LISTS) {
+                throw new Error(`Workspace Task List limit is ${MAX_TASK_LISTS}.`);
+            }
+            const list = {
+                id: `tl_${randomBytes(5).toString("hex")}`,
+                name: normalizeListName(input.name),
+                state: "active",
+                revision: 1,
+                tasks: [],
+            };
+            const position = normalizeInsertPosition(input.position, state.lists.length, "Task List");
+            state.lists.splice(position, 0, list);
+            return true;
+        });
+    }
+    updateList(workspaceId, listId, input) {
+        return this.mutate(workspaceId, (state) => {
+            const index = requireListIndex(state, listId);
+            const list = state.lists[index];
+            const nextName = input.name === undefined ? list.name : normalizeListName(input.name);
+            const nextState = input.state ?? list.state;
+            const nextPosition = input.position === undefined
+                ? index
+                : normalizeMovePosition(input.position, state.lists.length, "Task List");
+            const metadataChanged = nextName !== list.name || nextState !== list.state;
+            const positionChanged = nextPosition !== index;
+            if (!metadataChanged && !positionChanged)
+                return false;
+            list.name = nextName;
+            list.state = nextState;
+            list.revision += 1;
+            if (positionChanged)
+                moveArrayEntry(state.lists, index, nextPosition);
+            return true;
+        });
+    }
+    deleteList(workspaceId, listId) {
+        return this.mutate(workspaceId, (state) => {
+            state.lists.splice(requireListIndex(state, listId), 1);
+            return true;
+        });
+    }
+    createTask(workspaceId, listId, input) {
+        return this.mutate(workspaceId, (state) => {
+            const list = requireList(state, listId);
+            if (list.tasks.length >= MAX_TASKS_PER_LIST) {
+                throw new Error(`Task limit per Task List is ${MAX_TASKS_PER_LIST}.`);
+            }
+            const task = {
+                id: `tsk_${randomBytes(5).toString("hex")}`,
+                status: input.status ?? "pending",
+                subject: normalizeTaskSubject(input.subject),
+                content: normalizeTaskContent(input.content ?? ""),
+            };
+            const position = normalizeInsertPosition(input.position, list.tasks.length, "Task");
+            list.tasks.splice(position, 0, task);
+            list.revision += 1;
+            return true;
+        });
+    }
+    updateTask(workspaceId, listId, taskId, input) {
+        return this.mutate(workspaceId, (state) => {
+            const list = requireList(state, listId);
+            const index = requireTaskIndex(list, taskId);
+            const task = list.tasks[index];
+            const nextStatus = input.status ?? task.status;
+            const nextSubject = input.subject === undefined ? task.subject : normalizeTaskSubject(input.subject);
+            const nextContent = input.content === undefined ? task.content : normalizeTaskContent(input.content);
+            const nextPosition = input.position === undefined
+                ? index
+                : normalizeMovePosition(input.position, list.tasks.length, "Task");
+            const fieldsChanged = nextStatus !== task.status || nextSubject !== task.subject || nextContent !== task.content;
+            const positionChanged = nextPosition !== index;
+            if (!fieldsChanged && !positionChanged)
+                return false;
+            task.status = nextStatus;
+            task.subject = nextSubject;
+            task.content = nextContent;
+            if (positionChanged)
+                moveArrayEntry(list.tasks, index, nextPosition);
+            list.revision += 1;
+            return true;
+        });
+    }
+    deleteTask(workspaceId, listId, taskId) {
+        return this.mutate(workspaceId, (state) => {
+            const list = requireList(state, listId);
+            list.tasks.splice(requireTaskIndex(list, taskId), 1);
+            list.revision += 1;
+            return true;
+        });
+    }
+    deleteWorkspace(workspaceId) {
+        const id = normalizeWorkspaceId(workspaceId);
+        rmSync(this.statePath(id), { force: true });
+        try {
+            rmdirSync(this.workspaceStateDir(id));
+        }
+        catch (error) {
+            if (!isErrno(error, "ENOENT") && !isErrno(error, "ENOTEMPTY") && !isErrno(error, "EEXIST")) {
+                throw error;
+            }
+        }
+    }
+    mutate(workspaceId, mutateState) {
+        const id = normalizeWorkspaceId(workspaceId);
+        const loaded = this.tryReadState(id);
+        const state = loaded ? cloneState(loaded.state) : emptyState();
+        if (!mutateState(state)) {
+            return loaded
+                ? snapshot(loaded.state, loaded.fingerprint)
+                : this.writeState(id, state);
+        }
+        state.revision += 1;
+        return this.writeState(id, state);
+    }
+    tryReadState(workspaceId) {
+        const path = this.statePath(workspaceId);
+        let raw;
+        try {
+            raw = readFileSync(path);
+        }
+        catch (error) {
+            if (isErrno(error, "ENOENT"))
+                return undefined;
+            throw error;
+        }
+        if (raw.byteLength > MAX_TASK_STATE_BYTES) {
+            throw new Error(`Workspace Task state exceeds ${MAX_TASK_STATE_BYTES} bytes.`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw.toString("utf8"));
+        }
+        catch (error) {
+            throw new Error(`Workspace Task state is not valid JSON: ${errorMessage(error)}`);
+        }
+        const validated = workspaceTaskStateSchema.safeParse(parsed);
+        if (!validated.success) {
+            const details = validated.error.issues
+                .map((issue) => `${issue.path.length > 0 ? issue.path.join(".") : "state"}: ${issue.message}`)
+                .join("; ");
+            throw new Error(`Workspace Task state has an unsupported or invalid format: ${details}`);
+        }
+        return {
+            state: cloneState(validated.data),
+            fingerprint: fingerprint(raw),
+        };
+    }
+    writeState(workspaceId, state) {
+        const workspaceDir = this.workspaceStateDir(workspaceId);
+        mkdirSync(workspaceDir, { recursive: true, mode: 0o700 });
+        const validated = workspaceTaskStateSchema.parse(state);
+        const serialized = `${JSON.stringify(validated, null, 2)}\n`;
+        if (Buffer.byteLength(serialized, "utf8") > MAX_TASK_STATE_BYTES) {
+            throw new Error(`Workspace Task state exceeds ${MAX_TASK_STATE_BYTES} bytes.`);
+        }
+        const statePath = this.statePath(workspaceId);
+        const tempPath = `${statePath}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+        try {
+            writeFileSync(tempPath, serialized, { mode: 0o600 });
+            renameSync(tempPath, statePath);
+        }
+        finally {
+            rmSync(tempPath, { force: true });
+        }
+        return snapshot(validated, fingerprint(Buffer.from(serialized, "utf8")));
+    }
+    workspaceStateDir(workspaceId) {
+        return join(this.stateDir, "workspaces", workspaceId);
+    }
+    statePath(workspaceId) {
+        return join(this.workspaceStateDir(workspaceId), "tasks.json");
+    }
+}
+function emptyState() {
+    return { version: TASK_STATE_VERSION, revision: 0, lists: [] };
+}
+function snapshot(state, stateFingerprint) {
+    return {
+        ...cloneState(state),
+        fingerprint: stateFingerprint,
+    };
+}
+function taskSummary(snapshotValue) {
+    return {
+        level: "summary",
+        version: snapshotValue.version,
+        revision: snapshotValue.revision,
+        fingerprint: snapshotValue.fingerprint,
+        lists: snapshotValue.lists.map((list) => ({
+            id: list.id,
+            name: list.name,
+            state: list.state,
+            revision: list.revision,
+            taskCount: list.tasks.length,
+            unfinishedTaskCount: list.tasks.filter((task) => task.status !== "completed").length,
+        })),
+    };
+}
+function taskHeaders(snapshotValue, listId) {
+    const lists = listId === undefined
+        ? snapshotValue.lists
+        : [snapshotValue.lists[requireListIndex(snapshotValue, listId)]];
+    return {
+        level: "headers",
+        version: snapshotValue.version,
+        revision: snapshotValue.revision,
+        fingerprint: snapshotValue.fingerprint,
+        lists: lists.map((list) => ({
+            id: list.id,
+            name: list.name,
+            state: list.state,
+            revision: list.revision,
+            tasks: list.tasks.map((task) => ({
+                id: task.id,
+                status: task.status,
+                subject: task.subject,
+            })),
+        })),
+    };
+}
+function taskDetail(snapshotValue, listId, taskId) {
+    const list = requireList(snapshotValue, listId);
+    const task = list.tasks[requireTaskIndex(list, taskId)];
+    return {
+        level: "detail",
+        version: snapshotValue.version,
+        revision: snapshotValue.revision,
+        fingerprint: snapshotValue.fingerprint,
+        list: {
+            id: list.id,
+            name: list.name,
+            state: list.state,
+            revision: list.revision,
+        },
+        task: { ...task },
+    };
+}
+function cloneState(state) {
+    return {
+        version: state.version,
+        revision: state.revision,
+        lists: state.lists.map((list) => ({
+            ...list,
+            tasks: list.tasks.map((task) => ({ ...task })),
+        })),
+    };
+}
+function requireList(state, listId) {
+    return state.lists[requireListIndex(state, listId)];
+}
+function requireListIndex(state, listId) {
+    const index = state.lists.findIndex((list) => list.id === listId);
+    if (index < 0)
+        throw new Error(`Unknown Task List ${listId}.`);
+    return index;
+}
+function requireTaskIndex(list, taskId) {
+    const index = list.tasks.findIndex((task) => task.id === taskId);
+    if (index < 0)
+        throw new Error(`Task List ${list.id} has no Task ${taskId}.`);
+    return index;
+}
+function normalizeWorkspaceId(workspaceId) {
+    const value = workspaceId.trim();
+    if (!/^[a-z][a-z0-9_-]{1,127}$/.test(value)) {
+        throw new Error("Workspace ID is not valid for Workspace Task state.");
+    }
+    return value;
+}
+function normalizeListName(name) {
+    const value = name.trim();
+    if (!value)
+        throw new Error("Task List name must not be empty.");
+    if (value.length > MAX_LIST_NAME_LENGTH) {
+        throw new Error(`Task List name must be at most ${MAX_LIST_NAME_LENGTH} characters.`);
+    }
+    return value;
+}
+function normalizeTaskSubject(subject) {
+    const value = subject.trim();
+    if (!value)
+        throw new Error("Task subject must not be empty.");
+    if (value.length > MAX_TASK_SUBJECT_LENGTH) {
+        throw new Error(`Task subject must be at most ${MAX_TASK_SUBJECT_LENGTH} characters.`);
+    }
+    return value;
+}
+function normalizeTaskContent(content) {
+    if (content.length > MAX_TASK_CONTENT_LENGTH) {
+        throw new Error(`Task content must be at most ${MAX_TASK_CONTENT_LENGTH} characters.`);
+    }
+    return content;
+}
+function normalizeInsertPosition(position, length, label) {
+    if (position === undefined)
+        return length;
+    if (!Number.isInteger(position) || position < 0 || position > length) {
+        throw new Error(`${label} position must be an integer between 0 and ${length}.`);
+    }
+    return position;
+}
+function normalizeMovePosition(position, length, label) {
+    if (!Number.isInteger(position) || position < 0 || position >= length) {
+        throw new Error(`${label} position must be an integer between 0 and ${Math.max(0, length - 1)}.`);
+    }
+    return position;
+}
+function moveArrayEntry(values, from, to) {
+    const [value] = values.splice(from, 1);
+    values.splice(to, 0, value);
+}
+function fingerprint(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+function isErrno(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/workspaces.js

@@ -46,6 +46,37 @@ export class WorkspaceRegistry {
         }
         return this.openReusableCheckout(workspaceInput.path, openOptions.conversationScopeId, bootstrapContext);
     }
+    async inspectWorkspace(workspaceId) {
+        let session = this.store?.getSession(workspaceId);
+        if (!session) {
+            const workspace = this.workspaces.get(workspaceId);
+            if (workspace) {
+                session = {
+                    id: workspace.id,
+                    root: workspace.root,
+                    status: "active",
+                    mode: workspace.mode,
+                    sourceRoot: workspace.sourceRoot,
+                    baseRef: workspace.worktree?.baseRef,
+                    baseSha: workspace.worktree?.baseSha,
+                    branch: workspace.worktree?.branch,
+                    targetBranch: workspace.worktree?.targetBranch,
+                    managed: workspace.worktree?.managed ?? false,
+                    createdAt: "",
+                    lastUsedAt: "",
+                };
+            }
+        }
+        if (!session)
+            throw new Error(`Unknown workspaceId: ${workspaceId}.`);
+        const entry = await this.inventoryEntryForSession(session, Date.now(), false);
+        const { current: _current, ...inspection } = entry;
+        return {
+            kind: "workspace",
+            location: "local",
+            ...inspection,
+        };
+    }
     async listWorkspaces(input = {}, openOptions = {}) {
         this.pruneIdleWorkspaceSessions(openOptions.protectedWorkspaceIds ?? new Set());
         const now = Date.now();
@@ -77,36 +108,7 @@ export class WorkspaceRegistry {
         const rootKey = input.root
             ? await canonicalPath(assertAllowedPath(input.root, [...this.config.allowedRoots, this.config.worktreeRoot]))
             : undefined;
-        const entries = await Promise.all(sessions.map(async (session) => {
-            const rootValid = await this.validSessionRoot(session) !== undefined;
-            const lastUsedAt = Date.parse(session.lastUsedAt);
-            const idleMs = Number.isFinite(lastUsedAt) ? Math.max(0, now - lastUsedAt) : 0;
-            const state = session.status !== "active"
-                ? "closed"
-                : !rootValid
-                    ? "invalid"
-                    : idleMs >= WORKSPACE_STALE_REMINDER_MS
-                        ? "stale"
-                        : "active";
-            const projectRoot = session.sourceRoot ?? session.root;
-            return {
-                label: `${basename(resolve(projectRoot)) || "workspace"}/${session.id}`,
-                workspaceId: session.id,
-                root: session.root,
-                status: session.status,
-                state,
-                mode: session.mode,
-                sourceRoot: session.sourceRoot,
-                branch: session.branch,
-                targetBranch: session.targetBranch,
-                managed: session.managed,
-                createdAt: session.createdAt,
-                lastUsedAt: session.lastUsedAt,
-                idleMs,
-                rootValid,
-                current: currentWorkspaceIds.has(session.id),
-            };
-        }));
+        const entries = await Promise.all(sessions.map((session) => this.inventoryEntryForSession(session, now, currentWorkspaceIds.has(session.id))));
         const filtered = [];
         for (let index = 0; index < sessions.length; index += 1) {
             const session = sessions[index];
@@ -151,6 +153,36 @@ export class WorkspaceRegistry {
             },
         };
     }
+    async inventoryEntryForSession(session, now, current) {
+        const rootValid = await this.validSessionRoot(session) !== undefined;
+        const lastUsedAt = Date.parse(session.lastUsedAt);
+        const idleMs = Number.isFinite(lastUsedAt) ? Math.max(0, now - lastUsedAt) : 0;
+        const state = session.status !== "active"
+            ? "closed"
+            : !rootValid
+                ? "invalid"
+                : idleMs >= WORKSPACE_STALE_REMINDER_MS
+                    ? "stale"
+                    : "active";
+        const projectRoot = session.sourceRoot ?? session.root;
+        return {
+            label: `${basename(resolve(projectRoot)) || "workspace"}/${session.id}`,
+            workspaceId: session.id,
+            root: session.root,
+            status: session.status,
+            state,
+            mode: session.mode,
+            sourceRoot: session.sourceRoot,
+            branch: session.branch,
+            targetBranch: session.targetBranch,
+            managed: session.managed,
+            createdAt: session.createdAt,
+            lastUsedAt: session.lastUsedAt,
+            idleMs,
+            rootValid,
+            current,
+        };
+    }
     async resumeWorkspace(workspaceId, conversationScopeId, bootstrapContext = "auto") {
         const session = this.store?.getSession(workspaceId);
         const context = session?.status === "closed" && session.mode === "worktree"

package/docs/chatgpt-coding-workflow.md

@@ -49,9 +49,9 @@ returning the full project context and does not record the current fingerprint a
 already delivered. Context-delivery state remains conversation-scoped and does not
 change the persistent Workspace identity.
 
-Do not enumerate Workspace state on every normal open. When the user wants to
-continue earlier work, inspect known Workspaces, or clean up accumulated state, use
-the same Core tool in inventory mode:
+Do not enumerate Workspace state on every normal open. Use the same Core tool in
+inventory mode only when the user wants to discover known Workspaces, continue earlier
+work, or organize accumulated state:
 
 ```text
 open_workspace(action="list")
@@ -66,6 +66,16 @@ root/source root, or stale-only state. Entries include a compact label such as
 root validity, and whether that Workspace is currently selected by this
 conversation. Listing is observational and does not refresh `lastUsedAt`.
 
+When one known Workspace needs more bounded detail but must not be opened or resumed,
+use `open_workspace(action="inspect", workspaceId="...")`. Inspection is a strict
+allowlist projection: ordinary/worktree lifecycle metadata, Composite member
+summaries, safe Relay presentation metadata, and an existing Task List summary may be
+returned. It does not return bootstrap instructions, Skills, Capability guides,
+Subagent bodies, files, process/Activity output, credentials, routes, or Task bodies;
+it does not bind the conversation, mark bootstrap delivered, refresh `lastUsedAt`, or
+grant execution authority. Explicitly open the target Workspace before mutating or
+executing against it.
+
 Treat persisted status and derived state separately. `status="active"` means the
 record has not been explicitly closed. A valid recent record has `state="active"`;
 a valid active record idle for more than two days has `state="stale"`; an active

package/docs/configuration.md

@@ -327,17 +327,52 @@ Hooks, Skills, language services, and Activity facts remain owned by the underly
 Workspace. The Composite Activity Panel only aggregates their presentation into one
 Host Turn.
 
-Use `open_workspace(action="list")` only when the Agent needs to inspect known
-Workspaces, continue earlier work, or organize Workspace state. The inventory is
-paginated (50 records by default, at most 100) and can filter by Workspace ID,
-persisted status, derived state, mode, canonical root/source root, or stale-only
-state. Reading inventory does not refresh `lastUsedAt`. Persisted
-`status="active"` means the record has not been explicitly closed; the derived
-`state` distinguishes `active`, `stale`, `invalid`, and `closed`. A missing checkout
-or externally removed managed-worktree root can therefore remain diagnostically
-`status="active"` while appearing as `state="invalid"`. Canonical identity means
-ordinary same-target opens no longer accumulate duplicate inventory rows;
-`action="list"` remains the formal on-demand inventory path.
+## Workspace Tasks
+
+`workspace.tasks` keeps lightweight Task Lists in ForgeRelay-owned private Workspace
+state. Task data is not project bootstrap context and is not written into checkout or
+managed-worktree Git contents. Reads use progressive disclosure: default `get` returns
+List summaries and unfinished counts, `level="headers"` adds Task ID/status/subject,
+and `level="detail"` returns full content for one explicitly selected Task.
+
+ForgeRelay can append a bounded forgotten-update reminder after semantic Workspace
+work when active Lists still contain unfinished Tasks. The counter defaults to 30
+successful semantic work calls, resets on any Task mutation, treats one
+`batch.execute` as one call, and does not count Workspace inventory/lifecycle UI,
+Activity queries, Task reads, or Bash/process follow-up polling/input as new work.
+The counter is process-local and may reset on server restart; Task state itself
+remains durable.
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `FORGERELAY_TASK_REMINDER_INTERVAL` | `30` | Successful semantic work calls between Task update reminders; `0` disables reminders. |
+
+The same value may be persisted as `taskReminderInterval` in `config.json`. The
+legacy-compatible `DEVSPACE_TASK_REMINDER_INTERVAL` environment name is also accepted.
+
+Use `open_workspace(action="list")` only when the Agent needs lightweight inventory
+to discover known Workspaces, continue earlier work, or organize Workspace state. The
+inventory is paginated (50 records by default, at most 100) and can filter by Workspace
+ID, persisted status, derived state, mode, canonical root/source root, or stale-only
+state. Reading inventory does not refresh `lastUsedAt`. Persisted `status="active"`
+means the record has not been explicitly closed; the derived `state` distinguishes
+`active`, `stale`, `invalid`, and `closed`. A missing checkout or externally removed
+managed-worktree root can therefore remain diagnostically `status="active"` while
+appearing as `state="invalid"`. Canonical identity means ordinary same-target opens no
+longer accumulate duplicate inventory rows; `action="list"` remains the formal
+on-demand inventory path.
+
+`open_workspace(action="inspect", workspaceId="...")` is the bounded read-only detail
+path for one known Workspace. It uses an explicit allowlist and never opens/resumes the
+target, changes conversation bindings or bootstrap-delivery records, refreshes
+`lastUsedAt`, or grants file/process/Git/Capability authority. Safe projections include
+ordinary/worktree lifecycle metadata, Composite member availability summaries, Relay
+alias/execution-location presentation metadata, and an already-existing Task List
+summary. Inspection never returns AGENTS/CLAUDE contents, Skills, Capability-guide
+paths or contents, Subagent bodies/sessions, files, Git diffs, process/Activity output,
+Hook/review artifacts, credentials, network/SSH routes, or Task bodies. Relay inspection
+reports only that the Gateway route is known; it does not probe or claim the remote
+Workspace lifecycle state.
 
 For checkout-backed Workspaces, `close_workspace` defaults to `action="close"`:
 it marks the persistent Workspace closed, removes current conversation bindings, and