@pugi/cli 0.1.0-beta.7 → 0.1.0-beta.87

package/dist/tools/brief.js

@@ -0,0 +1,224 @@
+/**
+ * brief tool — operator-facing progress brief (tool gap pack).
+ *
+ * Emits a short, structured status note from the engine to the operator
+ * without consuming an assistant turn for narrative. The model calls
+ * this tool when it wants to surface "what I am doing right now" — a
+ * planning sketch, a blocker reason, a final wrap — in a form the
+ * operator can scan at-a-glance.
+ *
+ * Wire shape:
+ *  args: { headline: string, status: 'planning'|'working'|'blocked'|'done',
+ *          detail?: string }
+ *  side-effect: append one JSON line to `.pugi/briefs/<sessionId>.jsonl`,
+ *               via the atomic tmp+rename pattern (see writeBriefLine).
+ *  return:     one-line text envelope the engine echoes back to the
+ *               operator's stdout (the engine adapter renders it as a
+ *               neutral system line above the next model output).
+ *
+ * Why JSONL (one record per line) instead of a single rewritten JSON
+ * document: briefs accumulate across a session and the operator may
+ * want to scroll back through them; a JSONL tail is the natural shape
+ * for "give me the last N briefs" — same convention `.pugi/sessions/`
+ * already uses for tool-call events.
+ *
+ * Why atomic tmp+rename for append: a concurrent reader (`pugi briefs
+ * --tail`, future TUI surface) must never see a half-written line. The
+ * pattern: read existing body -> append the new line -> write the
+ * combined body to a sibling tmp file -> rename. Atomic on the same
+ * filesystem and POSIX-portable. The overhead (re-write the whole file
+ * on each append) is acceptable because briefs are short and capped to
+ * a small per-session budget by upstream rate limits.
+ *
+ * Brand voice: English only, no emoji, no banned words.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+/** Maximum header length. Mirrors the agent-progress card cap so the
+ * TUI can render briefs and progress cards in the same visual lane. */
+export const BRIEF_HEADLINE_MAX = 120;
+/** Maximum detail length. Keeps a single brief well below the 4 KiB
+ * line limit some tooling assumes for JSONL files. */
+export const BRIEF_DETAIL_MAX = 2_000;
+/** Hard cap on total bytes per brief line. Defense-in-depth gate so a
+ * pathological detail-with-headline-with-status combo cannot blow the
+ * tail consumer's per-line buffer. */
+export const BRIEF_LINE_MAX_BYTES = 4_096;
+/** Canonical brief statuses. The set is intentionally tiny — the goal
+ * is "what is the agent doing" at a glance, not a free-form taxonomy. */
+export const BRIEF_STATUSES = ['planning', 'working', 'blocked', 'done'];
+/** Sentinel returned when the input fails schema validation. The
+ * dispatcher pattern-matches on the prefix for retry-budget bookkeeping
+ * and the model self-corrects from the issue list that follows. */
+export const BRIEF_INVALID_ARGS = 'BRIEF_INVALID_ARGS';
+/** Sentinel returned when the encoded line would exceed the per-line
+ * byte cap. Distinct from the args-schema failure so the model knows it
+ * needs to shorten the detail / headline, not change the shape. */
+export const BRIEF_LINE_TOO_LARGE = 'BRIEF_LINE_TOO_LARGE';
+/**
+ * Validate the raw arguments. Returns the typed value on success or a
+ * `BRIEF_INVALID_ARGS: ...` sentinel string the dispatcher surfaces back
+ * to the model.
+ */
+export function parseBriefArgs(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return `${BRIEF_INVALID_ARGS}: arguments must be a JSON object`;
+    }
+    const obj = raw;
+    const issues = [];
+    const headline = obj['headline'];
+    if (typeof headline !== 'string') {
+        issues.push('headline: must be a string');
+    }
+    else if (headline.trim().length === 0) {
+        issues.push('headline: must be non-empty');
+    }
+    else if (headline.length > BRIEF_HEADLINE_MAX) {
+        issues.push(`headline: must be <= ${BRIEF_HEADLINE_MAX} chars`);
+    }
+    const status = obj['status'];
+    if (typeof status !== 'string') {
+        issues.push('status: must be a string');
+    }
+    else if (!BRIEF_STATUSES.includes(status)) {
+        issues.push(`status: must be one of ${BRIEF_STATUSES.join('|')}`);
+    }
+    let detail;
+    if (obj['detail'] !== undefined && obj['detail'] !== null) {
+        if (typeof obj['detail'] !== 'string') {
+            issues.push('detail: must be a string when present');
+        }
+        else if (obj['detail'].length > BRIEF_DETAIL_MAX) {
+            issues.push(`detail: must be <= ${BRIEF_DETAIL_MAX} chars`);
+        }
+        else {
+            detail = obj['detail'];
+        }
+    }
+    if (issues.length > 0) {
+        return `${BRIEF_INVALID_ARGS}: ${issues.join('; ')}`;
+    }
+    const result = detail !== undefined
+        ? { headline: headline, status: status, detail }
+        : { headline: headline, status: status };
+    return result;
+}
+/**
+ * Compute the on-disk path for a session's brief log. Public so a
+ * future tail consumer (`pugi briefs --tail <session>`) can share the
+ * exact resolution rules without duplicating layout knowledge.
+ */
+export function briefLogPath(ctx) {
+    const safe = sanitizeSessionId(ctx.sessionId);
+    return join(resolve(ctx.workspaceRoot), '.pugi', 'briefs', `${safe}.jsonl`);
+}
+/**
+ * Sanitise a session id for use as a filename. Restricts to the same
+ * character set agent-progress uses (`[A-Za-z0-9_-]+`) so the basename
+ * cannot escape the briefs directory via a `..` segment. Collapses any
+ * disallowed character to `_`; an empty result falls back to `session`.
+ *
+ * NOT exported as a generic helper because the only caller is this
+ * module — keep the surface area minimal.
+ */
+function sanitizeSessionId(id) {
+    if (typeof id !== 'string' || id.length === 0)
+        return 'session';
+    const collapsed = id.replace(/[^A-Za-z0-9_-]/g, '_');
+    const trimmed = collapsed.slice(0, 64);
+    return trimmed.length > 0 ? trimmed : 'session';
+}
+/**
+ * Dispatch entry point. Validates input, persists the brief line, and
+ * returns the operator-visible echo envelope. Returns sentinels on
+ * recoverable failures so the engine loop can surface them as tool
+ * results without tearing down on a throw.
+ */
+export function dispatchBrief(ctx, raw) {
+    const parsed = parseBriefArgs(raw);
+    if (typeof parsed === 'string') {
+        return parsed;
+    }
+    const ts = (ctx.now ? ctx.now() : new Date()).toISOString();
+    const record = parsed.detail !== undefined
+        ? { ts, status: parsed.status, headline: parsed.headline, detail: parsed.detail }
+        : { ts, status: parsed.status, headline: parsed.headline };
+    const line = JSON.stringify(record);
+    // Defense-in-depth byte cap. The earlier char-length checks bound the
+    // best case, but multi-byte UTF-8 input can still push the encoded
+    // line over the limit. Surface a distinct sentinel so the model knows
+    // to shorten the payload rather than change the shape.
+    if (Buffer.byteLength(line, 'utf8') > BRIEF_LINE_MAX_BYTES) {
+        return `${BRIEF_LINE_TOO_LARGE}: encoded line exceeds ${BRIEF_LINE_MAX_BYTES} bytes`;
+    }
+    const path = briefLogPath(ctx);
+    appendBriefLine(path, line);
+    return formatEcho(record, path);
+}
+/**
+ * Atomic append. Read existing body -> append the new line -> write to
+ * sibling tmp -> rename. The rename is atomic on the same filesystem
+ * so a concurrent tail consumer never reads a half-written line.
+ *
+ * Append-only via full rewrite is acceptable because brief logs are
+ * tiny (one short JSON object per call, sub-kilobyte each, capped by
+ * upstream rate limits to a few-hundred per session at most).
+ */
+function appendBriefLine(finalPath, line) {
+    const dir = dirname(finalPath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const prior = existsSync(finalPath) ? readFileSync(finalPath, 'utf8') : '';
+    const tail = prior.length > 0 && !prior.endsWith('\n') ? '\n' : '';
+    const next = `${prior}${tail}${line}\n`;
+    const tmpPath = `${finalPath}.tmp-${process.pid}-${briefSequence++}`;
+    writeFileSync(tmpPath, next, { encoding: 'utf8', mode: 0o644 });
+    renameSync(tmpPath, finalPath);
+}
+let briefSequence = 0;
+/**
+ * Render the one-line operator echo. The format is stable so a future
+ * REPL renderer can pattern-match the prefix for colouring.
+ */
+function formatEcho(record, path) {
+    const detail = record.detail ? ` -- ${truncate(record.detail, 240)}` : '';
+    return `[brief ${record.status}] ${record.headline}${detail} (logged to ${path})`;
+}
+function truncate(value, max) {
+    if (value.length <= max)
+        return value;
+    return `${value.slice(0, max - 1)}…`;
+}
+/**
+ * JSON-Schema fragment the schema builder advertises to the model.
+ * Hand-written to mirror the `parseBriefArgs` checks 1:1 — same
+ * convention `todo_write` and `ask_user_question` use because the
+ * runtime engine wires OpenAI-shape JSON Schema and we have not
+ * greenlit a zod-to-json-schema dependency.
+ */
+export const briefJsonSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['headline', 'status'],
+    properties: {
+        headline: {
+            type: 'string',
+            minLength: 1,
+            maxLength: BRIEF_HEADLINE_MAX,
+            description: `Short one-line summary, <= ${BRIEF_HEADLINE_MAX} chars.`,
+        },
+        status: {
+            type: 'string',
+            enum: [...BRIEF_STATUSES],
+            description: 'Lifecycle state: planning (deciding what to do), working (in progress), ' +
+                'blocked (waiting on operator), done (final wrap).',
+        },
+        detail: {
+            type: 'string',
+            maxLength: BRIEF_DETAIL_MAX,
+            description: `Optional context, <= ${BRIEF_DETAIL_MAX} chars.`,
+        },
+    },
+};
+//# sourceMappingURL=brief.js.map

package/dist/tools/enter-worktree.js

@@ -0,0 +1,250 @@
+/**
+ * enter_worktree tool — scratch git worktree primitive (tool gap pack
+ *).
+ *
+ * Spawns `git worktree add <path> [<baseRef>]` at
+ * `.pugi/worktrees/<taskId>/` so a long-running agent task can land
+ * its edits into an isolated scratch tree. The matching `exit_worktree`
+ * tool is the cleanup primitive. The actual fan-out (one worktree per
+ * task in a backlog batch) lives behind a separate task — this tool is
+ * the primitive both call paths share.
+ *
+ * Wire shape:
+ *  args:  { taskId: string, baseRef?: string }
+ *          - taskId: lowercase slug, `[a-z0-9][a-z0-9-]{0,63}`. The
+ *            pattern bans path-traversal segments (`..`, `/`, `\\`) so
+ *            the basename cannot escape `.pugi/worktrees/`.
+ *          - baseRef: optional git ref (branch / tag / SHA). Defaults
+ *            to `main` so the standard case is "fork from main and go".
+ *            The CLI validates the ref shape only loosely — git
+ *            rejects unknown refs upstream and that error message is
+ *            surfaced verbatim.
+ *  return: { ok: true, worktreePath, branchName } serialised JSON.
+ *
+ * Spawn discipline: every git invocation uses `spawnSync` with
+ * `shell: false` and a string-array argv so an unsanitised character
+ * inside a ref name cannot inject shell metacharacters. The taskId is
+ * gated by a strict regex BEFORE the spawn so the path argument is
+ * trusted.
+ *
+ * Path discipline: the worktree path is computed locally
+ * (`path.resolve(workspaceRoot, '.pugi/worktrees', taskId)`) and then
+ * containment-checked against the workspace root and the
+ * `.pugi/worktrees` subtree. Anything else throws — a deformed taskId
+ * that survived the regex (it should not) cannot pull the basename
+ * outside the expected subtree.
+ *
+ * Brand voice: English only, no emoji, no banned words.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+/** Strict taskId pattern. Lowercase alphanumeric + hyphen, must start
+ * with a lowercase letter or digit, length 1..64. The first-character
+ * constraint stops a leading hyphen from being interpreted as a flag
+ * by `git worktree add` (defense in depth — argv form already protects
+ * us, but a leading hyphen is still a smell). */
+export const TASK_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/** Default base ref when the caller does not supply one. */
+export const DEFAULT_BASE_REF = 'main';
+/** Sentinels. Distinct prefixes so the model / dispatcher can
+ * pattern-match without parsing the trailing message. */
+export const ENTER_WORKTREE_INVALID_ARGS = 'ENTER_WORKTREE_INVALID_ARGS';
+export const ENTER_WORKTREE_GIT_FAILED = 'ENTER_WORKTREE_GIT_FAILED';
+export const ENTER_WORKTREE_ALREADY_EXISTS = 'ENTER_WORKTREE_ALREADY_EXISTS';
+export const ENTER_WORKTREE_PATH_ESCAPED = 'ENTER_WORKTREE_PATH_ESCAPED';
+/**
+ * Validate the raw arguments. Returns the typed value on success or a
+ * `ENTER_WORKTREE_INVALID_ARGS: ...` sentinel string.
+ */
+/**
+ * Permissive git ref-name validation. We do not aim to fully implement
+ * `git check-ref-format` — instead reject anything outside a safe
+ * character class plus a leading-dash check. The leading-dash rule is
+ * the real defense: it stops an operator-controlled `baseRef` from
+ * being reinterpreted as a CLI flag (e.g. `--detach`, `--force`).
+ */
+function isValidGitRef(s) {
+    if (s.startsWith('-'))
+        return false;
+    return /^[A-Za-z0-9._/-]+$/.test(s);
+}
+export function parseEnterWorktreeArgs(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return `${ENTER_WORKTREE_INVALID_ARGS}: arguments must be a JSON object`;
+    }
+    const obj = raw;
+    const issues = [];
+    const taskId = obj['taskId'];
+    if (typeof taskId !== 'string') {
+        issues.push('taskId: must be a string');
+    }
+    else if (!TASK_ID_PATTERN.test(taskId)) {
+        issues.push(`taskId: must match ${TASK_ID_PATTERN}`);
+    }
+    let baseRef;
+    if (obj['baseRef'] !== undefined && obj['baseRef'] !== null) {
+        if (typeof obj['baseRef'] !== 'string') {
+            issues.push('baseRef: must be a string when present');
+        }
+        else if (obj['baseRef'].length === 0) {
+            issues.push('baseRef: must be non-empty when present');
+        }
+        else if (obj['baseRef'].length > 250) {
+            // Git imposes its own limits; we cut off well below them to keep
+            // error messages and audit lines bounded.
+            issues.push('baseRef: must be <= 250 chars when present');
+        }
+        else if (!isValidGitRef(obj['baseRef'])) {
+            // Permissive ref-chars regex that also rejects leading `-` so
+            // an operator-controlled `baseRef` cannot be reinterpreted as
+            // a git flag (e.g. `--detach`, `--force`). Combined with the
+            // `--` separator in argv this is belt-and-suspenders against
+            // arg-injection. Triple-review Claude P2,.
+            issues.push('baseRef: must match [A-Za-z0-9._/-] and not start with `-`');
+        }
+        else {
+            baseRef = obj['baseRef'];
+        }
+    }
+    if (issues.length > 0) {
+        return `${ENTER_WORKTREE_INVALID_ARGS}: ${issues.join('; ')}`;
+    }
+    const out = baseRef !== undefined
+        ? { taskId: taskId, baseRef }
+        : { taskId: taskId };
+    return out;
+}
+/**
+ * Compute the absolute on-disk path for a task's worktree. Public so
+ * `exit_worktree` and any future TUI surface can share the layout.
+ */
+export function worktreePathFor(workspaceRoot, taskId) {
+    return join(resolve(workspaceRoot), '.pugi', 'worktrees', taskId);
+}
+/**
+ * Compute the canonical worktree root (`<workspaceRoot>/.pugi/worktrees`).
+ * Used by `exit_worktree` for the containment check.
+ */
+export function worktreesRoot(workspaceRoot) {
+    return join(resolve(workspaceRoot), '.pugi', 'worktrees');
+}
+/**
+ * Dispatch entry point. Validates input, ensures the parent directory
+ * exists, then spawns `git worktree add` with the strict argv form.
+ * Returns the structured result envelope as JSON, or a sentinel string
+ * on a recoverable failure.
+ */
+export function dispatchEnterWorktree(ctx, raw) {
+    const parsed = parseEnterWorktreeArgs(raw);
+    if (typeof parsed === 'string') {
+        return parsed;
+    }
+    const baseRef = parsed.baseRef ?? DEFAULT_BASE_REF;
+    const root = resolve(ctx.workspaceRoot);
+    const targetPath = worktreePathFor(root, parsed.taskId);
+    const subtreeRoot = worktreesRoot(root);
+    // Defense in depth: re-check that the resolved target stays inside
+    // `<workspaceRoot>/.pugi/worktrees/`. The regex on taskId already
+    // bans `..` and `/`, so a successful escape here would indicate a
+    // catastrophic node:path regression — we still treat it as a fatal
+    // refusal rather than trusting the upstream gate alone.
+    if (!isContainedIn(targetPath, subtreeRoot)) {
+        return `${ENTER_WORKTREE_PATH_ESCAPED}: ${targetPath} is not under ${subtreeRoot}`;
+    }
+    if (existsSync(targetPath)) {
+        return `${ENTER_WORKTREE_ALREADY_EXISTS}: ${targetPath}`;
+    }
+    // Ensure `.pugi/worktrees/` exists; git worktree add will not create
+    // the parent for us.
+    if (!existsSync(subtreeRoot)) {
+        mkdirSync(subtreeRoot, { recursive: true });
+    }
+    // Compose the branch name we hand to git. The convention pairs
+    // 1:1 with taskId so `exit_worktree` does not need a separate
+    // lookup. `-b <branch>` creates the branch as a side effect of the
+    // worktree-add; without it git would refuse a worktree that points
+    // to an existing branch already checked out elsewhere.
+    const branchName = `pugi/worktree/${parsed.taskId}`;
+    // `--` separator forces git to treat everything after it as strict
+    // positionals. Belt-and-suspenders against arg-injection via
+    // `baseRef` (the regex above already rejects leading `-`).
+    const argv = [
+        'worktree',
+        'add',
+        '-b',
+        branchName,
+        '--',
+        targetPath,
+        baseRef,
+    ];
+    const runner = ctx.runGit ?? defaultGitRunner;
+    const result = runner(argv, root);
+    if (result.status !== 0) {
+        const detail = (result.stderr || result.stdout || `exit=${result.status}`).trim();
+        return `${ENTER_WORKTREE_GIT_FAILED}: ${detail}`;
+    }
+    const out = {
+        ok: true,
+        worktreePath: targetPath,
+        branchName,
+        baseRef,
+    };
+    return JSON.stringify(out);
+}
+/**
+ * Default spawnSync wrapper. `shell: false` is non-negotiable — every
+ * argv element is forwarded verbatim к the child without shell
+ * interpretation. The stdout/stderr captures are forced to utf-8 so the
+ * caller works with strings without manual decoding.
+ */
+function defaultGitRunner(argv, cwd) {
+    const result = spawnSync('git', [...argv], {
+        cwd,
+        shell: false,
+        encoding: 'utf8',
+        timeout: 30_000,
+    });
+    return {
+        status: result.status,
+        stdout: typeof result.stdout === 'string' ? result.stdout : '',
+        stderr: typeof result.stderr === 'string' ? result.stderr : '',
+    };
+}
+/**
+ * Containment check. Resolves both paths and asserts the target lives
+ * under the root via a separator-aware prefix match. The separator
+ * append on the root protects against the `/foo/bar2` vs `/foo/bar`
+ * partial-prefix bug.
+ */
+function isContainedIn(target, root) {
+    const rResolved = resolve(root);
+    const tResolved = resolve(target);
+    if (tResolved === rResolved)
+        return false;
+    const rootWithSep = rResolved.endsWith(sep) ? rResolved : `${rResolved}${sep}`;
+    return tResolved.startsWith(rootWithSep);
+}
+/**
+ * JSON-Schema fragment the schema builder advertises to the model.
+ */
+export const enterWorktreeJsonSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['taskId'],
+    properties: {
+        taskId: {
+            type: 'string',
+            pattern: '^[a-z0-9][a-z0-9-]{0,63}$',
+            description: 'Slug used as the worktree basename. ' +
+                'Lowercase alphanumeric + hyphen, must start with letter/digit, 1..64 chars.',
+        },
+        baseRef: {
+            type: 'string',
+            minLength: 1,
+            maxLength: 250,
+            description: `Optional git base ref (branch / tag / SHA). Defaults to "${DEFAULT_BASE_REF}".`,
+        },
+    },
+};
+//# sourceMappingURL=enter-worktree.js.map

package/dist/tools/exit-worktree.js

@@ -0,0 +1,147 @@
+/**
+ * exit_worktree tool — opposite of `enter_worktree` (tool gap pack
+ *).
+ *
+ * Tears down a scratch git worktree at the supplied path. The path is
+ * STRICTLY validated к live under `<workspaceRoot>/.pugi/worktrees/`
+ * — anything outside that subtree refuses with a sentinel and zero
+ * filesystem mutation. This is a destructive primitive, so the
+ * containment check is the load-bearing safety boundary.
+ *
+ * Procedure:
+ *  1. Validate the argument shape.
+ *  2. Resolve the input path and assert it lives under
+ *     `<workspaceRoot>/.pugi/worktrees/`. Refuse otherwise.
+ *  3. Run `git worktree remove --force <path>` so git's bookkeeping
+ *     drops the worktree. `--force` is required because the model may
+ *     have left dirty edits inside the scratch tree — that is the
+ *     normal case for a refactor that the operator is about to merge
+ *     via a different tool. Best-effort: a non-zero exit from git is
+ *     logged in the return envelope but does NOT abort the disk
+ *     cleanup. Git may have already cleaned the entry when the dir
+ *     itself was removed manually.
+ *  4. `rmSync(path, { recursive: true, force: true })` for any
+ *     leftover files.
+ *
+ * Wire shape:
+ *  args:  { worktreePath: string }
+ *  return: { ok: true, removed: boolean, gitStatus: number|null,
+ *            gitDetail?: string } serialised JSON.
+ *
+ * Idempotent: calling on a path that no longer exists returns
+ * `{ ok: true, removed: false }` with no error. This matches the
+ * semantics agent-progress / cleanup operations already follow elsewhere
+ * in the CLI.
+ *
+ * Brand voice: English only, no emoji, no banned words.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, rmSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+import { worktreesRoot } from './enter-worktree.js';
+/** Sentinels. Distinct prefixes so the model / dispatcher can
+ * pattern-match. */
+export const EXIT_WORKTREE_INVALID_ARGS = 'EXIT_WORKTREE_INVALID_ARGS';
+export const EXIT_WORKTREE_PATH_ESCAPED = 'EXIT_WORKTREE_PATH_ESCAPED';
+/**
+ * Validate the raw arguments. Returns the typed value on success or a
+ * `EXIT_WORKTREE_INVALID_ARGS: ...` sentinel string.
+ */
+export function parseExitWorktreeArgs(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return `${EXIT_WORKTREE_INVALID_ARGS}: arguments must be a JSON object`;
+    }
+    const obj = raw;
+    const worktreePath = obj['worktreePath'];
+    if (typeof worktreePath !== 'string') {
+        return `${EXIT_WORKTREE_INVALID_ARGS}: worktreePath: must be a string`;
+    }
+    if (worktreePath.length === 0) {
+        return `${EXIT_WORKTREE_INVALID_ARGS}: worktreePath: must be non-empty`;
+    }
+    return { worktreePath };
+}
+/**
+ * Dispatch entry point. Validates input, asserts the path lives under
+ * the allowed root, then runs `git worktree remove --force` followed
+ * by a filesystem removal for any leftovers. Returns the structured
+ * envelope as JSON.
+ *
+ * Returns sentinel strings on validation failures or a containment
+ * refusal — no throw — so the engine adapter surfaces a recoverable
+ * tool result and the model can adapt.
+ */
+export function dispatchExitWorktree(ctx, raw) {
+    const parsed = parseExitWorktreeArgs(raw);
+    if (typeof parsed === 'string') {
+        return parsed;
+    }
+    const root = resolve(ctx.workspaceRoot);
+    const subtreeRoot = worktreesRoot(root);
+    const target = resolve(parsed.worktreePath);
+    if (!isContainedIn(target, subtreeRoot)) {
+        return `${EXIT_WORKTREE_PATH_ESCAPED}: ${target} is not under ${subtreeRoot}`;
+    }
+    // git worktree remove. Best-effort. Non-zero exit is captured in the
+    // return envelope but does not block the rmTree step — a half-cleaned
+    // worktree (entry gone but dir survived) is a common operator-side
+    // mistake we want to recover from.
+    const runner = ctx.runGit ?? defaultGitRunner;
+    const gitResult = runner(['worktree', 'remove', '--force', target], root);
+    const existedBefore = existsSync(target);
+    const rmTree = ctx.rmTree ?? defaultRmTree;
+    if (existedBefore) {
+        rmTree(target);
+    }
+    const removed = existedBefore && !existsSync(target);
+    const envelope = gitResult.status === 0
+        ? { ok: true, removed, gitStatus: gitResult.status }
+        : {
+            ok: true,
+            removed,
+            gitStatus: gitResult.status,
+            gitDetail: (gitResult.stderr || gitResult.stdout || '').trim(),
+        };
+    return JSON.stringify(envelope);
+}
+function defaultGitRunner(argv, cwd) {
+    const result = spawnSync('git', [...argv], {
+        cwd,
+        shell: false,
+        encoding: 'utf8',
+        timeout: 30_000,
+    });
+    return {
+        status: result.status,
+        stdout: typeof result.stdout === 'string' ? result.stdout : '',
+        stderr: typeof result.stderr === 'string' ? result.stderr : '',
+    };
+}
+function defaultRmTree(path) {
+    rmSync(path, { recursive: true, force: true });
+}
+function isContainedIn(target, root) {
+    const rResolved = resolve(root);
+    const tResolved = resolve(target);
+    if (tResolved === rResolved)
+        return false;
+    const rootWithSep = rResolved.endsWith(sep) ? rResolved : `${rResolved}${sep}`;
+    return tResolved.startsWith(rootWithSep);
+}
+/**
+ * JSON-Schema fragment the schema builder advertises to the model.
+ */
+export const exitWorktreeJsonSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['worktreePath'],
+    properties: {
+        worktreePath: {
+            type: 'string',
+            minLength: 1,
+            description: 'Absolute path to the worktree to tear down. Must live under ' +
+                '<workspaceRoot>/.pugi/worktrees/ — anything else refuses.',
+        },
+    },
+};
+//# sourceMappingURL=exit-worktree.js.map