@akira-tl/forgerelay 0.8.9 → 0.9.0

package/dist/workspaces/resources/resource-monitor.js

@@ -0,0 +1,377 @@
+import { readFileSync, realpathSync, unwatchFile, watchFile } from "node:fs";
+import { relative, resolve, sep } from "node:path";
+import { createTwoFilesPatch } from "diff";
+import { skillSummaryFromContent } from "./skills.js";
+const WATCH_INTERVAL_MS = 750;
+const MAX_HISTORY = 128;
+const MAX_DELIVERY_CHARACTERS = 32 * 1024;
+const MAX_PATCH_CHARACTERS = 8 * 1024;
+const sharedWatches = new Map();
+let monitorSequence = 0;
+/**
+ * Tracks already-advertised Workspace instruction and Skill files. The OS-level
+ * stat watcher is process-global and canonical-path keyed, so two Workspaces or
+ * conversations that refer to the same physical file still create only one
+ * underlying watcher. Resource changes are delivered as bounded deltas.
+ */
+export class WorkspaceResourceMonitor {
+    id = `monitor-${++monitorSequence}`;
+    states = new Map();
+    trackWorkspace(input) {
+        const state = this.states.get(input.workspaceId) ?? {
+            root: input.root,
+            revision: 0,
+            tracked: new Map(),
+            subscriptions: new Map(),
+            changes: [],
+            deliveredRevisionByScope: new Map(),
+        };
+        state.root = input.root;
+        this.states.set(input.workspaceId, state);
+        const desired = new Map();
+        for (const path of input.availableInstructions) {
+            this.addDesired(desired, path, {
+                kind: "instruction-available",
+                displayPath: displayWorkspacePath(path, input.root),
+                exposeSkillBody: false,
+            });
+        }
+        for (const path of input.loadedInstructions) {
+            this.addDesired(desired, path, {
+                kind: "instruction-loaded",
+                displayPath: displayWorkspacePath(path, input.root),
+                exposeSkillBody: false,
+            });
+        }
+        for (const skill of input.skills) {
+            this.addDesired(desired, skill.filePath, {
+                kind: "skill",
+                displayPath: `skills://${encodeURIComponent(skill.name)}`,
+                skillName: skill.name,
+                exposeSkillBody: skill.activated,
+            });
+        }
+        for (const [key, stop] of state.tracked) {
+            if (desired.has(key))
+                continue;
+            stop();
+            state.tracked.delete(key);
+            state.subscriptions.delete(key);
+        }
+        for (const [key, item] of desired) {
+            state.subscriptions.set(key, item.subscription);
+            if (state.tracked.has(key)) {
+                synchronizeSharedWatch(key);
+                continue;
+            }
+            const subscriberId = `${this.id}:${input.workspaceId}:${key}`;
+            const stop = subscribeSharedWatch(item.path, subscriberId, (oldContent, newContent) => {
+                this.recordChange(input.workspaceId, key, oldContent, newContent);
+            });
+            state.tracked.set(key, stop);
+        }
+    }
+    trackLoadedInstruction(workspaceId, root, path) {
+        const state = this.states.get(workspaceId);
+        if (!state)
+            return;
+        const key = canonicalWatchKey(path);
+        state.subscriptions.set(key, {
+            kind: "instruction-loaded",
+            displayPath: displayWorkspacePath(path, root),
+            exposeSkillBody: false,
+        });
+        if (state.tracked.has(key))
+            return;
+        const subscriberId = `${this.id}:${workspaceId}:${key}`;
+        state.tracked.set(key, subscribeSharedWatch(path, subscriberId, (oldContent, newContent) => {
+            this.recordChange(workspaceId, key, oldContent, newContent);
+        }));
+    }
+    markSkillActivated(workspaceId, skillPath) {
+        const state = this.states.get(workspaceId);
+        if (!state)
+            return;
+        const subscription = state.subscriptions.get(canonicalWatchKey(skillPath));
+        if (subscription?.kind === "skill")
+            subscription.exposeSkillBody = true;
+    }
+    acknowledge(workspaceId, conversationScopeId) {
+        if (!conversationScopeId)
+            return;
+        const state = this.states.get(workspaceId);
+        if (!state)
+            return;
+        state.deliveredRevisionByScope.set(conversationScopeId, state.revision);
+        this.pruneDeliveredHistory(state);
+    }
+    claim(workspaceId, conversationScopeId) {
+        if (!conversationScopeId)
+            return undefined;
+        const state = this.states.get(workspaceId);
+        if (!state)
+            return undefined;
+        // File watcher delivery is advisory and can lag behind a tool call. Refresh
+        // tracked files synchronously before deciding whether this conversation has
+        // new context so rapid consecutive writes cannot be skipped.
+        for (const key of state.tracked.keys())
+            synchronizeSharedWatch(key);
+        const deliveredRevision = state.deliveredRevisionByScope.get(conversationScopeId) ?? state.revision;
+        const changes = state.changes.filter((change) => change.revision > deliveredRevision);
+        state.deliveredRevisionByScope.set(conversationScopeId, state.revision);
+        if (changes.length === 0)
+            return undefined;
+        const grouped = coalesceChanges(changes);
+        const sections = [];
+        const coveredComponents = new Set();
+        for (const change of grouped) {
+            const formatted = formatResourceChange(change);
+            if (!formatted)
+                continue;
+            sections.push(formatted.text);
+            for (const component of formatted.coveredComponents)
+                coveredComponents.add(component);
+        }
+        this.pruneDeliveredHistory(state);
+        if (sections.length === 0)
+            return undefined;
+        const header = "Workspace context changed after this Workspace was opened. Apply only these deltas; unchanged instructions and Skill metadata remain active:";
+        const joined = [header, ...sections].join("\n\n");
+        const text = joined.length <= MAX_DELIVERY_CHARACTERS
+            ? joined
+            : `${joined.slice(0, MAX_DELIVERY_CHARACTERS)}\n\n[Additional Workspace context deltas were truncated; reopen with context=\"auto\" to refresh metadata.]`;
+        return {
+            text,
+            coveredComponents: [...coveredComponents],
+            revision: state.revision,
+        };
+    }
+    isCurrentForScope(workspaceId, conversationScopeId) {
+        if (!conversationScopeId)
+            return false;
+        const state = this.states.get(workspaceId);
+        if (!state)
+            return false;
+        return state.deliveredRevisionByScope.get(conversationScopeId) === state.revision;
+    }
+    forgetWorkspace(workspaceId) {
+        const state = this.states.get(workspaceId);
+        if (!state)
+            return;
+        for (const stop of state.tracked.values())
+            stop();
+        this.states.delete(workspaceId);
+    }
+    pruneWorkspaces(activeWorkspaceIds) {
+        const active = new Set(activeWorkspaceIds);
+        for (const workspaceId of this.states.keys()) {
+            if (!active.has(workspaceId))
+                this.forgetWorkspace(workspaceId);
+        }
+    }
+    get watchedPhysicalFiles() {
+        return sharedWatches.size;
+    }
+    addDesired(desired, path, subscription) {
+        const key = canonicalWatchKey(path);
+        const current = desired.get(key);
+        if (current?.subscription.kind === "instruction-loaded")
+            return;
+        desired.set(key, { path, subscription });
+    }
+    recordChange(workspaceId, key, oldContent, newContent) {
+        if (oldContent === newContent)
+            return;
+        const state = this.states.get(workspaceId);
+        const subscription = state?.subscriptions.get(key);
+        if (!state || !subscription)
+            return;
+        state.revision += 1;
+        state.changes.push({
+            ...subscription,
+            revision: state.revision,
+            watchKey: key,
+            oldContent,
+            newContent,
+        });
+        if (state.changes.length > MAX_HISTORY) {
+            state.changes.splice(0, state.changes.length - MAX_HISTORY);
+        }
+    }
+    pruneDeliveredHistory(state) {
+        if (state.changes.length === 0 || state.deliveredRevisionByScope.size === 0)
+            return;
+        const floor = Math.min(...state.deliveredRevisionByScope.values());
+        while (state.changes[0] && state.changes[0].revision <= floor)
+            state.changes.shift();
+    }
+}
+function subscribeSharedWatch(inputPath, subscriberId, subscriber) {
+    const key = canonicalWatchKey(inputPath);
+    let entry = sharedWatches.get(key);
+    if (!entry) {
+        const watchPath = resolve(inputPath);
+        const listener = () => synchronizeSharedWatch(key);
+        entry = {
+            key,
+            watchPath,
+            content: readOptionalFile(watchPath),
+            subscribers: new Map(),
+            listener,
+        };
+        sharedWatches.set(key, entry);
+        watchFile(watchPath, { interval: WATCH_INTERVAL_MS, persistent: false }, listener);
+    }
+    else {
+        synchronizeSharedWatch(key);
+    }
+    entry.subscribers.set(subscriberId, subscriber);
+    return () => {
+        const current = sharedWatches.get(key);
+        if (!current)
+            return;
+        current.subscribers.delete(subscriberId);
+        if (current.subscribers.size > 0)
+            return;
+        unwatchFile(current.watchPath, current.listener);
+        sharedWatches.delete(key);
+    };
+}
+function synchronizeSharedWatch(key) {
+    const entry = sharedWatches.get(key);
+    if (!entry)
+        return;
+    const next = readOptionalFile(entry.watchPath);
+    if (next === entry.content)
+        return;
+    const previous = entry.content;
+    entry.content = next;
+    for (const subscriber of entry.subscribers.values())
+        subscriber(previous, next);
+}
+function canonicalWatchKey(path) {
+    const absolute = resolve(path);
+    try {
+        return realpathSync(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
+function readOptionalFile(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR")) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+function displayWorkspacePath(path, workspaceRoot) {
+    const relationship = relative(workspaceRoot, path);
+    if (!relationship || relationship === ".." || relationship.startsWith(`..${sep}`))
+        return resolve(path);
+    return relationship.split(sep).join("/");
+}
+function coalesceChanges(changes) {
+    const grouped = new Map();
+    for (const change of changes) {
+        const existing = grouped.get(change.watchKey);
+        if (!existing) {
+            grouped.set(change.watchKey, { ...change });
+            continue;
+        }
+        grouped.set(change.watchKey, {
+            ...change,
+            oldContent: existing.oldContent,
+        });
+    }
+    return [...grouped.values()].sort((left, right) => left.revision - right.revision);
+}
+function formatResourceChange(change) {
+    if (change.oldContent === change.newContent)
+        return undefined;
+    if (change.kind === "instruction-available") {
+        return {
+            text: `Nested Workspace instruction changed: ${change.displayPath}. Its body remains lazy; read it before working under that directory.`,
+            coveredComponents: [],
+        };
+    }
+    if (change.kind === "instruction-loaded") {
+        return {
+            text: [
+                `Workspace instruction delta: ${change.displayPath}`,
+                boundedPatch(change.displayPath, change.oldContent, change.newContent),
+            ].join("\n"),
+            coveredComponents: ["agentsFiles"],
+        };
+    }
+    if (change.exposeSkillBody) {
+        return {
+            text: [
+                `Active Skill delta: ${change.displayPath}`,
+                boundedPatch(change.displayPath, change.oldContent, change.newContent),
+            ].join("\n"),
+            coveredComponents: skillMetadataChanged(change) ? ["skills"] : [],
+        };
+    }
+    const metadata = formatSkillMetadataDelta(change);
+    return {
+        text: metadata ?? `Skill content changed: ${change.displayPath}. The Skill body was not injected because it was not active when it changed; reload it before next use.`,
+        coveredComponents: metadata ? ["skills"] : [],
+    };
+}
+function skillMetadataChanged(change) {
+    try {
+        const oldSummary = change.oldContent === undefined
+            ? undefined
+            : skillSummaryFromContent(change.oldContent, change.watchKey);
+        const newSummary = change.newContent === undefined
+            ? undefined
+            : skillSummaryFromContent(change.newContent, change.watchKey);
+        return JSON.stringify(oldSummary) !== JSON.stringify(newSummary);
+    }
+    catch {
+        return true;
+    }
+}
+function formatSkillMetadataDelta(change) {
+    try {
+        const oldSummary = change.oldContent === undefined
+            ? undefined
+            : skillSummaryFromContent(change.oldContent, change.watchKey);
+        const newSummary = change.newContent === undefined
+            ? undefined
+            : skillSummaryFromContent(change.newContent, change.watchKey);
+        if (JSON.stringify(oldSummary) === JSON.stringify(newSummary))
+            return undefined;
+        if (!oldSummary) {
+            return `Skill metadata added: ${change.displayPath}\n+ name: ${newSummary?.name ?? change.skillName ?? "unknown"}\n+ description: ${newSummary?.description ?? ""}\n+ disable-model-invocation: ${newSummary?.disableModelInvocation === true}`;
+        }
+        if (!newSummary)
+            return `Skill removed: ${change.displayPath}`;
+        const lines = [`Skill metadata delta: ${change.displayPath}`];
+        for (const field of ["name", "description", "disableModelInvocation"]) {
+            if (oldSummary[field] === newSummary[field])
+                continue;
+            const label = field === "disableModelInvocation" ? "disable-model-invocation" : field;
+            lines.push(`- ${label}: ${String(oldSummary[field])}`);
+            lines.push(`+ ${label}: ${String(newSummary[field])}`);
+        }
+        return lines.join("\n");
+    }
+    catch {
+        return `Skill metadata became unreadable or changed format: ${change.displayPath}. Reload it before next use.`;
+    }
+}
+function boundedPatch(path, oldContent, newContent) {
+    const patch = createTwoFilesPatch(path, path, oldContent ?? "", newContent ?? "", oldContent === undefined ? "missing" : "before", newContent === undefined ? "missing" : "after", { context: 1 });
+    const lines = patch.split("\n");
+    const hunk = lines.slice(Math.max(0, lines.findIndex((line) => line.startsWith("@@"))));
+    const compact = hunk.join("\n").trimEnd();
+    if (compact.length <= MAX_PATCH_CHARACTERS)
+        return compact;
+    return `${compact.slice(0, MAX_PATCH_CHARACTERS)}\n[delta truncated]`;
+}

package/dist/workspaces/resources/skills.js

@@ -4,7 +4,6 @@ import { basename, dirname, extname, join, resolve, sep } from "node:path";
 import { parse as parseYaml } from "yaml";
 import { markAdvertisedFileSourceActivated, resolveAdvertisedFileReadPath, } from "../../mcp/filesystem/advertised-files.js";
 import { expandHomePath, isPathInsideRoot } from "../../mcp/filesystem/roots.js";
-const SUBAGENT_DELEGATION_NAME = "subagent-delegation";
 const FRONTMATTER_DELIMITER = "---";
 export function effectiveSkillPaths(config, cwd) {
     const defaultPathCandidates = [
@@ -58,13 +57,7 @@ export function loadWorkspaceSkills(config, cwd) {
     }
     if (config.subagents)
         return { skills, diagnostics };
-    return {
-        skills: skills.filter((skill) => skill.name !== SUBAGENT_DELEGATION_NAME),
-        diagnostics: diagnostics.filter((diagnostic) => {
-            const collision = diagnostic.collision;
-            return !(collision?.resourceType === "skill" && collision.name === SUBAGENT_DELEGATION_NAME);
-        }),
-    };
+    return { skills, diagnostics };
 }
 function discoverSkills(sourcePath, diagnostics) {
     if (!existsSync(sourcePath))
@@ -158,8 +151,8 @@ function loadSkillFile(filePath, diagnostics) {
         return undefined;
     }
     const baseDir = dirname(filePath);
-    const name = normalizedSkillName(frontmatter.name, filePath);
-    if (!name) {
+    const summary = skillSummaryFromFrontmatter(frontmatter, filePath);
+    if (!summary.name) {
         diagnostics.push({
             type: "error",
             message: `Skill ${filePath} has an invalid or empty name.`,
@@ -167,14 +160,19 @@ function loadSkillFile(filePath, diagnostics) {
         });
         return undefined;
     }
-    const description = typeof frontmatter.description === "string"
-        ? frontmatter.description.trim()
-        : "";
     return {
-        name,
-        description,
+        ...summary,
         filePath: resolve(filePath),
         baseDir: resolve(baseDir),
+    };
+}
+export function skillSummaryFromContent(content, filePath) {
+    return skillSummaryFromFrontmatter(parseSkillFrontmatter(content), filePath);
+}
+function skillSummaryFromFrontmatter(frontmatter, filePath) {
+    return {
+        name: normalizedSkillName(frontmatter.name, filePath),
+        description: typeof frontmatter.description === "string" ? frontmatter.description.trim() : "",
         disableModelInvocation: frontmatter["disable-model-invocation"] === true,
     };
 }

package/dist/workspaces/sessions.js

@@ -149,6 +149,7 @@ export class WorkspaceSessionService {
                 continue;
             if (session.mode === "worktree" && worktreeAnchors.get(resolve(session.root))?.id === session.id)
                 continue;
+            this.context.forgetWorkspaceResources(session.id);
             this.workspaces.delete(session.id);
         }
     }
@@ -280,6 +281,7 @@ export class WorkspaceSessionService {
         workspace.loadedInstructionPaths.clear();
         const agentsFiles = await this.context.loadInitialAgentsFiles(workspace);
         const availableAgentsFiles = await this.context.findAvailableAgentsFiles(workspace, agentsFiles);
+        this.context.trackWorkspaceResources(workspace, agentsFiles, availableAgentsFiles);
         const { contextFingerprint, componentFingerprints: bootstrapComponentFingerprints, } = bootstrapContextFingerprints(workspace, agentsFiles, availableAgentsFiles);
         return {
             workspace,
@@ -356,6 +358,7 @@ export class WorkspaceSessionService {
             return context;
         }
         catch (error) {
+            this.context.forgetWorkspaceResources(session.id);
             this.workspaces.delete(session.id);
             try {
                 await discardFreshManagedWorktree({ worktree, config: this.config });

package/dist/workspaces.js

@@ -37,6 +37,7 @@ export class WorkspaceRegistry {
     }
     async openWorkspace(input, openOptions = {}) {
         this.sessions.pruneIdleWorkspaceSessions(openOptions.protectedWorkspaceIds ?? new Set());
+        this.context.pruneWorkspaceResources(this.workspaces.keys());
         const workspaceInput = typeof input === "string" ? { path: input } : input;
         const bootstrapContext = workspaceInput.context ?? "auto";
         if (workspaceInput.workspaceId) {
@@ -132,6 +133,7 @@ export class WorkspaceRegistry {
             this.sessions.deleteConversationBindingsForWorkspace(canonicalWorkspaceId);
             this.store.setSessionStatus(canonicalWorkspaceId, "closed");
         }
+        this.context.forgetWorkspaceResources(canonicalWorkspaceId);
         this.workspaces.delete(canonicalWorkspaceId);
     }
     deleteWorkspace(workspaceId) {
@@ -141,6 +143,7 @@ export class WorkspaceRegistry {
         }
         this.sessions.deleteConversationBindingsForWorkspace(session.id);
         this.store?.deleteSession(session.id);
+        this.context.forgetWorkspaceResources(session.id);
         this.workspaces.delete(session.id);
     }
     workspaceIdsForPhysicalWorkspace(workspace) {
@@ -243,6 +246,7 @@ export class WorkspaceRegistry {
         for (const aliasedWorkspaceId of aliasedWorkspaceIds) {
             this.sessions.deleteConversationBindingsForWorkspace(aliasedWorkspaceId);
             this.store?.setSessionStatus(aliasedWorkspaceId, "closed");
+            this.context.forgetWorkspaceResources(aliasedWorkspaceId);
             this.workspaces.delete(aliasedWorkspaceId);
         }
         return { ...result, hookReports };
@@ -394,6 +398,7 @@ export class WorkspaceRegistry {
         });
         const agentsFiles = await this.context.loadInitialAgentsFiles(workspace);
         const availableAgentsFiles = await this.context.findAvailableAgentsFiles(workspace, agentsFiles);
+        this.context.trackWorkspaceResources(workspace, agentsFiles, availableAgentsFiles);
         const { contextFingerprint, componentFingerprints: bootstrapComponentFingerprints, } = bootstrapContextFingerprints(workspace, agentsFiles, availableAgentsFiles);
         return {
             workspace,
@@ -410,6 +415,12 @@ export class WorkspaceRegistry {
     discoverPathInstructions(workspace, inputPath) {
         return this.context.discoverPathInstructions(workspace, inputPath);
     }
+    claimResourceUpdates(workspaceId, conversationScopeId) {
+        return this.context.claimResourceUpdates(workspaceId, conversationScopeId);
+    }
+    acknowledgeResourceUpdates(workspaceId, conversationScopeId) {
+        this.context.acknowledgeResourceUpdates(workspaceId, conversationScopeId);
+    }
 }
 export { formatAgentsPath };
 export { ensureCheckoutWorkspaceRoot } from "./workspaces/paths.js";

package/docs/chatgpt-coding-workflow.md

@@ -253,9 +253,10 @@ global config directory plus:
 The workspace result exposes only compact profile metadata so the host can
 choose a provider/profile without loading full provider launch details. Read the
 ForgeRelay-owned `subagents` capability guide when delegation is actually needed;
-0.3 no longer auto-loads the historical bundled `subagent-delegation` Skill for
-new setups. Existing user-authored or previously seeded Skills remain normal
-user configuration and are not deleted.
+ForgeRelay no longer ships or auto-loads the historical bundled `subagent-delegation` Skill.
+Official delegation behavior lives in the `subagents` capability guide/MCP contract;
+existing user-authored or previously seeded Skills remain normal user configuration
+and are not deleted.
 
 Host 正常委派通过现有 `capability` Gateway 中的 `subagent.session` 完成，不增加新的 Core MCP tool。支持的生命周期操作包括 `start`、`resume`、`status`、`list`、`stop` 和 `delete`；具体参数与 provider continuation 能力以 `subagents` capability guide 为准。
 

package/docs/configuration.md

@@ -224,7 +224,7 @@ use structured process launch and never go through a shell:
 }
 ```
 
-Global configuration uses the same definition shape under `languageServers`:
+Global configuration uses the same definition shape under `languageServers`. ForgeRelay can also keep optional npm-managed Language Servers under its private config directory. Agent-triggered installation is disabled by default and must be explicitly enabled:
 
 ```json
 {
@@ -233,10 +233,13 @@ Global configuration uses the same definition shape under `languageServers`:
       "command": "/absolute/path/to/typescript-language-server",
       "args": ["--stdio"]
     }
-  }
+  },
+  "allowAgentLanguageServerInstall": false
 }
 ```
 
+`forgerelay init` can manage TypeScript/JavaScript and Pyright installations without touching global npm. When `allowAgentLanguageServerInstall` is `true`, an Agent may use `code.intelligence` operations `managed.status` and `managed.install`; successful installs become discoverable by the same running ForgeRelay process on the next semantic request, with no restart required. Rust Analyzer, `gopls`, and `clangd` remain external toolchain/system installations.
+
 Explicit configuration can set `"enabled": false` to suppress the matching
 built-in definition. Project values override global values, and both override
 built-in defaults. ForgeRelay resolves a Language project by walking ancestors of
@@ -246,10 +249,12 @@ not recursively scan the Workspace.
 Code-intelligence input positions are 1-based line and 1-based Unicode code-point
 column values. The Workspace filesystem is the only v1 document source of truth.
 
+Successful `write`, `edit`, `rename`, and Codex `apply_patch` mutations automatically request Language Server diagnostics for affected code files. Non-empty diagnostics are appended to the same mutation response; missing Language Servers are skipped without turning a successful file mutation into a failure.
+
 For contributor/release interoperability checks, run `npm run lsp:interop`. The
-command tests each supported real Language server that is already on `PATH` through
-ForgeRelay built-in discovery and stdio LSP, reports a clear skip when an executable
-is absent, and never installs external dependencies.
+command tests each supported real Language server that is already discoverable through
+ForgeRelay built-in resolution and stdio LSP, reports a clear skip when an executable
+is absent, and never installs external dependencies itself.
 Definition results may point outside the Workspace and are then marked
 `external: true`; this is informational only and does not expand allowed roots or
 file-tool authority.
@@ -333,23 +338,30 @@ inventory is paginated (50 records by default, at most 100) and can filter by Wo
 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.
+`active`, `stale`, `invalid`, and `closed`. Active managed-worktree entries also expose
+a bounded `recovery` projection: ForgeRelay observes backing/source availability, the
+recorded managed and target branches, Git worktree registration, and the backing's
+current branch, then classifies the result as `healthy`, `recoverable`, or
+`manual-intervention`. A missing checkout or externally damaged managed worktree can
+therefore remain diagnostically `status="active"` while appearing as `state="invalid"`.
+This projection is observation only: inventory never runs `git worktree prune`, creates
+or removes worktrees/branches, or otherwise repairs Git state. 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.
+ordinary/worktree lifecycle metadata, managed-worktree recovery observations,
+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. For Relay Workspaces the Gateway asks
+the Execution ForgeRelay for this same bounded inspection and forwards sanitized
+lifecycle/recovery facts under the Gateway Workspace identity; the Gateway does not
+inspect or mutate the remote Git repository itself.
 
 For checkout-backed Workspaces, `close_workspace` defaults to `action="close"`:
 it marks the persistent Workspace closed, removes current conversation bindings, and
@@ -605,10 +617,10 @@ forgerelay agents run <profile-or-provider-or-id> "<prompt>"
 forgerelay agents show <id>
 ```
 
-0.3 no longer auto-discovers or seeds the package's historical bundled
-`subagent-delegation` Skill for new setups. An existing or user-authored Skill
-with that name remains an ordinary Skill and is still discovered from the normal
-Skill paths when subagents are enabled; ForgeRelay does not delete or rewrite it.
+ForgeRelay no longer ships or seeds the historical bundled `subagent-delegation` Skill.
+The official delegation rules live in the `subagents` capability guide and MCP
+contract. A user-authored Skill with that name is an ordinary Skill discovered
+from the normal Skill paths; ForgeRelay does not reserve, delete, or rewrite it.
 
 ## Logging