@retasc/cli 1.44.0 → 1.46.0

package/CHANGELOG.md

@@ -6,6 +6,54 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.46.0 (2026-09-08)
+
+- **RTSC-855** — `retasc doctor` and `retasc setup` now say whether the **Retasc Agent
+  Skill** is installed on this machine, and print the one command that installs it.
+
+  Wiring the MCP server gives an agent the ability to claim work. The skill is what tells
+  it what a lease is, that a claim needs its own worktree, what a checkpoint is for, and
+  how a handoff into review works. Nothing connected the two, so an agent could be fully
+  wired and still have the tools without the manual, and no surface anywhere would
+  mention it. The server cannot fill the gap: MCP carries a bearer token and no
+  filesystem, so only something running on the machine can look.
+
+  The hard part is not finding the file, it is not being wrong about it. A false "not
+  installed" shown to somebody who followed our own instructions teaches them to distrust
+  everything else `doctor` says, so the check knows all three routes a skill really
+  arrives by: global (`~/.claude/skills` and each harness's equivalent), project (the
+  `skills` installer's DEFAULT scope, which lands in the working directory), and, for
+  Claude Code, an installed plugin's own folder, since `/plugin install retasc@retasc` is
+  one of the routes our public README offers and it writes none of the above. It honours
+  `CLAUDE_CONFIG_DIR`, `CODEX_HOME` and `GROK_HOME` for the same reason. The printed
+  command carries `-g` so it installs where the check looks. A harness whose convention
+  we cannot verify is skipped rather than accused, one harness holding the skill silences
+  the nudge for the rest, absence is reported with `ℹ` rather than `✗`, and neither
+  command changes its exit code over any of 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,7 +1,10 @@
 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 { detectHarnesses } from "../lib/harness.js";
 import { runsOk } from "../lib/launcher.js";
+import { skillLines, skillReport } from "../lib/skill.js";
 import { clean } from "../lib/text.js";
 // RTSC-91 (DESIGN §13): `retasc doctor` — confirm THIS folder is correctly and
 // safely bound. The question a human actually has is "which org/project does
@@ -150,9 +153,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) {
@@ -199,7 +219,15 @@ export async function doctorAction() {
             `    own, so issues can land in the wrong project.\n` +
             `    Fix:  claude mcp remove -s user retasc`);
     }
-    // 3) Ambient context, not a verdict on this folder — so it trails the checks
+    // 3) Does the agent that will use this binding have the manual? (RTSC-855)
+    //
+    // A machine fact rather than a folder fact, so it comes after both folder checks.
+    // It is still a check, not a footnote: everything above proves an agent can REACH
+    // Retasc, and this is the one that says whether it will know what to do when it
+    // gets there. Absence never touches the exit code, and `doctorAction` sets none.
+    for (const line of skillLines(skillReport(detectHarnesses())))
+        console.log(line);
+    // 4) Ambient context, not a verdict on this folder — so it trails the checks
     // rather than framing them, and on macOS it prints nothing at all.
     const note = platformNote();
     if (note)

package/dist/commands/setup.js

@@ -18,6 +18,7 @@ import { wireClaudeHook, hookLauncher } from "../lib/sessionHook.js";
 import { AUTO_WORKSPACE } from "../lib/keystore.js";
 import { HARNESSES, detectHarnesses, tildePath } from "../lib/harness.js";
 import { resolveLauncher, launcherNote } from "../lib/launcher.js";
+import { skillLines, skillReport } from "../lib/skill.js";
 import { VERSION } from "../version.js";
 import { card } from "../lib/card.js";
 /** The one entry every harness gets: the watchdog proxy, resolving its own folder. */
@@ -49,6 +50,7 @@ export function runSetup(opts) {
         wired: [],
         failed: [],
         absent: known.filter((h) => !presentIds.has(h.id)).map((h) => h.label),
+        skill: skillReport(present),
     };
     for (const h of present) {
         const outcome = h.install(entry);
@@ -98,6 +100,12 @@ export function printSetup(r) {
     }
     if (r.absent.length)
         console.log(`  Not on this machine: ${r.absent.join(", ")}.`);
+    // RTSC-855 — next to the harness rows, because it is the same kind of fact: what this
+    // machine has, and what it is still missing. `setup` wires the tools; the skill is the
+    // document that tells an agent what to do with them, and nothing else on this receipt
+    // would ever mention that it is absent. Never a failure, and never installed for you.
+    for (const line of skillLines(r.skill))
+        console.log(line);
     console.log("\nThese entries carry no key and name no project, so they are correct in every folder.\n" +
         "Run `retasc bind` in a project to say which org it belongs to, then start your agent\n" +
         "there (or restart it if it's already open).");

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/harness.js

@@ -26,7 +26,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join } from "node:path";
 /**
  * The home directory harness configs are resolved under.
  *
@@ -48,6 +48,38 @@ export function tildePath(p) {
     const h = home();
     return p.startsWith(h + "/") ? `~${p.slice(h.length)}` : p;
 }
+// --- skills directories -----------------------------------------------------
+//
+// Not derived from theory, same rule as the rest of this registry: every path below is a
+// directory the `skills` installer (agentskills.io, the tool `SKILL_INSTALL_CMD` runs)
+// reads for that harness, taken from its published agent table rather than guessed at. If
+// a harness ever grew a convention we could not verify, the honest entry would be an empty
+// list. "We do not know where yours lives" is a finding a human can act on, a made-up path
+// is not.
+//
+// TWO scopes, because the installer has two and defaults to the one a global-only check
+// would never see (`installGlobally = options.global ?? false`, and its interactive prompt
+// offers Project first). A check that read only the home directory would call the skill
+// missing for everybody who ran the install command exactly as printed, forever.
+//
+// The harness's own home variable is honoured here even though `configPath()` does not
+// honour it. That asymmetry is deliberate: this path only READS, so resolving the same
+// home the harness itself resolves can at worst find the skill somewhere true, whereas
+// `configPath()` WRITES and shares its answer with subprocesses. RETASC_HOME still
+// outranks everything, exactly as in `opencodeConfig()`, or the test override would stop
+// protecting the developer's real home the moment one of these variables is set.
+/** A harness's own config home: the test override first, then its documented variable,
+ *  then the default under `~`. */
+function harnessHome(envVar, dir) {
+    if (process.env.RETASC_HOME)
+        return join(home(), dir);
+    return process.env[envVar]?.trim() || join(home(), dir);
+}
+/** `<global skills dir>` plus the project-scope folder this harness reads in the working
+ *  directory. Both are real install targets, so both answer "is the skill here". */
+function skillDirs(globalDir, projectDir) {
+    return [globalDir, join(process.cwd(), ...projectDir.split("/"))];
+}
 export const SERVER_NAME = "retasc";
 // --- shared helpers ---------------------------------------------------------
 /**
@@ -134,11 +166,12 @@ export function tomlBlock(entry) {
         env,
     ].join("\n");
 }
-function tomlHarness(id, label, path, bin) {
+function tomlHarness(id, label, path, bin, skills) {
     return {
         id,
         label,
         configPath: path,
+        skillDirs: () => skillDirs(join(harnessHome(skills.home, skills.dir), "skills"), skills.project),
         detect: () => existsSync(path()) || onPath(bin),
         install(entry) {
             const p = path();
@@ -335,6 +368,53 @@ export function jsonServerValue(entry) {
     return JSON.stringify({ command: entry.command, args: entry.args, env: entry.env }, null, 2);
 }
 // --- Claude Code ------------------------------------------------------------
+/**
+ * The `skills/` folder of every plugin Claude Code has installed (RTSC-855).
+ *
+ * `/plugin install retasc@retasc` is one of the three install routes our public skills
+ * README offers, and it does NOT write into `~/.claude/skills`. The plugin is unpacked
+ * under `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/` and its skills are
+ * read from there. So a check that only looked in the skills folder would tell exactly
+ * the people who followed our own instructions that they had not.
+ *
+ * Read from the manifest rather than globbed, because the manifest is what Claude Code
+ * itself acts on: a stale directory left behind by an uninstall is not an installed
+ * skill, and enumerating the cache would count it as one. Best effort throughout, because
+ * this feeds a nudge and a manifest we cannot parse must never become a hard failure in
+ * `doctor`.
+ */
+function claudePluginSkillDirs() {
+    try {
+        const manifest = join(harnessHome("CLAUDE_CONFIG_DIR", ".claude"), "plugins", "installed_plugins.json");
+        const parsed = JSON.parse(readIfExists(manifest) || "{}");
+        const plugins = parsed?.plugins;
+        if (!plugins || typeof plugins !== "object")
+            return [];
+        const dirs = [];
+        for (const installs of Object.values(plugins)) {
+            for (const i of Array.isArray(installs) ? installs : []) {
+                // Absolute only. A relative `installPath` would resolve against the CURRENT
+                // DIRECTORY, so running `retasc doctor` inside any repo that happens to contain
+                // `skills/retasc/SKILL.md` (this one does) would report the skill installed.
+                // Claude Code writes absolute paths, so nothing legitimate is dropped.
+                // User scope only. A plugin installed for one project would otherwise make
+                // `doctor` report the skill present in every OTHER folder, where the agent
+                // cannot load it. A false "installed" is the worse error of the two: it
+                // produces silence instead of the nudge this check exists to give.
+                const scope = i?.scope;
+                if (scope !== undefined && scope !== "user")
+                    continue;
+                const p = i?.installPath;
+                if (typeof p === "string" && isAbsolute(p))
+                    dirs.push(join(p, "skills"));
+            }
+        }
+        return dirs;
+    }
+    catch {
+        return [];
+    }
+}
 /**
  * Claude Code is the one harness with a real CLI for this, and `claude mcp add` is
  * the ONLY sanctioned way to edit `~/.claude.json`: a running Claude Code rewrites
@@ -351,6 +431,10 @@ const claudeCode = {
     id: "claude-code",
     label: "Claude Code",
     configPath: () => join(home(), ".claude.json"),
+    skillDirs: () => [
+        ...skillDirs(join(harnessHome("CLAUDE_CONFIG_DIR", ".claude"), "skills"), ".claude/skills"),
+        ...claudePluginSkillDirs(),
+    ],
     // A test home means "do not touch this machine's real config". `claude mcp add`
     // writes ~/.claude.json wherever HOME points, so the override has to gate DETECTION,
     // not just the path: an undetected harness is never installed into.
@@ -404,6 +488,7 @@ const cursor = {
     id: "cursor",
     label: "Cursor",
     configPath: () => join(home(), ".cursor", "mcp.json"),
+    skillDirs: () => skillDirs(join(home(), ".cursor", "skills"), ".agents/skills"),
     detect: () => existsSync(join(home(), ".cursor")) || onPath("cursor-agent"),
     install(entry) {
         const p = join(home(), ".cursor", "mcp.json");
@@ -438,6 +523,7 @@ function addCommandHarness(opts) {
         id: opts.id,
         label: opts.label,
         configPath: opts.configPath,
+        skillDirs: () => skillDirs(join(dirname(opts.configPath()), "skills"), opts.projectSkillDir),
         // Gated on RETASC_HOME for the same reason Claude Code is: this shells out to a
         // command that resolves the REAL home, so a test home has to stop it at DETECTION.
         // An undetected harness is never installed into.
@@ -488,6 +574,7 @@ const opencode = addCommandHarness({
     label: "OpenCode",
     bin: "opencode",
     configPath: opencodeConfig,
+    projectSkillDir: ".agents/skills",
     args: (entry) => [
         "mcp", "add", SERVER_NAME,
         ...Object.entries(entry.env).flatMap(([k, v]) => ["--env", `${k}=${v}`]),
@@ -513,6 +600,7 @@ const gemini = addCommandHarness({
     label: "Gemini CLI",
     bin: "gemini",
     configPath: () => join(home(), ".gemini", "settings.json"),
+    projectSkillDir: ".agents/skills",
     args: (entry) => [
         "mcp", "add",
         "-s", "user",
@@ -524,8 +612,16 @@ const gemini = addCommandHarness({
 // --- the registry -----------------------------------------------------------
 export const HARNESSES = [
     claudeCode,
-    tomlHarness("codex", "Codex", () => join(home(), ".codex", "config.toml"), "codex"),
-    tomlHarness("grok", "Grok", () => join(home(), ".grok", "config.toml"), "grok"),
+    tomlHarness("codex", "Codex", () => join(home(), ".codex", "config.toml"), "codex", {
+        home: "CODEX_HOME",
+        dir: ".codex",
+        project: ".agents/skills",
+    }),
+    tomlHarness("grok", "Grok", () => join(home(), ".grok", "config.toml"), "grok", {
+        home: "GROK_HOME",
+        dir: ".grok",
+        project: ".grok/skills",
+    }),
     cursor,
     opencode,
     gemini,

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/dist/lib/skill.js

@@ -0,0 +1,110 @@
+// RTSC-855: is the Retasc Agent Skill on this machine?
+//
+// This check can only live here. The server sees a bearer token and nothing else, no
+// filesystem and no working directory, so it cannot know whether `skills/retasc/SKILL.md`
+// was ever installed and must not pretend to infer it. The CLI runs on the machine, and
+// `doctor` and `setup` already report local facts, so they are the honest place to ask.
+//
+// What is at stake is not cosmetic. The MCP tools give an agent the ability to claim
+// work; the skill is what tells it what a lease is, that a claim needs its own worktree,
+// what a checkpoint is for, and how a handoff into review works. An agent with the tools
+// and not the manual looks like it is working and quietly gets the protocol wrong.
+//
+// Absence is a FINDING, not a failure. Nothing here touches an exit code, and nothing
+// here writes: installing the skill is a decision for the human, made with one command
+// they can read before they run it.
+//
+// Explicitly NOT in scope: deciding whether an installed copy is STALE. That needs a
+// version stamp on the published skill, which does not exist yet, and a guess at it
+// would produce the one output worse than silence, a confident wrong answer about a
+// file the human can see is right there.
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { clean } from "./text.js";
+/** The skill's folder name, and the name it is published under. */
+export const SKILL_NAME = "retasc";
+/**
+ * The one command to print.
+ *
+ * Harness-agnostic on purpose: `npx skills add Retasc/skills` is the first of the three
+ * routes our public README lists and the only one that is correct for all six harnesses
+ * at once, so a machine with Codex and Cursor on it gets a single line rather than a
+ * decision tree. The Claude Code plugin route and the git-clone route stay in the README
+ * where somebody choosing between them is already reading.
+ *
+ * `-g` is load-bearing and was missing here first time round. The installer defaults to
+ * PROJECT scope (`installGlobally = options.global ?? false`, and its interactive prompt
+ * offers Project first), which installs into the current folder. Without the flag this
+ * command would install the skill somewhere real, the agent would load it in that one
+ * folder, and every other folder would keep being told to run the same command again.
+ * Global is what "install this on my machine" means, and it is what a nudge printed by a
+ * machine-wide check should hand you.
+ */
+export const SKILL_INSTALL_CMD = "npx skills add Retasc/skills -g";
+/** A directory is "holding the skill" when the skill's own file is readable in it. A
+ *  bare `retasc/` folder is not an installed skill, and `existsSync` follows symlinks,
+ *  which is how a checkout linked into `~/.claude/skills` counts (see skills/README.md). */
+function holdsSkill(dir) {
+    try {
+        return existsSync(join(dir, SKILL_NAME, "SKILL.md"));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Which of these harnesses can read the skill, and which cannot.
+ *
+ * Takes the DETECTED harnesses rather than detecting for itself, so the answer is about
+ * agents that actually run here: telling someone the skill is missing from Gemini CLI on
+ * a machine with no Gemini CLI is noise dressed as a finding, and both callers have the
+ * detected list in hand already.
+ */
+export function skillReport(harnesses) {
+    const report = { installed: [], missing: [] };
+    for (const h of harnesses) {
+        let dirs = [];
+        try {
+            dirs = h.skillDirs();
+        }
+        catch {
+            dirs = [];
+        }
+        // No known skills directory means we cannot answer for this harness, and the honest
+        // move is to say nothing rather than to invent a path and report a miss against it.
+        if (!dirs.length)
+            continue;
+        const entry = { label: h.label };
+        (dirs.some(holdsSkill) ? report.installed : report.missing).push(entry);
+    }
+    return report;
+}
+const names = (list) => clean(list.map((p) => p.label).join(", "));
+/**
+ * The lines to print, prefixes included, shared verbatim by `doctor` and `setup`.
+ *
+ * One renderer because the issue asks both surfaces to say the same thing, and two
+ * copies of a sentence are two sentences the moment one of them is edited.
+ *
+ * `ℹ` and not `✗`: this is context about the machine, not a fault in the folder being
+ * checked, and it sits in a report whose ✓/✗ marks people read as pass and fail.
+ */
+export function skillLines(report) {
+    // One harness with the skill is enough to say so and stop talking. The nudge exists for
+    // the machine that has the manual NOWHERE; on a developer laptop that has Cursor and
+    // Gemini installed but points neither at Retasc, listing them as missing on every run
+    // is an unresolvable nag about work nobody intends to do, and a check people learn to
+    // scroll past has stopped being a check. Which harnesses DO have it is named in the ✓
+    // line, so nothing true is being hidden.
+    if (report.installed.length) {
+        return [`  ✓ the Retasc Agent Skill is installed (${names(report.installed)}).`];
+    }
+    if (!report.missing.length)
+        return [];
+    return [
+        `  ℹ the Retasc Agent Skill is not installed for ${names(report.missing)}.\n` +
+            `    It is what teaches an agent to work the queue: dispatch, leases, checkpoints,\n` +
+            `    handing off through review. Without it an agent has the tools and not the manual.\n` +
+            `    Install:  ${SKILL_INSTALL_CMD}`,
+    ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.44.0",
+  "version": "1.46.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": {