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

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 needs the device connection, which 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/events/__tests__/events-command.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { executeEventsCommand } from '../events-command.js';
+import { createEventsCommandModule } from '../events-command-module.js';
+
+import type { ICommandExternalEventsAdapter } from '@robota-sdk/agent-framework';
+
+function adapter(): ICommandExternalEventsAdapter & { revoke: ReturnType<typeof vi.fn> } {
+  return {
+    list: () => [
+      {
+        grantId: 'ci',
+        principal: 'client',
+        state: 'open',
+        counters: { accepted: 2, refused: { expired: 1 }, settled: { completed: 2 } },
+      },
+    ],
+    revoke: vi.fn((grantId: string) => (grantId === 'ci' ? 'revoked' : 'unknown-grant')),
+  };
+}
+
+const context = (externalEvents?: ICommandExternalEventsAdapter) => ({
+  getCommandHostAdapters: () => (externalEvents ? { externalEvents } : {}),
+});
+
+describe('/events command module', () => {
+  it('is user-only: never model-invocable, and palette metadata matches the executable', () => {
+    const module = createEventsCommandModule();
+    const palette = module.commandSources?.[0]?.getCommands()[0];
+    const executable = module.systemCommands?.[0];
+    expect(palette?.name).toBe('events');
+    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 what it does, what it returns, that it is user-only, and what to suggest', () => {
+    const description =
+      createEventsCommandModule().commandSources?.[0]?.getCommands()[0]?.description;
+    expect(description).toMatch(/external event grants/i);
+    expect(description).toMatch(/returns/i);
+    expect(description).toMatch(/user-only/i);
+    expect(description).toContain('`/events revoke <grant-id>`');
+  });
+});
+
+describe('/events', () => {
+  it('lists grants with their principal kind and counts', async () => {
+    const result = await executeEventsCommand(context(adapter()), '');
+    expect(result.success).toBe(true);
+    expect(result.message).toContain(
+      'ci  client  open  accepted 2; refused: expired 1; settled: completed 2',
+    );
+  });
+
+  it('revokes one grant by label and says when the label is unknown', async () => {
+    const events = adapter();
+    expect((await executeEventsCommand(context(events), 'revoke ci')).message).toMatch(
+      /Revoked external event grant ci/,
+    );
+    expect(events.revoke).toHaveBeenCalledWith('ci');
+    const unknown = await executeEventsCommand(context(events), 'revoke nope');
+    expect(unknown.success).toBe(false);
+    expect(unknown.message).toMatch(/no external event grant nope/);
+    expect((await executeEventsCommand(context(events), 'revoke')).success).toBe(false);
+  });
+
+  it('says how grants are given when the session holds none', async () => {
+    const result = await executeEventsCommand(context(), '');
+    expect(result.message).toMatch(/only when a session starts/);
+  });
+});

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

@@ -0,0 +1,49 @@
+import { executeEventsCommand } from './events-command.js';
+
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
+
+export function createEventsCommandEntry(): ICommand {
+  return {
+    name: 'events',
+    displayName: 'Events',
+    description:
+      "List this session's external event grants (each grant's label, whether it pins a subject or a client, whether it is open or revoked, and its counts of accepted, refused and settled events), or revoke one with `/events revoke <grant-id>`. Returns the grants, or whether the revocation took effect. User-only: the model cannot run it; when the user wants to stop events from outside, suggest `/events revoke <grant-id>`.",
+    source: 'events',
+    argumentHint: '[revoke <grant-id>]',
+    // User-only: a grant is the owner's standing decision that someone outside may put turns into
+    // this session. Withdrawing it is the owner's call too, and listing it lives on the same command.
+    modelInvocable: false,
+  };
+}
+
+function createEventsSystemCommand(): ISystemCommand {
+  const entry = createEventsCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: false,
+    ...(entry.argumentHint !== undefined ? { argumentHint: entry.argumentHint } : {}),
+    lifecycle: 'inline',
+    execute: (context, args) => executeEventsCommand(context, args),
+  };
+}
+
+export class EventsCommandSource implements ICommandSource {
+  readonly name = 'events';
+
+  getCommands(): ICommand[] {
+    return [createEventsCommandEntry()];
+  }
+}
+
+export function createEventsCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-events',
+    commandSources: [new EventsCommandSource()],
+    systemCommands: [createEventsSystemCommand()],
+  };
+}

package/src/events/events-command.ts

@@ -0,0 +1,69 @@
+import type {
+  ICommandExternalEventGrant,
+  ICommandHostAdapterAccess,
+} from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+
+const GRANT_ID = /^[a-zA-Z0-9_-]{1,64}$/u;
+
+function counts(values: Readonly<Partial<Record<string, number>>>): string {
+  const entries = Object.entries(values).filter(([, count]) => (count ?? 0) > 0);
+  return entries.length === 0
+    ? 'none'
+    : entries.map(([key, count]) => `${key} ${count}`).join(', ');
+}
+
+/** Label, principal kind, state and counts. The principal itself is never shown. */
+function describe(grant: ICommandExternalEventGrant): string {
+  const { counters } = grant;
+  return (
+    `  ${grant.grantId}  ${grant.principal}  ${grant.state}  accepted ${counters.accepted}; ` +
+    `refused: ${counts(counters.refused)}; settled: ${counts(counters.settled)}`
+  );
+}
+
+/**
+ * `/events` — this session's external-event grants, and `/events revoke <grant-id>` to withdraw one.
+ * Grants are given only when the session starts; nothing here creates one.
+ */
+export async function executeEventsCommand(
+  context: ICommandHostAdapterAccess,
+  args = '',
+): Promise<ICommandResult> {
+  const adapter = context.getCommandHostAdapters?.().externalEvents;
+  if (!adapter) {
+    return {
+      message:
+        'This session holds no external event grant. Grants are given only when a session starts.',
+      success: true,
+    };
+  }
+  const [verb, grantId, extra] = args
+    .trim()
+    .split(/\s+/u)
+    .filter((word) => word !== '');
+  if (verb === undefined) {
+    const grants = adapter.list();
+    return {
+      message:
+        grants.length === 0
+          ? 'This session holds no external event grant.'
+          : `External event grants:\n${grants.map(describe).join('\n')}\n\nWithdraw one: /events revoke <grant-id>`,
+      success: true,
+    };
+  }
+  if (
+    verb !== 'revoke' ||
+    grantId === undefined ||
+    extra !== undefined ||
+    !GRANT_ID.test(grantId)
+  ) {
+    return { message: 'Usage: /events  |  /events revoke <grant-id>', success: false };
+  }
+  return adapter.revoke(grantId) === 'revoked'
+    ? {
+        message: `Revoked external event grant ${grantId}. Later events for it are refused.`,
+        success: true,
+      }
+    : { message: `This session holds no external event grant ${grantId}.`, success: false };
+}

package/src/events/index.ts

@@ -0,0 +1,2 @@
+/** Only the module factory leaves this directory; the command is registered by default. */
+export { createEventsCommandModule } from './events-command-module.js';

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

@@ -1,5 +1,9 @@
 /** BEHAVIOR-2437 TC-05 — registration, the descriptor, and the verb parse through the real session. */
-import { afterEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterAll, afterEach, describe, expect, it } from 'vitest';
 
 import { scriptedSession, type ScriptedSessionHarness } from '@robota-sdk/agent-framework/testing';
 
@@ -35,7 +39,11 @@ const providerSettingsAdapter: IProviderCommandSettingsAdapter = {
   readTargetSettings: () => ({}) as TProviderSettingsDocument,
   writeTargetSettings: () => undefined,
 };
-const BASE_OPTIONS = { cwd: '/tmp', userLocalStorageRoot: '/tmp/robota-test', providerDefinitions, providerSettingsAdapter } as const;
+/** User-local storage lives in a private per-run directory, never a fixed name under /tmp. */
+const USER_LOCAL_STORAGE_ROOT = mkdtempSync(join(tmpdir(), 'robota-test-'));
+afterAll(() => rmSync(USER_LOCAL_STORAGE_ROOT, { recursive: true, force: true }));
+
+const BASE_OPTIONS = { cwd: '/tmp', userLocalStorageRoot: USER_LOCAL_STORAGE_ROOT, providerDefinitions, providerSettingsAdapter } as const;
 
 const STATUS_FIXTURE = '# branch.head main\0? scratch.log\0';
 

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

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+
+import { createHandoffCommandModule } from '../handoff-command-module.js';
+
+describe('/handoff command module', () => {
+  it('is user-only: never model-invocable, and palette metadata matches the executable', () => {
+    const module = createHandoffCommandModule();
+    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(palette?.userInvocable).toBe(true);
+    expect(executable?.description).toBe(palette?.description);
+  });
+
+  it('tells the model what it does and which command to suggest, since it cannot run it', () => {
+    const description =
+      createHandoffCommandModule().commandSources?.[0]?.getCommands()[0]?.description;
+    expect(description).toContain('/handoff <session-or-device-id>');
+    expect(description).toMatch(/linked over the device mesh/);
+    expect(description).toMatch(/user-only/i);
+    expect(description).toContain('saved, not started');
+  });
+});

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

@@ -138,8 +138,8 @@ describe('every outcome says where the session is now', () => {
     const result = await executeHandoffCommand(context, 'laptop');
 
     expect(result.success).toBe(true);
-    expect(result.message).toContain('laptop is running this session now');
-    expect(result.message).toContain('read-only');
+    expect(result.message).toContain('laptop saved this session and has not started it');
+    expect(result.message).toContain('this one ends');
   });
 
   it('says the session is still here when the transfer stops, and why', async () => {
@@ -155,7 +155,7 @@ describe('every outcome says where the session is now', () => {
     expect(result.success).toBe(false);
     expect(result.message).toContain('no provider credential');
     expect(result.message).toContain('still on this machine');
-    expect(result.message).not.toContain('read-only');
+    expect(result.message).not.toContain('this one ends');
   });
 
   it('names the waiting phase as safe to leave, since that is when it looks stuck', async () => {