@code-yeongyu/senpi 2026.11.10 → 2026.11.11

package/dist/modes/rpc/project-file-commands.js

@@ -0,0 +1,195 @@
+/**
+ * `read_project_file` / `write_project_file`: read and edit the session workspace's instruction files over RPC, so a
+ * client with no filesystem access to the machine (a remote desktop) edits Rules the way a local one does.
+ *
+ * Reading runs nothing, so trust does not gate it; writing is refused while the project is untrusted, like
+ * `set_project_setting`. Every write names the version it replaces (`ifEtag`, `null` to create), is refused as a
+ * conflict carrying the current etag when the file moved on, and lands by temp file + rename so a reader never sees a
+ * half-written file. Writes to one file are serialized inside the engine.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { chmod, open, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { createMissingFolders, NO_FOLLOW, PROJECT_FILE_MAX_BYTES, parseProjectFilePath, resolveProjectFile, } from "./project-file-path.js";
+import { RPC_ERROR_INVALID_ARGUMENT, RPC_ERROR_PROJECT_FILE_CONFLICT, RPC_ERROR_PROJECT_FILE_NOT_ALLOWED, RPC_ERROR_PROJECT_FILE_TOO_LARGE, RPC_ERROR_PROJECT_FILE_WRITE_FAILED, RPC_ERROR_PROJECT_NOT_TRUSTED, } from "./rpc-error-types.js";
+const writeChains = new Map();
+function etagOf(bytes) {
+    return `sha256-${createHash("sha256").update(bytes).digest("hex")}`;
+}
+function notAllowed(path) {
+    return {
+        ok: false,
+        message: `${path} is not an instruction file inside this workspace (AGENTS.md, CLAUDE.md or .omo/rules/**).`,
+        errorCode: RPC_ERROR_PROJECT_FILE_NOT_ALLOWED,
+        errorData: { path },
+    };
+}
+function tooLarge(path) {
+    return {
+        ok: false,
+        message: `${path} is larger than ${PROJECT_FILE_MAX_BYTES} bytes.`,
+        errorCode: RPC_ERROR_PROJECT_FILE_TOO_LARGE,
+        errorData: { limitBytes: PROJECT_FILE_MAX_BYTES },
+    };
+}
+function parsePath(command, path) {
+    if (typeof path !== "string") {
+        return { ok: false, message: `${command} requires a string 'path'.`, errorCode: RPC_ERROR_INVALID_ARGUMENT };
+    }
+    return parseProjectFilePath(path) ?? notAllowed(path);
+}
+/**
+ * Reads the stored bytes without following a link and without blocking on a FIFO swapped in after resolution; the
+ * size is checked on the open handle before anything is read.
+ */
+async function readStored(absolute) {
+    let handle;
+    try {
+        handle = await open(absolute, constants.O_RDONLY | NO_FOLLOW | (constants.O_NONBLOCK ?? 0));
+    }
+    catch (error) {
+        const code = error instanceof Error && "code" in error ? error.code : undefined;
+        if (code === "ENOENT")
+            return { kind: "missing" };
+        if (code === "ELOOP")
+            return { kind: "refused" };
+        throw error;
+    }
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile())
+            return { kind: "refused" };
+        if (stat.size > PROJECT_FILE_MAX_BYTES)
+            return { kind: "too_large" };
+        return { kind: "file", bytes: await handle.readFile(), mode: stat.mode & 0o777 };
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function readFileState(session, file) {
+    const cwd = session.sessionManager.getCwd();
+    const resolved = await resolveProjectFile(cwd, file);
+    if (!resolved.ok)
+        return notAllowed(file.relative);
+    const read = resolved.exists ? await readStored(resolved.absolute) : { kind: "missing" };
+    if (read.kind === "refused")
+        return notAllowed(file.relative);
+    if (read.kind === "too_large")
+        return tooLarge(file.relative);
+    const stored = read.kind === "file" ? read.bytes : undefined;
+    return {
+        data: {
+            cwd,
+            path: file.relative,
+            exists: stored !== undefined,
+            content: stored === undefined ? null : stored.toString("utf8"),
+            etag: stored === undefined ? null : etagOf(stored),
+            projectTrusted: session.settingsManager.isProjectTrusted(),
+        },
+        mode: read.kind === "file" ? read.mode : undefined,
+        absolute: resolved.absolute,
+        missingFolders: resolved.missingFolders,
+    };
+}
+export async function readProjectFile(session, path) {
+    const file = parsePath("read_project_file", path);
+    if ("ok" in file)
+        return file;
+    const state = await readFileState(session, file);
+    if ("ok" in state)
+        return state;
+    return { ok: true, data: state.data };
+}
+/** Thrown when the parent folder no longer resolves to itself, i.e. a folder on the way was swapped for a link. */
+class ParentMoved extends Error {
+}
+async function assertParentInPlace(folder) {
+    if ((await realpath(folder)) !== folder)
+        throw new ParentMoved(folder);
+}
+/**
+ * Temp file + rename in the resolved folder, keeping an existing file's permissions. The folder is re-resolved before
+ * the temp file is written and again before the rename, so a folder swapped for a link after resolution is refused
+ * instead of followed (the remaining window between that check and the syscall needs a local writer racing it).
+ */
+async function replaceAtomically(absolute, content, mode) {
+    const folder = dirname(absolute);
+    const temp = join(folder, `.${basename(absolute)}.${randomUUID()}.tmp`);
+    await assertParentInPlace(folder);
+    try {
+        await writeFile(temp, content, { flag: "wx", mode: mode ?? 0o644 });
+        if (mode !== undefined)
+            await chmod(temp, mode);
+        await assertParentInPlace(folder);
+        await rename(temp, absolute);
+    }
+    catch (error) {
+        await rm(temp, { force: true });
+        throw error;
+    }
+}
+async function writeChecked(session, file, content, ifEtag) {
+    const state = await readFileState(session, file);
+    if ("ok" in state)
+        return state;
+    if (state.data.etag !== ifEtag) {
+        return {
+            ok: false,
+            message: `${file.relative} changed since that version was read; read it again before writing.`,
+            errorCode: RPC_ERROR_PROJECT_FILE_CONFLICT,
+            errorData: { currentEtag: state.data.etag, exists: state.data.exists },
+        };
+    }
+    try {
+        if (!(await createMissingFolders(state.missingFolders)))
+            return notAllowed(file.relative);
+        await replaceAtomically(state.absolute, content, state.mode);
+    }
+    catch (error) {
+        if (error instanceof ParentMoved)
+            return notAllowed(file.relative);
+        return {
+            ok: false,
+            message: `Writing ${file.relative} failed: ${error instanceof Error ? error.message : String(error)}`,
+            errorCode: RPC_ERROR_PROJECT_FILE_WRITE_FAILED,
+        };
+    }
+    return readProjectFile(session, file.relative);
+}
+export async function writeProjectFile(session, path, content, ifEtag) {
+    const file = parsePath("write_project_file", path);
+    if ("ok" in file)
+        return file;
+    if (typeof content !== "string" || (ifEtag !== null && typeof ifEtag !== "string")) {
+        return {
+            ok: false,
+            message: "write_project_file requires a string 'content' and 'ifEtag' (the etag read, or null to create).",
+            errorCode: RPC_ERROR_INVALID_ARGUMENT,
+        };
+    }
+    if (!session.settingsManager.isProjectTrusted()) {
+        return {
+            ok: false,
+            message: "Project is not trusted; refusing to write project files. Trust it with set_project_trust first.",
+            errorCode: RPC_ERROR_PROJECT_NOT_TRUSTED,
+        };
+    }
+    if (Buffer.byteLength(content, "utf8") > PROJECT_FILE_MAX_BYTES)
+        return tooLarge(file.relative);
+    const key = join(session.sessionManager.getCwd(), file.relative);
+    const previous = writeChains.get(key) ?? Promise.resolve();
+    const run = () => writeChecked(session, file, content, ifEtag);
+    // A write queued behind a failed one still runs, and its caller never receives the earlier caller's error.
+    const next = previous.then(run, run);
+    writeChains.set(key, next);
+    try {
+        return await next;
+    }
+    finally {
+        if (writeChains.get(key) === next)
+            writeChains.delete(key);
+    }
+}
+//# sourceMappingURL=project-file-commands.js.map

package/dist/modes/rpc/project-file-path.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Which workspace files `read_project_file` / `write_project_file` may touch, and where they resolve on disk.
+ *
+ * The allowlist is the instruction files the engine itself reads: `AGENTS.md` / `CLAUDE.md` at the workspace root or
+ * in any folder below it, and anything under `.omo/rules/`. A path is relative, `/`-separated and canonical (no empty,
+ * `.` or `..` segment), and never passes through `.git` or `node_modules`. Resolution walks the path one segment at a
+ * time with `lstat` from the real workspace root and refuses any symlink or non-folder on the way, so neither a
+ * traversal nor a link can reach a file outside the workspace.
+ */
+/** Under the host's 1,000,000-character message limit, so an oversized write reaches this typed refusal. */
+export declare const PROJECT_FILE_MAX_BYTES: number;
+/** `O_NOFOLLOW` where the platform has it, so a link swapped in after resolution still fails the open. */
+export declare const NO_FOLLOW: number;
+export interface ProjectFilePath {
+    readonly relative: string;
+    readonly segments: readonly string[];
+}
+export declare function parseProjectFilePath(input: string): ProjectFilePath | undefined;
+export type ResolvedProjectFile = {
+    readonly ok: true;
+    readonly absolute: string;
+    readonly exists: boolean;
+    readonly missingFolders: readonly string[];
+} | {
+    readonly ok: false;
+};
+/** Resolves `file` inside the real workspace root; `missingFolders` are the parent folders a write must create. */
+export declare function resolveProjectFile(cwd: string, file: ProjectFilePath): Promise<ResolvedProjectFile>;
+/**
+ * Creates the missing parent folders one at a time; a non-recursive `mkdir` fails on anything that appeared in the
+ * meantime, and each new folder is re-checked as a real folder before the next one is made inside it.
+ */
+export declare function createMissingFolders(folders: readonly string[]): Promise<boolean>;
+//# sourceMappingURL=project-file-path.d.ts.map

package/dist/modes/rpc/project-file-path.js

@@ -0,0 +1,93 @@
+/**
+ * Which workspace files `read_project_file` / `write_project_file` may touch, and where they resolve on disk.
+ *
+ * The allowlist is the instruction files the engine itself reads: `AGENTS.md` / `CLAUDE.md` at the workspace root or
+ * in any folder below it, and anything under `.omo/rules/`. A path is relative, `/`-separated and canonical (no empty,
+ * `.` or `..` segment), and never passes through `.git` or `node_modules`. Resolution walks the path one segment at a
+ * time with `lstat` from the real workspace root and refuses any symlink or non-folder on the way, so neither a
+ * traversal nor a link can reach a file outside the workspace.
+ */
+import { constants } from "node:fs";
+import { lstat, mkdir, realpath } from "node:fs/promises";
+import { join } from "node:path";
+/** Under the host's 1,000,000-character message limit, so an oversized write reaches this typed refusal. */
+export const PROJECT_FILE_MAX_BYTES = 512 * 1024;
+const INSTRUCTION_FILE_NAMES = new Set(["AGENTS.md", "CLAUDE.md"]);
+const EXCLUDED_SEGMENTS = new Set([".git", "node_modules"]);
+const FORBIDDEN_CHARACTERS = /[\\:\0]/;
+/** `O_NOFOLLOW` where the platform has it, so a link swapped in after resolution still fails the open. */
+export const NO_FOLLOW = constants.O_NOFOLLOW ?? 0;
+export function parseProjectFilePath(input) {
+    if (input.length === 0 || input.startsWith("/") || FORBIDDEN_CHARACTERS.test(input))
+        return undefined;
+    const segments = input.split("/");
+    for (const segment of segments) {
+        if (segment === "" || segment === "." || segment === ".." || EXCLUDED_SEGMENTS.has(segment))
+            return undefined;
+    }
+    const name = segments[segments.length - 1] ?? "";
+    const isRule = segments.length >= 3 && segments[0] === ".omo" && segments[1] === "rules";
+    if (!isRule && !INSTRUCTION_FILE_NAMES.has(name))
+        return undefined;
+    return { relative: segments.join("/"), segments };
+}
+function isMissing(error) {
+    return error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR");
+}
+async function lstatOrMissing(path) {
+    try {
+        return await lstat(path);
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+}
+/** Resolves `file` inside the real workspace root; `missingFolders` are the parent folders a write must create. */
+export async function resolveProjectFile(cwd, file) {
+    let current = await realpath(cwd);
+    const folders = file.segments.slice(0, -1);
+    const missingFolders = [];
+    for (const folder of folders) {
+        current = join(current, folder);
+        if (missingFolders.length > 0) {
+            missingFolders.push(current);
+            continue;
+        }
+        const stat = await lstatOrMissing(current);
+        if (stat === undefined)
+            missingFolders.push(current);
+        else if (stat.isSymbolicLink() || !stat.isDirectory())
+            return { ok: false };
+    }
+    const absolute = join(current, file.segments[file.segments.length - 1] ?? "");
+    if (missingFolders.length > 0)
+        return { ok: true, absolute, exists: false, missingFolders };
+    const stat = await lstatOrMissing(absolute);
+    if (stat === undefined)
+        return { ok: true, absolute, exists: false, missingFolders };
+    if (stat.isSymbolicLink() || !stat.isFile())
+        return { ok: false };
+    return { ok: true, absolute, exists: true, missingFolders };
+}
+/**
+ * Creates the missing parent folders one at a time; a non-recursive `mkdir` fails on anything that appeared in the
+ * meantime, and each new folder is re-checked as a real folder before the next one is made inside it.
+ */
+export async function createMissingFolders(folders) {
+    for (const folder of folders) {
+        try {
+            await mkdir(folder);
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "EEXIST"))
+                throw error;
+        }
+        const stat = await lstat(folder);
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=project-file-path.js.map

package/dist/modes/rpc/rpc-error-types.d.ts

@@ -36,6 +36,14 @@ export declare const RPC_ERROR_PROJECT_SETTINGS_WRITE_FAILED = "project_settings
 export declare const RPC_ERROR_PROJECT_NOT_TRUSTED = "project_not_trusted";
 /** `set_project_setting` while the project settings file does not parse; fix the file first. */
 export declare const RPC_ERROR_PROJECT_SETTINGS_UNREADABLE = "project_settings_unreadable";
+/** `read_project_file`/`write_project_file` on a path outside the instruction-file allowlist or the workspace. */
+export declare const RPC_ERROR_PROJECT_FILE_NOT_ALLOWED = "project_file_not_allowed";
+/** `write_project_file` whose `ifEtag` is not the file's current version; `errorData.currentEtag` names it. */
+export declare const RPC_ERROR_PROJECT_FILE_CONFLICT = "project_file_conflict";
+/** `read_project_file`/`write_project_file` over the project file size limit. */
+export declare const RPC_ERROR_PROJECT_FILE_TOO_LARGE = "project_file_too_large";
+/** `write_project_file` whose write failed (permissions, disk). */
+export declare const RPC_ERROR_PROJECT_FILE_WRITE_FAILED = "project_file_write_failed";
 /** `open_session.context` broke a documented cap (key count, key syntax, value or total bytes). */
 export declare const RPC_ERROR_INVALID_SESSION_CONTEXT = "invalid_session_context";
 /** `open_session.env` is malformed or names a variable that is not caller-passable on this host (senpi#4381). */
@@ -123,5 +131,5 @@ export declare const RPC_ERROR_RELEASE_FAILED = "release_failed";
 export declare const RPC_ERROR_HOST_DRAINING = "host_draining";
 /** The supervisor has closed admission; a launch-owning caller may ensure a successor. */
 export declare const RPC_ERROR_HOST_STOPPING = "host_stopping";
-export type RpcErrorCode = typeof RPC_ERROR_SESSION_IDENTITY_MISMATCH | typeof RPC_ERROR_SESSION_BUSY_LIFECYCLE | typeof RPC_ERROR_ATTACHED_ELSEWHERE | typeof RPC_ERROR_OWNER_CHANGED | typeof RPC_ERROR_SESSION_NOT_HELD | typeof RPC_ERROR_HOST_STOPPING | typeof RPC_ERROR_UNKNOWN_SESSION | typeof RPC_ERROR_SESSION_NOT_ATTACHED | typeof RPC_ERROR_SESSION_CLOSING | typeof RPC_ERROR_SESSION_PATH_IN_USE | typeof RPC_ERROR_SESSION_HELD | typeof RPC_ERROR_SESSION_RESERVATION_LIMIT | typeof RPC_ERROR_MISSING_SESSION_ID | typeof RPC_ERROR_MULTI_SESSION_DISABLED | typeof RPC_ERROR_INVALID_PATH | typeof RPC_ERROR_OPEN_FAILED | typeof RPC_ERROR_MEDIA_NOT_FOUND | typeof RPC_ERROR_PROJECT_TRUST_LOCKED | typeof RPC_ERROR_PROJECT_TRUST_EXTENSION_DECIDED | typeof RPC_ERROR_PROJECT_SETTINGS_WRITE_FAILED | typeof RPC_ERROR_PROJECT_NOT_TRUSTED | typeof RPC_ERROR_PROJECT_SETTINGS_UNREADABLE | typeof RPC_ERROR_INVALID_SESSION_CONTEXT | typeof RPC_ERROR_INVALID_SUBSCRIPTION | typeof RPC_ERROR_UNKNOWN_SUBSCRIPTION | typeof RPC_ERROR_SUBSCRIPTION_LIMIT | typeof RPC_ERROR_UNSUPPORTED_TRANSPORT | typeof RPC_ERROR_INVALID_SESSION_KIND | typeof RPC_ERROR_INVALID_LAUNCH_PROFILE | typeof RPC_ERROR_INVALID_SESSION_ID | typeof RPC_ERROR_SESSION_ID_IN_USE | typeof RPC_ERROR_HOST_MEMORY_PRESSURE | typeof RPC_ERROR_WARM_FAILED | typeof RPC_ERROR_STREAMING | typeof RPC_ERROR_ENTRY_NOT_FOUND | typeof RPC_ERROR_MODEL_NOT_FOUND | typeof RPC_ERROR_EFFECT_ID_CONFLICT | typeof RPC_ERROR_TRANSCRIPT_UNREADABLE | typeof RPC_ERROR_PROVIDER_UNAVAILABLE | typeof RPC_ERROR_PROVIDER_CREDENTIALS_MISSING | typeof RPC_ERROR_PROVIDER_CREDENTIALS_EXPIRED | typeof RPC_ERROR_NO_MODEL_SELECTED | typeof RPC_ERROR_TURN_CONFLICT | typeof RPC_ERROR_CONTEXT_BUDGET | typeof RPC_ERROR_EVAL_CELL_NOT_FOUND | typeof RPC_ERROR_INVALID_EVAL_CELL_REQUEST | typeof RPC_ERROR_EVAL_CELLS_UNAVAILABLE | typeof RPC_ERROR_NOT_ASSISTANT | typeof RPC_ERROR_NOT_USER | typeof RPC_ERROR_EMPTY_TEXT | typeof RPC_ERROR_UNKNOWN_COMMAND | typeof RPC_ERROR_STALE_LEAF | typeof RPC_ERROR_TURN_ACTIVE | typeof RPC_ERROR_SESSION_BUSY | typeof RPC_ERROR_ATTACHED | typeof RPC_ERROR_INVALID_RELEASE_REASON | typeof RPC_ERROR_RELEASE_UNSUPPORTED | typeof RPC_ERROR_RELEASE_FAILED | typeof RPC_ERROR_HOST_DRAINING | typeof RPC_ERROR_RESPONSE_UNWRITABLE;
+export type RpcErrorCode = typeof RPC_ERROR_SESSION_IDENTITY_MISMATCH | typeof RPC_ERROR_SESSION_BUSY_LIFECYCLE | typeof RPC_ERROR_ATTACHED_ELSEWHERE | typeof RPC_ERROR_OWNER_CHANGED | typeof RPC_ERROR_SESSION_NOT_HELD | typeof RPC_ERROR_HOST_STOPPING | typeof RPC_ERROR_UNKNOWN_SESSION | typeof RPC_ERROR_SESSION_NOT_ATTACHED | typeof RPC_ERROR_SESSION_CLOSING | typeof RPC_ERROR_SESSION_PATH_IN_USE | typeof RPC_ERROR_SESSION_HELD | typeof RPC_ERROR_SESSION_RESERVATION_LIMIT | typeof RPC_ERROR_MISSING_SESSION_ID | typeof RPC_ERROR_MULTI_SESSION_DISABLED | typeof RPC_ERROR_INVALID_PATH | typeof RPC_ERROR_OPEN_FAILED | typeof RPC_ERROR_MEDIA_NOT_FOUND | typeof RPC_ERROR_PROJECT_TRUST_LOCKED | typeof RPC_ERROR_PROJECT_TRUST_EXTENSION_DECIDED | typeof RPC_ERROR_PROJECT_SETTINGS_WRITE_FAILED | typeof RPC_ERROR_PROJECT_NOT_TRUSTED | typeof RPC_ERROR_PROJECT_SETTINGS_UNREADABLE | typeof RPC_ERROR_PROJECT_FILE_NOT_ALLOWED | typeof RPC_ERROR_PROJECT_FILE_CONFLICT | typeof RPC_ERROR_PROJECT_FILE_TOO_LARGE | typeof RPC_ERROR_PROJECT_FILE_WRITE_FAILED | typeof RPC_ERROR_INVALID_SESSION_CONTEXT | typeof RPC_ERROR_INVALID_SUBSCRIPTION | typeof RPC_ERROR_UNKNOWN_SUBSCRIPTION | typeof RPC_ERROR_SUBSCRIPTION_LIMIT | typeof RPC_ERROR_UNSUPPORTED_TRANSPORT | typeof RPC_ERROR_INVALID_SESSION_KIND | typeof RPC_ERROR_INVALID_LAUNCH_PROFILE | typeof RPC_ERROR_INVALID_SESSION_ID | typeof RPC_ERROR_SESSION_ID_IN_USE | typeof RPC_ERROR_HOST_MEMORY_PRESSURE | typeof RPC_ERROR_WARM_FAILED | typeof RPC_ERROR_STREAMING | typeof RPC_ERROR_ENTRY_NOT_FOUND | typeof RPC_ERROR_MODEL_NOT_FOUND | typeof RPC_ERROR_EFFECT_ID_CONFLICT | typeof RPC_ERROR_TRANSCRIPT_UNREADABLE | typeof RPC_ERROR_PROVIDER_UNAVAILABLE | typeof RPC_ERROR_PROVIDER_CREDENTIALS_MISSING | typeof RPC_ERROR_PROVIDER_CREDENTIALS_EXPIRED | typeof RPC_ERROR_NO_MODEL_SELECTED | typeof RPC_ERROR_TURN_CONFLICT | typeof RPC_ERROR_CONTEXT_BUDGET | typeof RPC_ERROR_EVAL_CELL_NOT_FOUND | typeof RPC_ERROR_INVALID_EVAL_CELL_REQUEST | typeof RPC_ERROR_EVAL_CELLS_UNAVAILABLE | typeof RPC_ERROR_NOT_ASSISTANT | typeof RPC_ERROR_NOT_USER | typeof RPC_ERROR_EMPTY_TEXT | typeof RPC_ERROR_UNKNOWN_COMMAND | typeof RPC_ERROR_STALE_LEAF | typeof RPC_ERROR_TURN_ACTIVE | typeof RPC_ERROR_SESSION_BUSY | typeof RPC_ERROR_ATTACHED | typeof RPC_ERROR_INVALID_RELEASE_REASON | typeof RPC_ERROR_RELEASE_UNSUPPORTED | typeof RPC_ERROR_RELEASE_FAILED | typeof RPC_ERROR_HOST_DRAINING | typeof RPC_ERROR_RESPONSE_UNWRITABLE;
 //# sourceMappingURL=rpc-error-types.d.ts.map

package/dist/modes/rpc/rpc-error-types.js

@@ -36,6 +36,14 @@ export const RPC_ERROR_PROJECT_SETTINGS_WRITE_FAILED = "project_settings_write_f
 export const RPC_ERROR_PROJECT_NOT_TRUSTED = "project_not_trusted";
 /** `set_project_setting` while the project settings file does not parse; fix the file first. */
 export const RPC_ERROR_PROJECT_SETTINGS_UNREADABLE = "project_settings_unreadable";
+/** `read_project_file`/`write_project_file` on a path outside the instruction-file allowlist or the workspace. */
+export const RPC_ERROR_PROJECT_FILE_NOT_ALLOWED = "project_file_not_allowed";
+/** `write_project_file` whose `ifEtag` is not the file's current version; `errorData.currentEtag` names it. */
+export const RPC_ERROR_PROJECT_FILE_CONFLICT = "project_file_conflict";
+/** `read_project_file`/`write_project_file` over the project file size limit. */
+export const RPC_ERROR_PROJECT_FILE_TOO_LARGE = "project_file_too_large";
+/** `write_project_file` whose write failed (permissions, disk). */
+export const RPC_ERROR_PROJECT_FILE_WRITE_FAILED = "project_file_write_failed";
 /** `open_session.context` broke a documented cap (key count, key syntax, value or total bytes). */
 export const RPC_ERROR_INVALID_SESSION_CONTEXT = "invalid_session_context";
 /** `open_session.env` is malformed or names a variable that is not caller-passable on this host (senpi#4381). */

package/dist/modes/rpc/rpc-host-command-types.d.ts

@@ -255,7 +255,20 @@ type RpcCommandBody = RpcAttachmentCommand | (RpcSessionCommand & {
     context?: Record<string, string>;
 };
 /** Compact callers may identify their own admission on any correlated session request. */
-export type RpcCommand = RpcCommandBody & {
+export type RpcCommand = (RpcCommandBody | {
+    id?: string;
+    /** Build one invisible session for later claim; never an attachment. Requires `park_claim`. */
+    type: "park_session";
+    cwd: string;
+    kind?: SessionKind;
+    context?: Record<string, string>;
+} | (Omit<Extract<RpcCommandBody, {
+    type: "open_session";
+}>, "type" | "cwd"> & {
+    /** Consume one ready park. A miss returns `claimed: false` and never builds a session. */
+    type: "claim_session";
+    cwd: string;
+})) & {
     readonly admissionId?: string;
 };
 /** Stdin records: session/host commands plus extension-UI replies and progress, and host-request answers. */

package/dist/modes/rpc/rpc-host-response-types.d.ts

@@ -19,6 +19,27 @@ export interface RpcSessionPresence {
     readonly held: number;
 }
 export type RpcHostCommandResponse = {
+    id?: string;
+    type: "response";
+    command: "park_session";
+    success: true;
+    data: {
+        state: "parked" | "already_parked" | "full";
+    };
+} | {
+    id?: string;
+    type: "response";
+    command: "claim_session";
+    success: true;
+    data: {
+        claimed: false;
+    } | {
+        sessionId: string;
+        state: RpcSessionState;
+        attached?: boolean;
+        presence?: RpcSessionPresence;
+    };
+} | {
     id?: string;
     type: "response";
     command: "list_hands";

package/dist/modes/rpc/rpc-mutation-response-types.d.ts

@@ -9,6 +9,7 @@ import type { SessionControlAdmission } from "../../core/extensions/types.ts";
 import type { PermissionModeReply } from "../../core/permission-mode.ts";
 import type { ApiKeyVerification } from "../../core/verify-api-key.ts";
 import type { ClientMessageAdmission } from "./client-admission-record.ts";
+import type { RpcProjectFile } from "./project-file-commands.ts";
 import type { RpcProjectSettings, RpcProjectTrust } from "./project-workspace-commands.ts";
 import type { RpcAbortQuiesce, RpcEffectAnswer, RpcQueuedInputChange } from "./rpc-effect-answer-types.ts";
 import type { EditAssistantMessageResult, EditUserMessageResult, NavigateTreeResult } from "./rpc-result-types.ts";
@@ -219,6 +220,12 @@ export type RpcMutationResponse = {
     command: "set_project_setting";
     success: true;
     data: RpcProjectSettings;
+} | {
+    id?: string;
+    type: "response";
+    command: "write_project_file";
+    success: true;
+    data: RpcProjectFile;
 } | {
     id?: string;
     type: "response";

package/dist/modes/rpc/rpc-read-response-types.d.ts

@@ -9,6 +9,7 @@ import type { ReleaseReceipt } from "./compact-event-leases.ts";
 import type { EventPageAnswer, RecoveryPageAnswer } from "./compact-recovery-requests.ts";
 import type { ThinkingLevelSource } from "../../core/session-thinking-memory.ts";
 import type { EffectStatus } from "./effect-record.ts";
+import type { RpcProjectFile } from "./project-file-commands.ts";
 import type { RpcProjectSettings, RpcProjectTrust } from "./project-workspace-commands.ts";
 import type { RpcSlashCommand } from "./rpc-command-surface.ts";
 import type { RpcEvalCell, RpcEvalCellSnapshot } from "./rpc-result-types.ts";
@@ -209,6 +210,12 @@ export type RpcReadResponse = {
     command: "get_project_settings";
     success: true;
     data: RpcProjectSettings;
+} | {
+    id?: string;
+    type: "response";
+    command: "read_project_file";
+    success: true;
+    data: RpcProjectFile;
 } | {
     id?: string;
     type: "response";

package/dist/modes/rpc/rpc-session-command-types.d.ts

@@ -488,6 +488,16 @@ export type RpcSessionCommand = {
     type: "set_project_setting";
     key: string;
     value: unknown;
+} | {
+    id?: string;
+    type: "read_project_file";
+    path: string;
+} | {
+    id?: string;
+    type: "write_project_file";
+    path: string;
+    content: string;
+    ifEtag: string | null;
 } | {
     id?: string;
     type: "extension_request";

package/dist/modes/rpc/rpc-session-state-types.d.ts

@@ -74,6 +74,8 @@ export interface RpcProviderAccount {
         model: string;
         outcome: "ok" | "failed";
         reason?: string;
+        message?: string;
+        status?: number;
         at: number;
     };
     /** `needs_sign_in`: the account must sign in again before it is used. */

package/dist/modes/rpc/session-attachment-gate.js

@@ -8,6 +8,8 @@ export const ATTACH_GATE_EXEMPT = new Set([
     "unsubscribe_sessions",
     "get_subscription_limits",
     "warm",
+    "park_session",
+    "claim_session",
     "detach_connection",
     "open_session",
     "attach_session",
@@ -25,6 +27,7 @@ export const ATTACH_GATE_EXEMPT = new Set([
     "get_loaded_surfaces",
     "get_project_trust",
     "get_project_settings",
+    "read_project_file",
     "get_available_models",
     "get_available_thinking_levels",
     "get_fast_mode",
@@ -65,6 +68,9 @@ export function attachmentGate(host, command) {
         return undefined;
     if (host.sessionsByConnection.get(owner)?.has(command.sessionId))
         return undefined;
+    // senpi#6305: the forwarder's peer lane delivers an agent's message without ever attaching; only its admit passes.
+    if (command.type === "admit_external_message" && host.connectionRoles.grantedByForwarder(owner, "peer_agent"))
+        return undefined;
     if (process.env.SENPI_RPC_REQUIRE_ATTACH === "1")
         return error(command.id, command.type, "session_not_attached", {
             reason: "this connection is not attached to that session",

package/dist/modes/rpc/session-binding.d.ts

@@ -4,6 +4,7 @@ import type { RpcSessionEntry } from "./session-registry.ts";
 /** A session-owned adapter around the classic command and extension-UI wiring. */
 export interface RpcSessionBinding {
     handle(command: object): Promise<void>;
+    setClientCapabilities?(capabilities: readonly string[]): void;
     cancelPendingExtensionUiRequests?(): void;
     /** A connection of the shared host left this session (`close_session`, a dropped or detached connection). */
     connectionDetached?(connectionId: string): void;

package/dist/modes/rpc/session-binding.js

@@ -40,6 +40,8 @@ export async function createRpcSessionBinding(sessionId, entry, writer, requestC
         return carrier && record && firstOrdinal !== undefined ? { record, carrier, ordinal, firstOrdinal } : undefined;
     };
     const enqueueRecord = (record) => {
+        if (entry.speculative)
+            return;
         toolSpans.observe(record);
         const canonical = pairing?.take(record);
         const refused = pairing?.refused(record) === true;
@@ -103,6 +105,8 @@ export async function createRpcSessionBinding(sessionId, entry, writer, requestC
             writeInScope(record);
         };
         const writeStructuredInScope = bindToProviderScope((record) => {
+            if (entry.speculative)
+                return;
             writer.structuredLanes.accept(sessionId, record);
             const control = pairing?.structured(record);
             if (control && lane)
@@ -151,7 +155,7 @@ export async function createRpcSessionBinding(sessionId, entry, writer, requestC
                 rpcOwnersByConnection.clear();
             },
             publishLoadedSurfacesChanged: (previous, digest) => {
-                if (entry.scope.state !== "closed")
+                if (!entry.speculative && entry.scope.state !== "closed")
                     writer.publishLoadedSurfacesChanged(sessionId, previous, digest);
             },
             ...options,
@@ -171,6 +175,7 @@ export async function createRpcSessionBinding(sessionId, entry, writer, requestC
     });
     await handler.ready;
     return {
+        setClientCapabilities: (capabilities) => runWithProviderScope(entry.scope, () => handler.setClientCapabilities(capabilities)),
         handle: (command) => {
             if (writer.handleMcpForm(command))
                 return Promise.resolve();

package/dist/modes/rpc/session-command-activity.js

@@ -23,6 +23,7 @@ const observations = new Set([
     "get_loaded_surfaces",
     "get_project_trust",
     "get_project_settings",
+    "read_project_file",
     "get_media",
     "get_auth_providers",
     "get_provider_accounts",

package/dist/modes/rpc/session-connection-context.d.ts

@@ -7,6 +7,8 @@ export declare class SessionConnectionContext {
     private readonly delegationOf;
     constructor(ownerOf: (id: string) => ExtensionTransportOwner | undefined, delegationOf?: (id: string) => DelegationDescriptor | undefined);
     run<T>(id: string, task: () => T): T;
+    /** Host-owned background construction has no requesting transport or inherited delegation. */
+    outside<T>(task: () => T): T;
     /** The delegation the running line captured at its start, or undefined for a connection that never declared. */
     get delegation(): DelegationDescriptor | undefined;
     /**

package/dist/modes/rpc/session-connection-context.js

@@ -10,6 +10,10 @@ export class SessionConnectionContext {
         const delegation = this.delegationOf(id);
         return this.storage.run({ id, owner: this.ownerOf(id), ...(delegation === undefined ? {} : { delegation }) }, task);
     }
+    /** Host-owned background construction has no requesting transport or inherited delegation. */
+    outside(task) {
+        return this.storage.exit(task);
+    }
     /** The delegation the running line captured at its start, or undefined for a connection that never declared. */
     get delegation() {
         return this.storage.getStore()?.delegation;

package/dist/modes/rpc/session-registry-attach.d.ts

@@ -1,4 +1,6 @@
 import type { SessionPathReservations } from "./host-reservations.ts";
 import { type OpenRpcSession, type RpcSessionEntry, type RpcSessionLaunchProfile, type RpcSessionOpenOptions } from "./session-registry-types.ts";
 export declare function attachToOpenSession(entries: ReadonlyMap<string, RpcSessionEntry>, sessionPath: string, profile: RpcSessionLaunchProfile, options: RpcSessionOpenOptions | undefined, pathReservations: SessionPathReservations | undefined, now: number): Promise<OpenRpcSession>;
+/** The live launch choices shared by attach-on-open and claiming an already-built session. */
+export declare function applyAttachedProfile(entry: RpcSessionEntry, profile: RpcSessionLaunchProfile): void;
 //# sourceMappingURL=session-registry-attach.d.ts.map

package/dist/modes/rpc/session-registry-attach.js

@@ -102,6 +102,21 @@ export async function attachToOpenSession(entries, sessionPath, profile, options
         entry.retainOnDisconnect = true;
     if (!entry.durableSessionId)
         throw new RpcSessionRegistryError("session_path_in_use");
+    applyAttachedProfile(entry, profile);
+    entry.lastCommandAt = now;
+    if (wasParked) {
+        entry.lifecycleMutex = entry.lifecycleMutex.then(() => entry.runtime?.emitAttachmentEvent("session_resumed"));
+        await entry.lifecycleMutex;
+    }
+    return {
+        sessionId: handle,
+        durableSessionId: entry.durableSessionId,
+        sessionPath: entry.sessionPath,
+        attached: true,
+    };
+}
+/** The live launch choices shared by attach-on-open and claiming an already-built session. */
+export function applyAttachedProfile(entry, profile) {
     // The surface, browser engine and permission preset follow the client: an attach that names one
     // moves the live session to it; an attach without one keeps what the session has.
     if (profile.promptSurface !== undefined && profile.promptSurface !== entry.profile.promptSurface) {
@@ -121,16 +136,5 @@ export async function attachToOpenSession(entries, sessionPath, profile, options
         entry.profile = frozenProfile(withClientPreset(entry.profile, namedPreset));
         entry.runtime?.setPermissionPreset(namedPreset);
     }
-    entry.lastCommandAt = now;
-    if (wasParked) {
-        entry.lifecycleMutex = entry.lifecycleMutex.then(() => entry.runtime?.emitAttachmentEvent("session_resumed"));
-        await entry.lifecycleMutex;
-    }
-    return {
-        sessionId: handle,
-        durableSessionId: entry.durableSessionId,
-        sessionPath: entry.sessionPath,
-        attached: true,
-    };
 }
 //# sourceMappingURL=session-registry-attach.js.map

package/dist/modes/rpc/session-registry-claims.js

@@ -70,6 +70,8 @@ export async function settlePendingClaim(pending, sessionPath, graceMs) {
 /** Reconcile path and durable identity after runtime replacement. */
 export function syncRuntimeMetadata(entries, reservations, pathReservations) {
     for (const entry of entries) {
+        if (entry.speculative)
+            continue;
         const manager = entry.runtime?.session.sessionManager;
         if (!manager)
             continue;