kankaku 1.0.2 → 1.2.0

package/README.md

@@ -81,14 +81,16 @@ The wizard's steps, `enter` to advance and `esc` to go back throughout
    below.
 2. **Hub** — `use an existing hub` (URL, email, masked password, a `c`
    inline health check, reusing the current credentials as the default),
-   `install locally`, or `skip`. Installing locally asks only for the
-   owner's email and password and then runs the same installer as
-   `kankaku hub install` (see "Local hub" below): no `kankaku-hub`
-   checkout is needed, and the wizard writes the local hub's service
-   account as this machine's hub credentials. The wizard always uses the
-   default port; if another process already holds it the step fails with
-   the port-in-use message, and `kankaku hub install --port <N>` is the
-   way to pick another one.
+   `install locally`, or `skip`. Installing locally asks for the owner's
+   email and password and a `port` (digits only, 1024-65535), then runs
+   the same installer as `kankaku hub install` (see "Local hub" below): no
+   `kankaku-hub` checkout is needed. The port field starts at the first
+   free port from 8090 upwards (or at the port of an existing install)
+   and rejects a port that is in use inline (`port <N> is in use`). The
+   Review step says what happens to the sync credentials: either
+   `sync credentials → the local hub`, or `sync credentials stay on <url>
+   (switch later with kankaku hub use)` when this machine already syncs to
+   another hub.
 3. **Roots** — the comma-separated project roots, defaulting to the
    current `tui.json` (or the parent of the current directory the first
    time). See "Configuration" below for how deep each root is searched.
@@ -265,9 +267,18 @@ sets up and runs your own hub on this machine, under `~/.kankaku/hub/`:
 - `accounts.json` (owner-only, `0600`) — the PocketBase superuser email
   and generated password, and the owner account's email. The owner logs
   into the hub's own web admin UI with that owner account.
-- `~/.kankaku/credentials.json` — the generated `service` account
-  (`kankaku-sync@kankaku.local`) this app and kankaku's own sync already
-  read, exactly like a remote hub's credentials.
+- `service.json` (owner-only, `0600`) — the generated `service` account
+  (`kankaku-sync@kankaku.local`) as `{ url, email, password }`. Install
+  always writes it.
+
+Install never repoints where this machine syncs on its own.
+`~/.kankaku/credentials.json` (the file this app and kankaku's own sync
+read) is written by install only when it does not exist yet, or when its
+`url` already is this local hub's (same host and port). When it points at
+another hub it is left untouched, and the install report says so with a
+`sync credentials` step: `this machine syncs to <url>; run 'kankaku hub
+use' to switch to the local hub`. `kankaku hub use` is the explicit
+switch.
 
 Commands (macOS and Linux only — PocketBase ships no other build):
 
@@ -275,15 +286,33 @@ Commands (macOS and Linux only — PocketBase ships no other build):
   — installs (or, run again, verifies) the hub and leaves it running. On
   a real terminal, a missing owner email/password is prompted for
   (masked); without a TTY, both flags are required. Idempotent: re-running
-  with everything already in place changes nothing. If another process
-  already answers on the target port, `install`/`start`/`upgrade` refuse
-  with `port <N> is already in use by another process — pass --port <N>
-  or stop it` instead of provisioning accounts against it; pass a
-  different `--port` or free the port and retry.
+  with everything already in place changes nothing, and an existing
+  install keeps its recorded port. Without `--port`, a fresh install uses
+  8090 when it is free; when it is not, install fails (exit 1) with `port
+  8090 is already in use — try: kankaku hub install --port <first free>`
+  and never picks a port silently. A `--port` that is taken fails the same
+  way, with the existing message plus the suggestion; a `--port` that is
+  not a whole number between 1 and 65535 is a usage error. The check binds
+  `127.0.0.1:<port>` before anything is downloaded or created, and the
+  pre-spawn health check still runs after it. `start` and `upgrade` refuse
+  with `port <N> is already in use by another process — pass --port <N> or
+  stop it` when a foreign process holds the recorded port. Re-running
+  install on a hub made by an older version, which has no `service.json`,
+  writes it when the service password is still known (it is in
+  `credentials.json`); otherwise it says the password is not recoverable
+  and does not invent one.
+- `kankaku hub use` — points `~/.kankaku/credentials.json` at the local
+  hub, from `service.json` (the previous file is kept once as
+  `credentials.json.bak`, mode `0600`) and prints `sync now points at
+  <local url> (was <previous url>)`. Running it again reports `unchanged`.
+  It fails (exit 1) when no local hub is installed or `service.json` is
+  missing.
 - `kankaku hub start` / `kankaku hub stop` — start or stop the server
   process; `stop` is a no-op when it isn't running.
 - `kankaku hub status` — `local hub: running 0.2.0 (PocketBase 0.40.4) at
-  http://127.0.0.1:8090 · pb_data 1.2 MB`, `stopped`, or `not installed`.
+  http://127.0.0.1:8090 · pb_data 1.2 MB`, `stopped`, or `not installed`,
+  followed by where this machine's sync points: `sync: local hub`,
+  `sync: <other url>` or `sync: not configured`.
 - `kankaku hub upgrade` — copies a fresh `app/<version>/` from the
   currently installed `kankaku-hub` package, downloads a new PocketBase
   binary only if that version changed, and restarts — `pb_data` is never
@@ -318,8 +347,12 @@ developers via `kankaku setup --from-checkout <dir>`.
   checkout-based local hub install, see "Local hub" above.
 - `kankaku doctor` — the same read-only report `kankaku setup` ends with,
   without prompting or writing anything.
-- `kankaku hub install|start|stop|status|upgrade|logs` — the local hub's
-  lifecycle; see "Local hub" above.
+- `kankaku hub install|use|start|stop|status|upgrade|logs` — the local
+  hub's lifecycle; see "Local hub" above.
+- `kankaku --version`, `kankaku -v` or `kankaku version` — prints `kankaku
+  <version>` and, indented, the version of each package it carries
+  (`kankaku-pi`, `kankaku-claude`, `kankaku-hub`), or `not found` for one
+  that cannot be resolved; exit 0.
 
 `--roots` (on `today`/`tasks`) overrides the configured roots for that run.
 
@@ -412,7 +445,8 @@ the hub has no credentials — in which case `c`/`s`/`S` do nothing.
 - **Tasks** — a table (time, project, work, cost, prompt) with a
   highlighted row on the left, and a `[ Task ]` detail panel on the right
   showing the selected row's full prompt, client, project, hub task,
-  wall/work/wait time, cost, cache hit and subagent count.
+  wall/work/wait time, cost, cache hit and subagent count. `m` and `M`
+  move (reassign) hub rows (see "Reassigning from the Tasks screen" below).
 - **Catalog** — `[ Clients ]` on the left; the selected client's
   `[ Projects ]`, with open/doing hub task counts, on the right. The
   Clients panel header shows the cache's age and a `(stale)` flag.
@@ -420,6 +454,64 @@ the hub has no credentials — in which case `c`/`s`/`S` do nothing.
   highlighted, and each action's result line shows inside its card while
   it runs and once it settles.
 
+### Reassigning from the Tasks screen
+
+Sync never changes the assignment of a row that is already on the hub
+(it stays create-only, so a reassignment made anywhere is never undone by
+a later sync). The Tasks screen is the explicit way to change it from
+kankaku: with the content zone focused, `m` moves (reassigns) the selected task
+and `M` reassigns every task of the current view (the project filter and
+the today/all scope) whose hub row is on the unassigned client.
+
+Before anything opens, kankaku asks the hub for the rows involved (the
+footer shows `asking the hub…`) and refreshes the catalog. If the hub is
+not configured, rejects the credentials or cannot be reached, the footer
+says so and nothing opens; so does `m` on a task that is not on the hub
+yet (`not on the hub yet — sync first`) and `M` when no task of the view
+is unassigned there.
+
+The picker is a panel over the content zone with its own footer hints:
+
+1. **Client** — the active clients, with the unassigned client last, as
+   `unassigned`.
+2. **Project** — the client's active projects, plus `no project`.
+3. **Task** — the project's tasks that are not done, plus `no task`.
+   Skipped when `no project` was chosen.
+4. **Review** — one line per row, `current → new` by names, the count of
+   rows that will change and what will not be touched. `enter` applies.
+5. **Result** — one line per row (`reassigned`, `unchanged`, or
+   `failed: <reason>`); a failure never stops the remaining rows. `enter`
+   or `esc` returns to the list, which then shows the hub's assignment
+   (`hub …`) in the detail panel next to the local one, for the rows asked
+   about in this session.
+
+`↑`/`↓`/`PageUp`/`PageDown`/`Home`/`End` move inside a step, `enter`
+advances and `esc` (or `←`) goes back one step, closing the picker at the
+first. While the picker is open, the screen's other keys and the app's
+own `esc`/`←`/`Tab`/`1`-`4` are inert; `q` still quits.
+
+What it does and does not do:
+
+- Each changed row gets one `PATCH` of `{ client, project, task }` (an
+  empty relation is sent as `""`). Nothing else is written: not
+  `legacy_client_label`, not any measurement field.
+- The selection is checked against the catalog before any request: the
+  project must belong to the client, the task to the project, all
+  active, the task not done. The picker cannot build an inconsistent
+  choice, and the planner rejects one anyway (the hub itself only checks
+  that each id exists).
+- `M` only ever touches rows that are on the unassigned client on the
+  hub; a row that already has a real assignment is never changed by it.
+  Use `m` on that task to move it deliberately.
+- The local worklog is never rewritten; the Tasks screen keeps showing
+  the local assignment. After a reassignment the hub's assignment is shown
+  next to it for the rows asked about in this session.
+- Tasks that are not on the hub yet must be synced first (Sync screen or
+  `kankaku sync`).
+- The hub keeps no record of who reassigned a row or when. The
+  service account must be allowed to update `task_entries` (the hub's
+  `owner` and `service` roles are).
+
 ## Keys (TUI)
 
 The app has two focus zones — the sidebar and the active screen's own main
@@ -455,9 +547,11 @@ jump to the first/last row.
   (filtered to it), `r` refresh; the Quick actions panel additionally
   takes `c` (refresh catalog), `s` (sync all projects) and `S` (full sync
   all) — one at a time, ignored while another is running.
-- **Tasks** — `a` toggle today/all, `↑`/`↓`/`PageUp`/`PageDown`/`Home`/`End`
-  move the selection, `r` refresh, `esc` clears a project filter set from
-  Dashboard.
+- **Tasks** — `a` toggle today/all,
+  `↑`/`↓`/`PageUp`/`PageDown`/`Home`/`End` move the selection, `r` refresh,
+  `m` move (reassign) the selected task on the hub, `M` move every task of
+  the view that is unassigned on the hub (both open the picker, see above),
+  `esc` clears a project filter set from Dashboard.
 - **Catalog** — `↑`/`↓`/`PageUp`/`PageDown`/`Home`/`End` move the client
   selection, `r` refresh from the hub.
 - **Sync** — `↑`/`↓`/`PageUp`/`PageDown`/`Home`/`End` move the selection,
@@ -469,4 +563,6 @@ The TUI never writes to disk on its own — Dashboard, Tasks and read-only
 Catalog views write nothing at all; Catalog's `refresh`, Sync's
 `s`/`f`/`S` and Dashboard's Quick actions `c`/`s`/`S` write only through
 kankaku's own adapters (`CachedCatalog`, `SyncStateStore`, the hub
-itself), exactly as kankaku's own sync paths do.
+itself), exactly as kankaku's own sync paths do. Tasks' `m`/`M` write
+nothing to disk either (apart from the catalog cache refresh): they change
+the hub's rows only, after the picker's Review step.

package/dist/adapters/hub-manager/credentials.js

@@ -0,0 +1,58 @@
+/**
+ * The local hub's service account and where this machine's sync points.
+ * Install always stores the service account in `~/.kankaku/hub/service.json`
+ * (0600); `~/.kankaku/credentials.json` is a separate decision, made by
+ * `installHub` (only when none exists or it already points here) and by
+ * `useLocalHub` (`kankaku hub use`, explicit).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { hubLayout, parseServiceAccount } from "../../domain/local-hub-model.js";
+import { credentialsPath, writeHubCredentials } from "../setup/hub.js";
+import { readJsonObjectOrEmpty, writeJsonAtomic } from "../setup/json-writer.js";
+const OWNER_FILE_MODE = 0o600;
+/** `~/.kankaku/hub/service.json`, or `undefined` when it is missing or malformed. Never throws. */
+export function readServiceAccount(homeDir) {
+    const file = hubLayout(homeDir).serviceJson;
+    if (!existsSync(file))
+        return undefined;
+    try {
+        return parseServiceAccount(JSON.parse(readFileSync(file, "utf8")));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Writes `account` to `~/.kankaku/hub/service.json` (0600, tmp + rename); a no-op when it already holds exactly these values. */
+export function writeServiceAccount(homeDir, account) {
+    const current = readServiceAccount(homeDir);
+    if (current && current.url === account.url && current.email === account.email && current.password === account.password)
+        return { changed: false };
+    writeJsonAtomic(hubLayout(homeDir).serviceJson, { url: account.url, email: account.email, password: account.password }, undefined, OWNER_FILE_MODE);
+    return { changed: true };
+}
+/** The `url` currently in `~/.kankaku/credentials.json`, or `undefined` when there is none. */
+export function readCredentialsUrl(homeDir) {
+    const url = readJsonObjectOrEmpty(credentialsPath(homeDir))["url"];
+    return typeof url === "string" && url !== "" ? url : undefined;
+}
+/**
+ * `kankaku hub use`: points `credentials.json` at the local hub's service
+ * account (`service.json`), keeping the one-time `.bak` of the previous
+ * file. Needs an installed local hub and its `service.json`; idempotent.
+ */
+export function useLocalHub(homeDir) {
+    const layout = hubLayout(homeDir);
+    if (!existsSync(layout.hubJson)) {
+        return { ok: false, error: "no local hub is installed; run: kankaku hub install" };
+    }
+    const service = readServiceAccount(homeDir);
+    if (!service) {
+        return {
+            ok: false,
+            error: "the local hub has no service.json (an install made by an older version does not write one); run 'kankaku hub install' again - it is idempotent and writes it when the service password is still known",
+        };
+    }
+    const previousUrl = readCredentialsUrl(homeDir);
+    const written = writeHubCredentials(homeDir, service);
+    return { ok: true, changed: written.changed, url: service.url, ...(previousUrl !== undefined ? { previousUrl } : {}) };
+}

package/dist/adapters/hub-manager/install.js

@@ -9,12 +9,15 @@
  */
 import { chmodSync, cpSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { assetKeyFor, classifyStatus, generatePassword, hubLayout, parseHubConfig, serveArgs, } from "../../domain/local-hub-model.js";
+import { assetKeyFor, classifyStatus, generatePassword, hubLayout, credentialsKeptDetail, parseHubConfig, sameHubUrl, serveArgs, shouldWriteCredentials, } from "../../domain/local-hub-model.js";
 import { locateHubPackage } from "./package.js";
 import { downloadPocketBase } from "./download.js";
 import { isAlive, readPid, stopProcess, waitForHealth } from "./process.js";
+import { firstFreePort, isPortFree } from "./port-probe.js";
 import { createUser, upsertSuperuser } from "./accounts.js";
-import { writeHubCredentials } from "../setup/hub.js";
+import { credentialsPath, writeHubCredentials } from "../setup/hub.js";
+import { readJsonObjectOrEmpty } from "../setup/json-writer.js";
+import { readCredentialsUrl, readServiceAccount, writeServiceAccount } from "./credentials.js";
 const OWNER_DIR_MODE = 0o700;
 const OWNER_FILE_MODE = 0o600;
 /** The PocketBase superuser account this package provisions on first install; distinct from the owner/service application users. */
@@ -55,8 +58,14 @@ function readLogLines(layout) {
         lines.pop();
     return lines;
 }
-function portInUseMessage(port) {
-    return `port ${port} is already in use by another process — pass --port <N> or stop it`;
+/** The message when a foreign process holds `port`; `suggestion` (the first free port above it) adds the command that would work. */
+function portInUseMessage(port, suggestion) {
+    const base = `port ${port} is already in use by another process — pass --port <N> or stop it`;
+    return suggestion === undefined ? base : `${base}; try: kankaku hub install --port ${suggestion}`;
+}
+/** The first free port above `port`, for a "try: kankaku hub install --port N" suggestion; `undefined` when none of the next 20 is free. */
+function suggestPortAbove(port, deps) {
+    return firstFreePort(port + 1, 20, deps.portBinder);
 }
 /**
  * Before spawning: if `GET /api/health` on `port` answers at all (ok or
@@ -64,17 +73,32 @@ function portInUseMessage(port) {
  * held by a process that is not ours. Callers only reach this once they
  * have already established that no pid of ours is alive, so any response
  * here means a foreign process. Returns the detail message to report, or
- * `undefined` when the port is free.
+ * `undefined` when the port is free. `suggest` (install only) appends the
+ * first free port to try instead.
  */
-async function ensurePortFree(port, deps) {
+async function ensurePortFree(port, deps, suggest = false) {
     try {
         await deps.fetch(`${baseUrlFor(port)}/api/health`);
-        return portInUseMessage(port);
+        return portInUseMessage(port, suggest ? await suggestPortAbove(port, deps) : undefined);
     }
     catch {
         return undefined;
     }
 }
+/**
+ * The earlier, cheaper check of a fresh install: binds `127.0.0.1:<port>`.
+ * `explicit` (a `--port` was given) keeps the existing message and adds the
+ * first free port; without `--port` the default is never swapped silently -
+ * the message names the first free port to pass instead.
+ */
+async function checkPortBindable(port, explicit, deps) {
+    if (await isPortFree(port, deps.portBinder))
+        return undefined;
+    const suggestion = await suggestPortAbove(port, deps);
+    if (explicit)
+        return portInUseMessage(port, suggestion);
+    return suggestion === undefined ? `port ${port} is already in use` : `port ${port} is already in use — try: kankaku hub install --port ${suggestion}`;
+}
 /**
  * Spawns the hub detached and waits for it to become healthy, stopping
  * immediately (rather than waiting out the full timeout) if the process
@@ -103,6 +127,51 @@ function healthFailureDetail(layout, exitedEarly) {
     const lastLine = readLogLines(layout).at(-1);
     return lastLine ? `the hub exited during startup: ${lastLine}` : "the hub exited during startup";
 }
+/**
+ * Stores the local hub's service account in `service.json` (always) and
+ * decides what happens to `~/.kankaku/credentials.json`: written only when
+ * none exists or it already points at this local hub, otherwise left
+ * byte-for-byte untouched with a step saying how to switch (`kankaku hub
+ * use`). Returns the two report steps.
+ */
+function storeServiceAccount(homeDir, account, recoveredFrom) {
+    const serviceResult = writeServiceAccount(homeDir, account);
+    const steps = [
+        { step: "write service.json", outcome: serviceResult.changed ? "done" : "unchanged", ...(recoveredFrom ? { detail: recoveredFrom } : {}) },
+    ];
+    const existingUrl = readCredentialsUrl(homeDir);
+    if (!shouldWriteCredentials(existingUrl, account.url)) {
+        steps.push({ step: "sync credentials", outcome: "unchanged", detail: credentialsKeptDetail(existingUrl) });
+        return steps;
+    }
+    const written = writeHubCredentials(homeDir, account);
+    steps.push({ step: "sync credentials", outcome: written.changed ? "done" : "unchanged", detail: `points at ${account.url}` });
+    return steps;
+}
+/**
+ * Re-run on an install that already has accounts: `service.json` is kept up
+ * to date when it exists (its url follows the recorded port); an install
+ * made before `service.json` existed gets it back only when the service
+ * password is still known - it is in `credentials.json` (email and url are
+ * the local hub's). When it is not recoverable, says so and invents nothing.
+ */
+function ensureServiceAccount(homeDir, url) {
+    const stored = readServiceAccount(homeDir);
+    if (stored)
+        return storeServiceAccount(homeDir, { ...stored, url });
+    const credentials = readJsonObjectOrEmpty(credentialsPath(homeDir));
+    const { url: credentialsUrl, email, password } = credentials;
+    if (email === SERVICE_EMAIL && typeof password === "string" && password !== "" && typeof credentialsUrl === "string" && sameHubUrl(credentialsUrl, url)) {
+        return storeServiceAccount(homeDir, { url, email: SERVICE_EMAIL, password }, "recovered from credentials.json");
+    }
+    return [
+        {
+            step: "write service.json",
+            outcome: "unchanged",
+            detail: "the service account's password is not recoverable: it was not stored by the version that installed this hub and credentials.json does not hold it; none was invented",
+        },
+    ];
+}
 /**
  * Installs (or, run again, verifies) the local hub under
  * `~/.kankaku/hub`: locates the `kankaku-hub` package, creates the layout
@@ -112,13 +181,14 @@ function healthFailureDetail(layout, exitedEarly) {
  * package's migrations/hooks/public into `app/<version>/`, writes
  * `hub.json`, and — only the first time, when `accounts.json` doesn't
  * exist yet — provisions the superuser and the owner/service application
- * users, then leaves the server running. Idempotent: re-running with
- * everything already present reports every step `unchanged` and touches
+ * users, then leaves the server running. The service account always goes
+ * to `service.json`; `credentials.json` is written only when none exists
+ * or it already points at this hub (see `storeServiceAccount`). Idempotent:
+ * re-running with everything already present reports every step `unchanged` and touches
  * neither the process nor the accounts. Never throws; a failing step
  * stops the sequence and is reported as `error`.
  */
 export async function installHub(options, deps) {
-    const port = options.port ?? DEFAULT_HUB_PORT;
     const steps = [];
     let located;
     try {
@@ -129,13 +199,20 @@ export async function installHub(options, deps) {
     }
     const manifest = located.manifest;
     const layout = hubLayout(deps.homeDir);
+    // An existing install keeps its recorded port; a fresh one takes the default, and never a different one silently.
+    const existingConfig = readConfigOrUndefined(layout.hubJson);
+    const port = options.port ?? existingConfig?.port ?? DEFAULT_HUB_PORT;
+    if (!existsSync(layout.accountsJson)) {
+        const conflict = await checkPortBindable(port, options.port !== undefined, deps);
+        if (conflict)
+            return { ok: false, steps: [{ step: "check port", outcome: "error", detail: conflict }] };
+    }
     const rootExisted = existsSync(layout.root);
     if (!rootExisted)
         mkdirSync(layout.root, { recursive: true, mode: OWNER_DIR_MODE });
     mkdirSync(layout.bin, { recursive: true });
     mkdirSync(layout.pbData, { recursive: true });
     steps.push({ step: "create ~/.kankaku/hub", outcome: rootExisted ? "unchanged" : "done" });
-    const existingConfig = readConfigOrUndefined(layout.hubJson);
     const needsBinary = !existsSync(layout.binary) || existingConfig?.pocketbaseVersion !== manifest.pocketbase.version;
     if (needsBinary) {
         try {
@@ -177,11 +254,12 @@ export async function installHub(options, deps) {
     const accountsExist = existsSync(layout.accountsJson);
     if (accountsExist) {
         steps.push({ step: "provision accounts", outcome: "unchanged" });
+        steps.push(...ensureServiceAccount(deps.homeDir, baseUrlFor(port)));
         return { ok: true, steps, url: baseUrlFor(port) };
     }
     // Reported as its own step: a hub that cannot start is not an accounts
     // problem, and the accounts step must never claim to have run.
-    const portConflict = await ensurePortFree(port, deps);
+    const portConflict = await ensurePortFree(port, deps, true);
     if (portConflict) {
         steps.push({ step: "start hub", outcome: "error", detail: portConflict });
         return { ok: false, steps };
@@ -200,11 +278,12 @@ export async function installHub(options, deps) {
         await createUser(url, superuser, { email: options.ownerEmail, password: options.ownerPassword, role: "owner" }, deps.fetch);
         const servicePassword = generatePassword(deps.randomBytes);
         await createUser(url, superuser, { email: SERVICE_EMAIL, password: servicePassword, role: "service" }, deps.fetch);
+        // The service password is stored before accounts.json marks the accounts as provisioned: a crash in between must never leave a password nobody has.
+        const serviceSteps = storeServiceAccount(deps.homeDir, { url, email: SERVICE_EMAIL, password: servicePassword });
         const accounts = { superuserEmail: SUPERUSER_EMAIL, superuserPassword, ownerEmail: options.ownerEmail };
         writeFileSync(layout.accountsJson, JSON.stringify(accounts, null, 2));
         chmodSync(layout.accountsJson, OWNER_FILE_MODE);
-        writeHubCredentials(deps.homeDir, { url, email: SERVICE_EMAIL, password: servicePassword });
-        steps.push({ step: "provision accounts", outcome: "done" });
+        steps.push({ step: "provision accounts", outcome: "done" }, ...serviceSteps);
         return { ok: true, steps, url };
     }
     catch (error) {

package/dist/adapters/hub-manager/port-probe.js

@@ -0,0 +1,38 @@
+/**
+ * Free-port probe for the local hub: bind `127.0.0.1:<port>` with
+ * `node:net` and release it again. The binder is injectable so every test
+ * but the one proving the real binder works uses a fake.
+ */
+import { createServer } from "node:net";
+const LOOPBACK = "127.0.0.1";
+const MAX_PORT = 65535;
+/** The real binder: a `node:net` server listening on `host:port`. */
+export const realPortBinder = (port, host) => new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once("error", reject);
+    server.listen(port, host, () => {
+        resolve(() => new Promise((done) => server.close(() => done())));
+    });
+});
+/** `true` when `127.0.0.1:<port>` can be bound (it is released again before returning); `false` on any bind error. */
+export async function isPortFree(port, bind = realPortBinder) {
+    try {
+        const release = await bind(port, LOOPBACK);
+        await release();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The first free port among `from`, `from + 1`, … (at most `tries` candidates, never above 65535), or `undefined` when none is free. */
+export async function firstFreePort(from, tries = 20, bind = realPortBinder) {
+    for (let offset = 0; offset < tries; offset += 1) {
+        const port = from + offset;
+        if (port > MAX_PORT)
+            return undefined;
+        if (await isPortFree(port, bind))
+            return port;
+    }
+    return undefined;
+}

package/dist/adapters/hub-reassign.js

@@ -0,0 +1,115 @@
+/**
+ * The hub side of the Tasks screen's reassignment: read the `task_entries`
+ * rows of some kankaku tasks (by `task_id`, in chunks) and PATCH their
+ * `client`/`project`/`task` relations, both through the published
+ * `kankaku-pi/hub` client, so authentication, the 401 re-auth and the
+ * per-request time bound are the client's own. Sync stays create-only:
+ * this is the only path that changes an existing row's assignment, and it
+ * sends nothing but those three relations (never `legacy_client_label`,
+ * never a measurement field).
+ */
+import { PocketBaseClient, PocketBaseError, escapeFilterValue } from "kankaku-pi/hub";
+import { createCatalog } from "./hub.js";
+/** Task ids per lookup request, per the hub contract's guidance (and the sync sink's own chunking). */
+const LOOKUP_CHUNK_SIZE = 30;
+/** Overall bound for `prepare` (row lookups plus the catalog refresh), on top of each request's own time bound. */
+const PREPARE_TIMEOUT_MS = 20_000;
+function relation(value) {
+    return typeof value === "string" ? value : "";
+}
+/**
+ * The hub rows of `taskIds`, keyed by kankaku task id. A task with no row
+ * is simply absent from the map. An empty relation reads `""`. A hub
+ * failure propagates as the client's `PocketBaseError`.
+ */
+export async function fetchHubRows(client, taskIds, options = {}) {
+    const chunkSize = options.chunkSize ?? LOOKUP_CHUNK_SIZE;
+    const rows = new Map();
+    for (let start = 0; start < taskIds.length; start += chunkSize) {
+        const chunk = taskIds.slice(start, start + chunkSize);
+        const filter = chunk.map((taskId) => `task_id="${escapeFilterValue(taskId)}"`).join("||");
+        const items = await client.list("task_entries", { filter, perPage: chunkSize }, options.signal);
+        for (const item of items) {
+            const taskId = item["task_id"];
+            if (typeof taskId !== "string")
+                continue;
+            rows.set(taskId, {
+                rowId: item.id,
+                taskId,
+                clientId: relation(item["client"]),
+                projectId: relation(item["project"]),
+                hubTaskId: relation(item["task"]),
+            });
+        }
+    }
+    return rows;
+}
+/** A short, plain reason for a failed hub call: never a URL, a row id or a stack. */
+export function describeHubError(error) {
+    if (!(error instanceof PocketBaseError))
+        return error instanceof Error ? error.message : String(error);
+    switch (error.kind) {
+        case "auth":
+            return "the hub rejected the credentials";
+        case "timeout":
+            return "the request timed out";
+        case "network":
+            return "the hub is unreachable";
+        case "http":
+            if (error.status === 400)
+                return "the hub rejected the change (400)";
+            if (error.status === 403)
+                return "not allowed to change this row (403)";
+            if (error.status === 404)
+                return "the row no longer exists on the hub (404)";
+            return `the hub answered ${error.status ?? "an error"}`;
+    }
+}
+/**
+ * One `PATCH /api/collections/task_entries/records/<rowId>` per `reassign`
+ * line, body `{ client, project, task }` (`""` for an empty relation).
+ * Rows are sent one after the other; a failure is recorded for its row and
+ * the rest still run. Returns one outcome per `reassign` line, in order.
+ */
+export async function applyReassignment(client, plan) {
+    const outcomes = [];
+    for (const line of plan.lines) {
+        if (line.kind !== "reassign")
+            continue;
+        const body = { client: line.payload.client, project: line.payload.project, task: line.payload.task };
+        try {
+            await client.request("PATCH", `/api/collections/task_entries/records/${encodeURIComponent(line.rowId)}`, body);
+            outcomes.push({ taskId: line.taskId, status: "reassigned" });
+        }
+        catch (error) {
+            outcomes.push({ taskId: line.taskId, status: "failed", reason: describeHubError(error) });
+        }
+    }
+    return outcomes;
+}
+/** Build the {@link ReassignActions} for `credentials`: one client for the row lookups and the PATCHes, the disk-backed catalog for the refresh. */
+export function createReassignActions(credentials, deps) {
+    const client = new PocketBaseClient({ ...credentials, ...(deps.fetch ? { fetch: deps.fetch } : {}) });
+    const catalog = createCatalog(credentials, deps);
+    return {
+        async prepare(taskIds) {
+            const signal = AbortSignal.timeout(PREPARE_TIMEOUT_MS);
+            try {
+                const rows = await fetchHubRows(client, taskIds, { signal });
+                const snapshot = await catalog.refresh(signal);
+                if (snapshot === undefined)
+                    return { ok: false, message: "could not refresh the catalog from the hub" };
+                return { ok: true, rows, catalog: { clients: snapshot.clients, projects: snapshot.projects, tasks: snapshot.tasks ?? [] } };
+            }
+            catch (error) {
+                return { ok: false, message: describeHubError(error) };
+            }
+        },
+        async apply(plan) {
+            const outcomes = await applyReassignment(client, plan);
+            // Task statuses may have moved (opening a task marks it as doing); a failed refresh only leaves the cache as it was.
+            await catalog.refresh().catch(() => undefined);
+            return outcomes;
+        },
+    };
+}

package/dist/adapters/package-versions.js

@@ -0,0 +1,24 @@
+/**
+ * The versions of the packages `kankaku` carries (`kankaku-pi`,
+ * `kankaku-claude`, `kankaku-hub`), resolved the same way the rest of the
+ * code finds them (`require.resolve("<name>/package.json")`, see
+ * `hub-manager/package.ts` and `setup/claude-plugin.ts`). Never throws: a
+ * package that cannot be resolved or read has an `undefined` version.
+ */
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
+const defaultRequire = createRequire(import.meta.url);
+export const CARRIED_PACKAGES = ["kankaku-pi", "kankaku-claude", "kankaku-hub"];
+function versionOf(name, resolve) {
+    try {
+        const parsed = JSON.parse(readFileSync(resolve(`${name}/package.json`), "utf8"));
+        return typeof parsed.version === "string" && parsed.version !== "" ? parsed.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Each carried package's version, in {@link CARRIED_PACKAGES} order. `resolve` defaults to `require.resolve`; tests inject one. */
+export function readCarriedVersions(resolve = (specifier) => defaultRequire.resolve(specifier)) {
+    return CARRIED_PACKAGES.map((name) => ({ name, version: versionOf(name, resolve) }));
+}

package/dist/adapters/setup/hub.js

@@ -30,7 +30,7 @@ export function writeHubCredentials(homeDir, credentials) {
     if (unchanged)
         return { changed: false };
     backupOnce(filePath);
-    writeJsonAtomic(filePath, { ...existing, url: credentials.url, email: credentials.email, password: credentials.password });
+    writeJsonAtomic(filePath, { ...existing, url: credentials.url, email: credentials.email, password: credentials.password }, undefined, OWNER_FILE_MODE);
     chmodSync(filePath, OWNER_FILE_MODE);
     return { changed: true };
 }