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

package/README.md

@@ -18,7 +18,7 @@ $ npm install -g @hyperdrive.bot/gut
 $ gut COMMAND
 running command...
 $ gut (--version)
-@hyperdrive.bot/gut/0.1.13 linux-x64 node-v22.22.1
+@hyperdrive.bot/gut/0.1.14-alpha.0 linux-x64 node-v22.22.2
 $ gut --help [COMMAND]
 USAGE
   $ gut COMMAND
@@ -290,13 +290,21 @@ Show current focus context with entity details
 
 ```
 USAGE
-  $ gut context
+  $ gut context [--all] [--json]
+
+FLAGS
+  --all   Include all registered entities, not just focused ones (implies --json or adds to text output)
+  --json  Emit structured JSON for programmatic consumption (includes per-entity branch + hasUncommitted)
 
 DESCRIPTION
   Show current focus context with entity details
 
 EXAMPLES
   $ gut context
+
+  $ gut context --json
+
+  $ gut context --json --all
 ```
 
 ## `gut contexts`
@@ -1180,15 +1188,18 @@ Create mirrored worktrees for super-repo and focused entities
 
 ```
 USAGE
-  $ gut worktree create NAME [--base-dir <value>] [--from <value>] [--install]
+  $ gut worktree create NAME [--base-dir <value>] [--entity <value>...] [--from <value>] [--install]
 
 ARGUMENTS
   NAME  Branch name for the worktree
 
 FLAGS
-  --base-dir=<value>  [default: /tmp/gut-worktrees] Root directory for worktrees
-  --from=<value>      Base branch to create from (defaults to current branch)
-  --install           Run pnpm install after creation
+  --base-dir=<value>   [default: /root/.local/share/gut/worktrees] Root directory for worktrees (default:
+                       ~/.local/share/gut/worktrees, override via GUT_WORKTREE_DIR env var; explicit --base-dir wins)
+  --entity=<value>...  Entity to include, optionally pinned to a branch via "name:branch". Repeatable. Overrides current
+                       focus when provided.
+  --from=<value>       Base branch to create from (defaults to current branch)
+  --install            Run pnpm install after creation
 
 DESCRIPTION
   Create mirrored worktrees for super-repo and focused entities
@@ -1199,5 +1210,9 @@ EXAMPLES
   $ gut worktree create workflow/deploy-batch --from master --install
 
   $ gut worktree create feature/story-42 --base-dir /home/user/worktrees
+
+  $ gut worktree create seo-lake --entity serverless-api:feature/seo-lake --entity sign
+
+  GUT_WORKTREE_DIR=/tmp/gut-worktrees gut worktree create feature/ci-run
 ```
 <!-- commandsstop -->

package/dist/commands/worktree/create.js

@@ -33,6 +33,14 @@ export default class WorktreeCreate extends BaseCommand {
     };
     async run() {
         const { args, flags } = await this.parse(WorktreeCreate);
+        const stale = this.worktreeService.findStale();
+        if (stale.length > 0) {
+            this.log(chalk.yellow('⚠️  Stale worktree records detected (path does not exist on disk):'));
+            for (const record of stale) {
+                this.log(chalk.yellow(`  - ${record.name}  ${record.path}`));
+            }
+            this.log(chalk.yellow('Run `gut worktree prune` to remove them.'));
+        }
         const workspaceRoot = this.configService.getWorkspaceRoot();
         const slug = args.name.replace(/\//g, '-');
         const wtPath = path.join(flags['base-dir'], slug);

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

@@ -0,0 +1,13 @@
+import { BaseCommand } from '../../base-command.js';
+export default class WorktreeGc extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'older-than': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+    private countDirtyChanges;
+    private hasDirtyEntity;
+}

package/dist/commands/worktree/gc.js

@@ -0,0 +1,126 @@
+import { Flags } from '@oclif/core';
+import chalk from 'chalk';
+import fs from 'node:fs';
+import { BaseCommand } from '../../base-command.js';
+import { parseDuration } from '../../utils/duration.js';
+const DAY_MS = 86_400_000;
+export default class WorktreeGc extends BaseCommand {
+    static description = 'Remove worktrees older than a given duration (garbage collection)';
+    static examples = [
+        '<%= config.bin %> worktree gc --older-than 7d',
+        '<%= config.bin %> worktree gc --older-than 14d --force',
+        '<%= config.bin %> worktree gc --older-than 7d --dry-run',
+    ];
+    static flags = {
+        'dry-run': Flags.boolean({
+            char: 'n',
+            default: false,
+            description: 'List candidates without removing anything',
+        }),
+        force: Flags.boolean({
+            char: 'f',
+            default: false,
+            description: 'Remove even worktrees with uncommitted changes',
+        }),
+        'older-than': Flags.string({
+            char: 'o',
+            description: "Duration threshold (e.g. '7d', '24h', '30m', '90s')",
+            required: true,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(WorktreeGc);
+        const olderThanInput = flags['older-than'];
+        let thresholdMs;
+        try {
+            thresholdMs = parseDuration(olderThanInput);
+        }
+        catch (error) {
+            this.error(error instanceof Error ? error.message : String(error));
+        }
+        const state = this.worktreeService.loadState();
+        const now = Date.now();
+        const candidates = state.worktrees.filter(w => now - w.createdAt > thresholdMs);
+        if (candidates.length === 0) {
+            this.log(chalk.dim(`No worktrees older than ${olderThanInput}`));
+            return;
+        }
+        // Collect per-candidate dirty state up front (used by both dry-run and real run)
+        const dirtyFlags = await Promise.all(candidates.map(async (record) => this.hasDirtyEntity(record)));
+        if (flags['dry-run']) {
+            this.log(chalk.bold(`\nWorktrees older than ${olderThanInput}:`));
+            for (const [i, record] of candidates.entries()) {
+                const ageDays = Math.floor((now - record.createdAt) / DAY_MS);
+                const dirtyLabel = dirtyFlags[i] ? chalk.yellow(' [dirty]') : '';
+                this.log(`  ${record.name}  ${ageDays}d old${dirtyLabel}`);
+            }
+            this.log(chalk.dim(`\n${candidates.length} candidate(s)`));
+            return;
+        }
+        this.log(chalk.bold(`\n🧹 Garbage collecting worktrees older than ${olderThanInput}...`));
+        let removed = 0;
+        let skippedDirty = 0;
+        let skippedMissing = 0;
+        for (const [i, record] of candidates.entries()) {
+            if (dirtyFlags[i] && !flags.force) {
+                // eslint-disable-next-line no-await-in-loop
+                const changeCount = await this.countDirtyChanges(record);
+                this.log(chalk.yellow(`  ⚠ ${record.name}: skipped (${changeCount} uncommitted changes)`));
+                skippedDirty++;
+                continue;
+            }
+            // eslint-disable-next-line no-await-in-loop
+            const result = await this.worktreeService.removeWorktreeRecord(record.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) {
+                skippedDirty++;
+                continue;
+            }
+            removed++;
+            if (result.removedEntities === 0 && result.skippedEntities > 0) {
+                skippedMissing++;
+            }
+        }
+        this.log(chalk.dim('─'.repeat(50)));
+        this.log(chalk.green(`✓ Garbage collected ${removed} worktree(s)`));
+        this.log(chalk.dim(`  Removed:          ${removed}`));
+        this.log(chalk.dim(`  Skipped (dirty):  ${skippedDirty}`));
+        this.log(chalk.dim(`  Skipped (missing):${skippedMissing}`));
+        this.log(chalk.dim(`  Candidates:       ${candidates.length}`));
+    }
+    async countDirtyChanges(record) {
+        let total = 0;
+        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) {
+                total += status.changes.length + status.untracked.length;
+            }
+        }
+        return total;
+    }
+    async hasDirtyEntity(record) {
+        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)
+                return true;
+        }
+        return false;
+    }
+}

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

@@ -0,0 +1,12 @@
+import { BaseCommand } from '../../base-command.js';
+export declare const MS_PER_DAY: number;
+export declare const STALE_DAYS = 7;
+export declare function formatWorktreeAge(createdAt: number, now: number): {
+    isStale: boolean;
+    text: string;
+};
+export default class WorktreeList extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/worktree/list.js

@@ -0,0 +1,63 @@
+import fs from 'node:fs';
+import chalk from 'chalk';
+import { BaseCommand } from '../../base-command.js';
+export const MS_PER_DAY = 1000 * 60 * 60 * 24;
+export const STALE_DAYS = 7;
+export function formatWorktreeAge(createdAt, now) {
+    if (typeof createdAt !== 'number' || Number.isNaN(createdAt)) {
+        return { isStale: false, text: 'unknown age' };
+    }
+    const ageMs = now - createdAt;
+    if (ageMs <= 0) {
+        return { isStale: false, text: 'less than a day old' };
+    }
+    const ageDays = Math.floor(ageMs / MS_PER_DAY);
+    const isStale = ageMs / MS_PER_DAY > STALE_DAYS;
+    let text;
+    if (ageDays === 0) {
+        text = 'less than a day old';
+    }
+    else if (ageDays === 1) {
+        text = '1 day old';
+    }
+    else {
+        text = `${ageDays} days old`;
+    }
+    return { isStale, text };
+}
+export default class WorktreeList extends BaseCommand {
+    static description = 'List all active worktrees with metadata and staleness detection';
+    static examples = ['<%= config.bin %> <%= command.id %>'];
+    async run() {
+        const stale = this.worktreeService.findStale();
+        if (stale.length > 0) {
+            this.log(chalk.yellow('⚠️  Stale worktree records detected (path does not exist on disk):'));
+            for (const record of stale) {
+                this.log(chalk.yellow(`  - ${record.name}  ${record.path}`));
+            }
+            this.log(chalk.yellow('Run `gut worktree prune` to remove them.'));
+        }
+        const worktrees = this.worktreeService.list();
+        if (worktrees.length === 0) {
+            this.log(`No active worktrees. Create one with: ${chalk.cyan('gut worktree create <branch-name>')}`);
+            return;
+        }
+        this.log(chalk.bold('\nActive worktrees:\n'));
+        for (const record of worktrees) {
+            const isStale = !fs.existsSync(record.path);
+            const formattedDate = new Date(record.createdAt).toISOString().replace('T', ' ').slice(0, 16);
+            const entityNames = record.entities.map(e => e.entityName).join(', ');
+            const age = formatWorktreeAge(record.createdAt, Date.now());
+            const ageLine = age.isStale
+                ? chalk.yellow(`    Age:      ⚠ (${age.text}) — consider removing`)
+                : `    Age:      (${age.text})`;
+            this.log(`  ${chalk.bold(record.name)}`);
+            this.log(`    Path:     ${record.path}${isStale ? chalk.yellow(' [stale]') : ''}`);
+            this.log(`    Branch:   ${chalk.cyan(record.name)}`);
+            this.log(`    Created:  ${chalk.dim(formattedDate)}`);
+            this.log(ageLine);
+            this.log(`    Entities: ${entityNames}`);
+            this.log('');
+        }
+    }
+}

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

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

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/oclif.manifest.json

@@ -2249,7 +2249,170 @@
         "worktree",
         "create.js"
       ]
+    },
+    "worktree:gc": {
+      "aliases": [],
+      "args": {},
+      "description": "Remove worktrees older than a given duration (garbage collection)",
+      "examples": [
+        "<%= config.bin %> worktree gc --older-than 7d",
+        "<%= config.bin %> worktree gc --older-than 14d --force",
+        "<%= config.bin %> worktree gc --older-than 7d --dry-run"
+      ],
+      "flags": {
+        "dry-run": {
+          "char": "n",
+          "description": "List candidates without removing anything",
+          "name": "dry-run",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "force": {
+          "char": "f",
+          "description": "Remove even worktrees with uncommitted changes",
+          "name": "force",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "older-than": {
+          "char": "o",
+          "description": "Duration threshold (e.g. '7d', '24h', '30m', '90s')",
+          "name": "older-than",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "worktree:gc",
+      "pluginAlias": "@hyperdrive.bot/gut",
+      "pluginName": "@hyperdrive.bot/gut",
+      "pluginType": "core",
+      "strict": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "worktree",
+        "gc.js"
+      ]
+    },
+    "worktree:list": {
+      "aliases": [],
+      "args": {},
+      "description": "List all active worktrees with metadata and staleness detection",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>"
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "worktree:list",
+      "pluginAlias": "@hyperdrive.bot/gut",
+      "pluginName": "@hyperdrive.bot/gut",
+      "pluginType": "core",
+      "strict": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "worktree",
+        "list.js"
+      ]
+    },
+    "worktree:prune": {
+      "aliases": [],
+      "args": {},
+      "description": "Remove worktree records whose paths no longer exist on disk",
+      "examples": [
+        "<%= config.bin %> worktree prune"
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "worktree:prune",
+      "pluginAlias": "@hyperdrive.bot/gut",
+      "pluginName": "@hyperdrive.bot/gut",
+      "pluginType": "core",
+      "strict": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "worktree",
+        "prune.js"
+      ]
+    },
+    "worktree:remove": {
+      "aliases": [],
+      "args": {
+        "name": {
+          "description": "Worktree name to remove",
+          "name": "name",
+          "required": true
+        }
+      },
+      "description": "Remove a worktree and all entity worktrees",
+      "examples": [
+        "<%= config.bin %> worktree remove workflow/batch",
+        "<%= config.bin %> worktree remove workflow/batch --force"
+      ],
+      "flags": {
+        "force": {
+          "char": "f",
+          "description": "Remove even with uncommitted changes",
+          "name": "force",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "worktree:remove",
+      "pluginAlias": "@hyperdrive.bot/gut",
+      "pluginName": "@hyperdrive.bot/gut",
+      "pluginType": "core",
+      "strict": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "worktree",
+        "remove.js"
+      ]
+    },
+    "worktree:status": {
+      "aliases": [],
+      "args": {
+        "name": {
+          "description": "Worktree name (shows all if omitted)",
+          "name": "name",
+          "required": false
+        }
+      },
+      "description": "Show per-entity git status for worktrees",
+      "examples": [
+        "<%= config.bin %> worktree status",
+        "<%= config.bin %> worktree status workflow/deploy-batch"
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "worktree:status",
+      "pluginAlias": "@hyperdrive.bot/gut",
+      "pluginName": "@hyperdrive.bot/gut",
+      "pluginType": "core",
+      "strict": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "worktree",
+        "status.js"
+      ]
     }
   },
-  "version": "0.1.13"
+  "version": "0.1.14-alpha.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperdrive.bot/gut",
-  "version": "0.1.13",
+  "version": "0.1.14-alpha.0",
   "description": "Git Unified Tooling - Enhanced git with workspace intelligence for entity-based organization",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",