Make recall launches explicit and usable

[luckeyfaraday]

Summary

This PR makes the existing project recall feature materially usable from the main Command Room launch flow.

Before this change, Athena could write and display project-local recall, and immersive context bundles could consume it, but the default user path for launching a new agent still ignored recall. That made the recall cache feel like status decoration unless the user happened to use a handoff launch or an explicit MCP immersive path. This PR adds an explicit recall-backed launch path in the app, threads that launch mode through the embedded terminal spawner, and fixes the MCP batch validator so the documented immersive modes actually work.

Concretely, this PR:

• Adds a new Recall launches section to the Command Room New menu.
• Adds one-click recall-backed launches for Athena Code, Codex, OpenCode, Claude, and Grok.
• Keeps the existing clean/default launch entries unchanged.
• Threads contextMode="immersive" from the UI through launchEmbedded() into desktop.spawnEmbeddedTerminal().
• Reuses the existing context-bundle implementation instead of introducing another recall transport.
• Marks recall as used after a successful recall-backed launch, so the existing recall audit metadata becomes meaningful.
• Adjusts the immersive startup prompt so a recall launch without an explicit task reads the context file and then waits for the next user instruction.
• Fixes MCP batch spawning to accept immersive and immersive_curated, matching the documented context modes.
• Updates MCP documentation to describe recall as flowing through explicit immersive bundles rather than stale legacy run artifacts.

Problem

The recall feature had most of the storage and status plumbing, but the common agent launch path did not make that recall useful.

The repo already had:

• .context-workspace/hermes/session-recall.md as a project-local recall cache.
• /hermes/recall/status, /hermes/recall/write, /hermes/recall/refresh, and /hermes/recall/mark-used backend APIs.
• UI surfaces showing whether recall was missing, stale, or fresh.
• A context bundle implementation that can include project instructions, project-scoped Hermes memory, recall, and recent Athena runtime turns.
• A handoff flow that can save generated handoff markdown to recall.

But the normal Command Room flow still launched agents without recall. Starting Codex, OpenCode, Claude, Athena Code, or Grok from the main New menu resulted in a clean/default launch. That is a good default for avoiding hidden context injection, but it also meant that a user could look at a fresh recall cache and still have no obvious way to start an agent that actually used it.

The practical result was exactly the failure mode this PR is meant to address: recall could exist, appear in status panels, and even have audit metadata, while still feeling useless because it was not connected to an obvious launch action.

There was also a second, smaller inconsistency in MCP support. The MCP tool documentation described immersive and immersive_curated context modes, and the low-level terminal spawner supported them, but the batch spawn spec validator rejected those modes. That made the documented MCP batch path weaker than the single-terminal path.

Design Goals

The fix intentionally does not make recall ambient or automatic for every launch.

That is important because recall is short-lived background context. It may be stale, incomplete, or assembled from historical sessions whose current relevance needs to be verified. Automatically injecting it into every new agent session would create a different class of problem: agents could inherit stale context without the user realizing it.

The design goals here are:

1. Make recall usable from the first-class UI path.
2. Preserve clean launches as the default behavior.
3. Use explicit user intent for recall-backed launches.
4. Reuse the existing context bundle path rather than adding another prompt format.
5. Keep recall framed as background context, never as authority over current user instructions.
6. Make audit metadata useful by marking recall as consumed when a recall launch happens.
7. Bring MCP validation in line with the already documented context modes.

User-Facing Behavior

The Command Room New menu now has two functional groups.

The existing Native terminals group remains the normal launch path:

• Shell
• Hermes
• Athena Code
• Athena Code Grid
• Codex
• Codex Grid
• OpenCode
• OpenCode Grid
• Claude
• Claude Grid
• Grok
• Grok Grid

Those entries continue to behave as they did before. They do not automatically attach project recall.

A new Recall launches group appears underneath:

• Athena Code + Recall
• Codex + Recall
• OpenCode + Recall
• Claude + Recall
• Grok + Recall

Those entries request contextMode="immersive". The existing Electron launch path creates an Athena context bundle and passes the spawned agent a startup prompt pointing at the generated context.md file.

When no recall cache exists for the workspace, the recall launch entries are disabled and show No recall cache. This avoids presenting recall as available when Athena has nothing project-local to attach.

When a recall launch succeeds, the app calls /hermes/recall/mark-used, which updates the recall metadata with:

• used_for_launch_at
• last_launch_agent

That means the existing audit display can now answer a real question: has this recall cache actually been used to start an agent?

Context Bundle Behavior

This PR does not invent a new recall prompt shape. Recall launches use the existing immersive context bundle machinery.

For recall-backed launches, the path is:

1. User selects Codex + Recall or another recall launch entry.
2. CommandRoom passes contextMode="immersive" to onLaunch.
3. App.launchEmbedded() forwards that mode to desktop.spawnEmbeddedTerminal().
4. The Electron embedded terminal code sees the immersive mode and creates a context bundle through the backend.
5. The generated launch prompt points the agent at the bundle's context.md.
6. The agent reads the context file as startup context before continuing.

That bundle can include:

• Project instruction files such as AGENTS.md.
• Project-scoped Hermes memory excerpt.
• .context-workspace/hermes/session-recall.md.
• Recent Athena runtime turns.
• Warnings when expected sources are missing.

This is the right existing abstraction for recall-backed launches because the bundle is immutable, bounded, project-local, and already treats recalled material as background data rather than as system authority.

Prompt Behavior Change

The immersive prompt wording is now task-aware.

Before this PR, immersive mode always told the agent:

Read the context file before making decisions.

That was fine when immersive mode was paired with a concrete task, but the new UI recall launch can start an agent with recall context and no specific task. In that case, telling the agent to read context before making decisions is too open-ended: it might infer work that was not requested.

The prompt now branches:

• If a task is present: read the context file before working on the task.
• If no task is present: read the context file as startup context, then wait for the user's next instruction.

That keeps recall useful without encouraging the agent to run ahead of the user.

MCP Behavior Change

context_workspace_spawn_terminals_batch now accepts:

• none
• task
• curated
• immersive
• immersive_curated

Previously, the docs and terminal control path acknowledged immersive modes, but _context_mode_or_none() rejected them for batch specs. This PR fixes that validator and adds a regression test so batch MCP callers can request the same immersive context behavior that single terminal spawns already support.

The MCP README was also corrected. It previously said Context Workspace includes recall in future run context.md files. That is stale for the current architecture: legacy backend run artifacts intentionally do not include recall. The correct path is explicit immersive context bundles.

Why Not Attach Recall Automatically?

This PR keeps the default launch path clean on purpose.

Automatic recall injection would make the feature feel more active, but it would also make it easier for stale or irrelevant history to leak into new sessions. That would be especially risky in a multi-agent workspace where prior sessions may have explored dead ends, operated on different branches, or summarized state that has since changed.

Explicit recall launch entries are a better tradeoff:

• The user can still start a clean agent quickly.
• The user can clearly choose when prior context should be attached.
• The UI makes recall discoverable instead of hiding it behind MCP details.
• The implementation reuses bounded context bundles rather than injecting unbounded memory into prompts.
• Recall audit metadata now reflects real launch usage.

Implementation Details

client/src/rooms/CommandRoom.tsx

• Extends the launch callback signature to accept an optional AgentContextMode.
• Accepts a new recallAvailable prop from the app state.
• Adds a Recall launches menu section beneath the existing launch actions.
• Adds recall launch actions for Athena Code, Codex, OpenCode, Claude, and Grok.
• Disables recall launch actions when no recall cache exists for the active workspace.
• Sends contextMode="immersive" when one of the recall launch actions is selected.

client/src/App.tsx

• Imports AgentContextMode.
• Adds a small isRecallLaunchKind() helper so only coding-agent launches use recall labels/metadata.
• Extends launchEmbedded() to accept and forward contextMode.
• Labels recall launches as <Agent> Recall for a single recall-backed launch.
• Sets the session label to Recall for recall-backed coding-agent launches.
• Forwards contextMode into desktop.spawnEmbeddedTerminal().
• Marks recall as used after a successful immersive coding-agent launch.
• Passes recallAvailable={Boolean(state.recall?.exists)} into CommandRoom.

client/electron/agent-context.ts

• Makes the immersive launch prompt distinguish between task launches and no-task startup context launches.
• Keeps the existing priority rule that current user instructions override recalled material.
• Keeps the bundle as background context, not system/developer authority.

mcp_server/tools.py

• Updates _context_mode_or_none() to accept immersive and immersive_curated for batch specs.

mcp_server/README.md

• Corrects the recall bridge workflow to point at explicit immersive context bundles instead of legacy run context.md files.
• Documents immersive and immersive_curated in the context mode list.

Tests

• Adds an electron prompt test for immersive mode without a task.
• Updates the existing immersive prompt assertion to match the task-aware wording.
• Adds an MCP regression test proving batch spawn accepts context_mode="immersive".

Compatibility

Default launch behavior is preserved.

The existing launch entries still launch clean/default agent sessions. The new behavior is opt-in through the new recall entries or through callers explicitly passing immersive context mode.

Existing handoff launches are also preserved. The handoff flow still uses curated context with the exact preview markdown, which is distinct from this PR's new direct recall launch path.

Legacy backend run artifacts remain unchanged and still do not include recall. That is intentional and now documented more accurately.

Risks And Tradeoffs

Stale recall can still be launched if it exists

The UI enables recall launches when a recall cache exists. It does not require the recall status to be fresh.

That is a deliberate tradeoff for now. A stale handoff may still be useful as orientation, especially when refresh is not configured. The prompt and bundle wording continue to frame recall as background context, and current user instructions remain authoritative.

A future refinement could add stronger stale-state UI, such as showing Stale recall in the menu item detail or requiring a refresh when refresh_configured is true.

The New menu is longer

The Command Room launch menu now has an additional section. This makes recall discoverable but increases menu height.

The new entries are grouped under a section header to keep the distinction clear: normal launches are still normal launches, recall launches are explicit context launches.

Mark-used failures are non-critical

The launch itself is the important operation. If the follow-up markRecallUsed request fails, the agent may still have launched successfully. The app surfaces the error through existing error handling, but the launch path does not rely on the audit metadata write to create the terminal.

Validation

Ran the following checks on fix/recall-launches-use-cache after moving the work onto a branch based directly on main:

pytest tests/test_mcp_server.py tests/test_context_bundle.py tests/test_context_artifacts.py -q

Result: 43 passed

npm run build

Result: TypeScript, Vite build, and Electron TypeScript build completed successfully. Vite still reports the existing large chunk warning for index-*.js; this PR does not change that packaging characteristic.

npm run test:chat

Result: 25 passed

npm run test:electron

Result: 164 passed

Also attempted npm test -- --runInBand, but this package has no generic test script, so the repo-specific scripts above were used instead.

Manual Review Notes

The most important manual review path is:

1. Open Athena with a workspace that has a recall cache at .context-workspace/hermes/session-recall.md.
2. Open the Command Room.
3. Open the New menu.
4. Confirm the existing normal launch entries remain available.
5. Confirm the new Recall launches section appears.
6. Click Codex + Recall or another recall-backed agent entry.
7. Confirm Athena creates an immersive context bundle under .context-workspace/context/ctx_.../.
8. Confirm the spawned agent's launch prompt points at that bundle's context.md.
9. Confirm recall metadata updates with used_for_launch_at and last_launch_agent.

For a workspace without recall:

1. Open the Command Room.
2. Open the New menu.
3. Confirm recall launch entries are disabled and show No recall cache.

Follow-Up Ideas

This PR makes recall usable, but there are still sensible next steps:

• Show fresh/stale/missing directly in the recall launch menu item detail.
• Offer a one-click Refresh then launch with recall flow when refresh is configured.
• Add an in-app recall preview/read action next to the launch actions.
• Add telemetry or local diagnostics for context bundle creation failures.
• Consider a first-run explanation for why recall launches are explicit instead of default.