@robota-sdk/agent-command 3.0.0-beta.82 → 3.0.0-beta.84

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

@@ -44,7 +44,12 @@ function fakePort(): IDevicesCommandPort & { calls: string[] } {
       calls.push(`init:${options.name ?? ''}`);
       return {
         ok: true as const,
-        value: { userId: USER, deviceId: DEVICE_A, signingKeyId: SIGNING, keyStorage: 'OS keychain' },
+        value: {
+          userId: USER,
+          deviceId: DEVICE_A,
+          signingKeyId: SIGNING,
+          keyStorage: 'OS keychain',
+        },
       };
     }),
     recover: vi.fn(async () => {
@@ -63,6 +68,20 @@ function fakePort(): IDevicesCommandPort & { calls: string[] } {
       calls.push(`revoke:${target}`);
       return { ok: true as const, value: { deviceId: DEVICE_B, name: 'desktop' } };
     }),
+    add: vi.fn(async () => {
+      calls.push('add');
+      return {
+        ok: true as const,
+        value: { deviceId: DEVICE_B, name: 'desktop', confirmed: true },
+      };
+    }),
+    join: vi.fn(async (options) => {
+      calls.push(`join:${options.name ?? ''}`);
+      return {
+        ok: true as const,
+        value: { userId: USER, deviceId: DEVICE_B, name: 'desktop', keyStorage: 'OS keychain' },
+      };
+    }),
   };
 }
 
@@ -105,7 +124,19 @@ describe('/devices command', () => {
       'init',
       'revoke',
       'recover',
+      'add',
+      'join',
     ]);
+    // What the model reads names the one-time code as terminal-only, so it never asks for it.
+    expect(palette?.description).toMatch(/enrol/i);
+    expect(palette?.description).toMatch(/terminal/i);
+  });
+
+  it('tells the model it also shows the device mesh status', () => {
+    const description =
+      createDevicesCommandModule(fakePort()).commandSources?.[0]?.getCommands()[0]?.description;
+    expect(description).toMatch(/device mesh/);
+    expect(description).toMatch(/Operator-only/);
   });
 
   it('lists the roster with short ids, this device, the signing-key holder and expiry', async () => {
@@ -125,6 +156,17 @@ describe('/devices command', () => {
     vi.mocked(port.list).mockResolvedValueOnce(undefined);
     const result = await start(port).command('devices', 'list');
     expect(result?.message).toMatch(/\/devices init/);
+    // A device of a user who already has others joins them; `init` would never link to them.
+    expect(result?.message).toMatch(/\/devices join/);
+    expect(result?.message).toMatch(/separate identity/);
+  });
+
+  it('describes init as for the first device, and join as the way to the devices a user has', () => {
+    const entry = createDevicesCommandModule(fakePort()).commandSources?.[0]?.getCommands()[0];
+    const init = entry?.subcommands?.find((sub) => sub.name === 'init');
+    expect(init?.description).toMatch(/first device/);
+    expect(init?.description).toMatch(/separate identity/);
+    expect(entry?.description).toMatch(/separate identity/);
   });
 
   it('runs init, recover and revoke on the operator terminal', async () => {
@@ -156,7 +198,7 @@ describe('/devices command', () => {
   it('refuses without an interactive terminal and never reaches the port (fail closed)', async () => {
     const port = fakePort();
     const harness = start(port, handoff(false));
-    for (const args of ['init', 'recover', 'revoke abcdef']) {
+    for (const args of ['init', 'recover', 'revoke abcdef', 'add', 'join', 'join desktop']) {
       const result = await harness.command('devices', args);
       expect(result?.success).toBe(false);
       expect(result?.message).toMatch(/interactive terminal/i);
@@ -167,15 +209,17 @@ describe('/devices command', () => {
   it('refuses a model invocation', async () => {
     const port = fakePort();
     const harness = start(port);
-    const result = await harness.session.executeModelCommand('devices', 'init');
-    expect(result?.success ?? false).toBe(false);
+    for (const args of ['init', 'add', 'join']) {
+      const result = await harness.session.executeModelCommand('devices', args);
+      expect(result?.success ?? false).toBe(false);
+    }
     expect(port.calls).toEqual([]);
   });
 
   it('refuses every verb from a remote surface', async () => {
     const port = fakePort();
     const harness = start(port);
-    for (const args of ['', 'init', 'recover', 'revoke abcdef']) {
+    for (const args of ['', 'init', 'recover', 'revoke abcdef', 'add', 'join']) {
       const result = await harness.session.executeCommand('devices', args, 'remote');
       expect(result?.success).toBe(false);
       expect(result?.message).toMatch(/operator/i);
@@ -183,15 +227,58 @@ describe('/devices command', () => {
     expect(port.calls).toEqual([]);
   });
 
-  it('names add and join as not yet available rather than guessing', async () => {
+  it('shows the device mesh: whether it is on, how it finds devices, and what is linked', async () => {
+    const port = {
+      ...fakePort(),
+      meshStatus: () => ({
+        state: 'on' as const,
+        sources: ['local network (mDNS)', 'Mainline DHT'],
+        linked: [{ deviceId: DEVICE_B, name: 'desktop', locality: 'another-host' as const }],
+      }),
+    };
+    const result = await start(port).command('devices', '');
+    expect(result?.message).toMatch(/Device mesh: on/);
+    expect(result?.message).toContain('local network (mDNS), Mainline DHT');
+    expect(result?.message).toMatch(
+      new RegExp(`${DEVICE_B.slice(0, 10)}\\s+desktop\\s+on another machine`),
+    );
+  });
+
+  it('says how to turn the device mesh on when it is off', async () => {
+    const port = {
+      ...fakePort(),
+      meshStatus: () => ({ state: 'off' as const, sources: [], linked: [] }),
+    };
+    const result = await start(port).command('devices', 'list');
+    expect(result?.message).toMatch(/Device mesh: off/);
+    expect(result?.message).toContain('transports.mesh.enabled');
+  });
+
+  it('runs add and join on the operator terminal and reports ids and names only', async () => {
+    const port = fakePort();
+    const runs = vi.fn();
+    const harness = start(port, handoff(true, runs));
+    const add = await harness.command('devices', 'add');
+    expect(add?.success).toBe(true);
+    expect(add?.message).toContain('desktop');
+    expect(add?.message).toContain(DEVICE_B.slice(0, 10));
+    const join = await harness.command('devices', 'join my desktop');
+    expect(join?.success).toBe(true);
+    expect(join?.message).toContain(DEVICE_B.slice(0, 10));
+    expect(join?.message).toContain('OS keychain');
+    expect(port.calls).toEqual(['add', 'join:my desktop']);
+    expect(runs).toHaveBeenCalledTimes(2);
+  });
+
+  it('says what to do when an enrollment is refused', async () => {
     const port = fakePort();
     const harness = start(port);
-    for (const args of ['add', 'join abc']) {
-      const result = await harness.command('devices', args);
-      expect(result?.success).toBe(false);
-      expect(result?.message).toMatch(/not available yet/i);
-    }
-    expect(port.calls).toEqual([]);
+    vi.mocked(port.join).mockResolvedValueOnce({ ok: false, reason: 'code-not-accepted' });
+    expect((await harness.command('devices', 'join'))?.message).toMatch(/devices add/);
+    vi.mocked(port.add).mockResolvedValueOnce({ ok: false, reason: 'no-relay' });
+    expect((await harness.command('devices', 'add'))?.message).toMatch(/relayUrl/);
+    vi.mocked(port.join).mockResolvedValueOnce({ ok: false, reason: 'code-on-command-line' });
+    expect((await harness.command('devices', 'join ABCDE'))?.message).toMatch(/devices add/);
   });
 
   it('requires a device id for revoke', async () => {

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

@@ -1,17 +1,19 @@
 /**
  * `/devices` — this device's place in the user's device identity: list the roster, create the
- * identity, revoke a device, recover from the recovery phrase.
+ * identity, enrol another device or join with one, revoke a device, recover from the recovery phrase.
  *
  * Operator-only, twice over: the command is not model-invocable, and it refuses any invocation that
  * is not the operator's own (a remote surface, the model). Every verb that touches a secret or
  * asks for a confirmation runs inside the terminal handoff, so what is typed goes to the host's
- * terminal and never through the session's input, prompt history or conversation. Without an
+ * terminal and never through the session's input, prompt history or conversation — the enrollment
+ * code included, which is why `join` reads it there instead of taking it as an argument. Without an
  * interactive terminal those verbs refuse rather than fall back to anything else.
  */
 import { createSystemCommandFromEntry } from '../command-module-utils.js';
 
 import type {
   IDevicesCommandPort,
+  IDevicesMeshStatus,
   IDevicesView,
   TDevicesOutcome,
   TDevicesRefusal,
@@ -24,23 +26,28 @@ import type {
 import type { ICommand, ICommandResult, ICommandSource } from '@robota-sdk/agent-interface-command';
 
 const SHORT_ID_CHARS = 10;
-const USAGE = 'Usage: /devices [list|init [name]|revoke <device-id>|recover]';
+const USAGE = 'Usage: /devices [list|init [name]|add|join [name]|revoke <device-id>|recover]';
 
 export function createDevicesCommandEntry(): ICommand {
   return {
     name: 'devices',
     displayName: 'Devices',
     description:
-      "Manage this device's identity among the user's devices: list the roster, create the identity and its recovery phrase, revoke a device, or rotate the signing key from the phrase. Operator-only; the phrase is handled on the terminal and results carry only device ids and names.",
+      "Manage this device's identity among the user's devices: list the roster with the device mesh status (whether it is on, how this device finds the others, which are linked), create the identity and its recovery phrase (init, for the user's first device only: on a device of a user who already has others it makes a separate identity that can never link to them), enrol another device (add shows a one-time code; join on the new device reads it), revoke a device, or rotate the signing key from the phrase. A new identity or new lists take effect in the running session's device mesh at once. Operator-only; the phrase and the enrollment code are handled on the terminal only, and results carry only device ids and names.",
     source: 'devices',
     modelInvocable: false,
     userInvocable: true,
-    argumentHint: '[list|init [name]|revoke <device-id>|recover]',
+    argumentHint: '[list|init [name]|add|join [name]|revoke <device-id>|recover]',
     subcommands: [
-      { name: 'list', description: 'List your devices', source: 'devices' },
+      {
+        name: 'list',
+        description: 'List your devices and the device mesh status',
+        source: 'devices',
+      },
       {
         name: 'init',
-        description: 'Create your device identity and recovery phrase',
+        description:
+          'Create your device identity and recovery phrase, on your first device only (on another, a separate identity that can never link to your devices; use add/join there)',
         source: 'devices',
         argumentHint: '[name]',
       },
@@ -55,26 +62,57 @@ export function createDevicesCommandEntry(): ICommand {
         description: 'Rotate the signing key from your recovery phrase',
         source: 'devices',
       },
+      {
+        name: 'add',
+        description: 'Enrol another device: show a one-time code for it',
+        source: 'devices',
+      },
+      {
+        name: 'join',
+        description: 'Join your devices with the code another device shows',
+        source: 'devices',
+        argumentHint: '[name]',
+      },
     ],
   };
 }
 
 const REFUSALS: Readonly<Record<TDevicesRefusal, string>> = {
-  'no-terminal': 'This needs an interactive terminal; the recovery phrase is never shown or read anywhere else.',
-  'not-initialized': 'This device has no identity yet. Run `/devices init` first.',
-  'already-initialized': 'This device already has an identity. Use `/devices recover` to rotate its signing key.',
+  'no-terminal':
+    'This needs an interactive terminal; the recovery phrase is never shown or read anywhere else.',
+  'not-initialized':
+    'This device has no identity yet. If you already use Robota on another device, run `/devices add` there and `/devices join` here, typing the code it shows. Run `/devices init` only for your first device: it creates a separate identity that can never link to your other devices.',
+  'already-initialized':
+    'This device already has an identity. Use `/devices recover` to rotate its signing key.',
   cancelled: 'Cancelled. Nothing was changed.',
   'confirmation-failed': 'The confirmation did not match. Nothing was changed.',
   'phrase-invalid': 'That is not a valid recovery phrase. Nothing was changed.',
   'phrase-mismatch':
     'That phrase (with that passphrase) belongs to a different identity than this device. Nothing was changed.',
-  'no-signing-key': 'This device does not hold the signing key. Revoke from a device that does, or `/devices recover`.',
-  'signing-key-expired': 'The signing key on this device has expired. Run `/devices recover` to issue a new one.',
+  'no-signing-key':
+    'This device does not hold the signing key. Revoke from a device that does, or `/devices recover`.',
+  'signing-key-expired':
+    'The signing key on this device has expired. Run `/devices recover` to issue a new one.',
   'unknown-device': 'No device in the roster has that id.',
   'ambiguous-device': 'More than one device starts with that id; give more of it.',
-  'self-revocation': 'This device cannot revoke itself. Revoke it from another device, or `/devices recover`.',
+  'self-revocation':
+    'This device cannot revoke itself. Revoke it from another device, or `/devices recover`.',
   'changed-concurrently':
     'The device identity changed in another session while this was waiting. Nothing was changed; try again.',
+  'no-relay':
+    'Enrolling a device needs a signaling relay. Set `transports.webrtc.options.relayUrl` in your settings on both devices.',
+  'code-invalid': 'That is not an enrollment code. Nothing was changed.',
+  'code-on-command-line':
+    'Do not put the code on the command line, where history keeps it. Run `/devices add` again on the other device for a new code, then `/devices join` here and type it at the prompt.',
+  'code-not-accepted':
+    'No device accepted that code: it is wrong, expired or already used, or the connection was tampered with. Run `/devices add` on the other device for a new code.',
+  'enrollment-expired': 'The code expired before a device joined. Nothing was changed.',
+  'too-many-attempts':
+    'Too many attempts failed to prove the code, so it no longer works. Nothing was changed; run `/devices add` again.',
+  'enrollment-declined': 'The enrollment was declined. Nothing was changed.',
+  'enrollment-timed-out': 'Nobody answered in time. Nothing was changed.',
+  'enrollment-failed':
+    'The signaling relay or the connection to the other device failed before the enrollment finished. Nothing was changed; try again.',
 };
 
 function short(id: string): string {
@@ -89,7 +127,27 @@ function refused(reason: TDevicesRefusal): ICommandResult {
   return { success: false, message: REFUSALS[reason] };
 }
 
-function formatList(view: IDevicesView | undefined): ICommandResult {
+function formatMesh(mesh: IDevicesMeshStatus): string[] {
+  if (mesh.state === 'off') {
+    return [
+      'Device mesh: off. Set `transports.mesh.enabled` to true in your user settings to link your devices.',
+    ];
+  }
+  if (mesh.state === 'failed') {
+    return [`Device mesh: could not start: ${mesh.reason ?? 'no reason was reported'}.`];
+  }
+  const found = mesh.sources.length > 0 ? `; finds devices by ${mesh.sources.join(', ')}` : '';
+  const linked = mesh.linked.map(
+    (device) =>
+      `  ${short(device.deviceId)}  ${device.name ?? ''}  ${device.locality === 'same-host' ? 'on this machine' : 'on another machine'}`,
+  );
+  return [
+    `Device mesh: ${mesh.state}${found}.`,
+    ...(linked.length > 0 ? ['Linked now:', ...linked] : ['No device is linked right now.']),
+  ];
+}
+
+function formatList(view: IDevicesView | undefined, mesh?: IDevicesMeshStatus): ICommandResult {
   if (view === undefined) return { success: true, message: REFUSALS['not-initialized'] };
   const lines = view.devices.map((device) => {
     const notes = [
@@ -105,6 +163,7 @@ function formatList(view: IDevicesView | undefined): ICommandResult {
       `Devices of user ${short(view.userId)}:`,
       ...lines,
       `${view.revokedDeviceCount} revoked. Roster and revocation list valid until ${new Date(view.listsExpireAt).toISOString()}.`,
+      ...(mesh !== undefined ? formatMesh(mesh) : []),
     ].join('\n'),
   };
 }
@@ -139,7 +198,8 @@ export async function executeDevicesCommand(
   if (!isOperator(context)) {
     return {
       success: false,
-      message: '`/devices` runs only for the operator at this terminal, never from a remote surface or the model.',
+      message:
+        '`/devices` runs only for the operator at this terminal, never from a remote surface or the model.',
     };
   }
   const trimmed = args.trim();
@@ -152,7 +212,7 @@ export async function executeDevicesCommand(
     case '':
     case 'list':
       try {
-        return formatList(await port.list());
+        return formatList(await port.list(), port.meshStatus?.());
       } catch (error) {
         return {
           success: false,
@@ -167,7 +227,9 @@ export async function executeDevicesCommand(
           [
             `Device identity created. This device: ${short(value.deviceId)}; user ${short(value.userId)}.`,
             `It holds signing key ${short(value.signingKeyId)}.`,
-            ...(value.keyStorage !== undefined ? [`Private keys are kept in: ${value.keyStorage}.`] : []),
+            ...(value.keyStorage !== undefined
+              ? [`Private keys are kept in: ${value.keyStorage}.`]
+              : []),
             'Keep the recovery phrase offline; it is the only way to recover this identity.',
           ].join('\n'),
       );
@@ -180,23 +242,45 @@ export async function executeDevicesCommand(
             `Recovered. New signing key ${short(value.signingKeyId)}; ${value.revokedSigningKeyCount} old signing key(s) revoked.`,
             `This device (${short(value.deviceId)}) is certified again.`,
             ...(value.droppedDeviceCount > 0
-              ? [`${value.droppedDeviceCount} other device(s) were certified by a retired signing key and must enrol again.`]
+              ? [
+                  `${value.droppedDeviceCount} other device(s) were certified by a retired signing key and must enrol again.`,
+                ]
               : []),
           ].join('\n'),
       );
     case 'revoke':
-      if (rest.length === 0) return { success: false, message: 'Usage: /devices revoke <device-id>' };
+      if (rest.length === 0)
+        return { success: false, message: 'Usage: /devices revoke <device-id>' };
       return onTerminal(
         context,
         () => port.revoke(rest),
-        (value) => `Revoked ${value.name} (${short(value.deviceId)}). A new roster and revocation list were issued.`,
+        (value) =>
+          `Revoked ${value.name} (${short(value.deviceId)}). A new roster and revocation list were issued.`,
       );
     case 'add':
+      return onTerminal(
+        context,
+        () => port.add(),
+        (value) =>
+          [
+            `Enrolled ${value.name} (${short(value.deviceId)}). A new roster was issued.`,
+            ...(value.confirmed
+              ? []
+              : ['The new device did not confirm it kept its identity; check `/devices` there.']),
+          ].join('\n'),
+      );
     case 'join':
-      return {
-        success: false,
-        message: `\`/devices ${verb}\` is not available yet: enrolling another device over the device connection is not built yet.`,
-      };
+      return onTerminal(
+        context,
+        () => port.join(rest.length > 0 ? { name: rest } : {}),
+        (value) =>
+          [
+            `Joined the devices of user ${short(value.userId)}. This device: ${value.name} (${short(value.deviceId)}).`,
+            ...(value.keyStorage !== undefined
+              ? [`Private keys are kept in: ${value.keyStorage}.`]
+              : []),
+          ].join('\n'),
+      );
     default:
       return { success: false, message: `Unknown argument "${verb}". ${USAGE}` };
   }

package/src/devices/devices-command-port.ts

@@ -43,7 +43,25 @@ export type TDevicesRefusal =
   | 'ambiguous-device'
   | 'self-revocation'
   /** Another process changed the identity while this operation waited on the operator. */
-  | 'changed-concurrently';
+  | 'changed-concurrently'
+  /** No signaling relay is configured to meet the other device through. */
+  | 'no-relay'
+  /** What was typed is not an enrollment code. */
+  | 'code-invalid'
+  /** The code was typed on the command line, where history keeps it. */
+  | 'code-on-command-line'
+  /** No device waits for that code or proved it: wrong, expired, already used, or something in between. */
+  | 'code-not-accepted'
+  /** Nobody joined before the code expired. */
+  | 'enrollment-expired'
+  /** Too many attempts failed to prove the code; it no longer works. */
+  | 'too-many-attempts'
+  /** The operator of either device declined. */
+  | 'enrollment-declined'
+  /** An operator did not answer in time. */
+  | 'enrollment-timed-out'
+  /** The connection or the exchange with the other device failed partway. */
+  | 'enrollment-failed';
 
 export type TDevicesOutcome<T> =
   | { readonly ok: true; readonly value: T }
@@ -70,13 +88,56 @@ export interface IDevicesRevokeResult {
   readonly name: string;
 }
 
+/** This session's endpoint in the device mesh. */
+export interface IDevicesMeshStatus {
+  /** `off`: the setting is off, or this run does not open the mesh. `failed`: it could not open. */
+  readonly state: 'off' | 'starting' | 'on' | 'failed';
+  /** Why it could not open, for `failed`. */
+  readonly reason?: string;
+  /** How this device looks for the others, in the operator's words. */
+  readonly sources: readonly string[];
+  /** The devices with an admitted link now. */
+  readonly linked: readonly {
+    readonly deviceId: string;
+    readonly name?: string;
+    readonly locality: 'same-host' | 'another-host';
+  }[];
+}
+
+export interface IDevicesAddResult {
+  readonly deviceId: string;
+  readonly name: string;
+  /** Whether the new device said it kept what it was given. */
+  readonly confirmed: boolean;
+}
+
+export interface IDevicesJoinResult {
+  readonly userId: string;
+  readonly deviceId: string;
+  readonly name: string;
+  /** Where the private keys were kept, for the operator. */
+  readonly keyStorage?: string;
+}
+
 export interface IDevicesCommandPort {
   /** This device's view of the roster, or `undefined` when it has no identity yet. */
   list(): Promise<IDevicesView | undefined>;
+  /** The device mesh as this session runs it. Absent on a host with no device mesh. */
+  meshStatus?(): IDevicesMeshStatus;
   /** Create the identity. Runs on the operator terminal (it shows the phrase once). */
   init(options: { readonly name?: string }): Promise<TDevicesOutcome<IDevicesInitResult>>;
   /** Rotate the signing key from the phrase. Runs on the operator terminal. */
   recover(): Promise<TDevicesOutcome<IDevicesRecoverResult>>;
   /** Revoke a device by id prefix with the signing key. Confirms on the operator terminal. */
   revoke(deviceIdPrefix: string): Promise<TDevicesOutcome<IDevicesRevokeResult>>;
+  /**
+   * Enrol another device with the signing key: show a one-time code, and certify the device that
+   * proves it once both operators confirm the string both devices show. Runs on the operator terminal.
+   */
+  add(): Promise<TDevicesOutcome<IDevicesAddResult>>;
+  /**
+   * Join the user's devices with a code another device shows, once both operators confirm the string
+   * both devices show. Runs on the operator terminal.
+   */
+  join(options: { readonly name?: string }): Promise<TDevicesOutcome<IDevicesJoinResult>>;
 }

package/src/devices/index.ts

@@ -3,7 +3,10 @@ export type {
   IDeviceListEntry,
   IDevicesCommandPort,
   IDevicesInitResult,
+  IDevicesMeshStatus,
   IDevicesRecoverResult,
+  IDevicesAddResult,
+  IDevicesJoinResult,
   IDevicesRevokeResult,
   IDevicesView,
   TDevicesOutcome,

package/src/doctor/doctor-node-deps.ts

@@ -1,5 +1,5 @@
 /** Node defaults for {@link IDoctorDeps}: a TCP connect probe and read-only filesystem facts. */
-import { accessSync, constants, existsSync, statSync } from 'node:fs';
+import { accessSync, constants, existsSync, statSync, type Stats } from 'node:fs';
 import { createConnection } from 'node:net';
 import { delimiter, isAbsolute, join } from 'node:path';
 
@@ -41,16 +41,15 @@ export function probeEndpointViaSocket(
 /** Existence, directory-ness, `W_OK` and mode — probed without writing. */
 export function inspectPathFacts(path: string): IDoctorPathFacts {
   if (!existsSync(path)) return { exists: false, isDirectory: false, writable: false };
-  let isDirectory = false;
-  let mode: number | undefined;
+  let stat: Stats;
   try {
-    const stat = statSync(path);
-    isDirectory = stat.isDirectory();
-    mode = stat.mode & MODE_BITS;
+    stat = statSync(path);
   } catch {
     // allow-fallback: a path that exists but cannot be stat'ed is reported as not a writable directory
     return { exists: true, isDirectory: false, writable: false };
   }
+  const isDirectory = stat.isDirectory();
+  const mode = stat.mode & MODE_BITS;
   let writable = false;
   try {
     accessSync(path, constants.W_OK);
@@ -59,7 +58,7 @@ export function inspectPathFacts(path: string): IDoctorPathFacts {
     // allow-fallback: W_OK refused IS the fact being reported
     writable = false;
   }
-  return { exists: true, isDirectory, writable, ...(mode === undefined ? {} : { mode }) };
+  return { exists: true, isDirectory, writable, mode };
 }
 
 /** A bare command resolves through `PATH`; a path-form command must exist as given. */

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

@@ -14,6 +14,9 @@ export function createEditorCommandEntry(): ICommand {
     source: 'editor',
     // User-only: opens the user's terminal editor; UI-only.
     modelInvocable: false,
+    // It takes over the terminal the user sits at, so that terminal runs it, even when attached.
+    runner: 'client',
+    surfaces: ['terminal'],
   };
 }
 
@@ -26,6 +29,8 @@ function createEditorSystemCommand(temporaryDirectoryPrefix?: string): ISystemCo
     requiresPermission: false,
     userInvocable: true,
     modelInvocable: false,
+    runner: entry.runner,
+    surfaces: entry.surfaces,
     lifecycle: 'inline',
     execute: (context, args) => executeEditorCommand(context, args, temporaryDirectoryPrefix),
   };

package/src/effort/effort-command.test.ts

@@ -5,6 +5,37 @@ import { executeEffortCommand } from './effort-command.js';
 import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
 
 describe('/effort', () => {
+  it('#3282 §2: reports plainly when the model has no matching effort control at all', async () => {
+    const host = createTestCommandHost({
+      overrides: {
+        getCommandHostAdapters: () => ({
+          settings: { read: () => ({}), write: vi.fn() },
+          effort: {
+            getResolution: () => ({
+              requested: 'low',
+              effective: 'low',
+              source: 'command',
+              disposition: 'not-applied',
+              modelDefault: 'high',
+            }),
+            apply: async () => ({
+              requested: 'low',
+              effective: 'low',
+              source: 'command',
+              disposition: 'not-applied',
+              modelDefault: 'high',
+            }),
+          },
+        }),
+      },
+    });
+
+    const result = await executeEffortCommand(host, 'low');
+
+    expect(result.success).toBe(true);
+    expect(result.message).toBe("This model doesn't support effort levels, so it will use its default.");
+  });
+
   it('applies a requested level and returns the complete resolution', async () => {
     const applyModelOptions = vi.fn();
     const writeSettings = vi.fn();
@@ -36,6 +67,7 @@ describe('/effort', () => {
     const result = await executeEffortCommand(host, 'low');
 
     expect(result.success).toBe(true);
+    expect(result.message).toBe('Effort: Low');
     expect(result.data).toMatchObject({
       effort: { requested: 'low', effective: 'low', source: 'command', disposition: 'applied' },
     });
@@ -50,7 +82,7 @@ describe('/effort', () => {
     const result = await executeEffortCommand(host, '');
 
     expect(result.success).toBe(true);
-    expect(result.message).toContain('high');
+    expect(result.message).toBe('Effort: High');
     expect(applyModelOptions).not.toHaveBeenCalled();
   });
 
@@ -133,8 +165,39 @@ describe('/effort', () => {
     const result = await executeEffortCommand(host, '');
 
     expect(result.success).toBe(true);
-    expect(result.message).toContain('effective=medium');
+    expect(result.message).toBe('Effort: Medium');
     expect(applyModelOptions).not.toHaveBeenCalled();
     expect(writeSettings).not.toHaveBeenCalled();
   });
+
+  it('#3282 §2: uses the full plain word for xhigh, not the internal id', async () => {
+    const host = createTestCommandHost({
+      overrides: {
+        getCommandHostAdapters: () => ({
+          settings: { read: () => ({}), write: vi.fn() },
+          effort: {
+            getResolution: () => ({
+              requested: 'auto',
+              effective: 'high',
+              source: 'model-default',
+              disposition: 'model-default',
+              modelDefault: 'high',
+            }),
+            apply: async (selection) => ({
+              requested: selection,
+              effective: selection === 'auto' ? 'high' : selection,
+              source: 'command',
+              disposition: 'applied',
+              modelDefault: 'high',
+            }),
+          },
+        }),
+      },
+    });
+
+    const result = await executeEffortCommand(host, 'xhigh');
+
+    expect(result.success).toBe(true);
+    expect(result.message).toBe('Effort: Extra high');
+  });
 });