toolroll 0.8.0 → 0.8.1

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## Unreleased
 
+## 0.8.1 — 2026-09-30
+
+- **Safer `toolroll update`.** A release is accepted only when its signing
+  certificate names ap9000/toolroll, its publish workflow and GitHub
+  Actions, checked with the Sigstore verifier npm already ships (found from
+  npm itself, so a custom npm global folder works too). A failed
+  update puts the commands back before stopping the service, stops and
+  restarts per-project watch workers with it, restores even when the live
+  database can't be copied aside, and keeps the last good update so
+  `--rollback` still works after a refused attempt, including for the update
+  that brought 0.8.1. The console's update job
+  finds pnpm, bun and npm where they are installed; the desktop app is never
+  offered npm.
+- **Safer `toolroll onboard`.** It adds the main checkout rather than a
+  temporary worktree, never adds your home folder, and asks before adding a
+  project. Run by an agent, `toolroll up` never prints the password. Login
+  advice matches how the install actually signs in, and uses the port `up`
+  serves on. A skill you have edited is left alone.
+- **Chat opens instantly.** First-run suggestions and the agent sign-in check
+  refresh in the background, so a slow network never holds up the page.
+  Tapping a suggestion adds to what you typed instead of replacing it.
+
 ## 0.8.0 — 2026-09-30
 
 - **Install with your agent.** `toolroll onboard`, run by the agent that

package/README.md

@@ -53,13 +53,13 @@ Paste this into Claude Code or Codex:
 
 > Install Toolroll with `npm install -g toolroll` and start `toolroll up` in
 > the background; it keeps running. Then run `toolroll onboard` in this
-> repository, and run it again with `--yes` to install Toolroll's skill for
-> you. Tell me the console address, where my login is saved (not the
+> repository, and run it again with `--yes` to add it as a project and install
+> Toolroll's skill for you. Tell me the console address, where my login is saved (not the
 > password), how to pair my phone, and what I can ask you next.
 
-`toolroll onboard` adds the repository as a project, says which agent CLIs are
-signed in, and prints the line that adds Toolroll as tools
-(`claude mcp add toolroll -- toolroll mcp`) without running it.
+`toolroll onboard --yes` adds the repository (its main checkout) as a project,
+says which agent CLIs are signed in, and prints the line that adds Toolroll as
+tools (`claude mcp add --scope user toolroll -- toolroll mcp`) without running it.
 `toolroll onboard --remove --yes` takes the skill out again.
 
 Then read [Getting started](docs/guide/getting-started.md), [Flows](docs/guide/flows.md)

package/dist/agent-onboard.d.ts

@@ -7,29 +7,34 @@
  * a thin operator skill for the person's own agent, prints the MCP line
  * without running it, and ends with a handoff the agent can relay.
  *
- * The skill is the only write outside Toolroll's own state, so it needs
- * --yes or a yes typed at a terminal. It is marked as Toolroll's, replaced
- * by the next onboard, and deleted by `onboard --remove`; a file of the
- * same name that is not ours is never touched.
+ * Adding the project and writing the skill both need --yes or one yes
+ * typed at a terminal. The project is the main checkout (never a linked
+ * worktree, the home folder, or one of Toolroll's own worktrees). The skill
+ * is replaced by the next onboard and deleted by `onboard --remove` only
+ * while it is exactly a version Toolroll wrote; a file of the same name
+ * that is not ours, or ours with the person's edits, is never touched.
  */
 import type { ProviderConnection } from "./provider-connection.js";
 export type OnboardAgent = "claude" | "codex";
 export declare const ONBOARD_AGENTS: readonly OnboardAgent[];
 export declare const AGENT_NAMES: Record<OnboardAgent, string>;
-/** Each agent's user-level home: where its skills folder lives. */
+/** Each agent's user-level home: where its skills folder lives. A relative CODEX_HOME is under the home folder, never
+ * wherever onboard happens to run. */
 export declare function agentHome(agent: OnboardAgent, home: string, env: Record<string, string | undefined>): string;
 export declare function operatorSkillPath(agent: OnboardAgent, home: string, env: Record<string, string | undefined>): string;
 /** The agents this person uses: those whose home folder exists, else Claude Code. */
 export declare function detectAgents(home: string, env: Record<string, string | undefined>): OnboardAgent[];
-/** The line that adds Toolroll as tools. Printed, never run. */
+/** The line that adds Toolroll as tools, for every project. Printed, never run. */
 export declare function mcpLine(agent: OnboardAgent): string;
 /** The thin skill: when to reach for Toolroll, and where the real guides are. */
 export declare function operatorSkillContent(version: string): string;
+/** A skill's fingerprint with the version it names set aside: every release writes the same words. */
+export declare function skillFingerprint(content: string): string;
 export type SkillStep = {
     agent: OnboardAgent;
     path: string;
-    /** create/replace/remove change the file; current and absent change nothing; not-ours refuses. */
-    action: "create" | "replace" | "current" | "remove" | "absent" | "not-ours";
+    /** create/replace/remove change the file; current and absent change nothing; not-ours and edited refuse. */
+    action: "create" | "replace" | "current" | "remove" | "absent" | "not-ours" | "edited";
     /** Old guide copies of ours that go with it. */
     alsoRemove: string[];
 };
@@ -45,23 +50,24 @@ export declare function applyOperatorSkill(steps: readonly SkillStep[], version:
     wrote: string[];
     removed: string[];
 };
+/** How to sign in: the account, and the saved login file when one still works. Never the password. */
+export type HandoffLogin = {
+    account: string | null;
+    file: string | null;
+};
 export type Handoff = {
     console: string;
     /** How to start the console when it is not running. */
     start: string;
-    /** The saved login: the account and the file. Never the password. */
-    login: {
-        account: string | null;
-        file: string;
-    } | null;
+    /** null while there is no account yet. */
+    login: HandoffLogin | null;
     phone: string;
     next: readonly string[];
 };
 export declare const NEXT_THINGS: readonly ["queue these bugs overnight", "what needs me?", "open the result"];
 export declare function buildHandoff(input: {
     url: string;
-    loginFile: string | null;
-    account: string | null;
+    login: HandoffLogin | null;
 }): Handoff;
 export declare function handoffLines(handoff: Handoff): string[];
 /** The account name from a saved login file, never its password. */
@@ -82,16 +88,24 @@ export type OnboardIo = {
     /** --agent, as typed: a comma list of claude and codex. */
     agentFlag: string | undefined;
     url: string;
-    loginFile: string;
+    login: HandoffLogin | null;
     home: string;
+    /** Where Toolroll leases its own worktrees: never a project. */
+    worktrees: string;
     env: Record<string, string | undefined>;
     version: string;
     cwd: string;
     /** A person at a terminal who can be asked y/N. */
     interactive: boolean;
     confirm: (question: string) => Promise<boolean>;
-    /** The repository top folder containing cwd, or null outside one. */
-    findRepo: (cwd: string) => Promise<string | null>;
+    /** The repository containing cwd: its top folder, and its main checkout (the same folder unless cwd is in a linked
+     * worktree). null outside one. */
+    findRepo: (cwd: string) => Promise<{
+        top: string;
+        main: string;
+    } | null>;
+    /** Whether a repository is already a project. */
+    enrolled: (repo: string) => Promise<boolean>;
     /** Add a repository as a project, as Projects → add does. */
     enroll: (repo: string) => Promise<{
         ok: true;
@@ -102,5 +116,14 @@ export type OnboardIo = {
     }>;
     checkConnection: (agent: OnboardAgent) => Promise<ProviderConnection>;
 };
+/** Why a found repository cannot be the project, or null when it can. */
+export declare function projectRefusal(found: {
+    top: string;
+    main: string;
+}, where: {
+    cwd: string;
+    home: string;
+    worktrees: string;
+}): string | null;
 /** Returns the exit code: 0 done, 2 usage, 3 a refusal to answer. */
 export declare function runOnboard(io: OnboardIo): Promise<number>;

package/dist/agent-onboard.js

@@ -7,22 +7,30 @@
  * a thin operator skill for the person's own agent, prints the MCP line
  * without running it, and ends with a handoff the agent can relay.
  *
- * The skill is the only write outside Toolroll's own state, so it needs
- * --yes or a yes typed at a terminal. It is marked as Toolroll's, replaced
- * by the next onboard, and deleted by `onboard --remove`; a file of the
- * same name that is not ours is never touched.
+ * Adding the project and writing the skill both need --yes or one yes
+ * typed at a terminal. The project is the main checkout (never a linked
+ * worktree, the home folder, or one of Toolroll's own worktrees). The skill
+ * is replaced by the next onboard and deleted by `onboard --remove` only
+ * while it is exactly a version Toolroll wrote; a file of the same name
+ * that is not ours, or ours with the person's edits, is never touched.
  */
-import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { CLAUDE_CODE_GUIDES, CLAUDE_CODE_MANAGED_MARK, MANAGED_MARK, OPERATOR_SKILL_MARK } from "./skills.js";
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, resolve, sep } from "node:path";
+import { CLAUDE_CODE_GUIDES, CLAUDE_CODE_MANAGED_MARK, MANAGED_MARK, OPERATOR_SKILL_MARK, claudeCodeSkillContent } from "./skills.js";
 import { connectionWords } from "./control-ui.js";
 import { envelopeJson } from "./envelope.js";
 export const ONBOARD_AGENTS = ["claude", "codex"];
 export const AGENT_NAMES = { claude: "Claude Code", codex: "Codex" };
-/** Each agent's user-level home: where its skills folder lives. */
+/** Each agent's user-level home: where its skills folder lives. A relative CODEX_HOME is under the home folder, never
+ * wherever onboard happens to run. */
 export function agentHome(agent, home, env) {
-    if (agent === "codex")
-        return env["CODEX_HOME"] !== undefined && env["CODEX_HOME"] !== "" ? env["CODEX_HOME"] : join(home, ".codex");
+    if (agent === "codex") {
+        const codexHome = env["CODEX_HOME"];
+        if (codexHome === undefined || codexHome === "")
+            return join(home, ".codex");
+        return isAbsolute(codexHome) ? codexHome : resolve(home, codexHome);
+    }
     return join(home, ".claude");
 }
 export function operatorSkillPath(agent, home, env) {
@@ -33,9 +41,9 @@ export function detectAgents(home, env) {
     const found = ONBOARD_AGENTS.filter(agent => existsSync(agentHome(agent, home, env)));
     return found.length > 0 ? found : ["claude"];
 }
-/** The line that adds Toolroll as tools. Printed, never run. */
+/** The line that adds Toolroll as tools, for every project. Printed, never run. */
 export function mcpLine(agent) {
-    return `${agent} mcp add toolroll -- toolroll mcp`;
+    return agent === "claude" ? "claude mcp add --scope user toolroll -- toolroll mcp" : `${agent} mcp add toolroll -- toolroll mcp`;
 }
 /** The thin skill: when to reach for Toolroll, and where the real guides are. */
 export function operatorSkillContent(version) {
@@ -64,13 +72,24 @@ Read the guides from the installed binary. They match its version, so do not cop
 Approving work and answering decisions belong to the person. Never read out or repeat their password.
 `;
 }
-/** A regular file of ours: our frontmatter and one of our marks. */
-function ownSkill(path) {
+const escapedMark = OPERATOR_SKILL_MARK.replace(/[.*+?^$()|[\]\\{}]/g, "\\$&");
+const WRITTEN_BY = new RegExp(`^(${escapedMark} · written by toolroll )(\\S+?)(\\. \`toolroll onboard)`, "m");
+/** A skill's fingerprint with the version it names set aside: every release writes the same words. */
+export function skillFingerprint(content) {
+    return createHash("sha256").update(content.replace(WRITTEN_BY, "$1*$3")).digest("hex");
+}
+/** Every SKILL.md Toolroll has generated at this path: the operator skill, and `skills install --claude-code`'s. */
+const KNOWN_SKILLS = new Set([operatorSkillContent("0.0.0"), claudeCodeSkillContent()].map(skillFingerprint));
+/** ours: exactly a version Toolroll wrote. edited: ours, with the person's changes. foreign: not ours at all. */
+function skillOwnership(path) {
     const entry = lstatSync(path);
     if (entry.isSymbolicLink() || !entry.isFile() || entry.size > 2_000_000)
-        return false;
+        return "foreign";
     const content = readFileSync(path, "utf8");
-    return content.startsWith("---\nname: toolroll\n") && [OPERATOR_SKILL_MARK, CLAUDE_CODE_MANAGED_MARK, MANAGED_MARK].some(mark => content.includes(mark));
+    const marked = content.startsWith("---\nname: toolroll\n") && [OPERATOR_SKILL_MARK, CLAUDE_CODE_MANAGED_MARK, MANAGED_MARK].some(mark => content.includes(mark));
+    if (!marked)
+        return "foreign";
+    return KNOWN_SKILLS.has(skillFingerprint(content)) ? "ours" : "edited";
 }
 /** Guide copies an older `skills install --claude-code` left beside SKILL.md. */
 function oldGuideCopies(folder) {
@@ -103,8 +122,9 @@ export function planOperatorSkill(agents, options) {
         if (!lstatExists(path)) {
             return { agent, path, action: options.remove ? (alsoRemove.length > 0 ? "remove" : "absent") : "create", alsoRemove };
         }
-        if (!ownSkill(path))
-            return { agent, path, action: "not-ours", alsoRemove: [] };
+        const ownership = skillOwnership(path);
+        if (ownership !== "ours")
+            return { agent, path, action: ownership === "edited" ? "edited" : "not-ours", alsoRemove: [] };
         if (options.remove)
             return { agent, path, action: "remove", alsoRemove };
         const current = readFileSync(path, "utf8") === operatorSkillContent(options.version);
@@ -147,15 +167,17 @@ export function buildHandoff(input) {
     return {
         console: input.url,
         start: "toolroll up",
-        login: input.loginFile === null ? null : { account: input.account, file: input.loginFile },
+        login: input.login,
         phone: "Open the console on your phone over your tailnet, or pair Telegram in Settings → Telegram with the /pair code it shows.",
         next: NEXT_THINGS,
     };
 }
 export function handoffLines(handoff) {
     const login = handoff.login === null
-        ? "no saved login yet; `toolroll up` creates one"
-        : `${handoff.login.account === null ? "the account" : handoff.login.account} — the password is in ${handoff.login.file}`;
+        ? "no account yet; `toolroll up` creates one"
+        : handoff.login.file === null
+            ? `${handoff.login.account ?? "your account"} — sign in with your password`
+            : `${handoff.login.account ?? "the account"} — the password is in ${handoff.login.file}`;
     return [
         "Toolroll is ready.",
         `  console   ${handoff.console}`,
@@ -178,6 +200,27 @@ export function loginAccount(file) {
 export function agentReport(agent, connection) {
     return { agent, name: AGENT_NAMES[agent], state: connection.state, words: connectionWords(connection), ...(connection.plan === undefined ? {} : { plan: connection.plan }) };
 }
+const real = (path) => {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+};
+const within = (path, folder) => path === folder || path.startsWith(folder.endsWith(sep) ? folder : `${folder}${sep}`);
+/** Why a found repository cannot be the project, or null when it can. */
+export function projectRefusal(found, where) {
+    const worktrees = real(where.worktrees);
+    if ([where.cwd, found.top, found.main].some(path => within(real(path), worktrees))) {
+        return `${found.top} is one of Toolroll's own worktrees, not a project: run onboard inside your own checkout`;
+    }
+    const home = real(where.home);
+    if (real(found.main) === home || real(found.top) === home) {
+        return `${home} is your home folder, not a project: run onboard inside the repository you want to hand off`;
+    }
+    return null;
+}
 /** Returns the exit code: 0 done, 2 usage, 3 a refusal to answer. */
 export async function runOnboard(io) {
     const command = "onboard";
@@ -196,70 +239,101 @@ export async function runOnboard(io) {
     else {
         agents = detectAgents(io.home, io.env);
     }
-    // The skill: validate every file first, then ask once, then write.
+    // The skill: validate every file first.
     const steps = planOperatorSkill(agents, { home: io.home, env: io.env, version: io.version, remove: io.remove });
     const changes = steps.filter(step => step.action === "create" || step.action === "replace" || step.action === "remove");
-    const foreign = steps.filter(step => step.action === "not-ours");
+    const foreign = steps.filter(step => step.action === "not-ours" || step.action === "edited");
+    const skillChanges = foreign.length === 0 && changes.length > 0;
+    // The project: the main checkout of the repository onboard runs in, never --remove's business.
+    let project = { state: "none" };
+    if (!io.remove) {
+        const found = await io.findRepo(io.cwd);
+        if (found !== null) {
+            const refusal = projectRefusal(found, { cwd: io.cwd, home: io.home, worktrees: io.worktrees });
+            if (refusal !== null)
+                project = { state: "refused", path: found.main, message: refusal };
+            else
+                project = { state: (await io.enrolled(found.main)) ? "already" : "needs-yes", path: found.main };
+        }
+    }
+    const projectChange = project.state === "needs-yes";
+    // Then ask once for everything that writes, then write.
+    let consent = false;
+    if (skillChanges || projectChange) {
+        const parts = [
+            ...(projectChange ? [`add ${project.path} as a project`] : []),
+            ...(skillChanges ? [`${io.remove ? "remove" : "write"} ${changes.map(step => step.path).join(" and ")}`] : []),
+        ];
+        const question = `${parts.join(" and ").replace(/^./, first => first.toUpperCase())}? [y/N]`;
+        consent = io.yes || (io.interactive && !io.json && (await io.confirm(question)));
+    }
+    const unconfirmed = io.interactive && !io.json && !io.yes ? "declined" : "needs-yes";
     let skill;
     if (foreign.length > 0) {
-        skill = { state: "not-ours", files: steps, wrote: [], removed: [] };
+        skill = { state: foreign.some(step => step.action === "not-ours") ? "not-ours" : "edited", files: steps, wrote: [], removed: [] };
     }
-    else if (changes.length === 0) {
+    else if (!skillChanges) {
         skill = { state: io.remove ? "absent" : "current", files: steps, wrote: [], removed: [] };
     }
+    else if (!consent) {
+        skill = { state: unconfirmed, files: steps, wrote: [], removed: [] };
+    }
     else {
-        const paths = changes.map(step => step.path);
-        const consent = io.yes || (io.interactive && !io.json && (await io.confirm(`${io.remove ? "Remove" : "Write"} ${paths.join(" and ")}? [y/N]`)));
-        if (!consent) {
-            skill = { state: io.interactive && !io.json && !io.yes ? "declined" : "needs-yes", files: steps, wrote: [], removed: [] };
-        }
-        else {
-            const done = applyOperatorSkill(steps, io.version);
-            skill = { state: io.remove ? "removed" : "written", files: steps, ...done };
-        }
+        const done = applyOperatorSkill(steps, io.version);
+        skill = { state: io.remove ? "removed" : "written", files: steps, ...done };
     }
     const skillLine = () => {
         const where = (list) => list.map(step => step.path).join(", ");
+        const nothing = io.remove ? "removed" : "written";
         switch (skill.state) {
             case "written": return `skill     wrote ${skill.wrote.join(", ")}`;
             case "removed": return `skill     removed ${skill.removed.join(", ")}`;
             case "current": return `skill     up to date: ${where(steps)}`;
             case "absent": return "skill     not installed; nothing to remove";
-            case "not-ours": return `skill     ${where(foreign)} ${foreign.length === 1 ? "is" : "are"} not Toolroll's, so nothing was ${io.remove ? "removed" : "written"}`;
-            case "declined": return `skill     nothing ${io.remove ? "removed" : "written"}`;
-            case "needs-yes": return `skill     not ${io.remove ? "removed" : "written"} yet: run again with --yes to ${io.remove ? "remove" : "write"} ${where(changes)}`;
+            case "not-ours": return `skill     ${where(foreign)} ${foreign.length === 1 ? "is" : "are"} not Toolroll's, so nothing was ${nothing}`;
+            case "edited": return `skill     ${where(foreign)} ${foreign.length === 1 ? "has your edits, so it was" : "have your edits, so they were"} left as is`;
+            case "declined": return `skill     nothing ${nothing}`;
+            case "needs-yes": return `skill     not ${nothing} yet: run again with --yes to ${io.remove ? "remove" : "write"} ${where(changes)}`;
         }
     };
     const skillData = { state: skill.state, files: skill.files.map(step => ({ agent: step.agent, path: step.path, action: step.action })), wrote: skill.wrote, removed: skill.removed };
     if (io.remove) {
-        if (skill.state === "not-ours")
-            return refuse("not-ours", skillLine().replace(/^skill\s+/, ""), 3, { skill: skillData });
+        if (skill.state === "not-ours" || skill.state === "edited")
+            return refuse(skill.state, skillLine().replace(/^skill\s+/, ""), 3, { skill: skillData });
         if (skill.state === "needs-yes" || skill.state === "declined") {
             return refuse("unconfirmed", skillLine().replace(/^skill\s+/, ""), 3, { skill: skillData });
         }
         io.write(io.json ? envelopeJson({ ok: true, command, skill: skillData }) : skillLine());
         return 0;
     }
-    // The project, then who is signed in.
-    const repo = await io.findRepo(io.cwd);
-    let project = null;
-    let projectProblem = null;
-    if (repo !== null) {
-        const enrolled = await io.enroll(repo);
-        if (enrolled.ok)
-            project = { path: repo, added: enrolled.added };
-        else
-            projectProblem = enrolled.message;
+    if (project.state === "needs-yes") {
+        if (!consent)
+            project = { state: unconfirmed, path: project.path };
+        else {
+            const enrolled = await io.enroll(project.path);
+            project = enrolled.ok ? { state: enrolled.added ? "added" : "already", path: project.path } : { state: "failed", path: project.path, message: enrolled.message };
+        }
     }
     const reports = await Promise.all(ONBOARD_AGENTS.map(async (agent) => agentReport(agent, await io.checkConnection(agent))));
-    const handoff = buildHandoff({ url: io.url, loginFile: existsSync(io.loginFile) ? io.loginFile : null, account: loginAccount(io.loginFile) });
+    const handoff = buildHandoff({ url: io.url, login: io.login });
     const mcp = agents.map(agent => ({ agent, command: mcpLine(agent) }));
+    const projectData = project.state === "added" || project.state === "already" ? { path: project.path, added: project.state === "added" } : null;
+    const projectProblem = (() => {
+        switch (project.state) {
+            case "none": return "not inside a git repository";
+            case "refused": return project.message;
+            case "failed": return `${project.path} could not be added — ${project.message}`;
+            case "needs-yes": return `not added yet: run again with --yes to add ${project.path}`;
+            case "declined": return `${project.path} not added`;
+            default: return null;
+        }
+    })();
     if (io.json) {
         io.write(envelopeJson({
             ok: true,
             command,
-            project,
-            ...(repo === null ? { projectProblem: "not inside a git repository" } : projectProblem === null ? {} : { projectProblem }),
+            project: projectData,
+            ...(projectProblem === null ? {} : { projectProblem }),
             agents: reports,
             skill: skillData,
             mcp,
@@ -267,9 +341,9 @@ export async function runOnboard(io) {
         }));
         return 0;
     }
-    const projectLine = project !== null
-        ? `project   ${project.path} — ${project.added ? "added" : "already added"}`
-        : repo === null ? "project   none added: run onboard inside the repository you want to hand off" : `project   ${repo} could not be added — ${projectProblem}`;
+    const projectLine = projectData !== null
+        ? `project   ${projectData.path} — ${projectData.added ? "added" : "already added"}`
+        : project.state === "none" ? "project   none added: run onboard inside the repository you want to hand off" : `project   ${projectProblem}`;
     io.write([
         projectLine,
         `agents    ${reports.map(one => `${one.name}: ${[one.words, one.plan].filter(Boolean).join(" · ")}`).join("; ")}`,