@retasc/cli 1.44.0 → 1.45.0

package/CHANGELOG.md

@@ -6,6 +6,29 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.45.0 (2026-09-08)
+
+- **RTSC-862** — a binding now covers every **git worktree** of the repo it was made in.
+
+  `findBindingByPath` walks up from the current directory looking for a bound folder and
+  stops at the first `.git`, which is what stops `retasc bind` in `~` from silently
+  binding every project beneath it. But `.git` is a FILE at the root of every worktree,
+  so that stop fired on the first step inside one: every worktree resolved to nothing,
+  with no error and no hint, and the tools were simply absent. Repos whose workflow
+  creates a worktree per task (this one included) hit it constantly, and the rational
+  workaround — paste a raw key into a config that works everywhere — silently costs the
+  watchdog, session rows, transcripts and the folder name.
+
+  "Same repository" is decided by git's common dir, the one directory every worktree
+  shares, read from disk rather than by shelling out to git. A sibling repo checked out
+  inside a bound directory still resolves to nothing, so the cross-org property RTSC-91
+  exists for is untouched. Binding a worktree deliberately still wins over its repo's
+  binding.
+
+  `retasc doctor` says when a folder resolved this way, instead of the old warning that
+  the id "was bound at a different folder" — advice which, for a worktree, would have
+  minted a second key and a second agent for one repo.
+
 ## 1.44.0 (2026-09-08)
 
 - **RTSC-861** — the proxy now tells Retasc which CLI version it is. It rides on

package/dist/commands/doctor.js

@@ -1,6 +1,7 @@
 import { loadConfig } from "../config.js";
 import { claudeConfigPath, isNetworkError, readGlobalBinding, readLocalBinding, readShadowedBinding, resolveBinding, sameIdentity, } from "../lib/binding.js";
 import { getBinding } from "../lib/keystore.js";
+import { gitCommonDir } from "../lib/gitRepo.js";
 import { runsOk } from "../lib/launcher.js";
 import { clean } from "../lib/text.js";
 // RTSC-91 (DESIGN §13): `retasc doctor` — confirm THIS folder is correctly and
@@ -150,9 +151,26 @@ export async function doctorAction() {
             // may have reused someone else's id — surface it rather than silently use it.
             const entry = getBinding(local.workspaceId);
             if (entry?.boundPath && entry.boundPath !== cwd) {
-                warn(`this workspace id was bound at a different folder:\n` +
-                    `    ${entry.boundPath}\n` +
-                    `    If you didn't move this repo, re-run \`retasc bind\` to mint a key for THIS folder.`);
+                // RTSC-862 — a WORKTREE of the bound repo is the expected case now, not a
+                // problem, so it must not be reported as one. Before this it read "bound at a
+                // different folder… re-run bind", which is exactly the wrong advice: re-binding
+                // a worktree mints a second key and a second agent for one repo, which is how
+                // people ended up with three.
+                const repo = gitCommonDir(cwd);
+                const sameRepo = !!repo && gitCommonDir(entry.boundPath) === repo;
+                if (sameRepo) {
+                    // Deliberately not "this folder is a worktree of it": the relation is
+                    // symmetric, so that sentence is false when the cwd is the main checkout and
+                    // the BOUND folder is the worktree, which is an ordinary way round.
+                    console.log(`  ℹ same repository as the bound folder:\n` +
+                        `    ${clean(entry.boundPath)}\n` +
+                        `    Worktrees share one binding, so this is expected. Nothing to do.`);
+                }
+                else {
+                    warn(`this workspace id was bound at a different folder:\n` +
+                        `    ${entry.boundPath}\n` +
+                        `    If you didn't move this repo, re-run \`retasc bind\` to mint a key for THIS folder.`);
+                }
             }
         }
         else if (local.legacy) {

package/dist/lib/gitRepo.js

@@ -0,0 +1,141 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+/**
+ * Which repository is this directory part of? (RTSC-862.)
+ *
+ * The answer is git's COMMON DIR — the one directory every worktree of a repository
+ * shares. It is the only thing that makes "the same repo" a decidable question:
+ *
+ *   • normal clone `~/retasc`            → `~/retasc/.git`
+ *   • its worktree `~/retasc-rtsc-862`   → `~/retasc/.git`      (same repo)
+ *   • bare layout `~/retasc/.bare` with
+ *     worktrees `main`, `rtsc-854`       → `~/retasc/.bare`     (same repo)
+ *   • an unrelated clone nested inside   → its own `.git`       (different repo)
+ *
+ * WHY NOT SHELL OUT. `git rev-parse --git-common-dir` answers this directly, and this
+ * function deliberately does not call it. It runs at the start of every proxy session,
+ * which is every MCP server startup in every harness, and spawning a process there
+ * buys a fork+exec on a path whose whole job is to resolve a key in milliseconds. The
+ * on-disk format this reads is stable and documented (gitrepository-layout).
+ *
+ * TRUST MODEL, since this decides which ORG a folder acts in — so a `.git` file is now a
+ * routing input, not merely a stop marker, and it is content that can arrive in an
+ * archive. git refuses to track a path named `.git`, so this cannot come from a clone,
+ * but a tarball, a vendored bundle or a scaffold generator can carry one.
+ *
+ * So a worktree pointer is only believed when it is RECIPROCAL, the way git's own
+ * worktree bookkeeping is: `<common>/worktrees/<name>/gitdir` must point back at the
+ * `.git` file we started from. A hand-written `gitdir:` line at someone else's repository
+ * fails that check and resolves to nothing, where before this it would have claimed that
+ * repository's binding. Verified both ways.
+ *
+ * The check is git's own invariant rather than an invention, so it costs nothing on a
+ * real worktree and cannot drift from what git considers linked. What is deliberately NOT
+ * attempted is out-guessing git in general: if someone can write `.git` into a directory
+ * you work in, they already own your hooks and config there, which is a larger problem
+ * than a binding. The narrow thing we owe is never to resolve ACROSS repositories git
+ * considers distinct — which is also why submodules, whose gitdirs carry no `commondir`,
+ * resolve to themselves.
+ *
+ * NEVER THROWS. A malformed `.git` file, a dangling gitdir, a permissions error: all
+ * return undefined. Resolution failing means "no binding found", which the caller
+ * already handles; a startup crash in the proxy takes the agent's tools away entirely,
+ * which is far worse than a folder that needs `retasc bind` run again.
+ */
+export function gitCommonDir(dir) {
+    try {
+        const dotGit = join(dir, ".git");
+        if (!existsSync(dotGit))
+            return undefined;
+        // A normal clone: `.git` is a directory and IS the common dir. A worktree's private
+        // gitdir is also a directory and looks identical from here, which is what the
+        // `commondir` probe below distinguishes — git writes that file only in the private
+        // one. `GIT_DIR` pointed at a worktree gitdir lands here too.
+        if (statSync(dotGit).isDirectory())
+            return followCommonDir(dotGit);
+        // A worktree: `.git` is a FILE holding `gitdir: <path to the private gitdir>`.
+        // FIRST line only, as real git reads it — an `m` flag here would accept the pointer
+        // anywhere in the file, widening what an archive can smuggle in.
+        const first = readFileSync(dotGit, "utf8").split(/\r?\n/, 1)[0];
+        const m = /^gitdir:\s*(.+?)\s*$/.exec(first);
+        if (!m)
+            return undefined;
+        const gitdir = isAbsolute(m[1]) ? m[1] : resolve(dir, m[1]);
+        if (!existsSync(gitdir))
+            return undefined; // dangling: the worktree was pruned
+        if (!pointsBackAt(gitdir, dotGit))
+            return undefined;
+        return followCommonDir(gitdir);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Does this private gitdir agree that it belongs to this worktree?
+ *
+ * git keeps the link in both directions: the worktree's `.git` file names the private
+ * gitdir, and `<gitdir>/gitdir` names the worktree's `.git` file back. Only the first
+ * direction is writable by whoever plants a folder, so checking the second is what turns
+ * "a file claims to belong to your repo" into "your repo agrees".
+ *
+ * A gitdir with no `gitdir` file is not a worktree's — a submodule's private dir, or the
+ * bare/main directory reached some other way — so this returns false and the caller
+ * resolves nothing, which is the safe direction.
+ */
+function pointsBackAt(gitdir, dotGitFile) {
+    try {
+        const back = join(gitdir, "gitdir");
+        if (!existsSync(back))
+            return false;
+        const claimed = readFileSync(back, "utf8").trim();
+        if (!claimed)
+            return false;
+        return realish(claimed) === realish(dotGitFile);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve a gitdir to the repository's common dir.
+ *
+ * A worktree's private gitdir carries a `commondir` file (usually `../..`) pointing at
+ * the shared one. A main `.git` has no such file and is already the common dir. Reading
+ * the file rather than assuming `../..` is what makes the bare layout work, where the
+ * shared directory is `.bare` rather than `.git`.
+ */
+function followCommonDir(gitdir) {
+    const marker = join(gitdir, "commondir");
+    if (!existsSync(marker))
+        return realish(gitdir);
+    const rel = readFileSync(marker, "utf8").trim();
+    if (!rel)
+        return realish(gitdir);
+    return realish(isAbsolute(rel) ? rel : resolve(gitdir, rel));
+}
+/**
+ * Resolve a path the same way `gitCommonDir` resolves the ones it returns.
+ *
+ * Exported because comparing an unresolved path against a resolved one is a silent
+ * mismatch on macOS, where `/var` is a symlink to `/private/var` and a temp dir spells
+ * itself both ways. Anything compared against this module's output comes through here.
+ */
+export function realPath(p) {
+    return realish(p);
+}
+/**
+ * Resolve for comparison. `realpathSync` matters on macOS, where `/tmp` is a symlink to
+ * `/private/tmp` and two spellings of one directory would otherwise never match — the
+ * same reason `findBindingByPath` resolves both sides before comparing.
+ */
+function realish(p) {
+    try {
+        return realpathSync(resolve(p));
+    }
+    catch {
+        // A path that does not exist cannot be realpath'd. Comparing the lexical form is
+        // still better than giving up, and the callers only ever compare two of these.
+        return resolve(p);
+    }
+}

package/dist/lib/keystore.js

@@ -2,6 +2,7 @@ import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { mkdirSync, readFileSync, writeFileSync, existsSync, chmodSync } from "node:fs";
 import { randomUUID } from "node:crypto";
+import { gitCommonDir, realPath } from "./gitRepo.js";
 /** The dir the keystore lives in. RETASC_DIR overrides it (tests, sandboxes). */
 function keystoreDir() {
     return process.env.RETASC_DIR || join(homedir(), ".retasc");
@@ -119,12 +120,74 @@ export function findBindingByPath(dir) {
         // Checked AFTER the lookup so the repo root itself, the folder `bind` actually
         // writes, is always eligible.
         if (existsSync(join(cur, ".git")))
-            return undefined;
+            break;
         const up = dirname(cur);
         if (up === cur)
             return undefined;
         cur = up;
     }
+    // RTSC-862 — the walk stopped at a repository root that is not itself bound. Before
+    // giving up, ask the question a person actually means: is this a WORKTREE of a repo
+    // they already bound?
+    //
+    // The stop above is correct and stays. An unbounded walk would let `retasc bind` in
+    // `~` silently bind every project beneath it, which is the cross-org leak RTSC-91
+    // exists to prevent. But `.git` is a FILE at the root of every git worktree, so that
+    // same stop fires on the first step inside one — and this repo's own workflow mandates
+    // a worktree per claimed issue, created as a SIBLING of the checkout. Every one of them
+    // resolved to nothing, with no error and no hint: the tools were simply absent. The
+    // rational response is to paste a raw key into a config that works everywhere, and that
+    // silently costs the watchdog, session rows, transcripts and the folder name.
+    //
+    // "Same repository" is decided by git's COMMON DIR, the one directory every worktree of
+    // a repo shares, so a sibling repo checked out inside a bound directory still resolves
+    // to nothing — different common dir. RTSC-91's property is untouched.
+    //
+    // A path match always wins, because this runs only after the walk found none: a
+    // worktree that is ITSELF bound keeps its own binding.
+    const here = gitCommonDir(cur);
+    if (!here)
+        return undefined;
+    // Memoized because this probes OTHER bindings' folders, not just our own, and it runs
+    // at every proxy start in every folder a harness opens. One `boundPath` on a stale
+    // network mount would otherwise be stat'd repeatedly while it blocks on the mount
+    // timeout. Two bindings in one repo is the common case, so the cache earns its keep.
+    const repoOf = new Map();
+    const commonDirOf = (p) => {
+        if (!repoOf.has(p))
+            repoOf.set(p, gitCommonDir(p));
+        return repoOf.get(p);
+    };
+    let best;
+    for (const hit of byPath.values()) {
+        // Cheap rejection first: a binding that cannot beat the current best on recency
+        // never needs its folder touched at all.
+        if (best && (hit.entry.createdAt ?? 0) <= (best.entry.createdAt ?? 0))
+            continue;
+        // Realpath'd, because `here` is: comparing a resolved path against an unresolved
+        // one silently never matches on macOS (`/var` vs `/private/var`).
+        const bound = realPath(hit.entry.boundPath);
+        // Same repository, the ordinary case: the bound folder is a worktree (or the main
+        // checkout) of this one.
+        let match = commonDirOf(bound) === here;
+        // Or the bound folder is the one that DIRECTLY CONTAINS this repository's git dir.
+        // That is the bare layout — `~/proj/.bare` beside `~/proj/main` — where the folder a
+        // person opens and binds, `~/proj`, is not itself a git repo and so has no common
+        // dir of its own. Without this, binding the folder they actually look at does
+        // nothing and they get the same silent no-tools symptom this issue is about.
+        //
+        // DIRECT parent, never an ancestor. `dirname("~/proj/.bare") === "~/proj"` matches,
+        // while binding `~` and hoping to catch `~/proj/.git` does not — which is the whole
+        // point, because that is RTSC-91's cross-org leak.
+        if (!match)
+            match = dirname(here) === bound;
+        if (!match)
+            continue;
+        // Newest wins, the tie-break `byPath` already uses: a folder bound, unbound and
+        // bound again leaves an older entry behind, and the fresher one is live.
+        best = hit;
+    }
+    return best;
 }
 /**
  * RTSC-98: the ONE place that resolves a workspace's key + MCP url. Shared by the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.44.0",
+  "version": "1.45.0",
   "description": "Retasc CLI — the issue tracker AI agents pull work from. Sign in with GitHub or Google, create projects, mint agent API keys, and wire your agent to the Retasc MCP server in one command.",
   "type": "module",
   "bin": {