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

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

@@ -0,0 +1,212 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { scriptedSession, type ScriptedSessionHarness } from '@robota-sdk/agent-framework/testing';
+
+import { createDevicesCommandModule } from '../devices-command-module.js';
+
+import type { IDevicesCommandPort } from '../devices-command-port.js';
+import type { ITerminalHandoff } from '@robota-sdk/agent-interface-session';
+
+const DEVICE_A = 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA';
+const DEVICE_B = 'BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB';
+const USER = 'UUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUU';
+const SIGNING = 'SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS';
+
+function fakePort(): IDevicesCommandPort & { calls: string[] } {
+  const calls: string[] = [];
+  return {
+    calls,
+    list: vi.fn(async () => {
+      calls.push('list');
+      return {
+        userId: USER,
+        devices: [
+          {
+            deviceId: DEVICE_A,
+            name: 'laptop',
+            thisDevice: true,
+            holdsSigningKey: true,
+            certificateExpiresAt: Date.UTC(2026, 11, 25),
+          },
+          {
+            deviceId: DEVICE_B,
+            name: 'desktop',
+            thisDevice: false,
+            holdsSigningKey: false,
+            certificateExpiresAt: Date.UTC(2026, 11, 20),
+          },
+        ],
+        revokedDeviceCount: 1,
+        listsExpireAt: Date.UTC(2026, 8, 27),
+      };
+    }),
+    init: vi.fn(async (options) => {
+      calls.push(`init:${options.name ?? ''}`);
+      return {
+        ok: true as const,
+        value: { userId: USER, deviceId: DEVICE_A, signingKeyId: SIGNING, keyStorage: 'OS keychain' },
+      };
+    }),
+    recover: vi.fn(async () => {
+      calls.push('recover');
+      return {
+        ok: true as const,
+        value: {
+          deviceId: DEVICE_A,
+          signingKeyId: SIGNING,
+          revokedSigningKeyCount: 1,
+          droppedDeviceCount: 1,
+        },
+      };
+    }),
+    revoke: vi.fn(async (target) => {
+      calls.push(`revoke:${target}`);
+      return { ok: true as const, value: { deviceId: DEVICE_B, name: 'desktop' } };
+    }),
+  };
+}
+
+function handoff(enabled: boolean, onRun?: () => void): ITerminalHandoff {
+  return {
+    canHandoffTerminal: enabled,
+    runWithTerminal: async (operation) => {
+      onRun?.();
+      return operation();
+    },
+  };
+}
+
+let session: ScriptedSessionHarness | undefined;
+
+afterEach(async () => {
+  await session?.dispose();
+  session = undefined;
+});
+
+function start(port: IDevicesCommandPort, terminal = handoff(true)): ScriptedSessionHarness {
+  session = scriptedSession({
+    turns: [{ text: 'unused' }],
+    terminalHandoff: terminal,
+    commandModules: [createDevicesCommandModule(port)],
+  });
+  return session;
+}
+
+describe('/devices command', () => {
+  it('is operator-only: never model-invocable, and palette metadata matches the executable', () => {
+    const module = createDevicesCommandModule(fakePort());
+    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?.subcommands?.map(({ name }) => name)).toEqual([
+      'list',
+      'init',
+      'revoke',
+      'recover',
+    ]);
+  });
+
+  it('lists the roster with short ids, this device, the signing-key holder and expiry', async () => {
+    const port = fakePort();
+    const result = await start(port).command('devices', '');
+    expect(result?.success).toBe(true);
+    expect(result?.message).toContain(DEVICE_A.slice(0, 10));
+    expect(result?.message).not.toContain(DEVICE_A);
+    expect(result?.message).toMatch(/laptop.*this device.*signing key/);
+    expect(result?.message).toContain('2026-12-25');
+    expect(result?.message).toContain('desktop');
+    expect(result?.message).toMatch(/1 revoked/);
+  });
+
+  it('says so when this device has no identity yet', async () => {
+    const port = fakePort();
+    vi.mocked(port.list).mockResolvedValueOnce(undefined);
+    const result = await start(port).command('devices', 'list');
+    expect(result?.message).toMatch(/\/devices init/);
+  });
+
+  it('runs init, recover and revoke on the operator terminal', async () => {
+    const port = fakePort();
+    const runs = vi.fn();
+    const harness = start(port, handoff(true, runs));
+    const init = await harness.command('devices', 'init my laptop');
+    expect(init?.success).toBe(true);
+    expect(init?.message).toContain(DEVICE_A.slice(0, 10));
+    expect(init?.message).toContain('OS keychain');
+    const recover = await harness.command('devices', 'recover');
+    expect(recover?.success).toBe(true);
+    expect(recover?.message).toMatch(/signing key/i);
+    const revoke = await harness.command('devices', `revoke ${DEVICE_B.slice(0, 8)}`);
+    expect(revoke?.success).toBe(true);
+    expect(revoke?.message).toContain('desktop');
+    expect(port.calls).toEqual(['init:my laptop', 'recover', `revoke:${DEVICE_B.slice(0, 8)}`]);
+    expect(runs).toHaveBeenCalledTimes(3);
+  });
+
+  it('reports a refusal by its reason', async () => {
+    const port = fakePort();
+    vi.mocked(port.recover).mockResolvedValueOnce({ ok: false, reason: 'phrase-mismatch' });
+    const result = await start(port).command('devices', 'recover');
+    expect(result?.success).toBe(false);
+    expect(result?.message).toMatch(/different identity/i);
+  });
+
+  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']) {
+      const result = await harness.command('devices', args);
+      expect(result?.success).toBe(false);
+      expect(result?.message).toMatch(/interactive terminal/i);
+    }
+    expect(port.calls).toEqual([]);
+  });
+
+  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);
+    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']) {
+      const result = await harness.session.executeCommand('devices', args, 'remote');
+      expect(result?.success).toBe(false);
+      expect(result?.message).toMatch(/operator/i);
+    }
+    expect(port.calls).toEqual([]);
+  });
+
+  it('names add and join as not yet available rather than guessing', 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([]);
+  });
+
+  it('requires a device id for revoke', async () => {
+    const port = fakePort();
+    const result = await start(port).command('devices', 'revoke');
+    expect(result?.success).toBe(false);
+    expect(result?.message).toMatch(/usage/i);
+    expect(port.calls).toEqual([]);
+  });
+
+  it('reports a failure without its stack', async () => {
+    const port = fakePort();
+    vi.mocked(port.init).mockRejectedValueOnce(new Error('credential store unavailable'));
+    const result = await start(port).command('devices', 'init');
+    expect(result?.success).toBe(false);
+    expect(result?.message).toContain('credential store unavailable');
+  });
+});

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

@@ -0,0 +1,224 @@
+/**
+ * `/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.
+ *
+ * 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
+ * interactive terminal those verbs refuse rather than fall back to anything else.
+ */
+import { createSystemCommandFromEntry } from '../command-module-utils.js';
+
+import type {
+  IDevicesCommandPort,
+  IDevicesView,
+  TDevicesOutcome,
+  TDevicesRefusal,
+} from './devices-command-port.js';
+import type {
+  ICommandHostContext,
+  ICommandModule,
+  ISystemCommand,
+} from '@robota-sdk/agent-framework';
+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]';
+
+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.",
+    source: 'devices',
+    modelInvocable: false,
+    userInvocable: true,
+    argumentHint: '[list|init [name]|revoke <device-id>|recover]',
+    subcommands: [
+      { name: 'list', description: 'List your devices', source: 'devices' },
+      {
+        name: 'init',
+        description: 'Create your device identity and recovery phrase',
+        source: 'devices',
+        argumentHint: '[name]',
+      },
+      {
+        name: 'revoke',
+        description: 'Revoke a device with the signing key',
+        source: 'devices',
+        argumentHint: '<device-id>',
+      },
+      {
+        name: 'recover',
+        description: 'Rotate the signing key from your recovery phrase',
+        source: 'devices',
+      },
+    ],
+  };
+}
+
+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.',
+  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.',
+  '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`.',
+  'changed-concurrently':
+    'The device identity changed in another session while this was waiting. Nothing was changed; try again.',
+};
+
+function short(id: string): string {
+  return id.slice(0, SHORT_ID_CHARS);
+}
+
+function day(ms: number): string {
+  return new Date(ms).toISOString().slice(0, 10);
+}
+
+function refused(reason: TDevicesRefusal): ICommandResult {
+  return { success: false, message: REFUSALS[reason] };
+}
+
+function formatList(view: IDevicesView | undefined): ICommandResult {
+  if (view === undefined) return { success: true, message: REFUSALS['not-initialized'] };
+  const lines = view.devices.map((device) => {
+    const notes = [
+      ...(device.thisDevice ? ['this device'] : []),
+      ...(device.holdsSigningKey ? ['holds the signing key'] : []),
+    ];
+    const suffix = notes.length > 0 ? `  (${notes.join(', ')})` : '';
+    return `  ${short(device.deviceId)}  ${device.name}${suffix}  certificate expires ${day(device.certificateExpiresAt)}`;
+  });
+  return {
+    success: true,
+    message: [
+      `Devices of user ${short(view.userId)}:`,
+      ...lines,
+      `${view.revokedDeviceCount} revoked. Roster and revocation list valid until ${new Date(view.listsExpireAt).toISOString()}.`,
+    ].join('\n'),
+  };
+}
+
+function isOperator(context: ICommandHostContext): boolean {
+  return context.getCommandInvocationSource() === 'user';
+}
+
+/** Run a terminal-bound port call; a refusal or a thrown error becomes a failed result. */
+async function onTerminal<T>(
+  context: ICommandHostContext,
+  run: () => Promise<TDevicesOutcome<T>>,
+  done: (value: T) => string,
+): Promise<ICommandResult> {
+  if (!context.canHandoffTerminal()) return refused('no-terminal');
+  try {
+    const outcome = await context.runWithTerminal(run);
+    return outcome.ok ? { success: true, message: done(outcome.value) } : refused(outcome.reason);
+  } catch (error) {
+    return {
+      success: false,
+      message: `Device identity operation failed: ${error instanceof Error ? error.message : 'unknown error'}`,
+    };
+  }
+}
+
+export async function executeDevicesCommand(
+  port: IDevicesCommandPort,
+  context: ICommandHostContext,
+  args: string,
+): Promise<ICommandResult> {
+  if (!isOperator(context)) {
+    return {
+      success: false,
+      message: '`/devices` runs only for the operator at this terminal, never from a remote surface or the model.',
+    };
+  }
+  const trimmed = args.trim();
+  const spaceAt = trimmed.indexOf(' ');
+  const verb = (spaceAt === -1 ? trimmed : trimmed.slice(0, spaceAt)).toLowerCase();
+  // Device ids are case-sensitive base64url, so the remainder keeps its case.
+  const rest = spaceAt === -1 ? '' : trimmed.slice(spaceAt + 1).trim();
+
+  switch (verb) {
+    case '':
+    case 'list':
+      try {
+        return formatList(await port.list());
+      } catch (error) {
+        return {
+          success: false,
+          message: `Device identity could not be read: ${error instanceof Error ? error.message : 'unknown error'}`,
+        };
+      }
+    case 'init':
+      return onTerminal(
+        context,
+        () => port.init(rest.length > 0 ? { name: rest } : {}),
+        (value) =>
+          [
+            `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}.`] : []),
+            'Keep the recovery phrase offline; it is the only way to recover this identity.',
+          ].join('\n'),
+      );
+    case 'recover':
+      return onTerminal(
+        context,
+        () => port.recover(),
+        (value) =>
+          [
+            `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.`]
+              : []),
+          ].join('\n'),
+      );
+    case 'revoke':
+      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.`,
+      );
+    case 'add':
+    case 'join':
+      return {
+        success: false,
+        message: `\`/devices ${verb}\` is not available yet: enrolling another device needs the device connection, which is not built yet.`,
+      };
+    default:
+      return { success: false, message: `Unknown argument "${verb}". ${USAGE}` };
+  }
+}
+
+export class DevicesCommandSource implements ICommandSource {
+  readonly name = 'devices';
+
+  getCommands(): ICommand[] {
+    return [createDevicesCommandEntry()];
+  }
+}
+
+export function createDevicesCommandModule(port: IDevicesCommandPort): ICommandModule {
+  const command: ISystemCommand = createSystemCommandFromEntry(createDevicesCommandEntry(), {
+    requiresPermission: false,
+    lifecycle: 'inline',
+    execute: (context, args) => executeDevicesCommand(port, context, args),
+  });
+  return {
+    name: 'agent-command-devices',
+    commandSources: [new DevicesCommandSource()],
+    systemCommands: [command],
+  };
+}

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

@@ -0,0 +1,82 @@
+/**
+ * What `/devices` needs from the host that keeps this device's identity.
+ *
+ * The host owns every secret: the recovery phrase is shown and read on the host's own terminal, and
+ * private keys live in its credential store. What crosses this port back to the command is ids,
+ * names, times and closed refusal reasons — nothing the command formats can carry a secret, because
+ * the command never receives one. A thrown error's message is the host's promise to the same effect.
+ */
+
+export interface IDeviceListEntry {
+  readonly deviceId: string;
+  readonly name: string;
+  readonly thisDevice: boolean;
+  /** Whether this entry is known to hold the device-signing key. Only known for this device. */
+  readonly holdsSigningKey: boolean;
+  readonly certificateExpiresAt: number;
+}
+
+export interface IDevicesView {
+  readonly userId: string;
+  readonly devices: readonly IDeviceListEntry[];
+  readonly revokedDeviceCount: number;
+  /** When the roster and revocation list this device holds stop being accepted. */
+  readonly listsExpireAt: number;
+}
+
+/** Why an operation did not happen. Closed, so no free text from the secret path reaches a result. */
+export type TDevicesRefusal =
+  /** No interactive terminal: the phrase is never shown on or read from anything else. */
+  | 'no-terminal'
+  | 'not-initialized'
+  | 'already-initialized'
+  /** The operator cancelled at the terminal. */
+  | 'cancelled'
+  /** The re-typed words or passphrase did not match. */
+  | 'confirmation-failed'
+  | 'phrase-invalid'
+  /** The phrase is valid but derives another identity than this device's. */
+  | 'phrase-mismatch'
+  | 'no-signing-key'
+  | 'signing-key-expired'
+  | 'unknown-device'
+  | 'ambiguous-device'
+  | 'self-revocation'
+  /** Another process changed the identity while this operation waited on the operator. */
+  | 'changed-concurrently';
+
+export type TDevicesOutcome<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly reason: TDevicesRefusal };
+
+export interface IDevicesInitResult {
+  readonly userId: string;
+  readonly deviceId: string;
+  readonly signingKeyId: string;
+  /** Where the private keys were kept, for the operator. */
+  readonly keyStorage?: string;
+}
+
+export interface IDevicesRecoverResult {
+  readonly deviceId: string;
+  readonly signingKeyId: string;
+  readonly revokedSigningKeyCount: number;
+  /** Other devices that were certified by a retired signing key and must enrol again. */
+  readonly droppedDeviceCount: number;
+}
+
+export interface IDevicesRevokeResult {
+  readonly deviceId: string;
+  readonly name: string;
+}
+
+export interface IDevicesCommandPort {
+  /** This device's view of the roster, or `undefined` when it has no identity yet. */
+  list(): Promise<IDevicesView | undefined>;
+  /** 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>>;
+}

package/src/devices/index.ts

@@ -0,0 +1,11 @@
+export { createDevicesCommandModule } from './devices-command-module.js';
+export type {
+  IDeviceListEntry,
+  IDevicesCommandPort,
+  IDevicesInitResult,
+  IDevicesRecoverResult,
+  IDevicesRevokeResult,
+  IDevicesView,
+  TDevicesOutcome,
+  TDevicesRefusal,
+} from './devices-command-port.js';

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

@@ -0,0 +1,145 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { createDoctorCommandModule } from '../doctor-command-module.js';
+import {
+  createDoctorFixture,
+  fixtureProviderDefinition,
+  installBrokenHome,
+} from './doctor-fixture.js';
+
+import type { IDoctorFixture } from './doctor-fixture.js';
+import { CommandRegistry, SystemCommandExecutor } from '@robota-sdk/agent-framework';
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
+
+import type { IUserInteraction, TActionResponse } from '@robota-sdk/agent-core';
+
+const fixtures: IDoctorFixture[] = [];
+afterEach(() => {
+  for (const fixture of fixtures.splice(0)) fixture.cleanup();
+});
+
+/** The published conformant double, with only the interaction port overridden. */
+function contextWith(interaction: IUserInteraction | undefined) {
+  return createTestCommandHost({ overrides: { getUserInteraction: () => interaction } });
+}
+
+function answering(
+  response: TActionResponse,
+): IUserInteraction & { ask: ReturnType<typeof vi.fn> } {
+  return { ask: vi.fn(async () => response) };
+}
+
+describe('/doctor command module (OBSERVABILITY-1991 TC-06)', () => {
+  it('advertises repair arguments consistently in the palette and executable metadata', () => {
+    const fixture = createDoctorFixture({ env: {} });
+    fixtures.push(fixture);
+    const module = createDoctorCommandModule(fixture.inputs, fixture.deps);
+    const registry = new CommandRegistry();
+    registry.addModule(module);
+    const executor = new SystemCommandExecutor([...(module.systemCommands ?? [])]);
+    const entry = registry.getCommands().find((command) => command.name === 'doctor');
+    const command = executor.getCommand('doctor');
+    expect(entry).toMatchObject({ argumentHint: '[repair <check-id>]', modelInvocable: false });
+    expect(command).toMatchObject({
+      argumentHint: '[repair <check-id>]',
+      modelInvocable: false,
+      userInvocable: true,
+      requiresPermission: false,
+      lifecycle: 'inline',
+    });
+    expect(registry.getCapabilityDescriptors()).toContainEqual(
+      expect.objectContaining({
+        name: 'doctor',
+        argumentHint: '[repair <check-id>]',
+        userInvocable: true,
+        modelInvocable: false,
+      }),
+    );
+    expect(command?.description).toBe(entry?.description);
+    expect(executor.isModelInvocable('doctor')).toBe(false);
+  });
+
+  it('renders the same check set without constructing a provider or submitting input', async () => {
+    const createProvider = vi.fn(() => {
+      throw new Error('must not be called');
+    });
+    const fixture = createDoctorFixture({
+      env: {},
+      providerDefinitions: [fixtureProviderDefinition({ createProvider })],
+    });
+    fixtures.push(fixture);
+    installBrokenHome(fixture);
+    const module = createDoctorCommandModule(fixture.inputs, fixture.deps);
+    const command = module.systemCommands?.[0];
+    expect(command?.name).toBe('doctor');
+    const result = await command!.execute(contextWith(undefined), '');
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('settings.user.robota');
+    expect(result.message).toContain('plugin.broken-plugin@fixture-market');
+    expect(result.data).toMatchObject({
+      failCount: expect.any(Number),
+      repairable: ['settings.user.robota'],
+    });
+    expect(createProvider).not.toHaveBeenCalled();
+  });
+
+  it('renders host-selected product wording in the interactive command', async () => {
+    const fixture = createDoctorFixture({ env: {} });
+    fixtures.push(fixture);
+    installBrokenHome(fixture);
+    const command = createDoctorCommandModule(fixture.inputs, fixture.deps, {
+      title: 'Atlas doctor',
+      productName: 'Atlas',
+      formatRepairCommand: (id) => `atlas doctor --repair ${id}`,
+      repairOffer: 'run atlas doctor --repair <check-id>',
+    }).systemCommands![0]!;
+
+    const result = await command.execute(contextWith(undefined), '');
+    expect(result.message).toContain('Atlas doctor');
+    expect(result.message).toContain('Atlas');
+    expect(result.message).toContain('atlas doctor --repair settings.user.robota');
+    expect(result.message).toContain('run atlas doctor --repair <check-id>');
+  });
+
+  it('repair without an interaction port or with a cancelled answer writes nothing', async () => {
+    const fixture = createDoctorFixture({ env: {} });
+    fixtures.push(fixture);
+    installBrokenHome(fixture);
+    const path = join(fixture.home, '.robota', 'settings.json');
+    const command = createDoctorCommandModule(fixture.inputs, fixture.deps).systemCommands![0]!;
+
+    const noPort = await command.execute(contextWith(undefined), 'repair settings.user.robota');
+    expect(noPort.success).toBe(false);
+    expect(readFileSync(path, 'utf8')).toBe('');
+
+    const cancelled = answering({ type: 'cancelled' });
+    const declined = await command.execute(contextWith(cancelled), 'repair settings.user.robota');
+    expect(declined.success).toBe(false);
+    expect(cancelled.ask).toHaveBeenCalledTimes(1);
+    expect(readFileSync(path, 'utf8')).toBe('');
+
+    const usage = await command.execute(contextWith(cancelled), 'repair');
+    expect(usage.message).toContain('Usage');
+  });
+
+  it('repair with a confirmed answer applies the allowlisted writer and re-renders', async () => {
+    const fixture = createDoctorFixture({ env: {} });
+    fixtures.push(fixture);
+    installBrokenHome(fixture);
+    const path = join(fixture.home, '.robota', 'settings.json');
+    const command = createDoctorCommandModule(fixture.inputs, fixture.deps).systemCommands![0]!;
+    const yes = answering({ type: 'answer', values: ['yes'] });
+    const result = await command.execute(contextWith(yes), 'repair settings.user.robota');
+    expect(result.success).toBe(true);
+    expect(JSON.parse(readFileSync(path, 'utf8'))).toEqual({});
+    expect(result.data).toMatchObject({
+      repair: 'settings.user.robota',
+      applied: true,
+      status: 'ok',
+    });
+    expect(yes.ask.mock.calls[0]?.[0]).toMatchObject({ id: 'doctor-repair:settings.user.robota' });
+  });
+});