@yagni-app/code-staging 1.0.0-staging.1178.1 → 1.0.0-staging.1179.1

package/dist/cli.js

@@ -16,7 +16,7 @@ import { spawn } from "node:child_process";
 import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
 import { createInterface } from "node:readline/promises";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { PI_CONFIG_NAME } from "./branding.js";
 import { claudeCompatArgs } from "./claudeCompat.js";
 import { agentDir, credentialsDir, piPackageDir } from "./credentials.js";
@@ -35,8 +35,9 @@ import { currentCliVersion, maybeNudgeAndRefresh, upgradeCommand } from "./upgra
 import { maybeRefreshAtLaunch } from "./refresh.js";
 import { exitCodeFor, installSignalForwarding } from "./signalForward.js";
 import { PAD_X } from "./padding.js";
+import { parseWorktreeFlag, validateWorktreeLaunchArgs } from "./worktreeArgs.js";
 import { ensureShadowPiPackage } from "./piPackage.js";
-import { resolveExtensionPath, resolvePiCliPath, resolvePiPackageDir } from "./paths.js";
+import { resolveExtensionPath, resolvePiCliPath, resolvePiPackageDir, resolveSessionWorktreePath } from "./paths.js";
 import { credentialsFromProfile, getActiveProfileName, listProfiles, migrateLegacyCredentials, persistProfileTokenRotation, profilePath, readActiveProfile, useProfile, } from "./profiles.js";
 // Present as "yagni" in process listings, not "node".
 process.title = DISTRIBUTION.commandName;
@@ -161,6 +162,14 @@ export function seedHideThinkingBlock(piAgentDir) {
     return seedSetting(piAgentDir, "hideThinkingBlock", true);
 }
 async function runDefault(passthroughArgs) {
+    // `-w / --worktree [name]` is its own launch path: create/resume a worktree
+    // and enter a session there. Gate strictly on `requested` (not `name`) so a
+    // bare `-w` (random slug) is honored too. Returning early keeps the standard
+    // path below physically unreachable by any `-w` bug.
+    const worktree = parseWorktreeFlag(passthroughArgs);
+    if (worktree.requested) {
+        return runWorktreeLaunch(worktree.remainingArgs, worktree.name);
+    }
     // Parse --output-format out of argv before passing to pi (pi doesn't know
     // about it). The format determines how we handle pi's stdout: text = inherit,
     // stream-json = inherit with --mode json, json = pipe + post-process.
@@ -266,10 +275,22 @@ async function runDefault(passthroughArgs) {
         process.stderr.write(`${warning}\n`);
     }
     const { env, argv } = plan;
+    return spawnPiAndAwait({
+        argv,
+        env,
+        remainingArgs,
+        outputFormat,
+    });
+}
+/**
+ * Spawn pi and await its exit, mapping to the launcher's exit code. Extracted
+ * so `runDefault` (cwd = current) and `runWorktreeLaunch` (cwd = worktree) share
+ * the exact same json/stream-json post-processing, signal forwarding, and exit
+ * code mapping — the two paths can never drift on the output contract.
+ */
+async function spawnPiAndAwait(opts) {
+    const { argv, env, remainingArgs, outputFormat, cwd } = opts;
     // For json/stream-json output, inject --mode json so pi emits NDJSON events.
-    // Don't override if the user already chose --mode (mirrors userChoseProvider/
-    // userChoseModel in buildLaunch). Appended at the end — pi's flag parser
-    // handles --mode anywhere in argv.
     const userChoseMode = remainingArgs.some((a) => a === "--mode" || a.startsWith("--mode="));
     const childArgv = outputFormat === "text" || userChoseMode
         ? argv
@@ -285,6 +306,7 @@ async function runDefault(passthroughArgs) {
         const child = spawn(process.execPath, [piCli, ...childArgv], {
             stdio: stdio,
             env,
+            ...(cwd ? { cwd } : {}),
         });
         // Collect pi's stdout when piping for --output-format json.
         let stdoutChunks = "";
@@ -323,6 +345,131 @@ async function runDefault(passthroughArgs) {
         });
     });
 }
+async function defaultLoadSessionWorktree() {
+    const mod = (await import(pathToFileURL(resolveSessionWorktreePath()).href));
+    if (typeof mod?.createOrResume !== "function") {
+        throw new Error("The bundled extension is missing its session-worktree entry point (is the CLI up to date?).");
+    }
+    return mod;
+}
+/**
+ * `yagni -w [name]` — create/resume a worktree and enter a session there.
+ *
+ * Delegates all git behavior to the extension's `sessionWorktree` entry; this
+ * launcher path only resolves credentials, builds the plan, and spawns pi with
+ * `cwd` = the worktree. The worktree is DURABLE — nothing is ever removed.
+ */
+async function runWorktreeLaunch(passthroughArgs, worktreeName, loadSessionWorktree = defaultLoadSessionWorktree) {
+    // Validate the name + argv before any side effect (slug guard + `-c`
+    // disallow). The extension re-validates the mapped slug for PR refs.
+    const launchError = validateWorktreeLaunchArgs(worktreeName, passthroughArgs);
+    if (launchError !== undefined) {
+        process.stderr.write(`${launchError}\n`);
+        return 1;
+    }
+    const { format: outputFormat, remainingArgs } = parseOutputFormat(passthroughArgs);
+    // Load the session-worktree entry first, so a stale bundled extension fails
+    // honestly before we mutate anything.
+    let sessionWorktree;
+    try {
+        sessionWorktree = await loadSessionWorktree();
+    }
+    catch (err) {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+    // Create/resume resolves the main repo root + branch + dir, and performs
+    // `git worktree add` / resume. Never throws on a normal path; catch-all maps
+    // to a clean stderr + exit 1.
+    let result;
+    try {
+        result = await sessionWorktree.createOrResume(worktreeName, {
+            repoCwd: process.cwd(),
+        });
+    }
+    catch (err) {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+    // Reuse the standard credential + env + plan flow (same token refresh, shadow
+    // package, compat args, preflight). The worktree becomes the project cwd, so
+    // compat assets resolve from there.
+    await maybeNudgeAndRefresh({ current: cliVersion() });
+    const profile = await readActiveProfile();
+    let creds = credentialsFromProfile(profile);
+    if (!creds?.token) {
+        process.stderr.write(`Not logged in to environment "${profile.name}" (${profile.baseUrl}). Run \`yagni login\` first.\n`);
+        return 1;
+    }
+    const refresh = await maybeRefreshAtLaunch(creds, {
+        persist: (c) => persistProfileTokenRotation(profile.name, c),
+    });
+    for (const warning of refresh.warnings) {
+        process.stderr.write(`${warning}\n`);
+    }
+    creds = refresh.creds;
+    const piAgentDir = agentDir(profile.name);
+    mkdirSync(piAgentDir, { recursive: true, mode: 0o700 });
+    seedEditorPadding(piAgentDir);
+    seedCollapseChangelog(piAgentDir);
+    seedHideThinkingBlock(piAgentDir);
+    let shadowPiDir;
+    try {
+        shadowPiDir = ensureShadowPiPackage({
+            realPiDir: resolvePiPackageDir(),
+            shadowDir: piPackageDir(),
+            name: PI_CONFIG_NAME,
+        });
+    }
+    catch {
+        shadowPiDir = undefined;
+    }
+    let compat = { argv: [], env: {} };
+    try {
+        compat = await claudeCompatArgs({
+            cwd: result.worktreePath,
+            agentDir: piAgentDir,
+            confirm: confirmOnTty,
+        });
+    }
+    catch {
+        compat = { argv: [], env: {} };
+    }
+    let plan;
+    try {
+        plan = buildLaunch(creds, remainingArgs, {
+            extensionPath: resolveExtensionPath(),
+            agentDir: piAgentDir,
+            piPackageDir: shadowPiDir,
+            extraAgentArgs: compat.argv,
+            extraEnv: compat.env,
+            profilePath: profilePath(profile.name),
+            stateDir: credentialsDir(),
+            cliVersion: cliVersion(),
+            baseEnv: process.env,
+        });
+    }
+    catch (err) {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+    for (const warning of plan.warnings) {
+        process.stderr.write(`${warning}\n`);
+    }
+    const exitCode = await spawnPiAndAwait({
+        argv: plan.argv,
+        env: plan.env,
+        remainingArgs,
+        outputFormat,
+        cwd: result.worktreePath,
+    });
+    // Durable by default: nothing is removed. Tell the user where their work
+    // lives (stderr only — never stdout, to keep json clean).
+    process.stderr.write(`[yagni] worktree ${result.existed ? "resumed" : "created"}: ${result.worktreePath}\n` +
+        `[yagni] branch: ${result.branch}\n` +
+        `[yagni] resume: cd ${result.worktreePath} && yagni\n`);
+    return exitCode;
+}
 export const HELP_TEXT = [
     "YAGNI Code — a business-context-grounded terminal coding agent.",
     "",
@@ -330,6 +477,7 @@ export const HELP_TEXT = [
     "  yagni [args…]            Launch the agent in the current repo.",
     "  yagni -c                 Continue the most recent session.",
     "  yagni -r                 Browse and resume a previous session.",
+    "  yagni -w [name]          Create/resume a worktree and enter a session there.",
     '  yagni -p "prompt"        Print one response and exit (reads piped stdin too).',
     '  yagni -p "prompt"        Use --output-format json for a machine-readable',
     '    --output-format json   result object with tools, cost, guardian reviews.',

package/dist/extension/pipeline/sessionWorktree.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `-w / --worktree` session-worktree plumbing.
+ *
+ * The launcher (`yagni-code-cli`) reaches this module by file path (the same
+ * seam as `headlessGo.ts` → `runHeadlessGo`) so it can create/resume a named
+ * YAGNI worktree BEFORE spawning pi into it. The launcher owns the process
+ * lifecycle (spawn + `cwd` + exit summary); this module owns the git behavior.
+ *
+ * Design invariants (see the YAG-594 plan):
+ *  - **Add-only creation.** Every git op is `worktree add`, `fetch`, `show-ref`,
+ *    `symbolic-ref`, or `rev-parse`. Nothing deletes, force-resets, or
+ *    `branch -D`s — the worktree is DURABLE by default and never auto-removed.
+ *  - **Get-or-resume.** An existing worktree dir is resumed, never recreated.
+ *  - **Lazy fetch.** Base `origin/<default>` is read from the local ref when
+ *    present; `git fetch` only runs when that ref is absent, and always with
+ *    credential prompts disabled.
+ *  - **Validate before any side effect.** The slug is checked (again, defense
+ *    in depth against the launcher) before the first git subprocess.
+ *  - **Canonical root.** `-w` invoked from inside an existing worktree lands in
+ *    the main repo, never nested.
+ *
+ * Convention reused from `/wt-new`: branch `agent/<slug>`, dir `.worktrees/<slug>`
+ * (both gitignored in-repo). PR refs (`#N`, GitHub PR URLs) map to `pr-<N>` and
+ * base on `FETCH_HEAD`.
+ */
+export interface SessionWorktreeResult {
+    /** Absolute destination (under `<mainRepo>/.worktrees/<slug>`). */
+    worktreePath: string;
+    /** The `agent/<slug>` branch. */
+    branch: string;
+    /** True when the worktree already existed (resumed, not created). */
+    existed: boolean;
+}
+export type SessionGit = (argv: string[], cwd: string, env?: NodeJS.ProcessEnv) => Promise<string>;
+export interface CreateOrResumeDeps {
+    /** Repo the user ran `yagni -w` from (any path inside it works for git). */
+    repoCwd: string;
+    /** Injectable git seam (defaults to a real `git` exec). */
+    gitImpl?: SessionGit;
+    /** Injectable fs seam for existence checks (defaults to node:fs). */
+    pathExists?: (p: string) => boolean;
+    /** Injectable randomness (defaults to Math.random). */
+    random?: () => number;
+}
+/** Turn arbitrary name text into a git-ref-safe slug. Empty input → "worktree". */
+export declare function slugify(name: string): string;
+/**
+ * Validate a worktree slug before any side effect. Mirrors Claude's guard:
+ * length cap, per-segment allowlist, `.`/`..` rejection. Throws synchronously.
+ */
+export declare function validateWorktreeSlug(slug: string): void;
+/**
+ * Parse a PR reference: `#N` or a GitHub-style PR URL. Returns the number or null.
+ */
+export declare function parsePRReference(input: string): number | null;
+/**
+ * Create or resume the session worktree for `name`.
+ *
+ * Throws with a user-surfaced message on any failure; the caller (launcher)
+ * catches and prints it to stderr + the diagnostic sink. Never leaves a partial
+ * branch/worktree: validation happens first, and `git worktree add` is atomic.
+ */
+export declare function createOrResume(name: string | undefined, deps: CreateOrResumeDeps): Promise<SessionWorktreeResult>;
+//# sourceMappingURL=sessionWorktree.d.ts.map

package/dist/extension/pipeline/sessionWorktree.js

@@ -0,0 +1,225 @@
+/**
+ * `-w / --worktree` session-worktree plumbing.
+ *
+ * The launcher (`yagni-code-cli`) reaches this module by file path (the same
+ * seam as `headlessGo.ts` → `runHeadlessGo`) so it can create/resume a named
+ * YAGNI worktree BEFORE spawning pi into it. The launcher owns the process
+ * lifecycle (spawn + `cwd` + exit summary); this module owns the git behavior.
+ *
+ * Design invariants (see the YAG-594 plan):
+ *  - **Add-only creation.** Every git op is `worktree add`, `fetch`, `show-ref`,
+ *    `symbolic-ref`, or `rev-parse`. Nothing deletes, force-resets, or
+ *    `branch -D`s — the worktree is DURABLE by default and never auto-removed.
+ *  - **Get-or-resume.** An existing worktree dir is resumed, never recreated.
+ *  - **Lazy fetch.** Base `origin/<default>` is read from the local ref when
+ *    present; `git fetch` only runs when that ref is absent, and always with
+ *    credential prompts disabled.
+ *  - **Validate before any side effect.** The slug is checked (again, defense
+ *    in depth against the launcher) before the first git subprocess.
+ *  - **Canonical root.** `-w` invoked from inside an existing worktree lands in
+ *    the main repo, never nested.
+ *
+ * Convention reused from `/wt-new`: branch `agent/<slug>`, dir `.worktrees/<slug>`
+ * (both gitignored in-repo). PR refs (`#N`, GitHub PR URLs) map to `pr-<N>` and
+ * base on `FETCH_HEAD`.
+ */
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync } from "node:fs";
+import { basename, dirname, isAbsolute, join } from "node:path";
+import { bootstrapWorktree } from "./worktree.js";
+/** Cap on the slug half (keeps refs & dirs readable). */
+const SLUG_MAX = 40;
+/** Maximum slug characters, mirrored from Claude's guard. */
+const MAX_SLUG_LENGTH = 64;
+/** Allowlist per `/`-separated segment (mirrors Claude's `validateWorktreeSlug`). */
+const VALID_SLUG_SEGMENT = /^[a-zA-Z0-9._-]+$/;
+/** Env that prevents git/ssh from prompting for credentials (which would hang). */
+const GIT_NO_PROMPT_ENV = {
+    GIT_TERMINAL_PROMPT: "0",
+    GIT_ASKPASS: "",
+};
+/** Turn arbitrary name text into a git-ref-safe slug. Empty input → "worktree". */
+export function slugify(name) {
+    const slug = name
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, SLUG_MAX)
+        .replace(/-+$/, "");
+    return slug || "worktree";
+}
+/**
+ * Validate a worktree slug before any side effect. Mirrors Claude's guard:
+ * length cap, per-segment allowlist, `.`/`..` rejection. Throws synchronously.
+ */
+export function validateWorktreeSlug(slug) {
+    if (slug.length > MAX_SLUG_LENGTH) {
+        throw new Error(`Invalid worktree name: must be ${MAX_SLUG_LENGTH} characters or fewer (got ${slug.length})`);
+    }
+    for (const segment of slug.split("/")) {
+        if (segment === "." || segment === "..") {
+            throw new Error(`Invalid worktree name "${slug}": must not contain "." or ".." path segments`);
+        }
+        if (!VALID_SLUG_SEGMENT.test(segment)) {
+            throw new Error(`Invalid worktree name "${slug}": each "/"-separated segment must be non-empty and contain only letters, digits, dots, underscores, and dashes`);
+        }
+    }
+}
+/**
+ * Parse a PR reference: `#N` or a GitHub-style PR URL. Returns the number or null.
+ */
+export function parsePRReference(input) {
+    const urlMatch = input.match(/^https?:\/\/[^/]+\/[^/]+\/[^/]+\/pull\/(\d+)\/?(?:[?#].*)?$/i);
+    if (urlMatch?.[1])
+        return parseInt(urlMatch[1], 10);
+    const hashMatch = input.match(/^#(\d+)$/);
+    if (hashMatch?.[1])
+        return parseInt(hashMatch[1], 10);
+    return null;
+}
+function randomSlug(random = Math.random) {
+    const adjectives = ["swift", "bright", "calm", "keen", "bold", "quiet", "warm", "true"];
+    const nouns = ["fox", "owl", "elm", "oak", "ray", "fern", "pine", "brook"];
+    const adj = adjectives[Math.floor(random() * adjectives.length)];
+    const noun = nouns[Math.floor(random() * nouns.length)];
+    const suffix = Math.floor(random() * 0x10000).toString(36).padStart(4, "0");
+    return `${adj}-${noun}-${suffix}`;
+}
+function defaultGit(argv, cwd, env) {
+    return new Promise((resolve, reject) => {
+        execFile("git", argv, { cwd, env, maxBuffer: 32 * 1024 * 1024 }, (err, stdout, stderr) => {
+            if (err) {
+                reject(new Error(stderr.toString().trim() || err.message));
+                return;
+            }
+            resolve(stdout.toString().trim());
+        });
+    });
+}
+/** The main repo root, resolved through an existing linked worktree via commondir. */
+async function resolveMainRepo(gitImpl, repoCwd) {
+    let topLevel;
+    try {
+        topLevel = await gitImpl(["rev-parse", "--show-toplevel"], repoCwd);
+    }
+    catch (err) {
+        throw new Error(`Cannot create a worktree: not inside a git repository. ` +
+            `${err instanceof Error ? err.message : String(err)}`);
+    }
+    const common = await gitImpl(["rev-parse", "--git-common-dir"], repoCwd);
+    const abs = isAbsolute(common) ? common : join(topLevel, common);
+    // A linked worktree's commondir points at the shared `.git`; the main repo root
+    // is its parent. A main checkout resolves to its own toplevel.
+    return basename(abs) === ".git" ? dirname(abs) : topLevel;
+}
+/** Resolve the default branch: origin/HEAD symref, else main, else master. */
+async function resolveDefaultBranch(gitImpl, repoCwd) {
+    try {
+        const symref = await gitImpl(["symbolic-ref", "refs/remotes/origin/HEAD"], repoCwd);
+        const name = symref.replace(/^refs\/remotes\//, "");
+        if (name)
+            return name;
+    }
+    catch {
+        /* no origin/HEAD symref */
+    }
+    for (const candidate of ["main", "master"]) {
+        try {
+            await gitImpl(["show-ref", "--verify", "--quiet", `refs/remotes/origin/${candidate}`], repoCwd);
+            return candidate;
+        }
+        catch {
+            /* keep looking */
+        }
+    }
+    return "main";
+}
+/** True when a local branch `refs/heads/<branch>` exists. */
+async function branchExists(gitImpl, repoCwd, branch) {
+    try {
+        await gitImpl(["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], repoCwd);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Create or resume the session worktree for `name`.
+ *
+ * Throws with a user-surfaced message on any failure; the caller (launcher)
+ * catches and prints it to stderr + the diagnostic sink. Never leaves a partial
+ * branch/worktree: validation happens first, and `git worktree add` is atomic.
+ */
+export async function createOrResume(name, deps) {
+    const gitImpl = deps.gitImpl ?? defaultGit;
+    const pathExists = deps.pathExists ?? ((p) => existsSync(p));
+    const random = deps.random ?? Math.random;
+    const repoCwd = deps.repoCwd;
+    const prNumber = name !== undefined ? parsePRReference(name) : null;
+    const slug = prNumber !== null
+        ? `pr-${prNumber}`
+        : slugify(name ?? randomSlug(random));
+    validateWorktreeSlug(slug);
+    const repoRoot = await resolveMainRepo(gitImpl, repoCwd);
+    const branch = `agent/${slug}`;
+    const worktreePath = join(repoRoot, ".worktrees", slug);
+    // Get-or-resume: an existing dir is resumed, never recreated/fetched/overwritten.
+    if (pathExists(worktreePath)) {
+        return { worktreePath, branch, existed: true };
+    }
+    // Collision: the branch already exists locally (dirty leftover from a prior
+    // crash) — refuse rather than force-reset.
+    if (await branchExists(gitImpl, repoCwd, branch)) {
+        throw new Error(`Branch ${branch} already exists. Pick a different name with \`-w <other>\`, or clean it up first.`);
+    }
+    mkdirSync(dirname(worktreePath), { recursive: true, mode: 0o700 });
+    // Resolve base. PR path fetches the PR head into FETCH_HEAD; default path uses
+    // the local origin/<default> ref when present, else fetches, else falls back
+    // to HEAD (a repo with no remote or no commits still works).
+    let base;
+    const fetchEnv = { ...process.env, ...GIT_NO_PROMPT_ENV };
+    if (prNumber !== null) {
+        try {
+            await gitImpl(["fetch", "origin", `pull/${prNumber}/head`], repoCwd, fetchEnv);
+        }
+        catch (err) {
+            throw new Error(`Failed to fetch PR #${prNumber}: ${err instanceof Error ? err.message : String(err)}. ` +
+                `The PR may not exist or this repo may not have a remote named "origin".`);
+        }
+        base = "FETCH_HEAD";
+    }
+    else {
+        const defaultBranch = await resolveDefaultBranch(gitImpl, repoCwd);
+        let originRef = null;
+        try {
+            await gitImpl(["show-ref", "--verify", "--quiet", `refs/remotes/origin/${defaultBranch}`], repoCwd);
+            originRef = `origin/${defaultBranch}`;
+        }
+        catch {
+            try {
+                await gitImpl(["fetch", "origin", defaultBranch], repoCwd, fetchEnv);
+                originRef = `origin/${defaultBranch}`;
+            }
+            catch {
+                originRef = "HEAD"; // no remote / no commits: degrade to local HEAD
+            }
+        }
+        base = originRef;
+    }
+    try {
+        await gitImpl(["worktree", "add", "-b", branch, worktreePath, base], repoCwd);
+    }
+    catch (err) {
+        throw new Error(`Failed to create worktree: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Best-effort: install deps + env so a fresh worktree can actually run.
+    try {
+        await bootstrapWorktree(worktreePath);
+    }
+    catch {
+        /* bootstrap is best-effort; a failed install must not fail the launch */
+    }
+    return { worktreePath, branch, existed: false };
+}
+//# sourceMappingURL=sessionWorktree.js.map

package/dist/paths.d.ts

@@ -29,6 +29,16 @@ export declare function resolveExtensionPath(): string;
  * it pulls in the pipeline alone, with none of pi's TUI surface.
  */
 export declare function resolveHeadlessGoPath(): string;
+/**
+ * Absolute path to the extension's session-worktree entry
+ * (`pipeline/sessionWorktree.js`), the module `yagni -w` imports.
+ *
+ * Mirrors `resolveHeadlessGoPath`: derived from the extension entry so the
+ * bundled-vs-workspace fallback is resolved once. Only this one module is
+ * loaded (not the whole extension): it pulls in the worktree plumbing alone,
+ * with none of pi's TUI surface.
+ */
+export declare function resolveSessionWorktreePath(): string;
 /**
  * Absolute path to pi's package root — the dir whose package.json names the
  * package. The shadow package dir is built from this (we read its package.json

package/dist/paths.js

@@ -43,6 +43,19 @@ export function resolveHeadlessGoPath() {
     const entry = resolveExtensionPath();
     return join(dirname(entry), "pipeline", "headlessGo.js");
 }
+/**
+ * Absolute path to the extension's session-worktree entry
+ * (`pipeline/sessionWorktree.js`), the module `yagni -w` imports.
+ *
+ * Mirrors `resolveHeadlessGoPath`: derived from the extension entry so the
+ * bundled-vs-workspace fallback is resolved once. Only this one module is
+ * loaded (not the whole extension): it pulls in the worktree plumbing alone,
+ * with none of pi's TUI surface.
+ */
+export function resolveSessionWorktreePath() {
+    const entry = resolveExtensionPath();
+    return join(dirname(entry), "pipeline", "sessionWorktree.js");
+}
 /**
  * Absolute path to pi's package root — the dir whose package.json names the
  * package. The shadow package dir is built from this (we read its package.json

package/dist/worktreeArgs.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Pure parsing + validation for `-w / --worktree [name]` (YAG-594).
+ *
+ * No side effects, no I/O: `parseWorktreeFlag` extracts the flag and its
+ * optional value from argv (leaving everything else for pi unchanged), and
+ * `validateWorktreeSlug` mirrors Claude's allowlist so a hostile name is
+ * rejected before the launcher touches git in any way.
+ */
+export interface WorktreeFlag {
+    /** Distinguishes "-w with no name" from "-w absent" so bare `-w` is honored. */
+    requested: boolean;
+    /** The name value, when supplied (`-w foo` / `--worktree=foo`). */
+    name?: string;
+    /** Everything that isn't the worktree flag/name, passed through to pi. */
+    remainingArgs: string[];
+}
+/**
+ * Extract `-w`/`--worktree [name]` from argv without disturbing the rest. Runs
+ * BEFORE `parseOutputFormat` so the two argv-mutators never double-handle a
+ * flag: this strips only the worktree flag, and the caller feeds `remainingArgs`
+ * to `parseOutputFormat` next.
+ */
+export declare function parseWorktreeFlag(argv: string[]): WorktreeFlag;
+/**
+ * Parse a PR reference: `#N` or a GitHub-style PR URL, mirroring the extension's
+ * `parsePRReference` (the two packages stay independent; this is the launcher's
+ * copy so `-w` can recognize a PR ref before slug-validating the raw name).
+ */
+export declare function parsePRReference(input: string): number | null;
+/**
+ * Validate a worktree slug before any side effect. Mirrors Claude's guard:
+ * length cap, per-segment allowlist, `.`/`..` rejection. Throws synchronously
+ * with a clear message (surfaced by the caller).
+ */
+export declare function validateWorktreeSlug(slug: string): void;
+/**
+ * Validate the `-w` name + argv before any side effect. Returns a user-facing
+ * error message when the launch should be refused, or `undefined` to proceed.
+ * PR refs (`#N` / URL) skip slug validation here — they map to `pr-<N>` in the
+ * extension, whose own validation covers the mapped slug.
+ */
+export declare function validateWorktreeLaunchArgs(name: string | undefined, argv: string[]): string | undefined;
+//# sourceMappingURL=worktreeArgs.d.ts.map

package/dist/worktreeArgs.js

@@ -0,0 +1,96 @@
+/**
+ * Pure parsing + validation for `-w / --worktree [name]` (YAG-594).
+ *
+ * No side effects, no I/O: `parseWorktreeFlag` extracts the flag and its
+ * optional value from argv (leaving everything else for pi unchanged), and
+ * `validateWorktreeSlug` mirrors Claude's allowlist so a hostile name is
+ * rejected before the launcher touches git in any way.
+ */
+/** Maximum slug characters (mirrors Claude's guard). */
+const MAX_SLUG_LENGTH = 64;
+/** Allowlist per `/`-separated segment. */
+const VALID_SLUG_SEGMENT = /^[a-zA-Z0-9._-]+$/;
+/**
+ * Extract `-w`/`--worktree [name]` from argv without disturbing the rest. Runs
+ * BEFORE `parseOutputFormat` so the two argv-mutators never double-handle a
+ * flag: this strips only the worktree flag, and the caller feeds `remainingArgs`
+ * to `parseOutputFormat` next.
+ */
+export function parseWorktreeFlag(argv) {
+    const remainingArgs = [];
+    let requested = false;
+    let name;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "-w" || arg === "--worktree") {
+            requested = true;
+            // Consume the next token as the name only if it isn't another flag.
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith("-")) {
+                name = next;
+                i++;
+            }
+            continue;
+        }
+        if (arg.startsWith("--worktree=")) {
+            requested = true;
+            name = arg.slice("--worktree=".length);
+            continue;
+        }
+        remainingArgs.push(arg);
+    }
+    return { requested, name, remainingArgs };
+}
+/**
+ * Parse a PR reference: `#N` or a GitHub-style PR URL, mirroring the extension's
+ * `parsePRReference` (the two packages stay independent; this is the launcher's
+ * copy so `-w` can recognize a PR ref before slug-validating the raw name).
+ */
+export function parsePRReference(input) {
+    const urlMatch = input.match(/^https?:\/\/[^/]+\/[^/]+\/[^/]+\/pull\/(\d+)\/?(?:[?#].*)?$/i);
+    if (urlMatch?.[1])
+        return parseInt(urlMatch[1], 10);
+    const hashMatch = input.match(/^#(\d+)$/);
+    if (hashMatch?.[1])
+        return parseInt(hashMatch[1], 10);
+    return null;
+}
+/**
+ * Validate a worktree slug before any side effect. Mirrors Claude's guard:
+ * length cap, per-segment allowlist, `.`/`..` rejection. Throws synchronously
+ * with a clear message (surfaced by the caller).
+ */
+export function validateWorktreeSlug(slug) {
+    if (slug.length > MAX_SLUG_LENGTH) {
+        throw new Error(`Invalid worktree name: must be ${MAX_SLUG_LENGTH} characters or fewer (got ${slug.length})`);
+    }
+    for (const segment of slug.split("/")) {
+        if (segment === "." || segment === "..") {
+            throw new Error(`Invalid worktree name "${slug}": must not contain "." or ".." path segments`);
+        }
+        if (!VALID_SLUG_SEGMENT.test(segment)) {
+            throw new Error(`Invalid worktree name "${slug}": each "/"-separated segment must be non-empty and contain only letters, digits, dots, underscores, and dashes`);
+        }
+    }
+}
+/**
+ * Validate the `-w` name + argv before any side effect. Returns a user-facing
+ * error message when the launch should be refused, or `undefined` to proceed.
+ * PR refs (`#N` / URL) skip slug validation here — they map to `pr-<N>` in the
+ * extension, whose own validation covers the mapped slug.
+ */
+export function validateWorktreeLaunchArgs(name, argv) {
+    if (name !== undefined && parsePRReference(name) === null) {
+        try {
+            validateWorktreeSlug(name);
+        }
+        catch (err) {
+            return err instanceof Error ? err.message : String(err);
+        }
+    }
+    if (argv.includes("-c") || argv.includes("--continue")) {
+        return "`-c`/`--continue` is not supported with `-w` yet. Use `-w <name>` then `--session <id>` (or `-r`) to resume.";
+    }
+    return undefined;
+}
+//# sourceMappingURL=worktreeArgs.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yagni-app/code-staging",
-  "version": "1.0.0-staging.1178.1",
+  "version": "1.0.0-staging.1179.1",
   "description": "YAGNI Code: a terminal coding agent that already knows your company. One YAGNI login routes the model and grounds the agent in your team's context.",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "YAGNI, Inc. <jack@yagni.app> (https://yagni.app)",
@@ -40,5 +40,5 @@
     "turndown": "^7.2.4",
     "typebox": "^1.3.15"
   },
-  "yagniSourceSha": "d40167f97866479e71acceaf2132ed58f00cc0cc"
+  "yagniSourceSha": "0a0e2cda58c070bc25dbc00fe76d89269fb43c6f"
 }