@robota-sdk/agent-command 3.0.0-beta.100

package/src/doctor/__tests__/doctor-runner.test.ts

@@ -0,0 +1,484 @@
+import { readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  createNodeHostSettingsSource,
+  createRestrictedWorkspaceProjectAccess,
+} from '@robota-sdk/agent-framework';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { renderDoctorReport } from '../doctor-render.js';
+import { applyDoctorRepair, planDoctorRepair } from '../doctor-repair.js';
+import { runDoctor } from '../doctor-runner.js';
+import {
+  MARKERS,
+  createDoctorFixture,
+  fixtureProviderDefinition,
+  installBrokenHome,
+} from './doctor-fixture.js';
+
+import type { IDoctorFixture } from './doctor-fixture.js';
+import type { IDoctorReport } from '../doctor-types.js';
+
+const fixtures: IDoctorFixture[] = [];
+afterEach(() => {
+  for (const fixture of fixtures.splice(0)) fixture.cleanup();
+});
+
+function fixture(...args: Parameters<typeof createDoctorFixture>): IDoctorFixture {
+  const created = createDoctorFixture(...args);
+  fixtures.push(created);
+  return created;
+}
+
+function byId(report: IDoctorReport, id: string) {
+  const check = report.checks.find((candidate) => candidate.id === id);
+  if (check === undefined)
+    throw new Error(`no check ${id}; have ${report.checks.map((c) => c.id).join(', ')}`);
+  return check;
+}
+
+const CLEAN_SETTINGS = {
+  currentProvider: 'doctor-env',
+  providers: {
+    'doctor-env': { type: 'fixture', model: 'fixture-model', apiKey: '$ENV:FIXTURE_DOCTOR_MARKER' },
+    'doctor-inactive': { type: 'fixture', model: 'fixture-model', apiKey: MARKERS.profile },
+  },
+};
+
+describe('runDoctor (OBSERVABILITY-1991)', () => {
+  it('uses neutral provider and trust guidance unless the host supplies its own commands', async () => {
+    const f = fixture({ env: {} });
+    const neutral = await runDoctor(f.inputs, f.deps);
+    expect(byId(neutral, 'provider.resolution').detail?.join(' ')).not.toMatch(/fixture-agent/i);
+    expect(byId(neutral, 'workspace.trust').detail?.join(' ')).not.toMatch(/fixture-agent/i);
+
+    const hosted = await runDoctor(
+      {
+        ...f.inputs,
+        diagnosticGuidance: {
+          providerResolution: 'Run atlas configure.',
+          projectTrust: 'Run atlas trust.',
+        },
+      },
+      f.deps,
+    );
+    expect(byId(hosted, 'provider.resolution').detail).toEqual(['Run atlas configure.']);
+    expect(byId(hosted, 'workspace.trust').detail).toEqual(['Run atlas trust.']);
+  });
+
+  it('shows each effective settings hook source without embedding payloads in provenance', async () => {
+    const f = fixture({ env: {} });
+    const userPath = f.write(
+      '.fixture-product/settings.json',
+      JSON.stringify({
+        disabledHooks: ['project-muted'],
+        hooks: {
+          PreToolUse: [{ matcher: '*', hooks: [{ type: 'command', command: 'user-private' }] }],
+        },
+      }),
+    );
+    const laterPath = f.write(
+      '.claude/settings.json',
+      JSON.stringify({
+        hooks: {
+          PreToolUse: [
+            { matcher: '*', hooks: [{ type: 'command', command: 'project-private' }] },
+            {
+              id: 'project-muted',
+              matcher: '*',
+              hooks: [{ type: 'prompt', prompt: 'muted-private' }],
+            },
+          ],
+        },
+      }),
+    );
+    const inputs = {
+      ...f.inputs,
+      settingsSources: [
+        createNodeHostSettingsSource('user', userPath),
+        createNodeHostSettingsSource('user', laterPath),
+      ],
+    };
+
+    const report = await runDoctor(inputs, f.deps);
+    const output = renderDoctorReport(report).join('\n');
+    const mergeDetail = byId(report, 'settings.merge').detail?.join('\n') ?? '';
+
+    expect(byId(report, 'settings.merge').detail).toContain(
+      `settings hook 1: PreToolUse/command ← ${userPath}`,
+    );
+    expect(byId(report, 'settings.merge').detail).toContain(
+      `settings hook 2: PreToolUse/command ← ${laterPath}`,
+    );
+    expect(output).toContain(`settings hook 1: PreToolUse/command ← ${userPath}`);
+    expect(output).toContain(`settings hook 2: PreToolUse/command ← ${laterPath}`);
+    expect(mergeDetail).not.toMatch(/private/);
+    expect(output).not.toContain('PreToolUse/prompt');
+  });
+
+  it('TC-05/TC-02: names every failing path and cause in the broken HOME and exits 1', async () => {
+    const f = fixture({ env: { FIXTURE_DOCTOR_MARKER: MARKERS.env } });
+    installBrokenHome(f);
+    const report = await runDoctor(f.inputs, f.deps);
+
+    expect(report.exitCode).toBe(1);
+    expect(byId(report, 'host.fixture').status).toBe('ok');
+    const user = byId(report, 'settings.user.fixture-product');
+    expect(user).toMatchObject({
+      status: 'fail',
+      cause: 'empty',
+      path: join(f.home, '.fixture-product', 'settings.json'),
+      repair: 'settings.user.fixture-product',
+    });
+    const claude = byId(report, 'settings.user.claude');
+    expect(claude.status).toBe('fail');
+    expect(claude.path).toBe(join(f.home, '.claude', 'settings.json'));
+    expect(claude.cause).toContain('schema-invalid');
+    expect(claude.cause).toContain('defaultTrustLevel');
+    expect(claude.cause).not.toContain('42');
+    expect(claude.repair).toBeUndefined();
+    expect(byId(report, 'settings.merge').status).toBe('warn');
+
+    const broken = byId(report, 'plugin.broken-plugin@fixture-market');
+    expect(broken.status).toBe('fail');
+    expect(broken.path).toContain(join('broken-plugin', '1.0.0', '.claude-plugin', 'plugin.json'));
+    const ghost = byId(report, 'mcp.plugin.mcp-plugin@fixture-market.ghost');
+    expect(ghost).toMatchObject({ status: 'warn' });
+    expect(ghost.cause).toContain('agent-test-doctor-missing-binary');
+    const declaration = byId(report, 'mcp.plugin.mcp-plugin@fixture-market.ready');
+    expect(declaration.status).toBe('warn');
+    expect(declaration.detail?.join(' ')).toContain('not a runtime source');
+    expect(byId(report, 'mcp.activation').status).toBe('not-configured');
+    expect(byId(report, 'mcp.connection').status).toBe('not-probed');
+    expect(byId(report, 'hooks.execution').status).toBe('not-probed');
+    expect(byId(report, 'storage.user').status).toBe('ok');
+    expect(byId(report, 'storage.project').status).toBe('not-configured');
+    expect(byId(report, 'workspace.trust').status).toBe('warn');
+    expect(report.repairable).toEqual(['settings.user.fixture-product']);
+  });
+
+  it('TC-03: no rendered line carries a marker secret from any input', async () => {
+    const f = fixture({ env: { FIXTURE_DOCTOR_MARKER: MARKERS.env } });
+    installBrokenHome(f);
+    // Overwrite the schema-invalid layer with a syntax error beside a secret (the parser-snippet case).
+    f.write('.claude/settings.json', `{"providers":{"x":{"apiKey": ${MARKERS.adjacent}}}}`);
+    const report = await runDoctor(f.inputs, f.deps);
+    const text = renderDoctorReport(report).join('\n');
+    for (const marker of Object.values(MARKERS)) expect(text).not.toContain(marker);
+    expect(byId(report, 'settings.user.claude').cause).toContain('invalid-json');
+  });
+
+  it('TC-03: masks the resolved credential and inactive-profile literals in a clean configuration', async () => {
+    const f = fixture({ env: { FIXTURE_DOCTOR_MARKER: MARKERS.env } });
+    f.mkdir('.fixture-product');
+    f.mkdir('.fixture-product/sessions');
+    f.write('.fixture-product/settings.json', JSON.stringify(CLEAN_SETTINGS));
+    const report = await runDoctor(f.inputs, f.deps);
+    const text = renderDoctorReport(report).join('\n');
+    expect(report.exitCode).toBe(0);
+    expect(text).not.toContain(MARKERS.env);
+    expect(text).not.toContain(MARKERS.profile);
+    expect(byId(report, 'provider.resolution').cause).toContain('fixture (fixture-model)');
+  });
+
+  it('TC-03: a parse error in a settings layer never renders the file excerpt around the fault', async () => {
+    const f = fixture({ env: {} });
+    f.mkdir('.fixture-product');
+    f.mkdir('.fixture-product/sessions');
+    // Unquoted value: JSON.parse's message quotes the bytes around the fault, i.e. the credential.
+    f.write(
+      '.fixture-product/settings.json',
+      `{"currentProvider":"p","providers":{"p":{"apiKey": ${MARKERS.adjacent}}}}`,
+    );
+    const report = await runDoctor(f.inputs, f.deps);
+    const text = renderDoctorReport(report, 'fixture-agent doctor').join('\n');
+    expect(text).not.toContain(MARKERS.adjacent);
+    expect(text).not.toContain(MARKERS.adjacent.slice(0, 10));
+    expect(text).not.toContain('..."');
+    expect(byId(report, 'provider.resolution')).toMatchObject({
+      status: 'fail',
+      cause: expect.stringContaining('SettingsParseError'),
+    });
+    expect(byId(report, 'settings.user.fixture-product')).toMatchObject({ status: 'fail' });
+  });
+
+  it('an unparseable user settings file is a failed plugin check, not a crash', async () => {
+    const f = fixture({ env: {} });
+    f.mkdir('.fixture-product');
+    f.mkdir('.fixture-product/sessions');
+    f.write('.fixture-product/settings.json', '{ "enabledPlugins": { "helper": false }, }');
+
+    const report = await runDoctor(f.inputs, f.deps);
+
+    expect(byId(report, 'plugins')).toMatchObject({
+      status: 'fail',
+      cause: expect.stringContaining('not valid JSON'),
+    });
+  });
+
+  it('TC-04: derives the reachability host from profile baseURL, then defaults.baseURL, then endpoint', async () => {
+    const profile = fixture({ env: {} });
+    profile.write(
+      '.fixture-product/settings.json',
+      JSON.stringify({
+        currentProvider: 'p',
+        providers: {
+          p: { type: 'fixture', model: 'm', apiKey: 'k1234', baseURL: 'http://127.0.0.1:9' },
+        },
+      }),
+    );
+    await runDoctor(profile.inputs, profile.deps);
+    expect(profile.probes).toEqual([{ host: '127.0.0.1', port: 9 }]);
+
+    const defaults = fixture({
+      env: {},
+      providerDefinitions: [
+        fixtureProviderDefinition({
+          defaults: { model: 'm', baseURL: 'https://compat.example/v1' },
+          endpoint: undefined,
+        }),
+      ],
+    });
+    defaults.write(
+      '.fixture-product/settings.json',
+      JSON.stringify({
+        currentProvider: 'p',
+        providers: { p: { type: 'fixture', model: 'm', apiKey: 'k1234' } },
+      }),
+    );
+    await runDoctor(defaults.inputs, defaults.deps);
+    expect(defaults.probes).toEqual([{ host: 'compat.example', port: 443 }]);
+
+    const endpoint = fixture({ env: {} });
+    endpoint.write(
+      '.fixture-product/settings.json',
+      JSON.stringify({
+        currentProvider: 'p',
+        providers: { p: { type: 'fixture', model: 'm', apiKey: 'k1234' } },
+      }),
+    );
+    const report = await runDoctor(endpoint.inputs, endpoint.deps);
+    expect(endpoint.probes).toEqual([{ host: 'api.fixture.example', port: 443 }]);
+    expect(byId(report, 'provider.reachability').cause).toContain('definition endpoint');
+
+    const none = fixture({
+      env: {},
+      providerDefinitions: [fixtureProviderDefinition({ endpoint: undefined })],
+    });
+    none.write(
+      '.fixture-product/settings.json',
+      JSON.stringify({
+        currentProvider: 'p',
+        providers: { p: { type: 'fixture', model: 'm', apiKey: 'k1234' } },
+      }),
+    );
+    const noneReport = await runDoctor(none.inputs, none.deps);
+    expect(none.probes).toEqual([]);
+    expect(byId(noneReport, 'provider.reachability')).toMatchObject({ status: 'warn' });
+  });
+
+  it('TC-04: an unreachable host is warn, not fail, so an offline doctor still exits 0', async () => {
+    const f = fixture({ env: {}, reachable: false });
+    f.mkdir('.fixture-product');
+    f.mkdir('.fixture-product/sessions');
+    f.write(
+      '.fixture-product/settings.json',
+      JSON.stringify({
+        currentProvider: 'p',
+        providers: { p: { type: 'fixture', model: 'm', apiKey: 'k1234' } },
+      }),
+    );
+    const report = await runDoctor(f.inputs, f.deps);
+    expect(byId(report, 'provider.reachability').status).toBe('warn');
+    expect(report.exitCode).toBe(0);
+  });
+
+  it('TC-05: a missing user storage root is warn and repairable; non-posix mode is not-probed', async () => {
+    const missing = fixture({ env: {} });
+    const report = await runDoctor(missing.inputs, missing.deps);
+    expect(byId(report, 'storage.user')).toMatchObject({ status: 'warn', repair: 'storage.user' });
+    expect(byId(report, 'provider.resolution').status).toBe('fail');
+
+    const win = fixture({ env: {}, guarantee: 'windows-acl' });
+    win.mkdir('.fixture-product');
+    win.mkdir('.fixture-product/sessions');
+    expect(byId(await runDoctor(win.inputs, win.deps), 'storage.user').status).toBe('not-probed');
+  });
+
+  it('TC-05: a too-open storage directory is warn and repairable', async () => {
+    const f = fixture({ env: {} });
+    f.mkdir('.fixture-product', 0o755);
+    f.mkdir('.fixture-product/sessions', 0o755);
+    const report = await runDoctor(f.inputs, f.deps);
+    expect(byId(report, 'storage.user')).toMatchObject({ status: 'warn', repair: 'storage.user' });
+  });
+
+  it('TC-07: repair rewrites only an empty user settings file, re-reads before writing, and is idempotent', async () => {
+    const f = fixture({ env: {} });
+    installBrokenHome(f);
+    const path = join(f.home, '.fixture-product', 'settings.json');
+
+    expect(planDoctorRepair('nope', f.inputs, f.deps)).toMatchObject({ ok: false });
+    expect(planDoctorRepair('settings.user.claude', f.inputs, f.deps)).toMatchObject({ ok: false });
+
+    const refused = await applyDoctorRepair(
+      'settings.user.fixture-product',
+      f.inputs,
+      f.deps,
+      async () => false,
+    );
+    expect(refused.applied).toBe(false);
+    expect(readFileSync(path, 'utf8')).toBe('');
+
+    // The state changes between confirmation and write: refused, nothing overwritten.
+    const raced = await applyDoctorRepair('settings.user.fixture-product', f.inputs, f.deps, async () => {
+      f.write('.fixture-product/settings.json', '{"language":"ko"}');
+      return true;
+    });
+    expect(raced).toMatchObject({ applied: false });
+    expect(readFileSync(path, 'utf8')).toBe('{"language":"ko"}');
+
+    f.write('.fixture-product/settings.json', '');
+    const applied = await applyDoctorRepair(
+      'settings.user.fixture-product',
+      f.inputs,
+      f.deps,
+      async () => true,
+    );
+    expect(applied.applied).toBe(true);
+    expect(JSON.parse(readFileSync(path, 'utf8'))).toEqual({});
+    expect(byId(await runDoctor(f.inputs, f.deps), 'settings.user.fixture-product').status).toBe('ok');
+
+    const again = await applyDoctorRepair(
+      'settings.user.fixture-product',
+      f.inputs,
+      f.deps,
+      async () => true,
+    );
+    expect(again).toMatchObject({ applied: false });
+  });
+
+  it('TC-07: storage repair creates owner-only directories and is refused once clean', async () => {
+    const f = fixture({ env: {} });
+    const applied = await applyDoctorRepair('storage.user', f.inputs, f.deps, async () => true);
+    expect(applied.applied).toBe(true);
+    expect(statSync(join(f.home, '.fixture-product', 'sessions')).mode & 0o077).toBe(0);
+    expect(byId(await runDoctor(f.inputs, f.deps), 'storage.user').status).toBe('ok');
+    expect(
+      await applyDoctorRepair('storage.user', f.inputs, f.deps, async () => true),
+    ).toMatchObject({ applied: false });
+  });
+
+  it('TC-05 (skills): a skill definition session discovery throws on is a fail check, not a warning', async () => {
+    const f = fixture({ env: {} });
+    f.mkdir('.fixture-product');
+    f.mkdir('.fixture-product/sessions');
+    f.write('.fixture-product/settings.json', JSON.stringify(CLEAN_SETTINGS));
+    f.write('.fixture-product/skills/bad-effort/SKILL.md', '---\nname: bad\neffort: extreme\n---\nbody\n');
+    f.write('.fixture-product/skills/no-frontmatter/SKILL.md', 'just text\n');
+    const report = await runDoctor(f.inputs, f.deps);
+    expect(
+      byId(report, `skill.${join('.fixture-product', 'skills', 'bad-effort', 'SKILL.md')}`),
+    ).toMatchObject({
+      status: 'fail',
+      cause: 'frontmatter-invalid',
+      detail: [expect.stringContaining('effort: expected one of')],
+    });
+    expect(JSON.stringify(report)).not.toContain('received "extreme"');
+    expect(
+      byId(report, `skill.${join('.fixture-product', 'skills', 'no-frontmatter', 'SKILL.md')}`).status,
+    ).toBe('warn');
+    expect(report.exitCode).toBe(1);
+  });
+
+  it('TC-05 (workspace.trust): a trust service that swallowed an error is a fail check naming the cause', async () => {
+    const f = fixture({ env: {} });
+    const report = await runDoctor(
+      {
+        ...f.inputs,
+        projectAccess: createRestrictedWorkspaceProjectAccess(
+          'store-unavailable',
+          f.home,
+          new RangeError('trust store is corrupt'),
+        ),
+      },
+      f.deps,
+    );
+    const trust = byId(report, 'workspace.trust');
+    expect(trust.status).toBe('fail');
+    expect(trust.cause).toBe('store-unavailable: RangeError: trust store is corrupt');
+    expect(trust.path).toBe(f.home);
+    expect(report.exitCode).toBe(1);
+
+    const untrusted = byId(await runDoctor(f.inputs, f.deps), 'workspace.trust');
+    expect(untrusted).toMatchObject({ status: 'warn', cause: 'untrusted' });
+  });
+
+  it('TC-05: reports the quarantined provider endpoint without printing either credential', async () => {
+    const f = fixture({ env: {} });
+    f.mkdir('.fixture-product');
+    f.mkdir('.fixture-product/sessions');
+    f.write(
+      '.fixture-product/settings.json',
+      JSON.stringify({
+        currentProvider: 'q',
+        providers: {
+          q: {
+            type: 'fixture',
+            model: 'm',
+            apiKey: MARKERS.profile,
+            baseURL: 'http://127.0.0.1:9',
+          },
+        },
+      }),
+    );
+    f.write(
+      '.claude/settings.json',
+      JSON.stringify({ providers: { q: { baseURL: 'http://127.0.0.1:10' } } }),
+    );
+    const report = await runDoctor(f.inputs, f.deps);
+    expect(byId(report, 'provider.security')).toMatchObject({
+      status: 'warn',
+      cause: expect.stringContaining('quarantined'),
+    });
+    const text = renderDoctorReport(report, 'fixture-agent doctor').join('\n');
+    expect(text).not.toContain(MARKERS.profile);
+    expect(text).toContain('[provider.security] warn');
+  });
+
+  it('a throwing endpoint probe is a provider fail check, not a rejected run', async () => {
+    const f = fixture({ env: {} });
+    f.mkdir('.fixture-product');
+    f.mkdir('.fixture-product/sessions');
+    f.write('.fixture-product/settings.json', JSON.stringify(CLEAN_SETTINGS));
+    const deps = {
+      ...f.deps,
+      probeEndpoint: () => Promise.reject(new RangeError('socket table exhausted')),
+    };
+    const report = await runDoctor(f.inputs, deps);
+    expect(byId(report, 'provider')).toMatchObject({
+      status: 'fail',
+      cause: expect.stringContaining('RangeError'),
+    });
+    expect(report.exitCode).toBe(1);
+  });
+
+  it('renders a composition failure as a fail check instead of crashing', async () => {
+    const f = fixture({ env: {} });
+    const report = await runDoctor(
+      {
+        ...f.inputs,
+        compositionFailure: {
+          id: 'workspace.composition',
+          label: 'Workspace composition',
+          status: 'fail',
+          cause: 'WorkspaceAuthorityRequiredError: boom',
+        },
+      },
+      f.deps,
+    );
+    expect(byId(report, 'workspace.composition').status).toBe('fail');
+    expect(report.exitCode).toBe(1);
+  });
+});

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

@@ -0,0 +1,132 @@
+import { createSystemCommandFromEntry } from '../command-module-utils.js';
+/**
+ * `/doctor` — the interactive surface of the same runner the shell route uses (OBSERVABILITY-1991).
+ *
+ * `/doctor` renders the report; `/doctor repair <check-id>` confirms through the host's user
+ * interaction port and treats an absent port or a cancelled answer as "nothing written". Neither
+ * form creates a provider turn or submits user input: the command reads and, on explicit
+ * confirmation, runs one allowlisted writer.
+ */
+import { confirmAction } from '@robota-sdk/agent-core';
+
+import { createNodeDoctorDeps } from './doctor-node-deps.js';
+import { renderDoctorReport } from './doctor-render.js';
+import { applyDoctorRepair } from './doctor-repair.js';
+import { runDoctor } from './doctor-runner.js';
+
+import type { IDoctorRepairPlan } from './doctor-repair.js';
+import type { IDoctorDisplayVocabulary } from './doctor-render.js';
+import type { IDoctorDeps, IDoctorInputs } from './doctor-types.js';
+import type {
+  ICommandHostUserInteraction,
+  ICommandModule,
+  ISystemCommand,
+} from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandResult, ICommandSource } from '@robota-sdk/agent-interface-command';
+
+export function createDoctorCommandEntry(): ICommand {
+  return {
+    name: 'doctor',
+    displayName: 'Doctor',
+    description:
+      'Diagnose configuration and runtime readiness; `repair <check-id>` applies an allowlisted fix',
+    source: 'doctor',
+    // User-only: install diagnostics and confirmed repairs that write settings are the user's.
+    modelInvocable: false,
+    userInvocable: true,
+    argumentHint: '[repair <check-id>]',
+  };
+}
+
+export class DoctorCommandSource implements ICommandSource {
+  readonly name = 'doctor';
+
+  getCommands(): ICommand[] {
+    return [createDoctorCommandEntry()];
+  }
+}
+
+async function confirmThroughHost(
+  context: ICommandHostUserInteraction,
+  plan: IDoctorRepairPlan,
+): Promise<boolean> {
+  const ui = context.getUserInteraction();
+  if (ui === undefined) return false;
+  const response = await ui.ask(
+    confirmAction(`doctor-repair:${plan.id}`, `Repair ${plan.id}?`, {
+      description: `${plan.description} (${plan.path})`,
+      defaultYes: false,
+    }),
+  );
+  return response.type === 'answer' && response.values[0] === 'yes';
+}
+
+async function executeRepair(
+  id: string,
+  inputs: IDoctorInputs,
+  deps: IDoctorDeps,
+  context: ICommandHostUserInteraction,
+  display: IDoctorDisplayVocabulary,
+): Promise<ICommandResult> {
+  const outcome = await applyDoctorRepair(id, inputs, deps, (plan) =>
+    confirmThroughHost(context, plan),
+  );
+  if (!outcome.applied) {
+    return { success: false, message: outcome.reason, data: { repair: id, applied: false } };
+  }
+  const report = await runDoctor(inputs, deps);
+  const check = report.checks.find((candidate) => candidate.id === id);
+  return {
+    success: true,
+    message: [
+      `Repaired ${id}: ${outcome.plan.description}.`,
+      ...renderDoctorReport(report, `${display.title ?? 'Doctor'} (after repair)`, display),
+    ].join('\n'),
+    data: { repair: id, applied: true, status: check?.status, exitCode: report.exitCode },
+  };
+}
+
+async function executeDoctorCommand(
+  inputs: IDoctorInputs,
+  deps: IDoctorDeps,
+  context: ICommandHostUserInteraction,
+  args: string,
+  display: IDoctorDisplayVocabulary,
+): Promise<ICommandResult> {
+  const [verb, target] = args.trim().split(/\s+/);
+  if (verb === 'repair') {
+    if (target === undefined || target.length === 0) {
+      return { success: false, message: 'Usage: /doctor repair <check-id>' };
+    }
+    return executeRepair(target, inputs, deps, context, display);
+  }
+  const report = await runDoctor(inputs, deps);
+  return {
+    success: report.failCount === 0,
+    message: renderDoctorReport(report, display.title, display).join('\n'),
+    data: {
+      failCount: report.failCount,
+      warnCount: report.warnCount,
+      repairable: [...report.repairable],
+    },
+  };
+}
+
+/** Register `/doctor` over the host-composed inputs; the host decides whether to supply them. */
+export function createDoctorCommandModule(
+  inputs: IDoctorInputs,
+  deps: IDoctorDeps = createNodeDoctorDeps({ ...inputs.env }),
+  display: IDoctorDisplayVocabulary = {},
+): ICommandModule {
+  const entry = createDoctorCommandEntry();
+  const command: ISystemCommand = createSystemCommandFromEntry(entry, {
+    requiresPermission: false,
+    lifecycle: 'inline',
+    execute: (context, args) => executeDoctorCommand(inputs, deps, context, args, display),
+  });
+  return {
+    name: 'agent-command-doctor',
+    commandSources: [new DoctorCommandSource()],
+    systemCommands: [command],
+  };
+}