@1yefuwang1/dsh-worktrees 0.2.13 → 0.2.18

package/dist/context.js

@@ -14,11 +14,15 @@ export function renderWorktreeContext(record, state) {
         'Mode: isolated linked checkout.',
         `Execution directory: ${quote(record.effectiveCwd)}`,
         `Original local checkout: ${quote(record.repoRoot)}`,
-        `Fetched base branch: ${quote(`${record.remote}/${record.remoteBranch}`)}`,
+        record.branchSource === 'local'
+            ? `Local base branch: ${quote(record.localBranch ?? record.remoteBranch)}`
+            : `Fetched base branch: ${quote(`${record.remote}/${record.remoteBranch}`)}`,
         `Starting commit: ${quote(record.baseOid || 'not established')}`,
         `Checkout last known: ${quote(state === undefined ? 'unknown; inspect status before Git mutations' : state.branch === null ? 'detached HEAD' : state.branch)}`,
         ...(state === undefined ? [] : [`HEAD last known: ${quote(state.head)}`]),
-        'The base is a creation-time fetched snapshot, not continuous synchronization. Git refs and repository metadata remain shared.',
+        record.branchSource === 'local'
+            ? 'The base is a creation-time local commit snapshot pinned without fetching, not continuous synchronization. Git refs and repository metadata remain shared.'
+            : 'The base is a creation-time fetched snapshot, not continuous synchronization. Git refs and repository metadata remain shared.',
         'Work in the current session directory. Preserve the local checkout unless an explicit handoff is requested. Historical paths may refer to an earlier checkout; verify before writing.',
     ].join('\n');
 }

package/dist/git.d.ts

@@ -1,4 +1,4 @@
-import type { CheckoutState, CreateCheckoutInput, CreatedCheckout, GitExecutor, RemoteBranches, RemoteInfo, RepositoryInfo, SnapshotInput, WorktreeConfig, WorktreePreview, WorktreeRecord } from './types.js';
+import type { CheckoutState, CreateCheckoutInput, CreatedCheckout, GitExecutor, LocalBranches, RemoteBranches, RemoteInfo, RepositoryInfo, SnapshotInput, WorktreeConfig, WorktreePreview, WorktreeRecord } from './types.js';
 /** Strict Git engine. Its executor must enforce byte bounds, deadlines and caller sandbox access. */
 export declare class GitOperations {
     private readonly execute;
@@ -14,6 +14,9 @@ export declare class GitOperations {
     private remote;
     remotes(repoRoot: string, signal?: AbortSignal): Promise<RemoteInfo[]>;
     branches(repoRoot: string, remote: string, identity?: string, signal?: AbortSignal): Promise<RemoteBranches>;
+    /** One bounded local ref generation; no remote configuration or network commands. */
+    localBranches(repoRoot: string, signal?: AbortSignal): Promise<LocalBranches>;
+    private localBase;
     private destination;
     private store;
     private removeStore;

package/dist/git.js

@@ -145,8 +145,11 @@ export class GitOperations {
         const headResult = await this.run(root, ['rev-parse', '--verify', 'HEAD^{commit}'], signal, { allowed: [0, 128] });
         if (headResult.exitCode !== 0)
             fail('UNBORN_REPOSITORY', 'The repository does not have a committed HEAD.');
-        const branchResult = await this.run(root, ['symbolic-ref', '--quiet', '--short', 'HEAD'], signal, { allowed: [0, 1] });
-        return { root, commonDir, projectSubdir: path.relative(root, project).split(path.sep).join('/'), head: oid(line(headResult.stdout)), branch: branchResult.exitCode === 0 ? line(branchResult.stdout) : null };
+        const branchResult = await this.run(root, ['symbolic-ref', '--quiet', 'HEAD'], signal, { allowed: [0, 1] });
+        const branchRef = branchResult.exitCode === 0 ? line(branchResult.stdout) : null;
+        if (branchRef !== null && !branchRef.startsWith('refs/heads/'))
+            fail('UNSUPPORTED_REF', 'HEAD must identify a local branch or a detached commit.');
+        return { root, commonDir, projectSubdir: path.relative(root, project).split(path.sep).join('/'), head: oid(line(headResult.stdout)), branch: branchRef === null ? null : branchRef.slice(11) };
     }
     async ref(root, value, signal) {
         if (value.includes('\0') || value.includes('\n') || value.startsWith('-'))
@@ -253,6 +256,83 @@ export class GitOperations {
             fail('REMOTE_CHANGED', 'The remote identity changed during branch discovery.');
         return { remote, remoteIdentity: selected.identity, defaultBranch, branches: branches.sort((a, b) => a.name.localeCompare(b.name)), observedAt: Date.now() };
     }
+    /** One bounded local ref generation; no remote configuration or network commands. */
+    async localBranches(repoRoot, signal) {
+        const repository = await this.discover(repoRoot, signal);
+        const result = await this.run(repository.root, ['for-each-ref', '--format=%(refname)%00%(objectname)%00%(objecttype)%00%(symref)%00', 'refs/heads/'], signal);
+        const output = text(result.stdout);
+        if (output && !output.endsWith('\n'))
+            fail('TRUNCATED_OUTPUT', 'The local branch generation was truncated.');
+        const branches = [];
+        const seen = new Set();
+        for (const row of output ? output.slice(0, -1).split('\n') : []) {
+            const parts = row.split('\0');
+            if (parts.length !== 5 || parts[4] !== '' || !parts[0]?.startsWith('refs/heads/'))
+                fail('INVALID_GIT_OUTPUT', 'Git returned an invalid local reference.');
+            await this.ref(repository.root, parts[0], signal);
+            if (parts[2] !== 'commit' || parts[3] !== '')
+                fail('UNSUPPORTED_REF', 'Local branches must directly identify commits, not symbolic refs or other objects.');
+            const name = parts[0].slice(11);
+            if (name === 'HEAD' || seen.has(name))
+                fail('UNSUPPORTED_REF', 'The local branch generation contains an ambiguous branch.');
+            seen.add(name);
+            branches.push({ name, oid: oid(parts[1]) });
+            if (branches.length > this.config.maxFiles)
+                fail('REF_LIMIT', 'The local branch generation exceeds the configured count limit.');
+        }
+        const after = await this.discover(repoRoot, signal);
+        if (after.root !== repository.root || after.commonDir !== repository.commonDir || after.head !== repository.head || after.branch !== repository.branch)
+            fail('BRANCH_CHANGED', 'HEAD changed during local branch discovery. Reload its first page.');
+        if (repository.branch === null)
+            branches.push({ name: 'HEAD', oid: repository.head });
+        else if (branches.find(branch => branch.name === repository.branch)?.oid !== repository.head)
+            fail('BRANCH_CHANGED', 'The current branch changed during local branch discovery.');
+        if (branches.length > this.config.maxFiles)
+            fail('REF_LIMIT', 'The local branch generation exceeds the configured count limit.');
+        return { branchSource: 'local', currentBranch: repository.branch, defaultBranch: repository.branch ?? 'HEAD', branches: branches.sort((a, b) => a.name.localeCompare(b.name)), observedAt: Date.now() };
+    }
+    async localBase(repository, input) {
+        const { signal, localBranch, localOid } = input;
+        if (!localBranch || localBranch.startsWith('-'))
+            fail('INVALID_REF', 'The selected local branch name is invalid.');
+        if (localOid !== undefined && !oidPattern.test(localOid))
+            fail('INVALID_REF', 'The selected local commit identity is invalid.');
+        const ref = localBranch === 'HEAD' ? 'HEAD' : `refs/heads/${localBranch}`;
+        if (localBranch === 'HEAD') {
+            if (localOid === undefined)
+                fail('INVALID_REF', 'Detached HEAD creation requires an expected local commit.');
+            if (repository.branch !== null)
+                fail('BRANCH_CHANGED', 'HEAD is no longer detached. Reload the local branch list.');
+        }
+        else
+            await this.ref(repository.root, ref, signal);
+        const symbolic = await this.run(repository.root, ['symbolic-ref', '--quiet', ref], signal, { allowed: [0, 1] });
+        if (symbolic.exitCode === 0)
+            fail('UNSUPPORTED_REF', 'The selected local reference must directly identify a commit.');
+        const resolved = await this.run(repository.root, ['rev-parse', '--verify', '--end-of-options', `${ref}^{commit}`], signal, { allowed: [0, 128] });
+        if (resolved.exitCode !== 0)
+            fail('LOCAL_BRANCH_NOT_FOUND', 'The selected local branch has no commit.');
+        const baseOid = oid(line(resolved.stdout));
+        const direct = oid(line((await this.run(repository.root, ['rev-parse', '--verify', '--end-of-options', ref], signal)).stdout));
+        if (direct !== baseOid)
+            fail('UNSUPPORTED_REF', 'The selected local branch must directly identify a commit.');
+        if (localOid !== undefined && localOid !== baseOid)
+            fail('BRANCH_CHANGED', 'The selected local branch moved. Reload its branch list.');
+        // Compare the source under its ref lock and create (never overwrite/dereference)
+        // the managed base in the same transaction. No source ref/index/file is changed.
+        const pin = await this.run(repository.root, ['update-ref', '--no-deref', '--stdin'], signal, {
+            stdin: `start\nverify ${ref} ${baseOid}\ncreate ${input.baseRef} ${baseOid}\nprepare\ncommit\n`, allowed: [0, 128],
+        });
+        if (pin.exitCode !== 0)
+            fail('BRANCH_CHANGED', 'The local branch or managed base changed before pinning; no checkout was created.');
+        // Git's no-deref verify may still compare a symbolic ref's resolved OID.
+        // Reject replacement explicitly before any checkout, retaining the exact base
+        // as a recovery receipt rather than ever writing through the source reference.
+        const after = await this.run(repository.root, ['symbolic-ref', '--quiet', ref], signal, { allowed: [0, 1] });
+        if (after.exitCode === 0)
+            fail('BRANCH_CHANGED', 'The selected local branch became symbolic during pinning; the exact base may remain but no checkout was created.', { refsMayHaveChanged: true });
+        return baseOid;
+    }
     async destination(root, requested) {
         const absolute = path.resolve(requested);
         const parent = await realpath(path.dirname(absolute)).catch(() => fail('MISSING_PATH', 'The managed checkout parent directory is unavailable.'));
@@ -315,27 +395,39 @@ export class GitOperations {
         if (repository.root !== input.repository.root || repository.commonDir !== input.repository.commonDir)
             fail('REPOSITORY_CHANGED', 'The source repository identity changed.');
         const destination = await this.destination(repository.root, input.destination);
-        if (!input.remoteBranch || input.remoteBranch.startsWith('-'))
-            fail('INVALID_REF', 'The selected branch name is invalid.');
-        await this.ref(repository.root, `refs/heads/${input.remoteBranch}`, signal);
-        await this.ref(repository.root, `refs/remotes/${input.remote}/${input.remoteBranch}`, signal);
         await this.ref(repository.root, input.baseRef, signal);
         if (!input.baseRef.startsWith('refs/dsh-worktrees/'))
             fail('INVALID_REF', 'The persistent base ref must use the managed worktree namespace.');
         const prior = await this.run(repository.root, ['show-ref', '--verify', '--quiet', input.baseRef], signal, { allowed: [0, 1] });
         if (prior.exitCode === 0)
             fail('BASE_REF_EXISTS', 'The persistent base reference is already in use.');
-        const remote = await this.remote(repository.root, input.remote, signal);
-        if (remote.identity !== input.remoteIdentity)
-            fail('REMOTE_CHANGED', 'The selected remote identity has changed.');
-        checkoutProgress(input, 'fetching');
-        await this.run(repository.root, ['fetch', '--atomic', '--refmap=', '--no-tags', '--no-write-fetch-head', '--no-recurse-submodules', '--no-auto-maintenance', '--no-write-commit-graph', '--no-prune', '--upload-pack=git-upload-pack', '--', input.remote, `+refs/heads/${input.remoteBranch}:refs/remotes/${input.remote}/${input.remoteBranch}`, `refs/heads/${input.remoteBranch}:${input.baseRef}`], signal, { fetch: true });
-        if ((await this.remote(repository.root, input.remote, signal)).identity !== remote.identity)
-            fail('REMOTE_CHANGED', 'The remote changed during fetch; fetched refs may remain.', { refsMayHaveChanged: true });
-        const baseOid = oid(line((await this.run(repository.root, ['rev-parse', '--verify', `${input.baseRef}^{commit}`], signal)).stdout));
+        let baseOid;
+        if (input.branchSource === 'local') {
+            if (input.remote !== undefined || input.remoteIdentity !== undefined || input.remoteBranch !== undefined)
+                fail('INVALID_REQUEST', 'Local source does not accept remote fields.');
+            baseOid = await this.localBase(repository, input);
+        }
+        else {
+            if (input.branchSource !== undefined && input.branchSource !== 'remote')
+                fail('INVALID_REQUEST', 'The branch source is invalid.');
+            if (input.localBranch !== undefined || input.localOid !== undefined)
+                fail('INVALID_REQUEST', 'Remote source does not accept local fields.');
+            if (!input.remoteBranch || input.remoteBranch.startsWith('-'))
+                fail('INVALID_REF', 'The selected branch name is invalid.');
+            await this.ref(repository.root, `refs/heads/${input.remoteBranch}`, signal);
+            await this.ref(repository.root, `refs/remotes/${input.remote}/${input.remoteBranch}`, signal);
+            const remote = await this.remote(repository.root, input.remote, signal);
+            if (remote.identity !== input.remoteIdentity)
+                fail('REMOTE_CHANGED', 'The selected remote identity has changed.');
+            checkoutProgress(input, 'fetching');
+            await this.run(repository.root, ['fetch', '--atomic', '--refmap=', '--no-tags', '--no-write-fetch-head', '--no-recurse-submodules', '--no-auto-maintenance', '--no-write-commit-graph', '--no-prune', '--upload-pack=git-upload-pack', '--', input.remote, `+refs/heads/${input.remoteBranch}:refs/remotes/${input.remote}/${input.remoteBranch}`, `refs/heads/${input.remoteBranch}:${input.baseRef}`], signal, { fetch: true });
+            if ((await this.remote(repository.root, input.remote, signal)).identity !== remote.identity)
+                fail('REMOTE_CHANGED', 'The remote changed during fetch; fetched refs may remain.', { refsMayHaveChanged: true });
+            baseOid = oid(line((await this.run(repository.root, ['rev-parse', '--verify', `${input.baseRef}^{commit}`], signal)).stdout));
+        }
         const entries = await this.tree(repository.root, baseOid, signal);
         if (repository.projectSubdir && !entries.some(entry => entry.path.startsWith(`${repository.projectSubdir}/`)))
-            fail('PROJECT_SUBDIR_MISSING', 'The project subdirectory is absent from the freshly fetched tree.');
+            fail('PROJECT_SUBDIR_MISSING', 'The project subdirectory is absent from the selected base tree.');
         // Attribute validation uses an isolated index and object store, never the source index.
         const privateStore = await this.store(path.dirname(destination), repository.commonDir);
         try {
@@ -344,7 +436,7 @@ export class GitOperations {
             for (const entry of entries.filter(value => value.mode === '120000')) {
                 const target = text((await this.run(repository.root, ['cat-file', 'blob', entry.oid], signal)).stdout);
                 if (!target || path.isAbsolute(target) || !inside(destination, path.resolve(destination, path.dirname(entry.path), target)))
-                    fail('UNSAFE_SYMLINK', 'The fetched tree contains an escaping symlink.');
+                    fail('UNSAFE_SYMLINK', 'The selected base tree contains an escaping symlink.');
             }
         }
         finally {
@@ -354,7 +446,7 @@ export class GitOperations {
         try {
             await this.run(repository.root, ['worktree', 'add', '--detach', '--', destination, baseOid], signal);
             const checkoutRoot = await realpath(destination);
-            const effectiveCwd = await realpath(path.join(checkoutRoot, repository.projectSubdir)).catch(() => fail('PROJECT_SUBDIR_MISSING', 'The fetched project directory is unavailable.'));
+            const effectiveCwd = await realpath(path.join(checkoutRoot, repository.projectSubdir)).catch(() => fail('PROJECT_SUBDIR_MISSING', 'The selected base project directory is unavailable.'));
             if (checkoutRoot !== destination || !inside(checkoutRoot, effectiveCwd))
                 fail('UNSAFE_PATH', 'The created checkout has an unsafe project mapping.');
             return { checkoutRoot, effectiveCwd, baseOid, baseRef: input.baseRef, fetchedAt: Date.now() };
@@ -407,7 +499,16 @@ export class GitOperations {
         }
         const registration = nul((await this.run(repositoryRoot, ['worktree', 'list', '--porcelain', '-z'], signal)).stdout);
         const roots = registration.filter(value => value.startsWith('worktree ')).map(value => value.slice(9));
-        if (roots.filter(value => value === info.root).length !== 1)
+        // Git reports these machine-formatted, so a raw comparison against the canonical
+        // root fails wherever the two forms differ: Windows mixes separators and may
+        // report a short name, and a symlinked ancestor appears in one form only. Match
+        // canonically, and leave an entry that cannot be resolved unmatched rather than
+        // turning a stale registration into a failure to enumerate.
+        const matches = await Promise.all(roots.map(async (value) => {
+            const canonical = await realpath(value).catch(() => undefined);
+            return canonical === undefined ? value === info.root : canonical === info.root;
+        }));
+        if (matches.filter(Boolean).length !== 1)
             fail('CHECKOUT_IDENTITY_CHANGED', 'The checkout is not uniquely registered with its source repository.');
     }
     async verify(record, signal) {
@@ -699,7 +800,6 @@ export class GitOperations {
             await this.run(source.root, ['add', '-A', '--', '.'], signal, { env: privateStore.env });
             const finalTree = oid(line((await this.run(source.root, ['write-tree'], signal, { env: privateStore.env })).stdout));
             const finalEntries = await this.tree(source.root, finalTree, signal, privateStore.env);
-            await this.exactContents(source.root, finalEntries, sourceFiles.paths, signal);
             await this.attributes(source.root, finalEntries.map(entry => entry.path), signal, privateStore.env, true);
             const files = await this.patchFiles(source.root, input.baseOid, finalTree, privateStore, signal);
             for (const file of files) {
@@ -707,6 +807,10 @@ export class GitOperations {
                 if (symlinks.has(file.path) || symlinks.has(original))
                     fail('UNSAFE_SYMLINK', 'Changed symlinks are not supported by handoff snapshots.');
             }
+            // Refuse changed symlinks before comparing native readlink bytes with Git blobs:
+            // Windows normalizes link separators, but these changes are unsupported either way.
+            // Supported files must still match their exact working bytes and modes.
+            await this.exactContents(source.root, finalEntries, sourceFiles.paths, signal);
             await this.collisions(target.root, files, base);
             const patch = (await this.run(source.root, ['diff', '--binary', '--full-index', '--no-ext-diff', '--no-textconv', '--find-renames', '--src-prefix=a/', '--dst-prefix=b/', input.baseOid, finalTree, '--'], signal, { env: privateStore.env, maxBytes: this.config.maxSnapshotBytes })).stdout;
             if (await this.fingerprint(source.root, signal) !== sourceFingerprint)

package/dist/index.js

@@ -118,7 +118,7 @@ export async function apply(ctx, config) {
     });
     ctx.tools.register({
         name: 'git_worktree',
-        description: 'List or create isolated Git worktree threads from a freshly fetched remote branch; preview/export or hand off changes to a clean Local checkout. Cross-root Git mutations require existing full access. Handoff refuses running source/target sessions and never resets or deletes checkouts.',
+        description: 'List or create isolated Git worktree threads from an exact local branch without network access or a freshly fetched remote branch; preview/export or hand off changes to a clean Local checkout. Cross-root Git mutations require existing full access. Handoff refuses running source/target sessions and never resets or deletes checkouts.',
         parameters: parameterSchema,
         output: { schema: { type: 'object', additionalProperties: true }, render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }] },
         isConcurrencySafe: args => {

package/dist/project-store.d.ts

@@ -24,8 +24,8 @@ export declare const projectBindingSchema: z.ZodObject<{
     projectId: z.ZodString;
     folderId: z.ZodString;
     mode: z.ZodEnum<{
-        worktree: "worktree";
         local: "local";
+        worktree: "worktree";
     }>;
     effectiveCwd: z.ZodString;
     worktreeId: z.ZodOptional<z.ZodString>;
@@ -85,7 +85,7 @@ export declare const projectDomain: {
             sessionId: string;
             projectId: string;
             folderId: string;
-            mode: "worktree" | "local";
+            mode: "local" | "worktree";
             effectiveCwd: string;
             worktreeId?: string | undefined;
         }>;

package/dist/schema.d.ts

@@ -18,6 +18,12 @@ export declare const requestSchema: z.ZodObject<{
     repoPath: z.ZodOptional<z.ZodString>;
     id: z.ZodOptional<z.ZodString>;
     operationId: z.ZodOptional<z.ZodString>;
+    branchSource: z.ZodOptional<z.ZodEnum<{
+        local: "local";
+        remote: "remote";
+    }>>;
+    localBranch: z.ZodOptional<z.ZodString>;
+    localOid: z.ZodOptional<z.ZodString>;
     remote: z.ZodOptional<z.ZodString>;
     remoteIdentity: z.ZodOptional<z.ZodString>;
     remoteBranch: z.ZodOptional<z.ZodString>;

package/dist/schema.js

@@ -6,6 +6,9 @@ const text = z.string().min(1).max(4096);
 const id = z.string().uuid();
 export const requestSchema = z.object({
     action: z.enum(ACTIONS), repoPath: text.optional(), id: id.optional(), operationId: id.optional(),
+    branchSource: z.enum(['local', 'remote']).describe('Branch source; omitted preserves remote behavior.').optional(),
+    localBranch: text.describe('Exact local branch name, or HEAD for a pinned detached HEAD.').optional(),
+    localOid: z.string().regex(/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u).describe('Expected local commit; fail if the selected branch moved. Required for detached HEAD.').optional(),
     remote: text.optional(), remoteIdentity: text.optional(), remoteBranch: text.optional(),
     sourceSessionId: z.string().min(1).max(256).optional(), sessionMode: z.enum(['new', 'continue']).optional(),
     requireBlankSource: z.boolean().optional(), settingsHash: z.string().max(128).optional(),
@@ -19,8 +22,8 @@ export const requestSchema = z.object({
 const fields = {
     list: ['repoPath', 'cursor', 'limit', 'includeArchived'],
     status: ['repoPath', 'id', 'operationId'],
-    branches: ['repoPath', 'remote', 'remoteIdentity', 'query', 'cursor', 'limit'],
-    create: ['repoPath', 'operationId', 'remote', 'remoteIdentity', 'remoteBranch', 'sourceSessionId', 'sessionMode', 'requireBlankSource', 'settingsHash', 'firstPrompt', 'projectId', 'folderId'],
+    branches: ['repoPath', 'branchSource', 'remote', 'remoteIdentity', 'query', 'cursor', 'limit'],
+    create: ['repoPath', 'operationId', 'branchSource', 'localBranch', 'localOid', 'remote', 'remoteIdentity', 'remoteBranch', 'sourceSessionId', 'sessionMode', 'requireBlankSource', 'settingsHash', 'firstPrompt', 'projectId', 'folderId'],
     start: ['id', 'sourceSessionId', 'sessionMode'],
     branch: ['id', 'name'], protect: ['id', 'protected'],
     preview: ['id', 'sourceSessionId', 'targetPath'], export: ['previewId'],
@@ -35,12 +38,24 @@ export function parseRequest(value) {
         if (key !== 'action' && !fields[request.action].includes(key))
             throw new WorktreeError('INVALID_REQUEST', `${request.action} does not accept ${key}.`);
     const required = {
-        create: ['operationId', 'remote', 'remoteBranch'], start: ['id'], branch: ['id', 'name'], protect: ['id', 'protected'],
-        preview: ['id'], export: ['previewId'], handoff: ['id', 'previewId', 'operationId'], archive: ['id'], branches: ['remote'],
+        create: ['operationId'], start: ['id'], branch: ['id', 'name'], protect: ['id', 'protected'],
+        preview: ['id'], export: ['previewId'], handoff: ['id', 'previewId', 'operationId'], archive: ['id'],
     };
     for (const key of required[request.action] ?? [])
         if (request[key] === undefined)
             throw new WorktreeError('INVALID_REQUEST', `${request.action} requires ${key}.`);
+    if (request.action === 'create' || request.action === 'branches') {
+        const local = request.branchSource === 'local';
+        const sourceFields = local ? (request.action === 'create' ? ['localBranch'] : []) : (request.action === 'create' ? ['remote', 'remoteBranch'] : ['remote']);
+        for (const key of sourceFields)
+            if (request[key] === undefined)
+                throw new WorktreeError('INVALID_REQUEST', `${request.action} requires ${key}.`);
+        for (const key of local ? ['remote', 'remoteIdentity', 'remoteBranch'] : ['localBranch', 'localOid'])
+            if (request[key] !== undefined)
+                throw new WorktreeError('INVALID_REQUEST', `${local ? 'Local' : 'Remote'} source does not accept ${key}.`);
+        if (local && request.localBranch === 'HEAD' && request.localOid === undefined)
+            throw new WorktreeError('INVALID_REQUEST', 'Detached HEAD creation requires localOid.');
+    }
     if (request.action === 'status' && request.id !== undefined && request.operationId !== undefined)
         throw new WorktreeError('INVALID_REQUEST', 'Status accepts either id or operationId, not both.');
     if ((request.projectId === undefined) !== (request.folderId === undefined))

package/dist/service.d.ts

@@ -16,7 +16,7 @@ export interface Invocation {
     /** Internal admission snapshot only; execute always replaces caller-supplied values. */
     capturedRoot?: string;
 }
-type GitApi = Pick<GitOperations, 'discover' | 'remotes' | 'branches' | 'create' | 'verify' | 'status' | 'createBranch' | 'renameBranch' | 'fingerprint' | 'snapshot' | 'apply'>;
+type GitApi = Pick<GitOperations, 'discover' | 'remotes' | 'branches' | 'localBranches' | 'create' | 'verify' | 'status' | 'createBranch' | 'renameBranch' | 'fingerprint' | 'snapshot' | 'apply'>;
 type BootstrapApi = Pick<SessionBootstrap, 'actor' | 'isLive' | 'settings' | 'assertBlank' | 'create' | 'close'>;
 export interface ControllerDependencies {
     git?: (actor: Agent, signal: AbortSignal, guard: () => void) => GitApi;

package/dist/service.js

@@ -478,6 +478,24 @@ export class WorktreeController {
         return { repository, projectPath: path, ...(projectBinding === undefined ? {} : { projectBinding }), remotes: await git.remotes(repository.root, invocation.signal), settingsHash: settings.hash, defaults: { remote: this.config.defaultRemote, branch: this.config.defaultBranch }, namingConfig: namingConfig(this.config) };
     }
     async branches(request, invocation, git, repository) {
+        if (request.branchSource === 'local') {
+            let generation = this.generation;
+            if (request.cursor === undefined) {
+                this.generation = undefined;
+                const value = await git.localBranches(repository.root, invocation.signal);
+                generation = { id: randomUUID(), repository: hashValue([repository.root, repository.commonDir]), branchSource: 'local', value: { ...value, branches: [...value.branches].sort((a, b) => a.name.localeCompare(b.name)) } };
+                this.generation = generation;
+            }
+            // HEAD/default is checkout-specific even when linked checkouts share refs.
+            if (generation === undefined || generation.branchSource !== 'local' || generation.repository !== hashValue([repository.root, repository.commonDir]))
+                throw new WorktreeError('STALE_CURSOR', 'The local branch generation expired. Reload its first page.');
+            const query = request.query ?? '';
+            const items = generation.value.branches.filter(branch => branch.name.toLocaleLowerCase().includes(query.toLocaleLowerCase()));
+            const key = hashValue({ generation: generation.id, query });
+            const offset = this.cursor(key, request.cursor);
+            const limit = request.limit ?? 50;
+            return { branchSource: 'local', currentBranch: generation.value.currentBranch, defaultBranch: generation.value.defaultBranch, items: items.slice(offset, offset + limit), observedAt: generation.value.observedAt, ...(offset + limit < items.length ? { nextCursor: this.nextCursor(key, offset + limit) } : {}) };
+        }
         const remote = requiredText(request.remote, 'remote');
         const identity = (await git.remotes(repository.root, invocation.signal)).find(r => r.name === remote)?.identity;
         if (identity === undefined)
@@ -488,10 +506,10 @@ export class WorktreeController {
         if (request.cursor === undefined) {
             this.generation = undefined;
             const value = await git.branches(repository.root, remote, identity, invocation.signal);
-            generation = { id: randomUUID(), repository: repository.commonDir, value: { ...value, branches: [...value.branches].sort((a, b) => a.name.localeCompare(b.name)) } };
+            generation = { id: randomUUID(), repository: repository.commonDir, branchSource: 'remote', value: { ...value, branches: [...value.branches].sort((a, b) => a.name.localeCompare(b.name)) } };
             this.generation = generation;
         }
-        if (generation === undefined || generation.repository !== repository.commonDir || generation.value.remote !== remote || generation.value.remoteIdentity !== identity)
+        if (generation === undefined || generation.branchSource !== 'remote' || generation.repository !== repository.commonDir || generation.value.remote !== remote || generation.value.remoteIdentity !== identity)
             throw new WorktreeError('STALE_CURSOR', 'The branch generation expired. Reload its first page.');
         const query = request.query ?? '';
         const items = generation.value.branches.filter(branch => branch.name.toLocaleLowerCase().includes(query.toLocaleLowerCase()));
@@ -560,6 +578,9 @@ export class WorktreeController {
         if (request.requireBlankSource === true)
             await this.bootstrap.assertBlank(source);
         let repository = await git.discover(path, invocation.signal);
+        // Local HEAD is specific to the selected execution checkout, not its logical
+        // original Local folder (which may be attached to a different branch).
+        const selectedRepository = repository;
         let project = this.projectSelection(path, request);
         if (project === undefined && this.dependencies.projects !== undefined) {
             // An explicit agent repoPath may not have had a native Workspace yet.
@@ -595,13 +616,20 @@ export class WorktreeController {
         return this.queued(repository.commonDir, invocation.signal, async () => {
             this.assertProject(project);
             await this.sameSettings(source, settings, request, invocation);
-            const remote = requiredText(request.remote, 'remote');
-            const remoteBranch = requiredText(request.remoteBranch, 'remoteBranch');
-            const identity = (await git.remotes(repository.root, invocation.signal)).find(r => r.name === remote)?.identity;
-            if (identity === undefined)
-                throw new WorktreeError('REMOTE_NOT_FOUND', 'The selected remote is not configured.');
-            if (request.remoteIdentity !== undefined && request.remoteIdentity !== identity)
-                throw new WorktreeError('REMOTE_CHANGED', 'The remote configuration changed. Reload its branch list.');
+            const branchSource = request.branchSource ?? 'remote';
+            const remote = branchSource === 'local' ? 'local' : requiredText(request.remote, 'remote');
+            const remoteBranch = branchSource === 'local' ? requiredText(request.localBranch, 'localBranch') : requiredText(request.remoteBranch, 'remoteBranch');
+            let identity;
+            if (branchSource === 'local')
+                identity = hashValue(repository.commonDir);
+            else {
+                const selected = (await git.remotes(repository.root, invocation.signal)).find(r => r.name === remote)?.identity;
+                if (selected === undefined)
+                    throw new WorktreeError('REMOTE_NOT_FOUND', 'The selected remote is not configured.');
+                if (request.remoteIdentity !== undefined && request.remoteIdentity !== selected)
+                    throw new WorktreeError('REMOTE_CHANGED', 'The remote configuration changed. Reload its branch list.');
+                identity = selected;
+            }
             const root = resolveWorktreeRoot(await canonicalFuture(resolveWorktreeRoot(invocation.capturedRoot)));
             if (contained(repository.root, root))
                 throw new WorktreeError('UNSAFE_ROOT', 'The worktree root must be outside the source checkout.');
@@ -609,14 +637,15 @@ export class WorktreeController {
             const directoryRoot = resolve(root, hashValue(repository.commonDir).slice(0, 24), id);
             const initialBranch = `worktree/${id}`;
             const destination = resolve(directoryRoot, `worktree-${id}`);
-            const record = { id, operationId, repoRoot: repository.root, commonDir: repository.commonDir, projectSubdir: repository.projectSubdir, checkoutRoot: destination, effectiveCwd: resolve(destination, repository.projectSubdir), remote, remoteIdentity: identity, remoteBranch, baseOid: '', baseRef: `refs/dsh-worktrees/${id}/base`, fetchedAt: 0, createdAt: Date.now(), sessionIds: [], workspaceId: null, branch: null, ...(project === undefined ? {} : { projectId: project.projectId, folderId: project.folderId }), protected: false, archived: false, state: 'creating', error: null };
+            const record = { id, operationId, repoRoot: repository.root, commonDir: repository.commonDir, projectSubdir: repository.projectSubdir, checkoutRoot: destination, effectiveCwd: resolve(destination, repository.projectSubdir), remote, remoteIdentity: identity, remoteBranch, branchSource, ...(branchSource === 'local' ? { localBranch: remoteBranch } : {}), baseOid: '', baseRef: `refs/dsh-worktrees/${id}/base`, fetchedAt: 0, createdAt: Date.now(), sessionIds: [], workspaceId: null, branch: null, ...(project === undefined ? {} : { projectId: project.projectId, folderId: project.folderId }), protected: false, archived: false, state: 'creating', error: null };
             let operation = this.newOperation(operationId, 'create', requestHash, invocation.agent, record, source, settings, request.sessionMode ?? 'new');
             let effects = false;
             try {
                 await this.putOperation(operation, request, invocation);
                 await this.putRecord(record, request, invocation);
                 await this.sameSettings(source, settings, request, invocation);
-                operation = await this.phase(operation, 'fetching', request, invocation);
+                if (branchSource === 'remote')
+                    operation = await this.phase(operation, 'fetching', request, invocation);
                 effects = true;
                 this.guard(request, invocation);
                 await mkdir(dirname(destination), { recursive: true });
@@ -624,9 +653,12 @@ export class WorktreeController {
                     throw new WorktreeError('PATH_CHANGED', 'The destination ancestry changed during preparation.');
                 this.guard(request, invocation);
                 const progressOperation = Object.freeze({ id: operationId, worktreeId: id });
-                const checkout = await git.create({ id, repository, destination, remote, remoteIdentity: identity, remoteBranch, baseRef: record.baseRef, signal: invocation.signal,
+                const sourceInput = {
+                    id, repository: branchSource === 'local' ? selectedRepository : repository, destination, baseRef: record.baseRef, signal: invocation.signal,
                     onProgress: stage => this.progress(invocation, progressOperation, stage),
-                });
+                    ...(branchSource === 'local' ? { branchSource: 'local', localBranch: remoteBranch, ...(request.localOid === undefined ? {} : { localOid: request.localOid }) } : { branchSource: 'remote', remote, remoteIdentity: identity, remoteBranch }),
+                };
+                const checkout = await git.create(sourceInput);
                 let created = { ...record, ...checkout };
                 await this.store.worktrees.put(created.id, clone(created));
                 operation = await this.receipt(operation, 'checkout-created');

package/dist/store.d.ts

@@ -26,6 +26,8 @@ export declare const worktreeDomain: {
             archived: boolean;
             state: "creating" | "ready" | "recovery-required" | "missing";
             error: string | null;
+            branchSource?: "local" | "remote" | undefined;
+            localBranch?: string | undefined;
             displayName?: string | undefined;
             naming?: {
                 title: string;

package/dist/store.js

@@ -11,6 +11,7 @@ const namingSchema = z.object({
 const worktreeSchema = z.object({
     id: z.string().uuid(), operationId: z.string().uuid(), repoRoot: str, commonDir: str, projectSubdir: str,
     checkoutRoot: str, effectiveCwd: str, remote: str, remoteIdentity: str, remoteBranch: str,
+    branchSource: z.enum(['local', 'remote']).optional(), localBranch: str.optional(),
     baseOid: str, baseRef: str, fetchedAt: z.number().int().nonnegative(), createdAt: z.number().int().nonnegative(),
     sessionIds: z.array(str), workspaceId: str.nullable(), branch: str.nullable(), protected: z.boolean(), archived: z.boolean(),
     state: z.enum(['creating', 'ready', 'recovery-required', 'missing']), error: str.nullable(),

package/dist/types.d.ts

@@ -50,6 +50,7 @@ export interface RepositoryInfo {
     head: string;
     branch: string | null;
 }
+export type BranchSource = 'local' | 'remote';
 export interface RemoteInfo {
     name: string;
     identity: string;
@@ -58,6 +59,13 @@ export interface RemoteBranch {
     name: string;
     oid: string;
 }
+export interface LocalBranches {
+    branchSource: 'local';
+    currentBranch: string | null;
+    defaultBranch: string | null;
+    branches: RemoteBranch[];
+    observedAt: number;
+}
 export interface RemoteBranches {
     remote: string;
     remoteIdentity: string;
@@ -79,18 +87,30 @@ export interface WorktreeSetupProgress {
     readonly operationId: string;
     readonly worktreeId?: string;
 }
-export interface CreateCheckoutInput {
+export type CreateCheckoutInput = {
     id: string;
     repository: RepositoryInfo;
     destination: string;
-    remote: string;
-    remoteIdentity: string;
-    remoteBranch: string;
     baseRef: string;
     signal?: AbortSignal;
     /** Observer failures are ignored; never used to authorize or change Git effects. */
     onProgress?: (stage: 'fetching' | 'creating') => void;
-}
+} & ({
+    branchSource: 'local';
+    localBranch: string;
+    localOid?: string;
+    remote?: never;
+    remoteIdentity?: never;
+    remoteBranch?: never;
+} | {
+    /** Omission preserves freshly fetched remote behavior. */
+    branchSource?: 'remote';
+    remote: string;
+    remoteIdentity: string;
+    remoteBranch: string;
+    localBranch?: never;
+    localOid?: never;
+});
 export interface CreatedCheckout {
     checkoutRoot: string;
     effectiveCwd: string;
@@ -155,6 +175,9 @@ export interface WorktreeRecord {
     remote: string;
     remoteIdentity: string;
     remoteBranch: string;
+    /** Absent on legacy records means remote, never inferred from remote's value. */
+    branchSource?: BranchSource;
+    localBranch?: string;
     baseOid: string;
     baseRef: string;
     fetchedAt: number;
@@ -219,6 +242,9 @@ export interface WorktreeRequest {
     repoPath?: string;
     id?: string;
     operationId?: string;
+    branchSource?: BranchSource;
+    localBranch?: string;
+    localOid?: string;
     remote?: string;
     remoteIdentity?: string;
     remoteBranch?: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@1yefuwang1/dsh-worktrees",
-  "version": "0.2.13",
-  "description": "Multi-folder projects with Local and isolated Git worktree threads, freshly fetched remote branches and guarded local handoff.",
+  "version": "0.2.18",
+  "description": "Multi-folder projects with Local and isolated Git worktree threads, local or freshly fetched remote starting branches and guarded local handoff.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -42,6 +42,11 @@
   ],
   "icon": "./icon.svg",
   "license": "MIT",
+  "devDependencies": {
+    "jsdom": "^30.1.2",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"