diff --git a/docs/subsystems/worktrees.md b/docs/subsystems/worktrees.md index 27b8aa3d72..30456e8e03 100644 --- a/docs/subsystems/worktrees.md +++ b/docs/subsystems/worktrees.md @@ -58,6 +58,7 @@ Creates retained Git worktrees under the mounted filesystem and sandbox provider /** * Create a fresh branch and checkout at a pinned local revision, then enter it. * Existing branches or checkout paths fail. Uncommitted files stay in the source checkout. + * Checkout disables configured clean, smudge, and process filters without changing Git config. * The new checkout becomes current only after Git setup succeeds. Failures may retain newly * allocated Git/filesystem artifacts; no branch or checkout is removed automatically. * @param agent - caller whose current directory selects the source repository and file policy. diff --git a/docs/subsystems/worktrees.zh.md b/docs/subsystems/worktrees.zh.md index 2522544c48..4575778cfb 100644 --- a/docs/subsystems/worktrees.zh.md +++ b/docs/subsystems/worktrees.zh.md @@ -58,6 +58,7 @@ Creates retained Git worktrees under the mounted filesystem and sandbox provider /** * Create a fresh branch and checkout at a pinned local revision, then enter it. * Existing branches or checkout paths fail. Uncommitted files stay in the source checkout. + * Checkout disables configured clean, smudge, and process filters without changing Git config. * The new checkout becomes current only after Git setup succeeds. Failures may retain newly * allocated Git/filesystem artifacts; no branch or checkout is removed automatically. * @param agent - caller whose current directory selects the source repository and file policy. diff --git a/packages/experimental/worktree/README.i18n.yaml b/packages/experimental/worktree/README.i18n.yaml index 43142b8d46..152ac639fc 100644 --- a/packages/experimental/worktree/README.i18n.yaml +++ b/packages/experimental/worktree/README.i18n.yaml @@ -15,8 +15,8 @@ en: d152484eb41ac6b4 zh: 2f8a621b991260a1 /deepseek-ai-dsh-experimental-worktree/use-this-package: - en: bde2d1a47e2cbb21 - zh: 858d1809d670e6af + en: 70ca6f3e9b8dba85 + zh: 19e758cc90bc4047 /deepseek-ai-dsh-experimental-worktree/understand-the-implementation: en: 6971a7ca9073bef1 zh: b977c28a75c7f963 diff --git a/packages/experimental/worktree/README.md b/packages/experimental/worktree/README.md index 750ebbf62b..96d725ceb5 100644 --- a/packages/experimental/worktree/README.md +++ b/packages/experimental/worktree/README.md @@ -32,7 +32,7 @@ Mount the service alongside `workingDirectory`, `fs`, `subprocess`, `sandbox`, a - name: '@deepseek-ai/dsh-experimental-tool-worktree' ``` -`ctx.worktrees.create(agent, { name?, from? }, signal?)` creates a new branch and checkout, then enters the canonical checkout directory through `ctx.workingDirectory.set`. `from` resolves to a local commit before creation and defaults to `HEAD`; staged, unstaged, untracked, and ignored source files are not copied. An existing branch or checkout path is an error. The returned record contains `path`, `branch`, `baseCommit`, and `repositoryRoot`. +`ctx.worktrees.create(agent, { name?, from? }, signal?)` creates a new branch and checkout, then enters the canonical checkout directory through `ctx.workingDirectory.set`. `from` resolves to a local commit before creation and defaults to `HEAD`; staged, unstaged, untracked, and ignored source files are not copied. Checkout disables configured Git clean, smudge, and process filters without changing repository configuration; Git LFS files remain committed pointer files. An existing branch or checkout path is an error. The returned record contains `path`, `branch`, `baseCommit`, and `repositoryRoot`. The default checkout directory is `/.agents/worktrees/`. The returned `repositoryRoot` is the top-level directory of the caller’s current checkout; when it is a linked checkout, the pool is nested inside it. Omitted names use `worktree-` plus a UUID. The service writes a `.gitignore` containing `*` and a trailing newline only when its allocation creates the pool; existing files and ignore rules are preserved. Relative `directory`, generated `namePrefix`, executable choices, and process limits are configurable in the [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-experimental-worktree). diff --git a/packages/experimental/worktree/README.zh.md b/packages/experimental/worktree/README.zh.md index ade39d1240..9e40ce6a09 100644 --- a/packages/experimental/worktree/README.zh.md +++ b/packages/experimental/worktree/README.zh.md @@ -32,7 +32,7 @@ kind: "package-reference" - name: '@deepseek-ai/dsh-experimental-tool-worktree' ``` -`ctx.worktrees.create(agent, { name?, from? }, signal?)` 创建新分支与检出目录,再通过 `ctx.workingDirectory.set` 进入规范化的检出目录。`from` 在创建前解析为本地提交,默认是 `HEAD`;暂存、未暂存、未跟踪以及被忽略的源文件均不复制。分支或检出路径已存在时会报错。返回记录包含 `path`、`branch`、`baseCommit` 和 `repositoryRoot`。 +`ctx.worktrees.create(agent, { name?, from? }, signal?)` 创建新分支与检出目录,再通过 `ctx.workingDirectory.set` 进入规范化的检出目录。`from` 在创建前解析为本地提交,默认是 `HEAD`;暂存、未暂存、未跟踪以及被忽略的源文件均不复制。检出操作禁用已配置的 Git clean、smudge 和 process 过滤器,不修改仓库配置;Git LFS 文件保留已提交的指针文件形式。分支或检出路径已存在时会报错。返回记录包含 `path`、`branch`、`baseCommit` 和 `repositoryRoot`。 默认检出目录是 `/.agents/worktrees/`。返回的 `repositoryRoot` 是调用方当前检出目录的顶层目录;如果它是链接检出目录,工作树父目录就嵌套在其中。省略名称时,使用 `worktree-` 加 UUID。仅当服务的分配操作创建了父目录时,服务才会写入内容为 `*` 加换行符的 `.gitignore`;已有文件与忽略规则保持不变。相对路径 `directory`、生成名称使用的 `namePrefix`、可执行程序与进程限制可在[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-experimental-worktree)中查阅。 diff --git a/packages/experimental/worktree/src/index.ts b/packages/experimental/worktree/src/index.ts index 02202c57d2..bb18702644 100644 --- a/packages/experimental/worktree/src/index.ts +++ b/packages/experimental/worktree/src/index.ts @@ -95,6 +95,7 @@ export class WorktreeService extends Service { /** * Create a fresh branch and checkout at a pinned local revision, then enter it. * Existing branches or checkout paths fail. Uncommitted files stay in the source checkout. + * Checkout disables configured clean, smudge, and process filters without changing Git config. * The new checkout becomes current only after Git setup succeeds. Failures may retain newly * allocated Git/filesystem artifacts; no branch or checkout is removed automatically. * @param agent - caller whose current directory selects the source repository and file policy. @@ -125,10 +126,10 @@ export class WorktreeService extends Service { private async createCheckout(agent: Agent, { branch, revision }: WorktreeSpec, signal: AbortSignal): Promise { const cwd = await this.ctx.workingDirectory.ensure(agent, signal) const policy = this.ctx.sandboxPolicy.resolve({ session: agent.session }) - const run = (directory: string, args: string[], allowedExitCodes?: number[]) => runCommand( + const run = (directory: string, args: string[], allowedExitCodes?: number[], env?: NodeJS.ProcessEnv) => runCommand( this.ctx, this.config, policy, directory, [this.config.gitCommand, '--no-lazy-fetch', '-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false', ...args], - signal, allowedExitCodes, + signal, allowedExitCodes, env, ) await run(cwd, ['check-ref-format', `refs/heads/${branch}`]) const rootOutput = await run(cwd, ['rev-parse', '--show-toplevel']) @@ -147,7 +148,24 @@ export class WorktreeService extends Service { await runCommand(this.ctx, this.config, policy, repositoryRoot, [this.config.nodeCommand, '--input-type=module', '-e', PREPARE_DIRECTORY, poolPath, path], signal) await run(repositoryRoot, ['--work-tree', repositoryRoot, 'worktree', 'add', '--no-checkout', '-b', branch, '--', path, baseCommit]) - await run(path, ['--work-tree', path, 'reset', '--hard', '--no-recurse-submodules', baseCommit]) + const configured = await run(path, ['config', '--null', '--name-only', '--get-regexp', '^filter\\.'], [0, 1]) + const drivers = new Set() + for (const key of configured.stdout.split('\0')) { + const separator = key.lastIndexOf('.') + if (separator > 'filter.'.length && ['clean', 'smudge', 'process', 'required'].includes(key.slice(separator + 1))) { + drivers.add(key.slice('filter.'.length, separator)) + } + } + const overrides: NodeJS.ProcessEnv = { GIT_CONFIG_COUNT: String(drivers.size * 4) } + let index = 0 + for (const driver of drivers) { + for (const attribute of ['clean', 'smudge', 'process', 'required']) { + overrides[`GIT_CONFIG_KEY_${index}`] = `filter.${driver}.${attribute}` + overrides[`GIT_CONFIG_VALUE_${index}`] = attribute === 'required' ? 'false' : '' + index++ + } + } + await run(path, ['--work-tree', path, 'reset', '--hard', '--no-recurse-submodules', baseCommit], undefined, overrides) const canonicalPath = await this.ctx.workingDirectory.set(agent, path, signal) return { path: canonicalPath, branch, baseCommit, repositoryRoot } } catch (error) { diff --git a/packages/experimental/worktree/src/process.ts b/packages/experimental/worktree/src/process.ts index 47fba17956..5064988b1d 100644 --- a/packages/experimental/worktree/src/process.ts +++ b/packages/experimental/worktree/src/process.ts @@ -20,6 +20,7 @@ const GIT_ENV: NodeJS.ProcessEnv = Object.fromEntries([ 'GIT_DIR', 'GIT_WORK_TREE', 'GIT_COMMON_DIR', 'GIT_INDEX_FILE', 'GIT_OBJECT_DIRECTORY', 'GIT_ALTERNATE_OBJECT_DIRECTORIES', 'GIT_CONFIG', 'GIT_CONFIG_PARAMETERS', 'GIT_CONFIG_COUNT', 'GIT_CEILING_DIRECTORIES', 'GIT_PREFIX', 'GIT_SHALLOW_FILE', 'GIT_GRAFT_FILE', + 'GIT_REPLACE_REF_BASE', ].map(key => [key, undefined])) /** @@ -31,6 +32,7 @@ const GIT_ENV: NodeJS.ProcessEnv = Object.fromEntries([ * @param argv - executable followed by literal arguments. * @param signal - operation cancellation. * @param allowedExitCodes - command-specific successful statuses. + * @param env - command-local environment overrides, applied after Git selector removal. * @returns complete bounded stdout and the exit code. */ export async function runCommand( @@ -41,6 +43,7 @@ export async function runCommand( argv: readonly [string, ...string[]], signal: AbortSignal, allowedExitCodes: readonly number[] = [0], + env: NodeJS.ProcessEnv = {}, ): Promise<{ stdout: string; exitCode: number }> { using timeout = deadline(signal, config.timeoutMs, 'WORKTREE_TIMEOUT') timeout.signal.throwIfAborted() @@ -53,7 +56,7 @@ export async function runCommand( const child = ctx.subprocess.spawn({ argv: wrapped, cwd, - env: { ...GIT_ENV, GIT_TERMINAL_PROMPT: '0', GIT_LFS_SKIP_SMUDGE: '1' }, + env: { ...GIT_ENV, GIT_TERMINAL_PROMPT: '0', GIT_LFS_SKIP_SMUDGE: '1', ...env }, signal: timeout.signal, graceMs: config.graceMs, stdio: { diff --git a/packages/experimental/worktree/tests/checkout-safety.spec.ts b/packages/experimental/worktree/tests/checkout-safety.spec.ts new file mode 100644 index 0000000000..97fc876d9f --- /dev/null +++ b/packages/experimental/worktree/tests/checkout-safety.spec.ts @@ -0,0 +1,166 @@ +import { access, readFile, rm, writeFile } from 'node:fs/promises' +import { join } from 'node:path' +import { afterEach, describe, expect, it, vi } from 'vitest' +import type { Context } from '@deepseek-ai/cordis' +import { SubprocessExecutableNotFoundError } from '@deepseek-ai/dsh-subprocess' +import { contents, filterCommand, git, harness, repository, testAgent } from './harness.ts' + +let ctx: Context | undefined +const roots: string[] = [] + +afterEach(async () => { + vi.unstubAllEnvs() + await ctx?.fiber.dispose() + ctx = undefined + for (const root of roots.splice(0)) await rm(root, { recursive: true, force: true }) +}) + +async function repo(): Promise { + const root = await repository() + roots.push(root) + return root +} + +describe('worktree checkout Git configuration', () => { + it.each(['some.nested.driver', 'x=y', 'lfs'])('disables required clean and smudge filters named %s without changing repository configuration', async (driver) => { + const root = await repo() + const committed = driver === 'lfs' + ? `version https://git-lfs.github.com/spec/v1\noid sha256:${'0'.repeat(64)}\nsize 8\n` + : 'initial\n' + await writeFile(join(root, 'tracked.txt'), committed) + await writeFile(join(root, '.gitattributes'), `*.txt filter=${driver} -text\n`) + await git(root, 'add', '.gitattributes', 'tracked.txt') + await git(root, 'commit', '-m', 'attributes') + const { command, marker } = await filterCommand(root) + await git(root, 'config', `filter.${driver}.clean`, command) + await git(root, 'config', `filter.${driver}.smudge`, command) + await git(root, 'config', `filter.${driver}.required`, 'true') + await git(root, 'config', `filter.${driver}.unused`, 'preserved') + const configuration = await readFile(join(root, '.git/config')) + + const control = join(root, 'ordinary-checkout') + await git(root, 'worktree', 'add', '-b', 'ordinary', control) + expect(await contents(marker)).toContain('executed') + expect(await contents(join(control, 'tracked.txt'))).toBe(`filtered\n${committed}`) + await rm(marker) + + ctx = await harness(root) + const created = await ctx.worktrees.create(testAgent(ctx, root), { name: 'unfiltered' }) + + await expect(access(marker)).rejects.toMatchObject({ code: 'ENOENT' }) + expect(await contents(join(created.path, 'tracked.txt'))).toBe(committed) + expect(await readFile(join(root, '.git/config'))).toEqual(configuration) + }) + + it('disables a required process filter that makes ordinary checkout fail', async () => { + const root = await repo() + await writeFile(join(root, '.gitattributes'), '*.txt filter=process-driver -text\n') + await git(root, 'add', '.gitattributes') + await git(root, 'commit', '-m', 'attributes') + const { command, marker } = await filterCommand(root, true) + await git(root, 'config', 'filter.process-driver.process', command) + await git(root, 'config', 'filter.process-driver.required', 'true') + const control = join(root, 'ordinary-checkout') + await expect(git(root, 'worktree', 'add', '-b', 'ordinary', control)).rejects.toThrow() + expect(await contents(marker)).toBe('executed\n') + await rm(marker) + + ctx = await harness(root) + const created = await ctx.worktrees.create(testAgent(ctx, root), { name: 'unfiltered' }) + + await expect(access(marker)).rejects.toMatchObject({ code: 'ENOENT' }) + expect(await contents(join(created.path, 'tracked.txt'))).toBe('initial\n') + }) + + it('reports invalid destination-only configuration and retains the unpopulated checkout', async () => { + const root = await repo() + const included = join(root, 'invalid-config') + await writeFile(included, '[invalid configuration\n') + await git(root, 'config', 'includeIf.onbranch:invalid.path', included) + ctx = await harness(root) + const agent = testAgent(ctx, root) + + await expect(ctx.worktrees.create(agent, { name: 'invalid' })).rejects.toThrow(/Any created checkout and branch are retained.*bad config line/s) + + expect(ctx.workingDirectory.get(agent.session)).toBe(root) + await access(join(root, '.agents/worktrees/invalid/.git')) + await expect(access(join(root, '.agents/worktrees/invalid/tracked.txt'))).rejects.toMatchObject({ code: 'ENOENT' }) + expect(await git(root, 'branch', '--list', 'invalid')).toContain('invalid') + }) + + it('refuses truncated destination filter configuration before materializing files', async () => { + const root = await repo() + await git(root, 'config', `filter.${'long-driver-'.repeat(100)}.smudge`, 'unavailable-filter') + ctx = await harness(root, { maxOutputBytes: 256 }) + const agent = testAgent(ctx, root) + + await expect(ctx.worktrees.create(agent, { name: 'bounded' })).rejects.toThrow('output exceeds maxOutputBytes') + + expect(ctx.workingDirectory.get(agent.session)).toBe(root) + await access(join(root, '.agents/worktrees/bounded/.git')) + await expect(access(join(root, '.agents/worktrees/bounded/tracked.txt'))).rejects.toMatchObject({ code: 'ENOENT' }) + }) + + it('discovers filters selected only by the newly created branch', async () => { + const root = await repo() + await writeFile(join(root, '.gitattributes'), '*.txt filter=destination-only -text\n') + await git(root, 'add', '.gitattributes') + await git(root, 'commit', '-m', 'attributes') + const { command, marker } = await filterCommand(root) + const included = join(root, 'destination-config') + await git(root, 'config', '--file', included, 'filter.destination-only.smudge', command) + await git(root, 'config', '--file', included, 'filter.destination-only.required', 'true') + await git(root, 'config', 'includeIf.onbranch:destination.path', included) + await expect(git(root, 'config', '--get-regexp', '^filter\\.')).rejects.toMatchObject({ code: 1 }) + + ctx = await harness(root) + const created = await ctx.worktrees.create(testAgent(ctx, root), { name: 'destination' }) + + expect(await git(created.path, 'config', 'filter.destination-only.smudge')).toBe(command) + await expect(access(marker)).rejects.toMatchObject({ code: 'ENOENT' }) + expect(await contents(join(created.path, 'tracked.txt'))).toBe('initial\n') + }) + + it('ignores inherited repository, replacement-ref and command-config selectors', async () => { + const root = await repo() + const other = await repo() + const baseCommit = await git(root, 'rev-parse', 'HEAD') + await git(root, 'checkout', '-b', 'replacement') + await writeFile(join(root, 'tracked.txt'), 'redirected\n') + await git(root, 'commit', '-am', 'replacement') + const replacement = await git(root, 'rev-parse', 'HEAD') + await git(root, 'checkout', 'main') + await git(root, 'update-ref', `refs/alternate-replacements/${baseCommit}`, replacement) + ctx = await harness(root) + const agent = testAgent(ctx, root) + vi.stubEnv('GIT_DIR', join(other, '.git')) + vi.stubEnv('GIT_WORK_TREE', other) + vi.stubEnv('GIT_COMMON_DIR', join(other, '.git')) + vi.stubEnv('GIT_INDEX_FILE', join(other, '.git/index')) + vi.stubEnv('GIT_OBJECT_DIRECTORY', join(other, '.git/objects')) + vi.stubEnv('GIT_IMPLICIT_WORK_TREE', '0') + vi.stubEnv('GIT_REPLACE_REF_BASE', 'refs/alternate-replacements/') + vi.stubEnv('GIT_CONFIG_COUNT', '1') + vi.stubEnv('GIT_CONFIG_KEY_0', 'core.bare') + vi.stubEnv('GIT_CONFIG_VALUE_0', 'true') + + const created = await ctx.worktrees.create(agent, { name: 'selected' }) + + expect(created.repositoryRoot).toBe(root) + expect(created.baseCommit).toBe(baseCommit) + expect(await contents(join(created.path, 'tracked.txt'))).toBe('initial\n') + expect(await git(other, 'branch', '--list', 'selected')).toBe('') + }) + + it('reports a missing Git executable before allocating a checkout', async () => { + const root = await repo() + ctx = await harness(root, { gitCommand: join(root, 'unavailable-git') }) + const agent = testAgent(ctx, root) + + await expect(ctx.worktrees.create(agent, { name: 'unavailable' })).rejects.toBeInstanceOf(SubprocessExecutableNotFoundError) + + expect(ctx.workingDirectory.get(agent.session)).toBe(root) + await expect(access(join(root, '.agents/worktrees'))).rejects.toMatchObject({ code: 'ENOENT' }) + expect(await git(root, 'branch', '--list', 'unavailable')).toBe('') + }) +}) diff --git a/packages/experimental/worktree/tests/harness.ts b/packages/experimental/worktree/tests/harness.ts index dde45868c6..c38be4d57c 100644 --- a/packages/experimental/worktree/tests/harness.ts +++ b/packages/experimental/worktree/tests/harness.ts @@ -91,3 +91,21 @@ export async function harness(root: string, config: Config = {}, mode: SandboxMo export async function contents(path: string): Promise { return readFile(path, 'utf8') } + +/** + * Create a filter whose file marker and transformed output reveal its execution. + * @param root - the owning test's private repository directory. + * @param processFilter - fail the process-filter handshake instead of transforming stdin. + * @returns a Git shell command and the marker it writes. + */ +export async function filterCommand(root: string, processFilter = false): Promise<{ command: string; marker: string }> { + const script = join(root, 'filter.cjs') + const marker = join(root, 'filter-executed') + await writeFile(script, ` +const fs = require('node:fs'); +fs.appendFileSync(${JSON.stringify(marker)}, 'executed\\n'); +${processFilter ? 'process.exit(1);' : "process.stdout.write('filtered\\n' + fs.readFileSync(0, 'utf8'));"} +`) + const quoted = (value: string) => `'${value.replaceAll('\\', '/').replaceAll("'", "'\\''")}'` + return { command: `${quoted(process.execPath)} ${quoted(script)}`, marker } +} diff --git a/packages/experimental/worktree/tests/sandbox.spec.ts b/packages/experimental/worktree/tests/sandbox.spec.ts index f5ba693416..90bdd7594b 100644 --- a/packages/experimental/worktree/tests/sandbox.spec.ts +++ b/packages/experimental/worktree/tests/sandbox.spec.ts @@ -1,10 +1,10 @@ -import { mkdir, readFile, readdir, rm } from 'node:fs/promises' +import { access, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises' import { join } from 'node:path' import { afterEach, describe, expect, it, vi } from 'vitest' import { Context } from '@deepseek-ai/cordis' import { SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox' import LocalSandbox from '@deepseek-ai/dsh-sandbox-local' -import { git, harness, repository, testAgent } from './harness.ts' +import { filterCommand, git, harness, repository, testAgent } from './harness.ts' let ctx: Context | undefined let root: string | undefined @@ -49,8 +49,14 @@ describe.skipIf(!sandboxUsable)('worktree standing sandbox policy', () => { expect(confine.mock.calls.every(call => call[1].mode === 'read-only' && call[1].workspaceRoot === root)).toBe(true) }) - it('creates a checkout in the default pool under the source workspace-write grant', async () => { + it('creates an unfiltered checkout in the default pool under the source workspace-write grant', async () => { root = await repository(process.cwd()) + await writeFile(join(root, '.gitattributes'), '*.txt filter=configured -text\n') + await git(root, 'add', '.gitattributes') + await git(root, 'commit', '-m', 'attributes') + const { command, marker } = await filterCommand(root) + await git(root, 'config', 'filter.configured.smudge', command) + await git(root, 'config', 'filter.configured.required', 'true') ctx = await harness(root, {}, 'workspace-write') const agent = testAgent(ctx, root) const confine = vi.spyOn(ctx.sandbox, 'confine') @@ -58,6 +64,7 @@ describe.skipIf(!sandboxUsable)('worktree standing sandbox policy', () => { const checkout = join(root, '.agents', 'worktrees', 'allowed') expect(created.path).toBe(checkout) + await expect(access(marker)).rejects.toMatchObject({ code: 'ENOENT' }) expect(await readFile(join(checkout, 'tracked.txt'), 'utf8')).toBe('initial\n') expect(await git(checkout, 'branch', '--show-current')).toBe('allowed') expect(await git(root, 'branch', '--show-current')).toBe('main') diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts index f48397ffb7..8250d4a65a 100644 --- a/packages/extensions/tool-cordis/src/api-catalog.ts +++ b/packages/extensions/tool-cordis/src/api-catalog.ts @@ -3836,7 +3836,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ methods: [ { signature: 'async create(agent: Agent, request: CreateWorktreeRequest = {}, signal?: AbortSignal): Promise', - description: 'Create a fresh branch and checkout at a pinned local revision, then enter it. Existing branches or checkout paths fail. Uncommitted files stay in the source checkout. The new checkout becomes current only after Git setup succeeds. Failures may retain newly allocated Git/filesystem artifacts; no branch or checkout is removed automatically.', + description: 'Create a fresh branch and checkout at a pinned local revision, then enter it. Existing branches or checkout paths fail. Uncommitted files stay in the source checkout. Checkout disables configured clean, smudge, and process filters without changing Git config. The new checkout becomes current only after Git setup succeeds. Failures may retain newly allocated Git/filesystem artifacts; no branch or checkout is removed automatically.', parameters: [{ name: 'agent', description: 'caller whose current directory selects the source repository and file policy.' }, { name: 'request', description: 'optional new name and local revision; defaults are generated name and HEAD.' }, { name: 'signal', description: 'cancellation of lookup, creation, and working-directory publication.' }], returns: 'canonical checkout path, branch name, pinned commit, and source repository root.', },