@hyperdrive.bot/gut 0.1.14 → 0.1.15-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.14-alpha.0 linux-x64 node-v22.22.2
+@hyperdrive.bot/gut/0.1.15-alpha.0 linux-x64 node-v22.22.2
 $ gut --help [COMMAND]
 USAGE
   $ gut COMMAND
@@ -72,6 +72,11 @@ USAGE
 * [`gut used-by [ENTITY]`](#gut-used-by-entity)
 * [`gut workspace ACTION`](#gut-workspace-action)
 * [`gut worktree create NAME`](#gut-worktree-create-name)
+* [`gut worktree gc`](#gut-worktree-gc)
+* [`gut worktree list`](#gut-worktree-list)
+* [`gut worktree prune`](#gut-worktree-prune)
+* [`gut worktree remove NAME`](#gut-worktree-remove-name)
+* [`gut worktree status [NAME]`](#gut-worktree-status-name)
 
 ## `gut add [PATH]`
 
@@ -1215,4 +1220,101 @@ EXAMPLES
 
   GUT_WORKTREE_DIR=/tmp/gut-worktrees gut worktree create feature/ci-run
 ```
+
+## `gut worktree gc`
+
+Remove worktrees older than a given duration (garbage collection)
+
+```
+USAGE
+  $ gut worktree gc -o <value> [-n] [-f]
+
+FLAGS
+  -f, --force               Remove even worktrees with uncommitted changes
+  -n, --dry-run             List candidates without removing anything
+  -o, --older-than=<value>  (required) Duration threshold (e.g. '7d', '24h', '30m', '90s')
+
+DESCRIPTION
+  Remove worktrees older than a given duration (garbage collection)
+
+EXAMPLES
+  $ gut worktree gc --older-than 7d
+
+  $ gut worktree gc --older-than 14d --force
+
+  $ gut worktree gc --older-than 7d --dry-run
+```
+
+## `gut worktree list`
+
+List all active worktrees with metadata and staleness detection
+
+```
+USAGE
+  $ gut worktree list
+
+DESCRIPTION
+  List all active worktrees with metadata and staleness detection
+
+EXAMPLES
+  $ gut worktree list
+```
+
+## `gut worktree prune`
+
+Remove worktree records whose paths no longer exist on disk
+
+```
+USAGE
+  $ gut worktree prune
+
+DESCRIPTION
+  Remove worktree records whose paths no longer exist on disk
+
+EXAMPLES
+  $ gut worktree prune
+```
+
+## `gut worktree remove NAME`
+
+Remove a worktree and all entity worktrees
+
+```
+USAGE
+  $ gut worktree remove NAME [-f]
+
+ARGUMENTS
+  NAME  Worktree name to remove
+
+FLAGS
+  -f, --force  Remove even with uncommitted changes
+
+DESCRIPTION
+  Remove a worktree and all entity worktrees
+
+EXAMPLES
+  $ gut worktree remove workflow/batch
+
+  $ gut worktree remove workflow/batch --force
+```
+
+## `gut worktree status [NAME]`
+
+Show per-entity git status for worktrees
+
+```
+USAGE
+  $ gut worktree status [NAME]
+
+ARGUMENTS
+  NAME  Worktree name (shows all if omitted)
+
+DESCRIPTION
+  Show per-entity git status for worktrees
+
+EXAMPLES
+  $ gut worktree status
+
+  $ gut worktree status workflow/deploy-batch
+```
 <!-- commandsstop -->

package/dist/commands/claude/init.d.ts

@@ -0,0 +1,11 @@
+import { BaseCommand } from '../../base-command.js';
+export default class ClaudeInit 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>;
+    };
+    protected get requiresInit(): boolean;
+    run(): Promise<void>;
+}

package/dist/commands/claude/init.js

@@ -0,0 +1,120 @@
+import { Flags } from '@oclif/core';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import chalk from 'chalk';
+import { BaseCommand } from '../../base-command.js';
+const GUT_START = '<!-- gut:start -->';
+const GUT_END = '<!-- gut:end -->';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const templateDir = join(__dirname, '..', '..', '..', 'templates', 'claude-init');
+export default class ClaudeInit extends BaseCommand {
+    static description = 'Scaffold Claude Code configuration for gut';
+    static examples = [
+        '<%= config.bin %> claude init',
+        '<%= config.bin %> claude init --dry-run',
+        '<%= config.bin %> claude init --force',
+    ];
+    static flags = {
+        'dry-run': Flags.boolean({ description: 'Preview changes without writing files' }),
+        force: Flags.boolean({ char: 'f', description: 'Overwrite existing gut section and command files' }),
+    };
+    get requiresInit() {
+        return false;
+    }
+    async run() {
+        const { flags } = await this.parse(ClaudeInit);
+        const dryRun = flags['dry-run'];
+        const force = flags.force;
+        // Validate template directory
+        if (!existsSync(templateDir)) {
+            this.error('Template directory not found at: ' + templateDir);
+        }
+        const results = [];
+        // --- CLAUDE.md handler ---
+        const claudeMdPath = join(process.cwd(), 'CLAUDE.md');
+        const templateContent = readFileSync(join(templateDir, 'claude-md-section.md'), 'utf-8');
+        if (!existsSync(claudeMdPath)) {
+            // No CLAUDE.md — create new file
+            if (dryRun) {
+                results.push({ action: 'created', file: 'CLAUDE.md' });
+            }
+            else {
+                writeFileSync(claudeMdPath, templateContent);
+                results.push({ action: 'created', file: 'CLAUDE.md' });
+            }
+        }
+        else {
+            const existing = readFileSync(claudeMdPath, 'utf-8');
+            if (existing.includes(GUT_START)) {
+                if (force) {
+                    // Remove existing gut section and re-append
+                    const cleaned = existing.replace(new RegExp(GUT_START + '[\\s\\S]*?' + GUT_END, 'g'), '').trimEnd();
+                    if (!dryRun) {
+                        writeFileSync(claudeMdPath, cleaned + '\n\n' + templateContent);
+                    }
+                    results.push({ action: 'modified', file: 'CLAUDE.md' });
+                }
+                else {
+                    this.log('gut section already exists (use --force to overwrite)');
+                    results.push({ action: 'skipped', file: 'CLAUDE.md' });
+                }
+            }
+            else {
+                // Append gut section
+                if (!dryRun) {
+                    writeFileSync(claudeMdPath, existing + '\n\n' + templateContent);
+                }
+                results.push({ action: 'modified', file: 'CLAUDE.md' });
+            }
+        }
+        // --- .claude/commands/ handler ---
+        const commandsDir = join(process.cwd(), '.claude', 'commands');
+        const commandFiles = ['gut-status.md', 'gut-affected.md'];
+        if (!existsSync(commandsDir)) {
+            if (dryRun) {
+                this.log('.claude/commands/ → create directory');
+            }
+            else {
+                mkdirSync(commandsDir, { recursive: true });
+            }
+        }
+        for (const filename of commandFiles) {
+            const source = join(templateDir, 'commands', filename);
+            const target = join(commandsDir, filename);
+            if (existsSync(target) && !force) {
+                this.log(`${filename} → already exists (use --force to overwrite)`);
+                results.push({ action: 'skipped', file: `.claude/commands/${filename}` });
+            }
+            else {
+                if (!dryRun) {
+                    // Ensure directory exists (in case only some files existed)
+                    mkdirSync(commandsDir, { recursive: true });
+                    copyFileSync(source, target);
+                }
+                results.push({ action: 'created', file: `.claude/commands/${filename}` });
+            }
+        }
+        // --- Summary ---
+        const heading = dryRun ? 'gut claude init (dry run)' : 'gut claude init';
+        this.log('');
+        this.log(chalk.bold(heading));
+        this.log('');
+        for (const { action, file } of results) {
+            const label = action === 'created'
+                ? chalk.green(action)
+                : action === 'modified'
+                    ? chalk.yellow(action)
+                    : chalk.dim(action);
+            this.log(`  ${file} → ${label}`);
+        }
+        this.log('');
+        if (dryRun) {
+            this.log('No files were modified. Remove --dry-run to apply.');
+        }
+        else {
+            this.log('Run /gut-status in Claude Code to verify');
+        }
+    }
+}

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