@catalyst-cloud/cli 0.8.0 → 0.9.0

package/skills/catalyst-onboard/SKILL.md

@@ -5,7 +5,7 @@ description: >-
 disable-model-invocation: true
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.8.0 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.0 — written in this repository for customer tenants -->
 
 # Onboard me
 
@@ -20,6 +20,7 @@ Scripts are run, never read. Each prints `--help`.
 - `node scripts/where-am-i.mjs` — every part, each with the instrument that read it, its verdict, and for anything unfinished who can fix it and the page it is on. Works before the machine is connected; that is one of the states it reports.
 - `node scripts/where-am-i.mjs --next` — the same reading, reduced to the single next step.
 - `node scripts/where-am-i.mjs --json` — the same document for you to branch on.
+- `node scripts/local-sync.mjs` — optional local replica and event sync status. Run `node scripts/local-sync.mjs --start` only after the person chooses local sync; the script starts the supported writer and waits for a live heartbeat at the cloud cursor.
 
 Start every session with it, and run it again after every step the person completes. It is the only thing that decides where you are.
 
@@ -28,6 +29,7 @@ Start every session with it, and run it again after every step the person comple
 | when | read |
 | -- | -- |
 | walking the steps — what each one does, what to read back, when it is done | `references/the-one-path.md` |
+| the person chooses an optional local event and replica cache | `references/local-sync.md` |
 | anything reports not ready, or you are about to say who should fix something | `references/who-fixes-what.md` |
 | the next step is a browser page, or a page said it worked and you have to confirm it | `references/what-the-browser-owns.md` |
 | the person asks what Catalyst actually is, or how a ticket gets worked | the `how-catalyst-works` skill |
@@ -41,11 +43,12 @@ Start every session with it, and run it again after every step the person comple
 ## Rules
 
 - **One step, then stop.** Say what you are about to do, do it, show the real output, say what it means and what comes next. Never queue several steps into one message, and never move on from a step you did not watch finish.
+- **Local sync is opt-in.** API-backed skills work without it. Ask whether the person wants a local event and replica cache before running `local-sync.mjs --start`. A detached process starting is not evidence of freshness; only the script's verified current verdict is.
 - **Report what you observed, not what you expected.** Print the lines the command actually produced. "That worked" without the output it produced is the single easiest thing to get wrong here, and a person who later finds it did not work stops trusting every other step you reported.
 - **Each part by its own instrument.** Read the machine with the machine's instrument and the project with the project's, and label every finding with the part it belongs to. The script does this for you; keep it that way when you summarize.
 - **Not ready is a question about who, not a reason to retry.** When something reports not ready, name which check, who can fix it, and where. If the owner is not the person in front of you, say so and stop — re-running a local command cannot move a check that belongs to a tenant owner, an admin, or a browser page.
 - **Never invent a count or a list.** Every number and every name comes from what a command printed. If you want to tell them how many projects are mapped, read it off the script's output; do not carry one over from an earlier turn.
-- **Three steps belong to a browser and always will**: approving the login, connecting Linear, and installing the GitHub App. Hand over the page and say what you need back. Do not claim you did them.
+- **Provider consent belongs to the person in a browser.** This includes approving login, the tenant's Linear connection and GitHub App install, and the member's personal Linear and GitHub connections. Start personal Linear consent after tenant Linear is connected; start personal GitHub consent only after the tenant GitHub App is installed and its repository is registered. Give the person the printed URL, then check `status`. Never claim a grant succeeded because a browser opened.
 - **Some steps a key cannot do yet.** Listing every project, saving a stage mapping, adopting the workflow, registering a repository and approving one repository's environment are settings-page work today; a key-callable path for them is being built. Route those through the browser and say plainly that it is a gap, not the design. Never guess at a route for them.
 - **The account-wide environment declaration is the exception, and the one setup write you can perform.** `catalyst-skills environment` reads it, proposes it and approves it. Use the verb; do not send them to a page for it.
 - **Their tenant, as them.** Everything goes through the CLI and the person's own login. You never name another tenant, and you never ask for a key you could avoid — the keyless login needs nothing pasted.

package/skills/catalyst-onboard/references/local-sync.md

@@ -0,0 +1,15 @@
+# Optional local events and replica
+
+**For:** a person who wants an on-machine event file and searchable replica. The normal API-backed skills work without this, so ask before starting a background writer.
+
+**You run:** `node scripts/local-sync.mjs` to show the current local state. Only if the person opts in, run `node scripts/local-sync.mjs --start`. The script uses `catalyst-skills replica start --detach`, whose writer also starts the local event cache. It waits up to 90 seconds; `--wait <seconds>` sets a bounded wait from 0 to 300.
+
+**Read back:** `Local sync current` only when both the replica and event cache have live writer heartbeats and each cursor equals its own cloud head. A detached process starting, one fresh heartbeat alone, or replica freshness alone does not prove event freshness. `catalyst-skills replica status --probe --json` checks the replica cursor; `catalyst-skills events status --probe --json` checks the separate event cursor. Either command can report stale or unknown; unknown means the cloud comparison could not be proved, not that the cache is stale. Exit 0 means current, 1 stale, 2 unknown or not connected, and 3 absent. Do not tell the person local data is current unless the combined check says so.
+
+**Owner:** you check and, with the person's opt-in, start. The local writer is optional. A reboot recovery service is separate work; if this machine restarts, recheck status before relying on local data.
+
+## First ticket event
+
+Ask before starting the local writer. Before the person moves a card, run `node scripts/local-sync.mjs --start` after they opt in and wait until it reports current. Then run `catalyst-skills events status --probe --json` and record its `cursor` as `<cursor-before-move>`. Move the card only after this baseline is captured. Once the card is moved, run `catalyst-skills events wait-for --ticket <ticket-identifier> --after <cursor-before-move> --timeout 300` with the identifier `explain` printed. Do not guess an event type. The explicit cursor lets `wait-for` find the event if it reached the local cache before the command began.
+
+Exit 0 prints a matching event after the recorded baseline and proves it reached this machine's cache. Exit 1 means no matching cached event arrived within five minutes; recheck `node scripts/local-sync.mjs` and report stale or unknown evidence without inferring a cloud or webhook failure. Exit 3 means the event cache is absent; ask before starting it. Other errors are unknown. `explain` remains the API-backed source for why a ticket can or cannot run.

package/skills/catalyst-onboard/references/skill-sources.md

@@ -18,6 +18,9 @@ Install both packs on a workstation used for coding and tenant operations. Each
 - The global lock is `$XDG_STATE_HOME/skills/.skill-lock.json` when `XDG_STATE_HOME` is set, else `~/.agents/.skill-lock.json`. A project uses its own `skills-lock.json`.
 - The installer writes relative links. Resolve each with `readlink -f` before you compare paths.
 
+
+The `npx skills add --all` command replaces existing same-named directories and links. Before a first install or refresh on an existing machine, read the lock above. Inspect every same-named agent destination. Proceed only when each destination is absent or a verified, unmodified copy of the intended pack or its symlink. A lock entry alone does not verify every destination. Keep independent, changed, or uncertain copies in place and resolve the conflict before adding either pack. Do not schedule raw add commands as an unattended refresh.
+
 ## Is each pack there
 
 `catalyst-skills ready` checks the Cloud pack only. Check `catalyst-onboard/SKILL.md` (Cloud pack) and `research-codebase/SKILL.md` (development pack) in the intended directory. If both are there, have the person type `/catalyst-onboard` (`$catalyst-onboard` in Codex).
@@ -28,8 +31,8 @@ Inventory source and scope before removing anything:
 
 1. Run `claude plugin list` and record whether `catalyst-dev@catalyst` is installed and at which scope.
 2. Inspect the selected agent's home skill directory and the current project's skill directory separately. Read any `skills-lock.json` files and source/provenance markers. A folder name alone does not prove which repository supplied it. Check whether `.claude/skills` is a symlink to another skills directory before changing either path.
-3. If the old plugin is active, remove only `catalyst-dev@catalyst`: `claude plugin uninstall catalyst-dev@catalyst --scope user --keep-data --yes`. Keep `catalyst-dev@catalyst-dev-skills` and `catalyst@catalyst-cloud`. If old skill copies are present, remove only copies whose recorded source is the deprecated local runtime. Keep unrelated skills and plugin installs.
+3. If the old plugin is active, remove only `catalyst-dev@catalyst`: `claude plugin uninstall catalyst-dev@catalyst --scope user --keep-data --yes`. Keep `catalyst-dev@catalyst-dev-skills` and `catalyst@catalyst-cloud`. For a copied skill whose lock source names the deprecated Catalyst runtime repository, use `npx skills remove <name> -g -y` only when every existing global agent path is that canonical copy or a symlink to it. Omit `-g` for a proven project install and inspect every same-named project agent path first. The command removes that name across agent directories. Leave independent or uncertain copies in place and report the conflict.
 4. Install the replacement pack or packs in the intended scope with the commands above. For the Cloud pack, omit `-g` only when a project-scoped install is intended. Do not use a blanket `npx skills remove --all` during migration.
-5. Read back the plugin list or skill lock and the destination skill folders. Start a new agent session after changing Claude plugins.
+5. Read back the plugin list, the lock for each changed scope, and the destination skill folders. Start a new agent session after changing Claude plugins.
 
 Do not delete a Catalyst checkout, local project data, or a same-named skill whose source is not known. If the source or scope is ambiguous, stop and report what is unclear before removing anything.

package/skills/catalyst-onboard/references/the-one-path.md

@@ -1,12 +1,11 @@
 # The one path
 
-Nine steps, in this order. The order is the product's own: the tenant-side steps run Linear, then the project, then GitHub, then the repository, because each one is the cheapest place to catch the failure the next one would otherwise hide.
+Eleven steps, in this order. The order is the product's own: the tenant-side steps run Linear, then the project, then GitHub, then the repository, because each one is the cheapest place to catch the failure the next one would otherwise hide. Connect the tenant's Linear workspace before starting personal Linear consent (3a). Install the tenant's GitHub App and register its repository before starting personal GitHub consent (6a).
 
 Walk them **one at a time**. Before each step say what you are about to do and why; after it, show what actually came back. `node scripts/where-am-i.mjs --next` decides which step you are on — never your memory of the last turn.
 
 Each step below states: what it is for, what you run or hand over, **what you read back to prove it landed**, and **who owns it**.
 
----
 
 ## 0 — Where are we
 
@@ -18,8 +17,6 @@ Each step below states: what it is for, what you run or hand over, **what you re
 
 **Owner:** you.
 
----
-
 ## 1 — Connect this machine
 
 **For:** giving this machine a credential, so every later read is the person's own.
@@ -32,8 +29,6 @@ Each step below states: what it is for, what you run or hand over, **what you re
 
 If it refuses, stop here and use the `connect-me` skill; it owns every failure mode of this step.
 
----
-
 ## 2 — Who you are
 
 **For:** the person grain. A connected machine does not mean an active seat, and an active seat does not mean their Linear identity is matched.
@@ -42,9 +37,7 @@ If it refuses, stop here and use the `connect-me` skill; it owns every failure m
 
 **Read back:** their label and role, and whether their Linear identity is matched.
 
-**Owner:** an unmatched Linear identity is fixed by a tenant owner or admin in Settings → Members. A seat that is not active is the same. Say which, and move on — neither blocks the steps below, but an unmatched identity means "what needs me" will show everyone's asks until it is fixed, and they should know that now rather than later.
-
----
+**Owner:** a personal Linear connection normally matches the person's Linear identity automatically. If it remains unmatched after personal consent, run `catalyst-skills identity linear status`, then `catalyst-skills identity linear options`. Let the member select their own listed identity and run `catalyst-skills identity linear set <linearUserId>`. The command reads the result back. An automatically resolved identity cannot be replaced; an existing claim conflict needs a tenant owner or admin. An inactive seat also needs an owner or admin. Say which finding the instrument reported.
 
 ## 3 — Connect Linear
 
@@ -56,7 +49,15 @@ If it refuses, stop here and use the `connect-me` skill; it owns every failure m
 
 **Owner:** a tenant owner or admin, in a browser. **This is a browser step by construction** — it is an authorization grant, and no key can perform one.
 
----
+## 3a — Connect your personal Linear account
+
+**For:** giving this person's agent its own provider access. The tenant's Linear connection and GitHub App serve the tenant; they do not prove that this member has approved personal grants.
+
+**You run:** `catalyst-skills connections personal linear start`. It gives a short-lived URL and tries to open it. The person approves in their own browser. If the browser does not open, give them the URL printed by the command. Never paste a provider token into a prompt.
+
+**Read back:** after approval, run `catalyst-skills connections personal linear status`. `node scripts/where-am-i.mjs` also reads the personal grant statuses. A URL opening is not proof that a grant landed.
+
+**Owner:** you start and check; the member approves in a browser. A usable personal Linear grant normally binds its viewer automatically. If identity remains unmatched, use `catalyst-skills identity linear options` for supported self-service recovery. Never choose a roster entry on the member's behalf. An already-resolved or already-claimed refusal needs an owner or admin to inspect the conflict.
 
 ## 4 — Pick one project, and map its stages
 
@@ -70,7 +71,6 @@ If it refuses, stop here and use the `connect-me` skill; it owns every failure m
 
 ⭐ **One project at a time is safe, and lead with this.** Mapping one project changes no other project's stages and moves no other project's tickets. Encourage a pilot: pick the project they care least about breaking.
 
----
 
 ## 5 — Install the GitHub App
 
@@ -82,7 +82,6 @@ If it refuses, stop here and use the `connect-me` skill; it owns every failure m
 
 **Owner:** a tenant owner or admin, in a browser. **Browser by construction**, same reason as step 3.
 
----
 
 ## 6 — Register the repository
 
@@ -94,13 +93,16 @@ If it refuses, stop here and use the `connect-me` skill; it owns every failure m
 
 **Owner:** a tenant owner or admin. ⛔ **Registering is settings-page work today**; a key-callable path is being built. ⛔ A repository registered without a project attached is the trap here: the call succeeds, the repository is listed, and nothing can ever dispatch into it. Make sure they attach the project in the same form, and say why.
 
----
+
+## 6a — Connect your personal GitHub account
+
+**For:** letting Catalyst act as you in GitHub. This grant is separate from the tenant's GitHub App installation. **You run:** `catalyst-skills connections personal github start`, only after the GitHub App is installed and the repository is registered. The browser flow is the same as 3a. **Read back:** `catalyst-skills connections personal github status`; a connected result confirms the personal grant. **Owner:** you start and check; the member approves in a browser.
 
 ## 7 — Declare what the containers need
 
 **For:** the environment a phase runs in — the names of the variables and secrets the person's code needs. Names leave the machine; values are entered once, by them, in the app.
 
-⭐ **This is the one setup step you can actually do.** Every other step above is a page. This one is a command, and it is worth saying so to the person.
+You can read, propose, and approve the account-wide declaration through the CLI if this member has an admin or owner seat. Personal connection initiation and status are also CLI actions; the provider approval remains in the browser.
 
 **You run:** `catalyst-skills environment` first, to read what the tenant already declares — the current revision, whether it is approved, and which revision a phase's checkout actually carries. Those last two are different things more often than people expect: a proposal that nobody approved changes nothing.
 
@@ -120,7 +122,6 @@ Add `--approve` to approve exactly the revision that propose just returned, whic
 
 If they do not know what their build needs yet, skip this step. It blocks nothing until a phase needs a secret.
 
----
 
 ## 8 — A coding account, and a host
 
@@ -136,13 +137,12 @@ If they do not know what their build needs yet, skip this step. It blocks nothin
 
 **You run:** `catalyst-skills ready`. Its READY does not cover step 8; the script does. Read them the verdict and every failing line, each with its own fix and owner. If it says NOT READY, go to `references/who-fixes-what.md` before you touch anything — a project check failing is not something re-running anything on this machine can fix.
 
-**Then:** have them move one card into the project's dispatch stage, and watch. `catalyst-skills explain <ticket>` says why it is or is not about to run.
+**Then:** have them move one card into the project's dispatch stage, and watch. `catalyst-skills explain <ticket>` says why it is or is not about to run. If they opted into local sync, use the optional first-event check in `references/local-sync.md`.
 
 **Read back:** what `explain` actually said. If it says the ticket cannot start, the reason it names is the answer — read it to them and use the `how-catalyst-works` skill for what the reason means, then `unstick` if something is holding it.
 
 **Owner:** the card move is theirs. The verdict is the tenant's.
 
----
 
 ## When you are done
 

package/skills/catalyst-onboard/references/what-the-browser-owns.md

@@ -11,6 +11,8 @@ These will never be a command, on any release. Each is an authorization a person
 | approving the login | the URL and short code that `catalyst-skills login` printed | "I have started the login. It printed this code and this URL — approve it in your browser, or on your phone, and tell me when it is done." |
 | connecting Linear | `<their cloud>/settings/connections` | "Open this page and connect Linear. It will send you to Linear to authorize it and bring you back." |
 | installing the GitHub App | `<their cloud>/settings/connections` | "Open the same page and install the GitHub App, granting it the repository you want worked." |
+| connecting personal Linear | the URL printed by `catalyst-skills connections personal linear start` | "Approve your own Linear account in this browser. I will check the grant status afterward." |
+| connecting personal GitHub, after the tenant GitHub App is installed and its repository is registered | the URL printed by `catalyst-skills connections personal github start` | "Approve your own GitHub account in this browser. I will check the grant status afterward." |
 
 Say **by construction**, not "not supported yet". A person who thinks it is a missing feature will wait for it.
 

package/skills/catalyst-onboard/references/who-fixes-what.md

@@ -7,7 +7,7 @@ Setup is seven parts. Each has one instrument, and each instrument answers about
 | part | instrument | what a pass proves | what it does **not** prove | who fixes a failure, and where |
 | -- | -- | -- | -- | -- |
 | **machine** | `catalyst-skills status`, and the non-team checks of `catalyst-skills ready` | Node is new enough, this machine holds a credential, the CLI is where the config says, the contract is cached, the skills are on disk | anything at all about the tenant | the person at this keyboard, here |
-| **person** | `catalyst-skills me` | the credential resolves to this person, with a role, and whether their Linear identity is matched | that their seat is active, or that they may change tenant settings | a tenant owner or admin, Settings → Members |
+| **person** | `catalyst-skills me`, and `catalyst-skills connections personal <linear|github> status` | the credential resolves to this person, shows their role and Linear identity match, and reports each personal grant's state | that their seat is active, or that they may change tenant settings | the member approves missing or expired personal grants in a browser; an owner or admin handles seat or identity conflicts in Settings → Members |
 | **account** | `catalyst-skills contract --path account` | a resolved Linear workspace means the tenant's Linear grant landed | that the GitHub App is installed — the contract does not carry it | a tenant owner or admin, `<their cloud>/settings/connections` |
 | **project** | `catalyst-skills contract --path teams`, and the `team:` checks of `ready` | for each project **that has been mapped**: its readiness verdict and each failing check by name | that this is every project they have — see below | a tenant owner or admin, `<their cloud>/settings/linear-teams` |
 | **repository** | `catalyst-skills contract --path merge.repositories` | the repository is registered to the account | that it is active, that a project can dispatch into it, or that its environment is declared | a tenant owner or admin, `<their cloud>/settings/repositories` |
@@ -34,7 +34,7 @@ Setup is seven parts. Each has one instrument, and each instrument answers about
 
 - **A machine check failed.** This is the person's, here, now. Each failing check carries its own `fix` line; read it and do it. A missing or partial skill set is `catalyst-skills install`; a stale contract is `catalyst-skills contract --refresh`; a missing CLI path is one more `catalyst-skills login`.
 - **A project check failed.** ⛔ **Nothing you run on this machine can move it.** Name the check, name the project, and name the owner — the `who` field carries the tenant's own owners and admins. Point at `<their cloud>/settings/linear-teams`. Then stop. Re-running `ready` in a loop is the failure this section exists to prevent: it will keep saying NOT READY for a reason that lives somewhere else entirely.
-- **A check is a note.** Notes never move the verdict. A stale or absent replica is optional; a check that has never been run is waiting, not failing; a check the engine could not run is unknown, which is not a pass and not a failure. Say which of the three it is.
+- **A check is a note.** Notes never move the verdict. A stale or absent replica or event cache is optional; an unknown freshness probe means the cloud comparison could not be proved. The API-backed skills still work. Say whether the local cache is absent, stale or unknown, and ask before starting the optional writer.
 
 ## When to stop rather than continue
 

package/skills/catalyst-onboard/scripts/local-sync.mjs

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+// Optional onboarding step. The replica command starts the event cache with the writer;
+// only a live heartbeat at the cloud head proves that both were started successfully.
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { cliTarget } from "./lib/cli.mjs";
+
+const STATUS_COMMAND = ["replica", "status", "--probe", "--json"];
+const EVENTS_COMMAND = ["events", "status", "--probe", "--json"];
+const START_COMMAND = ["replica", "start", "--detach"];
+const RECOVERY_COMMAND = "catalyst-skills replica start --detach";
+
+function defaultRun(args) {
+  const target = cliTarget();
+  const result = spawnSync(target.command, [...target.prefix, ...args], {
+    encoding: "utf8",
+    timeout: 30_000,
+    maxBuffer: 64 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "pipe"],
+    shell: !target.recorded && process.platform === "win32",
+    env: process.env,
+  });
+  return {
+    code: result.status ?? 1,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    error: result.error?.message,
+  };
+}
+
+export function assessLocalSync(status, events) {
+  if (!status || typeof status !== "object")
+    return { verdict: "unknown", current: false, reason: "replica status did not return a document" };
+  if (status.verdict === "not-configured")
+    return { verdict: "unknown", current: false, reason: "this machine is not connected" };
+  if (status.verdict === "absent")
+    return { verdict: "absent", current: false, reason: "local replica is absent" };
+  if (status.verdict === "unknown" || status.verdict === "unverified" || !["fresh", "stale"].includes(status.verdict))
+    return { verdict: "unknown", current: false, reason: `replica freshness is unknown: ${(status.reasons ?? []).join("; ")}` };
+  if (status.verdict !== "fresh")
+    return {
+      verdict: "stale",
+      current: false,
+      reason: `replica ${status.verdict ?? "unknown"}: ${(status.reasons ?? []).join("; ")}`,
+    };
+  if (status.writerAlive !== true)
+    return { verdict: "stale", current: false, reason: "replica writer heartbeat is absent or stale" };
+  if (!Number.isFinite(status.heartbeatAgeMs))
+    return { verdict: "unknown", current: false, reason: "replica heartbeat age was not reported" };
+  if (status.heartbeatAgeMs >= 15_000)
+    return { verdict: "stale", current: false, reason: `replica writer heartbeat is ${status.heartbeatAgeMs}ms old` };
+  if (!Number.isSafeInteger(status.cursor) || !Number.isSafeInteger(status.head) || !Number.isSafeInteger(status.lag))
+    return { verdict: "unknown", current: false, reason: "replica cursor or cloud head was not reported" };
+  if (status.lag !== 0 || status.cursor !== status.head) {
+    return {
+      verdict: "stale",
+      current: false,
+      reason: "cloud head and local cursor have not been proved equal",
+    };
+  }
+  if (!events || !["current", "stale", "absent"].includes(events.verdict)) {
+    return {
+      verdict: "unknown",
+      current: false,
+      reason: `event freshness is unknown: ${(events?.reasons ?? []).join("; ")}`,
+    };
+  }
+  if (events.verdict === "absent") {
+    return { verdict: "absent", current: false, reason: "local event cache is absent" };
+  }
+  if (events.verdict === "stale")
+    return {
+      verdict: "stale",
+      current: false,
+      reason: `event cache is ${events?.verdict ?? "unverified"}: ${(events?.reasons ?? []).join("; ")}`,
+    };
+  if (events.writerAlive !== true)
+    return { verdict: "stale", current: false, reason: "event writer heartbeat is absent or stale" };
+  if (!Number.isFinite(events.heartbeatAgeMs))
+    return { verdict: "unknown", current: false, reason: "event writer heartbeat age was not reported" };
+  if (events.heartbeatAgeMs >= 15_000)
+    return { verdict: "stale", current: false, reason: `event writer heartbeat is ${events.heartbeatAgeMs}ms old` };
+  if (!Number.isSafeInteger(events.cursor) || !Number.isSafeInteger(events.head))
+    return { verdict: "unknown", current: false, reason: "event cursor or cloud head was not reported" };
+  if (events.cursor !== events.head)
+    return { verdict: "stale", current: false, reason: `event cache cursor ${events.cursor} differs from cloud head ${events.head}` };
+  return {
+    verdict: "current",
+    current: true,
+    reason: `replica cursor ${status.cursor} and event cursor ${events.cursor} each match their cloud head; both writer heartbeats are live`,
+  };
+}
+
+function readStatus(run) {
+  const replicaResult = run(STATUS_COMMAND);
+  let status, events;
+  try {
+    status = JSON.parse(replicaResult.stdout);
+  } catch {
+    return {
+      status: null,
+      events: null,
+      assessment: {
+        verdict: "unknown",
+        current: false,
+        reason: `replica status is unknown: ${replicaResult.error || replicaResult.stderr.trim() || "invalid JSON"}`,
+      },
+      recovery: replicaResult.code === 2 ? "catalyst-skills login" : "catalyst-skills replica status --probe --json",
+    };
+  }
+  const eventsResult = run(EVENTS_COMMAND);
+  try {
+    events = JSON.parse(eventsResult.stdout);
+  } catch {
+    return {
+      status,
+      events: null,
+      assessment: {
+        verdict: "unknown",
+        current: false,
+        reason: `event freshness is unknown: ${eventsResult.error || eventsResult.stderr.trim() || "invalid JSON"}`,
+      },
+      recovery: "catalyst-skills events status --probe --json",
+    };
+  }
+  return { status, events, assessment: assessLocalSync(status, events) };
+}
+
+/** A bounded check. Starting the optional writer requires an explicit opt-in. */
+export async function runLocalSync({
+  start = false,
+  waitSeconds = 90,
+  run = defaultRun,
+  now = Date.now,
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+} = {}) {
+  if (!Number.isInteger(waitSeconds) || waitSeconds < 0 || waitSeconds > 300)
+    throw new Error("--wait must be an integer from 0 to 300 seconds");
+  let reading = readStatus(run);
+  if (reading.assessment.current || !start)
+    return { ...reading, started: false, recovery: reading.recovery ?? RECOVERY_COMMAND };
+  if (!reading.status)
+    return { ...reading, started: false, recovery: reading.recovery ?? "catalyst-skills replica status --probe --json" };
+  if (
+    reading.status?.verdict === "not-configured" ||
+    reading.status?.dbPath == null
+  ) {
+    return { ...reading, started: false, recovery: "catalyst-skills login" };
+  }
+  let started = false;
+  if (reading.status.writerAlive !== true && ["absent", "stale"].includes(reading.assessment.verdict)) {
+    const result = run(START_COMMAND);
+    if (result.code !== 0) {
+      return {
+        status: reading.status,
+        events: reading.events,
+        assessment: {
+          verdict: "unknown",
+          current: false,
+          reason: `writer start failed: ${result.error || result.stderr.trim() || result.stdout.trim()}`,
+        },
+        started: false,
+        recovery: RECOVERY_COMMAND,
+      };
+    }
+    started = true;
+  }
+  const deadline = now() + waitSeconds * 1000;
+  do {
+    reading = readStatus(run);
+    if (reading.assessment.current || now() >= deadline) break;
+    await sleep(Math.min(3000, deadline - now()));
+  } while (true);
+  return {
+    ...reading,
+    started,
+    recovery: reading.assessment.verdict === "unknown"
+      ? "node scripts/local-sync.mjs --json"
+      : reading.status?.writerAlive
+        ? "catalyst-skills replica stop && catalyst-skills replica start --detach"
+        : RECOVERY_COMMAND,
+  };
+}
+
+function parseArgs(argv) {
+  const opts = { start: false, waitSeconds: 90, json: false };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--start") opts.start = true;
+    else if (argv[i] === "--json") opts.json = true;
+    else if (argv[i] === "--wait") opts.waitSeconds = Number(argv[++i]);
+    else if (argv[i] === "--help") {
+      console.log(
+        "Usage: node scripts/local-sync.mjs [--start] [--wait 0..300] [--json]\nWithout --start, this only checks status. Local sync is optional.",
+      );
+      process.exit(0);
+    } else throw new Error(`Unknown argument: ${argv[i]}`);
+  }
+  return opts;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  try {
+    const opts = parseArgs(process.argv.slice(2));
+    const result = await runLocalSync(opts);
+    if (opts.json) console.log(JSON.stringify(result));
+    else {
+      const label = result.assessment.verdict === "current" ? "current" : result.assessment.verdict;
+      console.log(`Local sync ${label}: ${result.assessment.reason}`);
+      if (!result.assessment.current) console.log(`Next: ${result.recovery}`);
+    }
+    process.exitCode = result.assessment.verdict === "current" ? 0 : result.assessment.verdict === "stale" ? 1 : result.assessment.verdict === "absent" ? 3 : 2;
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 2;
+  }
+}

package/skills/catalyst-onboard/scripts/where-am-i.mjs

@@ -6,6 +6,7 @@
 //
 // Every count and every name below is read off what a verb printed. Nothing here is written down.
 import { cliTarget, CONNECT_LINE, parseFlags, printHelp, runCli, tryJson, tryLoadConfig } from "./lib/cli.mjs";
+import { runLocalSync } from "./local-sync.mjs";
 
 const SPEC = {
   next: { help: "print only the single next step" },
@@ -13,7 +14,8 @@ const SPEC = {
 };
 const NOTES = [
   "Reads, in this order: `status` (machine), `ready --json` (machine checks and project checks, kept apart),",
-  "`me --json` (person), `contract --path …` for the account, the projects and the repositories,",
+  "`replica status --probe --json` and `events status --probe --json` (optional local freshness),",
+  "`me --json` and personal connection statuses (person), `contract --path …` for the account, the projects and the repositories,",
   "`contract --path codingAccounts` (coding accounts; `accounts --json` on an older cloud), and each",
   "project's hosts_current check with its fixedWhere (host).",
   "Writes nothing and changes nothing. Runs before this machine is connected — that is one of the states it reports.",
@@ -31,6 +33,13 @@ if (positionals.length > 0) {
 
 const via = cliTarget().via;
 const parts = [];
+const personalConnections = {};
+let personalGrantIncomplete = false;
+let personalLinearIncomplete = false;
+let personalGithubIncomplete = false;
+let personalNext = null;
+let workspaceResolved = false;
+let repositoryRegistered = false;
 // `blocking` is false for a finding that is real and reportable but does not stop the next step —
 // an unmatched Linear identity is the one that matters: it must be said, and it must not become the
 // thing the person is told to go and do before they can map a project.
@@ -64,6 +73,7 @@ let machineVerdict = connected ? "ok" : "unfinished";
 // whose id begins with "team:" belongs to a project and cannot be moved from this machine.
 let projectChecks = [];
 let machineFix = null;
+let localSync;
 if (connected) {
   const ready = runCli(["ready", "--json"]);
   const report = tryJson(ready.stdout);
@@ -81,6 +91,17 @@ if (connected) {
       machineFix = failed.find((c) => typeof c.fix === "string")?.fix ?? null;
     }
   }
+  // Supplemental only: local caches are optional and do not change setup completion or --next.
+  localSync = await runLocalSync({ waitSeconds: 0 });
+  machineLines.push(
+    `note optional local sync ${localSync.assessment.verdict}: ${localSync.assessment.reason}; check with 'node scripts/local-sync.mjs', and start only with the person's opt-in via 'node scripts/local-sync.mjs --start'`,
+  );
+} else {
+  localSync = {
+    assessment: { verdict: "unknown", current: false, reason: "connect this machine before local freshness can be checked" },
+    started: false,
+    recovery: "catalyst-skills login",
+  };
 }
 add(
   "machine",
@@ -111,13 +132,35 @@ if (!connected) {
     );
   } else {
     const matched = typeof user.linearUserId === "string" && user.linearUserId !== "";
+    const grantLines = [];
+    for (const provider of ["linear", "github"]) {
+      const read = runCli(["connections", "personal", provider, "status", "--json"]);
+      const result = tryJson(read.stdout);
+      const outcome = typeof result?.outcome === "string" ? result.outcome : "unreadable";
+      personalConnections[provider] = outcome;
+      if (outcome === "connected") {
+        grantLines.push(`personal ${provider}: connected`);
+      } else if (outcome === "absent" || outcome === "lapsed") {
+        personalGrantIncomplete = true;
+        if (provider === "linear") personalLinearIncomplete = true;
+        else personalGithubIncomplete = true;
+        grantLines.push(`personal ${provider}: ${outcome === "absent" ? "not connected" : "expired"}`);
+        if (provider === "linear") personalNext ??= "connect your personal linear account";
+      } else {
+        personalGrantIncomplete = true;
+        if (provider === "linear") personalLinearIncomplete = true;
+        else personalGithubIncomplete = true;
+        grantLines.push(`personal ${provider}: ${outcome === "unavailable" ? "temporarily unavailable; grant state unknown" : "could not be checked; update the catalyst-skills CLI or inspect its status output"}`);
+        if (provider === "linear") personalNext ??= "re-check your personal linear connection";
+      }
+    }
     add(
       "person",
-      "catalyst-skills me",
-      matched ? "ok" : "unfinished",
-      [`${user.label ?? "(unnamed)"} (${user.role ?? "role unknown"})`, matched ? "Linear identity matched" : "Linear identity NOT matched — asks assigned to you cannot be told apart from everyone else's. It blocks nothing below; get it fixed when convenient."],
-      matched ? null : "a tenant owner or admin",
-      matched ? null : link("/settings/account"),
+      "catalyst-skills me, and catalyst-skills connections personal <provider> status --json",
+      matched && !personalGrantIncomplete ? "ok" : "unfinished",
+      [`${user.label ?? "(unnamed)"} (${user.role ?? "role unknown"})`, matched ? "Linear identity matched" : "Linear identity NOT matched — asks assigned to you cannot be told apart from everyone else's. It blocks nothing below. Run catalyst-skills identity linear options for self-service recovery; personal Linear consent normally binds its viewer automatically.", ...grantLines],
+      personalGrantIncomplete ? "you" : matched ? null : "a tenant owner or admin",
+      personalGrantIncomplete ? "catalyst-skills connections personal <provider> start or status" : matched ? null : link("/settings/account"),
       false,
     );
   }
@@ -133,6 +176,7 @@ if (!connected) {
     add("account", "catalyst-skills contract --path account", "unreadable", ["the account block could not be read — try: catalyst-skills contract --refresh"], null, null);
   } else {
     const workspace = typeof doc.linearWorkspaceSlug === "string" && doc.linearWorkspaceSlug !== "" ? doc.linearWorkspaceSlug : typeof doc.linearWorkspaceId === "string" && doc.linearWorkspaceId !== "" ? doc.linearWorkspaceId : null;
+    workspaceResolved = workspace !== null;
     // The declaration is the one part of the account a key can also READ — and it is the one part a
     // key can WRITE, so it is reported here rather than left to the settings page like the rest.
     const envLines = [];
@@ -212,6 +256,7 @@ if (!connected) {
     add("repositories", "catalyst-skills contract --path merge.repositories", "unreadable", ["the repository list could not be read — try: catalyst-skills contract --refresh"], null, null);
   } else {
     const lines = [`${rows.length} registered`, ...rows.map((r) => `${r.owner ?? "?"}/${r.name ?? "?"}`)];
+    repositoryRegistered = rows.length > 0;
     lines.push("⛔ REGISTRATION only. This carries no status and no project attachment, so it never proves a repository can be dispatched into.");
     add("repositories", "catalyst-skills contract --path merge.repositories", rows.length > 0 ? "ok" : "unfinished", lines, "a tenant owner or admin", link("/settings/repositories"));
   }
@@ -309,13 +354,28 @@ const machineNext = connected
   : "connect this machine";
 const NEXT = {
   machine: machineNext,
-  person: "get this person's seat and Linear identity sorted",
+  person: personalLinearIncomplete
+    ? personalNext
+    : personalGithubIncomplete && repositoryRegistered
+      ? "connect your personal github account"
+      : personalGithubIncomplete
+        ? "install the tenant GitHub App and register its repository before connecting your personal GitHub account"
+        : "get this person's seat and Linear identity sorted",
   account: "connect Linear, and install the GitHub App",
   projects: "pick ONE project and map its stages (or adopt the Catalyst workflow)",
   repositories: "register the repository, attaching it to the project you mapped",
   "coding accounts": accountsNext,
   host: "connect a Catalyst host",
 };
+// A personal Linear grant cannot start until the tenant's Linear workspace exists. Once that account
+// connection is present, a missing personal grant becomes the next member step before project setup.
+const personPart = parts.find((p) => p.part === "person");
+// A personal Linear grant is the next provider step once the tenant workspace exists. A personal
+// GitHub grant is sequenced after the tenant GitHub App: successful repository registration is the
+// onboarding path's existing proof that the App installation is usable.
+if (personPart && personalGrantIncomplete && workspaceResolved) {
+  personPart.blocking = personalLinearIncomplete || (personalGithubIncomplete && repositoryRegistered);
+}
 const blocked = parts.filter((p) => p.verdict !== "ok" && p.blocking);
 const stuck = blocked[0] ?? parts.find((p) => p.verdict !== "ok") ?? null;
 const next =
@@ -325,7 +385,7 @@ const next =
 const finished = parts.every((p) => p.verdict === "ok");
 
 if (flags.json) {
-  console.log(JSON.stringify({ cli: via, connected, cloud, parts, next, finished }));
+  console.log(JSON.stringify({ cli: via, connected, cloud, personalConnections, parts, localSync, next, finished }));
 } else if (flags.next) {
   if (next === null) console.log("nothing left: every part is finished, a coding account is enrolled and the host check passes. Move one card into the project's dispatch stage.");
   else console.log(`${next.part}: ${next.action}${next.blocking ? "" : " (does not block the steps below)"}${next.owner ? ` — who: ${next.owner}` : ""}${next.where ? ` — ${next.where.startsWith("http") ? "where" : "do"}: ${next.where}` : ""}`);

package/skills/catalyst-setup/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Am I set up? Machine readiness (Node, the tenant connection, the cached contract, the CLI path, the skills, the SDK, the optional replica) plus tenant readiness from the contract's per-team checks, in one verdict: what passes, what is blocked, what is merely waiting, and who can click what. Use when someone asks "am I set up", "what is missing", "why does nothing happen", "is the replica running", or right after connecting a new machine. Reports; never repairs.
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.8.0 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.0 — written in this repository for customer tenants -->
 
 # Am I set up?
 

package/skills/connect-me/SKILL.md

@@ -5,7 +5,7 @@ description: >-
 disable-model-invocation: true
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.8.0 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.0 — written in this repository for customer tenants -->
 
 # Connect me