@repo-os/repoos 0.5.75 → 0.5.76

package/README.md

@@ -1,9 +1,9 @@
 # RepoOS
 
-**The repo is the operating system.**
+**The repo is the operating system. Your AI dev team, living in your repo, for CTOs and builders.**
 
 RepoOS is a lightweight, repo-native way to track work that lives as markdown
-files inside your monorepo. Tasks, specs, bugs, and feature requests are plain
+files inside your repo. Tasks, specs, bugs, and feature requests are plain
 `.md` files with YAML frontmatter — versioned in git, readable by humans, and
 designed to be consumed directly by AI coding agents.
 
@@ -50,7 +50,8 @@ curl -fsSL https://repoos.org/install | bash
 ```
 
 It runs on Bun when available (recommended), otherwise requires Node.js >=
-20.6.0. It installs to `~/.repoos` and links `repoos` into `~/.local/bin`.
+20.6.0. It installs to `~/.local/share/repoos` and links `repoos` into
+`~/.local/bin`. Machine state stays in `~/.repoos`.
 
 ### Homebrew
 
@@ -76,22 +77,18 @@ bun add -g @repo-os/repoos
 pnpm add -g @repo-os/repoos
 ```
 
-### mise
+mise is not a recommended install method. See `docs/install-layout.md`.
 
-```bash
-mise use --global npm:@repo-os/repoos
-```
-
-This uses mise's built-in npm backend and records RepoOS in your global mise
-configuration. Make sure [mise shell activation](https://mise.jdx.dev/getting-started.html)
-is enabled so its `repoos` shim is on your PATH.
+Bun installs `bun` into `~/.bun/bin`; add that directory to `PATH` before
+`bun add -g`. pnpm on a clean account needs `SHELL` set and `pnpm setup`
+before a global install.
 
 Use the same tool to update a package-manager install: `npm update -g
 @repo-os/repoos`, `bun update -g @repo-os/repoos`, `pnpm update -g
-@repo-os/repoos`, `mise upgrade npm:@repo-os/repoos`, or `brew update && brew
-upgrade repo-os/tap/repoos`. A standalone install updates with `repoos upgrade`
-and removes with `repoos uninstall`. When run from a recognised package-manager
-install, `repoos upgrade` prints the matching package-manager command instead.
+@repo-os/repoos`, or `brew update && brew upgrade repo-os/tap/repoos`. A
+standalone install updates with `repoos upgrade` and removes with
+`repoos uninstall`. When run from a recognised package-manager install,
+`repoos upgrade` prints the matching package-manager command instead.
 
 Then in any repo:
 

package/dist/.build-info.json

@@ -1,5 +1,5 @@
 {
-  "hash": "bd7090b8a9f41e6d39058987c990b663fd2d8e51ec58782d6dafbb41fd7e540a",
-  "version": "0.5.75",
+  "hash": "ee6f28bc85995205fba9c8e23d6fc9802ccba3ff85045ffd94eaba4a635c603f",
+  "version": "0.5.76",
   "devUi": false
 }

package/dist/.build-stamp.json

@@ -1,3 +1,3 @@
 {
-  "generatedAt": "2026-11-04T03:49:23.103Z"
+  "generatedAt": "2026-11-05T04:53:41.853Z"
 }

package/dist/cli/api-route-parity.js

@@ -18,6 +18,8 @@ const CONTROL_API_MATCHERS = [
     re("POST", /^\/api\/tasks\/([^/]+)\/needs-input\/dismiss$/.source),
     re("POST", /^\/api\/tasks\/([^/]+)\/review\/again$/.source),
     re("GET", /^\/api\/tasks\/([^/]+)\/landable$/.source),
+    // Non-blocking handoff outcome for `repoos handoff-status` (#1028).
+    re("GET", /^\/api\/tasks\/([^/]+)\/handoff-status$/.source),
     re("POST", /^\/api\/tasks\/([^/]+)\/preview$/.source),
     re("POST", /^\/api\/tasks\/([^/]+)\/preview\/stop$/.source),
     // `repoos shot` single-entry capture through the browser-capture policy (#0874).

package/dist/cli/help.js

@@ -160,6 +160,12 @@ const GROUPS = [
                 desc: "Read-only checks before merging (verdict, lock, worktree, merge, scope, main) — exits non-zero when the task is not ready to merge (GET /api/tasks/:id/landable)",
                 flags: "--json · --port",
             },
+            {
+                name: "handoff-status",
+                usage: "handoff-status <id> [--json] [--port N]",
+                desc: "Non-blocking state of the latest handoff attempt: not requested, running, passed, failed or deferred (GET /api/tasks/:id/handoff-status)",
+                flags: "--json · --port",
+            },
             {
                 name: "override",
                 usage: "override <id> [--cli <name>] [--model <model>] [--json] [--port N]",

package/dist/cli/index.js

@@ -27,7 +27,7 @@ import { cmdCertify } from "../commands/certify.js";
 import { cmdSupport } from "../commands/support.js";
 import { cmdService } from "../commands/service.js";
 import { cmdServers } from "../commands/servers.js";
-import { cmdAgentsRunning, cmdConfig, cmdDone, cmdLandable, cmdMessage, cmdSendBack, cmdOverride, cmdPause, cmdPreview, cmdDev, cmdReview, cmdVerify, cmdRunners, cmdStart, cmdSync, cmdStats, cmdDecisions, cmdApi, cmdIntegration, cmdAttention, cmdHold, cmdUnhold, } from "../commands/control-api.js";
+import { cmdAgentsRunning, cmdConfig, cmdDone, cmdLandable, cmdHandoffStatus, cmdMessage, cmdSendBack, cmdOverride, cmdPause, cmdPreview, cmdDev, cmdReview, cmdVerify, cmdRunners, cmdStart, cmdSync, cmdStats, cmdDecisions, cmdApi, cmdIntegration, cmdAttention, cmdHold, cmdUnhold, } from "../commands/control-api.js";
 import { cmdWatch } from "../commands/watch.js";
 import { cmdDriver } from "../commands/driver.js";
 import { cmdBundle } from "../commands/bundle.js";
@@ -327,6 +327,12 @@ function main() {
                     process.exitCode = code;
             });
             break;
+        case "handoff-status":
+            void cmdHandoffStatus(rest).then((code) => {
+                if (code !== 0)
+                    process.exitCode = code;
+            });
+            break;
         case "override":
             void cmdOverride(rest).then((code) => {
                 if (code !== 0)

package/dist/commands/control-api.d.ts

@@ -83,6 +83,12 @@ interface StatsGitJobView {
     ageMs?: number;
 }
 export declare function printSystemSummary(system: StatsSystemView): void;
+/**
+ * `repoos handoff-status <id>` (#1028): print the latest handoff attempt's
+ * state immediately. Never waits for, starts, or alters a handoff — safe to
+ * call from an engineer that is unsure whether its request reached the server.
+ */
+export declare function cmdHandoffStatus(args: string[]): Promise<number>;
 /**
  * `repoos landable <id>` (#0867): print the read-only landing pre-checks and
  * exit 0 only when every check passes. Never edits, commits or moves status.

package/dist/commands/control-api.js

@@ -179,9 +179,9 @@ export async function cmdHold(args) {
         return 1;
     }
     const api = new RepoOsApi({ port: opts.port });
-    // #0960 input validation (mirrors the API guard): a hold needs a reason so it
-    // is visible on the board, and `--until` must be a real date or it would
-    // never auto-release and become a permanent hold.
+    // #0960: the CLI still requires `--reason`. The HTTP hold route accepts a
+    // missing reason (#1033). `--until` must be a real date or it would never
+    // auto-release and become a permanent hold.
     if (!opts.reason || !opts.reason.trim()) {
         printErr("hold requires a --reason (free text documenting why the task is parked)");
         return 1;
@@ -1506,6 +1506,56 @@ function landableIcon(status) {
         return c.yellow("!");
     return c.red("✗");
 }
+/**
+ * `repoos handoff-status <id>` (#1028): print the latest handoff attempt's
+ * state immediately. Never waits for, starts, or alters a handoff — safe to
+ * call from an engineer that is unsure whether its request reached the server.
+ */
+export async function cmdHandoffStatus(args) {
+    const { rest, opts, error } = parseCommonFlags(args);
+    if (error) {
+        printErr(error);
+        return 1;
+    }
+    const id = rest[0];
+    if (!id) {
+        printErr("Usage: repoos handoff-status <id> [--json] [--port N]");
+        return 1;
+    }
+    const api = new RepoOsApi({ port: opts.port });
+    try {
+        await ensureServer(api);
+        const status = (await api.requestOk("GET", `/api/tasks/${id}/handoff-status`));
+        if (opts.json) {
+            printJson(status);
+            return 0;
+        }
+        const label = status.state === "passed"
+            ? c.green("passed")
+            : status.state === "failed"
+                ? c.red("failed")
+                : status.state === "running"
+                    ? c.yellow("running")
+                    : status.state === "deferred"
+                        ? c.yellow("deferred")
+                        : c.dim("not requested");
+        console.log(`  ${c.bold(`#${id}`)} handoff: ${label}`);
+        if (status.step)
+            console.log(`    step:   ${status.step}`);
+        if (status.reason)
+            console.log(`    reason: ${status.reason}`);
+        if (status.updatedAt)
+            console.log(`    at:     ${status.updatedAt}`);
+        if (status.state === "not_requested") {
+            console.log(c.dim(`    no handoff has been requested for this task (request it with \`repoos mv ${id} review\`)`));
+        }
+        return 0;
+    }
+    catch (e) {
+        printErr(e.message);
+        return 1;
+    }
+}
 /**
  * `repoos landable <id>` (#0867): print the read-only landing pre-checks and
  * exit 0 only when every check passes. Never edits, commits or moves status.

package/dist/commands/init.js

@@ -22,7 +22,7 @@ import { deriveServePort, findRepoRoot, loadConfig } from "../core/config.js";
 import { CHECK_PLAN_PROPOSAL_FILE, proposeCheckPlan } from "../core/check-plan-proposal.js";
 import { formatPlanToml } from "../core/check-plan.js";
 import { importDocsInto, scaffoldDocsInto } from "./docs-io.js";
-import { gitAvailable, gitCommitAll, gitConfig, gitInit, isGitRepo } from "../core/git.js";
+import { gitAvailable, gitCommitAll, gitIdentityConfigured, gitInit, isGitRepo, } from "../core/git.js";
 import { c } from "../cli/colors.js";
 import { cmdServe } from "./serve.js";
 import { detectAgents } from "../core/detect.js";
@@ -178,11 +178,11 @@ repo itself is the source of truth. This file tells AI agents how to operate.
 
 New to this repo? The board is \`${workDir}/\` — one markdown file per task.
 Create work with \`repoos new "<title>"\`, move it with \`repoos mv <id> <status>\`,
-and **never** edit \`${workDir}/*.md\` by hand (use the CLI or the HTTP API).
+and **never** edit task files under \`${workDir}/\` by hand (use the CLI or the HTTP API).
 Project context lives under \`${docsDir}/\`; start there. Run \`repoos serve\` in a
 terminal you keep open, or install \`repoos service\` for an unattended server —
 a detached \`repoos serve\` started from an agent shell is reaped as a stray orphan
-(see \`docs/agent-process-safety.md\`). RepoOS runs each managed agent turn in its
+(see https://docs.repoos.org/running-with-agents). RepoOS runs each managed agent turn in its
 own process group and tears that group down when the turn ends; never use \`pkill\`
 or \`killall\` to clean up helpers. When a task is done, run \`repoos check\` and
 hand off with \`repoos mv <id> review\`; see the operating loop below.
@@ -192,8 +192,8 @@ hand off with \`repoos mv <id> review\`; see the operating loop below.
 For a RepoOS-managed task runner:
 
 1. Read this file, your assigned task under \`${workDir}/\`, and relevant
-   project docs under \`${docsDir}/\` — start from the index at
-   \`${docsDir}/README.md\`, which lists the reading order. Before reading a
+   project docs under \`${docsDir}/\`. Maintain ${docsDir}/README.md as the
+   reading-order index as the doc set grows. Before reading a
    large file, run \`repoos outline <path>\` to get its symbols with line
    numbers, then read only the range you need instead of the whole file.
 2. Work in the task branch and dedicated worktree RepoOS assigned. The server
@@ -225,7 +225,7 @@ unless the human explicitly requests that separate workflow.
 
 The reviewer agent, when enabled, writes an advisory report in the task drawer.
 It does not edit code or replace human approval. After the human approves,
-use **Move to done** in RepoOS or \`POST /api/tasks/:id/done\`. The server
+use **Move to done** in RepoOS or POST /api/tasks/:id/done. The server
 merges the task into a separate candidate worktree, validates the combined
 result, rechecks the primary branch under a publication lock, publishes,
 cleans up, and records completion. \`repoos mv <id> done\` only changes metadata;
@@ -233,7 +233,7 @@ it does not run close-out or merge code.
 
 A direct commit on the primary branch is an exception requiring explicit
 human authorization. If that already-landed work has a branchless task record,
-the \`/done\` endpoint can check the primary checkout and record release without
+the /done endpoint can check the primary checkout and record release without
 a candidate merge. Do not erase a task's branch metadata to force this path.
 
 ## Rules
@@ -248,7 +248,7 @@ a candidate merge. Do not erase a task's branch metadata to force this path.
   invent ownership rules for RepoOS directories; the config is the only source
   of truth for layout.
 - **Never** move task files between folders. Status lives in frontmatter.
-- **Never write directly to \`${workDir}/*.md\` files.** All task creation and
+- **Never write directly to task files under \`${workDir}/\`.** All task creation and
   manipulation goes through \`repoos\` commands or HTTP API endpoints
   (\`POST /api/tasks\`, \`PATCH /api/tasks/:id\`, etc.). If the RepoOS server
   is unreachable, stop and report the issue — do not hand-write task files.
@@ -306,7 +306,7 @@ active/review.
 ## Declaring evidence shots (## Shots)
 
 A task body may carry a \`## Shots\` section with a fenced JSON list of capture
-entries (see \`src/core/shot-plan.ts\`). Each entry has \`target\`, \`route\`, an
+entries (see https://docs.repoos.org/cli#the-tasks-shots-list). Each entry has \`target\`, \`route\`, an
 optional \`selector\` (element crop — the exception), an optional \`highlight\`
 CSS selector (outlines changed elements), a \`label\`, and optional ordered
 \`steps\` (click/fill/wait, plain CSS selectors). Use \`repoos update <id>
@@ -315,9 +315,9 @@ fenced section) without touching the rest of the body — a full \`--body\` repl
 Problem / Desired UX / Acceptance criteria / Notes for AI is refused unless
 \`--force\` is passed.
 
-For tabbed views (e.g. Agents), prefer \`?tab=<id>\` routes
-(\`/agents?tab=detected\`) over click steps to reach the right tab; a task drawer
-is reached the same way (\`/work?task=<id>&tab=changes\`), and always
+For tabbed views (e.g. Agents), prefer ?tab=<id> routes
+(/agents?tab=detected) over click steps to reach the right tab; a task drawer
+is reached the same way (/work?task=<id>&tab=changes), and always
 set \`highlight\` to the changed elements. Reach a populated state with a
 \`route\` or a named \`state\` fixture, never with \`steps\` that click a
 placeholder selector (\`data-task-id "9999"\` and the like) — such a step times
@@ -1724,7 +1724,7 @@ async function guidedNewRepo(opts) {
     if (!gitOk) {
         console.log(c.yellow("\n  Warning: git doesn't appear to be installed — scaffolding without git."));
     }
-    else if (!gitConfig(target, "user.name") && !gitConfig(target, "user.email")) {
+    else if (!gitIdentityConfigured(target)) {
         console.log(c.yellow("\n  Warning: no git identity is configured."));
         console.log(c.dim("    git may auto-detect it, or the initial commit may fail. Set it with:"));
         console.log(c.dim('    git config --global user.name "You" && git config --global user.email you@example.com'));

package/dist/commands/schedule.js

@@ -10,7 +10,7 @@ import { commitTaskFile } from "../core/git.js";
 import { c } from "../cli/colors.js";
 import { createRepoOS } from "../core/repoos.js";
 import { computeNextRun, formatNextRunPreview, } from "../core/schedule-time.js";
-import { createSchedule, getSchedule, listSchedules, updateSchedule, validateScheduleInput, } from "../core/schedule.js";
+import { createSchedule, getSchedule, listSchedules, scheduleTemplateWarning, updateSchedule, validateScheduleInput, } from "../core/schedule.js";
 import { executeScheduleRun, findDueSchedule, releaseScheduleOccurrenceLock, tryAcquireScheduleOccurrenceLock, } from "../server/schedule-runner.js";
 import { scheduleHostileReason, scheduleRunRefusalMessage } from "../server/schedule-automation.js";
 import { deleteScheduleDataFile } from "../server/write.js";
@@ -132,6 +132,16 @@ function flagsToCreateInput(flags, fallback) {
         body: flags.body ?? fallback?.body,
     };
 }
+function printScheduleTemplateWarning(input) {
+    const detail = scheduleTemplateWarning({
+        body: input.body ?? "",
+        taskArea: input.taskArea,
+        taskAssignedTo: input.taskAssignedTo,
+    });
+    if (detail) {
+        console.log(c.yellow("  warning: ") + c.dim("schedule template is underspecified — ") + detail);
+    }
+}
 export function cmdScheduleList(args) {
     const { flags, error } = parseScheduleFlags(args);
     if (error) {
@@ -207,6 +217,7 @@ export function cmdScheduleNew(args) {
         const created = createSchedule(config, input);
         const committed = commitSchedule(config.root, created.path, created.id, "create");
         console.log(c.green(`  created schedule #${created.id}  ${created.title}`));
+        printScheduleTemplateWarning(input);
         if (!committed)
             console.log(c.yellow("  warning: ") + c.dim("file left uncommitted"));
     }
@@ -270,6 +281,9 @@ export function cmdScheduleUpdate(args) {
         const updated = updateSchedule(config, existing.id, patch);
         const committed = commitSchedule(config.root, updated.path, updated.id, "update");
         console.log(c.green(`  updated schedule #${updated.id}`));
+        const merged = flagsToCreateInput(flags, existing);
+        if (merged)
+            printScheduleTemplateWarning(merged);
         if (!committed)
             console.log(c.yellow("  warning: ") + c.dim("file left uncommitted"));
     }

package/dist/commands/serve-banner.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { renderServeBanner } from "./serve.js";
+import { formatServeBindBannerValue, renderServeBanner } from "./serve.js";
 describe("renderServeBanner", () => {
     const rows = [
         { label: "Local", value: "http://127.0.0.1:7515" },
@@ -10,6 +10,29 @@ describe("renderServeBanner", () => {
         expect(out).toContain("RepoOS v1.2.3");
         expect(out).toContain("Local          http://127.0.0.1:7515");
     });
+    it("names the bind address on localhost and tailnet rows", () => {
+        const localOnly = renderServeBanner("1.0.0", [
+            { label: "Bind", value: formatServeBindBannerValue("127.0.0.1", false) },
+            { label: "Local", value: "http://127.0.0.1:7515" },
+        ]);
+        expect(localOnly).toMatch(/Bind\s+127\.0\.0\.1/);
+        const tailscale = renderServeBanner("1.0.0", [
+            {
+                label: "Bind",
+                value: formatServeBindBannerValue("0.0.0.0", true),
+            },
+            { label: "Local", value: "http://127.0.0.1:7515" },
+            { label: "Tailnet", value: "http://100.64.0.1:7515" },
+        ]);
+        expect(tailscale).toMatch(/Bind\s+0\.0\.0\.0/);
+        expect(tailscale).toContain("--host 127.0.0.1");
+    });
+    it("formatServeBindBannerValue uses tailscaleDetected, not host alone", () => {
+        expect(formatServeBindBannerValue("0.0.0.0", false)).toContain("explicit --host");
+        expect(formatServeBindBannerValue("0.0.0.0", false)).not.toContain("Tailscale detected");
+        expect(formatServeBindBannerValue("0.0.0.0", true)).toContain("Tailscale detected");
+        expect(formatServeBindBannerValue("192.168.1.5", false)).toContain("192.168.1.5");
+    });
     it("splits an HTTPS warning into problem, fix and link", () => {
         const out = renderServeBanner("1.2.3", rows, "HTTPS certificates aren't enabled for your tailnet — turn on MagicDNS and HTTPS Certificates at https://login.tailscale.com/admin/dns");
         expect(out).toContain("Tailscale HTTPS unavailable");

package/dist/commands/serve.d.ts

@@ -40,6 +40,11 @@ export declare function resolveServeHost(explicitHost?: string): {
     tailscaleDetected: boolean;
     tailscaleIP?: string;
 };
+/**
+ * Bind row text for the serve startup banner. Uses {@link tailscaleDetected},
+ * not `host === "0.0.0.0"`, so an explicit `--host 0.0.0.0` is not mislabeled.
+ */
+export declare function formatServeBindBannerValue(host: string, tailscaleDetected: boolean): string;
 /**
  * Whether this `repoos serve` should apply the repo's preview-only
  * `[preview.*]` config overlay (#0464).

package/dist/commands/serve.js

@@ -81,6 +81,22 @@ export function resolveServeHost(explicitHost) {
         return { host: "0.0.0.0", tailscaleDetected: true, tailscaleIP };
     return { host: "127.0.0.1", tailscaleDetected: false };
 }
+/**
+ * Bind row text for the serve startup banner. Uses {@link tailscaleDetected},
+ * not `host === "0.0.0.0"`, so an explicit `--host 0.0.0.0` is not mislabeled.
+ */
+export function formatServeBindBannerValue(host, tailscaleDetected) {
+    if (tailscaleDetected) {
+        return (c.cyan("0.0.0.0") +
+            c.dim(" (all interfaces — Tailscale detected; pass ") +
+            c.cyan("--host 127.0.0.1") +
+            c.dim(" for localhost only)"));
+    }
+    if (host === "127.0.0.1") {
+        return c.cyan("127.0.0.1") + c.dim(" (localhost only)");
+    }
+    return c.cyan(host) + c.dim(" (explicit --host)");
+}
 /**
  * Whether this `repoos serve` should apply the repo's preview-only
  * `[preview.*]` config overlay (#0464).
@@ -225,6 +241,10 @@ export async function cmdServe(args, opts = {}) {
         ? `Bun ${process.versions.bun ?? ""}`.trim()
         : `Node ${process.versions.node}`;
     const rows = [
+        {
+            label: "Bind",
+            value: formatServeBindBannerValue(host, tailscaleDetected),
+        },
         { label: "Local", value: c.cyan(c.bold(handle.url)) },
         { label: "Events", value: c.cyan(handle.url + "/api/events") + c.dim("  (SSE)") },
         { label: "Watching", value: `${snap.taskCount} tasks` },

package/dist/commands/status.js

@@ -22,7 +22,7 @@ import { checkBuildForRoot, readBuildMeta, readBuildStamp } from "../core/build.
 import { isManagedService } from "../core/service-manager.js";
 import { readTunnelConfig } from "../core/tunnel.js";
 import { readRegistry, reconcileIdentity, syncFromRepo, unionApps, } from "../core/tunnel-registry.js";
-import { currentBranch, runGit } from "../core/git.js";
+import { currentBranch, isGitRepo, runGit } from "../core/git.js";
 import { countWorktrees, formatGcEntryDetails, sweepStaleWorktrees } from "../core/worktree-gc.js";
 import { isOrphanServeCommand, isPortListening } from "../server/serve-reaper.js";
 import { STATUSES } from "../core/types.js";
@@ -683,7 +683,7 @@ export function renderStatus(s, now = new Date()) {
     }
     // git
     if (!s.git.branch) {
-        row("git", c.dim("not a git repository"));
+        row("git", c.dim(isGitRepo(s.root) ? "unknown branch" : "not a git repository"));
     }
     else {
         const bits = [c.cyan(s.git.branch)];

package/dist/commands/tasks.js

@@ -105,7 +105,7 @@ async function listTasksViaApi(statusArg) {
         return { rootName: root.split("/").pop() ?? "repo", tasks };
     }
     catch (error) {
-        console.warn(`[repoos] task API unavailable; falling back to the local index: ${error instanceof Error ? error.message : String(error)}`);
+        console.warn(`[repoos] Server unavailable — using local index. Start with \`repoos serve\`.`);
         return null;
     }
 }

package/dist/commands/uninstall.d.ts

@@ -1,6 +1,9 @@
 export interface StandaloneUninstallPlan {
     installDir: string;
+    /** True when the tarball was unpacked into the state directory (pre-split installs). */
+    legacyCombined: boolean;
     launcherPath: string | null;
+    stateDir: string;
 }
 /**
  * Return the files owned by a default curl install, or null for every other

package/dist/commands/uninstall.js

@@ -1,17 +1,20 @@
 /**
  * `repoos uninstall` — remove a standalone install created by install.sh.
  *
- * This deliberately has a narrow scope. It never removes a source checkout or
- * a package-manager install, and it leaves project data and user configuration
- * alone. Package-manager installs must be removed by their package manager.
+ * Removes the install directory (`~/.local/share/repoos`, or a legacy
+ * `~/.repoos` payload) and the machine state entries RepoOS created there.
+ * Per-repo files (`repoos.toml`, a repo's `.repoos/` cache) are not touched.
+ * A package-manager install is not deleted; the command names the package
+ * manager command and any machine state that remains.
  */
-import { existsSync, readFileSync, rmSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, rmSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { c } from "../cli/colors.js";
-import { launcherScript } from "./upgrade.js";
+import { STANDALONE_INSTALL_PAYLOAD, classifyMachineState, isStandaloneInstallDir, machineStateDir, } from "../core/install-layout.js";
+import { launcherScript, packageManagerUpgrade } from "./upgrade.js";
 /**
  * Return the files owned by a default curl install, or null for every other
  * kind of execution (source checkout, npm/Bun, custom installation, etc.).
@@ -21,8 +24,8 @@ import { launcherScript } from "./upgrade.js";
  */
 export function standaloneUninstallPlan(entryPath, home = homedir(), binDir = join(home, ".local", "bin")) {
     const installDir = dirname(dirname(entryPath));
-    const expectedInstallDir = join(home, ".repoos");
-    if (installDir !== expectedInstallDir || !existsSync(join(installDir, "cli", "index.js"))) {
+    if (!isStandaloneInstallDir(installDir, home) ||
+        !existsSync(join(installDir, "cli", "index.js"))) {
         return null;
     }
     const launcherPath = join(binDir, "repoos");
@@ -35,12 +38,18 @@ export function standaloneUninstallPlan(entryPath, home = homedir(), binDir = jo
     catch {
         // A launcher we cannot read is not safe to remove.
     }
-    return { installDir, launcherPath: ownsLauncher ? launcherPath : null };
+    const stateDir = machineStateDir(home);
+    return {
+        installDir,
+        legacyCombined: installDir === stateDir,
+        launcherPath: ownsLauncher ? launcherPath : null,
+        stateDir,
+    };
 }
 async function confirm() {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     try {
-        const answer = (await rl.question("  Remove the standalone RepoOS install? [y/N] "))
+        const answer = (await rl.question("  Remove the standalone RepoOS install and its machine state? [y/N] "))
             .trim()
             .toLowerCase();
         return answer === "y" || answer === "yes";
@@ -49,27 +58,68 @@ async function confirm() {
         rl.close();
     }
 }
-function printPackageManagerRemoval() {
+function printPackageManagerRemoval(home) {
     console.log(c.yellow("  repoos was installed via a package manager."));
-    console.log(c.dim("  Remove it with the same package manager:"));
+    console.log(c.dim("  Remove the package with the same package manager:"));
     console.log(c.dim("    npm uninstall -g @repo-os/repoos"));
     console.log(c.dim("    bun remove -g @repo-os/repoos"));
     console.log(c.dim("    pnpm remove -g @repo-os/repoos"));
-    console.log(c.dim("    mise unuse --global npm:@repo-os/repoos"));
+    console.log(c.dim("    brew uninstall repoos"));
+    console.log(c.dim("  mise is not a supported install method. If you used it anyway, remove the shim with:"));
+    console.log(c.dim("    mise unuse --global npm:@repo-os/repoos && mise prune"));
+    const stateDir = machineStateDir(home);
+    const { remove, keep } = classifyMachineState(stateDir);
+    if (remove.length === 0 && keep.length === 0 && !existsSync(join(stateDir, "cli", "index.js"))) {
+        console.log(c.dim("  No machine state was found in ~/.repoos."));
+        return;
+    }
+    console.log(c.dim("  This command did not delete machine state. Still on disk:"));
+    for (const name of remove)
+        console.log(c.dim(`    ${join(stateDir, name)}`));
+    for (const name of keep)
+        console.log(c.dim(`    ${join(stateDir, name)}`));
+    if (existsSync(join(stateDir, "cli", "index.js"))) {
+        console.log(c.dim(`    ${join(stateDir, "cli")} (legacy install payload)`));
+    }
 }
 function printSourceRemoval() {
     console.log(c.yellow("  repoos appears to be running from a source checkout, not a standalone install."));
     console.log(c.dim("  There is nothing for RepoOS to uninstall. Remove the checkout only if you no longer need it."));
 }
+function removeStandalone(plan) {
+    if (plan.launcherPath)
+        rmSync(plan.launcherPath, { force: true });
+    if (plan.legacyCombined) {
+        for (const name of STANDALONE_INSTALL_PAYLOAD) {
+            rmSync(join(plan.installDir, name), { recursive: true, force: true });
+        }
+    }
+    else {
+        rmSync(plan.installDir, { recursive: true, force: true });
+        for (const name of STANDALONE_INSTALL_PAYLOAD) {
+            rmSync(join(plan.stateDir, name), { recursive: true, force: true });
+        }
+    }
+    const { remove, keep } = classifyMachineState(plan.stateDir);
+    const removedState = [];
+    for (const name of remove) {
+        rmSync(join(plan.stateDir, name), { recursive: true, force: true });
+        removedState.push(name);
+    }
+    if (existsSync(plan.stateDir) && readdirSync(plan.stateDir).length === 0) {
+        rmSync(plan.stateDir, { recursive: true, force: true });
+    }
+    return { removedState, keptState: keep };
+}
 export async function cmdUninstall(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log("\n  Usage: repoos uninstall [--yes]\n\n  Remove the default standalone install created by install.sh.\n  Project data and user configuration are left untouched.\n");
+        console.log("\n  Usage: repoos uninstall [--yes]\n\n  Remove the standalone install created by install.sh (~/.local/share/repoos,\n  or a legacy ~/.repoos payload) and machine state under ~/.repoos\n  (servers, services.json, local-check-slots, agent-run-tmp).\n  Other files in ~/.repoos are listed and left in place.\n  Per-repo files are not removed. A package-manager install is not deleted;\n  the command prints that package manager's uninstall and any state left behind.\n");
         return;
     }
     const entryPath = fileURLToPath(import.meta.url);
     const root = dirname(dirname(entryPath));
-    if (root.includes("node_modules")) {
-        printPackageManagerRemoval();
+    if (packageManagerUpgrade(root)) {
+        printPackageManagerRemoval(homedir());
         return;
     }
     const plan = standaloneUninstallPlan(entryPath);
@@ -86,26 +136,39 @@ export async function cmdUninstall(args) {
             return;
         }
         if (!(await confirm())) {
-            console.log(c.dim("  Kept the standalone RepoOS install."));
+            console.log(c.dim("  Kept the standalone RepoOS install and machine state."));
             return;
         }
     }
+    let removed;
     try {
-        if (plan.launcherPath)
-            rmSync(plan.launcherPath, { force: true });
-        rmSync(plan.installDir, { recursive: true, force: true });
+        removed = removeStandalone(plan);
     }
     catch (e) {
         console.error(c.red("  Failed to remove the standalone install: " + e.message));
         process.exitCode = 1;
         return;
     }
-    console.log(c.green("  Removed the standalone RepoOS install."));
+    console.log(c.green(`  Removed the standalone RepoOS install at ${plan.installDir}.`));
     if (plan.launcherPath) {
         console.log(c.dim(`  Removed launcher: ${plan.launcherPath}`));
     }
     else {
         console.log(c.dim("  Kept ~/.local/bin/repoos because it is not the launcher this install created."));
     }
-    console.log(c.dim("  Your RepoOS projects and user configuration were not changed."));
+    if (removed.removedState.length > 0) {
+        console.log(c.dim("  Removed machine state:"));
+        for (const name of removed.removedState) {
+            console.log(c.dim(`    ${join(plan.stateDir, name)}`));
+        }
+    }
+    else {
+        console.log(c.dim("  No RepoOS machine state entries were present under ~/.repoos."));
+    }
+    if (removed.keptState.length > 0) {
+        console.log(c.dim("  Left these entries in ~/.repoos (not created by RepoOS):"));
+        for (const name of removed.keptState)
+            console.log(c.dim(`    ${join(plan.stateDir, name)}`));
+    }
+    console.log(c.dim("  Per-repo files were not removed (repoos.toml and each repo's .repoos/ directory)."));
 }