Gate handoff session behind experiment

Add the experimental_handoff feature switch, wire /handoff session through the mobile handoff path, and cover the fork/clone/tree and handoff stories with focused tests.

Co-authored-by: Autohand Evolve <code-noreply@autohand.ai>

Author: igorcosta

src/commands/go.ts

@@ -26,6 +26,12 @@ export const metadata: SlashCommand = {
   implemented: true,
 };
 
+export const handoffSessionMetadata: SlashCommand = {
+  command: '/handoff session',
+  description: 'handoff this session to the Autohand Code iOS app',
+  implemented: true,
+};
+
 interface GoContext {
   sessionManager: SessionManager;
   currentSession?: Session;
@@ -37,7 +43,13 @@ interface GoContext {
   enqueueInstruction?: (instruction: string) => void;
 }
 
+interface HandoffSessionContext extends GoContext {
+  isFeatureEnabled?: (key: string, localDefault?: boolean) => boolean;
+  trackFeatureActivation?: (key: string, metadata?: Record<string, unknown>) => void | Promise<void>;
+}
+
 const MAX_MOBILE_SNAPSHOT_MESSAGES = 24;
+const HANDOFF_FLAG = 'experimental_handoff';
 
 type GoMode = 'queue' | 'steer';
 
@@ -212,3 +224,14 @@ export async function go(ctx: GoContext, args: string[] = []): Promise<string |
     ].join('\n');
   }
 }
+
+export async function handoffSession(ctx: HandoffSessionContext, args: string[] = []): Promise<string | null> {
+  const localDefault = ctx.config?.features?.experimentalHandoff === true;
+  const enabled = ctx.isFeatureEnabled?.(HANDOFF_FLAG, localDefault) ?? localDefault;
+  if (!enabled) {
+    return `The /handoff session command is behind ${HANDOFF_FLAG}. Run /features enable ${HANDOFF_FLAG}, then /handoff session again. No restart required.`;
+  }
+
+  await ctx.trackFeatureActivation?.(HANDOFF_FLAG, { surface: 'slash_command' });
+  return go(ctx, args);
+}

src/core/agent/AgentCommandRuntime.ts

@@ -206,7 +206,7 @@ export function parseAgentSlashCommand(_host: AgentCommandRuntimeHost, input: st
     const parts = trimmed.split(/\s+/);
 
     // Check for two-word commands like "/skills install", "/mcp install"
-    const twoWordCommands = ['/skills install', '/skills new', '/skills use', '/agents new', '/mcp install'];
+    const twoWordCommands = ['/skills install', '/skills new', '/skills use', '/agents new', '/mcp install', '/handoff session'];
     const potentialTwoWord = parts.slice(0, 2).join(' ');
 
     if (twoWordCommands.includes(potentialTwoWord)) {

src/core/slashCommandHandler.ts

@@ -250,6 +250,20 @@ export class SlashCommandHandler {
             enqueueInstruction: this.ctx.enqueueInstruction,
           }, args);
         }
+        case '/handoff session': {
+          const { handoffSession } = await import('../commands/go.js');
+          return handoffSession({
+            sessionManager: this.ctx.sessionManager,
+            currentSession: this.ctx.currentSession,
+            workspaceRoot: this.ctx.workspaceRoot,
+            model: this.ctx.model,
+            provider: this.ctx.provider,
+            config: this.ctx.config,
+            enqueueInstruction: this.ctx.enqueueInstruction,
+            isFeatureEnabled: this.ctx.isFeatureEnabled,
+            trackFeatureActivation: this.ctx.trackFeatureActivation,
+          }, args);
+        }
         case '/chrome': {
           const { chrome } = await import('../commands/chrome.js');
           return chrome(this.ctx, args);

src/core/slashCommands.ts

@@ -108,6 +108,7 @@ export const SLASH_COMMANDS: SlashCommand[] = ([
   automode.metadata,
   share.metadata,
   goCmd.metadata,
+  goCmd.handoffSessionMetadata,
   sync.metadata,
   addDir.metadata,
   language.metadata,

src/features/featureRegistry.ts

@@ -173,6 +173,14 @@ export const FEATURE_REGISTRY: readonly FeatureDefinition[] = [
     configPath: 'features.experimentalClone',
     defaultEnabled: false,
   },
+  {
+    id: 'experimental_handoff',
+    label: 'Experimental handoff',
+    description: 'Enable handoff session commands for continuing work from another Autohand surface.',
+    stage: 'experimental',
+    configPath: 'features.experimentalHandoff',
+    defaultEnabled: false,
+  },
   {
     id: 'chrome_integration',
     label: 'Chrome integration',

src/types.ts

@@ -316,6 +316,8 @@ export interface FeatureFlagSettings {
   experimentalFork?: boolean;
   /** Enable the experimental /clone session duplication surface. */
   experimentalClone?: boolean;
+  /** Enable the experimental /handoff session surface. */
+  experimentalHandoff?: boolean;
 }
 
 export type PermissionMode = 'interactive' | 'unrestricted' | 'restricted' | 'external';

tests/commands/features.test.ts

@@ -91,6 +91,21 @@ describe('/experiments command', () => {
     expect(mockSaveConfig).toHaveBeenCalledWith(config);
   });
 
+  it('lets users enable experimental_handoff without requiring restart', async () => {
+    const { features } = await import('../../src/commands/features.js');
+    const config = makeConfig({
+      features: {
+        experimentalHandoff: false,
+      },
+    });
+
+    const output = await features({ config }, ['enable', 'experimental_handoff']);
+
+    expect(output).toBe('Enabled experimental_handoff.');
+    expect(config.features?.experimentalHandoff).toBe(true);
+    expect(mockSaveConfig).toHaveBeenCalledWith(config);
+  });
+
   it('enables usage_v2 on the active config without requiring restart', async () => {
     const { features } = await import('../../src/commands/features.js');
     const { usage } = await import('../../src/commands/usage.js');

tests/commands/go.test.ts

@@ -5,7 +5,7 @@
  */
 import { describe, expect, it, vi } from 'vitest';
 import stripAnsi from 'strip-ansi';
-import { go } from '../../src/commands/go.js';
+import { go, handoffSession } from '../../src/commands/go.js';
 import { stopMobileRelay } from '../../src/mobile/MobileRelay.js';
 import type { MobileHandoffClientLike } from '../../src/mobile/MobileHandoffClient.js';
 import type { Session, SessionManager } from '../../src/session/SessionManager.js';
@@ -260,3 +260,71 @@ describe('/go command', () => {
     stopMobileRelay();
   });
 });
+
+describe('/handoff session command', () => {
+  it('stays behind experimental_handoff by default', async () => {
+    const client: MobileHandoffClientLike = {
+      getDeviceId: vi.fn(),
+      registerDevice: vi.fn(),
+      sendRelayHeartbeat: vi.fn(),
+      createPairing: vi.fn(),
+      claimWork: vi.fn(),
+    };
+
+    const result = await handoffSession({
+      sessionManager: createSessionManager(createSession()),
+      workspaceRoot: '/Users/test/project',
+      model: 'gpt-5.3-codex',
+      config: {
+        configPath: '/tmp/config.json',
+        auth: { token: 'token', user: { id: 'user-1', email: 'user@example.com', name: 'User' } },
+      },
+      client,
+    });
+
+    expect(stripAnsi(result || '')).toContain('experimental_handoff');
+    expect(client.createPairing).not.toHaveBeenCalled();
+  });
+
+  it('creates a handoff after experimental_handoff is enabled', async () => {
+    const client: MobileHandoffClientLike = {
+      getDeviceId: vi.fn().mockResolvedValue('device-1'),
+      registerDevice: vi.fn().mockResolvedValue(undefined),
+      sendRelayHeartbeat: vi.fn().mockResolvedValue(undefined),
+      createPairing: vi.fn().mockResolvedValue({
+        id: 'pairing-1',
+        pairingUrl: 'https://autohand.ai/code/go?pairing=pairing-1&token=secret',
+        expiresAt: '2026-05-13T00:10:00.000Z',
+        pollIntervalMs: 2000,
+        session: {
+          id: 'session-1',
+          deviceId: 'device-1',
+          workspacePath: '/Users/test/project',
+          projectName: 'project',
+          model: 'gpt-5.3-codex',
+          provider: 'openai',
+        },
+      }),
+      claimWork: vi.fn().mockResolvedValue(null),
+    };
+    const trackFeatureActivation = vi.fn();
+
+    const result = await handoffSession({
+      sessionManager: createSessionManager(createSession()),
+      workspaceRoot: '/Users/test/project',
+      model: 'gpt-5.3-codex',
+      provider: 'openai',
+      config: {
+        configPath: '/tmp/config.json',
+        features: { experimentalHandoff: true },
+        auth: { token: 'token', user: { id: 'user-1', email: 'user@example.com', name: 'User' } },
+      },
+      client,
+      trackFeatureActivation,
+    });
+
+    expect(stripAnsi(result || '')).toContain('Autohand Code mobile handoff');
+    expect(client.createPairing).toHaveBeenCalled();
+    expect(trackFeatureActivation).toHaveBeenCalledWith('experimental_handoff', { surface: 'slash_command' });
+  });
+});

tests/commands/sessionBranchingStories.test.ts

@@ -0,0 +1,88 @@
+/**
+ * @license
+ * Copyright 2026 Autohand AI LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cloneSession, forkSession, sessionTree } from '../../src/commands/sessionBranching.js';
+import { setFeatureState } from '../../src/features/featureRegistry.js';
+import { SessionManager, type Session } from '../../src/session/SessionManager.js';
+import type { SlashCommandContext } from '../../src/core/slashCommandTypes.js';
+import type { LoadedConfig } from '../../src/types.js';
+
+describe('session branching user stories', () => {
+  let tempDir: string;
+  let manager: SessionManager;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(path.join(os.tmpdir(), 'autohand-session-branching-story-'));
+    manager = new SessionManager(tempDir);
+    await manager.initialize();
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  it('lets a user enable fork and clone, branch from a real session, clone the branch, then inspect the tree', async () => {
+    const config: LoadedConfig = {
+      configPath: path.join(tempDir, 'config.json'),
+      provider: 'openrouter',
+    };
+    expect(setFeatureState(config, 'experimental_fork', true).ok).toBe(true);
+    expect(setFeatureState(config, 'experimental_clone', true).ok).toBe(true);
+
+    const source = await manager.createSession('/workspace/project', 'test-model');
+    await source.append({ role: 'user', content: 'Build the first version', timestamp: '2026-01-01T00:00:00.000Z' });
+    await source.append({ role: 'assistant', content: 'First version done', timestamp: '2026-01-01T00:00:01.000Z' });
+    await source.append({ role: 'user', content: 'Try the risky alternative', timestamp: '2026-01-01T00:00:02.000Z' });
+    await source.append({ role: 'assistant', content: 'Alternative done', timestamp: '2026-01-01T00:00:03.000Z' });
+
+    const restoredSessions: string[] = [];
+    const makeContext = (currentSession?: Session): SlashCommandContext => ({
+      promptModelSelection: vi.fn(),
+      createAgentsFile: vi.fn(),
+      resetConversation: vi.fn(),
+      sessionManager: manager,
+      currentSession,
+      memoryManager: {} as SlashCommandContext['memoryManager'],
+      permissionManager: {} as SlashCommandContext['permissionManager'],
+      llm: {} as SlashCommandContext['llm'],
+      workspaceRoot: '/workspace/project',
+      model: 'test-model',
+      config,
+      restoreSession: async (sessionId: string) => {
+        restoredSessions.push(sessionId);
+      },
+    });
+
+    const forkOutput = await forkSession(makeContext(source), ['2']);
+    const forked = manager.getCurrentSession();
+    expect(forked).toBeDefined();
+    expect(forkOutput).toContain('Forked session');
+    expect(forked?.getMessages().map((message) => message.content)).toEqual([
+      'Build the first version',
+      'First version done',
+      'Try the risky alternative',
+    ]);
+
+    const cloneOutput = await cloneSession(makeContext(forked));
+    const cloned = manager.getCurrentSession();
+    expect(cloned).toBeDefined();
+    expect(cloneOutput).toContain('Cloned session');
+    expect(cloned?.getMessages()).toEqual(forked?.getMessages());
+
+    const treeOutput = await sessionTree(makeContext(cloned));
+    expect(treeOutput).toContain(source.metadata.sessionId);
+    expect(treeOutput).toContain(forked!.metadata.sessionId);
+    expect(treeOutput).toContain(cloned!.metadata.sessionId);
+    expect(treeOutput).toContain('fork at user message 2');
+    expect(restoredSessions).toEqual([
+      forked!.metadata.sessionId,
+      cloned!.metadata.sessionId,
+    ]);
+  });
+});

tests/core/agent/AgentCommandRuntime.slashParsing.test.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2026 Autohand AI LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, expect, it } from 'vitest';
+import { parseAgentSlashCommand } from '../../../src/core/agent/AgentCommandRuntime.js';
+
+describe('parseAgentSlashCommand', () => {
+  it('parses /handoff session as a two-word command', () => {
+    const parsed = parseAgentSlashCommand({} as never, '/handoff session --queue');
+
+    expect(parsed).toEqual({
+      command: '/handoff session',
+      args: ['--queue'],
+    });
+  });
+});