@hyperdrive.bot/gut 0.1.12 → 0.1.14-alpha.0

package/dist/commands/worktree/list.test.js

@@ -0,0 +1,182 @@
+import { describe, expect, it, vi } from 'vitest';
+import fs from 'node:fs';
+import { MS_PER_DAY, formatWorktreeAge } from './list.js';
+// Mock fs.existsSync
+vi.mock('node:fs', () => ({
+    default: {
+        existsSync: vi.fn(() => true),
+    },
+    existsSync: vi.fn(() => true),
+}));
+// Mock chalk to return raw strings for easy assertion
+vi.mock('chalk', () => ({
+    default: {
+        bold: (s) => s,
+        cyan: (s) => s,
+        dim: (s) => s,
+        yellow: (s) => s,
+    },
+}));
+function makeRecord(overrides = {}) {
+    return {
+        baseBranch: 'master',
+        createdAt: new Date('2026-03-19T13:22:00Z').getTime(),
+        entities: [
+            { branch: 'workflow/deploy-batch', entityName: 'api', entityPath: 'packages/serverless/api', worktreePath: '/tmp/gut-worktrees/workflow-deploy-batch/packages/serverless/api' },
+            { branch: 'workflow/deploy-batch', entityName: 'sign', entityPath: 'packages/web-apps/sign', worktreePath: '/tmp/gut-worktrees/workflow-deploy-batch/packages/web-apps/sign' },
+        ],
+        name: 'workflow/deploy-batch',
+        path: '/tmp/gut-worktrees/workflow-deploy-batch',
+        ...overrides,
+    };
+}
+describe('WorktreeList', () => {
+    it('displays populated list with names, paths, branches, dates, entity names', async () => {
+        const record1 = makeRecord();
+        const record2 = makeRecord({
+            baseBranch: 'main',
+            createdAt: new Date('2026-03-19T14:05:00Z').getTime(),
+            entities: [{ branch: 'workflow/story-042', entityName: 'api', entityPath: 'packages/serverless/api', worktreePath: '/tmp/gut-worktrees/workflow-story-042/packages/serverless/api' }],
+            name: 'workflow/story-042',
+            path: '/tmp/gut-worktrees/workflow-story-042',
+        });
+        const logs = [];
+        // Import the command class
+        const { default: WorktreeList } = await import('./list.js');
+        // Create instance and override dependencies
+        const cmd = Object.create(WorktreeList.prototype);
+        cmd.log = (msg = '') => { logs.push(msg); };
+        cmd.worktreeService = { findStale: () => [], list: () => [record1, record2] };
+        vi.mocked(fs.existsSync).mockReturnValue(true);
+        await cmd.run();
+        const output = logs.join('\n');
+        expect(output).toContain('Active worktrees:');
+        expect(output).toContain('workflow/deploy-batch');
+        expect(output).toContain('workflow/story-042');
+        expect(output).toContain('/tmp/gut-worktrees/workflow-deploy-batch');
+        expect(output).toContain('/tmp/gut-worktrees/workflow-story-042');
+        expect(output).toContain('2026-03-19 13:22');
+        expect(output).toContain('2026-03-19 14:05');
+        expect(output).toContain('api, sign');
+        expect(output).toContain('api');
+        expect(output).not.toContain('[stale]');
+    });
+    it('displays empty state message when no worktrees exist', async () => {
+        const logs = [];
+        const { default: WorktreeList } = await import('./list.js');
+        const cmd = Object.create(WorktreeList.prototype);
+        cmd.log = (msg = '') => { logs.push(msg); };
+        cmd.worktreeService = { findStale: () => [], list: () => [] };
+        await cmd.run();
+        const output = logs.join('\n');
+        expect(output).toContain('No active worktrees');
+        expect(output).toContain('gut worktree create <branch-name>');
+        expect(output).not.toContain('Active worktrees:');
+    });
+    it('shows [stale] marker when worktree path does not exist on disk', async () => {
+        const record = makeRecord({
+            path: '/tmp/gut-worktrees/nonexistent-worktree',
+        });
+        const logs = [];
+        const { default: WorktreeList } = await import('./list.js');
+        const cmd = Object.create(WorktreeList.prototype);
+        cmd.log = (msg = '') => { logs.push(msg); };
+        cmd.worktreeService = { findStale: () => [record], list: () => [record] };
+        vi.mocked(fs.existsSync).mockReturnValue(false);
+        await cmd.run();
+        const output = logs.join('\n');
+        expect(output).toContain('[stale]');
+        expect(output).toContain('/tmp/gut-worktrees/nonexistent-worktree');
+    });
+    describe('stale warning block (Story 2.1)', () => {
+        it('prints warning block before the list when findStale returns records', async () => {
+            const staleA = makeRecord({ name: 'workflow/dead-a', path: '/tmp/gone-a' });
+            const staleB = makeRecord({ name: 'workflow/dead-b', path: '/tmp/gone-b' });
+            const alive = makeRecord({ name: 'workflow/alive', path: '/tmp/alive' });
+            const logs = [];
+            const { default: WorktreeList } = await import('./list.js');
+            const cmd = Object.create(WorktreeList.prototype);
+            cmd.log = (msg = '') => { logs.push(msg); };
+            cmd.worktreeService = {
+                findStale: () => [staleA, staleB],
+                list: () => [staleA, staleB, alive],
+            };
+            vi.mocked(fs.existsSync).mockImplementation((p) => p === '/tmp/alive');
+            await cmd.run();
+            const warningIdx = logs.findIndex(l => l.includes('⚠️  Stale worktree records detected (path does not exist on disk):'));
+            const activeIdx = logs.findIndex(l => l.includes('Active worktrees:'));
+            expect(warningIdx).toBeGreaterThanOrEqual(0);
+            expect(warningIdx).toBeLessThan(activeIdx);
+            expect(logs).toContain('  - workflow/dead-a  /tmp/gone-a');
+            expect(logs).toContain('  - workflow/dead-b  /tmp/gone-b');
+            expect(logs).toContain('Run `gut worktree prune` to remove them.');
+        });
+        it('omits the warning block entirely when findStale returns empty', async () => {
+            const alive = makeRecord({ name: 'workflow/alive', path: '/tmp/alive' });
+            const logs = [];
+            const { default: WorktreeList } = await import('./list.js');
+            const cmd = Object.create(WorktreeList.prototype);
+            cmd.log = (msg = '') => { logs.push(msg); };
+            cmd.worktreeService = { findStale: () => [], list: () => [alive] };
+            vi.mocked(fs.existsSync).mockReturnValue(true);
+            await cmd.run();
+            const output = logs.join('\n');
+            expect(output).not.toContain('⚠️');
+            expect(output).not.toContain('Stale worktree records detected');
+            expect(output).not.toContain('gut worktree prune');
+        });
+    });
+    describe('formatWorktreeAge (Story 3.1)', () => {
+        const NOW = new Date('2026-04-11T12:00:00Z').getTime();
+        it('returns "less than a day old", not stale, when created right now', () => {
+            const result = formatWorktreeAge(NOW, NOW);
+            expect(result.text).toContain('less than a day old');
+            expect(result.isStale).toBe(false);
+        });
+        it('returns "1 day old" at exactly 1 day', () => {
+            const result = formatWorktreeAge(NOW - MS_PER_DAY, NOW);
+            expect(result.text).toContain('1 day old');
+            expect(result.isStale).toBe(false);
+        });
+        it('returns "3 days old", not stale, at 3 days', () => {
+            const result = formatWorktreeAge(NOW - 3 * MS_PER_DAY, NOW);
+            expect(result.text).toContain('3 days old');
+            expect(result.isStale).toBe(false);
+        });
+        it('is NOT stale at exactly 7 days (strict >)', () => {
+            const result = formatWorktreeAge(NOW - 7 * MS_PER_DAY, NOW);
+            expect(result.isStale).toBe(false);
+            expect(result.text).toContain('7 days old');
+        });
+        it('IS stale at 7 days + 1ms', () => {
+            const result = formatWorktreeAge(NOW - (7 * MS_PER_DAY + 1), NOW);
+            expect(result.isStale).toBe(true);
+        });
+        it('returns "30 days old" and is stale at 30 days', () => {
+            const result = formatWorktreeAge(NOW - 30 * MS_PER_DAY, NOW);
+            expect(result.text).toContain('30 days old');
+            expect(result.isStale).toBe(true);
+        });
+        it('handles future createdAt (clock skew) as "less than a day old", not stale', () => {
+            const result = formatWorktreeAge(NOW + 5 * MS_PER_DAY, NOW);
+            expect(result.text).toContain('less than a day old');
+            expect(result.isStale).toBe(false);
+        });
+        it('handles NaN createdAt as "unknown age", not stale', () => {
+            const result = formatWorktreeAge(Number.NaN, NOW);
+            expect(result.text).toContain('unknown age');
+            expect(result.isStale).toBe(false);
+        });
+    });
+    it('handles missing worktrees.json (first-run) — same as empty state', async () => {
+        const logs = [];
+        const { default: WorktreeList } = await import('./list.js');
+        const cmd = Object.create(WorktreeList.prototype);
+        cmd.log = (msg = '') => { logs.push(msg); };
+        cmd.worktreeService = { findStale: () => [], list: () => [] };
+        await cmd.run();
+        const output = logs.join('\n');
+        expect(output).toContain('No active worktrees');
+        expect(output).toContain('gut worktree create <branch-name>');
+    });
+});

package/dist/commands/worktree/prune.d.ts

@@ -0,0 +1,6 @@
+import { BaseCommand } from '../../base-command.js';
+export default class WorktreePrune extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/worktree/prune.js

@@ -0,0 +1,28 @@
+import chalk from 'chalk';
+import fs from 'node:fs';
+import { BaseCommand } from '../../base-command.js';
+export default class WorktreePrune extends BaseCommand {
+    static description = 'Remove worktree records whose paths no longer exist on disk';
+    static examples = ['<%= config.bin %> worktree prune'];
+    async run() {
+        const state = this.worktreeService.loadState();
+        const stale = [];
+        const kept = [];
+        for (const w of state.worktrees) {
+            if (fs.existsSync(w.path))
+                kept.push(w);
+            else
+                stale.push(w);
+        }
+        if (stale.length === 0) {
+            this.log(chalk.dim('No stale worktree records found'));
+            return;
+        }
+        for (const record of stale) {
+            this.log(`  ${chalk.yellow('✗')} ${record.name} ${chalk.dim('→')} ${record.path}`);
+        }
+        this.worktreeService.saveState({ worktrees: kept });
+        await this.gitService.worktreePrune(this.configService.getWorkspaceRoot());
+        this.log(chalk.green(`✓ Pruned ${stale.length} stale worktree record(s)`));
+    }
+}

package/dist/commands/worktree/prune.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/worktree/prune.test.js

@@ -0,0 +1,105 @@
+import { describe, expect, it, vi } from 'vitest';
+import fs from 'node:fs';
+vi.mock('node:fs', () => ({
+    default: {
+        existsSync: vi.fn(() => true),
+    },
+    existsSync: vi.fn(() => true),
+}));
+vi.mock('chalk', () => ({
+    default: {
+        bold: (s) => s,
+        cyan: (s) => s,
+        dim: (s) => s,
+        green: (s) => s,
+        yellow: (s) => s,
+    },
+}));
+function makeRecord(overrides = {}) {
+    return {
+        baseBranch: 'master',
+        createdAt: new Date('2026-03-19T13:22:00Z').getTime(),
+        entities: [
+            { branch: 'workflow/deploy-batch', entityName: 'api', entityPath: 'packages/serverless/api', worktreePath: '/tmp/gut-worktrees/workflow-deploy-batch/packages/serverless/api' },
+        ],
+        name: 'workflow/deploy-batch',
+        path: '/tmp/gut-worktrees/workflow-deploy-batch',
+        ...overrides,
+    };
+}
+async function makeCmd(state) {
+    const logs = [];
+    const { default: WorktreePrune } = await import('./prune.js');
+    const cmd = Object.create(WorktreePrune.prototype);
+    cmd.log = (msg = '') => { logs.push(msg); };
+    const stubs = {
+        configService: { getWorkspaceRoot: vi.fn(() => '/fake/workspace') },
+        gitService: { worktreePrune: vi.fn(async () => { }) },
+        worktreeService: {
+            loadState: vi.fn(() => state),
+            saveState: vi.fn(),
+        },
+    };
+    cmd.configService = stubs.configService;
+    cmd.gitService = stubs.gitService;
+    cmd.worktreeService = stubs.worktreeService;
+    return { cmd, logs, stubs };
+}
+describe('WorktreePrune', () => {
+    it('mixed stale+healthy: removes only stale, logs, calls saveState(kept) and worktreePrune once', async () => {
+        const healthy = makeRecord({ name: 'workflow/alive', path: '/tmp/alive' });
+        const stale = makeRecord({ name: 'workflow/dead', path: '/tmp/dead' });
+        vi.mocked(fs.existsSync).mockImplementation((p) => p === '/tmp/alive');
+        const { cmd, logs, stubs } = await makeCmd({ worktrees: [healthy, stale] });
+        await cmd.run();
+        expect(stubs.worktreeService.saveState).toHaveBeenCalledTimes(1);
+        expect(stubs.worktreeService.saveState).toHaveBeenCalledWith({ worktrees: [healthy] });
+        expect(stubs.gitService.worktreePrune).toHaveBeenCalledTimes(1);
+        expect(stubs.gitService.worktreePrune).toHaveBeenCalledWith('/fake/workspace');
+        const output = logs.join('\n');
+        expect(output).toContain('✗');
+        expect(output).toContain('workflow/dead');
+        expect(output).toContain('/tmp/dead');
+        expect(output).not.toContain('workflow/alive');
+        expect(output).toContain('✓ Pruned 1 stale worktree record(s)');
+    });
+    it('all stale: removes all, saveState called with empty, summary reports full count', async () => {
+        const a = makeRecord({ name: 'workflow/dead-a', path: '/tmp/dead-a' });
+        const b = makeRecord({ name: 'workflow/dead-b', path: '/tmp/dead-b' });
+        vi.mocked(fs.existsSync).mockReturnValue(false);
+        const { cmd, logs, stubs } = await makeCmd({ worktrees: [a, b] });
+        await cmd.run();
+        expect(stubs.worktreeService.saveState).toHaveBeenCalledTimes(1);
+        expect(stubs.worktreeService.saveState).toHaveBeenCalledWith({ worktrees: [] });
+        expect(stubs.gitService.worktreePrune).toHaveBeenCalledTimes(1);
+        expect(stubs.gitService.worktreePrune).toHaveBeenCalledWith('/fake/workspace');
+        const output = logs.join('\n');
+        expect(output).toContain('workflow/dead-a');
+        expect(output).toContain('/tmp/dead-a');
+        expect(output).toContain('workflow/dead-b');
+        expect(output).toContain('/tmp/dead-b');
+        expect(output).toContain('✓ Pruned 2 stale worktree record(s)');
+    });
+    it('all healthy: no save, no git prune, logs empty-state message', async () => {
+        const a = makeRecord({ name: 'workflow/alive-a', path: '/tmp/alive-a' });
+        const b = makeRecord({ name: 'workflow/alive-b', path: '/tmp/alive-b' });
+        vi.mocked(fs.existsSync).mockReturnValue(true);
+        const { cmd, logs, stubs } = await makeCmd({ worktrees: [a, b] });
+        await cmd.run();
+        expect(stubs.worktreeService.saveState).not.toHaveBeenCalled();
+        expect(stubs.gitService.worktreePrune).not.toHaveBeenCalled();
+        const output = logs.join('\n');
+        expect(output).toContain('No stale worktree records found');
+        expect(output).not.toContain('Pruned');
+    });
+    it('empty state: no save, no git prune, logs empty-state message', async () => {
+        vi.mocked(fs.existsSync).mockReturnValue(true);
+        const { cmd, logs, stubs } = await makeCmd({ worktrees: [] });
+        await cmd.run();
+        expect(stubs.worktreeService.saveState).not.toHaveBeenCalled();
+        expect(stubs.gitService.worktreePrune).not.toHaveBeenCalled();
+        const output = logs.join('\n');
+        expect(output).toContain('No stale worktree records found');
+        expect(output).not.toContain('Pruned');
+    });
+});

package/dist/commands/worktree/remove.d.ts

@@ -0,0 +1,12 @@
+import { BaseCommand } from '../../base-command.js';
+export default class WorktreeRemove extends BaseCommand {
+    static args: {
+        name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/worktree/remove.js

@@ -0,0 +1,48 @@
+import { Args, Flags } from '@oclif/core';
+import chalk from 'chalk';
+import { BaseCommand } from '../../base-command.js';
+export default class WorktreeRemove extends BaseCommand {
+    static args = {
+        name: Args.string({ description: 'Worktree name to remove', required: true }),
+    };
+    static description = 'Remove a worktree and all entity worktrees';
+    static examples = [
+        '<%= config.bin %> worktree remove workflow/batch',
+        '<%= config.bin %> worktree remove workflow/batch --force',
+    ];
+    static flags = {
+        force: Flags.boolean({ char: 'f', default: false, description: 'Remove even with uncommitted changes' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(WorktreeRemove);
+        const { name } = args;
+        const record = this.worktreeService.get(name);
+        if (!record) {
+            this.error(`Worktree '${name}' not found`);
+        }
+        this.log(chalk.bold('\n🗑️  Removing worktree...'));
+        const result = await this.worktreeService.removeWorktreeRecord(name, {
+            force: flags.force,
+            logger: (msg) => {
+                if (msg.includes('⚠'))
+                    this.log(chalk.yellow(msg));
+                else if (msg.includes('○'))
+                    this.log(chalk.dim(msg));
+                else if (msg.includes('✓'))
+                    this.log(chalk.green(msg));
+                else
+                    this.log(msg);
+            },
+        });
+        if (result.skippedDueToDirty) {
+            const dirtyList = result.dirtyEntities
+                .map(d => `  ${d.entityName}: ${d.changeCount} uncommitted changes`)
+                .join('\n');
+            this.error(`Cannot remove worktree with uncommitted changes:\n${dirtyList}\n\nUse --force to remove anyway.`);
+        }
+        this.log(chalk.dim('─'.repeat(50)));
+        this.log(chalk.green(`✓ Removed worktree '${name}'`));
+        this.log(`  Path:     ${record.path}`);
+        this.log(`  Entities: ${result.removedEntities} removed${result.skippedEntities > 0 ? `, ${result.skippedEntities} skipped` : ''}`);
+    }
+}

package/dist/commands/worktree/status.d.ts

@@ -0,0 +1,9 @@
+import { BaseCommand } from '../../base-command.js';
+export default class WorktreeStatus extends BaseCommand {
+    static args: {
+        name: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/worktree/status.js

@@ -0,0 +1,58 @@
+import { Args } from '@oclif/core';
+import chalk from 'chalk';
+import Table from 'cli-table3';
+import fs from 'node:fs';
+import { BaseCommand } from '../../base-command.js';
+export default class WorktreeStatus extends BaseCommand {
+    static args = {
+        name: Args.string({ description: 'Worktree name (shows all if omitted)', required: false }),
+    };
+    static description = 'Show per-entity git status for worktrees';
+    static examples = [
+        '<%= config.bin %> worktree status',
+        '<%= config.bin %> worktree status workflow/deploy-batch',
+    ];
+    async run() {
+        const { args } = await this.parse(WorktreeStatus);
+        let worktrees;
+        if (args.name) {
+            const record = this.worktreeService.get(args.name);
+            if (!record) {
+                this.error(`Worktree "${args.name}" not found. Run "gut worktree list" to see active worktrees.`);
+            }
+            worktrees = [record];
+        }
+        else {
+            worktrees = this.worktreeService.list();
+            if (worktrees.length === 0) {
+                this.log(`No active worktrees. Create one with: ${chalk.cyan('gut worktree create <branch-name>')}`);
+                return;
+            }
+        }
+        for (const worktree of worktrees) {
+            this.log(chalk.bold(`\n${worktree.name}`));
+            this.log(chalk.dim(worktree.path));
+            const table = new Table({
+                head: [chalk.cyan('Entity'), chalk.cyan('Branch'), chalk.cyan('Status'), chalk.cyan('Changes'), chalk.cyan('Ahead'), chalk.cyan('Behind')],
+                style: { border: [], head: [] },
+            });
+            for (const entity of worktree.entities) {
+                if (!fs.existsSync(entity.worktreePath)) {
+                    table.push([entity.entityName, '-', chalk.yellow('[stale - path missing]'), '-', '-', '-']);
+                    continue;
+                }
+                const status = await this.gitService.getStatus(entity.worktreePath);
+                const changeCount = status.changes.length + status.untracked.length;
+                table.push([
+                    entity.entityName,
+                    status.branch,
+                    status.hasChanges ? chalk.yellow('dirty') : chalk.green('clean'),
+                    status.hasChanges ? chalk.yellow(`${changeCount} changes`) : chalk.green('clean'),
+                    status.ahead.toString(),
+                    status.behind.toString(),
+                ]);
+            }
+            this.log(table.toString());
+        }
+    }
+}

package/dist/services/worktree.service.d.ts

@@ -2,6 +2,20 @@ import type { WorktreeRecord, WorktreeState } from '../models/entity.model.js';
 import type { ConfigService } from './config.service.js';
 import type { FocusService } from './focus.service.js';
 import type { GitService } from './git.service.js';
+export interface RemoveWorktreeOptions {
+    force: boolean;
+    logger?: (message: string) => void;
+}
+export interface RemoveWorktreeResult {
+    dirtyEntities: Array<{
+        changeCount: number;
+        entityName: string;
+    }>;
+    removed: boolean;
+    removedEntities: number;
+    skippedDueToDirty: boolean;
+    skippedEntities: number;
+}
 export declare class WorktreeService {
     private readonly configService;
     private readonly gitService;
@@ -11,6 +25,16 @@ export declare class WorktreeService {
     constructor(configService: ConfigService, gitService: GitService, focusService: FocusService);
     get(name: string): WorktreeRecord | null;
     list(): WorktreeRecord[];
+    findStale(): WorktreeRecord[];
     loadState(): WorktreeState;
+    /**
+     * Remove a worktree record: all entity worktrees in reverse order, then the
+     * super-repo worktree, pruning refs along the way, then splice the record
+     * out of state. Shared between `worktree remove` and `worktree gc`.
+     *
+     * If any entity has uncommitted changes and `force` is false, nothing is
+     * removed and `skippedDueToDirty` is returned true.
+     */
+    removeWorktreeRecord(name: string, options: RemoveWorktreeOptions): Promise<RemoveWorktreeResult>;
     saveState(state: WorktreeState): void;
 }

package/dist/services/worktree.service.js

@@ -20,6 +20,9 @@ export class WorktreeService {
     list() {
         return this.loadState().worktrees;
     }
+    findStale() {
+        return this.loadState().worktrees.filter(w => !fs.existsSync(w.path));
+    }
     loadState() {
         if (!fs.existsSync(this.stateFile)) {
             return { worktrees: [] };
@@ -37,6 +40,93 @@ export class WorktreeService {
             return { worktrees: [] };
         }
     }
+    /**
+     * Remove a worktree record: all entity worktrees in reverse order, then the
+     * super-repo worktree, pruning refs along the way, then splice the record
+     * out of state. Shared between `worktree remove` and `worktree gc`.
+     *
+     * If any entity has uncommitted changes and `force` is false, nothing is
+     * removed and `skippedDueToDirty` is returned true.
+     */
+    async removeWorktreeRecord(name, options) {
+        const { force, logger } = options;
+        const log = (message) => {
+            if (logger)
+                logger(message);
+        };
+        const record = this.get(name);
+        if (!record) {
+            throw new Error(`Worktree '${name}' not found`);
+        }
+        const workspaceRoot = this.configService.getWorkspaceRoot();
+        // Dirty-state pre-check (mirrors remove.ts:39-50)
+        const dirtyEntities = [];
+        for (const entity of record.entities) {
+            if (!fs.existsSync(entity.worktreePath))
+                continue;
+            // eslint-disable-next-line no-await-in-loop
+            const status = await this.gitService.getStatus(entity.worktreePath);
+            if (status.hasChanges) {
+                dirtyEntities.push({
+                    changeCount: status.changes.length + status.untracked.length,
+                    entityName: entity.entityName,
+                });
+            }
+        }
+        if (dirtyEntities.length > 0 && !force) {
+            return {
+                dirtyEntities,
+                removed: false,
+                removedEntities: 0,
+                skippedDueToDirty: true,
+                skippedEntities: 0,
+            };
+        }
+        if (dirtyEntities.length > 0 && force) {
+            for (const d of dirtyEntities) {
+                log(`  ⚠ ${d.entityName}: ${d.changeCount} uncommitted changes will be lost`);
+            }
+        }
+        // Entity worktrees in reverse order
+        let removedEntities = 0;
+        let skippedEntities = 0;
+        const reversed = [...record.entities].reverse();
+        for (const entity of reversed) {
+            const mainRepoPath = path.join(workspaceRoot, entity.entityPath);
+            if (!fs.existsSync(entity.worktreePath)) {
+                log(`  ○ ${entity.entityName}: already removed (skipped)`);
+                skippedEntities++;
+                // eslint-disable-next-line no-await-in-loop
+                await this.gitService.worktreePrune(mainRepoPath).catch(() => { });
+                continue;
+            }
+            // eslint-disable-next-line no-await-in-loop
+            await this.gitService.worktreeRemove(mainRepoPath, entity.worktreePath, force);
+            // eslint-disable-next-line no-await-in-loop
+            await this.gitService.worktreePrune(mainRepoPath);
+            log(`  ✓ ${entity.entityName}: worktree removed`);
+            removedEntities++;
+        }
+        // Super-repo worktree
+        if (fs.existsSync(record.path)) {
+            await this.gitService.worktreeRemove(workspaceRoot, record.path, force);
+        }
+        await this.gitService.worktreePrune(workspaceRoot);
+        // Splice the record out of state
+        const state = this.loadState();
+        const idx = state.worktrees.findIndex(w => w.name === name);
+        if (idx !== -1) {
+            state.worktrees.splice(idx, 1);
+        }
+        this.saveState(state);
+        return {
+            dirtyEntities,
+            removed: true,
+            removedEntities,
+            skippedDueToDirty: false,
+            skippedEntities,
+        };
+    }
     saveState(state) {
         const serialized = JSON.stringify(state, null, 2);
         try {

package/dist/utils/duration.d.ts

@@ -0,0 +1 @@
+export declare function parseDuration(input: string): number;

package/dist/utils/duration.js

@@ -0,0 +1,26 @@
+const SUFFIX_MS = {
+    d: 86_400_000,
+    h: 3_600_000,
+    m: 60_000,
+    s: 1000,
+};
+export function parseDuration(input) {
+    const invalid = () => {
+        throw new Error(`Invalid duration: '${input}'. Expected format like '7d', '24h', '30m', or '90s'.`);
+    };
+    if (typeof input !== 'string' || input.length === 0)
+        invalid();
+    if (/\s/.test(input))
+        invalid();
+    const match = /^(\d+)([a-zA-Z])$/.exec(input);
+    if (!match)
+        invalid();
+    const [, numStr, suffix] = match;
+    const multiplier = SUFFIX_MS[suffix];
+    if (multiplier === undefined)
+        invalid();
+    const value = Number(numStr);
+    if (!Number.isFinite(value) || value < 0)
+        invalid();
+    return value * multiplier;
+}

package/dist/utils/entity-spec.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Parses `--entity` flag values for `gut worktree create`.
+ *
+ * Each spec is either a bare entity name (`serverless-api`) or a pinned
+ * spec (`serverless-api:feature/seo-lake`). The first `:` separates the
+ * entity name from the branch; the branch itself may contain `/` or `-`.
+ *
+ * Invalid shapes throw with a descriptive message so callers can surface
+ * the error to the user.
+ */
+export interface EntitySpec {
+    branch?: string;
+    name: string;
+}
+export declare function parseEntitySpecs(specs: string[] | undefined): EntitySpec[];