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

package/src/effort/effort-command.ts

@@ -0,0 +1,136 @@
+import { MODEL_EFFORT_VALUES, selectAction } from '@robota-sdk/agent-core';
+import { EFFORT_LEVEL_LABELS, parseModelEffort, resolveModelEffort } from '@robota-sdk/agent-framework';
+
+import type {
+  ICommandHostAdapterAccess,
+  ICommandHostAdapters,
+  ICommandHostSessionAccess,
+  ICommandHostUserInteraction,
+  ICommandHostWorkspace,
+  IModelEffortResolution,
+  TEffortSelection,
+} from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+
+const EFFORT_SELECTIONS: readonly TEffortSelection[] = ['auto', ...MODEL_EFFORT_VALUES];
+
+/**
+ * #3282 §2 — re-exported for callers already importing it from here; the canonical definition moved
+ * to `agent-framework` (`effort/effort-resolution.ts`) so headless `/goal` output (in that same
+ * package) can use the same labels without a circular dependency on `agent-command`.
+ */
+export { EFFORT_LEVEL_LABELS };
+
+/**
+ * Plain outcome text (#3282 §2), replacing the earlier `Model effort: requested=…, effective=…,
+ * source=…, disposition=…` internal-field dump. `not-applied` means the model has no matching native
+ * control at all — the earlier fields carried no information a person could act on for that case, so
+ * it gets its own plain sentence instead of a label.
+ */
+function formatEffortMessage(resolution: {
+  requested: TEffortSelection;
+  disposition: string;
+}): string {
+  if (resolution.disposition === 'not-applied') {
+    return "This model doesn't support effort levels, so it will use its default.";
+  }
+  return `Effort: ${EFFORT_LEVEL_LABELS[resolution.requested]}`;
+}
+
+async function askForEffort(
+  context: ICommandHostUserInteraction,
+): Promise<TEffortSelection | undefined> {
+  const interaction = context.getUserInteraction();
+  if (interaction === undefined) return undefined;
+  const response = await interaction.ask(
+    selectAction(
+      'effort',
+      'Select model effort',
+      EFFORT_SELECTIONS.map((value) => ({ value, label: EFFORT_LEVEL_LABELS[value] })),
+    ),
+  );
+  const selected = response.type === 'answer' ? response.values[0] : undefined;
+  return parseModelEffort(selected, '/effort');
+}
+
+function readCurrentResolution(
+  context: ICommandHostAdapterAccess & ICommandHostSessionAccess,
+): IModelEffortResolution {
+  const adapter = context.getCommandHostAdapters?.().effort;
+  if (adapter !== undefined) return adapter.getResolution();
+  const selection = context.getSession().getModelEffort();
+  return resolveModelEffort({
+    command: selection,
+    modelDefault: selection === 'auto' ? 'high' : selection,
+  });
+}
+
+function readAdapters(context: ICommandHostAdapterAccess): ICommandHostAdapters {
+  return context.getCommandHostAdapters?.() ?? {};
+}
+
+function persistEffortSelection(
+  context: ICommandHostAdapterAccess,
+  selection: TEffortSelection,
+): void {
+  const settings = readAdapters(context).settings;
+  if (settings === undefined || selection === 'max') return;
+  const current = settings.read();
+  if (selection === 'auto') {
+    const { effort: _effort, ...withoutEffort } = current;
+    settings.write(withoutEffort);
+    return;
+  }
+  settings.write({ ...current, effort: selection });
+}
+
+export async function executeEffortCommand(
+  context: ICommandHostAdapterAccess &
+    ICommandHostSessionAccess &
+    ICommandHostUserInteraction &
+    ICommandHostWorkspace,
+  args: string,
+): Promise<ICommandResult> {
+  let selection: TEffortSelection | undefined;
+  try {
+    selection = parseModelEffort(args.trim() || undefined, '/effort');
+    if (selection === undefined) selection = await askForEffort(context);
+  } catch (error) {
+    return { message: error instanceof Error ? error.message : String(error), success: false };
+  }
+
+  const current = readCurrentResolution(context);
+  if (selection === undefined) {
+    return {
+      message: formatEffortMessage(current),
+      success: true,
+      data: { effort: current },
+    };
+  }
+
+  const adapter = readAdapters(context).effort;
+  let resolution;
+  try {
+    resolution =
+      adapter === undefined
+        ? resolveModelEffort({ command: selection, modelDefault: current.effective })
+        : await adapter.apply(selection, context.getSession());
+    if (adapter === undefined) {
+      await context.getSession().applyModelOptions({ effort: selection });
+    }
+    if (context.getCommandInvocationSource() === 'user') {
+      persistEffortSelection(context, selection);
+    }
+  } catch (error) {
+    return {
+      message: `Model effort was not applied: ${error instanceof Error ? error.message : String(error)}`,
+      success: false,
+    };
+  }
+
+  return {
+    message: formatEffortMessage(resolution),
+    success: true,
+    data: { effort: resolution },
+  };
+}

package/src/effort/index.ts

@@ -0,0 +1,6 @@
+export {
+  createEffortCommandEntry,
+  createEffortCommandModule,
+  EffortCommandSource,
+} from './effort-command-module.js';
+export { executeEffortCommand } from './effort-command.js';

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/exit/__tests__/exit-command-module.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest';
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
+import {
+  ExitCommandSource,
+  createExitCommandEntry,
+  createExitCommandModule,
+  executeExitCommand,
+} from '../index.js';
+
+function contextWithAnswer(value: string) {
+  // The double answers "no capability of that kind" by default; this fixture states the one
+  // capability it exercises, so the precondition is declared rather than inherited.
+  return createTestCommandHost({
+    overrides: {
+      getUserInteraction: () => ({ ask: async () => ({ type: 'answer', values: [value] }) }),
+    },
+  });
+}
+
+describe('exit command module', () => {
+  it('provides command metadata and executable registration from one module', () => {
+    const entry = createExitCommandEntry();
+    const module = createExitCommandModule();
+
+    expect(entry).toEqual({
+      name: 'exit',
+      displayName: 'Exit Session',
+      description: 'Exit CLI',
+      source: 'exit',
+      modelInvocable: false,
+    });
+    expect(new ExitCommandSource().getCommands()).toEqual([entry]);
+    expect(module.systemCommands?.map((command) => command.name)).toEqual(['exit']);
+    expect(module.commandSources?.flatMap((source) => source.getCommands())).toEqual([entry]);
+  });
+
+  it('proceeds to exit with no renderer attached (no human to confirm)', async () => {
+    // ARCH-029 TC-09: "no renderer attached" is a VALUE — `getUserInteraction()` returns undefined —
+    // not an absent member. `{} as never` expressed it as absence, which the required member no
+    // longer permits, and the double's default answers exactly this case.
+    const result = await executeExitCommand(createTestCommandHost(), '');
+
+    expect(result).toEqual({
+      success: true,
+      message: 'Exit requested.',
+      hostActions: [{ type: 'session-exit' }],
+    });
+  });
+
+  it('confirms before exiting and proceeds on yes (CMD-004)', async () => {
+    const result = await executeExitCommand(contextWithAnswer('yes'), '');
+    expect(result.hostActions).toEqual([{ type: 'session-exit' }]);
+  });
+
+  it('cancels the exit when the user declines (CMD-004)', async () => {
+    const result = await executeExitCommand(contextWithAnswer('no'), '');
+    expect(result.success).toBe(true);
+    expect(result.message).toBe('Exit cancelled.');
+    expect(result.hostActions).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,47 @@
+import { EXIT_COMMAND_DESCRIPTION } from '@robota-sdk/agent-framework';
+
+import { executeExitCommand } from './exit-command.js';
+
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
+
+export function createExitCommandEntry(): ICommand {
+  return {
+    name: 'exit',
+    displayName: 'Exit Session',
+    description: EXIT_COMMAND_DESCRIPTION,
+    source: 'exit',
+    // User-only: ending the session is the user's decision.
+    modelInvocable: false,
+  };
+}
+
+function createExitSystemCommand(): ISystemCommand {
+  const entry = createExitCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: true,
+    userInvocable: true,
+    modelInvocable: false,
+    lifecycle: 'inline',
+    execute: executeExitCommand,
+  };
+}
+
+export class ExitCommandSource implements ICommandSource {
+  readonly name = 'exit';
+
+  getCommands(): ICommand[] {
+    return [createExitCommandEntry()];
+  }
+}
+
+export function createExitCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-exit',
+    commandSources: [new ExitCommandSource()],
+    systemCommands: [createExitSystemCommand()],
+  };
+}

package/src/exit/exit-command.ts

@@ -0,0 +1,26 @@
+import { confirmAction, isConfirmed } from '@robota-sdk/agent-core';
+import { createSessionExitHostAction } from '@robota-sdk/agent-framework';
+
+import type { ICommandHostUserInteraction } from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+
+export async function executeExitCommand(
+  context: ICommandHostUserInteraction,
+  _args: string,
+): Promise<ICommandResult> {
+  // Confirm only when an interactive renderer is attached. With no human (headless/automation) the
+  // user explicitly invoked /exit, so proceed — the confirm is an interactive safety prompt, not a gate.
+  const ui = context.getUserInteraction();
+  if (ui) {
+    const response = await ui.ask(confirmAction('exit', 'Exit the session?'));
+    if (!isConfirmed(response)) {
+      return { success: true, message: 'Exit cancelled.' };
+    }
+  }
+
+  return {
+    success: true,
+    message: 'Exit requested.',
+    hostActions: [createSessionExitHostAction()],
+  };
+}

package/src/exit/index.ts

@@ -0,0 +1,6 @@
+export {
+  ExitCommandSource,
+  createExitCommandEntry,
+  createExitCommandModule,
+} from './exit-command-module.js';
+export { executeExitCommand } from './exit-command.js';

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

@@ -0,0 +1,184 @@
+/**
+ * CLI-1994 TC-07 — what `/fork` actually does to its host.
+ *
+ * The command is the only place the two halves of a fork meet: the session writes the COPY, and the
+ * job that resumes it carries the copy's id and nothing else. What these cases pin is that pairing —
+ * the copy is written exactly once, the job that follows names it, and a failure to write the copy
+ * stops there rather than spawning a child that will look for a record nobody wrote.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { executeForkCommand } from '../fork-command.js';
+
+import type { ICommandHostAgentJobs, ICommandHostSessionAccess } from '@robota-sdk/agent-framework';
+import type { ISubagentJobState } from '@robota-sdk/agent-interface-execution';
+
+const FORK_SESSION_ID = 'session_cli-1994-fork';
+const DEFAULT_FORK_NAME = 'parent-work (fork)';
+const TASK_ID = 'agent_1';
+
+const JOB_STATE = {
+  id: TASK_ID,
+  type: 'general-purpose',
+  label: DEFAULT_FORK_NAME,
+  parentSessionId: 'session_parent',
+  status: 'running',
+  mode: 'background',
+  depth: 1,
+  cwd: '/workspace',
+  promptPreview: 'forked',
+  updatedAt: '2026-09-07T00:00:00.000Z',
+} as unknown as ISubagentJobState;
+
+interface IForkHost {
+  readonly context: ICommandHostSessionAccess & ICommandHostAgentJobs;
+  readonly forkSession: ReturnType<typeof vi.fn>;
+  readonly spawnAgentJob: ReturnType<typeof vi.fn>;
+}
+
+/** The two capabilities `/fork` reads, and nothing else the command never touches. */
+function createForkHost(options?: {
+  readonly forkSession?: ReturnType<typeof vi.fn>;
+  readonly spawnAgentJob?: ReturnType<typeof vi.fn>;
+  readonly withoutAgentJobs?: boolean;
+}): IForkHost {
+  const forkSession =
+    options?.forkSession ??
+    vi.fn().mockResolvedValue({ sessionId: FORK_SESSION_ID, name: DEFAULT_FORK_NAME });
+  const spawnAgentJob = options?.spawnAgentJob ?? vi.fn().mockResolvedValue(JOB_STATE);
+  const context = {
+    forkSession,
+    getAgentJobCapability: () =>
+      options?.withoutAgentJobs === true ? undefined : { spawnAgentJob },
+  } as unknown as ICommandHostSessionAccess & ICommandHostAgentJobs;
+  return { context, forkSession, spawnAgentJob };
+}
+
+describe('/fork writes the copy and starts the job that resumes it (CLI-1994 TC-07)', () => {
+  it('forks once, then spawns a background job carrying the returned id and a worktree', async () => {
+    const host = createForkHost();
+
+    const result = await executeForkCommand(host.context, '');
+
+    expect(host.forkSession).toHaveBeenCalledTimes(1);
+    expect(host.forkSession).toHaveBeenCalledWith({});
+    expect(host.spawnAgentJob).toHaveBeenCalledTimes(1);
+    expect(host.spawnAgentJob).toHaveBeenCalledWith(
+      expect.objectContaining({
+        mode: 'background',
+        isolation: 'worktree',
+        resumeSessionId: FORK_SESSION_ID,
+        label: DEFAULT_FORK_NAME,
+      }),
+    );
+    // The conversation is NOT on the request — only the id it was written under.
+    const request = host.spawnAgentJob.mock.calls[0]?.[0] as Record<string, unknown>;
+    expect(Object.keys(request)).not.toContain('messages');
+    expect(Object.keys(request)).not.toContain('seedMessages');
+    // The operator is told both names they will need: the new session and the task.
+    expect(result.success).toBe(true);
+    expect(result.message).toContain(DEFAULT_FORK_NAME);
+    expect(result.message).toContain(TASK_ID);
+    expect(result.data).toEqual({
+      sessionId: FORK_SESSION_ID,
+      name: DEFAULT_FORK_NAME,
+      taskId: TASK_ID,
+    });
+  });
+
+  it('`/fork my-branch` passes the operator name through to the copy', async () => {
+    const host = createForkHost({
+      forkSession: vi.fn().mockResolvedValue({ sessionId: FORK_SESSION_ID, name: 'my-branch' }),
+    });
+
+    const result = await executeForkCommand(host.context, 'my-branch');
+
+    expect(host.forkSession).toHaveBeenCalledWith({ name: 'my-branch' });
+    expect(host.spawnAgentJob).toHaveBeenCalledWith(
+      expect.objectContaining({ label: 'my-branch', resumeSessionId: FORK_SESSION_ID }),
+    );
+    expect(result.message).toContain('my-branch');
+  });
+
+  it('`/fork --same-dir` opts out of the worktree, and still names the copy by default', async () => {
+    const host = createForkHost();
+
+    const result = await executeForkCommand(host.context, '--same-dir');
+
+    expect(host.forkSession).toHaveBeenCalledWith({});
+    expect(host.spawnAgentJob).toHaveBeenCalledWith(expect.objectContaining({ isolation: 'none' }));
+    expect(result.message).toContain('in this directory');
+  });
+
+  it('`/fork name --same-dir` reads as both — the flag is not part of the name', async () => {
+    const host = createForkHost({
+      forkSession: vi.fn().mockResolvedValue({ sessionId: FORK_SESSION_ID, name: 'experiment' }),
+    });
+
+    await executeForkCommand(host.context, 'experiment --same-dir');
+
+    expect(host.forkSession).toHaveBeenCalledWith({ name: 'experiment' });
+    expect(host.spawnAgentJob).toHaveBeenCalledWith(expect.objectContaining({ isolation: 'none' }));
+  });
+
+  it('a forkSession rejection is reported and NO job is spawned', async () => {
+    const host = createForkHost({
+      forkSession: vi.fn().mockRejectedValue(new Error('this session has no session store')),
+    });
+
+    const result = await executeForkCommand(host.context, '');
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('this session has no session store');
+    expect(host.spawnAgentJob).not.toHaveBeenCalled();
+  });
+
+  it('a spawn failure still names the written copy, so the operator can resume it by hand', async () => {
+    const host = createForkHost({
+      spawnAgentJob: vi.fn().mockRejectedValue(new Error('depth limit reached')),
+    });
+
+    const result = await executeForkCommand(host.context, '');
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('depth limit reached');
+    expect(result.message).toContain(FORK_SESSION_ID);
+    expect(result.message).not.toContain('fixture-agent');
+  });
+
+  it('renders a host-selected resume command after a fork spawn failure', async () => {
+    const host = createForkHost({
+      spawnAgentJob: vi.fn().mockRejectedValue(new Error('depth limit reached')),
+    });
+
+    const result = await executeForkCommand(
+      host.context,
+      '',
+      (sessionId) => `atlas --resume ${sessionId}`,
+    );
+
+    expect(result.message).toContain(`atlas --resume ${FORK_SESSION_ID}`);
+  });
+
+  it('a host with no agent runtime refuses before writing anything', async () => {
+    const host = createForkHost({ withoutAgentJobs: true });
+
+    const result = await executeForkCommand(host.context, '');
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('cannot start background jobs');
+    expect(host.forkSession).not.toHaveBeenCalled();
+  });
+
+  it('a mistyped flag is refused rather than becoming the session name', async () => {
+    const host = createForkHost();
+
+    const result = await executeForkCommand(host.context, '--same-dr');
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('Unknown option: --same-dr');
+    expect(host.forkSession).not.toHaveBeenCalled();
+    expect(host.spawnAgentJob).not.toHaveBeenCalled();
+  });
+});