@gajae-code/coding-agent 0.5.4 → 0.6.1

package/src/modes/shared/agent-wire/scopes.ts

@@ -46,6 +46,7 @@ const RPC_COMMAND_SCOPE_REGISTRY: Record<RpcCommandType, BridgeCommandScope> = {
 	set_todos: "control",
 	set_host_tools: "host_tools",
 	set_host_uri_schemes: "host_uri",
+	get_pending_workflow_gates: "message:read",
 	set_model: "model",
 	cycle_model: "model",
 	get_available_models: "model",

package/src/modes/shared/agent-wire/unattended-session.ts

@@ -181,6 +181,15 @@ export class UnattendedSessionControlPlane implements RpcUnattendedControlPlane,
 		return this.#broker.resolve(response);
 	}
 
+	listPendingGates(): import("../../rpc/rpc-types").RpcWorkflowGate[] {
+		const store = this.opts.store;
+		if (!store) return [];
+		return store
+			.list()
+			.filter(record => record.status === "pending")
+			.map(record => record.gate);
+	}
+
 	emitGate(input: OpenGateInput): Promise<unknown> {
 		if (!this.#broker) {
 			return Promise.reject(new Error("cannot emit a workflow gate before unattended mode is negotiated"));

package/src/modes/utils/hotkeys-markdown.ts

@@ -21,8 +21,9 @@ export function buildHotkeysMarkdown(bindings: HotkeysMarkdownBindings): string
 		"**Editing**",
 		"| Key | Action |",
 		"|-----|--------|",
-		"| `Enter` | Send message |",
-		"| `Shift+Enter` / `Alt+Enter` | New line |",
+		"| `Enter` | Send / queue while busy |",
+		`| \`${appKey(bindings, "app.message.queue")}\` | Queue message for next turn |`,
+		"| `Shift+Enter` | New line |",
 		"| `Ctrl+W` / `Option+Backspace` | Delete word backwards |",
 		"| `Ctrl+U` | Delete to start of line |",
 		"| `Ctrl+K` | Delete to end of line |",
@@ -45,6 +46,7 @@ export function buildHotkeysMarkdown(bindings: HotkeysMarkdownBindings): string
 		`| \`${appKey(bindings, "app.plan.toggle")}\` | Toggle plan mode |`,
 		`| \`${appKey(bindings, "app.history.search")}\` | Search prompt history |`,
 		`| \`${appKey(bindings, "app.tools.expand")}\` | Toggle tool output expansion |`,
+		`| \`${appKey(bindings, "app.tool.backgroundFold")}\` twice | Fold supported foreground bash into a background job |`,
 		`| \`${appKey(bindings, "app.thinking.toggle")}\` | Toggle thinking block visibility |`,
 		`| \`${appKey(bindings, "app.editor.external")}\` | Edit message in external editor |`,
 		`| \`${appKey(bindings, "app.clipboard.pasteImage")}\` | Paste image from clipboard |`,

package/src/modes/utils/ui-helpers.ts

@@ -559,11 +559,11 @@ export class UiHelpers {
 
 		const followUpMessages: Array<{ message: string; label: string }> = [];
 		for (const message of queuedMessages.followUp) {
-			followUpMessages.push({ message, label: "Follow-up" });
+			followUpMessages.push({ message, label: "Queued" });
 		}
 		for (const entry of this.ctx.compactionQueuedMessages as CompactionQueuedMessage[]) {
 			if (entry.mode === "followUp") {
-				followUpMessages.push({ message: entry.text, label: "Follow-up" });
+				followUpMessages.push({ message: entry.text, label: "Queued" });
 			}
 		}
 

package/src/prompts/goals/goal-continuation.md

@@ -23,3 +23,4 @@ Before calling `goal({op:"complete"})`, you MUST perform a completion audit agai
 Call `goal({op:"complete"})` only when every deliverable has direct, current-state evidence proving it is satisfied. The completion call is a load-bearing claim; it ends the autonomous loop and surfaces a "done" report to the user.
 
 If the work is not done, just keep working. Do not narrate that you are continuing — execute.
+If every outstanding deliverable is genuinely blocked on human input or action only the user can perform (e.g. the user must sing, record, edit, approve, or carry out a manual/physical step) and no further autonomous progress is possible, call `goal({op:"pause"})` to park the goal. This stops the autonomous continuation loop without falsely completing or dropping the objective. State the human blocker, pause, then stop. When the user later unblocks the work, they (or you) resume via `goal({op:"resume"})`.

package/src/prompts/goals/goal-mode-active.md

@@ -12,6 +12,7 @@ Usage:
 Use the `goal` tool to inspect or complete the active goal:
 - `goal({op:"get"})` returns the current goal and usage state.
 - `goal({op:"complete"})` is only for verified completion.
+- `goal({op:"pause"})` parks the goal when every outstanding deliverable is blocked on human input only the user can perform; it stops the autonomous continuation loop and is resumed with `goal({op:"resume"})`.
 
 You MUST keep the full objective intact across turns. Do not redefine success around a smaller, easier, or already-completed subset.
 

package/src/prompts/system/rlm-report-command.md

@@ -0,0 +1 @@
+Call complete_research with final=false and a concise summary of the current notebook-backed findings. Do not mark the goal complete unless the full research objective is satisfied.

package/src/prompts/system/rlm-research.md

@@ -0,0 +1,23 @@
+You are operating in **RLM research mode** — a Jupyter-notebook-style research session backed by a persistent Python kernel. Your job is to investigate a question or dataset through iterative, reproducible Python analysis and then synthesize what you found.
+
+## How you work
+
+- Drive the investigation with the `python` tool. The kernel is **persistent**: variables, imports, and loaded data survive across calls, exactly like notebook cells. Build up state incrementally instead of re-running everything each time.
+- Each `python` call is recorded as a notebook cell (code + output) in this session's `notebook.ipynb`. Write focused cells that each make one clear step of progress.
+- Prefer the managed scientific stack (`numpy`, `pandas`, `matplotlib`, `polars`) when useful. If an additional package is missing, use the kernel's `%pip install ...` magic only when it is necessary for the investigation; that install cell is recorded in the notebook as provenance.
+- Use `read` to inspect local files, `web_search` to gather external facts, and read-only `bash` only for simple inspection commands where shell-native views are materially useful (`grep`, `rg`, `tree`, `ls`, `pwd`, `wc`, `du`, `file`, `stat`). The `bash` surface is restricted to a single command with no pipelines, redirects, env overrides, command substitution, shell expansion, or write-capable flags. You do **not** have file-editing or arbitrary-mutation tools in this mode by design: keep all work inside the Python kernel, read-only inspection, and the notebook/report artifacts.
+- RLM always runs under goal mode. Use `goal({"op":"get"})` to inspect the active research goal. When the research objective is actually satisfied and the report-worthy conclusions are grounded in notebook outputs, call `goal({"op":"complete"})`, then call `complete_research` with a concise final summary. Do not present the session as complete without both tool calls.
+
+## Evidence discipline
+
+- Ground every claim in an actual cell output you can point to. Do not report a metric, finding, or conclusion you have not computed and seen.
+- When a cell fails, read the error, fix the specific cause, and continue — do not paper over failures.
+- Distinguish what the data shows from what you infer. State assumptions explicitly.
+
+## Data context
+
+- If a `DATA.md` file (or a `--data` path) was provided, treat it as the authoritative description of the available data and honor it.
+
+## Reporting
+
+- When the investigation is complete (or when asked), produce a clear Markdown research report covering the question, the method, the key findings with their supporting evidence, and the conclusions and caveats. The session's `report.md` is synthesized from your notebook and final summary.

package/src/prompts/tools/bash.md

@@ -2,27 +2,48 @@ Executes bash command in shell session for terminal operations like git, bun, ca
 
 <instruction>
 - Use `cwd` to set working directory, not `cd dir && …`
+{{#when restrictionProfile "==" "read-only"}}
+- Do not pass `env` overrides or `pty: true`; read-only bash rejects both.
+- Shell control operators such as `;`, `|`, `&`, `<`, `>`, and command substitution are blocked.
+- Internal URIs (`agent://`, `artifact://`, `rule://`, `local://`) are auto-resolved to filesystem paths without creating parent directories.
+{{else}}
 - Prefer `env: { NAME: "…" }` for multiline, quote-heavy, or untrusted values; reference as `$NAME`
 - Quote variable expansions like `"$NAME"` to preserve exact content
 - PTY mode is opt-in: set `pty: true` only when the command needs a real terminal (e.g. `sudo`, `ssh` requiring user input); default is `false`
 - Use `;` only when later commands should run regardless of earlier failures
 - Internal URIs (`agent://`, `artifact://`, `rule://`, `local://`) are auto-resolved to filesystem paths
+{{/when}}
 {{#if asyncEnabled}}
 - Use `async: true` for long-running commands when you don't need immediate output; the call returns a background job ID and the result is delivered automatically as a follow-up.
 {{/if}}
+{{#if autoBackgroundEnabled}}
+- In the interactive TUI, the user can press `Ctrl+B` twice while a supported managed foreground bash command is still running to fold it into a quiet background job. Do not instruct users to use raw shell `Ctrl+Z`/`bg` inside the GJC TUI; ownership and output routing are not safe there.
+{{/if}}
 </instruction>
 {{#if restrictedAllowedPrefixes}}
-<restricted-role-agent-mode>
+<restricted-bash-mode>
+{{#when restrictionProfile "==" "read-only"}}
+This session's bash tool is read-only. It accepts only simple, single-command inspections beginning with:
+{{#each restrictedAllowedPrefixes}}
+- `{{this}}`
+{{/each}}
+Shell control operators, command substitution, env overrides, redirects, pipelines, glob expansion, and known write-capable flags are blocked before execution. Use it only when an inspection command is materially better than `read`, `search`, or `find`.
+{{else}}
 This session's bash tool is restricted. It only accepts commands beginning with:
 {{#each restrictedAllowedPrefixes}}
 - `{{this}}`
 {{/each}}
 Use it only for sanctioned GJC workflow CLI persistence or state read/write/contract operations; per-command env overrides and all other shell command shapes are blocked before execution.
-</restricted-role-agent-mode>
+{{/when}}
+</restricted-bash-mode>
 {{/if}}
 
 <critical>
+{{#when restrictionProfile "==" "read-only"}}
+- Use read-only bash only for approved inspection commands that are materially better than `read`, `search`, or `find`; the tool itself blocks non-approved commands and unsafe shell shapes.
+{{else}}
 - NEVER use Linux coreutils (`cat`, `head`, `tail`, `less`, `more`, `ls`, `grep`, `rg`, `awk`, `sed`, `find`, `fd`, etc.) when a dedicated tool suffices — ALWAYS prefer `read`, `search`, `find`, `edit`, `write`.
+{{/when}}
 - NEVER pipe through `| head -n N` or `| tail -n N` — output is already truncated with the full result available via `artifact://<id>`.
 - NEVER redirect with `2>&1` or `2>/dev/null` — stdout and stderr are already merged.
 </critical>

package/src/prompts/tools/browser.md

@@ -10,9 +10,10 @@ Drives a real Chromium tab with full puppeteer access via JS execution.
 - Tabs survive across `run` calls and across in-process subagents. Open once, reuse many times.
 - Browser kinds, selected by the `app` field on `open`:
   - default (no `app`) → headless Chromium with stealth patches.
-  - `app.path` → spawn an absolute binary (Electron/CDP). If a running instance already exposes a CDP port, it is reused; otherwise stale instances are killed and a fresh one is spawned. No stealth patches — never tamper with a real desktop app.
-  - `app.cdp_url` → connect to an existing CDP endpoint (e.g. `http://127.0.0.1:9222`).
-  - `app.target` (with `path`/`cdp_url`) — substring matched against url+title to pick a BrowserWindow when the app exposes several.
+  - `app.path` → spawn an absolute binary (Electron/CDP). If a running instance already exposes a CDP port, it is reused; otherwise stale instances are killed and a fresh one is spawned. Do not use this for a daily Chrome profile; use `app.browser: "chrome"` instead.
+  - `app.browser: "chrome"` + `app.path` + `app.user_data_dir` + `app.profile_directory` → use an existing saved Chrome profile. GJC binds CDP to `127.0.0.1` on an ephemeral or `app.cdp_port` port, reuses a matching running profile only when it already exposes attachable localhost CDP, refuses a matching non-CDP running profile instead of killing/relaunching it, and kills only the Chrome process GJC launched. Externally-owned CDP is disconnect-only. `app.background`/`app.no_focus` add Chromium's `--no-startup-window` guard; focus avoidance is best-effort and platform-dependent.
+  - `app.cdp_url` → connect to an existing CDP endpoint (e.g. `http://127.0.0.1:9222`). For logged-in profiles, only expose CDP on localhost and treat the endpoint as full browser-account access.
+  - `app.target` (with `path`/`cdp_url`/Chrome profile) — substring matched against url+title to pick a BrowserWindow when the app exposes several.
 - Inside `run`, `tab` exposes high-level helpers; reach for `page` (raw puppeteer Page) when you need anything they don't cover.
   - `tab.goto(url, { waitUntil? })` — clears the element cache and navigates.
   - `tab.observe({ includeAll?, viewportOnly? })` — accessibility snapshot. Returns `{ url, title, viewport, scroll, elements: [{ id, role, name, value, states, … }] }`. Element ids are stable until the next observe/goto.
@@ -56,6 +57,9 @@ Drives a real Chromium tab with full puppeteer access via JS execution.
 # Attach to an existing Electron app
 `{"action":"open","name":"cursor","app":{"path":"/Applications/Cursor.app/Contents/MacOS/Cursor"}}`
 
+# Use an existing Chrome profile in the background
+`{"action":"open","name":"work-browser","app":{"browser":"chrome","path":"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome","user_data_dir":"~/Library/Application Support/Google/Chrome","profile_directory":"Profile 10","background":true,"no_focus":true,"target":"example.com"}}`
+
 # Close one tab (browser stays alive if other tabs reference it)
 `{"action":"close","name":"docs"}`
 

package/src/prompts/tools/computer.md

@@ -0,0 +1,74 @@
+# computer
+
+`computer` is available by default on supported Apple Silicon macOS. It controls the real desktop, so use it only when the task genuinely needs real desktop screenshot or input control.
+
+## Safety contract
+
+- Disabled means disabled: when the tool is disabled (`computer.alwaysOn=false` with `computer.enabled` unset/false) or the platform is unsupported, every action including `screenshot` fails with `COMPUTER_DISABLED` and captures nothing.
+- Callable only on Apple Silicon macOS (`arm64` darwin); available by default there, with `computer.alwaysOn=false` as the off-switch and `computer.enabled=true` as the manual enable path.
+- Native execution remains supervisor-gated. If the stop/suspend supervisor is unavailable, stale, suspended, permissioned off, display-stale, or cancelled, the action fails closed with a `COMPUTER_*` code.
+- Respect the user's stop/suspend request immediately. Do not loop desktop actions after a stop/suspend/error.
+- The user can stop or suspend the session at any time with the configured kill-switch hotkey (default `Control+Option+Command+Escape`). If you see `COMPUTER_CANCELLED` or `COMPUTER_SUPERVISOR_NOT_LIVE`, stop and wait for the user.
+
+## Coordinate contract
+
+Coordinates are screenshot pixels, not CSS pixels and not normalized fractions. Use the latest successful `screenshot` dimensions and origin/scale metadata as the coordinate frame. Do not guess coordinates outside the screenshot bounds.
+
+When you send a sequence of actions in one `batch` call, pointer coordinates in later steps are validated against the most recent screenshot from that batch. If a coordinate is out of bounds, the batch stops and reports `COMPUTER_COORD_INVALID`. Always capture a fresh screenshot before acting if the display may have changed.
+
+## Actions
+
+The model action object uses exactly these snake_case actions and fields:
+
+- `screenshot` — capture the enabled desktop.
+- `click` — `x`, `y`, optional `button` (`left`, `right`, `middle`).
+- `double_click` — `x`, `y`, optional `button`.
+- `move` — `x`, `y`, optional `button`.
+- `drag` — `x`, `y`, `to_x`, `to_y`, optional `button`.
+- `scroll` — `x`, `y`, `scroll_x`, `scroll_y`.
+- `type` — `text`.
+- `keypress` — `keys` string array.
+- `wait` — `ms`.
+- `batch` — `actions`: a non-empty array of the single actions above. Steps run in order and the result includes per-step status and the last screenshot captured inside the batch.
+
+Shared optional fields: `timeout` seconds and `include_screenshot` for a bounded post-action screenshot when supported.
+
+Do not use camelCase fields such as `doubleClick`, `toX`, `scrollX`, or `includeScreenshot` in the model action object.
+
+## Examples
+
+Take a single screenshot:
+
+```json
+{ "action": "screenshot" }
+```
+
+Click a coordinate from the latest screenshot:
+
+```json
+{ "action": "click", "x": 120, "y": 340 }
+```
+
+Run a focused sequence in one batch — screenshot first, then act, so coordinates are validated:
+
+```json
+{
+  "action": "batch",
+  "actions": [
+    { "action": "screenshot" },
+    { "action": "click", "x": 120, "y": 340 },
+    { "action": "type", "text": "hello" },
+    { "action": "keypress", "keys": ["Return"] }
+  ]
+}
+```
+
+## Error recovery
+
+- `COMPUTER_COORD_INVALID`: the coordinate was outside the latest screenshot bounds. Capture a fresh screenshot and re-derive coordinates.
+- `COMPUTER_DISPLAY_STALE`: the display changed since the screenshot. Capture a fresh screenshot before acting.
+- `COMPUTER_SUPERVISOR_NOT_LIVE` / `COMPUTER_SUSPENDED` / `COMPUTER_CANCELLED`: stop acting and wait for the user.
+- `COMPUTER_PERMISSION_REQUIRED`: the host needs screen-recording or accessibility permission. Ask the user to grant it.
+- `COMPUTER_DISABLED`: the tool is disabled or the host is unsupported. Do not retry.
+
+After any error, resume with a fresh screenshot rather than guessing.

package/src/prompts/tools/goal.md

@@ -6,13 +6,16 @@ Use a single `op` field:
 - `resume` re-activates a paused goal so work can continue.
 - `complete` marks the goal complete after you have verified every deliverable against current evidence.
 - `drop` discards the current goal without completing it.
+- `pause` parks an active goal without completing or dropping it. The autonomous continuation loop stops while the goal is paused, so the agent is not re-activated every turn. Use `pause` (not `drop`) when the goal is genuinely still alive but every outstanding deliverable is blocked on human input or action only the user can perform — e.g. the user must sing, record, edit, approve, or perform a manual/physical step — and no further autonomous progress is possible. A paused goal keeps its progress and is fully resumable via `resume`.
 
 Examples:
 - `goal({"op":"create","objective":"Implement feature X"})`
 - `goal({"op":"get"})`
 - `goal({"op":"resume"})`
+- `goal({"op":"pause"})`
 - `goal({"op":"complete"})`
 - `goal({"op":"drop"})`
 
 Call `complete` only when the goal is actually done and verified.
 If `get` shows a paused goal, call `resume` before continuing work on it.
+Do not `pause` as a substitute for `complete`; pause only when the outstanding work is human-blocked.

package/src/prompts/tools/job.md

@@ -1,12 +1,20 @@
 Inspects, waits, or cancels async jobs.
 
-Background job results are delivered automatically when complete. Reach for this tool only when you need to intervene.
+Background job results are delivered automatically when complete. Running job output stays quiet by default to avoid flooding the conversation; use `tail` when you explicitly want to show/reopen retained output. Reach for this tool only when you need to inspect or intervene.
+
+In the interactive TUI, supported managed foreground bash can be folded into a background job by pressing `Ctrl+B` twice while it is running. Raw shell `Ctrl+Z`/`bg` is not the supported path inside GJC because it bypasses job ownership and output-routing contracts.
 
 # Operations
 
 ## `list: true`
 Use to inspect what's running.
 
+## `tail: [id, …]`
+Show the retained output buffer for one or more background jobs without waiting.
+- Use this to reopen/tail a backgrounded long-running bash/tool output after folding it away.
+- Output is bounded by the manager retention window; stale cursors may report that only the retained tail is available.
+- Prefer `tail` over polling when you only need to peek at progress, so the conversation can continue without flooding the TUI.
+
 ## `poll: [id, …]`
 Block until the specified jobs finish or the wait window elapses.
 - Use when you are genuinely blocked on a result and have no other work to do.

package/src/prompts/tools/web-search.md

@@ -5,6 +5,13 @@ Searches the web for up-to-date information beyond knowledge cutoff.
 - You MUST include links for cited sources in the final response
 </instruction>
 
+<xai>
+- With provider `xai`, use `xai_search_mode: "web"` for normal web search, `"x"` for X/Twitter search, or `"web_and_x"` when both surfaces are relevant.
+- xAI web filters: `allowed_domains` or `excluded_domains` (max 5, mutually exclusive), plus `enable_image_understanding` and `enable_image_search`.
+- xAI X filters: `allowed_x_handles` or `excluded_x_handles` (max 20, mutually exclusive), `from_date`, `to_date`, `enable_image_understanding`, and `enable_video_understanding`.
+- Use `no_inline_citations` with provider `xai` when the answer should omit inline citation markdown while still returning structured sources.
+</xai>
+
 <caution>
 Searches are performed automatically within a single API call—no pagination or follow-up requests needed.
 </caution>

package/src/rlm/artifacts.ts

@@ -0,0 +1,60 @@
+/**
+ * RLM session artifact layout under <cwd>/.gjc/rlm/<sessionId>/.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { readNotebookDocument } from "../edit/notebook";
+import type { RlmArtifactPaths } from "./types";
+
+export const RLM_DIR_SEGMENT = path.join(".gjc", "rlm");
+
+const SESSION_ID_RE = /^[A-Za-z0-9_-]+$/;
+
+export function isValidRlmSessionId(sessionId: string): boolean {
+	return sessionId.length > 0 && sessionId.length <= 128 && SESSION_ID_RE.test(sessionId);
+}
+
+/** Generate a filesystem-safe, sortable session id (timestamp + random suffix). */
+export function generateRlmSessionId(now: Date = new Date()): string {
+	const stamp = now.toISOString().replace(/[:.]/g, "").replace("T", "-").replace("Z", "");
+	const suffix = Math.random().toString(36).slice(2, 8);
+	return `${stamp}-${suffix}`;
+}
+
+export function resolveRlmArtifactPaths(cwd: string, sessionId: string): RlmArtifactPaths {
+	if (!isValidRlmSessionId(sessionId)) {
+		throw new Error(`Invalid RLM session id: ${JSON.stringify(sessionId)}`);
+	}
+	const dir = path.join(cwd, RLM_DIR_SEGMENT, sessionId);
+	return {
+		dir,
+		notebookPath: path.join(dir, "notebook.ipynb"),
+		reportPath: path.join(dir, "report.md"),
+		metadataPath: path.join(dir, "metadata.json"),
+		agentSessionDir: path.join(dir, "agent-session"),
+	};
+}
+
+export async function ensureRlmSessionDir(paths: RlmArtifactPaths): Promise<void> {
+	await fs.mkdir(paths.dir, { recursive: true });
+}
+
+export async function rlmSessionExists(cwd: string, sessionId: string): Promise<boolean> {
+	const paths = resolveRlmArtifactPaths(cwd, sessionId);
+	try {
+		const stat = await fs.stat(paths.dir);
+		return stat.isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+export async function readRlmNotebookIfPresent(cwd: string, sessionId: string) {
+	const paths = resolveRlmArtifactPaths(cwd, sessionId);
+	try {
+		return await readNotebookDocument(paths.notebookPath, paths.notebookPath);
+	} catch (error) {
+		if (error instanceof Error && error.message.startsWith("File not found:")) return undefined;
+		throw error;
+	}
+}

package/src/rlm/complete-research-tool.ts

@@ -0,0 +1,163 @@
+/**
+ * RLM completion/report tool.
+ *
+ * This is the model-facing stop/report seam for autonomous research mode. It
+ * writes the deterministic report from the live notebook and, for final
+ * completion, marks the RLM controller complete so the existing agent loop can
+ * pause through CreateAgentSessionOptions.shouldPause.
+ */
+import * as z from "zod/v4";
+import type { NotebookCell, NotebookDocument } from "../edit/notebook";
+import type { CustomTool } from "../extensibility/custom-tools/types";
+import { ToolError } from "../tools/tool-errors";
+import type { RlmNotebookWriter } from "./notebook";
+import { synthesizeRlmReport } from "./report";
+import type { RlmArtifactPaths } from "./types";
+
+export const RLM_COMPLETE_RESEARCH_TOOL_NAME = "complete_research";
+
+const paramsSchema = z.object({
+	summary: z
+		.string()
+		.min(1)
+		.describe("Concise final report summary grounded in notebook outputs and cited observations."),
+	final: z
+		.boolean()
+		.optional()
+		.describe("Set false to synthesize a draft report without ending the research session."),
+});
+
+export interface RlmReportWriteInput {
+	paths: RlmArtifactPaths;
+	notebook: RlmNotebookWriter;
+	title: string;
+	summary?: string;
+	dataPath?: string | null;
+}
+
+export interface RlmCompleteResearchContext extends RlmReportWriteInput {
+	minSuccessfulRuns?: number;
+	getGoalStatus?: () => string | undefined;
+	markCompleted?: (summary: string) => void;
+}
+
+function cellText(value: string | string[] | undefined): string {
+	if (value === undefined) return "";
+	return Array.isArray(value) ? value.join("") : value;
+}
+
+function isErrorOutput(output: unknown): boolean {
+	if (!output || typeof output !== "object") return false;
+	const record = output as Record<string, unknown>;
+	return record.output_type === "error" || (record.output_type === "stream" && record.name === "stderr");
+}
+
+function hasAnyOutput(cell: NotebookCell): boolean {
+	return Array.isArray(cell.outputs) && cell.outputs.length > 0;
+}
+
+export function countSuccessfulNotebookRuns(notebook: NotebookDocument): number {
+	return notebook.cells.filter(cell => {
+		if (cell.cell_type !== "code") return false;
+		if (!hasAnyOutput(cell)) return true;
+		return !(cell.outputs ?? []).some(isErrorOutput);
+	}).length;
+}
+
+export function summarizeNotebookForReplay(notebook: NotebookDocument, maxChars: number = 12_000): string {
+	const parts: string[] = [];
+	let codeIndex = 0;
+	for (const cell of notebook.cells) {
+		if (cell.cell_type === "markdown") {
+			const text = cellText(cell.source).trim();
+			if (text.length > 0) parts.push(`Markdown:\n${text}`);
+			continue;
+		}
+		if (cell.cell_type !== "code") continue;
+		codeIndex += 1;
+		const source = cellText(cell.source).trimEnd();
+		const outputs = (cell.outputs ?? [])
+			.map(output => {
+				if (!output || typeof output !== "object") return "";
+				const record = output as Record<string, unknown>;
+				if (record.output_type === "stream")
+					return cellText(record.text as string | string[] | undefined).trimEnd();
+				if (record.output_type === "error") return [record.ename, record.evalue].filter(Boolean).join(": ");
+				return "";
+			})
+			.filter(Boolean)
+			.join("\n");
+		parts.push(
+			[`Cell ${codeIndex}:`, "```python", source, "```", outputs ? `Output:\n${outputs}` : undefined]
+				.filter(Boolean)
+				.join("\n"),
+		);
+	}
+	const text = parts.join("\n\n---\n\n");
+	return text.length > maxChars ? `${text.slice(0, maxChars)}\n\n...[prior notebook replay truncated]` : text;
+}
+
+export async function writeRlmReport(input: RlmReportWriteInput): Promise<string> {
+	await input.notebook.flush();
+	const report = synthesizeRlmReport({
+		title: input.title,
+		summary: input.summary,
+		notebook: input.notebook.document,
+		dataPath: input.dataPath,
+	});
+	await Bun.write(input.paths.reportPath, report);
+	return report;
+}
+
+export function createRlmCompleteResearchTool(context: RlmCompleteResearchContext): CustomTool<typeof paramsSchema> {
+	return {
+		name: RLM_COMPLETE_RESEARCH_TOOL_NAME,
+		label: "Complete Research",
+		description:
+			'Synthesize the RLM report from the live notebook. For final completion, call goal({op:"complete"}) first, then call this tool with final=true (default). Use final=false for a draft /report without ending the session.',
+		parameters: paramsSchema,
+		strict: true,
+		concurrency: "exclusive",
+		async execute(_toolCallId, params) {
+			const final = params.final ?? true;
+			const minRuns = Math.max(0, Math.floor(context.minSuccessfulRuns ?? 0));
+			const successfulRuns = countSuccessfulNotebookRuns(context.notebook.document);
+			if (final && minRuns > 0 && successfulRuns < minRuns) {
+				throw new ToolError(
+					`complete_research requires at least ${minRuns} successful Python run(s); current successful runs: ${successfulRuns}.`,
+				);
+			}
+
+			if (final) {
+				const goalStatus = context.getGoalStatus?.();
+				if (goalStatus !== undefined && goalStatus !== "complete") {
+					throw new ToolError(
+						`complete_research finalization requires goal({op:"complete"}) first; current RLM goal status is ${goalStatus}.`,
+					);
+				}
+			}
+
+			await writeRlmReport({
+				paths: context.paths,
+				notebook: context.notebook,
+				title: context.title,
+				summary: params.summary,
+				dataPath: context.dataPath,
+			});
+
+			if (final) {
+				context.markCompleted?.(params.summary);
+			}
+
+			const action = final ? "Final report synthesized" : "Draft report synthesized";
+			return {
+				content: [
+					{
+						type: "text",
+						text: `${action}: ${context.paths.reportPath}\nSuccessful Python runs: ${successfulRuns}`,
+					},
+				],
+			};
+		},
+	};
+}

package/src/rlm/data-context.ts

@@ -0,0 +1,26 @@
+/**
+ * Optional research data description loading for RLM mode.
+ *
+ * Precedence: an explicit --data <path> (required to exist) overrides the
+ * project-root DATA.md, which auto-loads when present and is silently skipped
+ * when absent.
+ */
+import * as path from "node:path";
+
+export interface RlmDataContext {
+	/** Absolute path the content was loaded from. */
+	path: string;
+	content: string;
+}
+
+export async function loadRlmDataContext(cwd: string, dataFlag: string | undefined): Promise<RlmDataContext | null> {
+	const target = dataFlag ? path.resolve(cwd, dataFlag) : path.join(cwd, "DATA.md");
+	const file = Bun.file(target);
+	if (!(await file.exists())) {
+		if (dataFlag) {
+			throw new Error(`--data file not found: ${target}`);
+		}
+		return null;
+	}
+	return { path: target, content: await file.text() };
+}