@developerz.ai/aitm 0.0.0

package/dist/tools/fetch-html.js

@@ -0,0 +1,139 @@
+// fetch_html — a heavier-stealth sibling of web-fetch for sites that fingerprint TLS (JA3/JA4)
+// or HTTP/2 frame ordering (Cloudflare JS challenge, Akamai Bot Manager). Node's stock `fetch`
+// can't fake a browser's TLS handshake, so this shells out to a `curl-impersonate` binary
+// (https://github.com/lwthiker/curl-impersonate), which speaks a real Chrome/Firefox/Safari
+// handshake. Same WebFetchOutput shape as web-fetch so a subagent can swap tools without prompt
+// changes — the model should reach for this only when web-fetch returns a 403/challenge.
+//
+// curl-impersonate is an OPTIONAL system binary. The tool never hard-fails at startup: when the
+// binary is absent the call returns a status-0 result whose body explains how to install it
+// (use isFetchHtmlAvailable() at the wiring site to skip registration entirely). No npm dep.
+import { tool } from 'ai';
+import { ExecaError, execa } from 'execa';
+import { z } from 'zod';
+import { assertSafeUrl, defaultLookup } from "./web-fetch.js";
+const fetchHtmlInputSchema = z.object({
+    url: z.string().url(),
+    timeoutMs: z.number().int().positive().optional(),
+    maxChars: z.number().int().positive().optional(),
+    impersonate: z.enum(['chrome', 'firefox', 'safari']).optional(),
+});
+// Default curl-impersonate target per browser hint. These version strings depend on the
+// installed curl-impersonate build — override via FetchHtmlInit.targets to match your version.
+export const DEFAULT_IMPERSONATE_TARGETS = Object.freeze({ chrome: 'chrome116', firefox: 'firefox117', safari: 'safari15_5' });
+// Default binary — the chrome build ships in most curl-impersonate installs. Point at a
+// different binary (e.g. `curl-impersonate-ff`, an absolute path) via FetchHtmlInit.binary.
+const DEFAULT_BINARY = 'curl-impersonate-chrome';
+const DEFAULT_MAX_CHARS = 200_000;
+const DEFAULT_TIMEOUT_MS = 15_000;
+// Hard ceilings on model-provided inputs so one tool call can't exhaust resources: cap the
+// request runtime, and cap maxChars (which also bounds the subprocess maxBuffer below).
+const MAX_TIMEOUT_MS = 120_000;
+const MAX_OUTPUT_CHARS = 5_000_000;
+// Marker separating curl's `--write-out` metadata (redirected to stderr via %{stderr}) from any
+// real stderr noise. Chosen to be vanishingly unlikely to occur in normal output.
+const META = '__AITM_FETCH_HTML_META__';
+function resolveExec(init) {
+    return init.exec ?? ((file, args, options) => execa(file, args, options));
+}
+// True when the curl-impersonate binary is callable. Use at the wiring site to decide whether to
+// register fetch_html at all (per CLAUDE.md: gate on "binary present", don't hard-fail).
+export async function isFetchHtmlAvailable(init = {}) {
+    const exec = resolveExec(init);
+    const binary = init.binary ?? DEFAULT_BINARY;
+    try {
+        await exec(binary, ['--version']);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function fetchHtmlTool(init = {}) {
+    const exec = resolveExec(init);
+    const binary = init.binary ?? DEFAULT_BINARY;
+    const targets = init.targets ?? DEFAULT_IMPERSONATE_TARGETS;
+    const lookup = init.lookup ?? defaultLookup;
+    return tool({
+        description: 'Fetch a URL using a real browser TLS fingerprint (via curl-impersonate), for sites that block stock fetch with a JS challenge / 403 (Cloudflare, Akamai). Same output shape as web-fetch. Use this only when web-fetch returns a challenge or 403.',
+        inputSchema: fetchHtmlInputSchema,
+        execute: async (input) => {
+            const maxChars = Math.min(input.maxChars ?? DEFAULT_MAX_CHARS, MAX_OUTPUT_CHARS);
+            const timeoutMs = Math.min(input.timeoutMs ?? DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS);
+            const safeUrl = await assertSafeUrl(input.url, lookup);
+            const target = targets[input.impersonate ?? 'chrome'];
+            // -sS: quiet but show errors; -L: follow redirects; --max-time bounds the request.
+            // -w '%{stderr}…': write the metadata line to STDERR (so STDOUT is purely the body).
+            const args = [
+                '--impersonate',
+                target,
+                '-sSL',
+                '--max-time',
+                String(Math.max(1, Math.ceil(timeoutMs / 1000))),
+                '-w',
+                `%{stderr}\n${META}\t%{http_code}\t%{url_effective}\t%{content_type}`,
+                safeUrl.toString(),
+            ];
+            try {
+                const r = await exec(binary, args, {
+                    timeout: timeoutMs + 5_000,
+                    maxBuffer: maxChars * 4 + 2_000_000,
+                });
+                return buildOutput(input.url, asString(r.stdout), asString(r.stderr), maxChars);
+            }
+            catch (err) {
+                // curl ran but returned non-zero (e.g. still blocked, timeout): salvage metadata if present.
+                if (err instanceof ExecaError) {
+                    const parsed = parseMeta(asString(err.stderr));
+                    if (parsed)
+                        return buildOutput(input.url, asString(err.stdout), asString(err.stderr), maxChars);
+                    return errorOutput(input.url, err.shortMessage || err.message);
+                }
+                return errorOutput(input.url, err instanceof Error ? err.message : String(err));
+            }
+        },
+    });
+}
+function buildOutput(requestedUrl, stdout, stderr, maxChars) {
+    const meta = parseMeta(stderr);
+    const truncated = stdout.length > maxChars;
+    return {
+        url: requestedUrl,
+        finalUrl: meta?.finalUrl || requestedUrl,
+        status: meta?.status ?? 0,
+        contentType: meta?.contentType ?? null,
+        body: truncated ? stdout.slice(0, maxChars) : stdout,
+        truncated,
+        retrievedAt: new Date().toISOString(),
+    };
+}
+function parseMeta(stderr) {
+    const line = stderr
+        .split('\n')
+        .reverse()
+        .find((l) => l.startsWith(META));
+    if (!line)
+        return null;
+    const [, statusRaw, finalUrl, contentType] = line.split('\t');
+    const status = Number.parseInt(statusRaw ?? '', 10);
+    return {
+        status: Number.isFinite(status) ? status : 0,
+        finalUrl: finalUrl ?? '',
+        contentType: contentType && contentType.length > 0 ? contentType : null,
+    };
+}
+function errorOutput(requestedUrl, message) {
+    return {
+        url: requestedUrl,
+        finalUrl: requestedUrl,
+        status: 0,
+        contentType: null,
+        body: `fetch_html failed: ${message}. Is curl-impersonate installed and on PATH? See https://github.com/lwthiker/curl-impersonate`,
+        truncated: false,
+        retrievedAt: new Date().toISOString(),
+    };
+}
+function asString(v) {
+    return typeof v === 'string' ? v : '';
+}
+//# sourceMappingURL=fetch-html.js.map

package/dist/tools/fetch-html.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-html.js","sourceRoot":"","sources":["../../src/tools/fetch-html.ts"],"names":[],"mappings":"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"}

package/dist/tools/github-thread-tool.d.ts

@@ -0,0 +1,10 @@
+import { type Tool } from 'ai';
+import type { GithubToolInput, GithubToolOutput } from '../subagents/reviewer.ts';
+export type GithubThreadClient = {
+    replyToThread(threadId: string, body: string): Promise<void>;
+    resolveThread(threadId: string): Promise<void>;
+};
+export type GithubThreadToolInit = {
+    github: GithubThreadClient;
+};
+export declare function githubThreadTool(init: GithubThreadToolInit): Tool<GithubToolInput, GithubToolOutput>;

package/dist/tools/github-thread-tool.js

@@ -0,0 +1,36 @@
+// Reviewer subagent's github tool — a thin LLM-facing wrapper around the two GitHubClient
+// methods Reviewer needs: replyToThread + resolveThread. Kept as one discriminated-union
+// tool so the SDK only registers a single `github` slot (matches the contract in
+// src/subagents/reviewer.ts §ReviewerTools.github).
+//
+// Lifecycle parallels the claude-task-master `post_comment_replies()` flow (fix_pr.py):
+//   1. agent decides per thread: fixed | replied | wontfix
+//   2. agent calls github tool → replyToThread to post the reply
+//   3. agent calls github tool → resolveThread to mark it resolved (skipped for "replied")
+//
+// `resolveThread` follows the same pattern: optional, only fired when the thread is "done".
+import { tool } from 'ai';
+import { z } from 'zod';
+// Flat object, not a discriminatedUnion: a union compiles to JSON-Schema `oneOf` in the tool's
+// parameters, which some OpenRouter-routed providers reject ("Invalid arguments passed to the
+// model"). `body` is required only for replyToThread (enforced in execute).
+const githubInputSchema = z.object({
+    action: z.enum(['replyToThread', 'resolveThread']),
+    threadId: z.string().min(1),
+    body: z.string().optional(),
+});
+export function githubThreadTool(init) {
+    return tool({
+        description: 'Act on a single PR review thread. action="replyToThread" posts a reply; action="resolveThread" marks it resolved. Use replyToThread before resolveThread so the resolution carries an explanation.',
+        inputSchema: githubInputSchema,
+        execute: async (input) => {
+            if (input.action === 'replyToThread') {
+                await init.github.replyToThread(input.threadId, input.body ?? '');
+                return { ok: true };
+            }
+            await init.github.resolveThread(input.threadId);
+            return { ok: true };
+        },
+    });
+}
+//# sourceMappingURL=github-thread-tool.js.map

package/dist/tools/github-thread-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-thread-tool.js","sourceRoot":"","sources":["../../src/tools/github-thread-tool.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAC1F,yFAAyF;AACzF,iFAAiF;AACjF,oDAAoD;AACpD,EAAE;AACF,wFAAwF;AACxF,2DAA2D;AAC3D,iEAAiE;AACjE,2FAA2F;AAC3F,EAAE;AACF,4FAA4F;AAE5F,OAAO,EAAa,IAAI,EAAE,MAAM,IAAI,CAAC;AACrC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAUxB,+FAA+F;AAC/F,8FAA8F;AAC9F,4EAA4E;AAC5E,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC;IAClD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC5B,CAAC,CAAC;AAMH,MAAM,UAAU,gBAAgB,CAC9B,IAA0B;IAE1B,OAAO,IAAI,CAAC;QACV,WAAW,EACT,oMAAoM;QACtM,WAAW,EAAE,iBAAiB;QAC9B,OAAO,EAAE,KAAK,EAAE,KAAK,EAA6B,EAAE;YAClD,IAAI,KAAK,CAAC,MAAM,KAAK,eAAe,EAAE,CAAC;gBACrC,MAAM,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;gBAClE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;YACtB,CAAC;YACD,MAAM,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YAChD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;QACtB,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/tools/web-fetch.d.ts

@@ -0,0 +1,31 @@
+import type { Tool } from 'ai';
+import { z } from 'zod';
+declare const webFetchInputSchema: z.ZodObject<{
+    url: z.ZodString;
+    maxChars: z.ZodOptional<z.ZodNumber>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    referrer: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type WebFetchInput = z.infer<typeof webFetchInputSchema>;
+export type WebFetchOutput = {
+    url: string;
+    finalUrl: string;
+    status: number;
+    contentType: string | null;
+    body: string;
+    truncated: boolean;
+    retrievedAt: string;
+};
+export type LookupFn = (hostname: string) => Promise<Array<{
+    address: string;
+}>>;
+export type WebFetchInit = {
+    local?: boolean;
+    headers?: Record<string, string>;
+    lookup?: LookupFn;
+};
+export declare const defaultLookup: LookupFn;
+export declare function assertSafeUrl(rawUrl: string, lookup: LookupFn): Promise<URL>;
+export declare const DEFAULT_STEALTH_HEADERS: Readonly<Record<string, string>>;
+export declare function webFetchTool(init?: WebFetchInit): Tool;
+export {};

package/dist/tools/web-fetch.js

@@ -0,0 +1,223 @@
+// Local web-fetch tool — default. Runs a stealthed `fetch` from the agent host
+// (Chrome-like User-Agent + Sec-Ch-Ua + Accept-* headers), so the model can pull
+// public docs without paying for OpenRouter's server-tool round-trip.
+//
+// For the OpenRouter server-tool variant (model-decides, billable via Exa/Firecrawl/etc.),
+// see src/openrouter/server-tools.ts §webFetchServerTool. Pick local for cost / speed,
+// server for sites that block scrapers harder than headers fix.
+//
+// SDK ref: docs/vendor/ai-sdk/chunk-02.md §"Tool Calling" — tool({ description, inputSchema, execute }).
+import * as dns from 'node:dns/promises';
+import { tool } from 'ai';
+import { z } from 'zod';
+const webFetchInputSchema = z.object({
+    url: z.string().url(),
+    maxChars: z.number().int().positive().optional(),
+    timeoutMs: z.number().int().positive().optional(),
+    referrer: z.string().optional(),
+});
+export const defaultLookup = async (hostname) => {
+    return await dns.lookup(hostname, { all: true });
+};
+// SSRF guard. Rejects non-http(s), private/loopback/link-local literals, and hostnames
+// that resolve to private/loopback IPs. NOT a full DNS-rebinding fix: we don't pin the
+// resolved address at connect time, so a hostile resolver could return a public IP here
+// and a private one when `fetch` re-resolves. Portable connect-time pinning across
+// Bun/Node/Deno isn't possible via standard fetch — that needs a runtime-specific
+// dispatcher (e.g. undici `lookup` on Node) and is out of scope here.
+export async function assertSafeUrl(rawUrl, lookup) {
+    let u;
+    try {
+        u = new URL(rawUrl);
+    }
+    catch {
+        throw new Error(`Invalid URL: ${rawUrl}`);
+    }
+    if (u.protocol !== 'http:' && u.protocol !== 'https:') {
+        throw new Error(`Only http/https URLs are allowed: ${u.protocol}`);
+    }
+    const h = u.hostname.toLowerCase();
+    if (isPrivateOrLoopbackHost(h)) {
+        throw new Error(`Refusing to fetch private/loopback address: ${h}`);
+    }
+    // For non-literal hostnames, resolve and re-check every returned IP. Closes the
+    // "public-looking domain resolves to private IP" bypass on the literal-hostname check.
+    if (!isIpLiteral(h)) {
+        let addrs;
+        try {
+            addrs = await lookup(h);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(`DNS lookup failed for ${h}: ${message}`);
+        }
+        if (addrs.length === 0) {
+            throw new Error(`Hostname did not resolve to any address: ${h}`);
+        }
+        for (const { address } of addrs) {
+            if (isPrivateOrLoopbackHost(address.toLowerCase())) {
+                throw new Error(`Refusing to fetch hostname resolving to private/loopback: ${h} → ${address}`);
+            }
+        }
+    }
+    return u;
+}
+function isIpLiteral(h) {
+    // Brackets are already stripped by URL.hostname for IPv6, but be defensive.
+    const s = h.startsWith('[') && h.endsWith(']') ? h.slice(1, -1) : h;
+    // IPv6 literals always contain a colon. IPv4 literals are pure dotted quads.
+    if (s.includes(':'))
+        return true;
+    return /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(s);
+}
+function isPrivateOrLoopbackHost(h) {
+    // WHATWG URL preserves brackets on IPv6 hostnames — strip them so the rest can pattern-match.
+    if (h.startsWith('[') && h.endsWith(']'))
+        h = h.slice(1, -1);
+    if (h === 'localhost' || h === '::1' || h === '::' || h.endsWith('.localhost'))
+        return true;
+    // IPv4-mapped IPv6 (::ffff:0:0/96). URL normalizes ::ffff:127.0.0.1 → ::ffff:7f00:1
+    // (compressed hex), so handle both dotted and hex tails. Extract embedded IPv4 and re-check.
+    if (h.startsWith('::ffff:')) {
+        const tail = h.slice(7);
+        const dotted = /^(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(tail);
+        if (dotted?.[1])
+            return isPrivateOrLoopbackHost(dotted[1]);
+        const hex = /^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(tail);
+        if (hex?.[1] && hex[2]) {
+            const high = parseInt(hex[1], 16);
+            const low = parseInt(hex[2], 16);
+            const ipv4 = `${(high >> 8) & 0xff}.${high & 0xff}.${(low >> 8) & 0xff}.${low & 0xff}`;
+            return isPrivateOrLoopbackHost(ipv4);
+        }
+        // Unrecognized ::ffff: form — block as a safety net rather than fall through.
+        return true;
+    }
+    const ipv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(h);
+    if (ipv4) {
+        const a = Number(ipv4[1]);
+        const b = Number(ipv4[2]);
+        if (a === 0 || a === 10 || a === 127)
+            return true;
+        if (a === 169 && b === 254)
+            return true;
+        if (a === 172 && b >= 16 && b <= 31)
+            return true;
+        if (a === 192 && b === 168)
+            return true;
+    }
+    // IPv6 unique-local fc00::/7, link-local fe80::/10 — only meaningful on IPv6 literals,
+    // otherwise we'd block valid public domains like `fc-example.com`.
+    if (h.includes(':')) {
+        if (h.startsWith('fc') || h.startsWith('fd'))
+            return true;
+        if (h.startsWith('fe8') || h.startsWith('fe9') || h.startsWith('fea') || h.startsWith('feb')) {
+            return true;
+        }
+    }
+    return false;
+}
+// Stream the body until `maxChars` UTF-8 characters have been collected, then cancel
+// the reader. Avoids buffering an entire huge response into memory just to slice it.
+async function readBodyCapped(response, maxChars) {
+    if (!response.body)
+        return { body: '', truncated: false };
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let body = '';
+    let truncated = false;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+                body += decoder.decode();
+                break;
+            }
+            body += decoder.decode(value, { stream: true });
+            if (body.length >= maxChars) {
+                truncated = body.length > maxChars;
+                body = body.slice(0, maxChars);
+                await reader.cancel();
+                return { body, truncated: true };
+            }
+        }
+    }
+    finally {
+        // Best-effort release; cancel after `done` is a no-op but throws on some streams.
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            // ignore
+        }
+    }
+    return { body, truncated };
+}
+// Default stealth headers — Chrome on macOS. Override via WebFetchInit.headers if a site
+// is blocking this exact fingerprint. Keep them in one place so it's easy to bump versions.
+export const DEFAULT_STEALTH_HEADERS = Object.freeze({
+    'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36',
+    Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8',
+    'Accept-Language': 'en-US,en;q=0.9',
+    'Accept-Encoding': 'gzip, deflate, br, zstd',
+    'Sec-Ch-Ua': '"Chromium";v="131", "Not_A Brand";v="24", "Google Chrome";v="131"',
+    'Sec-Ch-Ua-Mobile': '?0',
+    'Sec-Ch-Ua-Platform': '"macOS"',
+    'Sec-Fetch-Dest': 'document',
+    'Sec-Fetch-Mode': 'navigate',
+    'Sec-Fetch-Site': 'none',
+    'Sec-Fetch-User': '?1',
+    'Upgrade-Insecure-Requests': '1',
+});
+const DEFAULT_MAX_CHARS = 200_000;
+const DEFAULT_TIMEOUT_MS = 15_000;
+const SERVER_TOOL_STUB = 'Local web-fetch is disabled. Use the openrouter:web_fetch server tool instead (see webFetchServerTool in src/openrouter/server-tools.ts).';
+export function webFetchTool(init = {}) {
+    const local = init.local ?? true;
+    const headers = { ...DEFAULT_STEALTH_HEADERS, ...init.headers };
+    const lookup = init.lookup ?? defaultLookup;
+    if (!local) {
+        return tool({
+            description: 'Fetch a URL via stealthed local HTTP. Stubbed: this instance delegates to OpenRouter web_fetch server tool.',
+            inputSchema: webFetchInputSchema,
+            execute: async (input) => ({
+                url: input.url,
+                finalUrl: input.url,
+                status: 0,
+                contentType: null,
+                body: SERVER_TOOL_STUB,
+                truncated: false,
+                retrievedAt: new Date().toISOString(),
+            }),
+        });
+    }
+    return tool({
+        description: 'Fetch a URL with browser-like headers and return the response body. Body is truncated to maxChars (default 200_000).',
+        inputSchema: webFetchInputSchema,
+        execute: async (input) => {
+            const maxChars = input.maxChars ?? DEFAULT_MAX_CHARS;
+            const timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+            const safeUrl = await assertSafeUrl(input.url, lookup);
+            const requestHeaders = { ...headers };
+            if (input.referrer !== undefined) {
+                requestHeaders.Referer = input.referrer;
+            }
+            const response = await fetch(safeUrl, {
+                headers: requestHeaders,
+                redirect: 'follow',
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            const { body, truncated } = await readBodyCapped(response, maxChars);
+            return {
+                url: input.url,
+                finalUrl: response.url || input.url,
+                status: response.status,
+                contentType: response.headers.get('content-type'),
+                body,
+                truncated,
+                retrievedAt: new Date().toISOString(),
+            };
+        },
+    });
+}
+//# sourceMappingURL=web-fetch.js.map

package/dist/tools/web-fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-fetch.js","sourceRoot":"","sources":["../../src/tools/web-fetch.ts"],"names":[],"mappings":"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"}

package/dist/workspace/worktree-pool.d.ts

@@ -0,0 +1,21 @@
+export type Worktree = {
+    groupId: string;
+    branch: string;
+    path: string;
+};
+export declare class WorktreePool {
+    private readonly repoRoot;
+    private readonly stateDir;
+    private readonly maxConcurrent;
+    private readonly worktrees;
+    private readonly pendingGroupIds;
+    private readonly waiters;
+    private reserved;
+    constructor(repoRoot: string, stateDir: string, maxConcurrent: number);
+    acquire(groupId: string, branch: string, baseBranch: string): Promise<Worktree>;
+    release(groupId: string): Promise<void>;
+    releaseAll(): Promise<void>;
+    active(): ReadonlyArray<Worktree>;
+    private reserveSlot;
+    private freeSlot;
+}

package/dist/workspace/worktree-pool.js

@@ -0,0 +1,104 @@
+// Concurrent Workers cannot share the same git working tree without trampling each other.
+// WorktreePool issues an isolated `git worktree` per active group under
+// .ai-task-master/worktrees/<group-id>/. On release, the worktree is removed.
+//
+// docs/state.md (state dir layout — `worktrees/` is a new subtree added for concurrent runs)
+// docs/task-groups.md §Branching (branch naming: aitm/<runId>/<group.id>)
+// docs/runtime.md (uses execa, never Bun.$)
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { execa } from 'execa';
+// Restrict groupId to characters safe as a single path segment so `join(worktreesDir,
+// groupId)` cannot escape into a parent directory and `release()`'s force-remove of
+// the computed path cannot reach outside `worktrees/`.
+const SAFE_GROUP_ID = /^[A-Za-z0-9._-]+$/;
+function assertSafeGroupId(groupId) {
+    if (!SAFE_GROUP_ID.test(groupId) || groupId === '.' || groupId === '..') {
+        throw new Error(`invalid groupId: ${groupId}`);
+    }
+}
+export class WorktreePool {
+    repoRoot;
+    stateDir;
+    maxConcurrent;
+    worktrees = new Map();
+    // `pendingGroupIds` covers acquires that have passed the duplicate check but not yet
+    // completed `git worktree add`. Without it, two concurrent `acquire(g1, ...)` calls
+    // could both pass the `worktrees.has` gate and race in `git worktree add`.
+    pendingGroupIds = new Set();
+    waiters = [];
+    // `reserved` covers both checked-out worktrees AND acquires that have passed the
+    // gate but not yet completed `git worktree add`. Without this, two concurrent
+    // acquire() calls could both pass `worktrees.size < maxConcurrent` and exceed the cap.
+    reserved = 0;
+    constructor(repoRoot, stateDir, maxConcurrent) {
+        this.repoRoot = repoRoot;
+        this.stateDir = stateDir;
+        this.maxConcurrent = maxConcurrent;
+    }
+    async acquire(groupId, branch, baseBranch) {
+        assertSafeGroupId(groupId);
+        if (this.worktrees.has(groupId) || this.pendingGroupIds.has(groupId)) {
+            throw new Error(`worktree already acquired for group ${groupId}`);
+        }
+        this.pendingGroupIds.add(groupId);
+        await this.reserveSlot();
+        const worktreesDir = join(this.stateDir, 'worktrees');
+        const path = join(worktreesDir, groupId);
+        try {
+            await mkdir(worktreesDir, { recursive: true });
+            await execa('git', ['worktree', 'add', path, '-b', branch, baseBranch], {
+                cwd: this.repoRoot,
+            });
+            const wt = { groupId, branch, path };
+            this.worktrees.set(groupId, wt);
+            return wt;
+        }
+        catch (err) {
+            this.freeSlot();
+            throw err;
+        }
+        finally {
+            this.pendingGroupIds.delete(groupId);
+        }
+    }
+    async release(groupId) {
+        const wt = this.worktrees.get(groupId);
+        if (!wt)
+            return;
+        // Don't drop tracking until `git worktree remove` succeeds: a failed cleanup must
+        // remain re-tryable via `release(groupId)`, and the slot must stay reserved so the
+        // pool doesn't overbook after an untracked worktree is left on disk.
+        await execa('git', ['worktree', 'remove', '--force', wt.path], { cwd: this.repoRoot });
+        this.worktrees.delete(groupId);
+        this.freeSlot();
+    }
+    async releaseAll() {
+        const ids = Array.from(this.worktrees.keys());
+        for (const id of ids) {
+            await this.release(id);
+        }
+    }
+    active() {
+        return Array.from(this.worktrees.values());
+    }
+    async reserveSlot() {
+        if (this.reserved < this.maxConcurrent) {
+            this.reserved++;
+            return;
+        }
+        await new Promise((resolve) => {
+            this.waiters.push(resolve);
+        });
+        // Slot was transferred from a releaser via freeSlot(); `reserved` is unchanged.
+    }
+    freeSlot() {
+        const next = this.waiters.shift();
+        if (next) {
+            next();
+            return;
+        }
+        this.reserved--;
+    }
+}
+//# sourceMappingURL=worktree-pool.js.map

package/dist/workspace/worktree-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-pool.js","sourceRoot":"","sources":["../../src/workspace/worktree-pool.ts"],"names":[],"mappings":"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"}