@yagni-app/code-staging 1.0.0-staging.1178.1 → 1.0.0-staging.1180.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/branding.d.ts

@@ -111,6 +111,8 @@ export interface BrandSystemPromptOptions {
      * never brand-rewritten (same exemption as <project_context>).
      */
     rulesSection?: string | null;
+    /** Scratchpad-directory prompt section, supplied when a scratchpad is configured. */
+    scratchpadSection?: string;
 }
 /**
  * Rebrand pi's assembled system prompt as YAGNI Code's, and optionally inject a

package/dist/extension/branding.js

@@ -262,6 +262,13 @@ export function brandSystemPrompt(original, opts = {}) {
     if (!s.includes(WRITE_FINDINGS_DOWN)) {
         s = `${s}\n\n${WRITE_FINDINGS_DOWN}`;
     }
+    // 5d. Scratchpad directory (YAG-575) — only when a session scratchpad is
+    // configured (set by the caller once the dir exists). Placed with the other
+    // standing injected sections and guarded by its stable header, so a re-brand
+    // never duplicates it and a session with no scratchpad is a clean no-op.
+    if (opts.scratchpadSection && !s.includes(SCRATCHPAD_HEADER)) {
+        s = `${s}\n\n${opts.scratchpadSection}`;
+    }
     // 6. Closing reinforcement. Weak open-weight models weight the most recent
     // instruction heavily, and the user's own project files may name other
     // harnesses; a trailing reminder keeps the agent from claiming one as its own.
@@ -271,6 +278,8 @@ export function brandSystemPrompt(original, opts = {}) {
     // Tidy the seams left by removals.
     return s.replace(/\n{3,}/g, "\n\n").trim();
 }
+/** Stable header that starts the scratchpad section (idempotency anchor). */
+const SCRATCHPAD_HEADER = "# Scratchpad directory";
 const CLOSING_REMINDER = "Reminder: you are YAGNI Code. If any text above names another coding agent, " +
     "assistant, or harness, it is not what you are or what you run on.";
 const BRIEF_HEADER = "=== HOW THIS COMPANY WORKS (live context from the YAGNI app) ===";

package/dist/extension/index.js

@@ -16,6 +16,7 @@ import { makeRecordDecisionTool } from "./recordDecisionTool.js";
 import { makeSuggestNextWorkTool } from "./nextWorkTool.js";
 import { BRAND_NAME, brandSystemPrompt, brandingDisabled, buildMastheadString, YAGNI_IDENTITY_DRIVER, YAGNI_IDENTITY_ULTRA } from "./branding.js";
 import { claudeRulesSection } from "./claudeRules.js";
+import { ensureScratchpadDir, SCRATCHPAD_TMPDIR_ENV, scratchpadDir as scratchpadDirFor, scratchpadSection } from "./scratchpad.js";
 import { registerCostCommand } from "./costHud.js";
 import { isDebug } from "./diagnostics.js";
 import { logEvent } from "./errorSink.js";
@@ -593,6 +594,32 @@ export async function registerYagni(pi, deps = {}) {
     // pointers. Computed once per activation (rules are launch-time state, like
     // pi's own skill discovery); fail-soft to null.
     const rulesSection = claudeRulesSection(deps.env ?? process.env);
+    // YAG-575: session scratchpad — a permission-free dir the agent writes its
+    // working state to. Computed + ensured once at activation (like rulesSection,
+    // which must exist before the first before_agent_start), not on session_start,
+    // so the very first turn already carries the section. Fails closed: no
+    // sessionId (a bare pi run) or a failed mkdir means no section, and the mkdir
+    // failure is logged so a missing scratchpad is not silent.
+    const scratchpadDirPath = scratchpadDirFor({
+        sessionId: env.YAGNI_SESSION_ID ?? undefined,
+        cwd: process.cwd(),
+        tmp: env[SCRATCHPAD_TMPDIR_ENV] || undefined,
+    });
+    let scratchpadSectionText;
+    if (scratchpadDirPath) {
+        const ensured = ensureScratchpadDir(scratchpadDirPath);
+        if (ensured) {
+            scratchpadSectionText = scratchpadSection(ensured);
+        }
+        else {
+            logEvent({
+                source: "scratchpad",
+                level: "error",
+                event: "scratchpad_mkdir_failed",
+                sessionId: env.YAGNI_SESSION_ID ?? undefined,
+            });
+        }
+    }
     // Own the identity + inject live company context (and repo rules) on every
     // turn. The extension loads identically in every pi process this app spawns —
     // the interactive driver AND every `/go` stage child, subagent, and advisor
@@ -617,6 +644,7 @@ export async function registerYagni(pi, deps = {}) {
                         : YAGNI_IDENTITY_DRIVER
                     : undefined,
                 rulesSection,
+                scratchpadSection: scratchpadSectionText,
             }),
         });
     // Turn-lifecycle WAL: a `turn_start` with no matching `turn_end` is the

package/dist/extension/pipeline/personas.js

@@ -56,7 +56,7 @@ Numbered, small, actionable steps — each names the file/function to touch.
 ## Risks
 What to watch for, including any decision the worker will be forced to make.
 
-Finish the job in ONE turn: do not end your turn on an interstitial like "now let me check X". Your FINAL message MUST be the complete plan in the format above (## Goal / ## Plan / ## Files to modify or create / ## Risks). Keep exploring with your tools until you can write the whole plan, then write it as your last message.
+Complete the task fully — do not gold-plate, but do not leave it half-done. Finish the job in ONE turn: do not end your turn on an interstitial like "now let me check X". Your FINAL message MUST be the complete plan in the format above (## Goal / ## Plan / ## Files to modify or create / ## Risks). Keep exploring with your tools until you can write the whole plan, then write it as your last message.
 
 Budget discipline: you have a hard output budget, and a plan that gets cut off mid-thought is worth less than a short plan that ships. Explore only until you can name the files and the steps — do not read broadly for completeness, and do not re-verify what you have already established. Aim for 5-10 short steps; the worker fills small gaps from the ticket. When in doubt, write the plan NOW.
 
@@ -65,7 +65,7 @@ const WORKER_BODY = `You are a worker with full capabilities, operating in an is
 
 You are grounded. Call ask_yagni before guessing about anything organization- or codebase-specific. Treat a confirmed answer as settled; when an answer is an unverified assumption or an inference and your change leans on it, say so in your Notes so the reviewer knows what to check. Critically: for ANY product-intent call you are forced to make that the plan did not settle — a behavior choice, a tradeoff, an interpretation of intent — call record_decision so the company's decision corpus captures it and the next agent inherits the call instead of re-litigating it. When ask_yagni reports no recorded position, follow its instruction and record the assumption you proceed on.
 
-You MUST make the change. If the plan is missing, partial, or appears cut off, do not stop at exploring: implement the ticket directly from the ticket text and the code, calling record_decision for any intent you infer. Ending your turn with no write/edit is a failure.
+Complete the task fully — do not gold-plate, but do not leave it half-done. You MUST make the change. If the plan is missing, partial, or appears cut off, do not stop at exploring: implement the ticket directly from the ticket text and the code, calling record_decision for any intent you infer. Ending your turn with no write/edit is a failure.
 
 Output:
 ## Completed
@@ -242,14 +242,14 @@ Numbered, small, actionable steps — each names the file/function to touch.
 ## Risks
 What to watch for, including any decision the worker will be forced to make.
 
-Finish the job in ONE turn: do not end your turn on an interstitial like "now let me check X". Your FINAL message MUST be the complete plan in the format above (## Goal / ## Plan / ## Files to modify or create / ## Risks). Keep exploring with your tools until you can write the whole plan, then write it as your last message.
+Complete the task fully — do not gold-plate, but do not leave it half-done. Finish the job in ONE turn: do not end your turn on an interstitial like "now let me check X". Your FINAL message MUST be the complete plan in the format above (## Goal / ## Plan / ## Files to modify or create / ## Risks). Keep exploring with your tools until you can write the whole plan, then write it as your last message.
 
 Budget discipline: you have a hard output budget, and a plan that gets cut off mid-thought is worth less than a short plan that ships. Explore only until you can name the files and the steps — do not read broadly for completeness, and do not re-verify what you have already established. Aim for 5-10 short steps; the worker fills small gaps from the ticket. When in doubt, write the plan NOW.
 
 Keep it concrete; the worker executes it verbatim.`;
 const WORKER_BLIND = `You are a worker with full capabilities, operating in an isolated context to implement a plan. Work autonomously and use the tools as needed.
 
-You MUST make the change. If the plan is missing, partial, or appears cut off, do not stop at exploring: implement the ticket directly from the ticket text and the code. Ending your turn with no write/edit is a failure.
+Complete the task fully — do not gold-plate, but do not leave it half-done. You MUST make the change. If the plan is missing, partial, or appears cut off, do not stop at exploring: implement the ticket directly from the ticket text and the code. Ending your turn with no write/edit is a failure.
 
 Output:
 ## Completed

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/extension/scratchpad.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Session scratchpad — a permission-free directory the agent writes its working
+ * state to, so neither it nor the user has to reconstruct intermediate results.
+ *
+ * Ports Claude Code's scratchpad with one deliberate simplification: Claude
+ * resolves the tmp root and normalizes against path traversal because its
+ * scratchpad is an allow-listed path in a permission classifier. We have no
+ * such classifier (auto mode already passes write/edit unprompted, and plan
+ * mode's write gate holds scratchpad like every other write), so the path is
+ * built plainly and the only caller-facing contract is "the dir exists or the
+ * section is omitted."
+ *
+ * Path mirrors Claude Code's shape under our own owner namespace so the two
+ * never collide: <tmp>/yagni-{uid}/<sanitized-cwd>/<sessionId>/scratchpad/.
+ *   - tmp root: YAGNI_CODE_TMPDIR, else os.tmpdir()
+ *   - uid: process.getuid() ?? 0 (multi-user isolation; tmpdir() is already
+ *     per-user on Windows)
+ *   - sanitized-cwd: non-alphanumerics → "-", length-capped (cosmetic grouping
+ *     only — sessionId is the real uniqueness key)
+ *   - sessionId: env.YAGNI_SESSION_ID, minted by the launcher as a UUID; when
+ *     absent (a bare pi run) no scratchpad is configured at all.
+ *
+ * PURE path/section builders are separated from the one impure mkdir so tests
+ * drive the former directly and the latter through an injectable fs seam.
+ */
+/** Env override for the scratchpad tmp root (mirrors CLAUDE_CODE_TMPDIR). */
+export declare const SCRATCHPAD_TMPDIR_ENV = "YAGNI_CODE_TMPDIR";
+/**
+ * PURE: sanitize an absolute cwd into a filename-safe segment. Mirrors Claude
+ * Code's sanitizePath but without the hash suffix — the cwd segment is cosmetic
+ * grouping, not a permission identity, so an identical prefix under two long
+ * cwds is disambiguated by the sessionId one level deeper.
+ */
+export declare function sanitizeCwdSegment(cwd: string): string;
+/**
+ * PURE: the per-user scratchpad owner dir name. uid isolates multi-user systems
+ * the way Claude Code's "claude-{uid}" does, under our own prefix.
+ */
+export declare function scratchpadOwnerDir(uid: number): string;
+/**
+ * PURE: the session scratchpad directory path. Returns null when there is no
+ * sessionId — a scratchpad is meaningless without a per-session key, and the
+ * prompt section is gated on a non-null result.
+ */
+export declare function scratchpadDir(opts?: {
+    sessionId?: string;
+    cwd?: string;
+    uid?: number;
+    tmp?: string;
+}): string | null;
+/**
+ * IMPURE: ensure the scratchpad dir exists (owner-only), failing soft. Returns
+ * the path on success and null on failure — a null result means "no scratchpad
+ * this session", which the caller turns into an omitted prompt section.
+ */
+export declare function ensureScratchpadDir(path: string, mkdir?: (p: string, o: {
+    mode: number;
+    recursive: boolean;
+}) => void): string | null;
+/**
+ * PURE: the prompt section naming the scratchpad. Gated by the caller on the
+ * dir existing; when present, it tells the agent where to put intermediate
+ * files instead of /tmp or the user's project.
+ */
+export declare function scratchpadSection(dir: string): string;
+//# sourceMappingURL=scratchpad.d.ts.map

package/dist/extension/scratchpad.js

@@ -0,0 +1,93 @@
+/**
+ * Session scratchpad — a permission-free directory the agent writes its working
+ * state to, so neither it nor the user has to reconstruct intermediate results.
+ *
+ * Ports Claude Code's scratchpad with one deliberate simplification: Claude
+ * resolves the tmp root and normalizes against path traversal because its
+ * scratchpad is an allow-listed path in a permission classifier. We have no
+ * such classifier (auto mode already passes write/edit unprompted, and plan
+ * mode's write gate holds scratchpad like every other write), so the path is
+ * built plainly and the only caller-facing contract is "the dir exists or the
+ * section is omitted."
+ *
+ * Path mirrors Claude Code's shape under our own owner namespace so the two
+ * never collide: <tmp>/yagni-{uid}/<sanitized-cwd>/<sessionId>/scratchpad/.
+ *   - tmp root: YAGNI_CODE_TMPDIR, else os.tmpdir()
+ *   - uid: process.getuid() ?? 0 (multi-user isolation; tmpdir() is already
+ *     per-user on Windows)
+ *   - sanitized-cwd: non-alphanumerics → "-", length-capped (cosmetic grouping
+ *     only — sessionId is the real uniqueness key)
+ *   - sessionId: env.YAGNI_SESSION_ID, minted by the launcher as a UUID; when
+ *     absent (a bare pi run) no scratchpad is configured at all.
+ *
+ * PURE path/section builders are separated from the one impure mkdir so tests
+ * drive the former directly and the latter through an injectable fs seam.
+ */
+import { mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/** Env override for the scratchpad tmp root (mirrors CLAUDE_CODE_TMPDIR). */
+export const SCRATCHPAD_TMPDIR_ENV = "YAGNI_CODE_TMPDIR";
+/** Longest sanitized-cwd segment we keep; the sessionId carries uniqueness. */
+const MAX_SANITIZED_CWD = 64;
+/**
+ * PURE: sanitize an absolute cwd into a filename-safe segment. Mirrors Claude
+ * Code's sanitizePath but without the hash suffix — the cwd segment is cosmetic
+ * grouping, not a permission identity, so an identical prefix under two long
+ * cwds is disambiguated by the sessionId one level deeper.
+ */
+export function sanitizeCwdSegment(cwd) {
+    const sanitized = cwd.replace(/[^a-zA-Z0-9]/g, "-").replace(/^-+|-+$/g, "");
+    return sanitized.slice(0, MAX_SANITIZED_CWD) || "root";
+}
+/**
+ * PURE: the per-user scratchpad owner dir name. uid isolates multi-user systems
+ * the way Claude Code's "claude-{uid}" does, under our own prefix.
+ */
+export function scratchpadOwnerDir(uid) {
+    return `yagni-${uid}`;
+}
+/**
+ * PURE: the session scratchpad directory path. Returns null when there is no
+ * sessionId — a scratchpad is meaningless without a per-session key, and the
+ * prompt section is gated on a non-null result.
+ */
+export function scratchpadDir(opts = {}) {
+    const sessionId = opts.sessionId?.trim();
+    if (!sessionId)
+        return null;
+    const tmp = opts.tmp ?? tmpdir();
+    const uid = opts.uid ?? (typeof process.getuid === "function" ? process.getuid() ?? 0 : 0);
+    const cwd = sanitizeCwdSegment(opts.cwd ?? ".");
+    return join(tmp, scratchpadOwnerDir(uid), cwd, sessionId, "scratchpad");
+}
+/**
+ * IMPURE: ensure the scratchpad dir exists (owner-only), failing soft. Returns
+ * the path on success and null on failure — a null result means "no scratchpad
+ * this session", which the caller turns into an omitted prompt section.
+ */
+export function ensureScratchpadDir(path, mkdir = mkdirSync) {
+    try {
+        mkdir(path, { recursive: true, mode: 0o700 });
+        return path;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * PURE: the prompt section naming the scratchpad. Gated by the caller on the
+ * dir existing; when present, it tells the agent where to put intermediate
+ * files instead of /tmp or the user's project.
+ */
+export function scratchpadSection(dir) {
+    return ("# Scratchpad directory\n\n" +
+        `Use this session scratchpad directory for files that do not belong in the user's project:\n` +
+        `${dir}\n\n` +
+        "- Store intermediate results or data during multi-step tasks.\n" +
+        "- Write temporary scripts or configuration files.\n" +
+        "- Save outputs that don't belong in the user's project.\n" +
+        "- Anything that would otherwise go to /tmp.\n\n" +
+        "The directory is session-specific and isolated from the user's project.");
+}
+//# sourceMappingURL=scratchpad.js.map

package/dist/extension/subagents.js

@@ -74,7 +74,7 @@ You are grounded in how THIS company works: call ask_yagni before inferring a co
 
 Never fabricate file paths, contents, or findings. If you cannot find something, say so.
 
-Your final message is your report back to the driving agent, which has NOT seen what you read or did. Make it compressed and complete: what you did, what you found, exact file paths and key excerpts, and anything the driver must know before continuing.`;
+Complete the task fully — do not gold-plate, but do not leave it half-done. Your final message is your report back to the driving agent, which has NOT seen what you read or did: make it a concise report of what was done and the key findings, since the caller relays it to the user and it only needs the essentials. Cover what you did, what you found, exact file paths and key excerpts, and anything the driver must know before continuing.`;
 const GENERAL_AGENT = {
     name: GENERAL_AGENT_NAME,
     description: "General-purpose agent for research, multi-file changes, and self-contained tasks.",
@@ -94,6 +94,8 @@ one you actually read with a tool. If you cannot find something, say "not
 found" — a plausible-sounding invention is worse than no answer because the
 driving agent trusts your report.
 
+Complete the task fully — do not gold-plate, but do not leave it half-done.
+
 Your final message is your report back to the driving agent, which has NOT
 seen what you read. Make it compressed and complete: exact file paths, the
 key excerpts, and a one-paragraph map of how the pieces relate. Say what you
@@ -122,6 +124,8 @@ convention, an ownership rule, or anything organization-specific.
 Never fabricate file paths or results. Report what you actually did and what
 you actually found.
 
+Complete the task fully — do not gold-plate, but do not leave it half-done.
+
 Your final message is your report back to the driving agent, which has NOT
 seen what you did. List every file you touched, what changed in each, the
 commands you ran with their outcomes, and anything you deliberately left
@@ -154,6 +158,8 @@ a convention, an ownership rule, or anything organization-specific.
 Never fabricate file paths or findings. If you could not verify something,
 say exactly what you tried and why you could not.
 
+Complete the task fully — do not gold-plate, but do not leave it half-done.
+
 Your final message is your verdict back to the driving agent, which has NOT
 seen what you read. Format:
 ## Verdict

package/dist/extension/todos.d.ts

@@ -105,6 +105,7 @@ export declare function makeTodoTool(get: () => TodoItem[], set: (todos: TodoIte
     label: string;
     description: string;
     promptSnippet: string;
+    promptGuidelines: string[];
     parameters: Type.TObject<{
         todos: Type.TArray<Type.TObject<{
             text: Type.TString;

package/dist/extension/todos.js

@@ -204,6 +204,21 @@ export function makeTodoTool(get, set) {
             "in_progress at a time, mark items completed the moment they are done, and add newly " +
             "discovered steps as pending. Use it for any task with three or more steps, updating as you go.",
         promptSnippet: "todo_write: keep a user-visible checklist for multi-step work (full-list replacement).",
+        promptGuidelines: [
+            "Use todo_write proactively when a task needs 3 or more distinct steps, requires careful " +
+                "planning, or the user gives you a list of things (numbered or comma-separated).",
+            "Capture new instructions as todos the moment you receive them, and mark a step in_progress " +
+                "BEFORE you start working on it.",
+            "When in doubt, use it — a visible checklist answers \"is it stuck?\" without the user having " +
+                "to interrupt.",
+            "Skip it when there is only one straightforward task, the work is trivial, or the request is " +
+                "purely conversational or informational — in those cases just do the task directly.",
+            "Pass the FULL list every call; it replaces the previous one. Keep exactly ONE item in_progress " +
+                "at a time.",
+            "Mark a step completed the moment it is done (do not batch completions), and add newly " +
+                "discovered steps as pending. Only mark a step completed when it is fully done — if tests " +
+                "fail or work is partial, leave it in_progress and add a new step for the blocker.",
+        ],
         parameters,
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             const normalized = normalizeTodos(params.todos);

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.1180.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": "1db89538911e63de0e383aad36bd707e947140d9"
 }