@yagni-app/code 1.0.0 → 1.0.2

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

@@ -32,6 +32,7 @@ export interface RunStageDeps {
     resolveChild?: () => {
         piCli: string;
         extensionPath: string;
+        otelExtensionPath?: string;
     };
     /** Optional environment for spawned child stages. Defaults to Node's inherited env. */
     env?: NodeJS.ProcessEnv;

package/dist/extension/pipeline/runner.js

@@ -61,11 +61,19 @@ async function defaultWritePrompt(body) {
 /**
  * Default child resolution: the parent process IS pi (so `process.argv[1]` is
  * pi's cli), and our compiled extension entry sits one dir up from this module.
+ *
+ * `otelExtensionPath` comes from `YAGNI_OTEL_EXTENSION_PATH`, set by the
+ * launcher only when an OTLP endpoint is configured (see the CLI's otel.ts) —
+ * children then load pi-otel so their LLM spend is traced. Guarded with
+ * existsSync so a stale env value degrades to an untraced child, never a
+ * child that fails to boot.
  */
 function defaultResolveChild() {
     const piCli = process.argv[1] ?? "pi";
     const extensionPath = fileURLToPath(new URL("../index.js", import.meta.url));
-    return { piCli, extensionPath };
+    const otelPath = process.env.YAGNI_OTEL_EXTENSION_PATH;
+    const otelExtensionPath = otelPath && fs.existsSync(otelPath) ? otelPath : undefined;
+    return { piCli, extensionPath, ...(otelExtensionPath ? { otelExtensionPath } : {}) };
 }
 const EMPTY_USAGE = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
 /** Truncate to PER_TASK_OUTPUT_CAP bytes, never exceeding the cap. */
@@ -116,8 +124,12 @@ export async function runStage(stage, ctx, deps) {
             lens: ctx.lens,
             ...(tierCap ? { tierCap } : {}),
         });
-        const { piCli, extensionPath } = resolveChild();
-        const argv = groundedChildArgv(passthrough, { piCli, extensionPath });
+        const { piCli, extensionPath, otelExtensionPath } = resolveChild();
+        const argv = groundedChildArgv(passthrough, {
+            piCli,
+            extensionPath,
+            ...(otelExtensionPath ? { otelExtensionPath } : {}),
+        });
         // Fold events into a fixed-size accumulator as they stream — never retain
         // the full array (that OOMs on a verbose stage; YAG-317 follow-up).
         const acc = newEventAccumulator();

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

@@ -0,0 +1,30 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+/**
+ * Slash-command filtering for the CLI.
+ *
+ * pi ships its own built-in slash commands (see `BUILTIN_SLASH_COMMANDS` in
+ * pi's `core/slash-commands.js`) and bakes them directly into its interactive
+ * autocomplete provider (`createBaseAutocompleteProvider`). Most are
+ * pi-generic and harmless (`/new`, `/compact`, `/settings`), but a subset
+ * contradict YAGNI's single-provider, single-identity model — or leak pi
+ * features YAGNI deliberately does not surface — and only confuse a YAGNI Code
+ * user. We hide those from slash-discovery.
+ *
+ * Scope note: this filters DISCOVERY only. pi dispatches built-in commands in
+ * its own private `onSubmit` chain (not from the autocomplete list), so a
+ * hidden command can still be typed by hand — the same bar pi itself draws for
+ * its easter-egg commands, which are also absent from autocomplete. Removing
+ * them from the list is the whole intent: a YAGNI user should not be offered
+ * `/share` (ships a transcript to a GitHub gist) or `/login <provider>` (pi
+ * provider auth) when YAGNI's model is a single `yagni` provider.
+ *
+ * The desktop palette is unaffected: pi's RPC `get_commands` (which the desktop
+ * app reads) already returns extension commands + prompt templates + skills and
+ * never includes built-ins. This wrapper is inert outside interactive TUI mode,
+ * where `addAutocompleteProvider` is handed a no-op factory.
+ */
+/** pi built-in slash commands hidden from YAGNI Code autocomplete. */
+export declare const HIDDEN_BUILTIN_SLASH_COMMANDS: readonly string[];
+/** Register the slash-command filter on `session_start` (TUI autocomplete only). */
+export declare function registerSlashCommandFilter(pi: ExtensionAPI): void;
+//# sourceMappingURL=slashCommandFilter.d.ts.map

package/dist/extension/slashCommandFilter.js

@@ -0,0 +1,89 @@
+/**
+ * Slash-command filtering for the CLI.
+ *
+ * pi ships its own built-in slash commands (see `BUILTIN_SLASH_COMMANDS` in
+ * pi's `core/slash-commands.js`) and bakes them directly into its interactive
+ * autocomplete provider (`createBaseAutocompleteProvider`). Most are
+ * pi-generic and harmless (`/new`, `/compact`, `/settings`), but a subset
+ * contradict YAGNI's single-provider, single-identity model — or leak pi
+ * features YAGNI deliberately does not surface — and only confuse a YAGNI Code
+ * user. We hide those from slash-discovery.
+ *
+ * Scope note: this filters DISCOVERY only. pi dispatches built-in commands in
+ * its own private `onSubmit` chain (not from the autocomplete list), so a
+ * hidden command can still be typed by hand — the same bar pi itself draws for
+ * its easter-egg commands, which are also absent from autocomplete. Removing
+ * them from the list is the whole intent: a YAGNI user should not be offered
+ * `/share` (ships a transcript to a GitHub gist) or `/login <provider>` (pi
+ * provider auth) when YAGNI's model is a single `yagni` provider.
+ *
+ * The desktop palette is unaffected: pi's RPC `get_commands` (which the desktop
+ * app reads) already returns extension commands + prompt templates + skills and
+ * never includes built-ins. This wrapper is inert outside interactive TUI mode,
+ * where `addAutocompleteProvider` is handed a no-op factory.
+ */
+/** pi built-in slash commands hidden from YAGNI Code autocomplete. */
+export const HIDDEN_BUILTIN_SLASH_COMMANDS = [
+    "share", // ships a session transcript to a secret GitHub gist (off-brand + privacy footgun)
+    "login", // pi provider auth; YAGNI auth is `yagni login`, one provider
+    "logout", // pi provider auth; YAGNI auth is `yagni logout`
+    "scoped-models", // pi multi-model Ctrl+P cycling; YAGNI pins a single tier
+    "fork", // pi session-fork feature YAGNI never surfaces
+    "clone", // pi session-clone feature YAGNI never surfaces
+    "tree", // pi session-tree feature YAGNI never surfaces
+    "trust", // pi project-trust prompt; collides with YAGNI guardrails
+    "changelog", // pi's own changelog, not YAGNI's
+];
+const HIDDEN = new Set(HIDDEN_BUILTIN_SLASH_COMMANDS);
+/**
+ * True when the text before the cursor is a slash-COMMAND name being typed —
+ * a leading `/` plus a name with no interior `/` or space. This mirrors pi's
+ * own slash-command detection (its `applyCompletion` treats a prefix with an
+ * interior `/` as a file path, e.g. the absolute path `/usr/local/...`), so we
+ * never strip a legitimate file-named completion.
+ */
+function isSlashCommandName(textBeforeCursor) {
+    return textBeforeCursor.startsWith("/")
+        && !textBeforeCursor.slice(1).includes("/")
+        && !textBeforeCursor.slice(1).includes(" ");
+}
+function filterHiddenSlashSuggestions(suggestions) {
+    const items = suggestions.items.filter((item) => !HIDDEN.has(item.value));
+    if (items.length === 0)
+        return null;
+    return { ...suggestions, items };
+}
+/** Wrap pi's built-in autocomplete provider so hidden built-ins never complete. */
+function makeYagniAutocompleteProvider(current) {
+    return {
+        triggerCharacters: current.triggerCharacters,
+        async getSuggestions(lines, cursorLine, cursorCol, options) {
+            const textBeforeCursor = (lines[cursorLine] ?? "").slice(0, cursorCol);
+            if (!isSlashCommandName(textBeforeCursor)) {
+                return current.getSuggestions(lines, cursorLine, cursorCol, options);
+            }
+            const suggestions = await current.getSuggestions(lines, cursorLine, cursorCol, options);
+            return suggestions ? filterHiddenSlashSuggestions(suggestions) : null;
+        },
+        applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+            return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+        },
+        shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
+            return current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true;
+        },
+    };
+}
+/** Register the slash-command filter on `session_start` (TUI autocomplete only). */
+export function registerSlashCommandFilter(pi) {
+    pi.on("session_start", (_event, ctx) => {
+        if (ctx.mode !== "tui" || !ctx.hasUI)
+            return;
+        try {
+            ctx.ui.addAutocompleteProvider(makeYagniAutocompleteProvider);
+        }
+        catch {
+            // Filtering is cosmetic; a failure must never break session start.
+        }
+    });
+}
+//# sourceMappingURL=slashCommandFilter.js.map