letagents 0.12.31 → 0.12.33

package/dist/mcp/server/register-tools.js

@@ -1,6 +1,7 @@
 import { localSupervisedRoomToolAvailable } from "../../../shared/local-supervised-tools.mjs";
 import { isLocalRoomApi } from "../../../shared/room-api-origin.mjs";
 import { registerRoomKnowledgeTools } from "./tools/knowledge.js";
+import { registerWakeRuleTools } from "./tools/wake-rules.js";
 import { registerAgentSessionTools } from "./tools/agent-sessions.js";
 import { registerMessageTools, registerStatusTools } from "./tools/messages.js";
 import { registerOnboardingTools } from "./tools/onboarding.js";
@@ -40,6 +41,7 @@ export function registerTools(server, profile = "autonomous_mcp_worker", supervi
         registerAgentSessionTools(tools);
     registerRoomInspectionTools(tools);
     registerRoomKnowledgeTools(tools);
+    registerWakeRuleTools(tools);
     registerStatusTools(tools);
     if (profile === "autonomous_mcp_worker" || profile === "interactive_desktop")
         registerWorkspaceTools(tools);

package/dist/mcp/server/runtime/identity/config.js

@@ -39,10 +39,39 @@ function getExplicitAgentIdentityStorageKey() {
     ].filter((value) => Boolean(value?.trim()));
     return runtimeSignals[0] ?? null;
 }
+/**
+ * Reads the `clientInfo.name` the MCP host sent in `initialize`. Hosts that
+ * do not set LETAGENTS_AGENT_IDE are still identifiable this way; without it
+ * every Claude Code or OpenCode agent showed up as a generic "Agent". Read
+ * lazily: the name exists as soon as the initialize request is handled.
+ */
+let readMcpClientName = () => null;
+export function setMcpClientNameSource(source) {
+    readMcpClientName = source;
+}
+const MCP_CLIENT_IDE_LABELS = [
+    [/^claude[-_ ]?code\b/i, "Claude Code"],
+    [/^opencode\b/i, "OpenCode"],
+    [/^codex\b/i, "Codex"],
+    [/^cursor\b/i, "Cursor"],
+    [/^antigravity\b/i, "Antigravity"],
+];
+export function ideLabelFromMcpClientName(name) {
+    const value = String(name ?? "").trim();
+    if (!value)
+        return null;
+    return MCP_CLIENT_IDE_LABELS.find(([pattern]) => pattern.test(value))?.[1] ?? null;
+}
 export function detectAgentIdeLabel() {
     if (AGENT_IDE_LABEL) {
         return toTitleCaseCodename(AGENT_IDE_LABEL);
     }
+    // The host's own name outranks inherited environment: Claude Code started
+    // from a Codex shell still carries CODEX_* variables.
+    const fromClient = ideLabelFromMcpClientName(readMcpClientName());
+    if (fromClient) {
+        return fromClient;
+    }
     if (isCodexRuntime()) {
         return "Codex";
     }
@@ -54,5 +83,5 @@ export function detectAgentRuntimeLabel() {
     if (isCodexRuntime()) {
         return "codex";
     }
-    return detectAgentIdeLabel().trim().toLowerCase() || "unknown";
+    return detectAgentIdeLabel().trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "unknown";
 }

package/dist/mcp/server/supervised-tool-facade.js

@@ -1,24 +1,9 @@
 import { parsePositivePgIntegerScopedId } from "../../../shared/message-contracts.mjs";
+import { SUPERVISED_READ_ONLY_TOOLS } from "../../../shared/supervised-read-tools.mjs";
 import { runWithCurrentSupervisedRoom } from "./runtime/room-state.js";
 import { completeCurrentSupervisedEffect, authorizeCustodialPolling, executeCurrentSupervisedTool, prepareCurrentSupervisedEffect, } from "./runtime/supervisor-bridge.js";
-const READ_TOOLS = new Set([
-    "get_current_room",
-    "check_repo",
-    "check_repo_visibility",
-    "read_messages",
-    "wait_for_messages",
-    "get_board",
-    "get_board_settings",
-    "get_room_memory", "get_human_requests", "get_room_guidelines",
-    "get_room_artifacts",
-    "get_room_events",
-    "list_board_intents",
-    "get_onboarding_status",
-    "status_local_codex_session",
-    "rental_list_requests",
-]);
 export function supervisedToolIsMutation(toolName) {
-    return !READ_TOOLS.has(toolName);
+    return !SUPERVISED_READ_ONLY_TOOLS.has(toolName);
 }
 // The desktop daemon's local control protocol intentionally uses small bounded
 // frames. A read result can be returned live to the provider without copying

package/dist/mcp/server/tools/messages/wait-tool.js

@@ -438,7 +438,7 @@ export async function collectThreadContextMessages(input) {
     return { messages: contextMessages, truncated };
 }
 export function registerWaitForMessagesTool(server) {
-    server.tool("wait_for_messages", "Wait for new messages in a Let Agents Chat room (HTTP long-poll). Messages labeled activation.for_current_agent.decision=\"silent\" are skipped for the current worker; when last_observed_message_id is present, use it as cursor progress even if messages is empty. Threaded replies include thread_parent_id/thread.root_message_id; use send_thread_message with that id to keep focused side discussion out of the main room. For multi-hour runs, call in a loop: always pass after_message_id from the last message you processed or last_observed_message_id so an empty result means 'nothing new yet', not 'stop working'. Legacy/manual room workers may send a brief continue instruction when another legacy/manual participant posts a premature 'I will wait' closing line. Never send that nudge to or about a daemon-supervised participant, and daemon-supervised workers must not emit it; their supervisor owns wake and retry. Per-call wait is capped (default max 180s unless LETAGENTS_POLL_MAX_MS is set on API and MCP).", {
+    server.tool("wait_for_messages", "Wait for new messages in a Let Agents Chat room (HTTP long-poll). Messages labeled activation.for_current_agent.decision=\"silent\" are skipped for the current worker; when last_observed_message_id is present, use it as cursor progress even if messages is empty. Threaded replies include thread_parent_id/thread.root_message_id; use send_thread_message with that id to keep focused side discussion out of the main room. For multi-hour runs, call in a loop: always pass after_message_id from the last message you processed or last_observed_message_id so an empty result means 'nothing new yet', not 'stop working'. Legacy/manual room workers may send a brief continue instruction when another legacy/manual participant posts a premature 'I will wait' closing line. Never send that nudge to or about a daemon-supervised participant, and daemon-supervised workers must not emit it; their supervisor owns wake and retry. Per-call wait is capped (default max 180s unless LETAGENTS_POLL_MAX_MS is set on API and MCP). To wait for CI, a review, a task change or a later time, add a wake rule with add_wake_rule: its wake arrives here as a message addressed to you.", {
         room_id: z.string().optional().describe("Canonical room ID. Defaults to the current room."),
         after_message_id: z
             .string()

package/dist/mcp/server/tools/tasks/board-intent-tools.js

@@ -260,7 +260,7 @@ export function registerBoardIntentTools(server) {
         }
     });
     server.tool("list_board_intents", "List Board Manager intents for this room, optionally filtered by status.", {
-        status: z.enum(["pending", "approved", "denied", "expired", "used"]).optional(),
+        status: z.enum(["pending", "approved", "denied", "expired", "used", "superseded"]).optional(),
         room_id: z.string().optional().describe("Canonical room ID. Defaults to current room."),
     }, async ({ status, room_id }) => {
         const targetRoomId = resolveCanonicalRoomId(room_id);

package/dist/mcp/server/tools/wake-rules.js

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import { WAKE_RULE_EVENTS, WakeRuleError, } from "../../../../shared/wake-rules.mjs";
+import { isLocalRoomStorageEnabled, roomScopedApiCall } from "../runtime.js";
+import { resolveTaskToolIdentity, resolveTaskToolTarget, taskActorPayload } from "./tasks/context.js";
+import { jsonToolResponse, taskToolError } from "./tasks/response.js";
+const scope = {
+    room_id: z.string().optional().describe("Exact room ID. Defaults to this worker’s room."),
+    agent_session_id: z.string().optional(),
+};
+const LOCAL_ROOM_NOTE = "Wake rules need a room shared online; this room is stored on this device.";
+async function roomTarget(roomId) {
+    const target = resolveTaskToolTarget(roomId);
+    if (!target)
+        throw new WakeRuleError("Join a room first.");
+    const id = target.effectiveRoomId || target.roomId || target.projectId;
+    return { target, id, local: await isLocalRoomStorageEnabled(id) };
+}
+function roomPath(suffix) {
+    return (id) => `/rooms/${encodeURIComponent(id)}/wake-rules${suffix}`;
+}
+function toolError(error) {
+    return taskToolError(error instanceof Error ? error.message : String(error));
+}
+export function registerWakeRuleTools(server) {
+    server.tool("add_wake_rule", "Wait for something without polling. Say what you are waiting for, then end your turn: you are woken with a room message addressed to you when it happens, or when the rule expires. "
+        + "Use this instead of saying you will check back later. Events and arguments: "
+        + "timer {at: ISO time} or {after_ms}; "
+        + "task.status_changed {task_id, to?: [statuses]}; "
+        + "github.check_completed {branch | pr | mine: true, conclusions?: [...]} (one wake per push, after CI goes quiet); "
+        + "github.review_submitted {pr | mine: true, states?: [approved, changes_requested, commented]}; "
+        + "github.pr_closed {pr | mine: true, merged_only?}. "
+        + "`mine` means the branches and pull requests of tasks you are working on. Rules expire after 24 hours unless you set expires_at (at most 7 days). "
+        + "Adding the same rule twice returns the existing one. People see what you are waiting for and can cancel it.", {
+        event: z.enum(WAKE_RULE_EVENTS),
+        arguments: z.record(z.string(), z.unknown()).optional().describe("What exactly to wait for; see the event list above."),
+        note: z.string().max(280).optional().describe("Why you are waiting, shown to people and repeated to you when you wake, e.g. \"merge #1440 once CI passes\"."),
+        repeat: z.boolean().optional().describe("Keep watching after the first wake (at most one wake a minute) until it expires. Not for timers."),
+        expires_at: z.string().optional().describe("ISO time to stop waiting. You are woken once more if nothing happened by then."),
+        ...scope,
+    }, async (input) => {
+        try {
+            const { target, local } = await roomTarget(input.room_id);
+            if (local)
+                return taskToolError(LOCAL_ROOM_NOTE);
+            // The server validates the rule and times it by its own clock, so a
+            // timer given as after_ms is not skewed by this machine's clock.
+            const rule = { event: input.event, arguments: input.arguments ?? {}, note: input.note, repeat: input.repeat, expires_at: input.expires_at };
+            const { identity, agentSession } = await resolveTaskToolIdentity(target, input.agent_session_id);
+            return jsonToolResponse(await roomScopedApiCall({
+                room_id: target.roomId,
+                project_id: target.projectId,
+                room_path: roomPath(""),
+                project_path: roomPath(""),
+                options: { method: "POST", body: JSON.stringify({ rule, ...taskActorPayload(identity, agentSession) }) },
+            }));
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+    server.tool("list_wake_rules", "List what agents in this room are waiting for, and wake rules that recently fired, expired or were cancelled. Check this on resume to see what you were waiting for.", { ...scope, agent_key: z.string().optional().describe("Only this agent’s rules.") }, async ({ room_id, agent_key }) => {
+        try {
+            const { target, local } = await roomTarget(room_id);
+            if (local)
+                return jsonToolResponse({ note: LOCAL_ROOM_NOTE, active: [], recent: [] });
+            const query = agent_key ? `?agent_key=${encodeURIComponent(agent_key)}` : "";
+            return jsonToolResponse(await roomScopedApiCall({
+                room_id: target.roomId,
+                project_id: target.projectId,
+                room_path: roomPath(query),
+                project_path: roomPath(query),
+            }));
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+    server.tool("cancel_wake_rule", "Stop waiting: cancel one of your wake rules when you no longer need it, for example after you checked the result yourself.", { rule_id: z.string().regex(/^wake_[a-z0-9]{1,40}$/), ...scope }, async ({ rule_id, room_id, agent_session_id }) => {
+        try {
+            const { target, local } = await roomTarget(room_id);
+            if (local)
+                return taskToolError(LOCAL_ROOM_NOTE);
+            const { identity, agentSession } = await resolveTaskToolIdentity(target, agent_session_id);
+            return jsonToolResponse(await roomScopedApiCall({
+                room_id: target.roomId,
+                project_id: target.projectId,
+                room_path: roomPath(`/${rule_id}/cancel`),
+                project_path: roomPath(`/${rule_id}/cancel`),
+                options: { method: "POST", body: JSON.stringify(taskActorPayload(identity, agentSession)) },
+            }));
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+}

package/dist/mcp/server.js

@@ -7,8 +7,10 @@ import { attachMcpServer, autoJoinFromContext, shutdownRuntime } from "./server/
 import { requireValidWorkerBearerRuntime } from "./server/runtime/worker-bearer.js";
 import { announceProcessExit } from "./server/runtime/process-connection.js";
 import { executionProfile } from "./server/runtime/execution-profile.js";
+import { setMcpClientNameSource } from "./server/runtime/identity/config.js";
 import { WORKSPACE_CAPTURE_INSTRUCTIONS } from "./server/tools/workspace.js";
 import { LETAGENTS_RUNTIME_CONTRACT_ARG, letAgentsRuntimeContract, registerRuntimeReadinessResource, } from "./server/runtime-contract.js";
+const CLIENT_INITIALIZE_WAIT_MS = 5_000;
 async function main() {
     if (process.argv.slice(2).includes(LETAGENTS_RUNTIME_CONTRACT_ARG)) {
         process.stdout.write(`${JSON.stringify(letAgentsRuntimeContract())}\n`);
@@ -25,9 +27,19 @@ async function main() {
     registerTools(server, profile, supervisedProvider);
     registerRuntimeReadinessResource(server, profile, supervisedProvider);
     requireValidWorkerBearerRuntime();
+    // Auto-join resolves the agent identity, whose IDE label comes from the
+    // host's clientInfo, so wait (briefly) for the host to finish initialize.
+    setMcpClientNameSource(() => server.server.getClientVersion()?.name);
+    const initialized = new Promise((resolve) => {
+        server.server.oninitialized = resolve;
+    });
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("🔌 Let Agents Chat MCP server running on stdio (v0.6.0)");
+    await Promise.race([
+        initialized,
+        new Promise((resolve) => setTimeout(resolve, CLIENT_INITIALIZE_WAIT_MS).unref()),
+    ]);
     await autoJoinFromContext();
 }
 let exiting = false;

package/dist/shared/agent-identity.js

@@ -3,7 +3,11 @@ const IDE_LABELS = new Map([
     ["agent", "Agent"],
     ["antigravity", "Antigravity"],
     ["claude", "Claude"],
+    ["claude-code", "Claude Code"],
     ["codex", "Codex"],
+    ["cursor", "Cursor"],
+    ["open-model", "Open Model"],
+    ["opencode", "OpenCode"],
     ["orchestrator", "Orchestrator"],
 ]);
 function normalizeWhitespace(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "letagents",
-  "version": "0.12.31",
+  "version": "0.12.33",
   "description": "Let Agents Chat \u2014 MCP server for AI agent communication",
   "type": "module",
   "main": "dist/mcp/server.js",

package/shared/activation-routing.d.mts

@@ -1,5 +1,5 @@
 export type AgentMessageActivationDecision = "activate" | "silent" | "unclear";
-export type AgentMessageActivationReason = "self_message" | "explicit_mention" | "explicit_other_mention" | "broadcast" | "reply_target" | "other_reply_target" | "thread_participant" | "task_owner" | "small_room" | "recent_conversation" | "jev_routed" | "system_event" | "unaddressed";
+export type AgentMessageActivationReason = "self_message" | "explicit_mention" | "explicit_other_mention" | "broadcast" | "reply_target" | "other_reply_target" | "thread_participant" | "task_owner" | "small_room" | "recent_conversation" | "jev_routed" | "wake_rule" | "system_event" | "unaddressed";
 /** Send-time human fallback only; never use this to re-route historical reads. */
 export declare function humanConversationFallback(input: {
     source: string | null;

package/shared/room-knowledge.d.mts

@@ -22,4 +22,6 @@ export function createKnowledgeRecord(room_id: string, type: KnowledgeType, inpu
 export function reviseKnowledgeRecord(record: KnowledgeRecord, input: KnowledgeRevisionInput, actor: KnowledgeActor, now?: string): KnowledgeRecord;
 export function assertKnowledgeReplay(existing: KnowledgeRecord, candidate: KnowledgeRecord): void;
 
+export function attentionResponseHandle(agentKey: string | null | undefined): string;
 export function formatAttentionResponse(record: KnowledgeRecord): string;
+export function attentionResponseDisplayText(text: string, agentName: (handle: string) => string | null | undefined): string | null;

package/shared/room-knowledge.mjs

@@ -68,7 +68,38 @@ export function assertKnowledgeReplay(existing, candidate) {
   }
 }
 
+/** The `@agent:` handle an answer uses to wake the agent that asked. */
+export function attentionResponseHandle(agentKey) {
+  return String(agentKey ?? '').trim().replace(/[A-Z]/g, c => c.toLowerCase()).replace(/[^a-z0-9_.:/-]+/g, '');
+}
+
 export function formatAttentionResponse(record) {
-  const handle = record.author.kind === 'agent' ? record.author.id.trim().replace(/[A-Z]/g, c => c.toLowerCase()).replace(/[^a-z0-9_.:/-]+/g, '') : '';
+  const handle = record.author.kind === 'agent' ? attentionResponseHandle(record.author.id) : '';
   return `${handle ? `@agent:${handle}\n\n` : ''}Human response (${record.id}):\n\n${record.response.body}`;
 }
+
+const ATTENTION_RESPONSE_TEXT = /^(?:@agent:([a-z0-9_.:/-]+)\n\n)?Human response \([a-zA-Z0-9_-]{8,80}\):\n\n([\s\S]+)$/;
+// A room display name used as a mention: never markdown, never spaces, and
+// no underscore that could open emphasis (leading, or doubled anywhere).
+const MENTION_NAME = /^(?!_)(?!.*__)[A-Za-z0-9._:-]{1,64}$/;
+// Answers that open with a block (fence, list, heading, quote, table, rule or
+// indented code) keep it as a block instead of joining the mention's line.
+const OPENS_WITH_BLOCK = /^(?: {4}|\t| {0,3}(?:`{3}|~{3}|[-*+](?:\s|$)|\d{1,9}[.)](?:\s|$)|#{1,6}(?:\s|$)|>|\||(?:[-*_] *){3,}$))/;
+
+/**
+ * What people see for a message formatAttentionResponse wrote. The handle and
+ * request id route the answer to the agent that asked; the room reads it as a
+ * reply to that agent by name, or to a neutral @agent when the room no longer
+ * lists it (the visible mention is the record of who was woken). Null for any
+ * other text.
+ */
+export function attentionResponseDisplayText(text, agentName) {
+  const match = ATTENTION_RESPONSE_TEXT.exec(typeof text === 'string' ? text : '');
+  if (!match) return null;
+  const answer = match[2];
+  if (!match[1]) return answer;
+  const name = String(agentName(match[1]) ?? '').trim();
+  const mention = `@${MENTION_NAME.test(name) ? name : 'agent'}`;
+  // trimEnd: a CRLF line keeps its \r, and trailing space must not hide a rule.
+  return OPENS_WITH_BLOCK.test(answer.split('\n', 1)[0].trimEnd()) ? `${mention}\n\n${answer}` : `${mention} ${answer}`;
+}

package/shared/room-resource-invalidation.d.mts

@@ -3,11 +3,14 @@ export const ROOM_RESOURCE_AGENT_WORK: "agent_work";
 /** Content-free approval-state hint; consumers repair through separately authorized exact reads. */
 export const ROOM_RESOURCE_AGENT_APPROVAL: "agent_approval";
 export const ROOM_RESOURCE_EXECUTION_DELEGATION: "execution_delegation";
+/** What agents are waiting for changed; consumers re-read the room's wake rules. */
+export const ROOM_RESOURCE_WAKE_RULES: "wake_rules";
 /** Protocol-known references; consumers independently choose what they render. */
 export const ROOM_RESOURCE_INVALIDATION_RESOURCES: readonly [
   "agent_work",
   "agent_approval",
   "execution_delegation",
+  "wake_rules",
 ];
 
 export type RoomResourceInvalidationResource =

package/shared/room-resource-invalidation.mjs

@@ -5,12 +5,14 @@ export const ROOM_RESOURCE_AGENT_WORK = "agent_work";
 // authorized exact reads; the pointer never carries approval content.
 export const ROOM_RESOURCE_AGENT_APPROVAL = "agent_approval";
 export const ROOM_RESOURCE_EXECUTION_DELEGATION = "execution_delegation";
+export const ROOM_RESOURCE_WAKE_RULES = "wake_rules";
 // Protocol-known references. Each consumer still decides which surfaces, if
 // any, react to a supported pointer.
 export const ROOM_RESOURCE_INVALIDATION_RESOURCES = [
   ROOM_RESOURCE_AGENT_WORK,
   ROOM_RESOURCE_AGENT_APPROVAL,
   ROOM_RESOURCE_EXECUTION_DELEGATION,
+  ROOM_RESOURCE_WAKE_RULES,
 ];
 
 function exactKeys(value, keys) {

package/shared/room-turn-no-reply.d.mts

@@ -0,0 +1,7 @@
+export const NO_REPLY_FAILURE: Readonly<{
+  outputLimit: "The model hit its output limit before writing a reply.";
+  emptyAnswer: "The model finished without writing a reply.";
+  contentFilter: "The model provider's content filter stopped the reply before any text was written.";
+}>;
+export type NoReplyFailureKind = keyof typeof NO_REPLY_FAILURE;
+export function noReplyFailureKind(detail: unknown): NoReplyFailureKind | null;

package/shared/room-turn-no-reply.mjs

@@ -0,0 +1,15 @@
+/**
+ * Why a completed provider turn ended without a room reply. The Open Model
+ * adapter reports these as the exact failure detail, and task continuity
+ * reads them back to decide whether a follow-up turn can help.
+ */
+export const NO_REPLY_FAILURE = Object.freeze({
+  outputLimit: "The model hit its output limit before writing a reply.",
+  emptyAnswer: "The model finished without writing a reply.",
+  contentFilter: "The model provider's content filter stopped the reply before any text was written.",
+});
+
+export function noReplyFailureKind(detail) {
+  const text = typeof detail === "string" ? detail.trim() : "";
+  return Object.keys(NO_REPLY_FAILURE).find((kind) => NO_REPLY_FAILURE[kind] === text) ?? null;
+}

package/shared/scratch-workspace-repository.d.mts

@@ -0,0 +1,13 @@
+export const SCRATCH_WORKSPACE_BRANCH: "main";
+export const RETAINED_REPLACED_ENTRIES: number;
+/** Makes a room's scratch workspace the root of its own empty Git repository. */
+export function ensureScratchWorkspaceRepository(
+  workspace: string,
+  options?: { exclude?: readonly string[] },
+): Promise<"created" | "present" | "replaced">;
+/** Null when Git, run with this environment, takes the workspace as a repository. */
+export function probeScratchWorkspaceGit(
+  workspace: string,
+  environment: Record<string, string | undefined>,
+  options?: { timeoutMs?: number; platform?: string; xcodeSelect?: string },
+): Promise<string | null>;

package/shared/scratch-workspace-repository.mjs

@@ -0,0 +1,213 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { access, lstat, mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/** Branch the empty repository starts on. It has no commits. */
+export const SCRATCH_WORKSPACE_BRANCH = "main";
+
+const STAGING = /^\.git\.([1-9][0-9]*)\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.tmp$/;
+// Our own entries beside the repository stay out of an agent's `git add`.
+const OWN_EXCLUDE = ["/.git.*.tmp", "/.git.replaced.*"];
+const REPLACED = /^\.git\.replaced\.([0-9]+)\.[0-9a-f-]{36}$/;
+let replacedCount = 0;
+/** How many broken `.git` entries are kept aside for inspection. */
+export const RETAINED_REPLACED_ENTRIES = 3;
+// A symbolic ref, or a detached SHA-1 or SHA-256 object name.
+const HEAD_CONTENT = /^(?:ref: refs\/\S+|[0-9a-f]{40}|[0-9a-f]{64})\n?$/;
+
+async function kind(path) {
+  try {
+    const info = await lstat(path);
+    return info.isSymbolicLink() ? "link" : info.isDirectory() ? "directory" : info.isFile() ? "file" : "other";
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+/** The least Git and OpenCode need to take `.git` as a repository. */
+async function isRepository(target) {
+  if (await kind(target) !== "directory") return false;
+  if (!(await kind(join(target, "HEAD")) === "file"
+    && await kind(join(target, "config")) === "file"
+    && await kind(join(target, "objects")) === "directory"
+    && await kind(join(target, "refs")) === "directory")) return false;
+  // Git refuses a directory whose HEAD it cannot read as a ref or an object name.
+  const head = await readFile(join(target, "HEAD"), "utf8").catch(() => "");
+  return HEAD_CONTENT.test(head);
+}
+
+/** Keeps only the newest few broken `.git` entries that were moved aside. */
+async function pruneReplaced(workspace) {
+  const replaced = (await readdir(workspace))
+    .map((name) => ({ name, at: Number(REPLACED.exec(name)?.[1] ?? NaN) }))
+    .filter((entry) => Number.isFinite(entry.at))
+    .sort((left, right) => right.at - left.at || (left.name < right.name ? 1 : -1));
+  for (const { name } of replaced.slice(RETAINED_REPLACED_ENTRIES)) {
+    await rm(join(workspace, name), { recursive: true, force: true });
+  }
+}
+
+function alive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code !== "ESRCH";
+  }
+}
+
+/** Removes staging directories left by a process that died mid-write. */
+async function removeAbandonedStaging(workspace) {
+  for (const name of await readdir(workspace)) {
+    const match = STAGING.exec(name);
+    if (!match) continue;
+    const pid = Number(match[1]);
+    if (pid === process.pid || alive(pid)) continue;
+    if (await kind(join(workspace, name)) === "directory") {
+      await rm(join(workspace, name), { recursive: true, force: true });
+    }
+  }
+}
+
+async function build(workspace, exclude) {
+  const staging = join(workspace, `.git.${process.pid}.${randomUUID()}.tmp`);
+  await mkdir(staging, { mode: 0o700 });
+  for (const directory of ["objects/info", "objects/pack", "refs/heads", "refs/tags", "info"]) {
+    await mkdir(join(staging, directory), { recursive: true, mode: 0o700 });
+  }
+  const file = (path, content) => writeFile(join(staging, path), content, { encoding: "utf8", mode: 0o600, flag: "wx" });
+  await file("HEAD", `ref: refs/heads/${SCRATCH_WORKSPACE_BRANCH}\n`);
+  // Git records whether the file system ignores case, as `git init` does.
+  const ignoreCase = await kind(join(staging, "head")) === "file";
+  await file("config", [
+    "[core]",
+    "\trepositoryformatversion = 0",
+    "\tfilemode = true",
+    "\tbare = false",
+    "\tlogallrefupdates = true",
+    ...(ignoreCase ? ["\tignorecase = true"] : []),
+    ...(process.platform === "darwin" ? ["\tprecomposeunicode = true"] : []),
+    "",
+  ].join("\n"));
+  await file(join("info", "exclude"), [...OWN_EXCLUDE, ...exclude].map((line) => `${line}\n`).join(""));
+  return staging;
+}
+
+/**
+ * Makes a room's scratch workspace the root of its own empty Git repository.
+ *
+ * Agent tools treat the root of a Git repository as the edge of a project.
+ * Without one, OpenCode 1.18.20 searches every directory from the workspace
+ * up to the file system root and imports any plugin it finds there into the
+ * process that holds the model provider's key. A repository in the workspace
+ * stops that search at the workspace. It has to be the workspace itself: a
+ * repository in the parent `room-only` directory would make every other
+ * room's workspace part of the same project.
+ *
+ * The repository is written as files, without running Git. Nothing from the
+ * owner's Git configuration, templates, hooks or `GIT_*` variables can reach
+ * it, and a machine without Git still gets a workspace. It has no remote and
+ * no commits, so nothing can be pushed from it unless an agent adds a remote
+ * itself. `exclude` lines go into `.git/info/exclude`, which keeps the
+ * daemon's own files out of `git add` and `git clean`.
+ *
+ * A `.git` that is a directory with `HEAD`, `config`, `objects` and `refs` is
+ * left as it is when its HEAD names a ref or an object: it is a repository,
+ * possibly one the agent made. Anything else at `.git` (a file, a link, an
+ * empty or partial directory, an unreadable HEAD) would let Git and OpenCode
+ * look above the workspace again, so it is moved aside to
+ * `.git.replaced.<time>.<uuid>` and a repository takes its place; only the
+ * newest few moved-aside entries are kept. The repository
+ * is built beside the workspace's files and renamed into place, so a crash
+ * or a second caller never leaves a half-written `.git`; a staging directory
+ * left by a process that died is removed on the next call.
+ *
+ * @param {string} workspace Absolute path of an existing directory.
+ * @param {{ exclude?: readonly string[] }} [options]
+ * @returns {Promise<"created" | "present" | "replaced">}
+ */
+export async function ensureScratchWorkspaceRepository(workspace, options = {}) {
+  const target = join(workspace, ".git");
+  await removeAbandonedStaging(workspace);
+  if (await isRepository(target)) return "present";
+  let replaced = false;
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const staging = await build(workspace, options.exclude ?? []);
+    try {
+      if (await kind(target) !== null && !await isRepository(target)) {
+        // Time, then a per-process count, so that order survives several in one millisecond.
+        const order = Date.now() * 10_000 + (replacedCount++ % 10_000);
+        await rename(target, join(workspace, `.git.replaced.${order}.${randomUUID()}`)).catch((error) => {
+          if (error?.code !== "ENOENT") throw error;
+        });
+        replaced = true;
+      }
+      try {
+        await rename(staging, target);
+      } catch (error) {
+        if (!["EEXIST", "ENOTEMPTY", "ENOTDIR", "EISDIR"].includes(error?.code)) throw error;
+      }
+      // Whoever won, only a verified repository counts.
+      if (await isRepository(target)) {
+        if (replaced) await pruneReplaced(workspace);
+        const ours = await kind(staging) === null;
+        return replaced ? "replaced" : ours ? "created" : "present";
+      }
+    } finally {
+      await rm(staging, { recursive: true, force: true });
+    }
+  }
+  throw new Error("The scratch workspace's .git could not be made a repository.");
+}
+
+const SYSTEM_GIT = "/usr/bin/git";
+
+/** The first executable `git` on a `PATH`, as a shell would find it. */
+async function resolveGit(path) {
+  for (const directory of String(path ?? "").split(":")) {
+    if (!directory) continue;
+    const candidate = join(directory, "git");
+    if (await access(candidate, constants.X_OK).then(() => true, () => false)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Checks, with a launch's environment, that Git takes a scratch workspace as
+ * a repository: `git -C <workspace> rev-parse --git-dir`, as OpenCode runs
+ * it. Without that, OpenCode does not see the repository and the plugin
+ * boundary is not in effect. On macOS, when the `git` found is Apple's
+ * `/usr/bin/git` and `xcode-select -p` fails, the command line tools are
+ * missing: that is reported without running Git, so the check itself never
+ * brings up Apple's install prompt. Each command is bounded by `timeoutMs`.
+ * Resolves to null when Git works, otherwise to what went wrong.
+ *
+ * @param {string} workspace
+ * @param {Record<string, string | undefined>} environment
+ * @param {{ timeoutMs?: number, platform?: string, xcodeSelect?: string }} [options]
+ * @returns {Promise<string | null>}
+ */
+export async function probeScratchWorkspaceGit(workspace, environment, options = {}) {
+  const { execFile } = await import("node:child_process");
+  const timeout = options.timeoutMs ?? 2_000;
+  const env = {};
+  for (const key of ["PATH", "HOME", "XDG_CONFIG_HOME", "LANG", "LC_ALL", "TMPDIR"]) {
+    if (environment[key] !== undefined) env[key] = environment[key];
+  }
+  const run = (file, args) => new Promise((resolve) => {
+    execFile(file, args, { env, timeout, maxBuffer: 16 * 1024 }, (error, stdout) => resolve({ error, stdout: String(stdout ?? "") }));
+  });
+  const git = await resolveGit(env.PATH);
+  if (!git) return "no git on the launch's PATH";
+  if ((options.platform ?? process.platform) === "darwin" && git === SYSTEM_GIT) {
+    const tools = await run(options.xcodeSelect ?? "/usr/bin/xcode-select", ["-p"]);
+    if (tools.error) return "the Xcode command line tools are not installed (xcode-select -p failed), so /usr/bin/git cannot run";
+  }
+  const result = await run(git, ["-C", workspace, "rev-parse", "--git-dir"]);
+  if (result.error) return `git rev-parse --git-dir failed: ${String(result.error.message).split("\n")[0]}`;
+  const gitDir = result.stdout.trim();
+  if (gitDir !== ".git" && gitDir !== join(workspace, ".git")) return `git found its repository at ${gitDir}, not in the workspace`;
+  return null;
+}

package/shared/supervised-read-tools.d.mts

@@ -0,0 +1,2 @@
+/** Room tools that only read; every other supervised tool call is a journaled mutation. */
+export const SUPERVISED_READ_ONLY_TOOLS: ReadonlySet<string>;

package/shared/supervised-read-tools.mjs

@@ -0,0 +1,25 @@
+/**
+ * Room tools that only read. A supervised agent's every other tool call is a
+ * mutation: the MCP facade asks the daemon to journal it, and the daemon
+ * checks that the call it journals was declared as one. Both read this list,
+ * so they cannot disagree about which is which.
+ */
+export const SUPERVISED_READ_ONLY_TOOLS = new Set([
+  "get_current_room",
+  "check_repo",
+  "check_repo_visibility",
+  "read_messages",
+  "wait_for_messages",
+  "get_board",
+  "get_board_settings",
+  "get_room_memory",
+  "get_human_requests",
+  "get_room_guidelines",
+  "get_room_artifacts",
+  "get_room_events",
+  "list_wake_rules",
+  "list_board_intents",
+  "get_onboarding_status",
+  "status_local_codex_session",
+  "rental_list_requests",
+]);