@akira-tl/forgerelay 0.8.9 → 0.9.0

package/dist/lsp/runtime/diagnostic-snapshots.js

@@ -4,6 +4,7 @@ export class DiagnosticSnapshotStore {
     maxDiagnosticsPerDocument;
     pushSnapshots = new Map();
     pullSnapshots = new Map();
+    pushWaiters = new Map();
     pushObserved = false;
     constructor(maxDocuments, maxDiagnosticsPerDocument) {
         this.maxDocuments = maxDocuments;
@@ -11,10 +12,13 @@ export class DiagnosticSnapshotStore {
     }
     capturePush(params, document, encoding) {
         this.pushObserved = true;
-        if (!document)
+        if (!document) {
+            this.notifyPushWaiters(params.uri, true);
             return;
+        }
         const snapshot = this.normalizeSnapshot(params.diagnostics, document, encoding, params.version === undefined ? {} : { publishedVersion: params.version });
         this.setBounded(this.pushSnapshots, params.uri, snapshot);
+        this.notifyPushWaiters(params.uri, true);
     }
     capturePull(diagnostics, document, encoding, resultId) {
         const snapshot = this.normalizeSnapshot(diagnostics, document, encoding, resultId === undefined ? {} : { resultId });
@@ -41,12 +45,52 @@ export class DiagnosticSnapshotStore {
     readPull(document, limit) {
         return this.read(this.pullSnapshots, document, limit, false);
     }
+    async waitForFreshPush(document, limit, timeoutMs, signal) {
+        let snapshot = this.readPush(document, limit);
+        const deadline = Date.now() + timeoutMs;
+        while (snapshot.freshness.state === "missing" || snapshot.freshness.state === "stale") {
+            if (signal?.aborted)
+                break;
+            const remaining = deadline - Date.now();
+            if (remaining <= 0 || !await this.waitForPush(document.uri, remaining, signal))
+                break;
+            snapshot = this.readPush(document, limit);
+        }
+        return snapshot;
+    }
     hasObservedPushDiagnostics() {
         return this.pushObserved;
     }
+    waitForPush(uri, timeoutMs, signal) {
+        if (signal?.aborted)
+            return Promise.resolve(false);
+        return new Promise((resolve) => {
+            let settled = false;
+            const waiters = this.pushWaiters.get(uri) ?? new Set();
+            const finish = (observed) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", onAbort);
+                waiters.delete(finish);
+                if (waiters.size === 0)
+                    this.pushWaiters.delete(uri);
+                resolve(observed);
+            };
+            const onAbort = () => finish(false);
+            const timer = setTimeout(() => finish(false), timeoutMs);
+            timer.unref();
+            signal?.addEventListener("abort", onAbort, { once: true });
+            waiters.add(finish);
+            this.pushWaiters.set(uri, waiters);
+        });
+    }
     clear() {
         this.pushSnapshots.clear();
         this.pullSnapshots.clear();
+        for (const uri of [...this.pushWaiters.keys()])
+            this.notifyPushWaiters(uri, false);
         this.pushObserved = false;
     }
     get size() {
@@ -70,6 +114,13 @@ export class DiagnosticSnapshotStore {
             ...metadata,
         };
     }
+    notifyPushWaiters(uri, observed) {
+        const waiters = this.pushWaiters.get(uri);
+        if (!waiters)
+            return;
+        for (const waiter of [...waiters])
+            waiter(observed);
+    }
     setBounded(snapshots, uri, snapshot) {
         snapshots.delete(uri);
         snapshots.set(uri, snapshot);

package/dist/lsp/runtime/managed-language-servers.js

@@ -0,0 +1,172 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { delimiter, join, resolve } from "node:path";
+const MANAGED_LANGUAGE_SERVERS = {
+    typescript: {
+        id: "typescript",
+        label: "TypeScript / JavaScript",
+        executable: "typescript-language-server",
+        packages: ["typescript-language-server@6", "typescript@6"],
+    },
+    pyright: {
+        id: "pyright",
+        label: "Python (Pyright)",
+        executable: "pyright-langserver",
+        packages: ["pyright@1"],
+    },
+};
+export function managedLanguageServerRoot(configDir) {
+    return join(configDir, "language-servers");
+}
+export function managedLanguageServerBinDir(configDir) {
+    return join(managedLanguageServerRoot(configDir), "node_modules", ".bin");
+}
+export function managedLanguageServerExecutablePath(configDir, id, platform = process.platform) {
+    const bin = managedLanguageServerBinDir(configDir);
+    const executable = MANAGED_LANGUAGE_SERVERS[id].executable;
+    const extensions = platform === "win32" ? [".cmd", ".exe", ".bat", ""] : [""];
+    return extensions
+        .map((extension) => join(bin, `${executable}${extension}`))
+        .find((path) => existsSync(path));
+}
+export function managedLanguageServerIdForCommand(configDir, command, platform = process.platform) {
+    return supportedManagedLanguageServers().find((id) => {
+        const executable = managedLanguageServerExecutablePath(configDir, id, platform);
+        if (executable === undefined)
+            return false;
+        const executablePath = resolve(executable);
+        const commandPath = resolve(command);
+        return platform === "win32"
+            ? executablePath.toLowerCase() === commandPath.toLowerCase()
+            : executablePath === commandPath;
+    });
+}
+export function managedTypeScriptTsserverPath(configDir) {
+    const path = join(managedLanguageServerRoot(configDir), "node_modules", "typescript", "lib", "tsserver.js");
+    return existsSync(path) ? path : undefined;
+}
+export function managedLanguageServerRuntimeIdentity(configDir, id) {
+    const packageNames = id === "typescript"
+        ? ["typescript-language-server", "typescript"]
+        : ["pyright"];
+    try {
+        const versions = packageNames.map((name) => {
+            const packageJson = JSON.parse(readFileSync(join(managedLanguageServerRoot(configDir), "node_modules", name, "package.json"), "utf8"));
+            if (!packageJson.version)
+                throw new Error(`Missing version for ${name}`);
+            return [name, packageJson.version];
+        });
+        return JSON.stringify(versions);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function withManagedLanguageServerPath(env, configDir) {
+    if (!configDir)
+        return { ...env };
+    const bin = managedLanguageServerBinDir(configDir);
+    return {
+        ...env,
+        PATH: [bin, env.PATH].filter((value) => Boolean(value)).join(delimiter),
+    };
+}
+export function managedLanguageServerOptions() {
+    return [
+        {
+            value: "typescript",
+            label: MANAGED_LANGUAGE_SERVERS.typescript.label,
+            hint: "Installs typescript-language-server and TypeScript into ForgeRelay's private config directory.",
+        },
+        {
+            value: "pyright",
+            label: MANAGED_LANGUAGE_SERVERS.pyright.label,
+            hint: "Installs Pyright into ForgeRelay's private config directory.",
+        },
+    ];
+}
+export function supportedManagedLanguageServers() {
+    return Object.keys(MANAGED_LANGUAGE_SERVERS);
+}
+export function installedManagedLanguageServers(configDir) {
+    return supportedManagedLanguageServers()
+        .filter((id) => managedExecutableExists(configDir, MANAGED_LANGUAGE_SERVERS[id].executable));
+}
+export function managedLanguageServerPackages(ids) {
+    const packages = new Set();
+    for (const id of ids) {
+        for (const packageSpec of MANAGED_LANGUAGE_SERVERS[id].packages)
+            packages.add(packageSpec);
+    }
+    return [...packages];
+}
+export async function installManagedLanguageServers(ids, configDir, runNpm = defaultNpmRunner) {
+    const selected = Array.from(new Set(ids));
+    const root = managedLanguageServerRoot(configDir);
+    const packages = managedLanguageServerPackages(selected);
+    if (packages.length === 0)
+        return { installed: [], packages: [], root };
+    mkdirSync(root, { recursive: true });
+    const packageJsonPath = join(root, "package.json");
+    if (!existsSync(packageJsonPath)) {
+        writeFileSync(packageJsonPath, JSON.stringify({
+            name: "forgerelay-managed-language-servers",
+            private: true,
+            description: "ForgeRelay-managed optional Language Servers. Do not publish.",
+        }, null, 2) + "\n");
+    }
+    await runNpm([
+        "install",
+        "--prefix",
+        root,
+        "--save-exact",
+        "--no-audit",
+        "--no-fund",
+        ...packages,
+    ]);
+    for (const id of selected)
+        assertManagedLanguageServerInstall(configDir, id);
+    return { installed: selected, packages, root };
+}
+function assertManagedLanguageServerInstall(configDir, id) {
+    if (!managedLanguageServerExecutablePath(configDir, id)) {
+        throw new Error(`Managed Language Server ${id} installed without its expected executable.`);
+    }
+    if (id === "typescript" && !managedTypeScriptTsserverPath(configDir)) {
+        throw new Error("Managed TypeScript Language Server installed without a compatible TypeScript tsserver.js. " +
+            "ForgeRelay requires a tsserver-based TypeScript package for typescript-language-server.");
+    }
+}
+function managedExecutableExists(configDir, executable) {
+    const bin = managedLanguageServerBinDir(configDir);
+    if (process.platform === "win32") {
+        return [".cmd", ".exe", ".bat", ""].some((extension) => existsSync(join(bin, `${executable}${extension}`)));
+    }
+    return existsSync(join(bin, executable));
+}
+function defaultNpmRunner(args) {
+    const command = process.platform === "win32" ? "npm.cmd" : "npm";
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            env: process.env,
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+            shell: process.platform === "win32",
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.setEncoding("utf8");
+        child.stderr?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => { stdout += chunk; });
+        child.stderr?.on("data", (chunk) => { stderr += chunk; });
+        child.once("error", reject);
+        child.once("close", (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            const detail = (stderr || stdout).trim();
+            reject(new Error(`npm install for managed Language Servers failed with exit ${code ?? "unknown"}${detail ? `: ${detail}` : ""}`));
+        });
+    });
+}

package/dist/lsp/runtime/manager.js

@@ -1,7 +1,9 @@
+import { createHash } from "node:crypto";
 import { realpath } from "node:fs/promises";
 import { resolve, sep } from "node:path";
 import { CodeIntelligenceError, LanguageService, languageServiceKey, } from "../code-intelligence.js";
 import { LanguageServerConfigurationError, resolveLanguageProject, } from "../language-server-config.js";
+import { managedLanguageServerIdForCommand, managedLanguageServerRuntimeIdentity, managedTypeScriptTsserverPath, withManagedLanguageServerPath, } from "./managed-language-servers.js";
 const LANGUAGE_SERVICE_IDLE_MS = 10 * 60 * 1_000;
 const LANGUAGE_SERVICE_CLEANUP_INTERVAL_MS = 60 * 1_000;
 const MAX_LANGUAGE_SERVICES = 16;
@@ -50,11 +52,12 @@ export class CodeIntelligenceManager {
         try {
             canonicalWorkspaceRoot = await realpath(resolve(workspaceRoot));
             this.assertWorkspaceRootAvailable(canonicalWorkspaceRoot);
-            project = await resolveLanguageProject({
+            project = withManagedLanguageServerRuntime(await resolveLanguageProject({
                 workspaceRoot: canonicalWorkspaceRoot,
                 sourcePath: input.path,
                 globalConfig: this.config.languageServers,
-            });
+                env: withManagedLanguageServerPath(process.env, this.config.configDir),
+            }), this.config.configDir);
         }
         catch (error) {
             if (error instanceof LanguageServerConfigurationError) {
@@ -319,6 +322,38 @@ export class CodeIntelligenceManager {
         await candidate[1].shutdown();
     }
 }
+function withManagedLanguageServerRuntime(project, configDir) {
+    if (!configDir)
+        return project;
+    const managedId = managedLanguageServerIdForCommand(configDir, project.definition.command);
+    if (!managedId)
+        return project;
+    const runtimeIdentity = managedLanguageServerRuntimeIdentity(configDir, managedId);
+    if (!runtimeIdentity)
+        return project;
+    let initializationOptions = project.definition.initializationOptions;
+    if (managedId === "typescript") {
+        const tsserverPath = managedTypeScriptTsserverPath(configDir);
+        if (!tsserverPath)
+            return project;
+        initializationOptions = { tsserver: { path: tsserverPath } };
+    }
+    const fingerprint = createHash("sha256")
+        .update(project.definition.fingerprint)
+        .update("\0")
+        .update(runtimeIdentity)
+        .update("\0")
+        .update(JSON.stringify(initializationOptions ?? null))
+        .digest("hex");
+    return {
+        ...project,
+        definition: {
+            ...project.definition,
+            ...(initializationOptions === undefined ? {} : { initializationOptions }),
+            fingerprint,
+        },
+    };
+}
 function identityBelongsToWorkspaceRoot(identity, workspaceRoot) {
     try {
         const parsed = JSON.parse(identity);

package/dist/lsp/runtime/process-launch.js

@@ -0,0 +1,3 @@
+export function languageServerCommandRequiresShell(command, platform = process.platform) {
+    return platform === "win32" && /\.(?:cmd|bat)$/i.test(command);
+}

package/dist/lsp/test-support/server-fixture.js

@@ -35,6 +35,7 @@ export async function createCodeIntelligenceServerFixture(t, options = {}) {
         FORGERELAY_OAUTH_OWNER_TOKEN: "test-owner-token-that-is-long-enough",
         PORT: "1",
     });
+    config.allowAgentLanguageServerInstall = options.allowAgentLanguageServerInstall === true;
     const store = new SqliteWorkspaceStore(stateDir);
     const workspaces = new WorkspaceRegistry(config, store);
     const auditStore = new ActivityAuditStore(stateDir);
@@ -46,7 +47,9 @@ export async function createCodeIntelligenceServerFixture(t, options = {}) {
         turnIdForConversation: (conversationScopeId, workspaceId) => activityQueries.currentTurnId(conversationScopeId, workspaceId),
     });
     const codeIntelligence = new CodeIntelligenceManager(config, options.codeIntelligenceOptions);
-    const server = createMcpServer(config, workspaces, createReviewCheckpointManager(), processSessions, [], [], codeIntelligence, activityLifecycle, bashOutputStore, activityQueries);
+    const server = createMcpServer(config, workspaces, createReviewCheckpointManager(), processSessions, [], [], codeIntelligence, activityLifecycle, bashOutputStore, activityQueries, options.managedLanguageServerInstaller
+        ? { managedLanguageServerInstaller: options.managedLanguageServerInstaller }
+        : {});
     const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
     const client = new Client({ name: "forgerelay-code-intelligence-test-client", version: "1.0.0" });
     await Promise.all([client.connect(clientTransport), server.connect(serverTransport)]);
@@ -73,7 +76,7 @@ export async function createCodeIntelligenceServerFixture(t, options = {}) {
             retryDelay: 100,
         });
     });
-    return { client, project, codeIntelligence, close };
+    return { client, project, config, codeIntelligence, close };
 }
 export async function callOpen(client, path, conversationScopeId) {
     return client.callTool({

package/dist/mcp/process/process-platform.js

@@ -11,23 +11,35 @@ const defaultProcessTreeRuntime = {
         return !result.error && result.status === 0;
     },
 };
-const LOGIN_SHELLS = new Set(["bash", "ksh", "zsh"]);
-const POSIX_SHELLS = new Set(["ash", "dash", "sh"]);
+const POSIX_SHELLS = new Set(["ash", "dash", "ksh", "sh"]);
 export function resolveShellCommand(command, platform = process.platform, environment = process.env) {
     if (platform === "win32") {
         return {
             executable: environment.ComSpec ?? environment.COMSPEC ?? "cmd.exe",
-            args: ["/d", "/s", "/c", command],
+            // Match Node's native `spawn(command, { shell: cmd.exe })` quoting.
+            // cmd.exe /S applies special quote stripping, so the whole command must
+            // be wrapped even when the executable inside it is already quoted.
+            args: ["/d", "/s", "/c", `"${command}"`],
             windowsVerbatimArguments: true,
         };
     }
-    const configuredShell = environment.SHELL;
-    const shellName = configuredShell ? basename(configuredShell) : "";
-    if (configuredShell && LOGIN_SHELLS.has(shellName)) {
-        return { executable: configuredShell, args: ["-lc", command] };
+    // Agent and Hook commands must not source the user's interactive/login shell
+    // configuration. ForgeRelay already inherits PATH and other environment from
+    // the process that launched the server; re-running zsh/bash as a login shell
+    // can inject prompts, banners, aliases, plugins, or other user-only behavior.
+    const configuredShell = environment.FORGERELAY_COMMAND_SHELL?.trim();
+    const executable = configuredShell || (platform === "linux" || platform === "darwin"
+        ? "/bin/bash"
+        : "/bin/sh");
+    const shellName = basename(executable);
+    if (shellName === "bash") {
+        return { executable, args: ["--noprofile", "--norc", "-c", command] };
     }
-    if (configuredShell && POSIX_SHELLS.has(shellName)) {
-        return { executable: configuredShell, args: ["-c", command] };
+    if (shellName === "zsh") {
+        return { executable, args: ["-f", "-c", command] };
+    }
+    if (POSIX_SHELLS.has(shellName)) {
+        return { executable, args: ["-c", command] };
     }
     return { executable: "/bin/sh", args: ["-c", command] };
 }

package/dist/mcp/process/process-sessions.js

@@ -2,7 +2,7 @@ import { spawn } from "node:child_process";
 import { resolveShellCommand, terminateProcessTree } from "./process-platform.js";
 const DEFAULT_EXEC_YIELD_MS = 10_000;
 const DEFAULT_INTERACTIVE_YIELD_MS = 250;
-const DEFAULT_POLL_YIELD_MS = 5_000;
+export const DEFAULT_POLL_YIELD_MS = 60_000;
 const MAX_START_YIELD_MS = 300_000;
 const MAX_COMMAND_YIELD_MS = 300_000;
 const MAX_POLL_YIELD_MS = 300_000;
@@ -437,7 +437,7 @@ export class ProcessManager {
     startPipe(processEntry, input) {
         const shell = resolveShellCommand(input.command);
         const detached = process.platform !== "win32";
-        const child = spawn(input.command, {
+        const child = spawn(shell.executable, shell.args, {
             cwd: input.cwd,
             env: processEnvironment({
                 workspaceId: input.workspaceId,
@@ -446,8 +446,8 @@ export class ProcessManager {
             }),
             stdio: "pipe",
             windowsHide: true,
+            windowsVerbatimArguments: shell.windowsVerbatimArguments,
             detached,
-            shell: shell.executable,
         });
         processEntry.process = {
             write: (data) => child.stdin.write(data),

package/dist/mcp/process/tools.js

@@ -40,7 +40,7 @@ function registerBashTool(options) {
             columns: z.number().int().min(1).max(1_000).optional().describe("Initial PTY width for action=run, or resize width for action=process."),
             rows: z.number().int().min(1).max(1_000).optional().describe("Initial PTY height for action=run, or resize height for action=process."),
             workingDirectory: z.string().optional().describe("For action=run, working directory relative to the workspace root. Defaults to the workspace root."),
-            yieldTimeMs: z.number().int().min(0).max(300_000).optional().describe("Maximum feedback wait, not a minimum delay: if the process finishes sooner, the call returns immediately. For long-running commands or wait-only action=process calls, set a long window near the Host request deadline (60000ms when supported) instead of repeated short polling. For action=run, use 0 for immediate background handoff; otherwise defaults to 10000ms. For action=process, wait-only calls default to 5000ms and interaction to 250ms."),
+            yieldTimeMs: z.number().int().min(0).max(300_000).optional().describe("Maximum feedback wait, not a minimum delay: if the process finishes sooner, the call returns immediately. For long-running commands or wait-only action=process calls, set a long window near the Host request deadline (60000ms when supported) instead of repeated short polling. For action=run, use 0 for immediate background handoff; otherwise defaults to 10000ms. For action=process, wait-only calls default to 60000ms and interaction to 250ms."),
             timeoutMs: z.number().int().min(1).max(86_400_000).optional().describe("For action=run, total execution timeout from process start. On expiry ForgeRelay terminates the process. Omit for no ForgeRelay execution deadline."),
             maxOutputTokens: z.number().int().positive().max(100_000).optional().describe("Approximate output token budget. Defaults to 10000."),
         },
@@ -70,7 +70,7 @@ function registerBashTool(options) {
                 ...(maxOutputTokens !== undefined ? { maxOutputTokens } : {}),
             }, routing.hostScopeIdFor(extra._meta, extra.sessionId));
             return action === "run"
-                ? routing.presentSemantic(response, target)
+                ? routing.presentSemantic(response, target, routing.hostScopeIdFor(extra._meta, extra.sessionId))
                 : routing.present(response, target);
         }
         const workspace = workspaces.getWorkspace(executionWorkspaceId);
@@ -91,7 +91,7 @@ function registerBashTool(options) {
                 yieldTimeMs,
                 timeoutMs,
                 maxOutputTokens,
-            }, executionContext), target);
+            }, executionContext), target, routing.hostScopeIdFor(extra._meta, extra.sessionId));
         }
         if (action === "output") {
             if (!outputId)
@@ -202,7 +202,7 @@ function registerCodexProcessTools(options) {
                 ...(yieldTimeMs !== undefined ? { yieldTimeMs } : {}),
                 ...(timeoutMs !== undefined ? { timeoutMs } : {}),
                 ...(maxOutputTokens !== undefined ? { maxOutputTokens } : {}),
-            }, routing.hostScopeIdFor(extra._meta, extra.sessionId)), target);
+            }, routing.hostScopeIdFor(extra._meta, extra.sessionId)), target, routing.hostScopeIdFor(extra._meta, extra.sessionId));
         }
         return routing.presentSemantic(await shellRun({
             workspaceId: target.executionWorkspaceId,
@@ -215,7 +215,7 @@ function registerCodexProcessTools(options) {
             yieldTimeMs,
             timeoutMs,
             maxOutputTokens,
-        }, context), target);
+        }, context), target, routing.hostScopeIdFor(extra._meta, extra.sessionId));
     });
     registerAppTool(server, "write_stdin", {
         title: "Write to process",
@@ -229,7 +229,7 @@ function registerCodexProcessTools(options) {
             chars: z.string().optional().describe("Characters to write. Omit or pass an empty string to poll."),
             columns: z.number().int().min(1).max(1_000).optional().describe("Resize a PTY to this width."),
             rows: z.number().int().min(1).max(1_000).optional().describe("Resize a PTY to this height."),
-            yieldTimeMs: z.number().int().min(0).max(300_000).optional().describe("Milliseconds to keep waiting before returning again, max 300000. Polling defaults to 5000; interaction defaults to 250."),
+            yieldTimeMs: z.number().int().min(0).max(300_000).optional().describe("Milliseconds to keep waiting before returning again, max 300000. Polling defaults to 60000; interaction defaults to 250."),
             maxOutputTokens: z.number().int().positive().max(100_000).optional().describe("Approximate output token budget. Defaults to 10000."),
         },
         outputSchema: processOutputSchema(),

package/dist/mcp/server/core/capability-registry.js

@@ -241,6 +241,11 @@ export function createCapabilityRegistry(dependencies) {
             path: z.string().min(1),
             limit: z.number().int().min(1).max(MAX_CODE_INTELLIGENCE_RESULT_LIMIT).optional(),
         }).strict(),
+        z.object({ operation: z.literal("managed.status") }).strict(),
+        z.object({
+            operation: z.literal("managed.install"),
+            servers: z.array(z.enum(["typescript", "pyright"])).min(1),
+        }).strict(),
     ]);
     return new CapabilityRegistry([
         {
@@ -273,7 +278,7 @@ export function createCapabilityRegistry(dependencies) {
         ...(dependencies.codeIntelligence
             ? [{
                     name: "code.intelligence",
-                    description: "Read semantic code information through an available Language server without changing the Workspace.",
+                    description: "Read semantic code information and, when explicitly enabled by the user, manage ForgeRelay-owned Language Servers for this instance.",
                     guideName: "code-intelligence",
                     readGuideBeforeFirstUse: true,
                     batchPolicy: "parallel",
@@ -300,7 +305,7 @@ export function createCapabilityRegistry(dependencies) {
         ...(dependencies.subagentSession
             ? [{
                     name: "subagent.session",
-                    description: "Coordinate provider-backed Subagent Sessions in the current Execution Workspace.",
+                    description: "Delegate explicit work to provider-backed Subagent Sessions in the current Execution Workspace; disclose delegation and verify returned results before presenting them as final.",
                     guideName: "subagents",
                     readGuideBeforeFirstUse: true,
                     batchPolicy: "unsupported",

package/dist/mcp/server/core/schemas.js

@@ -94,6 +94,26 @@ export const workspaceSubagentProviderOutputSchema = z.object({
 export const workspaceAvailableAgentsFileOutputSchema = z.object({
     path: z.string(),
 });
+export const managedWorktreeRecoveryOutputSchema = z.object({
+    classification: z.enum(["healthy", "recoverable", "manual-intervention"]),
+    conditions: z.array(z.enum([
+        "backing-missing",
+        "managed-branch-missing",
+        "git-registration-stale",
+        "git-registration-missing",
+        "git-registration-unavailable",
+        "branch-mismatch",
+        "source-missing",
+        "source-unavailable",
+        "target-branch-missing",
+    ])),
+    backing: z.enum(["present", "missing"]),
+    source: z.enum(["available", "missing", "unavailable"]),
+    gitRegistration: z.enum(["registered", "stale", "missing", "unavailable"]),
+    managedBranch: z.enum(["present", "missing", "unknown"]),
+    targetBranch: z.enum(["present", "missing", "unknown"]),
+    backingBranch: z.enum(["matching", "mismatched", "unavailable"]),
+});
 export const workspaceInventoryEntryOutputSchema = z.object({
     label: z.string(),
     workspaceId: z.string(),
@@ -109,6 +129,7 @@ export const workspaceInventoryEntryOutputSchema = z.object({
     lastUsedAt: z.string(),
     idleMs: z.number().nonnegative(),
     rootValid: z.boolean(),
+    recovery: managedWorktreeRecoveryOutputSchema.optional(),
     current: z.boolean(),
 });
 export const workspaceInventorySummaryOutputSchema = z.object({
@@ -167,6 +188,7 @@ export const workspaceInspectionOutputSchema = z.union([
         lastUsedAt: z.string(),
         idleMs: z.number().nonnegative(),
         rootValid: z.boolean(),
+        recovery: managedWorktreeRecoveryOutputSchema.optional(),
         taskSummary: workspaceTaskInspectionSummaryOutputSchema.optional(),
     }),
     z.object({
@@ -186,6 +208,7 @@ export const workspaceInspectionOutputSchema = z.union([
         lastUsedAt: z.string().optional(),
         idleMs: z.number().nonnegative().optional(),
         rootValid: z.boolean().optional(),
+        recovery: managedWorktreeRecoveryOutputSchema.optional(),
         taskSummary: workspaceTaskInspectionSummaryOutputSchema.optional(),
         relay: z.string(),
         executionLocation: z.string(),

package/dist/mcp/server/core/tool-support.js

@@ -64,15 +64,18 @@ export function textBlock(text) {
     return { type: "text", text };
 }
 export function attachWorkspaceTaskReminder(result, reminder) {
-    if (!reminder || toolResultIsError(result) || typeof result !== "object" || result === null)
+    return attachWorkspaceNotice(result, reminder);
+}
+export function attachWorkspaceContextUpdate(result, update) {
+    return attachWorkspaceNotice(result, update);
+}
+function attachWorkspaceNotice(result, notice) {
+    if (!notice || toolResultIsError(result) || typeof result !== "object" || result === null)
         return result;
     const content = result.content;
     if (!Array.isArray(content))
         return result;
-    return {
-        ...result,
-        content: [...content, textBlock(reminder)],
-    };
+    return { ...result, content: [...content, textBlock(notice)] };
 }
 export function textSummary(content) {
     const text = contentText(content);