ccmanager 4.3.1 → 4.4.0

package/dist/services/sessionRestoreStore.js

@@ -0,0 +1,138 @@
+/**
+ * @fileoverview Durable record of the sessions ccmanager currently has open,
+ * so that a later ccmanager run can offer to start them again.
+ *
+ * Only what is needed to launch the same command again is stored (which
+ * worktree, which command preset, the user-assigned session name). The
+ * terminal output and the conversation held inside the launched CLI are
+ * deliberately not stored: restoring means "run the launch command in that
+ * worktree again", not "bring back what was on screen".
+ *
+ * Every mutation is written to disk immediately and synchronously rather than
+ * on shutdown, so a crash, a `kill -9`, or a closed terminal still leaves an
+ * accurate record behind.
+ *
+ * Each mutation also re-reads the file before rewriting it. Two ccmanager
+ * processes share this one file, and a read-modify-write keeps one process's
+ * write from discarding sessions the other process recorded in the meantime.
+ */
+import path from 'path';
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { ensureConfigDir } from '../utils/configDir.js';
+import { logger } from '../utils/logger.js';
+/** Format version of the on-disk file, so future changes can be detected. */
+export const SESSION_RECORD_VERSION = 1;
+export const SESSION_RECORD_FILE_NAME = 'sessions.json';
+export class SessionRestoreStore {
+    explicitFilePath;
+    /**
+     * While true, mutations are ignored. Set just before ccmanager tears its
+     * sessions down on exit: those sessions are exactly the ones the next run
+     * should offer to restore, so their records must survive the teardown.
+     */
+    trackingSuspended = false;
+    constructor(filePath) {
+        this.explicitFilePath = filePath;
+    }
+    /**
+     * Resolved lazily rather than in the constructor so that merely importing
+     * this module does not create the configuration directory.
+     */
+    get filePath() {
+        return (this.explicitFilePath ??
+            path.join(ensureConfigDir(), SESSION_RECORD_FILE_NAME));
+    }
+    /** All recorded sessions, including ones owned by other ccmanager runs. */
+    list() {
+        return this.read();
+    }
+    /** Add a session to the record, replacing any earlier record with the same id. */
+    record(session) {
+        if (this.trackingSuspended) {
+            return;
+        }
+        this.write([...this.read().filter(s => s.id !== session.id), session]);
+    }
+    /**
+     * Drop sessions from the record, so they are not offered on the next run.
+     * Called when a session ends for a reason that means it should stay ended:
+     * the user killed it, or the launched command exited by itself.
+     */
+    forget(...ids) {
+        if (this.trackingSuspended || ids.length === 0) {
+            return;
+        }
+        const dropped = new Set(ids);
+        const remaining = this.read().filter(session => !dropped.has(session.id));
+        this.write(remaining);
+    }
+    /**
+     * Keep a renamed session's name in the record. An absent name means the
+     * user cleared it.
+     */
+    rename(id, sessionName) {
+        if (this.trackingSuspended) {
+            return;
+        }
+        const sessions = this.read();
+        const target = sessions.find(session => session.id === id);
+        if (!target) {
+            return;
+        }
+        target.sessionName = sessionName;
+        this.write(sessions);
+    }
+    /**
+     * Stop applying further mutations. Used when ccmanager is shutting down and
+     * destroys its sessions: without this the teardown would erase precisely the
+     * records the next run needs.
+     */
+    suspendTracking() {
+        this.trackingSuspended = true;
+    }
+    /** Resume applying mutations. Counterpart of {@link suspendTracking}. */
+    resumeTracking() {
+        this.trackingSuspended = false;
+    }
+    isTrackingSuspended() {
+        return this.trackingSuspended;
+    }
+    read() {
+        if (!existsSync(this.filePath)) {
+            return [];
+        }
+        try {
+            const parsed = JSON.parse(readFileSync(this.filePath, 'utf-8'));
+            if (!Array.isArray(parsed.sessions)) {
+                return [];
+            }
+            return parsed.sessions.filter(session => typeof session?.id === 'string' &&
+                typeof session?.projectPath === 'string' &&
+                typeof session?.worktreePath === 'string');
+        }
+        catch (error) {
+            // A truncated or hand-edited file must not stop ccmanager from
+            // starting; the worst outcome of ignoring it is no restore offer.
+            logger.warn(`Failed to read session records from ${this.filePath}: ${String(error)}`);
+            return [];
+        }
+    }
+    write(sessions) {
+        const contents = {
+            version: SESSION_RECORD_VERSION,
+            sessions,
+        };
+        try {
+            // Write to a sibling file and rename over the target: a crash midway
+            // through then leaves the previous complete file rather than a
+            // half-written one.
+            const tempPath = `${this.filePath}.${process.pid}.tmp`;
+            writeFileSync(tempPath, JSON.stringify(contents, null, 2));
+            renameSync(tempPath, this.filePath);
+        }
+        catch (error) {
+            logger.warn(`Failed to write session records to ${this.filePath}: ${String(error)}`);
+        }
+    }
+}
+export const sessionRestoreStore = new SessionRestoreStore();

package/dist/services/sessionRestoreStore.test.d.ts

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

package/dist/services/sessionRestoreStore.test.js

@@ -0,0 +1,92 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import path from 'path';
+import { SessionRestoreStore, SESSION_RECORD_VERSION, } from './sessionRestoreStore.js';
+describe('SessionRestoreStore', () => {
+    let directory;
+    let filePath;
+    let store;
+    const record = (overrides = {}) => ({
+        id: 'session-1',
+        projectPath: '/repo',
+        worktreePath: '/repo/worktrees/feature',
+        presetId: 'preset-1',
+        ownerPid: 1234,
+        createdAt: 1,
+        ...overrides,
+    });
+    beforeEach(() => {
+        directory = mkdtempSync(path.join(tmpdir(), 'ccmanager-records-'));
+        filePath = path.join(directory, 'sessions.json');
+        store = new SessionRestoreStore(filePath);
+    });
+    afterEach(() => {
+        rmSync(directory, { recursive: true, force: true });
+    });
+    it('returns no sessions when nothing has been recorded yet', () => {
+        expect(store.list()).toEqual([]);
+    });
+    it('writes each recorded session to disk immediately', () => {
+        store.record(record());
+        const contents = JSON.parse(readFileSync(filePath, 'utf-8'));
+        expect(contents.version).toBe(SESSION_RECORD_VERSION);
+        expect(contents.sessions).toHaveLength(1);
+        expect(contents.sessions[0].worktreePath).toBe('/repo/worktrees/feature');
+    });
+    it('replaces an existing record with the same id instead of duplicating it', () => {
+        store.record(record());
+        store.record(record({ presetId: 'preset-2' }));
+        expect(store.list()).toHaveLength(1);
+        expect(store.list()[0]?.presetId).toBe('preset-2');
+    });
+    it('forgets the requested sessions and keeps the others', () => {
+        store.record(record({ id: 'session-1' }));
+        store.record(record({ id: 'session-2' }));
+        store.record(record({ id: 'session-3' }));
+        store.forget('session-1', 'session-3');
+        expect(store.list().map(session => session.id)).toEqual(['session-2']);
+    });
+    it('keeps a renamed session name, and clears it when the name is removed', () => {
+        store.record(record());
+        store.rename('session-1', 'review');
+        expect(store.list()[0]?.sessionName).toBe('review');
+        store.rename('session-1', undefined);
+        expect(store.list()[0]?.sessionName).toBeUndefined();
+    });
+    it('keeps records while tracking is suspended, so a shutdown does not erase them', () => {
+        store.record(record());
+        store.suspendTracking();
+        store.forget('session-1');
+        store.record(record({ id: 'session-2' }));
+        expect(store.list().map(session => session.id)).toEqual(['session-1']);
+        store.resumeTracking();
+        store.forget('session-1');
+        expect(store.list()).toEqual([]);
+    });
+    it('picks up records another process wrote instead of overwriting them', () => {
+        // Stands in for a second ccmanager writing to the shared file between
+        // this store's own writes.
+        store.record(record({ id: 'session-1' }));
+        const other = new SessionRestoreStore(filePath);
+        other.record(record({ id: 'other-session' }));
+        store.record(record({ id: 'session-2' }));
+        expect(store
+            .list()
+            .map(session => session.id)
+            .sort()).toEqual(['other-session', 'session-1', 'session-2']);
+    });
+    it('ignores a corrupted file rather than failing', () => {
+        writeFileSync(filePath, '{not json');
+        expect(store.list()).toEqual([]);
+        store.record(record());
+        expect(store.list()).toHaveLength(1);
+    });
+    it('ignores entries that are missing the fields needed to launch them', () => {
+        writeFileSync(filePath, JSON.stringify({
+            version: SESSION_RECORD_VERSION,
+            sessions: [record(), { id: 'broken' }],
+        }));
+        expect(store.list().map(session => session.id)).toEqual(['session-1']);
+    });
+});

package/dist/services/sessionRestorer.d.ts

@@ -0,0 +1,46 @@
+import { SessionRecord } from './sessionRestoreStore.js';
+export interface RestoreFailure {
+    record: SessionRecord;
+    message: string;
+}
+export interface RestoreOutcome {
+    restored: number;
+    failures: RestoreFailure[];
+}
+/**
+ * Recorded sessions that this ccmanager run may offer to launch again.
+ *
+ * @param options.projectPath - When given, only sessions of that repository are
+ * returned (single-project mode). Omit it to consider every recorded project,
+ * which is what multi-project mode does.
+ */
+export declare function listRestorableSessions(options?: {
+    projectPath?: string;
+}): SessionRecord[];
+/**
+ * Name of the command preset a record will be launched with, for display.
+ * Resolved from the current configuration rather than stored alongside the
+ * record, so a renamed preset shows its current name. Records whose preset no
+ * longer exists fall back to the default preset, as launching does.
+ */
+export declare function describeRecordPreset(record: SessionRecord): string;
+/**
+ * Launch each recorded session again, in the session manager the running
+ * ccmanager will look at for its project.
+ *
+ * Sessions are started one at a time: each one is numbered relative to the
+ * sessions already present in its worktree, which only holds if they are not
+ * created concurrently.
+ *
+ * Every record is dropped from the durable store as it is processed — a
+ * successfully restored session records itself anew under its new id, and a
+ * failed one must not keep being offered on every subsequent start.
+ */
+export declare function restoreSessions(records: SessionRecord[], options: {
+    multiProject: boolean;
+}): Promise<RestoreOutcome>;
+/**
+ * Forget the offered sessions without launching them, so declining the offer
+ * does not make it come back on the next start.
+ */
+export declare function discardRestorableSessions(records: SessionRecord[]): void;

package/dist/services/sessionRestorer.js

@@ -0,0 +1,123 @@
+/**
+ * @fileoverview Turns the durable session record written by
+ * {@link SessionRestoreStore} back into running sessions.
+ *
+ * Restoring a session means launching its command preset in its worktree
+ * again — nothing of the previous run's terminal output or conversation is
+ * brought back. An initial prompt, if the session was originally started with
+ * one, is deliberately not replayed: it was a one-off instruction, not part of
+ * the session's identity.
+ */
+import { existsSync } from 'fs';
+import { Effect, Either } from 'effect';
+import { globalSessionOrchestrator } from './globalSessionOrchestrator.js';
+import { sessionRestoreStore } from './sessionRestoreStore.js';
+import { configReader } from './config/configReader.js';
+import { formatErrorMessage } from '../utils/errorMessage.js';
+import { logger } from '../utils/logger.js';
+/**
+ * Whether a process with this id is currently running. Used to leave alone the
+ * sessions of another ccmanager that is still open.
+ *
+ * A process id can be reused after a reboot, in which case an unrelated live
+ * process makes a record look owned and its session is silently not offered.
+ * That is the cheaper mistake: the opposite error would start a second copy of
+ * a session that is already running in another ccmanager window.
+ */
+function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) {
+        return false;
+    }
+    try {
+        // Signal 0 performs the permission and existence checks without
+        // delivering a signal.
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM means the process exists but belongs to another user.
+        return (typeof error === 'object' &&
+            error !== null &&
+            'code' in error &&
+            error.code === 'EPERM');
+    }
+}
+/**
+ * Recorded sessions that this ccmanager run may offer to launch again.
+ *
+ * @param options.projectPath - When given, only sessions of that repository are
+ * returned (single-project mode). Omit it to consider every recorded project,
+ * which is what multi-project mode does.
+ */
+export function listRestorableSessions(options = {}) {
+    return sessionRestoreStore
+        .list()
+        .filter(record => {
+        if (options.projectPath && record.projectPath !== options.projectPath) {
+            return false;
+        }
+        // The worktree may have been deleted while ccmanager was not running.
+        if (!existsSync(record.worktreePath)) {
+            logger.info(`Skipping session restore for missing worktree: ${record.worktreePath}`);
+            return false;
+        }
+        return !isProcessAlive(record.ownerPid);
+    })
+        .sort((a, b) => a.createdAt - b.createdAt);
+}
+/**
+ * Name of the command preset a record will be launched with, for display.
+ * Resolved from the current configuration rather than stored alongside the
+ * record, so a renamed preset shows its current name. Records whose preset no
+ * longer exists fall back to the default preset, as launching does.
+ */
+export function describeRecordPreset(record) {
+    const preset = record.presetId
+        ? Either.getOrElse(configReader.getPresetByIdEffect(record.presetId), () => undefined)
+        : undefined;
+    return preset?.name ?? configReader.getDefaultPreset()?.name ?? 'default';
+}
+/**
+ * Launch each recorded session again, in the session manager the running
+ * ccmanager will look at for its project.
+ *
+ * Sessions are started one at a time: each one is numbered relative to the
+ * sessions already present in its worktree, which only holds if they are not
+ * created concurrently.
+ *
+ * Every record is dropped from the durable store as it is processed — a
+ * successfully restored session records itself anew under its new id, and a
+ * failed one must not keep being offered on every subsequent start.
+ */
+export async function restoreSessions(records, options) {
+    const failures = [];
+    let restored = 0;
+    for (const record of records) {
+        sessionRestoreStore.forget(record.id);
+        // Single-project mode keeps every session in the one global manager;
+        // multi-project mode keeps a manager per project.
+        const manager = globalSessionOrchestrator.getManagerForProject(options.multiProject ? record.projectPath : undefined);
+        const sessionEffect = record.devcontainerConfig
+            ? manager.createSessionWithDevcontainerEffect(record.worktreePath, record.devcontainerConfig, record.presetId)
+            : manager.createSessionWithPresetEffect(record.worktreePath, record.presetId);
+        const result = await Effect.runPromise(Effect.either(sessionEffect));
+        if (result._tag === 'Left') {
+            const message = formatErrorMessage(result.left);
+            logger.error(`Failed to restore session in ${record.worktreePath}: ${message}`);
+            failures.push({ record, message });
+            continue;
+        }
+        if (record.sessionName) {
+            manager.renameSession(result.right.id, record.sessionName);
+        }
+        restored++;
+    }
+    return { restored, failures };
+}
+/**
+ * Forget the offered sessions without launching them, so declining the offer
+ * does not make it come back on the next start.
+ */
+export function discardRestorableSessions(records) {
+    sessionRestoreStore.forget(...records.map(record => record.id));
+}

package/dist/services/sessionRestorer.test.d.ts

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

package/dist/services/sessionRestorer.test.js

@@ -0,0 +1,163 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { Effect, Either } from 'effect';
+import { mkdtempSync, mkdirSync } from 'fs';
+import { tmpdir } from 'os';
+import path from 'path';
+import { ProcessError, ValidationError } from '../types/errors.js';
+const storedRecords = [];
+const forgetMock = vi.fn((...ids) => {
+    for (const id of ids) {
+        const index = storedRecords.findIndex(record => record.id === id);
+        if (index !== -1) {
+            storedRecords.splice(index, 1);
+        }
+    }
+});
+vi.mock('./sessionRestoreStore.js', () => ({
+    sessionRestoreStore: {
+        list: () => [...storedRecords],
+        forget: (...ids) => forgetMock(...ids),
+    },
+}));
+class MockSessionManager {
+    createSessionWithPresetEffect = vi.fn((_worktreePath, _presetId) => Effect.succeed({ id: 'new-session' }));
+    createSessionWithDevcontainerEffect = vi.fn((_worktreePath, _devcontainerConfig, _presetId) => Effect.succeed({ id: 'new-session' }));
+    renameSession = vi.fn((_id, _name) => { });
+}
+const managersByProject = new Map();
+const getManagerForProjectMock = vi.fn((projectPath) => {
+    let manager = managersByProject.get(projectPath);
+    if (!manager) {
+        manager = new MockSessionManager();
+        managersByProject.set(projectPath, manager);
+    }
+    return manager;
+});
+vi.mock('./globalSessionOrchestrator.js', () => ({
+    globalSessionOrchestrator: {
+        getManagerForProject: (projectPath) => getManagerForProjectMock(projectPath),
+    },
+}));
+vi.mock('./config/configReader.js', () => ({
+    configReader: {
+        getPresetByIdEffect: (id) => id === 'preset-1'
+            ? Either.right({ id: 'preset-1', name: 'Main' })
+            : Either.left(new ValidationError({
+                field: 'presetId',
+                constraint: 'Preset not found',
+                receivedValue: id,
+            })),
+        getDefaultPreset: () => ({ id: 'default', name: 'Default' }),
+    },
+}));
+const { listRestorableSessions, restoreSessions, discardRestorableSessions, describeRecordPreset, } = await import('./sessionRestorer.js');
+describe('sessionRestorer', () => {
+    let existingWorktree;
+    const record = (overrides = {}) => ({
+        id: 'session-1',
+        projectPath: '/repo',
+        worktreePath: existingWorktree,
+        presetId: 'preset-1',
+        // A process id that is not running, so the record counts as restorable.
+        ownerPid: 999999,
+        createdAt: 1,
+        ...overrides,
+    });
+    beforeEach(() => {
+        const directory = mkdtempSync(path.join(tmpdir(), 'ccmanager-restore-'));
+        existingWorktree = path.join(directory, 'feature');
+        mkdirSync(existingWorktree);
+        storedRecords.length = 0;
+        forgetMock.mockClear();
+        managersByProject.clear();
+        getManagerForProjectMock.mockClear();
+    });
+    describe('listRestorableSessions', () => {
+        it('offers a recorded session whose worktree still exists', () => {
+            storedRecords.push(record());
+            expect(listRestorableSessions().map(r => r.id)).toEqual(['session-1']);
+        });
+        it('skips a session whose worktree has been deleted', () => {
+            storedRecords.push(record({ worktreePath: '/gone/worktree' }));
+            expect(listRestorableSessions()).toEqual([]);
+        });
+        it('skips a session still owned by a running ccmanager', () => {
+            storedRecords.push(record({ ownerPid: process.pid }));
+            expect(listRestorableSessions()).toEqual([]);
+        });
+        it('only offers the requested project when a project path is given', () => {
+            storedRecords.push(record({ id: 'mine', projectPath: '/repo' }));
+            storedRecords.push(record({ id: 'other', projectPath: '/elsewhere' }));
+            expect(listRestorableSessions({ projectPath: '/repo' }).map(r => r.id)).toEqual(['mine']);
+        });
+        it('returns oldest first so sessions come back in the order they were opened', () => {
+            storedRecords.push(record({ id: 'second', createdAt: 20 }));
+            storedRecords.push(record({ id: 'first', createdAt: 10 }));
+            expect(listRestorableSessions().map(r => r.id)).toEqual([
+                'first',
+                'second',
+            ]);
+        });
+    });
+    describe('restoreSessions', () => {
+        it('launches the recorded preset in the recorded worktree', async () => {
+            const target = record();
+            const outcome = await restoreSessions([target], { multiProject: false });
+            const manager = managersByProject.get(undefined);
+            expect(manager.createSessionWithPresetEffect).toHaveBeenCalledWith(existingWorktree, 'preset-1');
+            expect(outcome).toEqual({ restored: 1, failures: [] });
+        });
+        it('drops the old record so the same session is not offered twice', async () => {
+            storedRecords.push(record());
+            await restoreSessions([record()], { multiProject: false });
+            expect(forgetMock).toHaveBeenCalledWith('session-1');
+            expect(storedRecords).toEqual([]);
+        });
+        it('restores the session name the user had given', async () => {
+            await restoreSessions([record({ sessionName: 'review' })], {
+                multiProject: false,
+            });
+            const manager = managersByProject.get(undefined);
+            expect(manager.renameSession).toHaveBeenCalledWith('new-session', 'review');
+        });
+        it('uses the manager of the recorded project in multi-project mode', async () => {
+            await restoreSessions([record()], { multiProject: true });
+            expect(getManagerForProjectMock).toHaveBeenCalledWith('/repo');
+        });
+        it('relaunches through the devcontainer when the session used one', async () => {
+            const devcontainerConfig = {
+                upCommand: 'devcontainer up',
+                execCommand: 'devcontainer exec',
+            };
+            await restoreSessions([record({ devcontainerConfig })], {
+                multiProject: false,
+            });
+            const manager = managersByProject.get(undefined);
+            expect(manager.createSessionWithDevcontainerEffect).toHaveBeenCalledWith(existingWorktree, devcontainerConfig, 'preset-1');
+        });
+        it('reports a failed session and carries on with the rest', async () => {
+            const failing = record({ id: 'failing' });
+            const succeeding = record({ id: 'succeeding' });
+            const manager = getManagerForProjectMock(undefined);
+            manager.createSessionWithPresetEffect.mockImplementationOnce(() => Effect.fail(new ProcessError({ command: 'claude', message: 'spawn failed' })));
+            const outcome = await restoreSessions([failing, succeeding], {
+                multiProject: false,
+            });
+            expect(outcome.restored).toBe(1);
+            expect(outcome.failures).toHaveLength(1);
+            expect(outcome.failures[0]?.record.id).toBe('failing');
+            expect(outcome.failures[0]?.message).toContain('spawn failed');
+        });
+    });
+    it('describes a record by its current preset name, falling back to the default', () => {
+        expect(describeRecordPreset(record())).toBe('Main');
+        expect(describeRecordPreset(record({ presetId: 'removed' }))).toBe('Default');
+        expect(describeRecordPreset(record({ presetId: undefined }))).toBe('Default');
+    });
+    it('forgets the sessions the user declined to restore', () => {
+        storedRecords.push(record({ id: 'a' }), record({ id: 'b' }));
+        discardRestorableSessions([record({ id: 'a' }), record({ id: 'b' })]);
+        expect(forgetMock).toHaveBeenCalledWith('a', 'b');
+        expect(storedRecords).toEqual([]);
+    });
+});

package/dist/services/worktreeService.d.ts

@@ -155,6 +155,18 @@ export declare class WorktreeService {
      * @throws {FileSystemError} When copying the directory fails
      */
     private copyClaudeDirectoryFromBaseBranchEffect;
+    /**
+     * Effect-based copyWorktreeIncludeFiles operation.
+     * Copies the gitignored files a `.worktreeinclude` file at the repository
+     * root selects (see src/utils/worktreeInclude.ts) into the new worktree.
+     * A no-op when no `.worktreeinclude` file exists, so this always runs
+     * unconditionally rather than being gated by a config flag.
+     *
+     * @param {string} gitRoot - Absolute path to the main checkout
+     * @param {string} targetWorktreePath - Path of the newly created worktree
+     * @returns {Effect.Effect<void, FileSystemError, never>} Effect that completes successfully or fails with FileSystemError
+     */
+    private copyWorktreeIncludeFilesEffect;
     /**
      * Effect-based getDefaultBranch operation
      * Returns Effect that may fail with GitError

package/dist/services/worktreeService.js

@@ -7,6 +7,7 @@ import { GitError, FileSystemError } from '../types/errors.js';
 import { setWorktreeParentBranch } from '../utils/worktreeConfig.js';
 import { getClaudeProjectsDir, pathToClaudeProjectName, } from '../utils/claudeDir.js';
 import { executeWorktreePostCreationHook, executeWorktreePreCreationHook, } from '../utils/hookExecutor.js';
+import { copyWorktreeIncludeFiles } from '../utils/worktreeInclude.js';
 import { configReader } from './config/configReader.js';
 import { logger } from '../utils/logger.js';
 const CLAUDE_DIR = '.claude';
@@ -448,6 +449,27 @@ export class WorktreeService {
             });
         });
     }
+    /**
+     * Effect-based copyWorktreeIncludeFiles operation.
+     * Copies the gitignored files a `.worktreeinclude` file at the repository
+     * root selects (see src/utils/worktreeInclude.ts) into the new worktree.
+     * A no-op when no `.worktreeinclude` file exists, so this always runs
+     * unconditionally rather than being gated by a config flag.
+     *
+     * @param {string} gitRoot - Absolute path to the main checkout
+     * @param {string} targetWorktreePath - Path of the newly created worktree
+     * @returns {Effect.Effect<void, FileSystemError, never>} Effect that completes successfully or fails with FileSystemError
+     */
+    copyWorktreeIncludeFilesEffect(gitRoot, targetWorktreePath) {
+        return Effect.try({
+            try: () => copyWorktreeIncludeFiles(gitRoot, targetWorktreePath),
+            catch: (error) => new FileSystemError({
+                operation: 'write',
+                path: targetWorktreePath,
+                cause: String(error),
+            }),
+        });
+    }
     /**
      * Effect-based getDefaultBranch operation
      * Returns Effect that may fail with GitError
@@ -967,6 +989,14 @@ export class WorktreeService {
                     return Effect.succeed(undefined);
                 });
             }
+            // Copy files selected by a .worktreeinclude file, if one exists at
+            // the repository root. Runs unconditionally (no config flag) and
+            // before the post-creation hook, so hook commands can rely on the
+            // copied files (e.g. .env) already being in place.
+            yield* Effect.catchAll(self.copyWorktreeIncludeFilesEffect(absoluteGitRoot, resolvedPath), (error) => {
+                console.error('Warning: Failed to copy .worktreeinclude files:', error);
+                return Effect.succeed(undefined);
+            });
             // Execute post-creation hook if configured
             const worktreeHooks = configReader.getWorktreeHooks();
             logger.info('Worktree hook config after creation', {