@robota-sdk/agent-command 3.0.0-beta.81 → 3.0.0-beta.83

package/src/handoff/handoff-command-module.ts

@@ -7,13 +7,14 @@ export function createHandoffCommandEntry(): ICommand {
   return {
     name: 'handoff',
     displayName: 'Hand off',
-    description: 'Move this session to another machine, after confirming what stays behind',
+    description:
+      "Push this conversation to another running Robota session of the same user on this machine, or to another of the user's devices linked over the device mesh, after the operator confirms what stays behind (uncommitted changes, running processes; credentials never travel). The receiving operator must also accept; the session arrives saved, not started, and this one ends once it is saved there. With no argument it lists the sessions and devices it could go to. User-only: the model cannot run it; when the user wants to continue this work in another session or on another device, suggest they run `/handoff <session-or-device-id>`.",
     source: 'handoff',
-    // The model does not decide to give this session away. A hand-off moves AUTHORITY over the
-    // operator's work to a different computer — it is a decision about where the person is sitting,
-    // which is a fact about them and not about the task.
-    // User-only: moves the session to another machine; the user decides where it lives.
+    // User-only: a hand-off moves authority over the operator's work to another place, a decision
+    // about where the person is, not about the task.
     modelInvocable: false,
+    userInvocable: true,
+    argumentHint: '[session-id]',
   };
 }
 

package/src/handoff/handoff-command.ts

@@ -33,7 +33,7 @@ type THandoffHost = ICommandHostAdapterAccess & Partial<ICommandHostUserInteract
 function whereIsIt(progress: IHandoffProgress): string {
   return progress.stillMine
     ? 'This session is still on this machine, and still yours to use.'
-    : 'This session now belongs to the destination. This copy is read-only.';
+    : 'This session now belongs to the destination, and this one ends.';
 }
 
 function describeDestinations(
@@ -47,8 +47,8 @@ function usage(): ICommandResult {
     success: true,
     message: [
       'Usage:',
-      '  /handoff              list the machines this session could move to',
-      '  /handoff <device-id>  move it there, after confirming what stays behind',
+      '  /handoff                         list where this session could move to',
+      '  /handoff <session-or-device-id>  move it there, after confirming what stays behind',
     ].join('\n'),
   };
 }
@@ -153,7 +153,7 @@ export async function executeHandoffCommand(
     message: [
       ...progressLines,
       final.state === 'done'
-        ? `Hand-off complete. ${target} is running this session now.`
+        ? `Hand-off complete. ${target} saved this session and has not started it; resume it there.`
         : `Hand-off stopped: ${final.reason ?? 'no reason was reported'}.`,
       whereIsIt(final),
     ].join('\n'),

package/src/help/__tests__/help-command-module.test.ts

@@ -55,12 +55,14 @@ function createCommandHostContext() {
           displayName: 'Help',
           description: 'Show available commands',
           modelInvocable: true,
+          runner: 'runtime',
         },
         {
           name: 'provider',
           displayName: 'Provider Setup',
           description: 'Manage provider profiles',
           modelInvocable: true,
+          runner: 'runtime',
         },
         // SEC-008: `plugin` installs and enables code, so it is NOT model-invocable — the fixture says
         // what the real command says rather than the value that happened to compile.
@@ -69,6 +71,7 @@ function createCommandHostContext() {
           displayName: 'Plugins',
           description: 'Manage plugins',
           modelInvocable: false,
+          runner: 'runtime',
         },
       ],
       listEditCheckpoints: () => [],

package/src/help/__tests__/help-command.test.ts

@@ -86,6 +86,7 @@ describe('formatCommandHelpMessage — example field', () => {
         description: 'Compress context window',
         example: '/compact Summarize the current context',
         modelInvocable: true,
+        runner: 'runtime',
       },
     ]);
 
@@ -102,6 +103,7 @@ describe('formatCommandHelpMessage — example field', () => {
         description: 'Manage provider profiles',
         example: '/provider switch production',
         modelInvocable: true,
+        runner: 'runtime',
       },
     ]);
 
@@ -117,6 +119,7 @@ describe('formatCommandHelpMessage — example field', () => {
         displayName: 'Help',
         description: 'Show available commands',
         modelInvocable: true,
+        runner: 'runtime',
       },
     ]);
 

package/src/index.ts

@@ -79,8 +79,11 @@ export {
   type IDeviceListEntry,
   type IDevicesCommandPort,
   type IDevicesInitResult,
+  type IDevicesAddResult,
+  type IDevicesJoinResult,
   type IDevicesRecoverResult,
   type IDevicesRevokeResult,
+  type IDevicesMeshStatus,
   type IDevicesView,
   type TDevicesOutcome,
   type TDevicesRefusal,
@@ -146,4 +149,9 @@ export * from './session/index.js';
 export * from './settings/index.js';
 export * from './skills/index.js';
 export * from './statusline/index.js';
+export {
+  createTerminalClientCommands,
+  type ITerminalClientCommand,
+  type ITerminalClientCommandOptions,
+} from './terminal-client/index.js';
 export * from './user-local/index.js';

package/src/keybindings/keybindings-command-module.ts

@@ -21,13 +21,23 @@ export function createKeybindingsCommandEntry(): ICommand {
     source: 'keybindings',
     // User-only: UI preference.
     modelInvocable: false,
+    // Key bindings belong to the terminal the user sits at, so that terminal runs it, even when
+    // attached.
+    runner: 'client',
+    surfaces: ['terminal'],
   };
 }
 
-async function executeKeybindingsCommand(
-  file: IKeybindingsFilePort,
+// A host without a terminal (the desktop app's sidecar) still answers, so the command is never
+// "unknown" there — it says where key bindings live instead.
+const KEYBINDINGS_UNAVAILABLE =
+  'Key bindings belong to the robota terminal, and this surface has none. Run /keybindings in the robota terminal.';
+
+export async function executeKeybindingsCommand(
+  file: IKeybindingsFilePort | undefined,
   context: ICommandHostTerminalHandoff & ICommandHostWorkspace,
 ): Promise<ICommandResult> {
+  if (!file) return { success: false, message: KEYBINDINGS_UNAVAILABLE };
   if (!context.canHandoffTerminal()) {
     return { success: false, message: 'Keybindings editor is unavailable here.' };
   }
@@ -54,7 +64,9 @@ export class KeybindingsCommandSource implements ICommandSource {
   }
 }
 
-export function createKeybindingsCommandModule(file: IKeybindingsFilePort): ICommandModule {
+export function createKeybindingsCommandModule(
+  file: IKeybindingsFilePort | undefined,
+): ICommandModule {
   const entry = createKeybindingsCommandEntry();
   const command: ISystemCommand = {
     name: entry.name,
@@ -63,6 +75,8 @@ export function createKeybindingsCommandModule(file: IKeybindingsFilePort): ICom
     requiresPermission: false,
     userInvocable: true,
     modelInvocable: false,
+    runner: entry.runner,
+    surfaces: entry.surfaces,
     lifecycle: 'inline',
     execute: (context) => executeKeybindingsCommand(file, context),
   };

package/src/mcp-activation/__tests__/mcp-activation-command.test.ts

@@ -484,6 +484,47 @@ describe('/mcp login', () => {
     expect(h.added).toEqual([]);
   });
 
+  it('asks nothing for a sign-in that has already ended', async () => {
+    const ended = new AbortController();
+    ended.abort();
+    let choice: string | undefined;
+    const h = harness(
+      async (request) => {
+        choice = await request.confirmBrowser!(PROMPT, ended.signal);
+        await expect(request.readRedirect!(PROMPT, ended.signal)).rejects.toThrow();
+        return {
+          serverId: request.serverId,
+          failure: 'cancelled',
+          preRegisteredClient: false,
+          tools: [],
+        };
+      },
+      { type: 'answer', values: ['open'], text: 'http://127.0.0.1:1/callback?code=c&state=s' },
+    );
+    await h.run('login files');
+    expect(choice).toBe('cancel');
+    expect(h.asked).toEqual([]);
+  });
+
+  it('never opens the browser for a sign-in that ended while the user was choosing', async () => {
+    const signIn = new AbortController();
+    let choice: string | undefined;
+    const h = harness(
+      async (request) => {
+        choice = await request.confirmBrowser!(PROMPT, signIn.signal);
+        return signedIn(request.serverId);
+      },
+      () => {
+        // The sign-in times out while the question is still open; the user then picks `open`.
+        signIn.abort();
+        return { type: 'answer', values: ['open'] };
+      },
+    );
+    await h.run('login files');
+    expect(h.asked).toHaveLength(1);
+    expect(choice).toBe('cancel');
+  });
+
   it('never asks for a client secret, and names the terminal command instead', async () => {
     const h = harness(async (request) => signedIn(request.serverId));
     const result = await h.run('login files --client-secret');

package/src/mcp-activation/mcp-activation-command.ts

@@ -259,7 +259,10 @@ function browserConfirmer(
 ): ICommandMCPOAuthLoginRequest['confirmBrowser'] {
   const ui = context.getUserInteraction();
   if (ui === undefined) return undefined;
-  return async (prompt) => {
+  return async (prompt, signal) => {
+    // The ask port cannot withdraw a question, so a sign-in that has already ended is not asked
+    // about, and an answer that arrives after it ended never opens a browser for it.
+    if (signal.aborted) return 'cancel';
     loginPrompts += 1;
     const answer = await ui.ask({
       id: `mcp-login-browser-${loginPrompts}`,
@@ -275,7 +278,7 @@ function browserConfirmer(
       maxSelect: 1,
       default: { values: ['open'] },
     });
-    if (answer.type !== 'answer') return 'cancel';
+    if (answer.type !== 'answer' || signal.aborted) return 'cancel';
     const choice = answer.values[0];
     return choice === 'open' || choice === 'paste' ? choice : 'cancel';
   };
@@ -288,7 +291,9 @@ function redirectReader(
 ): ICommandMCPOAuthLoginRequest['readRedirect'] {
   const ui = context.getUserInteraction();
   if (ui === undefined) return undefined;
-  return async (prompt) => {
+  return async (prompt, signal) => {
+    // A sign-in that has already ended (cancelled or timed out) does not ask for a paste.
+    signal.throwIfAborted();
     loginPrompts += 1;
     const answer = await ui.ask({
       id: `mcp-login-redirect-${loginPrompts}`,

package/src/peers/__tests__/peers-command-module.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+
+import { createPeersCommandModule } from '../peers-command-module.js';
+
+describe('/peers command module', () => {
+  it('is user-only: never model-invocable, and palette metadata matches the executable', () => {
+    const module = createPeersCommandModule();
+    const palette = module.commandSources?.[0]?.getCommands()[0];
+    const executable = module.systemCommands?.[0];
+    expect(executable?.modelInvocable).toBe(false);
+    expect(palette?.modelInvocable).toBe(false);
+    expect(executable?.userInvocable).toBe(true);
+    expect(executable?.description).toBe(palette?.description);
+  });
+
+  it('tells the model it covers linked devices, what it returns, and what to suggest', () => {
+    const description =
+      createPeersCommandModule().commandSources?.[0]?.getCommands()[0]?.description;
+    expect(description).toMatch(/linked over the device mesh/);
+    expect(description).toMatch(/returns/i);
+    expect(description).toMatch(/user-only/i);
+    expect(description).toContain('`/peers`');
+  });
+});

package/src/peers/__tests__/peers-command.test.ts

@@ -142,6 +142,84 @@ describe('what the operator is told', () => {
   });
 });
 
+describe('linked devices of the device mesh', () => {
+  const DEVICE = 'D'.repeat(43);
+
+  function hostWithDevices(
+    peers: readonly TPeerSummary[],
+    devices: readonly { deviceId: string; name?: string; locality: 'same-host' | 'another-host' }[],
+  ): ICommandHostAdapterAccess {
+    return {
+      getCommandHostAdapters: () => ({
+        localPeers: { list: () => peers, ownSessionId: () => OWN, listDevices: () => devices },
+      }),
+    } as ICommandHostAdapterAccess;
+  }
+
+  it('lists a linked device beside the sessions on this host, addressable by its id', async () => {
+    const result = await executePeersCommand(
+      hostWithDevices(
+        [
+          { sessionId: OWN, liveness: 'alive' },
+          { sessionId: 'session-other', liveness: 'alive' },
+        ],
+        [{ deviceId: DEVICE, name: 'desktop', locality: 'another-host' }],
+      ),
+    );
+    expect(result.success).toBe(true);
+    expect(result.message).toContain('session-other');
+    expect(result.message).toMatch(new RegExp(`${DEVICE}\\s+desktop\\s+on another machine`));
+    expect(result.message).toContain('/peers send <session-or-device-id>');
+  });
+
+  it('lists a linked device even when this is the only session on this host', async () => {
+    const result = await executePeersCommand(
+      hostWithDevices(
+        [{ sessionId: OWN, liveness: 'alive' }],
+        [{ deviceId: DEVICE, locality: 'same-host' }],
+      ),
+    );
+    expect(result.message).not.toContain('No other live session');
+    expect(result.message).toMatch(new RegExp(`${DEVICE}\\s+on this machine`));
+  });
+});
+
+describe('when local discovery is off but the device mesh is not', () => {
+  const DEVICE = 'D'.repeat(43);
+
+  function hostWithoutDiscovery(
+    devices: readonly { deviceId: string; name?: string; locality: 'same-host' | 'another-host' }[],
+  ): ICommandHostAdapterAccess {
+    return {
+      getCommandHostAdapters: () => ({
+        localPeers: {
+          list: () => [],
+          ownSessionId: () => OWN,
+          listDevices: () => devices,
+          localDiscoveryOff: 'the rendezvous directory was not admitted',
+        },
+      }),
+    } as ICommandHostAdapterAccess;
+  }
+
+  it('lists the linked devices and says why sessions on this host are not listed', async () => {
+    const result = await executePeersCommand(
+      hostWithoutDiscovery([{ deviceId: DEVICE, name: 'desktop', locality: 'another-host' }]),
+    );
+    expect(result.success).toBe(true);
+    expect(result.message).toMatch(new RegExp(`${DEVICE}\\s+desktop\\s+on another machine`));
+    expect(result.message).toContain('not admitted');
+    expect(result.message).not.toContain('Live sessions');
+    expect(result.message).toContain('/peers send <device-id>');
+  });
+
+  it('with no device linked, says discovery is off rather than that nobody is there', async () => {
+    const result = await executePeersCommand(hostWithoutDiscovery([]));
+    expect(result.message).toContain('not admitted');
+    expect(result.message).not.toContain('No other live session');
+  });
+});
+
 describe('when the host wires no discovery', () => {
   it('says the feature is unavailable rather than reporting no peers', async () => {
     // The two are different facts and the difference matters: "nobody is there" invites the operator
@@ -239,3 +317,83 @@ describe('PEER-006 — /peers send', () => {
     expect(result.success).toBe(false);
   });
 });
+
+describe('/peers send-file', () => {
+  type TPrepareFile = NonNullable<NonNullable<ICommandHostAdapters['localPeers']>['prepareFile']>;
+
+  function hostWithFiles(prepareFile: TPrepareFile): ICommandHostAdapterAccess {
+    return {
+      getCwd: () => '/work',
+      getCommandHostAdapters: () => ({
+        localPeers: {
+          list: () => [{ sessionId: 'other', liveness: 'alive' as const }],
+          ownSessionId: () => OWN,
+          prepareFile,
+        },
+      }),
+    } as unknown as ICommandHostAdapterAccess;
+  }
+
+  it('sends the named file as the operator, spaces in the path and all', async () => {
+    const calls: unknown[] = [];
+    const result = await executePeersCommand(
+      hostWithFiles(async (target, path, options) => {
+        calls.push([target, path, options]);
+        return {
+          ok: true,
+          file: {
+            path: '/work/my notes.txt',
+            size: 5,
+            sha256: 'e'.repeat(64),
+            send: async () => ({ state: 'delivered' }),
+          },
+        };
+      }),
+      'send-file other my notes.txt',
+    );
+
+    expect(calls).toEqual([['other', 'my notes.txt', { origin: 'operator', cwd: '/work' }]]);
+    expect(result.success).toBe(true);
+    expect(result.message).toContain(`5 bytes, sha256 ${'e'.repeat(64)}`);
+  });
+
+  it('carries a refusal back to the operator', async () => {
+    const result = await executePeersCommand(
+      hostWithFiles(async () => ({
+        ok: true,
+        file: {
+          path: '/work/a.txt',
+          size: 1,
+          sha256: 'e'.repeat(64),
+          send: async () => ({ state: 'refused', reason: 'the receiving side did not accept it' }),
+        },
+      })),
+      'send-file other a.txt',
+    );
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('did not accept it');
+  });
+
+  it('says what it needs when the path is missing', async () => {
+    const result = await executePeersCommand(
+      hostWithFiles(async () => ({ ok: false, reason: 'unused' })),
+      'send-file other',
+    );
+    expect(result.message).toContain('Usage: /peers send-file');
+    expect(result.success).toBe(false);
+  });
+
+  it('says so when the host cannot send files', async () => {
+    const result = await executePeersCommand(
+      {
+        getCommandHostAdapters: () => ({
+          localPeers: { list: () => [], ownSessionId: () => OWN },
+        }),
+      } as ICommandHostAdapterAccess,
+      'send-file other a.txt',
+    );
+    expect(result.message).toContain('cannot send files');
+    expect(result.success).toBe(false);
+  });
+});

package/src/peers/peers-command-module.ts

@@ -7,11 +7,13 @@ export function createPeersCommandEntry(): ICommand {
   return {
     name: 'peers',
     displayName: 'Peers',
-    description: 'List the other live sessions on this host, or send one a message',
+    description:
+      "List the other live Robota sessions on this host and the user's other devices linked over the device mesh, send one a message, or send one a copy of a file. Returns the sessions and devices with the ids to address them by (linked devices even when local discovery is off and sessions on this host cannot be listed), or how a send ended. User-only: the model cannot run it; it answers a peer's message with its reply tool, and when the user wants to reach another session or device, suggest they run `/peers`.",
     source: 'peers',
     // The model does not enumerate the operator's other sessions. Discovery is an operator-facing
     // view of who is at the machine, which is a fact about the person and not about the task.
-    // User-only: sends messages into other sessions; crossing a session boundary is the user's call.
+    // User-only: sends messages and files into other sessions; crossing a session boundary is the
+    // user's call. The model sends a file only through `peer_send_file`, which asks every time.
     modelInvocable: false,
   };
 }

package/src/peers/peers-command.ts

@@ -33,6 +33,16 @@ function describe(peer: TPeerSummary, ownSessionId: string): string {
   return `  ${peer.sessionId}${peer.name ? `  ${peer.name}` : ''}  status ${status}${self ? '' : workspace(peer)}${liveness}${self}`;
 }
 
+type TDeviceSummary = ReturnType<
+  NonNullable<NonNullable<ICommandHostAdapters['localPeers']>['listDevices']>
+>[number];
+
+/** A linked device: its full id, since that is what `send` takes, and where it runs. */
+function describeDevice(device: TDeviceSummary): string {
+  const where = device.locality === 'same-host' ? 'on this machine' : 'on another machine';
+  return `  ${device.deviceId}${device.name ? `  ${device.name}` : ''}  ${where}`;
+}
+
 /** The relation this session verified. A claim it could not confirm is named as such, not shown. */
 function workspace(peer: TPeerSummary): string {
   if (peer.workspaceClaim === 'mismatched') return '  workspace claim mismatched, not believed';
@@ -103,8 +113,47 @@ async function executeSend(
   return describeSend(await adapter.send(parsed.target, parsed.text), parsed.target);
 }
 
+/**
+ * `/peers send-file <session-id> <path>` — the operator sends a copy of a file.
+ *
+ * The operator typed the path, so any regular file they can read may go, including one outside the
+ * workspace or one that looks like it holds secrets: this is the one way to send those. Everything
+ * after the session id is the path, spaces and all.
+ */
+async function executeSendFile(
+  adapter: NonNullable<ICommandHostAdapters['localPeers']>,
+  args: string,
+  cwd: string,
+): Promise<ICommandResult> {
+  if (adapter.prepareFile === undefined) {
+    return { message: 'This environment cannot send files to other sessions.', success: false };
+  }
+  const parsed = parseSend(args);
+  if (parsed === undefined) {
+    return {
+      message: 'Usage: /peers send-file <session-id> <path>. Run /peers for the session ids.',
+      success: false,
+    };
+  }
+  const prepared = await adapter.prepareFile(parsed.target, parsed.text, {
+    origin: 'operator',
+    cwd,
+  });
+  if (!prepared.ok) return { message: `Not sent: ${prepared.reason}`, success: false };
+  const { file } = prepared;
+  const result = await file.send();
+  if (result.state === 'delivered' || result.state === 'acknowledged') {
+    return {
+      message: `Sent ${file.path} to ${parsed.target}: ${file.size} bytes, sha256 ${file.sha256}.`,
+      success: true,
+    };
+  }
+  const reason = result.reason !== undefined ? ` ${result.reason}` : '';
+  return { message: `${file.path} was not sent to ${parsed.target}.${reason}`, success: false };
+}
+
 export async function executePeersCommand(
-  context: ICommandHostAdapterAccess,
+  context: ICommandHostAdapterAccess & { getCwd?(): string },
   args = '',
 ): Promise<ICommandResult> {
   const adapter = context.getCommandHostAdapters?.().localPeers;
@@ -115,9 +164,32 @@ export async function executePeersCommand(
   // `send` must be a WHOLE word: `startsWith('send')` would also claim a session id beginning with
   // those four letters, and a uuid that happens to start `send…` is not a subcommand.
   const trimmed = args.trim();
+  const sendFileVerb = /^send-file(?=\s|$)/.exec(trimmed);
+  if (sendFileVerb !== null) {
+    return executeSendFile(
+      adapter,
+      trimmed.slice(sendFileVerb[0].length),
+      context.getCwd?.() ?? '',
+    );
+  }
   const sendVerb = /^send(?=\s|$)/.exec(trimmed);
   if (sendVerb !== null) return executeSend(adapter, trimmed.slice(sendVerb[0].length));
 
+  const devices = adapter.listDevices?.() ?? [];
+  const discoveryOff = adapter.localDiscoveryOff;
+  if (discoveryOff !== undefined) {
+    const off = `Sessions on this host are not listed: local peer discovery is off for this session (${discoveryOff}).`;
+    return {
+      message:
+        devices.length === 0
+          ? `${off}\nNo device is linked right now.`
+          : `Linked devices:\n${devices.map(describeDevice).join('\n')}\n\n${off}` +
+            `\n\nSend to one: /peers send <device-id> <message>` +
+            `\nSend a file: /peers send-file <device-id> <path>`,
+      success: true,
+    };
+  }
+
   const own = adapter.ownSessionId();
   // The workspace-judged listing when the host has one; it reads git, so only this view asks for it.
   const peers = (
@@ -125,7 +197,7 @@ export async function executePeersCommand(
   ).filter(addressable);
   const others = peers.filter((peer) => peer.sessionId !== own);
 
-  if (others.length === 0) {
+  if (others.length === 0 && devices.length === 0) {
     return {
       message:
         'No other live session is announced. Start a second session on this host, as this user, ' +
@@ -134,9 +206,15 @@ export async function executePeersCommand(
     };
   }
 
-  const lines = peers.map((peer) => describe(peer, own));
+  const sections = [`Live sessions:\n${peers.map((peer) => describe(peer, own)).join('\n')}`];
+  if (devices.length > 0) {
+    sections.push(`Linked devices:\n${devices.map(describeDevice).join('\n')}`);
+  }
+  const target = devices.length > 0 ? '<session-or-device-id>' : '<session-id>';
   return {
-    message: `Live sessions:\n${lines.join('\n')}\n\nSend to one: /peers send <session-id> <message>`,
+    message:
+      `${sections.join('\n\n')}\n\nSend to one: /peers send ${target} <message>` +
+      `\nSend a file: /peers send-file ${target} <path>`,
     success: true,
   };
 }

package/src/rewind/__tests__/rewind-command-module.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it, vi } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import type {
   IEditCheckpointInspection,
   IEditCheckpointRestoreResult,
@@ -252,4 +252,34 @@ describe('executeRewindCommand', () => {
     expect(result?.success).toBe(false);
     expect(result?.message).toBe('Unknown edit checkpoint');
   });
+
+  describe('in a session built without a checkpoint store', () => {
+    afterEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    it('tells a restricted workspace to trust it, for every subcommand', async () => {
+      vi.spyOn(process, 'platform', 'get').mockReturnValue('linux');
+      const session = createInteractiveSession();
+
+      for (const args of ['', 'list', 'inspect turn-0001', 'restore turn-0001', 'branches']) {
+        const result = await session.executeCommand('rewind', args);
+        expect(result?.success).toBe(false);
+        expect(result?.message).toBe(
+          'Edit checkpoints need a trusted workspace: run robota trust --yes, then restart robota.',
+        );
+      }
+    });
+
+    it('says why on a host that cannot prove a project write is safe, without naming trust', async () => {
+      vi.spyOn(process, 'platform', 'get').mockReturnValue('darwin');
+      const session = createInteractiveSession();
+
+      const result = await session.executeCommand('rewind', 'list');
+
+      expect(result?.success).toBe(false);
+      expect(result?.message).toContain('cannot prove a write stays inside the project');
+      expect(result?.message).not.toContain('trust');
+    });
+  });
 });

package/src/rewind/rewind-command.ts

@@ -1,4 +1,5 @@
 import {
+  EditCheckpointsUnavailableError,
   inspectCommandEditCheckpoint,
   listCommandEditCheckpoints,
   restoreCommandEditCheckpoint,
@@ -121,13 +122,33 @@ function formatRollbackResult(result: IEditCheckpointRestoreResult): ICommandRes
   };
 }
 
+/** A restricted workspace is the one case the user fixes with a command; the rest say why. */
+function unavailableMessage(error: EditCheckpointsUnavailableError): string {
+  return error.reason === 'restricted-workspace'
+    ? 'Edit checkpoints need a trusted workspace: run robota trust --yes, then restart robota.'
+    : error.message;
+}
+
 function formatError(error: Error | string): ICommandResult {
   return {
-    message: error instanceof Error ? error.message : String(error),
+    message:
+      error instanceof EditCheckpointsUnavailableError
+        ? unavailableMessage(error)
+        : error instanceof Error
+          ? error.message
+          : String(error),
     success: false,
   };
 }
 
+function list(context: ICommandHostCheckpoints): ICommandResult {
+  try {
+    return formatList(listCommandEditCheckpoints(context));
+  } catch (error) {
+    return formatError(error instanceof Error ? error : String(error));
+  }
+}
+
 function inspect(
   context: ICommandHostCheckpoints,
   checkpointId: string | undefined,
@@ -222,7 +243,7 @@ export async function executeRewindCommand(
   const subcommand = args[SUBCOMMAND_INDEX] ?? 'list';
 
   if (subcommand === 'list') {
-    return formatList(listCommandEditCheckpoints(context));
+    return list(context);
   }
 
   if (subcommand === 'inspect') {