mintree 0.5.9 → 0.5.12

package/README.md

@@ -161,6 +161,29 @@ Three top-level keys in `.mintree/metadata.json` tune how mintree launches Claud
 
   When omitted, mintree uses a built-in default that asks Claude to orchestrate the selected tickets with minimal intervention — parallelising via subagents unless dependencies force sequential work, creating a worktree per ticket with mintree, using the repo's skills, and moving each ticket to *in progress* on start and closing it when done.
 
+### Linking gitignored files into worktrees (optional)
+
+Git worktrees don't share **untracked** files: a new worktree is a fresh working directory, so gitignored config like `.env` lives only in your main checkout and is **absent** in every worktree mintree creates. That breaks per-worktree tooling that needs it — e.g. running an E2E suite that reads `.env` for staging credentials.
+
+The `linkFiles` top-level key (valid on GitHub and Linear repos) lists repo-root-relative paths that mintree **symlinks** into each new worktree, right after creating it:
+
+```json
+{
+  "version": 1,
+  "provider": "linear",
+  "issues": {},
+  "linkFiles": [".env"],
+  "linear": { "workspaceSlug": "my-team", "teams": [{ "key": "FE" }] }
+}
+```
+
+- **Symlink, not copy** — one source of truth. Rotate a credential in the main `.env` and every worktree sees it; no re-copying. `worktree remove` deletes the link, never the original file.
+- **Best-effort, never fatal** — an entry that doesn't exist in the repo root is skipped, and so is one whose target is already present in the worktree (e.g. a tracked file). Both show up as `skip` steps in the create log.
+- **Runs before `.mintree/init.sh`** — so the post-create hook (if any) can rely on the linked files being there.
+- **Sandboxed paths** — entries must be repo-root-relative; absolute paths and `..` escapes are dropped on read, so a stray `metadata.json` can't make mintree link something outside the worktree.
+
+This applies to `worktree create` (CLI), the dashboard `w` overlay, and the detached-worktree flow alike. For more involved per-worktree setup (installing deps, copying templated files), use `.mintree/init.sh` instead — see [What gets stored where](#what-gets-stored-where).
+
 ---
 
 ## Daily flow
@@ -276,7 +299,7 @@ The worktree directory is still the **bare, upper-case issue id** (`VAL-68`) reg
     │   └── FE-123/               # Linear form: <TEAM-digits>
     ├── session-states/           # gitignored
     │   └── 100.json              # live state written by Claude hooks (active/waiting/idle/exited)
-    └── init.sh                   # opt-in. Runs in the new worktree post-create (copy .env, install deps, …)
+    └── init.sh                   # opt-in. Runs in the new worktree post-create (install deps, scaffold, …)
 ```
 
 The worktree directory is named after the bare issue id (`100`, `FE-123`, `VAL-68`); the branch keeps its full name — `<type>/<issue>-<desc>` for the convention, or Linear's own `<user>/<team>-<n>-<desc>` on Linear repos.
@@ -292,7 +315,7 @@ Linear authentication lives in `~/.mintree/credentials.json` (user-scoped, not p
 - **Sessions persist by issue**: each issue gets a UUID stored in `metadata.json`. Subsequent `worktree work` calls pass `--resume <uuid>` so Claude reopens the same conversation.
 - **Live state** (optional): the four hooks installed by `mintree helpers session-signal install` write the current Claude state to `.mintree/session-states/<issue>.json` on every prompt / stop / notification / session-end. The dashboard reads those files to colour each row in real time.
 - **Remote Control** (optional): `mintree doctor` checks `~/.claude.json` for `remoteControlAtStartup: true`. Enabling it lets you continue a local session from a different device.
-- **iTerm2 tab title** (automatic): when you launch on [iTerm2](https://iterm2.com), mintree sets the **tab title** to the session name (the worktree issue id like `VAL-68`, or the orchestrator's name) so each tab stays identifiable at a glance. It sets the tab title via OSC 1 (icon name) rather than the window title, because Claude Code rewrites the window title with a descriptive summary while it runs; the icon-name slot is independent of it. The title clears on exit. No-op on other terminals (detected via `TERM_PROGRAM` / `LC_TERMINAL`).
+- **iTerm2 session badge** (automatic): when you launch on [iTerm2](https://iterm2.com), mintree sets the terminal **badge** — the large translucent label drawn over the session — to the session name (the worktree issue id like `VAL-68`, or the orchestrator's name) so each tab stays identifiable at a glance. It uses the badge rather than the tab title because Claude Code overwrites the title while it runs; the badge is independent of it and persists for the whole session, then clears on exit. No-op on other terminals (detected via `TERM_PROGRAM` / `LC_TERMINAL`).
 
 ---
 

package/dist/lib/claude.js

@@ -2,7 +2,7 @@ import { execSync, spawn } from "child_process";
 import { existsSync, writeFileSync } from "fs";
 import { homedir, tmpdir } from "os";
 import { join } from "path";
-import { setITermTabTitle, clearITermTabTitle } from "./terminal.js";
+import { setITermBadge, clearITermBadge } from "./terminal.js";
 export const PERMISSION_MODES = ["default", "auto"];
 /**
  * Resolves the absolute path of the Claude Code CLI binary, or null if not on
@@ -75,17 +75,17 @@ export function launchClaude(options) {
     if (options.prompt && options.prompt.length > 0) {
         args.push("--", promptArg(options.prompt));
     }
-    // Label the session via the iTerm2 tab title before handing over the TTY.
-    // We use OSC 1 (icon name), a slot separate from the window title Claude
-    // rewrites, so the tab stays identifiable (worktree issue id, or
-    // orchestrator name) while it runs. No-op outside iTerm2.
-    const tabTitle = options.remoteControlName;
-    if (tabTitle)
-        setITermTabTitle(tabTitle);
+    // Label the session with an iTerm2 badge before handing over the TTY. The
+    // badge survives Claude overwriting the terminal title, so the tab stays
+    // identifiable (worktree issue id, or orchestrator name) while it runs.
+    // No-op outside iTerm2.
+    const badge = options.remoteControlName;
+    if (badge)
+        setITermBadge(badge);
     const child = spawn(bin, args, { stdio: "inherit", cwd: options.cwd });
-    // Clear the tab title once Claude exits so it doesn't linger on the shell
-    // that regains the TTY.
-    if (tabTitle)
-        child.on("exit", () => clearITermTabTitle());
+    // Clear the badge once Claude exits so the badge doesn't linger on the
+    // shell that regains the TTY.
+    if (badge)
+        child.on("exit", () => clearITermBadge());
     return child;
 }

package/dist/lib/metadata.d.ts

@@ -30,6 +30,7 @@ export type Metadata = {
     defaultPermissionMode?: PermissionMode;
     promptTemplate?: string;
     orchestratorPromptTemplate?: string;
+    linkFiles?: string[];
 };
 export declare function readMetadata(repoRoot: string): Metadata;
 export declare function writeMetadata(repoRoot: string, data: Metadata): void;

package/dist/lib/metadata.js

@@ -1,4 +1,5 @@
 import * as fs from "fs";
+import * as path from "path";
 import { getMetadataPath } from "./git.js";
 import { PERMISSION_MODES } from "./claude.js";
 const EMPTY = { version: 1, issues: {} };
@@ -16,6 +17,36 @@ function sanitizePromptTemplate(raw) {
 function sanitizeOrchestratorPromptTemplate(raw) {
     return typeof raw === "string" && raw.trim().length > 0 ? raw : undefined;
 }
+/**
+ * Keeps only safe, repo-root-relative paths. Drops non-strings, blanks,
+ * absolute paths and any entry that escapes the repo root via `..` — a
+ * malicious / fat-fingered `metadata.json` must never make mintree symlink
+ * something outside the worktree. Normalises and de-dupes the survivors.
+ */
+function sanitizeLinkFiles(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const out = [];
+    const seen = new Set();
+    for (const v of raw) {
+        if (typeof v !== "string")
+            continue;
+        const trimmed = v.trim();
+        if (trimmed.length === 0 || path.isAbsolute(trimmed))
+            continue;
+        const norm = path.normalize(trimmed);
+        if (norm === ".." ||
+            norm.startsWith(`..${path.sep}`) ||
+            norm.includes(`${path.sep}..${path.sep}`)) {
+            continue;
+        }
+        if (seen.has(norm))
+            continue;
+        seen.add(norm);
+        out.push(norm);
+    }
+    return out.length > 0 ? out : undefined;
+}
 function sanitizeLinearTeam(raw) {
     if (typeof raw !== "object" || raw === null)
         return undefined;
@@ -90,6 +121,7 @@ export function readMetadata(repoRoot) {
         const defaultPermissionMode = sanitizePermissionMode(parsed.defaultPermissionMode);
         const promptTemplate = sanitizePromptTemplate(parsed.promptTemplate);
         const orchestratorPromptTemplate = sanitizeOrchestratorPromptTemplate(parsed.orchestratorPromptTemplate);
+        const linkFiles = sanitizeLinkFiles(parsed.linkFiles);
         return {
             version: 1,
             issues: typeof parsed.issues === "object" && parsed.issues !== null
@@ -101,6 +133,7 @@ export function readMetadata(repoRoot) {
             ...(defaultPermissionMode ? { defaultPermissionMode } : {}),
             ...(promptTemplate ? { promptTemplate } : {}),
             ...(orchestratorPromptTemplate ? { orchestratorPromptTemplate } : {}),
+            ...(linkFiles ? { linkFiles } : {}),
         };
     }
     catch {

package/dist/lib/terminal.d.ts

@@ -1,12 +1,13 @@
 /** True when the active terminal is iTerm2 (also detected through tmux). */
 export declare function isITerm(): boolean;
 /**
- * Builds the raw OSC 1 (set icon name) escape sequence for `text`. Pure (no I/O)
- * so it can be unit-tested; an empty string clears the tab title, letting
- * iTerm2 fall back to its default.
+ * Builds the raw iTerm2 SetBadgeFormat escape sequence for `text`. Pure (no I/O)
+ * so it can be unit-tested; an empty string clears the badge. The badge format
+ * supports `\(...)` interpolation in iTerm2, but plain ids/labels carry no
+ * parens so the base64-encoded literal renders verbatim.
  */
-export declare function buildTabTitleSequence(text: string): string;
-/** Sets the iTerm2 tab title to `text`. No-op outside iTerm2 or with empty text. */
-export declare function setITermTabTitle(text: string): void;
-/** Clears the iTerm2 tab title. No-op outside iTerm2. */
-export declare function clearITermTabTitle(): void;
+export declare function buildBadgeSequence(text: string): string;
+/** Sets the iTerm2 badge to `text`. No-op outside iTerm2 or with empty text. */
+export declare function setITermBadge(text: string): void;
+/** Clears the iTerm2 badge. No-op outside iTerm2. */
+export declare function clearITermBadge(): void;

package/dist/lib/terminal.js

@@ -1,15 +1,11 @@
-// iTerm2 tab-title integration.
+// iTerm2 badge integration.
 //
-// We label each mintree session with the iTerm2 *tab title* (the small text in
-// the tab bar) so a session is identifiable at a glance — e.g. the worktree
-// issue id `VAL-68`, or `orchestrator-VAL-12_BE-16`.
-//
-// We use OSC 1 (set icon name) rather than OSC 2 (window title): Claude Code
-// rewrites the window title with a descriptive summary while it runs, but the
-// icon name / tab title is a separate slot it leaves alone. An earlier version
-// used the iTerm2 badge instead, but the badge font scales to fill a
-// profile-controlled box and rendered enormous for short labels, with no
-// per-session escape to shrink it. The tab title is small and unobtrusive.
+// Claude Code overwrites the terminal title (OSC 0/2) while it runs and exposes
+// no way to disable that or pin a custom title, so a tab title we set before
+// launching wouldn't survive. The iTerm2 *badge* — a large translucent label
+// drawn over the session — is independent of the title and Claude never touches
+// it, so it's the one reliable way to identify a mintree session at a glance
+// (e.g. the worktree issue id `VAL-68`, or `orchestrator-VAL-12_BE-16`).
 //
 // Everything here is a no-op outside iTerm2, so callers can invoke it
 // unconditionally.
@@ -29,12 +25,14 @@ function wrapForTmux(seq) {
     return `${ESC}Ptmux;${doubled}${ESC}\\`;
 }
 /**
- * Builds the raw OSC 1 (set icon name) escape sequence for `text`. Pure (no I/O)
- * so it can be unit-tested; an empty string clears the tab title, letting
- * iTerm2 fall back to its default.
+ * Builds the raw iTerm2 SetBadgeFormat escape sequence for `text`. Pure (no I/O)
+ * so it can be unit-tested; an empty string clears the badge. The badge format
+ * supports `\(...)` interpolation in iTerm2, but plain ids/labels carry no
+ * parens so the base64-encoded literal renders verbatim.
  */
-export function buildTabTitleSequence(text) {
-    return wrapForTmux(`${ESC}]1;${text}${BEL}`);
+export function buildBadgeSequence(text) {
+    const b64 = Buffer.from(text, "utf8").toString("base64");
+    return wrapForTmux(`${ESC}]1337;SetBadgeFormat=${b64}${BEL}`);
 }
 function writeToTty(seq) {
     // We only call this right before spawning Claude / right after it exits,
@@ -43,15 +41,15 @@ function writeToTty(seq) {
     if (process.stdout.isTTY)
         process.stdout.write(seq);
 }
-/** Sets the iTerm2 tab title to `text`. No-op outside iTerm2 or with empty text. */
-export function setITermTabTitle(text) {
+/** Sets the iTerm2 badge to `text`. No-op outside iTerm2 or with empty text. */
+export function setITermBadge(text) {
     if (!isITerm() || !text)
         return;
-    writeToTty(buildTabTitleSequence(text));
+    writeToTty(buildBadgeSequence(text));
 }
-/** Clears the iTerm2 tab title. No-op outside iTerm2. */
-export function clearITermTabTitle() {
+/** Clears the iTerm2 badge. No-op outside iTerm2. */
+export function clearITermBadge() {
     if (!isITerm())
         return;
-    writeToTty(buildTabTitleSequence(""));
+    writeToTty(buildBadgeSequence(""));
 }

package/dist/lib/worktreeCreate.js

@@ -49,6 +49,59 @@ function tryRunInitScript(scriptPath, worktreePath, repoRoot) {
         };
     }
 }
+/**
+ * Symlinks each `metadata.linkFiles` entry from the main repo into the freshly
+ * created worktree. Git worktrees don't share untracked files, so gitignored
+ * config like `.env` is absent in a new worktree; this links it in so the
+ * worktree's tooling finds the same secrets/config as the main checkout.
+ *
+ * A symlink (not a copy) keeps a single source of truth — rotating a credential
+ * in the main `.env` is seen by every worktree, and `worktree remove` deletes
+ * only the link. Entries are repo-root-relative (already validated by
+ * `sanitizeLinkFiles`). Each entry is best-effort: a missing source or an
+ * already-present target is skipped, never fatal.
+ */
+function linkFilesIntoWorktree(repoRoot, worktreePath, linkFiles, pushStep) {
+    for (const rel of linkFiles) {
+        const source = path.join(repoRoot, rel);
+        const target = path.join(worktreePath, rel);
+        if (!pathExists(source)) {
+            pushStep({ kind: "skip", label: `skipped link ${rel}`, detail: "not present in repo root" });
+            continue;
+        }
+        // lstat (not pathExists) so an existing symlink/file/dir already at the
+        // target — e.g. a tracked file git checked out — counts as present and
+        // we don't clobber it.
+        let targetTaken = false;
+        try {
+            fs.lstatSync(target);
+            targetTaken = true;
+        }
+        catch {
+            targetTaken = false;
+        }
+        if (targetTaken) {
+            pushStep({
+                kind: "skip",
+                label: `skipped link ${rel}`,
+                detail: "already present in worktree",
+            });
+            continue;
+        }
+        try {
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            fs.symlinkSync(source, target);
+            pushStep({ kind: "ok", label: `linked ${rel}`, detail: `→ ${source}` });
+        }
+        catch (err) {
+            pushStep({
+                kind: "warn",
+                label: `failed to link ${rel}`,
+                detail: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+}
 /**
  * Stashes a `--prompt` value into a temp file so the shell wrapper can hand
  * it back to `worktree work` via `--prompt-file`. Plain stdout markers can't
@@ -207,6 +260,13 @@ export async function runCreate(branchArg, opts) {
     upsertIssue(root, parsed.issueId, base ? { base_branch: base } : {});
     pushStep({ kind: "ok", label: "metadata updated", detail: `issue ${parsed.issueId}` });
     await nextFrame(progress);
+    // Link gitignored config (e.g. .env) before init.sh, so the hook can rely
+    // on those files being present.
+    const linkFiles = readMetadata(root).linkFiles;
+    if (linkFiles && linkFiles.length > 0) {
+        linkFilesIntoWorktree(root, worktreePath, linkFiles, pushStep);
+        await nextFrame(progress);
+    }
     const initShPath = getInitScriptPath(root);
     if (pathExists(initShPath)) {
         progress?.onPending?.("Running .mintree/init.sh...");
@@ -362,6 +422,13 @@ export async function runCreateDetached(opts) {
     upsertIssue(root, opts.issueId, { base_branch: currentBranch });
     pushStep({ kind: "ok", label: "metadata updated", detail: `issue ${opts.issueId}` });
     await nextFrame(progress);
+    // Link gitignored config (e.g. .env) before init.sh, so the hook can rely
+    // on those files being present.
+    const linkFiles = readMetadata(root).linkFiles;
+    if (linkFiles && linkFiles.length > 0) {
+        linkFilesIntoWorktree(root, worktreePath, linkFiles, pushStep);
+        await nextFrame(progress);
+    }
     const initShPath = getInitScriptPath(root);
     if (pathExists(initShPath)) {
         progress?.onPending?.("Running .mintree/init.sh...");

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mintree",
-	"version": "0.5.9",
+	"version": "0.5.12",
 	"description": "Issue-driven git worktrees + Claude Code sessions for repos with an opinionated SDD+TDD flow.",
 	"license": "MIT",
 	"author": "Martin Mineo <mmineo@canarytechnologies.com>",