@akira-tl/forgerelay 0.2.5 → 0.2.6

package/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.2.6] - 2026-08-10
+
+### Changed
+
+- Running shell commands now expose canonical `processId` handles; `write_stdin` accepts `processId`, while the former process `sessionId` remains a deprecated compatibility alias throughout 0.2.x.
+- ForgeRelay now names protocol-level MCP state as a transport session in internal/debug terminology. Workspace identity remains `workspaceId`, one-request tracing remains `requestId`, and third-party provider session identifiers are unchanged.
+- Process elapsed time now uses a monotonic clock, preventing negative `wallTimeMs` values when the operating-system wall clock is adjusted while a long-running command or release Hook is executing.
+
 ## [0.2.5] - 2026-08-10
 
 ### Changed

package/dist/artifact-tools.js

@@ -7,7 +7,7 @@ import * as z from "zod/v4";
 import { ArtifactError } from "./artifact-error.js";
 import { runToolWithHooks } from "./hooks.js";
 import { describeIncomingArtifactValue, IncomingArtifactAdapterRegistry, } from "./incoming-artifacts.js";
-import { logEvent, sessionIdPrefix, workspaceLogLabel } from "./logger.js";
+import { logEvent, workspaceLogLabel } from "./logger.js";
 const ARTIFACT_WRITE_ANNOTATIONS = {
     readOnlyHint: false,
     destructiveHint: false,
@@ -47,7 +47,7 @@ export function registerArtifactTools(server, { config, workspaces, hooks, incom
         },
         _meta: { "openai/fileParams": ["file"] },
         annotations: ARTIFACT_WRITE_ANNOTATIONS,
-    }, async (input, extra) => {
+    }, async (input) => {
         const workspace = workspaces.getWorkspace(input.workspaceId);
         return runToolWithHooks(hooks, {
             tool: "download_artifact",
@@ -61,7 +61,6 @@ export function registerArtifactTools(server, { config, workspaces, hooks, incom
             changedPaths: (result) => [result.structuredContent.path],
             operation: () => executeArtifactTool(config, input, {
                 workspace: workspaceLogLabel(workspace.root, workspace.id),
-                session: sessionIdPrefix(extra?.sessionId),
             }, async () => {
                 const downloaded = await downloadIncomingArtifact({
                     registry: incomingRegistry,

package/dist/logger.js

@@ -61,9 +61,11 @@ export function requestIp(req, trustProxy) {
 export function requestPath(req) {
     return req.path || req.url.split("?")[0] || req.url;
 }
-export function sessionIdPrefix(sessionId) {
-    return sessionId ? sessionId.slice(0, 8) : undefined;
+export function transportSessionIdPrefix(transportSessionId) {
+    return transportSessionId ? transportSessionId.slice(0, 8) : undefined;
 }
+/** @deprecated Use transportSessionIdPrefix. */
+export const sessionIdPrefix = transportSessionIdPrefix;
 export function workspaceLogLabel(root, workspaceId) {
     const shortWorkspaceId = workspaceId.startsWith("ws_")
         ? `ws_${workspaceId.slice(3, 11)}`
@@ -78,14 +80,16 @@ export function formatPrettyLogEntry(entry, options = {}) {
     const level = logLevel(entry.level);
     const time = formatTimestamp(entry.ts);
     const source = stringField(entry.workspace) ?? stringField(entry.workspaceId) ?? "forgerelay";
-    const session = level === "debug"
-        ? stringField(entry.session) ?? stringField(entry.sessionIdPrefix)
+    const transportSession = level === "debug"
+        ? stringField(entry.transportSessionIdPrefix)
+            ?? stringField(entry.session)
+            ?? stringField(entry.sessionIdPrefix)
         : undefined;
     const prefix = [
         style("gray", time, options),
         `[${style(LEVEL_STYLE[level], level.toUpperCase(), options)}]`,
         formatPrettySource(source, options),
-        session ? style("gray", `session:${session}`, options) : undefined,
+        transportSession ? style("gray", `transport:${transportSession}`, options) : undefined,
         style("gray", "|", options),
     ].filter((value) => Boolean(value)).join(" ");
     return `${prefix} ${formatPrettyMessage(entry, options)}`;
@@ -108,14 +112,18 @@ function formatPrettyMessage(entry, options) {
             return formatAppTemplateMessage(entry, options, false);
         case "mcp_app_template_read_failed":
             return formatAppTemplateMessage(entry, options, true);
+        case "mcp_transport_session_created":
         case "mcp_session_created":
-            return `session ${stringField(entry.sessionIdPrefix) ?? "unknown"} created`;
+            return `transport session ${transportSessionPrefix(entry) ?? "unknown"} created`;
+        case "mcp_transport_session_closed":
         case "mcp_session_closed":
-            return `session ${stringField(entry.sessionIdPrefix) ?? "unknown"} closed`;
+            return `transport session ${transportSessionPrefix(entry) ?? "unknown"} closed`;
+        case "mcp_transport_sessions_closed":
         case "mcp_sessions_closed":
-            return `${numberField(entry.count) ?? 0} sessions closed`;
+            return `${numberField(entry.count) ?? 0} transport sessions closed`;
+        case "mcp_transport_session_close_failed":
         case "mcp_session_close_failed":
-            return `session ${stringField(entry.sessionIdPrefix) ?? "unknown"} close -> ${style("red", "error", options)}`;
+            return `transport session ${transportSessionPrefix(entry) ?? "unknown"} close -> ${style("red", "error", options)}`;
         case "auth_denied":
             return `auth denied${entry.reason ? `: ${String(entry.reason)}` : ""}`;
         case "mcp_request_error":
@@ -139,8 +147,8 @@ function toolTarget(entry, tool) {
 }
 function toolResult(entry, tool, options) {
     if (entry.running === true) {
-        const processSessionId = entry.processSessionId;
-        return style("yellow", processSessionId === undefined ? "running" : `running process:${String(processSessionId)}`, options);
+        const processId = entry.processId ?? entry.processSessionId;
+        return style("yellow", processId === undefined ? "running" : `running process:${String(processId)}`, options);
     }
     const exitCode = numberField(entry.exitCode) ?? exitCodeFromError(entry.error);
     if (isShellTool(tool)) {
@@ -235,6 +243,11 @@ function logLevel(value) {
 function stringField(value) {
     return typeof value === "string" && value.length > 0 ? value : undefined;
 }
+function transportSessionPrefix(entry) {
+    return stringField(entry.transportSessionIdPrefix)
+        ?? stringField(entry.sessionIdPrefix)
+        ?? stringField(entry.session);
+}
 function numberField(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }

package/dist/mcp/server-instructions.js

@@ -34,7 +34,7 @@ export function buildToolDescriptions(config) {
         rename: `Rename or move one file or directory inside an open workspace or the OS temp directory without overwriting an existing destination. Source and destination must both remain inside the permitted file roots. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
         delete: `Delete one file or directory inside an open workspace or the OS temp directory. Non-empty directories require recursive=true. An allowed root itself cannot be deleted. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
         applyPatch: `Apply one Codex-style patch inside an open workspace or the OS temp directory. Supports adding, overwriting, updating, deleting, and moving files. Workspace paths must remain relative; absolute paths are accepted only inside the OS temp directory. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
-        shell: `Run a shell command inside an open workspace.${shellSurface} Commands execute with the local user's authority; workspace filesystem containment does not make shell execution a sandbox. ForgeRelay waits up to 300 seconds for bash, then returns a running process session without killing it; use ${toolNames.writeStdin} to poll, keep waiting, interact, or send Ctrl-C. Completed background commands are also reported with a later tool result for the same workspaceId. ${shellMutationPolicy} Call ${toolNames.openWorkspace} first and pass workspaceId. This capability should only be exposed behind strong authentication.`,
+        shell: `Run a shell command inside an open workspace.${shellSurface} Commands execute with the local user's authority; workspace filesystem containment does not make shell execution a sandbox. ForgeRelay waits up to 300 seconds for bash, then returns a running process with a processId without killing it; use ${toolNames.writeStdin} with that processId to poll, keep waiting, interact, or send Ctrl-C. Completed background commands are also reported with a later tool result for the same workspaceId. ${shellMutationPolicy} Call ${toolNames.openWorkspace} first and pass workspaceId. This capability should only be exposed behind strong authentication.`,
         shellCommand: "Shell command to run with the local user's authority.",
     };
 }
@@ -62,9 +62,9 @@ function toolSurfaceInstructions(config) {
         return `In codex tool mode, workspace file and command operations use ${toolNames.read}, ${toolNames.rename}, ${toolNames.delete}, apply_patch, exec_command, and ${toolNames.writeStdin}.`;
     }
     if (config.toolMode === "full") {
-        return `In full tool mode, dedicated ${toolNames.grep}, ${toolNames.glob}, and ${toolNames.ls} inspection tools are available alongside the core workspace tools. ${toolNames.writeStdin} is available for running bash sessions.`;
+        return `In full tool mode, dedicated ${toolNames.grep}, ${toolNames.glob}, and ${toolNames.ls} inspection tools are available alongside the core workspace tools. ${toolNames.writeStdin} is available for running bash processes.`;
     }
-    return `In minimal tool mode, dedicated ${toolNames.grep}, ${toolNames.glob}, and ${toolNames.ls} inspection tools are disabled; the core workspace tools remain available, including ${toolNames.writeStdin} for running bash sessions.`;
+    return `In minimal tool mode, dedicated ${toolNames.grep}, ${toolNames.glob}, and ${toolNames.ls} inspection tools are disabled; the core workspace tools remain available, including ${toolNames.writeStdin} for running bash processes.`;
 }
 function selectedWorkflowInstructions(config) {
     if (config.workflowInstructions === false)
@@ -80,7 +80,7 @@ function defaultWorkflowInstructions(config) {
     const inspection = config.toolMode === "full"
         ? `Prefer ${toolNames.read}, ${toolNames.grep}, ${toolNames.glob}, and ${toolNames.ls} for file inspection.`
         : `Use ${toolNames.shell} with command-line tools such as grep, rg, find, ls, and tree for search and directory inspection.`;
-    return joinInstructions(inspection, `Prefer ${toolNames.edit} for targeted content modifications, ${toolNames.write} only for new files or complete rewrites, ${toolNames.rename} for path moves, ${toolNames.delete} for removals, and ${toolNames.shell} for tests, builds, git inspection, package scripts, generators, formatters, and commands that are better executed by the shell. If ${toolNames.shell} returns a running session, use ${toolNames.writeStdin} only when you need to poll, wait, interact, or interrupt it; otherwise you may continue other work and consume its completion notice from a later tool result.`);
+    return joinInstructions(inspection, `Prefer ${toolNames.edit} for targeted content modifications, ${toolNames.write} only for new files or complete rewrites, ${toolNames.rename} for path moves, ${toolNames.delete} for removals, and ${toolNames.shell} for tests, builds, git inspection, package scripts, generators, formatters, and commands that are better executed by the shell. If ${toolNames.shell} returns a running process with a processId, use ${toolNames.writeStdin} only when you need to poll, wait, interact, or interrupt it; otherwise you may continue other work and consume its completion notice from a later tool result.`);
 }
 function joinInstructions(...parts) {
     return parts

package/dist/mcp-sessions.js

@@ -1,56 +1,58 @@
-export class McpSessionRegistry {
-    sessions = new Map();
+export class McpTransportRegistry {
+    transports = new Map();
     now;
     constructor(options = {}) {
         this.now = options.now ?? Date.now;
     }
     get size() {
-        return this.sessions.size;
+        return this.transports.size;
     }
-    register(sessionId, transport) {
-        this.sessions.set(sessionId, {
+    register(transportSessionId, transport) {
+        this.transports.set(transportSessionId, {
             transport,
             lastActivityAt: this.now(),
         });
     }
-    get(sessionId) {
-        const entry = this.sessions.get(sessionId);
+    get(transportSessionId) {
+        const entry = this.transports.get(transportSessionId);
         if (!entry)
             return undefined;
         entry.lastActivityAt = this.now();
         return entry.transport;
     }
-    remove(sessionId) {
-        return this.sessions.delete(sessionId);
+    remove(transportSessionId) {
+        return this.transports.delete(transportSessionId);
     }
     async closeIdle(idleTimeoutMs) {
         const cutoff = this.now() - idleTimeoutMs;
-        const idleSessions = [];
-        for (const [sessionId, entry] of this.sessions) {
+        const idleTransports = [];
+        for (const [transportSessionId, entry] of this.transports) {
             if (entry.lastActivityAt > cutoff)
                 continue;
-            this.sessions.delete(sessionId);
-            idleSessions.push({ sessionId, transport: entry.transport });
+            this.transports.delete(transportSessionId);
+            idleTransports.push({ transportSessionId, transport: entry.transport });
         }
-        return closeSessions(idleSessions);
+        return closeTransports(idleTransports);
     }
     async closeAll() {
-        const sessions = Array.from(this.sessions, ([sessionId, entry]) => ({
-            sessionId,
+        const transports = Array.from(this.transports, ([transportSessionId, entry]) => ({
+            transportSessionId,
             transport: entry.transport,
         }));
-        this.sessions.clear();
-        return closeSessions(sessions);
+        this.transports.clear();
+        return closeTransports(transports);
     }
 }
-async function closeSessions(sessions) {
-    return Promise.all(sessions.map(async ({ sessionId, transport }) => {
+async function closeTransports(transports) {
+    return Promise.all(transports.map(async ({ transportSessionId, transport }) => {
         try {
             await transport.close();
-            return { sessionId };
+            return { transportSessionId };
         }
         catch (error) {
-            return { sessionId, error };
+            return { transportSessionId, error };
         }
     }));
 }
+/** @deprecated Use McpTransportRegistry. */
+export { McpTransportRegistry as McpSessionRegistry };

package/dist/process-sessions.js

@@ -8,7 +8,7 @@ const MAX_COMMAND_YIELD_MS = 300_000;
 const MAX_POLL_YIELD_MS = 300_000;
 const DEFAULT_MAX_OUTPUT_TOKENS = 10_000;
 const DEFAULT_BUFFER_CHARACTERS = 1_000_000;
-const COMPLETED_SESSION_TTL_MS = 24 * 60 * 60 * 1_000;
+const COMPLETED_PROCESS_TTL_MS = 24 * 60 * 60 * 1_000;
 const DEFAULT_COLUMNS = 80;
 const DEFAULT_ROWS = 24;
 function boundedInteger(value, fallback, maximum) {
@@ -27,6 +27,19 @@ function terminalSize(value, fallback) {
     }
     return value;
 }
+export function resolveProcessId(processId, legacySessionId) {
+    if (processId !== undefined && legacySessionId !== undefined && processId !== legacySessionId) {
+        throw new Error("processId and deprecated sessionId must identify the same process when both are provided.");
+    }
+    const resolved = processId ?? legacySessionId;
+    if (resolved === undefined) {
+        throw new Error("A processId is required. Deprecated sessionId remains accepted for compatibility.");
+    }
+    if (!Number.isInteger(resolved) || resolved < 1) {
+        throw new Error("processId must be a positive integer.");
+    }
+    return resolved;
+}
 function processEnvironment(input) {
     return {
         ...Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] !== undefined && (input?.codexCi || entry[0] !== "CODEX_CI"))),
@@ -129,110 +142,120 @@ function truncateOutput(output, maxCharacters) {
         truncated: true,
     };
 }
-export class ProcessSessionManager {
-    sessions = new Map();
+export class ProcessManager {
+    processes = new Map();
     completedByWorkspace = new Map();
     maxBufferCharacters;
-    completedSessionTtlMs;
+    completedProcessTtlMs;
     maxStartYieldMs;
-    nextSessionId = 1;
+    monotonicNow;
+    nextProcessId = 1;
     constructor(options = {}) {
         this.maxBufferCharacters = options.maxBufferCharacters ?? DEFAULT_BUFFER_CHARACTERS;
-        this.completedSessionTtlMs = options.completedSessionTtlMs ?? COMPLETED_SESSION_TTL_MS;
+        this.completedProcessTtlMs = options.completedProcessTtlMs
+            ?? options.completedSessionTtlMs
+            ?? COMPLETED_PROCESS_TTL_MS;
         this.maxStartYieldMs = options.maxStartYieldMs ?? MAX_START_YIELD_MS;
+        this.monotonicNow = options.monotonicNow ?? (() => performance.now());
     }
     async start(input) {
-        const session = this.createSession(input);
-        this.sessions.set(session.id, session);
+        const processEntry = this.createProcess(input);
+        this.processes.set(processEntry.id, processEntry);
         try {
             if (input.tty && process.platform !== "win32")
-                await this.startPty(session, input);
+                await this.startPty(processEntry, input);
             else
-                this.startPipe(session, input);
+                this.startPipe(processEntry, input);
         }
         catch (error) {
-            this.sessions.delete(session.id);
+            this.processes.delete(processEntry.id);
             throw error;
         }
         const yieldTimeMs = boundedInteger(input.yieldTimeMs, DEFAULT_EXEC_YIELD_MS, this.maxStartYieldMs);
-        await this.waitForExit(session, yieldTimeMs);
-        if (session.running)
-            session.background = true;
-        const snapshot = this.consume(session, input.maxOutputTokens);
+        await this.waitForExit(processEntry, yieldTimeMs);
+        if (processEntry.running)
+            processEntry.background = true;
+        const snapshot = this.consume(processEntry, input.maxOutputTokens);
         if (!snapshot.running)
-            this.removeSession(session.id);
+            this.removeProcess(processEntry.id);
         return snapshot;
     }
     async write(input) {
-        const session = this.getOwnedSession(input.workspaceId, input.sessionId);
+        const processId = resolveProcessId(input.processId, input.sessionId);
+        const processEntry = this.getOwnedProcess(input.workspaceId, processId);
         const chars = input.chars ?? "";
         const interactionRequested = chars.length > 0 || input.columns !== undefined || input.rows !== undefined;
         if (input.columns !== undefined || input.rows !== undefined) {
-            session.columns = terminalSize(input.columns, session.columns);
-            session.rows = terminalSize(input.rows, session.rows);
-            if (!session.process?.resize) {
-                throw new Error(`Process session ${session.id} is not a PTY and cannot be resized.`);
+            processEntry.columns = terminalSize(input.columns, processEntry.columns);
+            processEntry.rows = terminalSize(input.rows, processEntry.rows);
+            if (!processEntry.process?.resize) {
+                throw new Error(`Process ${processEntry.id} is not a PTY and cannot be resized.`);
             }
-            session.process.resize(session.columns, session.rows);
+            processEntry.process.resize(processEntry.columns, processEntry.rows);
         }
-        const interruptRequested = chars.includes("\u0003") && session.running;
+        const interruptRequested = chars.includes("\u0003") && processEntry.running;
         if (interruptRequested) {
-            session.process?.kill("SIGINT");
+            processEntry.process?.kill("SIGINT");
         }
         const writableChars = chars.replaceAll("\u0003", "");
-        if (writableChars && session.running)
-            session.process?.write(writableChars);
-        if ((interactionRequested || !session.buffer.hasOutput()) && session.running) {
+        if (writableChars && processEntry.running)
+            processEntry.process?.write(writableChars);
+        if ((interactionRequested || !processEntry.buffer.hasOutput()) && processEntry.running) {
             const fallback = interactionRequested ? DEFAULT_INTERACTIVE_YIELD_MS : DEFAULT_POLL_YIELD_MS;
             const maximum = interactionRequested ? MAX_COMMAND_YIELD_MS : MAX_POLL_YIELD_MS;
             const yieldTimeMs = boundedInteger(input.yieldTimeMs, fallback, maximum);
-            await this.waitForExit(session, yieldTimeMs);
+            await this.waitForExit(processEntry, yieldTimeMs);
         }
-        const snapshot = this.consume(session, input.maxOutputTokens);
-        if (!session.running)
-            this.removeSession(session.id);
+        const snapshot = this.consume(processEntry, input.maxOutputTokens);
+        if (!processEntry.running)
+            this.removeProcess(processEntry.id);
         return snapshot;
     }
     activeWorkspaceIds() {
-        return new Set([...this.sessions.values()].map((session) => session.workspaceId));
+        return new Set([...this.processes.values()].map((processEntry) => processEntry.workspaceId));
     }
-    takeCompleted(workspaceId, maxOutputTokens, excludeSessionId) {
-        const sessionIds = this.completedByWorkspace.get(workspaceId) ?? [];
-        if (sessionIds.length === 0)
+    takeCompleted(workspaceId, maxOutputTokens, excludeProcessId) {
+        const processIds = this.completedByWorkspace.get(workspaceId) ?? [];
+        if (processIds.length === 0)
             return [];
         const completed = [];
-        for (const sessionId of sessionIds) {
-            if (sessionId === excludeSessionId)
+        for (const processId of processIds) {
+            if (processId === excludeProcessId)
                 continue;
-            const session = this.sessions.get(sessionId);
-            if (!session || session.running)
+            const processEntry = this.processes.get(processId);
+            if (!processEntry || processEntry.running)
                 continue;
-            const snapshot = this.consume(session, maxOutputTokens);
-            completed.push({ ...snapshot, sessionId: session.id, command: session.command });
-            this.removeSession(session.id);
+            const snapshot = this.consume(processEntry, maxOutputTokens);
+            completed.push({
+                ...snapshot,
+                processId: processEntry.id,
+                sessionId: processEntry.id,
+                command: processEntry.command,
+            });
+            this.removeProcess(processEntry.id);
         }
         return completed;
     }
-    terminate(workspaceId, sessionId) {
-        const session = this.getOwnedSession(workspaceId, sessionId);
-        if (session.running)
-            session.process?.kill("SIGTERM");
+    terminate(workspaceId, processId) {
+        const processEntry = this.getOwnedProcess(workspaceId, processId);
+        if (processEntry.running)
+            processEntry.process?.kill("SIGTERM");
     }
     shutdown() {
-        for (const session of this.sessions.values()) {
-            if (session.cleanupTimer)
-                clearTimeout(session.cleanupTimer);
-            if (session.running)
-                session.process?.kill("SIGTERM");
+        for (const processEntry of this.processes.values()) {
+            if (processEntry.cleanupTimer)
+                clearTimeout(processEntry.cleanupTimer);
+            if (processEntry.running)
+                processEntry.process?.kill("SIGTERM");
         }
-        this.sessions.clear();
+        this.processes.clear();
         this.completedByWorkspace.clear();
     }
-    async waitForExit(session, yieldTimeMs) {
+    async waitForExit(processEntry, yieldTimeMs) {
         let timer;
         try {
             await Promise.race([
-                session.exitPromise,
+                processEntry.exitPromise,
                 new Promise((resolve) => {
                     timer = setTimeout(resolve, yieldTimeMs);
                 }),
@@ -243,16 +266,16 @@ export class ProcessSessionManager {
                 clearTimeout(timer);
         }
     }
-    createSession(input) {
+    createProcess(input) {
         let resolveExit = () => undefined;
         const exitPromise = new Promise((resolve) => {
             resolveExit = resolve;
         });
         return {
-            id: this.nextSessionId++,
+            id: this.nextProcessId++,
             workspaceId: input.workspaceId,
             command: input.command,
-            startedAt: Date.now(),
+            startedAtMonotonic: this.monotonicNow(),
             columns: terminalSize(input.columns, DEFAULT_COLUMNS),
             rows: terminalSize(input.rows, DEFAULT_ROWS),
             buffer: new HeadTailBuffer(this.maxBufferCharacters),
@@ -262,7 +285,7 @@ export class ProcessSessionManager {
             resolveExit,
         };
     }
-    startPipe(session, input) {
+    startPipe(processEntry, input) {
         const shell = resolveShellCommand(input.command);
         const detached = process.platform !== "win32";
         const child = spawn(input.command, {
@@ -277,17 +300,17 @@ export class ProcessSessionManager {
             detached,
             shell: shell.executable,
         });
-        session.process = {
+        processEntry.process = {
             write: (data) => child.stdin.write(data),
             kill: (signal = "SIGTERM") => terminateProcessTree(child, signal, detached),
             resize: input.tty ? () => undefined : undefined,
         };
-        child.stdout.on("data", (data) => this.append(session, data.toString("utf8")));
-        child.stderr.on("data", (data) => this.append(session, data.toString("utf8")));
-        child.on("error", (error) => this.append(session, `${error.message}\n`));
-        child.on("close", (code, signal) => this.finish(session, code ?? undefined, signal ?? undefined));
+        child.stdout.on("data", (data) => this.append(processEntry, data.toString("utf8")));
+        child.stderr.on("data", (data) => this.append(processEntry, data.toString("utf8")));
+        child.on("error", (error) => this.append(processEntry, `${error.message}\n`));
+        child.on("close", (code, signal) => this.finish(processEntry, code ?? undefined, signal ?? undefined));
     }
-    async startPty(session, input) {
+    async startPty(processEntry, input) {
         let nodePty;
         try {
             nodePty = await import("node-pty");
@@ -306,80 +329,84 @@ export class ProcessSessionManager {
                     codexCi: input.codexCi,
                 }),
                 name: "xterm-256color",
-                cols: session.columns,
-                rows: session.rows,
+                cols: processEntry.columns,
+                rows: processEntry.rows,
             });
         }
         catch (error) {
             throw error;
         }
-        session.process = {
+        processEntry.process = {
             write: (data) => pty.write(data),
             kill: (signal) => pty.kill(signal),
             resize: (columns, rows) => pty.resize(columns, rows),
         };
-        pty.onData((data) => this.append(session, data));
+        pty.onData((data) => this.append(processEntry, data));
         pty.onExit(({ exitCode, signal }) => {
-            this.finish(session, exitCode, signal === 0 ? undefined : String(signal));
+            this.finish(processEntry, exitCode, signal === 0 ? undefined : String(signal));
         });
     }
-    finish(session, exitCode, signal) {
-        if (!session.running)
+    finish(processEntry, exitCode, signal) {
+        if (!processEntry.running)
             return;
-        session.running = false;
-        session.exitCode = exitCode;
-        session.signal = signal;
-        session.resolveExit();
-        if (session.background) {
-            const completed = this.completedByWorkspace.get(session.workspaceId) ?? [];
-            if (!completed.includes(session.id)) {
-                completed.push(session.id);
-                this.completedByWorkspace.set(session.workspaceId, completed);
+        processEntry.running = false;
+        processEntry.exitCode = exitCode;
+        processEntry.signal = signal;
+        processEntry.resolveExit();
+        if (processEntry.background) {
+            const completed = this.completedByWorkspace.get(processEntry.workspaceId) ?? [];
+            if (!completed.includes(processEntry.id)) {
+                completed.push(processEntry.id);
+                this.completedByWorkspace.set(processEntry.workspaceId, completed);
             }
         }
-        session.cleanupTimer = setTimeout(() => this.removeSession(session.id), this.completedSessionTtlMs);
-        session.cleanupTimer.unref();
+        processEntry.cleanupTimer = setTimeout(() => this.removeProcess(processEntry.id), this.completedProcessTtlMs);
+        processEntry.cleanupTimer.unref();
     }
-    append(session, output) {
-        session.buffer.append(output);
+    append(processEntry, output) {
+        processEntry.buffer.append(output);
     }
-    consume(session, maxOutputTokens) {
+    consume(processEntry, maxOutputTokens) {
         const limit = boundedInteger(maxOutputTokens, DEFAULT_MAX_OUTPUT_TOKENS, 100_000);
         const maxCharacters = Math.max(256, limit * 4);
-        const buffered = session.buffer.drain(maxCharacters);
+        const buffered = processEntry.buffer.drain(maxCharacters);
+        const processId = processEntry.running ? processEntry.id : undefined;
         return {
-            sessionId: session.running ? session.id : undefined,
+            processId,
+            sessionId: processId,
             output: buffered.output,
             outputTruncated: buffered.truncated,
-            running: session.running,
-            exitCode: session.exitCode,
-            signal: session.signal,
-            wallTimeMs: Date.now() - session.startedAt,
+            running: processEntry.running,
+            exitCode: processEntry.exitCode,
+            signal: processEntry.signal,
+            wallTimeMs: Math.max(0, Math.round(this.monotonicNow() - processEntry.startedAtMonotonic)),
         };
     }
-    getOwnedSession(workspaceId, sessionId) {
-        const session = this.sessions.get(sessionId);
-        if (!session)
-            throw new Error(`Unknown process session: ${sessionId}`);
-        if (session.workspaceId !== workspaceId) {
-            throw new Error(`Process session ${sessionId} does not belong to workspace ${workspaceId}.`);
+    getOwnedProcess(workspaceId, processId) {
+        const processEntry = this.processes.get(processId);
+        if (!processEntry)
+            throw new Error(`Unknown process: ${processId}`);
+        if (processEntry.workspaceId !== workspaceId) {
+            throw new Error(`Process ${processId} does not belong to workspace ${workspaceId}.`);
         }
-        return session;
+        return processEntry;
     }
-    removeSession(sessionId) {
-        const session = this.sessions.get(sessionId);
-        if (session?.cleanupTimer)
-            clearTimeout(session.cleanupTimer);
-        this.sessions.delete(sessionId);
-        if (!session)
+    removeProcess(processId) {
+        const processEntry = this.processes.get(processId);
+        if (processEntry?.cleanupTimer)
+            clearTimeout(processEntry.cleanupTimer);
+        this.processes.delete(processId);
+        if (!processEntry)
             return;
-        const completed = this.completedByWorkspace.get(session.workspaceId);
+        const completed = this.completedByWorkspace.get(processEntry.workspaceId);
         if (!completed)
             return;
-        const remaining = completed.filter((id) => id !== sessionId);
+        const remaining = completed.filter((id) => id !== processId);
         if (remaining.length > 0)
-            this.completedByWorkspace.set(session.workspaceId, remaining);
+            this.completedByWorkspace.set(processEntry.workspaceId, remaining);
         else
-            this.completedByWorkspace.delete(session.workspaceId);
+            this.completedByWorkspace.delete(processEntry.workspaceId);
     }
 }
+/** @deprecated Use ProcessManager. */
+export { ProcessManager as ProcessSessionManager };

package/dist/server.js

@@ -20,11 +20,11 @@ import { loadConfig } from "./config.js";
 import { attachHookReports, HookRunner, runToolWithHooks } from "./hooks.js";
 import { buildServerInstructions, buildShellMutationPolicy, buildToolDescriptions, toolNames, } from "./mcp/server-instructions.js";
 import { createOpenAIIncomingArtifactAdapter, } from "./incoming-artifacts.js";
-import { logEvent, requestIp, requestPath, commandPreview, sessionIdPrefix, workspaceLogLabel, } from "./logger.js";
+import { logEvent, requestIp, requestPath, commandPreview, transportSessionIdPrefix, workspaceLogLabel, } from "./logger.js";
 import { editFileTool, findFilesTool, grepFilesTool, listDirectoryTool, readFileTool, writeFileTool, } from "./pi-tools.js";
 import { SingleUserOAuthProvider } from "./oauth-provider.js";
-import { McpSessionRegistry, } from "./mcp-sessions.js";
-import { ProcessSessionManager, } from "./process-sessions.js";
+import { McpTransportRegistry, } from "./mcp-sessions.js";
+import { ProcessManager, resolveProcessId, } from "./process-sessions.js";
 import { createReviewCheckpointManager } from "./review-checkpoints.js";
 import { openAiConversationScopeId } from "./request-meta.js";
 import { readWorkspaceAppManifestEntry, resolveWorkspaceAppIdentity, WORKSPACE_APP_LEGACY_URI, WORKSPACE_APP_URI_TEMPLATE, } from "./mcp-app-template.js";
@@ -34,11 +34,12 @@ import { createWorkspaceStore } from "./workspace-store.js";
 import { formatAgentsPath, WorkspaceRegistry } from "./workspaces.js";
 import { summarizeLocalAgentProfile } from "./local-agent-profiles.js";
 import { formatLocalAgentProviderAvailabilitySummary, getLocalAgentProviderAvailabilitySnapshot, } from "./local-agent-availability.js";
-// MCP clients can reconnect without closing the previous transport. Bound stale
-// session retention so abandoned MCP servers do not accumulate for the life of the process.
-const MCP_SESSION_IDLE_TIMEOUT_MS = 24 * 60 * 60 * 1_000;
+// Legacy MCP Streamable HTTP clients can reconnect without closing the previous
+// transport. Bound stale transport-session retention so abandoned transports do
+// not accumulate for the life of the process.
+const MCP_TRANSPORT_IDLE_TIMEOUT_MS = 24 * 60 * 60 * 1_000;
 const FORGERELAY_VERSION = readForgeRelayVersion();
-const MCP_SESSION_CLEANUP_INTERVAL_MS = 5 * 60 * 1_000;
+const MCP_TRANSPORT_CLEANUP_INTERVAL_MS = 5 * 60 * 1_000;
 const WRITE_TOOL_ANNOTATIONS = {
     readOnlyHint: false,
     destructiveHint: true,
@@ -81,7 +82,7 @@ function toolWidgetDescriptorMeta(config, kind) {
         },
     };
 }
-function workspaceLogContext(workspace, _sessionId) {
+function workspaceLogContext(workspace, _transportSessionId) {
     return {
         workspaceId: workspace.id,
         workspace: workspaceLogLabel(workspace.root, workspace.id),
@@ -357,7 +358,7 @@ async function readWorkspaceAppResource(config, requestedUri, transportSessionId
             requestedUri,
             currentUri,
             compatibility,
-            sessionIdPrefix: sessionIdPrefix(transportSessionId),
+            transportSessionIdPrefix: transportSessionIdPrefix(transportSessionId),
         });
         return result;
     }
@@ -367,14 +368,14 @@ async function readWorkspaceAppResource(config, requestedUri, transportSessionId
             currentUri,
             compatibility,
             error: error instanceof Error ? error.message : String(error),
-            sessionIdPrefix: sessionIdPrefix(transportSessionId),
+            transportSessionIdPrefix: transportSessionIdPrefix(transportSessionId),
         });
         throw error;
     }
 }
 function processResult(snapshot) {
     const status = snapshot.running
-        ? `Process running with session ID ${snapshot.sessionId}.`
+        ? `Process running with process ID ${snapshot.processId}.`
         : snapshot.signal
             ? `Process exited after signal ${snapshot.signal}.`
             : `Process exited with code ${snapshot.exitCode ?? "unknown"}.`;
@@ -382,8 +383,8 @@ function processResult(snapshot) {
 }
 function completedProcessResult(snapshot) {
     const status = snapshot.signal
-        ? `Background process ${snapshot.sessionId} exited after signal ${snapshot.signal}.`
-        : `Background process ${snapshot.sessionId} exited with code ${snapshot.exitCode ?? "unknown"}.`;
+        ? `Background process ${snapshot.processId} exited after signal ${snapshot.signal}.`
+        : `Background process ${snapshot.processId} exited with code ${snapshot.exitCode ?? "unknown"}.`;
     const command = `Command: ${snapshot.command}`;
     const output = snapshot.output ? `\n${snapshot.output.replace(/\n$/, "")}` : "";
     return `${status}\n${command}${output}`;
@@ -405,10 +406,14 @@ function attachCompletedProcessNotices(processSessions, workspaceId, result) {
     if (!Array.isArray(content))
         return result;
     const structured = result.structuredContent;
-    const currentSessionId = structured?.running === true && typeof structured.sessionId === "number"
-        ? structured.sessionId
+    const currentProcessId = structured?.running === true
+        ? typeof structured.processId === "number"
+            ? structured.processId
+            : typeof structured.sessionId === "number"
+                ? structured.sessionId
+                : undefined
         : undefined;
-    const completed = processSessions.takeCompleted(workspaceId, undefined, currentSessionId);
+    const completed = processSessions.takeCompleted(workspaceId, undefined, currentProcessId);
     if (completed.length === 0)
         return result;
     return {
@@ -421,7 +426,8 @@ function attachCompletedProcessNotices(processSessions, workspaceId, result) {
 }
 function processOutputSchema() {
     return resultOutputSchema({
-        sessionId: z.number().optional(),
+        processId: z.number().int().positive().optional().describe("Canonical process handle for write_stdin."),
+        sessionId: z.number().int().positive().optional().describe("Deprecated alias of processId for compatibility."),
         running: z.boolean(),
         exitCode: z.number().int().optional(),
         signal: z.string().optional(),
@@ -452,6 +458,7 @@ function processToolResponse(tool, workspaceId, snapshot, summary) {
         },
         structuredContent: {
             result,
+            processId: snapshot.processId,
             sessionId: snapshot.sessionId,
             running: snapshot.running,
             exitCode: snapshot.exitCode,
@@ -476,7 +483,7 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
     if (config.toolMode === "codex") {
         registerAppTool(server, "exec_command", {
             title: "Execute command",
-            description: `Run a command inside an open workspace. Returns its result when it exits during the yield window, otherwise returns a sessionId for write_stdin. Use this for file inspection, tests, builds, package scripts, generators, formatters, and long-running processes. ${buildShellMutationPolicy()} Call open_workspace first and pass workspaceId.`,
+            description: `Run a command inside an open workspace. Returns its result when it exits during the yield window, otherwise returns a processId for write_stdin. Use this for file inspection, tests, builds, package scripts, generators, formatters, and long-running processes. ${buildShellMutationPolicy()} Call open_workspace first and pass workspaceId.`,
             inputSchema: {
                 workspaceId: z.string().describe("Workspace identifier returned by open_workspace."),
                 cmd: z.string().min(1).describe("Shell command to execute."),
@@ -496,7 +503,7 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
                     .min(0)
                     .max(30_000)
                     .optional()
-                    .describe("Milliseconds to wait before returning a running session. Defaults to 10000."),
+                    .describe("Milliseconds to wait before returning a running process. Defaults to 10000."),
                 maxOutputTokens: z
                     .number()
                     .int()
@@ -537,7 +544,7 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
                         commandLength: cmd.length,
                         exitCode: snapshot.exitCode,
                         running: snapshot.running,
-                        processSessionId: snapshot.sessionId,
+                        processId: snapshot.processId,
                         success: snapshot.running || snapshot.exitCode === 0,
                         durationMs: Math.round(performance.now() - startedAt),
                     });
@@ -557,7 +564,8 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
         description: "Poll or write characters to a running process returned by bash or exec_command. Omit chars or pass an empty string to poll. Waiting never kills the process; pass \\u0003 to explicitly send Ctrl-C.",
         inputSchema: {
             workspaceId: z.string().describe("Workspace identifier used to start the process."),
-            sessionId: z.number().describe("Process session identifier returned by exec_command."),
+            processId: z.number().int().positive().optional().describe("Canonical process identifier returned by bash or exec_command."),
+            sessionId: z.number().int().positive().optional().describe("Deprecated alias for processId. Retained for compatibility."),
             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."),
@@ -579,13 +587,14 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
         outputSchema: processOutputSchema(),
         ...toolWidgetDescriptorMeta(config, "shell"),
         annotations: SHELL_TOOL_ANNOTATIONS,
-    }, async ({ workspaceId, sessionId, chars, columns, rows, yieldTimeMs, maxOutputTokens }, extra) => {
+    }, async ({ workspaceId, processId, sessionId, chars, columns, rows, yieldTimeMs, maxOutputTokens }, extra) => {
         const workspace = workspaces.getWorkspace(workspaceId);
+        const resolvedProcessId = resolveProcessId(processId, sessionId);
         return runToolWithHooks(hooks, {
             tool: "write_stdin",
             invocation: workspaceHookInvocation(workspace),
             payload: {
-                sessionId,
+                processId: resolvedProcessId,
                 charactersWritten: chars?.length ?? 0,
                 columns,
                 rows,
@@ -594,7 +603,7 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
                 const startedAt = performance.now();
                 const snapshot = await processSessions.write({
                     workspaceId,
-                    sessionId,
+                    processId: resolvedProcessId,
                     chars,
                     columns,
                     rows,
@@ -606,12 +615,12 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
                     ...workspaceLogContext(workspace, extra.sessionId),
                     exitCode: snapshot.exitCode,
                     running: snapshot.running,
-                    processSessionId: snapshot.sessionId,
+                    processId: snapshot.processId,
                     success: snapshot.running || snapshot.exitCode === 0,
                     durationMs: Math.round(performance.now() - startedAt),
                 });
                 return processToolResponse("write_stdin", workspaceId, snapshot, {
-                    sessionId,
+                    processId: resolvedProcessId,
                     charactersWritten: chars?.length ?? 0,
                     running: snapshot.running,
                     exitCode: snapshot.exitCode,
@@ -1747,7 +1756,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                         commandLength: command.length,
                         exitCode: snapshot.exitCode,
                         running: snapshot.running,
-                        processSessionId: snapshot.sessionId,
+                        processId: snapshot.processId,
                         success: snapshot.running || (snapshot.exitCode === 0 && !snapshot.signal),
                         durationMs: Math.round(performance.now() - startedAt),
                     });
@@ -1786,7 +1795,7 @@ export function createServer(config = loadConfig(), options = {}) {
         host: config.host,
         ...(allowedHosts ? { allowedHosts } : {}),
     });
-    const transports = new McpSessionRegistry();
+    const transports = new McpTransportRegistry();
     const mcpUrl = new URL("/mcp", config.publicBaseUrl);
     const resourceServerUrl = resourceUrlFromServerUrl(mcpUrl);
     const oauthProvider = new SingleUserOAuthProvider(config.oauth, mcpUrl, config.stateDir);
@@ -1798,17 +1807,17 @@ export function createServer(config = loadConfig(), options = {}) {
     const workspaceStore = createWorkspaceStore(config.stateDir);
     const workspaces = new WorkspaceRegistry(config, workspaceStore);
     const reviewCheckpoints = createReviewCheckpointManager();
-    const processSessions = new ProcessSessionManager();
+    const processSessions = new ProcessManager();
     const localAgentProviders = config.subagents
         ? getLocalAgentProviderAvailabilitySnapshot()
         : [];
-    const logSessionCloseResults = (reason, results) => {
+    const logTransportCloseResults = (reason, results) => {
         let closedCount = 0;
         for (const result of results) {
             if (result.error) {
-                logEvent(config.logging, "warn", "mcp_session_close_failed", {
+                logEvent(config.logging, "warn", "mcp_transport_session_close_failed", {
                     reason,
-                    sessionIdPrefix: sessionIdPrefix(result.sessionId),
+                    transportSessionIdPrefix: transportSessionIdPrefix(result.transportSessionId),
                     error: result.error instanceof Error
                         ? result.error.message
                         : String(result.error),
@@ -1817,25 +1826,25 @@ export function createServer(config = loadConfig(), options = {}) {
             }
             closedCount += 1;
             if (reason === "idle_timeout") {
-                logEvent(config.logging, "debug", "mcp_session_closed", {
+                logEvent(config.logging, "debug", "mcp_transport_session_closed", {
                     reason,
-                    sessionIdPrefix: sessionIdPrefix(result.sessionId),
+                    transportSessionIdPrefix: transportSessionIdPrefix(result.transportSessionId),
                 });
             }
         }
         if (reason === "server_shutdown" && closedCount > 0) {
-            logEvent(config.logging, "debug", "mcp_sessions_closed", {
+            logEvent(config.logging, "debug", "mcp_transport_sessions_closed", {
                 reason,
                 count: closedCount,
             });
         }
     };
-    const sessionCleanupTimer = setInterval(() => {
+    const transportCleanupTimer = setInterval(() => {
         void transports
-            .closeIdle(MCP_SESSION_IDLE_TIMEOUT_MS)
-            .then((results) => logSessionCloseResults("idle_timeout", results));
-    }, MCP_SESSION_CLEANUP_INTERVAL_MS);
-    sessionCleanupTimer.unref();
+            .closeIdle(MCP_TRANSPORT_IDLE_TIMEOUT_MS)
+            .then((results) => logTransportCloseResults("idle_timeout", results));
+    }, MCP_TRANSPORT_CLEANUP_INTERVAL_MS);
+    transportCleanupTimer.unref();
     if (config.logging.trustProxy) {
         app.set("trust proxy", true);
     }
@@ -1883,7 +1892,7 @@ export function createServer(config = loadConfig(), options = {}) {
     });
     app.all("/mcp", async (req, res) => {
         const requestId = res.locals.requestId;
-        const sessionId = req.header("mcp-session-id");
+        const transportSessionId = req.header("mcp-session-id");
         const initializeRequest = req.method === "POST" && isInitializeRequest(req.body);
         await new Promise((resolve, reject) => {
             bearerAuth(req, res, (error) => {
@@ -1909,39 +1918,39 @@ export function createServer(config = loadConfig(), options = {}) {
         logEvent(config.logging, "debug", "mcp_request", {
             requestId,
             httpMethod: req.method,
-            sessionIdPresent: Boolean(sessionId),
-            sessionIdPrefix: sessionIdPrefix(sessionId),
+            transportSessionIdPresent: Boolean(transportSessionId),
+            transportSessionIdPrefix: transportSessionIdPrefix(transportSessionId),
             isInitialize: initializeRequest,
             ...mcpRequestDebugFields(req.body),
         });
         try {
             let transport;
-            if (sessionId) {
-                transport = transports.get(sessionId);
+            if (transportSessionId) {
+                transport = transports.get(transportSessionId);
                 if (!transport) {
-                    sendJsonRpcError(res, 404, -32000, "Unknown MCP session");
+                    sendJsonRpcError(res, 404, -32000, "Unknown MCP transport session");
                     return;
                 }
             }
             else if (initializeRequest) {
                 transport = new StreamableHTTPServerTransport({
                     sessionIdGenerator: () => randomUUID(),
-                    onsessioninitialized: (newSessionId) => {
+                    onsessioninitialized: (newTransportSessionId) => {
                         if (transport)
-                            transports.register(newSessionId, transport);
-                        logEvent(config.logging, "debug", "mcp_session_created", {
+                            transports.register(newTransportSessionId, transport);
+                        logEvent(config.logging, "debug", "mcp_transport_session_created", {
                             requestId,
-                            sessionIdPrefix: sessionIdPrefix(newSessionId),
+                            transportSessionIdPrefix: transportSessionIdPrefix(newTransportSessionId),
                             ...requestLogFields(req, config),
                         });
                     },
                 });
                 transport.onclose = () => {
-                    const closedSessionId = transport?.sessionId;
-                    if (closedSessionId && transports.remove(closedSessionId)) {
-                        logEvent(config.logging, "debug", "mcp_session_closed", {
+                    const closedTransportSessionId = transport?.sessionId;
+                    if (closedTransportSessionId && transports.remove(closedTransportSessionId)) {
+                        logEvent(config.logging, "debug", "mcp_transport_session_closed", {
                             reason: "transport_close",
-                            sessionIdPrefix: sessionIdPrefix(closedSessionId),
+                            transportSessionIdPrefix: transportSessionIdPrefix(closedTransportSessionId),
                         });
                     }
                 };
@@ -1949,7 +1958,7 @@ export function createServer(config = loadConfig(), options = {}) {
                 await server.connect(transport);
             }
             else {
-                sendJsonRpcError(res, 400, -32000, "No valid MCP session");
+                sendJsonRpcError(res, 400, -32000, "No valid MCP transport session");
                 return;
             }
             await transport.handleRequest(req, res, req.body);
@@ -1971,9 +1980,9 @@ export function createServer(config = loadConfig(), options = {}) {
         localAgentProviders,
         close: () => {
             closePromise ??= (async () => {
-                clearInterval(sessionCleanupTimer);
+                clearInterval(transportCleanupTimer);
                 const results = await transports.closeAll();
-                logSessionCloseResults("server_shutdown", results);
+                logTransportCloseResults("server_shutdown", results);
                 processSessions.shutdown();
                 oauthProvider.close();
                 workspaceStore.close?.();

package/docs/chatgpt-coding-workflow.md

@@ -168,10 +168,11 @@ The exact lifecycle tools available depend on the active server configuration.
 In minimal mode, normal shell inspection commands such as `rg`, `find`, and `ls`
 can be used rather than dedicated MCP search tools. `bash` waits in the foreground
 for at most 300 seconds. If the command is still running, ForgeRelay returns a
-process `sessionId` without killing it. The Agent can use `write_stdin` to poll,
+canonical `processId` without killing it. The Agent can use `write_stdin` to poll,
 wait again, interact, or explicitly send Ctrl-C, or continue other work; once the
 command finishes, its completion is attached to a later tool result using the
-same workspace ID.
+same workspace ID. The former process `sessionId` remains a deprecated alias in
+0.2.x for compatibility with existing clients.
 
 `FORGERELAY_TOOL_MODE=full` adds dedicated search/directory tools.
 

package/docs/configuration.md

@@ -132,16 +132,17 @@ receives a different ID for the same physical checkout/worktree. Pass
 `workspaceId` to `open_workspace` to explicitly resume an existing handle in the
 current conversation. `newWorkspace: true` allocates a new logical handle without
 creating another checkout or Git worktree and should be used only on explicit user
-request. Sessions idle for more than two days are returned in `staleWorkspaces` so
+request. Logical workspaces idle for more than two days are returned in `staleWorkspaces` so
 the user can choose whether to resume or release them. `close_workspace` removes a
 logical handle without deleting checkout files; it refuses to remove the last
 handle anchoring a physical worktree.
 
 `bash` has no execution-timeout input. It waits in the foreground for at most 300
 seconds; if the process is still alive, the result contains `running: true` and a
-`sessionId`. `write_stdin` can poll or interact with that session for up to another
-300 seconds per call. ForgeRelay does not kill a process merely because a wait
-window expires. Completed background processes are delivered once with a later
+canonical `processId`. `write_stdin` can poll or interact with that process for up
+to another 300 seconds per call. The former `sessionId` field remains a deprecated
+alias during the 0.2.x compatibility window. ForgeRelay does not kill a process
+merely because a wait window expires. Completed background processes are delivered once with a later
 tool result for the same logical workspace ID.
 
 ## Widgets
@@ -339,8 +340,9 @@ forgerelay agents show <id>
 short timestamps, workspace-first context, and compact operation results while
 keeping HTTP request records off by default. Project names receive stable
 per-project colors and logical `ws_...` identifiers remain visible; transient MCP
-transport session IDs and normal session lifecycle events are shown only at
-`debug` level. Shell command previews are enabled
+transport session IDs and normal transport lifecycle events are shown only at
+`debug` level, where they are labeled as `transport` rather than workspace/process
+identity. Shell command previews are enabled
 in this mode and truncated to 120 characters; set
 `FORGERELAY_LOG_SHELL_COMMANDS=0` when command arguments may contain secrets.
 

package/docs/debugging.md

@@ -59,10 +59,10 @@ The acceptance checks:
 3. unauthenticated `/mcp` rejection;
 4. dynamic OAuth client registration, PKCE Owner-password approval, and access-token exchange;
 5. MCP `initialize`, including package/server version consistency and the shell mutation safety contract;
-6. `tools/list` for the full debug tool surface, including `close_workspace`, `write_stdin`, the non-blanket `bash` mutation policy, no kill-timeout input, the 300-second foreground-wait contract, workspace resume/stale-session schema, and MCP App tool metadata;
+6. `tools/list` for the full debug tool surface, including `close_workspace`, `write_stdin`, canonical `processId` plus the deprecated `sessionId` compatibility alias, the non-blanket `bash` mutation policy, no kill-timeout input, the 300-second foreground-wait contract, workspace resume/stale-workspace schema, and MCP App tool metadata;
 7. the full MCP App template chain: `resources/list`, `resources/templates/list`, current content-hashed `resources/read`, legacy/historical template compatibility reads, `text/html;profile=mcp-app`, CSP resource domains, and an HTTP fetch of the JavaScript asset referenced by the template;
-8. a real checkout workspace with `write`, `read`, `rename`, `delete`, foreground `bash` through `ProcessSessionManager`, and a deliberate failed `edit`;
-9. OS temp-directory `write` → `read` → `edit` → `rename` → `delete` over the same real MCP session, plus rejection of an arbitrary path outside the workspace/temp roots;
+8. a real checkout workspace with `write`, `read`, `rename`, `delete`, foreground `bash` through `ProcessManager`, and a deliberate failed `edit`;
+9. OS temp-directory `write` → `read` → `edit` → `rename` → `delete` over the same real MCP transport session, plus rejection of an arbitrary path outside the workspace/temp roots;
 10. a temporary Git repository with managed worktree creation, file modification, and `close_worktree`;
 11. 本地 bare remote 上的 release-tag-push Hook：成功 Hook 必须先运行再允许 `v0.2.0` push，失败 Hook 必须在 remote mutation 前阻断 `v0.2.1`；
 12. deterministic local subagent error path，不联系任何模型 provider；

package/docs/roadmap.md

@@ -99,7 +99,7 @@ Hooks v1 的目标是给用户和 Agent 一个很小、自动、可组合的生
 - `workspaceId` 是唯一持久的逻辑工作身份，跨请求和 transport 重连保持连续；
 - `requestId` 只追踪单次 HTTP/JSON-RPC 请求，不持久化；
 - MCP 协议层 session 在内部和 debug 输出中明确称为 `transportSessionId`，业务状态不得依赖它；
-- 后台命令句柄逐步迁移为 `processId` / process handle；若公开 schema 改名需要兼容窗口，则在明确的版本边界完成；
+- 后台命令句柄以 `processId` / process handle 为 canonical 名称，旧 `sessionId` 在 0.2.x 保留 deprecated alias 兼容窗口；
 - 为 stateless MCP transport 做准备，同时保留旧协议兼容 adapter，避免把 transport 生命周期重新提升成 ForgeRelay 会话模型。
 
 ## 0.3 — LSP code intelligence v1

package/docs/security.md

@@ -124,8 +124,9 @@ Do not describe ForgeRelay as a sandboxed coding environment.
 
 Shell execution has a 300-second foreground wait ceiling, not a 300-second
 process lifetime. When `bash` is still running after that window, ForgeRelay
-returns a process `sessionId` and leaves the process alive. `write_stdin` can poll,
-wait, interact, or explicitly interrupt it. An asynchronously completed process
+returns a canonical `processId` and leaves the process alive. `write_stdin` can
+poll, wait, interact, or explicitly interrupt it. The former process `sessionId`
+remains a deprecated compatibility alias during 0.2.x. An asynchronously completed process
 is reported on a later tool result for the same logical workspace ID, including
 error-result paths, and is never broadcast to another workspace ID. Explicitly
 resuming the same workspace ID in another conversation intentionally transfers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",

package/scripts/debug/accept.mjs

@@ -126,6 +126,14 @@ try {
   assert.match(bashTool?.description ?? "", /write_stdin/);
   const writeStdinTool = tools.find((tool) => tool.name === "write_stdin");
   assert.equal(writeStdinTool?.inputSchema?.properties?.yieldTimeMs?.maximum, 300000);
+  assert.match(
+    writeStdinTool?.inputSchema?.properties?.processId?.description ?? "",
+    /Canonical process identifier/,
+  );
+  assert.match(
+    writeStdinTool?.inputSchema?.properties?.sessionId?.description ?? "",
+    /Deprecated alias for processId/,
+  );
   const openWorkspaceTool = tools.find((tool) => tool.name === "open_workspace");
   assert.ok(openWorkspaceTool?.inputSchema?.properties?.workspaceId);
   assert.ok(openWorkspaceTool?.inputSchema?.properties?.newWorkspace);
@@ -217,7 +225,7 @@ try {
   });
   assert.match(shell.structuredContent.result, /debug-bash-ok/);
   assert.equal(shell.structuredContent.running, false);
-  pass("bash", "foreground command completed through ProcessSessionManager");
+  pass("bash", "foreground command completed through ProcessManager");
 
   const failedEdit = callTool(oauth.accessToken, sessionId, 7, "edit", {
     workspaceId,