xtrm-cli 0.5.0

package/src/index.ts

@@ -0,0 +1,87 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { Command } from 'commander';
+import kleur from 'kleur';
+
+// __dirname is available in CJS output (tsup target: cjs)
+declare const __dirname: string;
+let version = '0.0.0';
+try { version = JSON.parse(readFileSync(resolve(__dirname, '../package.json'), 'utf8')).version; } catch { /* fallback */ }
+
+import { createInstallCommand } from './commands/install.js';
+import { createClaudeCommand } from './commands/claude.js';
+import { createPiCommand } from './commands/pi.js';
+import { runProjectInit } from './commands/init.js';
+import { createStatusCommand } from './commands/status.js';
+import { createResetCommand } from './commands/reset.js';
+import { createHelpCommand } from './commands/help.js';
+import { createCleanCommand } from './commands/clean.js';
+import { createFinishCommand } from './commands/finish.js';
+import { createEndCommand } from './commands/end.js';
+import { createWorktreeCommand } from './commands/worktree.js';
+import { printBanner } from './utils/banner.js';
+
+const program = new Command();
+
+program
+    .name('xtrm')
+    .description('Claude Code tools installer (skills, hooks, MCP servers)')
+    .version(version);
+
+// Add exit override for cleaner unknown command error
+program.exitOverride((err) => {
+    if (err.code === 'commander.unknownCommand') {
+        console.error(kleur.red(`\n✗ Unknown command. Run 'xtrm --help'\n`));
+        process.exit(1);
+    }
+    // Preserve exit code for help (0) and version (0); default to 1 for real errors
+    process.exit(err.exitCode ?? 1);
+});
+
+// Main commands
+program.addCommand(createInstallCommand());
+program.addCommand(createClaudeCommand());
+program.addCommand(createPiCommand());
+program
+    .command('init')
+    .description('Alias for xtrm project init')
+    .action(async () => {
+        await runProjectInit();
+    });
+program.addCommand(createStatusCommand());
+program.addCommand(createResetCommand());
+program.addCommand(createCleanCommand());
+program.addCommand(createFinishCommand());
+program.addCommand(createEndCommand());
+program.addCommand(createWorktreeCommand());
+program.addCommand(createHelpCommand());
+
+// Default action: show help
+program
+    .action(async () => {
+        program.help();
+    });
+
+// Global error handlers
+process.on('uncaughtException', (err) => {
+    if ((err as any).code?.startsWith('commander.')) {
+        return;
+    }
+    console.error(kleur.red(`\n✗ ${err.message}\n`));
+    process.exit(1);
+});
+
+process.on('unhandledRejection', (reason) => {
+    console.error(kleur.red(`\n✗ ${String(reason)}\n`));
+    process.exit(1);
+});
+
+// Show startup banner unless --help or --version flag is present
+const isHelpOrVersion = process.argv.some(a => a === '--help' || a === '-h' || a === '--version' || a === '-V');
+
+(async () => {
+    if (!isHelpOrVersion) {
+        await printBanner(version);
+    }
+    program.parseAsync(process.argv);
+})();

package/src/tests/policy-parity.test.ts

@@ -0,0 +1,204 @@
+/**
+ * Cross-runtime policy parity tests (79m)
+ *
+ * Verifies that:
+ * 1. Each policy file passes structural validation
+ * 2. Policies with runtime:both have both Claude hooks and Pi extension metadata
+ * 3. All referenced hook scripts and Pi extension files exist on disk
+ * 4. The policy compiler produces up-to-date hooks/hooks.json (--check passes)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync, existsSync, readdirSync, mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join, resolve, basename } from 'node:path';
+import { tmpdir } from 'node:os';
+import { spawnSync } from 'node:child_process';
+
+// Resolve repo root from cli/src/tests/
+const ROOT = resolve(__dirname, '..', '..', '..');
+const POLICIES_DIR = join(ROOT, 'policies');
+
+interface PolicyHook {
+  event: string;
+  matcher?: string;
+  command: string;
+  timeout?: number;
+}
+
+interface Policy {
+  id: string;
+  description: string;
+  version: string;
+  runtime?: 'claude' | 'pi' | 'both';
+  order?: number;
+  claude?: { hooks: PolicyHook[] };
+  pi?: { extension: string; events?: string[] };
+}
+
+// Load all policies (skip schema.json)
+const policyFiles = readdirSync(POLICIES_DIR)
+  .filter(f => f.endsWith('.json') && f !== 'schema.json')
+  .sort();
+
+const policies: Array<{ file: string; policy: Policy }> = policyFiles.map(file => ({
+  file,
+  policy: JSON.parse(readFileSync(join(POLICIES_DIR, file), 'utf8')) as Policy,
+}));
+
+
+// ── Structural validation ─────────────────────────────────────────────────────
+
+describe('policy structure', () => {
+  it.each(policyFiles)('%s has required fields', (file) => {
+    const { policy } = policies.find(p => p.file === file)!;
+    expect(policy.id, 'missing id').toBeTruthy();
+    expect(policy.description, 'missing description').toBeTruthy();
+    expect(policy.version, 'missing version').toBeTruthy();
+  });
+
+  it.each(policyFiles)('%s has valid runtime value', (file) => {
+    const { policy } = policies.find(p => p.file === file)!;
+    const validRuntimes = ['claude', 'pi', 'both', undefined];
+    expect(validRuntimes).toContain(policy.runtime);
+  });
+
+  it.each(policyFiles)('%s has at least one runtime target', (file) => {
+    const { policy } = policies.find(p => p.file === file)!;
+    const hasClaude = (policy.claude?.hooks?.length ?? 0) > 0;
+    const hasPi = !!policy.pi?.extension;
+    expect(hasClaude || hasPi, 'policy has no claude hooks and no pi extension').toBe(true);
+  });
+});
+
+// ── Cross-runtime parity ──────────────────────────────────────────────────────
+
+const bothPolicies = policies.filter(({ policy }) => policy.runtime === 'both');
+
+describe('runtime:both parity', () => {
+  it('at least one policy targets both runtimes', () => {
+    expect(bothPolicies.length).toBeGreaterThan(0);
+  });
+
+  it.each(bothPolicies.map(p => p.file))('%s has claude.hooks', (file) => {
+    const { policy } = policies.find(p => p.file === file)!;
+    expect(policy.claude?.hooks?.length ?? 0).toBeGreaterThan(0);
+  });
+
+  it.each(bothPolicies.map(p => p.file))('%s has pi.extension', (file) => {
+    const { policy } = policies.find(p => p.file === file)!;
+    expect(policy.pi?.extension, 'runtime:both policy missing pi.extension').toBeTruthy();
+  });
+});
+
+// ── Matcher macro expansion parity ────────────────────────────────────────────
+
+describe('matcher macro expansion parity', () => {
+  it('compiled hooks contain no unresolved matcher macros', () => {
+    const compiledHooks = JSON.parse(readFileSync(join(ROOT, 'hooks', 'hooks.json'), 'utf8'));
+    const allGroups = Object.values(compiledHooks?.hooks ?? {}).flat() as Array<{ matcher?: string }>;
+    const unresolved = allGroups.filter((group) => typeof group.matcher === 'string' && group.matcher.includes('$'));
+    expect(unresolved, 'found unresolved matcher macros in hooks/hooks.json').toHaveLength(0);
+  });
+});
+
+// ── File existence ────────────────────────────────────────────────────────────
+
+describe('referenced files exist', () => {
+  // Resolve ${CLAUDE_PLUGIN_ROOT}/hooks/foo.mjs → hooks/foo.mjs (repo-relative)
+  const resolveCommand = (command: string): string =>
+    command.replace('node ${CLAUDE_PLUGIN_ROOT}/', '').replace('python3 ${CLAUDE_PLUGIN_ROOT}/', '');
+
+  const allHooks = policies.flatMap(({ file, policy }) =>
+    (policy.claude?.hooks ?? []).map(hook => ({ file, command: hook.command })),
+  );
+
+  it.each(allHooks)('$file: command "$command" references existing file', ({ command }) => {
+    const relativePath = resolveCommand(command);
+    const absolutePath = join(ROOT, relativePath);
+    expect(existsSync(absolutePath), `Hook script not found: ${relativePath}`).toBe(true);
+  });
+
+  const piPolicies = policies.filter(({ policy }) => policy.pi?.extension);
+
+  it.each(piPolicies.map(p => p.file))('%s: pi.extension file exists', (file) => {
+    const { policy } = policies.find(p => p.file === file)!;
+    const absPath = join(ROOT, policy.pi!.extension);
+    expect(existsSync(absPath), `Pi extension not found: ${policy.pi!.extension}`).toBe(true);
+  });
+});
+
+describe('pi extension guard-rules imports', () => {
+  it('main-guard and adapter use shared guard-rules constants', () => {
+    const mainGuard = readFileSync(join(ROOT, 'config', 'pi', 'extensions', 'main-guard.ts'), 'utf8');
+    const adapter = readFileSync(join(ROOT, 'config', 'pi', 'extensions', 'core', 'adapter.ts'), 'utf8');
+
+    expect(mainGuard).toContain('from "./core/guard-rules"');
+    expect(adapter).toContain('from "./guard-rules"');
+
+    expect(mainGuard).not.toMatch(/^\s*const\s+SAFE_BASH_PREFIXES\s*=\s*\[/m);
+    expect(mainGuard).not.toMatch(/^\s*const\s+DANGEROUS_BASH_PATTERNS\s*=\s*\[/m);
+    expect(adapter).not.toMatch(/const\s+tools\s*=\s*\[/m);
+  });
+});
+
+// ── Compiler consistency ──────────────────────────────────────────────────────
+
+describe('compiler', () => {
+  it('hooks/hooks.json is up to date with policies/', () => {
+    const result = spawnSync(
+      'node',
+      [join(ROOT, 'scripts', 'compile-policies.mjs'), '--check'],
+      { cwd: ROOT, encoding: 'utf8' },
+    );
+    expect(
+      result.status,
+      `hooks.json drift detected — run: npm run compile-policies\n${result.stdout}${result.stderr}`,
+    ).toBe(0);
+  });
+
+  it('--check-pi validates policy-declared extension deployment set', () => {
+    const tmpAgent = mkdtempSync(join(tmpdir(), 'xtrm-pi-agent-'));
+    const tmpExtDir = join(tmpAgent, 'extensions');
+    mkdirSync(tmpExtDir, { recursive: true });
+
+    try {
+      const declared = policies
+        .filter(({ policy }) => ['pi', 'both'].includes(policy.runtime ?? 'both'))
+        .map(({ policy }) => policy.pi?.extension)
+        .filter(Boolean) as string[];
+
+      for (const rel of declared) {
+        const src = join(ROOT, rel);
+        const dst = join(tmpExtDir, basename(rel));
+        writeFileSync(dst, readFileSync(src));
+      }
+
+      const result = spawnSync(
+        'node',
+        [join(ROOT, 'scripts', 'compile-policies.mjs'), '--check-pi'],
+        {
+          cwd: ROOT,
+          encoding: 'utf8',
+          env: { ...process.env, PI_AGENT_DIR: tmpAgent },
+        },
+      );
+
+      expect(result.status, `check-pi failed:\n${result.stdout}${result.stderr}`).toBe(0);
+    } finally {
+      rmSync(tmpAgent, { recursive: true, force: true });
+    }
+  });
+
+  it('all policy ids are unique', () => {
+    const ids = policies.map(({ policy }) => policy.id);
+    const unique = new Set(ids);
+    expect(unique.size).toBe(ids.length);
+  });
+
+  it('policy order values are unique or explicitly equal', () => {
+    // Multiple policies can share an order value — just document it
+    const orders = policies.map(({ file, policy }) => ({ file, order: policy.order ?? 50 }));
+    // No assertion — informational only, logged to help debug ordering issues
+    expect(orders.length).toBeGreaterThan(0);
+  });
+});

package/src/tests/session-flow-parity.test.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync, existsSync, mkdtempSync, mkdirSync, writeFileSync, chmodSync, rmSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+
+const ROOT = path.resolve(__dirname, '..', '..', '..');
+const HOOKS_DIR = path.join(ROOT, 'hooks');
+
+function runHook(hookFile: string, input: Record<string, unknown>, env: Record<string, string> = {}) {
+  return spawnSync('node', [path.join(HOOKS_DIR, hookFile)], {
+    input: JSON.stringify(input),
+    encoding: 'utf8',
+    env: { ...process.env, ...env },
+  });
+}
+
+function withFakeBdDir(scriptBody: string) {
+  const tempDir = mkdtempSync(path.join(os.tmpdir(), 'xtrm-fakebd-'));
+  const fakeBdPath = path.join(tempDir, 'bd');
+  writeFileSync(fakeBdPath, scriptBody, { encoding: 'utf8' });
+  chmodSync(fakeBdPath, 0o755);
+  return { tempDir, fakeBdPath };
+}
+
+describe('session-flow policy parity', () => {
+  it('declares runtime:both with Claude hooks and Pi extension', () => {
+    const policy = JSON.parse(readFileSync(path.join(ROOT, 'policies', 'session-flow.json'), 'utf8'));
+    expect(policy.runtime).toBe('both');
+    expect(policy.order).toBeLessThan(20); // must run before beads stop memory gate
+    expect(policy.claude?.hooks?.length).toBeGreaterThan(0);
+    expect(policy.pi?.extension).toBe('config/pi/extensions/session-flow.ts');
+    expect(existsSync(path.join(ROOT, policy.pi.extension))).toBe(true);
+  });
+
+  it('compiled hooks run stop gate before memory gate', () => {
+    const hooks = JSON.parse(readFileSync(path.join(ROOT, 'hooks', 'hooks.json'), 'utf8'));
+    const stopGroups = hooks?.hooks?.Stop ?? [];
+    const commands: string[] = stopGroups.flatMap((g: any) => (g.hooks ?? []).map((h: any) => String(h.command)));
+    const stopIdx = commands.findIndex((c) => c.includes('beads-stop-gate.mjs'));
+    const memIdx = commands.findIndex((c) => c.includes('beads-memory-gate.mjs'));
+    expect(stopIdx).toBeGreaterThanOrEqual(0);
+    expect(memIdx).toBeGreaterThanOrEqual(0);
+    expect(stopIdx).toBeLessThan(memIdx);
+  });
+
+  it('Claude stop hook enforces phase blocking contract', () => {
+    const projectDir = mkdtempSync(path.join(os.tmpdir(), 'xtrm-session-flow-stop-'));
+    mkdirSync(path.join(projectDir, '.beads'));
+
+    const fake = withFakeBdDir(`#!/usr/bin/env bash
+set -euo pipefail
+if [[ "$1" == "kv" && "$2" == "get" ]]; then exit 1; fi
+if [[ "$1" == "list" ]]; then
+  cat <<'EOF'
+
+--------------------------------------------------------------------------------
+Total: 0 issues (0 open, 0 in progress)
+EOF
+  exit 0
+fi
+exit 1
+`);
+
+    try {
+      const cases = [
+        { phase: 'waiting-merge', blocked: true },
+        { phase: 'pending-cleanup', blocked: true },
+        { phase: 'conflicting', blocked: true },
+        { phase: 'cleanup-done', blocked: false },
+      ];
+
+      for (const c of cases) {
+        writeFileSync(path.join(projectDir, '.xtrm-session-state.json'), JSON.stringify({
+          issueId: 'jaggers-agent-tools-1xa2',
+          branch: 'feature/jaggers-agent-tools-1xa2',
+          worktreePath: '/tmp/worktrees/jaggers-agent-tools-1xa2',
+          prNumber: 101,
+          prUrl: 'https://example.invalid/pr/101',
+          phase: c.phase,
+          conflictFiles: c.phase === 'conflicting' ? ['src/a.ts'] : [],
+          startedAt: new Date().toISOString(),
+          lastChecked: new Date().toISOString(),
+        }), 'utf8');
+
+        const r = runHook(
+          'beads-stop-gate.mjs',
+          { hook_event_name: 'Stop', session_id: 'parity-session', cwd: projectDir },
+          { PATH: `${fake.tempDir}:${process.env.PATH ?? ''}` },
+        );
+
+        if (c.blocked) {
+          expect(r.status, `expected block for ${c.phase}`).toBe(2);
+        } else {
+          expect(r.status, `expected allow for ${c.phase}`).toBe(0);
+        }
+      }
+    } finally {
+      rmSync(fake.tempDir, { recursive: true, force: true });
+      rmSync(projectDir, { recursive: true, force: true });
+    }
+  });
+
+  it('Pi extension encodes same phase guards and claim detection semantics', () => {
+    const src = readFileSync(path.join(ROOT, 'config', 'pi', 'extensions', 'session-flow.ts'), 'utf8');
+
+    // claim detection path
+    expect(src).toContain('bd\\s+update');
+    expect(src).toContain('--claim');
+
+    // phase parity with Claude stop-gate
+    expect(src).toContain('waiting-merge');
+    expect(src).toContain('pending-cleanup');
+    expect(src).toContain('conflicting');
+    expect(src).toContain('phase1-done');
+    expect(src).toContain('xtrm finish');
+  });
+});

package/src/tests/session-state.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect } from 'vitest';
+import { mkdtempSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+import {
+  findSessionStateFile,
+  readSessionState,
+  writeSessionState,
+  updateSessionPhase,
+} from '../core/session-state.js';
+
+describe('session-state.ts', () => {
+  it('returns null when no state file exists', () => {
+    const dir = mkdtempSync(path.join(os.tmpdir(), 'xtrm-session-state-none-'));
+    try {
+      expect(findSessionStateFile(dir)).toBeNull();
+      expect(readSessionState(dir)).toBeNull();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('writes and reads state roundtrip', () => {
+    const dir = mkdtempSync(path.join(os.tmpdir(), 'xtrm-session-state-roundtrip-'));
+    try {
+      writeSessionState({
+        issueId: 'jaggers-agent-tools-1xa2',
+        branch: 'feature/jaggers-agent-tools-1xa2',
+        worktreePath: '/tmp/worktrees/jaggers-agent-tools-1xa2',
+        prNumber: null,
+        prUrl: null,
+        phase: 'claimed',
+        conflictFiles: [],
+        startedAt: new Date().toISOString(),
+        lastChecked: new Date().toISOString(),
+      }, dir);
+
+      const state = readSessionState(dir);
+      expect(state).not.toBeNull();
+      expect(state?.issueId).toBe('jaggers-agent-tools-1xa2');
+      expect(state?.phase).toBe('claimed');
+      expect(Array.isArray(state?.conflictFiles)).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('findSessionStateFile walks up directory tree', () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'xtrm-session-state-walk-'));
+    const nested = path.join(root, 'a', 'b', 'c');
+    mkdirSync(nested, { recursive: true });
+
+    try {
+      writeSessionState({
+        issueId: 'walk-1',
+        branch: 'feature/walk-1',
+        worktreePath: '/tmp/worktrees/walk-1',
+        prNumber: null,
+        prUrl: null,
+        phase: 'claimed',
+        conflictFiles: [],
+        startedAt: new Date().toISOString(),
+        lastChecked: new Date().toISOString(),
+      }, root);
+
+      const found = findSessionStateFile(nested);
+      expect(found).toBe(path.join(root, '.xtrm-session-state.json'));
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('enforces phase transition validation', () => {
+    const dir = mkdtempSync(path.join(os.tmpdir(), 'xtrm-session-state-phase-'));
+    try {
+      writeSessionState({
+        issueId: 'phase-1',
+        branch: 'feature/phase-1',
+        worktreePath: '/tmp/worktrees/phase-1',
+        prNumber: null,
+        prUrl: null,
+        phase: 'claimed',
+        conflictFiles: [],
+        startedAt: new Date().toISOString(),
+        lastChecked: new Date().toISOString(),
+      }, dir);
+
+      const waiting = updateSessionPhase('waiting-merge', dir, { prNumber: 12 });
+      expect(waiting.phase).toBe('waiting-merge');
+
+      const done = updateSessionPhase('cleanup-done', dir);
+      expect(done.phase).toBe('cleanup-done');
+
+      expect(() => updateSessionPhase('claimed', dir)).toThrow(/Invalid phase transition/);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('updates persisted file on phase changes', () => {
+    const dir = mkdtempSync(path.join(os.tmpdir(), 'xtrm-session-state-persist-'));
+    try {
+      writeSessionState({
+        issueId: 'persist-1',
+        branch: 'feature/persist-1',
+        worktreePath: '/tmp/worktrees/persist-1',
+        prNumber: null,
+        prUrl: null,
+        phase: 'claimed',
+        conflictFiles: [],
+        startedAt: new Date().toISOString(),
+        lastChecked: new Date().toISOString(),
+      }, dir);
+
+      updateSessionPhase('conflicting', dir, { conflictFiles: ['src/core.ts'] });
+      const raw = JSON.parse(readFileSync(path.join(dir, '.xtrm-session-state.json'), 'utf8'));
+      expect(raw.phase).toBe('conflicting');
+      expect(raw.conflictFiles).toContain('src/core.ts');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/tests/xtrm-finish.test.ts

@@ -0,0 +1,148 @@
+import { describe, it, expect } from 'vitest';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync, chmodSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+
+import { runXtrmFinish } from '../core/xtrm-finish.js';
+
+function initRepo(dir: string) {
+  spawnSync('git', ['init'], { cwd: dir, stdio: 'pipe' });
+  spawnSync('git', ['config', 'user.email', 'test@example.com'], { cwd: dir, stdio: 'pipe' });
+  spawnSync('git', ['config', 'user.name', 'Test User'], { cwd: dir, stdio: 'pipe' });
+  writeFileSync(path.join(dir, 'README.md'), '# test\n', 'utf8');
+  spawnSync('git', ['add', 'README.md'], { cwd: dir, stdio: 'pipe' });
+  spawnSync('git', ['commit', '-m', 'init'], { cwd: dir, stdio: 'pipe' });
+}
+
+describe('runXtrmFinish', () => {
+  it('fails when session state file is missing', async () => {
+    const dir = mkdtempSync(path.join(os.tmpdir(), 'xtrm-finish-none-'));
+    try {
+      const result = await runXtrmFinish({ cwd: dir, pollIntervalMs: 1, timeoutMs: 5 });
+      expect(result.ok).toBe(false);
+      expect(result.message).toContain('.xtrm-session-state.json');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('re-entrant waiting-merge path reaches cleanup-done on merged PR', async () => {
+    const dir = mkdtempSync(path.join(os.tmpdir(), 'xtrm-finish-merge-'));
+    const fakeDir = path.join(dir, 'fakebin');
+    mkdirSync(fakeDir, { recursive: true });
+    initRepo(dir);
+
+    writeFileSync(path.join(dir, '.xtrm-session-state.json'), JSON.stringify({
+      issueId: 'jaggers-agent-tools-1xa2',
+      branch: 'feature/jaggers-agent-tools-1xa2',
+      worktreePath: '/tmp/nonexistent-worktree-path',
+      prNumber: 42,
+      prUrl: 'https://example.invalid/pr/42',
+      phase: 'waiting-merge',
+      conflictFiles: [],
+      startedAt: new Date().toISOString(),
+      lastChecked: new Date().toISOString(),
+    }), 'utf8');
+
+    const ghPath = path.join(fakeDir, 'gh');
+    writeFileSync(ghPath, `#!/usr/bin/env bash\nset -euo pipefail\nif [[ "$1" == "pr" && "$2" == "view" ]]; then\n  echo '{"state":"MERGED","mergeStateStatus":"CLEAN","mergeable":"MERGEABLE"}'\n  exit 0\nfi\nexit 1\n`);
+    chmodSync(ghPath, 0o755);
+
+    const oldPath = process.env.PATH;
+    process.env.PATH = `${fakeDir}:${oldPath ?? ''}`;
+    try {
+      const result = await runXtrmFinish({ cwd: dir, pollIntervalMs: 1, timeoutMs: 20 });
+      expect(result.ok).toBe(true);
+      expect(result.message).toContain('merged');
+      const state = JSON.parse(readFileSync(path.join(dir, '.xtrm-session-state.json'), 'utf8'));
+      expect(state.phase).toBe('cleanup-done');
+    } finally {
+      process.env.PATH = oldPath;
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('uses claimed worktree path for gh/git phase steps when run from repo root', async () => {
+    const dir = mkdtempSync(path.join(os.tmpdir(), 'xtrm-finish-worktree-cwd-'));
+    const fakeDir = path.join(dir, 'fakebin');
+    mkdirSync(fakeDir, { recursive: true });
+    initRepo(dir);
+
+    const worktreePath = path.join(dir, '.worktrees', 'jaggers-agent-tools-1xa2');
+    spawnSync('git', ['worktree', 'add', worktreePath, '-b', 'feature/jaggers-agent-tools-1xa2'], {
+      cwd: dir,
+      stdio: 'pipe',
+    });
+
+    writeFileSync(path.join(dir, '.xtrm-session-state.json'), JSON.stringify({
+      issueId: 'jaggers-agent-tools-1xa2',
+      branch: 'feature/jaggers-agent-tools-1xa2',
+      worktreePath,
+      prNumber: 77,
+      prUrl: 'https://example.invalid/pr/77',
+      phase: 'waiting-merge',
+      conflictFiles: [],
+      startedAt: new Date().toISOString(),
+      lastChecked: new Date().toISOString(),
+    }), 'utf8');
+
+    const markerPath = path.join(dir, 'gh-cwd.txt');
+    const ghPath = path.join(fakeDir, 'gh');
+    writeFileSync(
+      ghPath,
+      `#!/usr/bin/env bash\nset -euo pipefail\nif [[ "$1" == "pr" && "$2" == "view" ]]; then\n  pwd > "${markerPath}"\n  echo '{"state":"MERGED","mergeStateStatus":"CLEAN","mergeable":"MERGEABLE"}'\n  exit 0\nfi\nexit 1\n`,
+    );
+    chmodSync(ghPath, 0o755);
+
+    const oldPath = process.env.PATH;
+    process.env.PATH = `${fakeDir}:${oldPath ?? ''}`;
+    try {
+      const result = await runXtrmFinish({ cwd: dir, pollIntervalMs: 1, timeoutMs: 20 });
+      expect(result.ok).toBe(true);
+      expect(readFileSync(markerPath, 'utf8').trim()).toBe(worktreePath);
+      expect(spawnSync('git', ['worktree', 'list'], { cwd: dir, encoding: 'utf8' }).stdout).not.toContain(worktreePath);
+      const state = JSON.parse(readFileSync(path.join(dir, '.xtrm-session-state.json'), 'utf8'));
+      expect(state.phase).toBe('cleanup-done');
+    } finally {
+      process.env.PATH = oldPath;
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('sets pending-cleanup when PR is not merged before timeout', async () => {
+    const dir = mkdtempSync(path.join(os.tmpdir(), 'xtrm-finish-timeout-'));
+    const fakeDir = path.join(dir, 'fakebin');
+    mkdirSync(fakeDir, { recursive: true });
+    initRepo(dir);
+
+    writeFileSync(path.join(dir, '.xtrm-session-state.json'), JSON.stringify({
+      issueId: 'jaggers-agent-tools-1xa2',
+      branch: 'feature/jaggers-agent-tools-1xa2',
+      worktreePath: '/tmp/nonexistent-worktree-path',
+      prNumber: 55,
+      prUrl: 'https://example.invalid/pr/55',
+      phase: 'waiting-merge',
+      conflictFiles: [],
+      startedAt: new Date().toISOString(),
+      lastChecked: new Date().toISOString(),
+    }), 'utf8');
+
+    const ghPath = path.join(fakeDir, 'gh');
+    writeFileSync(ghPath, `#!/usr/bin/env bash\nset -euo pipefail\nif [[ "$1" == "pr" && "$2" == "view" ]]; then\n  echo '{"state":"OPEN","mergeStateStatus":"BLOCKED","mergeable":"UNKNOWN"}'\n  exit 0\nfi\nexit 1\n`);
+    chmodSync(ghPath, 0o755);
+
+    const oldPath = process.env.PATH;
+    process.env.PATH = `${fakeDir}:${oldPath ?? ''}`;
+    try {
+      const result = await runXtrmFinish({ cwd: dir, pollIntervalMs: 1, timeoutMs: 10 });
+      expect(result.ok).toBe(false);
+      expect(result.message).toContain('Run xtrm finish when ready');
+      const state = JSON.parse(readFileSync(path.join(dir, '.xtrm-session-state.json'), 'utf8'));
+      expect(state.phase).toBe('pending-cleanup');
+    } finally {
+      process.env.PATH = oldPath;
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});