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

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import type { ICommandHostContext } from '@robota-sdk/agent-framework';
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
 import {
   ExitCommandSource,
   createExitCommandEntry,
@@ -7,10 +7,14 @@ import {
   executeExitCommand,
 } from '../index.js';
 
-function contextWithAnswer(value: string): ICommandHostContext {
-  return {
-    getUserInteraction: () => ({ ask: async () => ({ type: 'answer', values: [value] }) }),
-  } as unknown as ICommandHostContext;
+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', () => {
@@ -31,24 +35,27 @@ describe('exit command module', () => {
   });
 
   it('proceeds to exit with no renderer attached (no human to confirm)', async () => {
-    const result = await executeExitCommand({} as never, '');
+    // 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.',
-      effects: [{ type: 'session-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.effects).toEqual([{ type: 'session-exit-requested' }]);
+    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.effects).toBeUndefined();
+    expect(result.hostActions).toBeUndefined();
   });
 });

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

@@ -3,7 +3,7 @@ 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-transport';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
 
 export function createExitCommandEntry(): ICommand {
   return {
@@ -11,6 +11,7 @@ export function createExitCommandEntry(): ICommand {
     displayName: 'Exit Session',
     description: EXIT_COMMAND_DESCRIPTION,
     source: 'exit',
+    // User-only: ending the session is the user's decision.
     modelInvocable: false,
   };
 }

package/src/exit/exit-command.ts

@@ -1,16 +1,16 @@
 import { confirmAction, isConfirmed } from '@robota-sdk/agent-core';
-import { createSessionExitRequestedEffect } from '@robota-sdk/agent-framework';
+import { createSessionExitHostAction } from '@robota-sdk/agent-framework';
 
-import type { ICommandHostContext } from '@robota-sdk/agent-framework';
-import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
+import type { ICommandHostUserInteraction } from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
 
 export async function executeExitCommand(
-  context: ICommandHostContext,
+  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?.();
+  const ui = context.getUserInteraction();
   if (ui) {
     const response = await ui.ask(confirmAction('exit', 'Exit the session?'));
     if (!isConfirmed(response)) {
@@ -21,6 +21,6 @@ export async function executeExitCommand(
   return {
     success: true,
     message: 'Exit requested.',
-    effects: [createSessionExitRequestedEffect()],
+    hostActions: [createSessionExitHostAction()],
   };
 }

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('robota');
+  });
+
+  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();
+  });
+});

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

@@ -0,0 +1,61 @@
+import { executeForkCommand } from './fork-command.js';
+
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
+
+export function createForkCommandEntry(): ICommand {
+  return {
+    name: 'fork',
+    displayName: 'Fork Session',
+    description:
+      'Copy this conversation into a new background session and keep working here. ' +
+      'The fork inherits the whole conversation and the assembled system prompt; it is a copy, ' +
+      'so nothing it does reaches this session and it never merges back.',
+    source: 'fork',
+    // The model does not decide to duplicate the operator's conversation. Forking spends a second
+    // session's budget and creates a second worktree, both of which are the operator's call.
+    // User-only: starts a separate session the user owns and attaches to.
+    modelInvocable: false,
+    argumentHint: '[name] [--same-dir]',
+  };
+}
+
+function createForkSystemCommand(
+  formatResumeCommand?: (sessionId: string) => string,
+): ISystemCommand {
+  const entry = createForkCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: false,
+    lifecycle: 'inline',
+    ...(entry.argumentHint !== undefined ? { argumentHint: entry.argumentHint } : {}),
+    // `ICommandHostContext` aggregates both role ports `/fork` declares, so the narrowing is the
+    // parameter's own type — no assertion, and a role the command stops satisfying is a build error.
+    execute: (context, args) => executeForkCommand(context, args, formatResumeCommand),
+  };
+}
+
+export class ForkCommandSource implements ICommandSource {
+  readonly name = 'fork';
+
+  getCommands(): ICommand[] {
+    return [createForkCommandEntry()];
+  }
+}
+
+export function createForkCommandModule(
+  formatResumeCommand?: (sessionId: string) => string,
+): ICommandModule {
+  return {
+    name: 'agent-command-fork',
+    commandSources: [new ForkCommandSource()],
+    systemCommands: [createForkSystemCommand(formatResumeCommand)],
+    // A fork is a background agent job resuming a session record; a host with no agent runtime has
+    // neither half, so the command is not offered rather than offered and refused.
+    sessionRequirements: ['agent-runtime'],
+  };
+}

package/src/fork/fork-command.ts

@@ -0,0 +1,162 @@
+/**
+ * `/fork [name] [--same-dir]` (CLI-1994, issue #1994) — copy this conversation into a background
+ * session and keep working here.
+ *
+ * The two halves are deliberately separate calls to two different capabilities, because they are two
+ * different facts. `forkSession` writes a COPY of the live conversation as a new session record: the
+ * messages, the parent's assembled system message, the tool schemas and the transcript, under a
+ * fresh id and a name that is not the parent's. Spawning then starts a background agent job that
+ * carries ONLY that id — the conversation never rides on the request, so it never crosses the
+ * child-process wire (ARCH-044); the child reads the record from the session store, exactly as the
+ * startup `--fork-session` does.
+ *
+ * A fork is a copy, not a branch of one live thing: from the moment the record is written, work in
+ * the fork and work here are two histories that never rejoin. Attaching to the fork later (the
+ * background panel's `attach` control) switches the terminal's VIEW to that session; it does not
+ * merge anything back.
+ */
+
+import type { ICommandHostAgentJobs, ICommandHostSessionAccess } from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+import type { TBackgroundTaskIsolation } from '@robota-sdk/agent-interface-execution';
+
+/** What `/fork` needs from its host: the copy-writer and the job dispatcher. */
+export type TForkCommandContext = ICommandHostSessionAccess & ICommandHostAgentJobs;
+
+/**
+ * The fork runs in its own worktree by DEFAULT.
+ *
+ * A spawned job inherits the parent's cwd, so a fork that keeps working in the same directory writes
+ * over the files the parent is still editing — the "work in it does not affect the original"
+ * property lost through the filesystem rather than through the conversation. `--same-dir` is the
+ * explicit opt-out for a fork that is meant to read and think rather than to edit.
+ */
+const DEFAULT_ISOLATION: TBackgroundTaskIsolation = 'worktree';
+const SAME_DIR_ISOLATION: TBackgroundTaskIsolation = 'none';
+const SAME_DIR_FLAG = '--same-dir';
+
+/** The agent a forked conversation continues under — the general one, since the fork IS the context. */
+const FORK_AGENT_TYPE = 'general-purpose';
+
+/**
+ * The fork's first turn input.
+ *
+ * A fork inherits the parent's whole conversation and its assembled system message, so there is
+ * nothing left to brief it about — this is a minimal continuation cue, deliberately NOT a prompt.
+ * § Solution 5 asked for an empty string; a turn with no user content is rejected by providers, and
+ * one word is the smallest thing that is not — the divergence is recorded in the spec beside it. Anything longer would be this neutral command layer
+ * deciding how a forked agent should behave, which is the product layer's call
+ * (`scan-prompt-prose` is the mechanical form of that rule).
+ */
+const FORK_FIRST_TURN = 'Continue.';
+
+export interface IParsedForkArgs {
+  readonly name: string | undefined;
+  readonly isolation: TBackgroundTaskIsolation;
+}
+
+/** A rejected argument string, kept distinct from a parse so neither can be read as the other. */
+export interface IForkArgsError {
+  readonly error: string;
+}
+
+/**
+ * `--same-dir` may appear anywhere; everything else is the name.
+ *
+ * An unrecognised `--flag` is REFUSED rather than folded into the name: a mistyped `--same-dr` that
+ * became a session called "--same-dr" would silently give the operator a worktree they asked not to
+ * have, and the name is the one field they will later use to find the fork.
+ */
+export function parseForkArgs(args: string): IParsedForkArgs | IForkArgsError {
+  const tokens = args
+    .trim()
+    .split(/\s+/)
+    .filter((token) => token.length > 0);
+  const unknownFlag = tokens.find((token) => token.startsWith('--') && token !== SAME_DIR_FLAG);
+  if (unknownFlag !== undefined) {
+    return { error: `Unknown option: ${unknownFlag}\nUsage: /fork [name] [${SAME_DIR_FLAG}]` };
+  }
+  const nameTokens = tokens.filter((token) => token !== SAME_DIR_FLAG);
+  return {
+    name: nameTokens.length > 0 ? nameTokens.join(' ') : undefined,
+    isolation: tokens.includes(SAME_DIR_FLAG) ? SAME_DIR_ISOLATION : DEFAULT_ISOLATION,
+  };
+}
+
+function formatError<TError>(error: TError): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function describeFork(name: string, taskId: string, isolation: TBackgroundTaskIsolation): string {
+  const where = isolation === SAME_DIR_ISOLATION ? 'in this directory' : 'in its own worktree';
+  return [
+    `Forked this conversation into "${name}" (${taskId}), running ${where}.`,
+    'The fork is a copy: this session keeps going, and the two are separate records.',
+    'See its progress with /background list. Attaching from the background panel points this',
+    "terminal at the copy as it was forked; the fork's own turns stay in its task transcript.",
+  ].join('\n');
+}
+
+/**
+ * The copy is on disk and the job is not. Both facts are reported, because the record is still
+ * resumable by name and an operator told only "failed" would not know that.
+ */
+function describeSpawnFailure(
+  fork: { sessionId: string; name: string },
+  reason: string,
+  formatResumeCommand?: (sessionId: string) => string,
+): string {
+  const resumeHint = formatResumeCommand?.(fork.sessionId);
+  return (
+    `The fork "${fork.name}" was written (${fork.sessionId}) but its background job could not ` +
+    `start: ${reason}\n${resumeHint === undefined ? 'Resume the saved session through your host.' : `Resume it in a new terminal with: ${resumeHint}`}`
+  );
+}
+
+export async function executeForkCommand(
+  context: TForkCommandContext,
+  args = '',
+  formatResumeCommand?: (sessionId: string) => string,
+): Promise<ICommandResult> {
+  const parsed = parseForkArgs(args);
+  if ('error' in parsed) return { message: parsed.error, success: false };
+
+  const jobs = context.getAgentJobCapability();
+  if (!jobs) {
+    return {
+      message: 'This session cannot start background jobs, so it cannot run a fork.',
+      success: false,
+    };
+  }
+
+  // The copy is written FIRST, and a failure here is reported without spawning: a job that resumes a
+  // record which was never written is a child that fails on its own far side, out of the operator's
+  // sight.
+  let fork: { sessionId: string; name: string };
+  try {
+    fork = await context.forkSession(parsed.name !== undefined ? { name: parsed.name } : {});
+  } catch (error) {
+    return { message: `Could not fork this session: ${formatError(error)}`, success: false };
+  }
+
+  try {
+    const state = await jobs.spawnAgentJob({
+      agentType: FORK_AGENT_TYPE,
+      label: fork.name,
+      mode: 'background',
+      prompt: FORK_FIRST_TURN,
+      isolation: parsed.isolation,
+      resumeSessionId: fork.sessionId,
+    });
+    return {
+      message: describeFork(fork.name, state.id, parsed.isolation),
+      success: true,
+      data: { sessionId: fork.sessionId, name: fork.name, taskId: state.id },
+    };
+  } catch (error) {
+    return {
+      message: describeSpawnFailure(fork, formatError(error), formatResumeCommand),
+      success: false,
+    };
+  }
+}

package/src/fork/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Only the module factory leaves this directory — the same rule the sibling `src/peers/` follows.
+ *
+ * `executeForkCommand`, `parseForkArgs` and `ForkCommandSource` are how the module is BUILT, not how
+ * it is used: `/fork` is registered by default, so nothing outside constructs one. Exporting them
+ * would add entries to this package's frozen undocumented-surface count for a reach nobody asked for.
+ */
+export { createForkCommandModule } from './fork-command-module.js';

package/src/git/__tests__/fake-git-port.ts

@@ -0,0 +1,28 @@
+/** A scripted `IGitProcessPort`: answers by argv, records every call, throws on an unscripted one. */
+import type { IGitProcessPort, TGitProcessOutcome } from '../git-process.js';
+
+export interface IFakeGitPort extends IGitProcessPort {
+  readonly calls: readonly (readonly string[])[];
+}
+
+export function exited(stdout: string, exitCode = 0, stderr = ''): TGitProcessOutcome {
+  return { kind: 'exited', stdout, stderr, exitCode };
+}
+
+export function fakeGitPort(
+  script: Readonly<
+    Record<string, TGitProcessOutcome | ((args: readonly string[]) => TGitProcessOutcome)>
+  >,
+): IFakeGitPort {
+  const calls: (readonly string[])[] = [];
+  return {
+    calls,
+    async run(args) {
+      calls.push([...args]);
+      const key = args.join(' ');
+      const entry = script[key];
+      if (entry === undefined) throw new Error(`unscripted git call: ${key}`);
+      return typeof entry === 'function' ? entry(args) : entry;
+    },
+  };
+}

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

@@ -0,0 +1,103 @@
+/** BEHAVIOR-2437 TC-05 — registration, the descriptor, and the verb parse through the real session. */
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { scriptedSession, type ScriptedSessionHarness } from '@robota-sdk/agent-framework/testing';
+
+import { createDefaultCommandModules } from '../../default/default-command-modules.js';
+import { createHelpCommandModule } from '../../help/help-command-module.js';
+import {
+  createGitCommandEntry,
+  createGitCommandModule,
+  executeGitCommand,
+} from '../git-command-module.js';
+
+import { exited, fakeGitPort } from './fake-git-port.js';
+
+import type { IProviderDefinition } from '@robota-sdk/agent-core';
+import type {
+  IProviderCommandSettingsAdapter,
+  TProviderSettingsDocument,
+} from '@robota-sdk/agent-framework';
+
+const providerDefinitions: readonly IProviderDefinition[] = [
+  {
+    type: 'anthropic',
+    defaults: { model: 'claude-sonnet-4-6', apiKey: '$ENV:ANTHROPIC_API_KEY' },
+    setupSteps: [{ key: 'apiKey', title: 'anthropic API key', masked: true }],
+    requiresApiKey: true,
+    createProvider: () => {
+      throw new Error('not used');
+    },
+  },
+];
+const providerSettingsAdapter: IProviderCommandSettingsAdapter = {
+  readMergedSettings: () => ({}) as TProviderSettingsDocument,
+  readTargetSettings: () => ({}) as TProviderSettingsDocument,
+  writeTargetSettings: () => undefined,
+};
+const BASE_OPTIONS = { cwd: '/tmp', userLocalStorageRoot: '/tmp/robota-test', providerDefinitions, providerSettingsAdapter } as const;
+
+const STATUS_FIXTURE = '# branch.head main\0? scratch.log\0';
+
+let h: ScriptedSessionHarness | undefined;
+afterEach(async () => {
+  await h?.dispose();
+  h = undefined;
+});
+
+describe('the /git descriptor', () => {
+  it('is host-only, with the three verbs as descriptive subcommands', () => {
+    const entry = createGitCommandEntry();
+    expect(entry.name).toBe('git');
+    expect(entry.modelInvocable).toBe(false);
+    expect(entry.subcommands?.map((s) => s.name)).toEqual(['status', 'diff', 'commit']);
+    const module = createGitCommandModule({ port: fakeGitPort({}) });
+    expect(module.name).toBe('agent-command-git');
+    expect(module.systemCommands?.[0]).toMatchObject({
+      name: 'git',
+      requiresPermission: true,
+      modelInvocable: false,
+      lifecycle: 'blocking',
+    });
+  });
+
+  it('is in the base list, and the name `status` is registered nowhere', () => {
+    const { modules } = createDefaultCommandModules(BASE_OPTIONS);
+    expect(modules.map((m) => m.name)).toContain('agent-command-git');
+    const names = modules.flatMap((m) => (m.systemCommands ?? []).map((c) => c.name));
+    expect(names).toContain('git');
+    expect(names).not.toContain('status');
+  });
+});
+
+describe('executeGitCommand verb parse', () => {
+  const context = { getCwd: () => '/r', getUserInteraction: () => undefined };
+
+  it('routes status, refuses arguments to it, and refuses unknown or missing verbs', async () => {
+    const port = fakeGitPort({ 'status --porcelain=v2 -z --branch': exited(STATUS_FIXTURE) });
+    expect((await executeGitCommand(context, '  status ', port)).message).toContain(
+      'On branch main',
+    );
+    expect((await executeGitCommand(context, 'status extra', port)).success).toBe(false);
+    const unknown = await executeGitCommand(context, 'push', port);
+    expect(unknown.success).toBe(false);
+    expect(unknown.message).toContain('push');
+    expect((await executeGitCommand(context, '', port)).message).toContain('Usage: /git');
+    expect(port.calls).toHaveLength(1);
+  });
+});
+
+describe('/git through the real session', () => {
+  it('/help lists /git, and /git status answers through the injected port', async () => {
+    const port = fakeGitPort({ 'status --porcelain=v2 -z --branch': exited(STATUS_FIXTURE) });
+    h = scriptedSession({
+      turns: [{ text: 'unused' }],
+      commandModules: [createHelpCommandModule(), createGitCommandModule({ port })],
+    });
+    const help = await h.command('help');
+    expect(help?.message).toContain('/git');
+    const status = await h.command('git', 'status');
+    expect(status?.success).toBe(true);
+    expect(status?.message).toContain('untracked (1): scratch.log');
+  });
+});