@catalyst-cloud/cli 0.14.0 → 0.14.2

package/dist/legacy.js

@@ -6,8 +6,8 @@
 //
 // The list is fixed on purpose. A prefix match would one day catch a current job (the housekeeping
 // job, the sandbox credit guard, jobs a person made); this matches names the old runtime installed,
-// read at the source commit below, and nothing else. Data folders are a separate yes (--data).
-import { existsSync, lstatSync, readFileSync, readdirSync, rmSync, unlinkSync } from "node:fs";
+// read at the source commit below, and nothing else. Shared data folders are always kept. The historical --data flag cannot remove them.
+import { existsSync, lstatSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { join } from "node:path";
 import { flagBool, positionals } from "./args.js";
@@ -47,8 +47,8 @@ const OLD_ROLE_PREFIX = "com.catalyst.role.";
 export const OLD_USER_UNITS = ["catalyst.service", "catalyst-monitor.service"];
 /** Command files the old runtime put on the person's PATH. `~/.local/bin/catalyst` is NOT one: that
  *  name belongs to the current CLI wherever npm put it. */
-export const OLD_BINS = [".catalyst/bin", ".local/bin/catalyst-events", ".local/bin/catalyst-filter", ".local/bin/catalyst-hud", ".local/bin/catalyst-monitor", ".local/bin/catalyst-myown"];
-/** State the old runtime kept. `~/.config/catalyst-cloud` is the current CLI's and never touched. */
+export const OLD_BINS = [".local/bin/catalyst-events", ".local/bin/catalyst-filter", ".local/bin/catalyst-hud", ".local/bin/catalyst-monitor", ".local/bin/catalyst-myown"];
+/** Shared roots also hold current skills, logs, hosts and seats. Never remove these directories. */
 export const OLD_DATA_DIRS = [".catalyst", ".config/catalyst", ".local/state/catalyst", ".local/state/catalyst-fleet-runner", ".local/state/catalyst-ledger"];
 const RECOMMEND = "Remove them: the cloud runtime replaced them, and left in place they can start old jobs or shadow current commands.";
 function readJson(path) {
@@ -138,11 +138,10 @@ function remove(item, run, platform, uid) {
             unlinkSync(item.path);
             return null;
         }
-        // a bin or a data folder: a file goes with unlink, a directory (~/.catalyst/bin, the data) with rm -rf
-        if (lstatSync(item.path).isDirectory())
-            rmSync(item.path, { recursive: true, force: true });
-        else
-            unlinkSync(item.path);
+        // CTC-4496: even explicit --data cannot delete shared roots. Unknown directories stay too.
+        if (item.data || lstatSync(item.path).isDirectory())
+            return "directory kept; shared data is protected";
+        unlinkSync(item.path);
         return null;
     }
     catch (err) {
@@ -171,10 +170,10 @@ export async function cmdLegacy(args, ctx, deps = {}) {
     }
     const listLines = [
         `Leftovers of the old local Catalyst runtime on this machine (${found.length}):`,
-        ...found.map((f) => `  ${f.kind}: ${f.name}${f.kind === "job" ? ` — ${f.path}` : f.data ? " (kept unless --data)" : ""}`),
+        ...found.map((f) => `  ${f.kind}: ${f.name}${f.kind === "job" ? ` — ${f.path}` : f.data ? " (kept: shared current state)" : ""}`),
     ];
     if (!wantRemove) {
-        emit({ sourceCommit: LEGACY_SOURCE_COMMIT, found, removed: [], remaining: found }, [...listLines, RECOMMEND, "Run: catalyst legacy --remove (add --data to delete its data folders too)"]);
+        emit({ sourceCommit: LEGACY_SOURCE_COMMIT, found, removed: [], remaining: found }, [...listLines, RECOMMEND, "Run: catalyst legacy --remove (all data folders are kept)"]);
         return 1;
     }
     // the one question, only on a terminal; --yes answers it without asking
@@ -182,13 +181,13 @@ export async function cmdLegacy(args, ctx, deps = {}) {
     if (!go) {
         const tty = (deps.isTty ?? stdinIsTty)();
         if (!tty) {
-            emit({ sourceCommit: LEGACY_SOURCE_COMMIT, found, removed: [], remaining: found, asked: false }, [...listLines, RECOMMEND, "nothing removed: no terminal to ask on; run catalyst legacy --remove --yes to remove these without a question (add --data for the data folders)"]);
+            emit({ sourceCommit: LEGACY_SOURCE_COMMIT, found, removed: [], remaining: found, asked: false }, [...listLines, RECOMMEND, "nothing removed: no terminal to ask on; run catalyst legacy --remove --yes to remove these without a question (all data folders are kept)"]);
             return 1;
         }
         for (const l of listLines)
             ctx.stdout(l);
         ctx.stdout(RECOMMEND);
-        const answer = (await (deps.prompt ?? ((q) => promptSecret(q)))(`Remove ${found.length} item${found.length === 1 ? "" : "s"}${withData ? ", data folders included" : ", keeping the data folders"}? [y/N] `)).trim().toLowerCase();
+        const answer = (await (deps.prompt ?? ((q) => promptSecret(q)))(`Remove ${found.length} item${found.length === 1 ? "" : "s"}, keeping all data folders? [y/N] `)).trim().toLowerCase();
         go = answer === "y" || answer === "yes";
         if (!go) {
             emit({ sourceCommit: LEGACY_SOURCE_COMMIT, found, removed: [], remaining: found, asked: true }, ["nothing removed; run catalyst legacy --remove again when ready"]);
@@ -200,9 +199,9 @@ export async function cmdLegacy(args, ctx, deps = {}) {
     const kept = [];
     const lines = [];
     for (const item of found) {
-        if (item.data && !withData) {
+        if (item.data) {
             kept.push(item);
-            lines.push(`kept: ${item.kind} ${item.name} (run with --data to delete it)`);
+            lines.push(`kept: ${item.kind} ${item.name} (shared current state; always kept)`);
             continue;
         }
         const why = remove(item, run, platform, uid);
@@ -216,8 +215,8 @@ export async function cmdLegacy(args, ctx, deps = {}) {
         }
     }
     // re-check from the same list, so the report says what the machine holds now, not what was attempted
-    const remaining = findLegacy(ctx.home, platform).filter((f) => !(f.data && !withData));
-    const keptNote = kept.length > 0 ? " except the data folders you kept" : "";
+    const remaining = findLegacy(ctx.home, platform).filter((f) => !f.data);
+    const keptNote = kept.length > 0 ? "; all shared data folders were kept" : "";
     lines.push(remaining.length === 0 ? `re-checked: nothing of the old runtime remains${keptNote}` : `re-checked: ${remaining.length} item${remaining.length === 1 ? "" : "s"} of the old runtime remain${remaining.length === 1 ? "s" : ""}${keptNote}: ${remaining.map((r) => `${r.kind} ${r.name}`).join(", ")}`);
     emit({ sourceCommit: LEGACY_SOURCE_COMMIT, found, removed, remaining: [...remaining, ...kept], kept, failed }, lines);
     return remaining.length === 0 ? 0 : 1;

package/dist/oauth.js

@@ -35,6 +35,9 @@ function isDiscovery(v) {
     return ["clientId", "issuer", "deviceAuthorizationUrl", "tokenUrl", "jwksUrl"].every((k) => typeof d[k] === "string");
 }
 export async function fetchDiscovery(ctx, baseUrl, opts = {}) {
+    const cancelled = () => { if (opts.signal?.aborted)
+        throw new CliError("Sign-in paused. Run the same command to resume.", "login-cancelled", 11); };
+    cancelled();
     const base = normalizeBaseUrl(baseUrl);
     const nowMs = ctx.now().getTime();
     const fresh = (e) => e !== null && e.baseUrl === base && nowMs - e.fetchedAt < DISCOVERY_TTL_MS;
@@ -53,6 +56,7 @@ export async function fetchDiscovery(ctx, baseUrl, opts = {}) {
         throw new CliError(`could not read the login discovery document (${res.status}) at ${url} — is this a Catalyst Cloud origin?`, "discovery-failed");
     }
     const doc = (await parseJson(res, url));
+    cancelled();
     if (!isDiscovery(doc))
         throw new CliError(`the login discovery document at ${url} is not the expected shape`, "discovery-shape");
     const entry = { baseUrl: base, fetchedAt: nowMs, doc };
@@ -79,12 +83,24 @@ export const MAX_DEVICE_CODES = 3;
  * expires, a fresh one is minted and printed, up to MAX_DEVICE_CODES in all.
  */
 export async function deviceFlowLogin(ctx, baseUrl, deps = {}) {
-    const sleep = deps.sleep ?? defaultSleep;
-    const discovery = await fetchDiscovery(ctx, baseUrl);
+    const cancelled = () => { if (deps.signal?.aborted)
+        throw new CliError("Sign-in paused. Run the same command to resume.", "login-cancelled", 11); };
+    cancelled();
+    if (deps.signal) {
+        const fetchImpl = ctx.fetch;
+        const signal = deps.signal;
+        ctx = { ...ctx, fetch: ((input, init) => fetchImpl(input, {
+                ...init, signal: init?.signal ? AbortSignal.any([signal, init.signal]) : signal,
+            })) };
+    }
+    const discovery = await fetchDiscovery(ctx, baseUrl, { signal: deps.signal });
+    cancelled();
     // The browser rule is decided on the first code; a later code re-opens it only when the first did.
     let browserOpened = false;
     for (let round = 1; round <= MAX_DEVICE_CODES; round++) {
+        cancelled();
         const auth = await deviceAuthorize(ctx, discovery);
+        cancelled();
         if (round > 1)
             ctx.stdout(`That code expired. Here is a new one (${round} of ${MAX_DEVICE_CODES}):`);
         ctx.stdout("");
@@ -103,7 +119,9 @@ export async function deviceFlowLogin(ctx, baseUrl, deps = {}) {
             }
         }
         ctx.stdout("Waiting for you to approve… (Ctrl-C to cancel)");
-        const tokens = await pollDeviceCode(ctx, discovery, auth, sleep);
+        const poll = () => pollDeviceCode(ctx, discovery, auth, deps.sleep, deps.signal);
+        const tokens = deps.waitForApproval ? await deps.waitForApproval(poll) : await poll();
+        cancelled();
         if (tokens !== "expired")
             return tokensToAuth(ctx, tokens.access_token, tokens.refresh_token);
     }
@@ -116,20 +134,35 @@ export async function deviceFlowLogin(ctx, baseUrl, deps = {}) {
  * a non-transient error) throw; expiry, by the server's `expired_token` or the code's own
  * `expires_in` lapsing, returns "expired" so the caller can mint the next code.
  */
-async function pollDeviceCode(ctx, discovery, auth, sleep) {
+async function pollDeviceCode(ctx, discovery, auth, sleep, external) {
     const deadline = AbortSignal.timeout(auth.expires_in * 1_000);
+    const signal = external ? AbortSignal.any([external, deadline]) : deadline;
+    const cancelled = () => { if (external?.aborted)
+        throw new CliError("Sign-in paused. Run the same command to resume.", "login-cancelled", 11); };
     let intervalMs = Math.max(1, auth.interval) * 1_000;
     for (;;) {
-        await sleep(intervalMs);
+        cancelled();
+        try {
+            await devicePollDelay(intervalMs, signal, sleep);
+        }
+        catch (error) {
+            cancelled();
+            if (deadline.aborted)
+                return "expired";
+            throw error;
+        }
+        cancelled();
         // The device code's own lifetime bounds the loop: once it lapses, treat it as expired rather than
         // letting the next fetch's aborted signal surface as a generic network error (Codex P2).
         if (deadline.aborted)
             return "expired";
         let res;
         try {
-            res = await safeFetch(ctx, discovery.tokenUrl, { method: "POST", headers: formHeaders(), body: form({ grant_type: "urn:ietf:params:oauth:grant-type:device_code", device_code: auth.device_code, client_id: discovery.clientId }) }, deadline);
+            res = await safeFetch(ctx, discovery.tokenUrl, { method: "POST", headers: formHeaders(), body: form({ grant_type: "urn:ietf:params:oauth:grant-type:device_code", device_code: auth.device_code, client_id: discovery.clientId }) }, signal);
+            cancelled();
         }
         catch (err) {
+            cancelled();
             // The deadline firing mid-fetch is an expiry, not a failure; anything else is a transient
             // network blip — retry with backoff until the deadline, never abandon the login (CTC-2112 P1).
             if (deadline.aborted)
@@ -165,6 +198,24 @@ async function pollDeviceCode(ctx, discovery, auth, sleep) {
         throw new CliError(`login failed (${res.status}): ${err}`, "login-failed");
     }
 }
+/** Clear the real timer on cancellation; an injected slow callback is bounded by the same signal. */
+function devicePollDelay(ms, signal, sleep) {
+    return new Promise((resolve, reject) => {
+        let timer;
+        const clean = () => { clearTimeout(timer); signal.removeEventListener("abort", abort); };
+        const abort = () => { clean(); reject(new Error("device_poll_stopped")); };
+        if (signal.aborted) {
+            abort();
+            return;
+        }
+        signal.addEventListener("abort", abort, { once: true });
+        if (sleep) {
+            Promise.resolve().then(() => sleep(ms)).then(() => { clean(); resolve(); }, error => { clean(); reject(error); });
+        }
+        else
+            timer = setTimeout(() => { clean(); resolve(); }, ms);
+    });
+}
 /** Grow the poll interval on a transient failure, capped, so retries never hammer the endpoint. */
 function backoff(intervalMs) {
     return Math.min(intervalMs * 2, MAX_POLL_BACKOFF_MS);

package/dist/onboard-existing.js

@@ -0,0 +1,169 @@
+import { loadConfig, normalizeBaseUrl } from "./config.js";
+import { CliError } from "./errors.js";
+const idPattern = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+const waiting = (reason) => ({ state: "waiting", reason });
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+const label = (value) => value.replace(/[\u0000-\u001f\u007f-\u009f]/g, "").slice(0, 120);
+/** A receipt keeps an explicit selection, never the team used to inspect the tenant grant. */
+export function selectedOnboardTeam(journal) {
+    const step = journal?.steps.find(row => row.id === "linear.team");
+    const id = step?.state === "done" ? step.evidence?.team : undefined;
+    return typeof id === "string" && idPattern.test(id) ? id : undefined;
+}
+/** Read-only requests bound headers and body together; raw provider errors never reach receipts. */
+export async function readExistingOnboardJson(ctx, path, external) {
+    const cfg = loadConfig(ctx.home);
+    if (!cfg?.user)
+        return { reason: "personal_login_required" };
+    // Identity verification refreshes before adapters run. These bounded reads never rotate a grant
+    // that could finish after the engine has released its lock.
+    const expiry = cfg.auth ? Date.parse(cfg.auth.expiresAt) - ctx.now().getTime() : 0;
+    const bearer = cfg.key || (cfg.auth && Number.isFinite(expiry) && expiry > 30_000 ? cfg.auth.accessToken : undefined);
+    if (!bearer)
+        return { reason: "team_read_login_refresh_required" };
+    const deadline = new AbortController();
+    const timer = setTimeout(() => deadline.abort(), 30_000);
+    const signal = external ? AbortSignal.any([external, deadline.signal]) : deadline.signal;
+    let remove = () => { };
+    try {
+        return await new Promise((resolve, reject) => {
+            const stopped = () => external?.aborted
+                ? reject(new CliError("Setup paused. Run the same command to resume.", "interrupted", 11))
+                : resolve({ reason: "team_read_unavailable" });
+            if (signal.aborted) {
+                stopped();
+                return;
+            }
+            signal.addEventListener("abort", stopped, { once: true });
+            remove = () => signal.removeEventListener("abort", stopped);
+            Promise.resolve().then(async () => {
+                if (signal.aborted)
+                    return { reason: "team_read_unavailable" };
+                const response = await ctx.fetch(`${normalizeBaseUrl(cfg.baseUrl)}${path}`, {
+                    headers: { authorization: `Bearer ${bearer}`, accept: "application/json" }, signal,
+                });
+                if (response.status !== 200)
+                    return { reason: "team_read_unavailable" };
+                const body = await response.json();
+                return { body };
+            }).then(value => signal.aborted ? stopped() : resolve(value), () => signal.aborted ? stopped() : resolve({ reason: "team_read_unavailable" }));
+        });
+    }
+    finally {
+        clearTimeout(timer);
+        remove();
+    }
+}
+async function inventory(ctx, signal) {
+    const read = await readExistingOnboardJson(ctx, "/api/v1/agent/teams", signal);
+    if ("reason" in read)
+        return read;
+    const body = object(read.body);
+    if (!body || !Array.isArray(body.teams) || body.teams.length > 1_000)
+        return { reason: "team_inventory_shape" };
+    const live = object(body.liveTeamRead);
+    if (live?.error !== undefined && live.error !== null)
+        return { reason: "team_read_unavailable" };
+    const teams = [];
+    const seen = new Set();
+    for (const value of body.teams) {
+        const row = object(value);
+        if (!row || typeof row.teamId !== "string" || !idPattern.test(row.teamId) || seen.has(row.teamId) ||
+            typeof row.teamKey !== "string" || typeof row.teamName !== "string")
+            return { reason: "team_inventory_shape" };
+        seen.add(row.teamId);
+        teams.push({ id: row.teamId, key: label(row.teamKey), name: label(row.teamName) });
+    }
+    return { teams };
+}
+async function observe(ctx, id, signal) {
+    const read = await readExistingOnboardJson(ctx, `/api/v1/agent/tenant/readiness?team=${encodeURIComponent(id)}`, signal);
+    if ("reason" in read)
+        return null;
+    const row = object(object(read.body)?.readiness);
+    // The GET owns expiry/revision freshness. Do not invent an expiresAt absent from its wire shape.
+    if (!row || row.teamId !== id || typeof row.status !== "string" || !["ready", "degraded", "blocked"].includes(row.status) || typeof row.checkedAt !== "number" ||
+        !Number.isFinite(row.checkedAt) || row.checkedAt < 0 || row.checkedAt > ctx.now().getTime() ||
+        typeof row.workflowRev !== "number" || !Number.isSafeInteger(row.workflowRev) || row.workflowRev < 0 || !Array.isArray(row.checks))
+        return null;
+    const checks = new Map();
+    for (const value of row.checks) {
+        const check = object(value);
+        if (!check || typeof check.id !== "string" || checks.has(check.id) || typeof check.state !== "string" || !["pass", "fail", "unknown"].includes(check.state))
+            return null;
+        checks.set(check.id, check.state);
+    }
+    return { checkedAt: row.checkedAt, revision: row.workflowRev, checks };
+}
+export function existingLinearAdapters(args, choose) {
+    let chosen;
+    const requested = (teams, journal) => {
+        const explicit = args.flags.team;
+        if (typeof explicit === "string") {
+            const ids = teams.filter(team => team.id === explicit);
+            if (ids.length === 1)
+                return ids[0];
+            const keys = teams.filter(team => team.key === explicit);
+            return keys.length === 1 ? keys[0] : undefined;
+        }
+        const saved = chosen ?? selectedOnboardTeam(journal);
+        return saved ? teams.find(team => team.id === saved) : undefined;
+    };
+    const teamCheck = async (ctx, journal, signal) => {
+        const list = await inventory(ctx, signal);
+        if ("reason" in list)
+            return waiting(list.reason);
+        if (!list.teams.length)
+            return waiting("team_inventory_empty");
+        const team = requested(list.teams, journal);
+        if (!team) {
+            if (typeof args.flags.team === "string")
+                return waiting("team_selection_unverified");
+            return choose ? { state: "pending" } : waiting("team_choice_required");
+        }
+        const result = await observe(ctx, team.id, signal);
+        if (!result || result.checks.get("team_visible") !== "pass")
+            return waiting("team_selection_unverified");
+        return { state: "done", evidence: { team: team.id, teamKey: team.key, checkedAt: result.checkedAt, revision: result.revision } };
+    };
+    return {
+        "linear.workspace": { check: async (ctx, journal, signal) => {
+                const list = await inventory(ctx, signal);
+                if ("reason" in list)
+                    return waiting(list.reason);
+                const candidate = requested(list.teams, journal) ?? list.teams[0];
+                if (!candidate)
+                    return waiting("linear_workspace_unverified");
+                const result = await observe(ctx, candidate.id, signal);
+                return result?.checks.get("oauth_scope") === "pass" && result.checks.get("token_live") === "pass"
+                    ? { state: "done", evidence: { checkedAt: result.checkedAt, revision: result.revision } }
+                    : waiting("linear_workspace_unverified");
+            }, act: async () => waiting("cloud_capability_unavailable") },
+        "linear.team": { check: teamCheck, act: async (ctx, journal, signal) => {
+                const list = await inventory(ctx, signal);
+                if ("reason" in list)
+                    return waiting(list.reason);
+                if (!list.teams.length)
+                    return waiting("team_inventory_empty");
+                if (!choose)
+                    return waiting("team_choice_required");
+                let remove = () => { };
+                const answer = await new Promise((resolve, reject) => {
+                    const stopped = () => resolve(null);
+                    if (signal?.aborted) {
+                        stopped();
+                        return;
+                    }
+                    signal?.addEventListener("abort", stopped, { once: true });
+                    remove = () => signal?.removeEventListener("abort", stopped);
+                    Promise.resolve().then(() => signal?.aborted ? null : choose(list.teams.map(team => ({ ...team })))).then(resolve, reject);
+                }).finally(() => remove());
+                if (!answer || signal?.aborted)
+                    return waiting("interrupted");
+                if (!list.teams.some(team => team.id === answer))
+                    return waiting("team_selection_unverified");
+                chosen = answer;
+                return teamCheck(ctx, journal, signal);
+            } },
+    };
+}

package/dist/onboard-progress.js

@@ -0,0 +1,70 @@
+/** Progress never owns stdin, raw mode or process exit; cancellation belongs to onboarding. */
+export function createOnboardProgress(output, signal, onError) {
+    let timer;
+    let active = false;
+    let disposed = false;
+    const clearTimer = () => { if (timer) {
+        clearInterval(timer);
+        timer = undefined;
+    } };
+    const failed = () => {
+        if (disposed)
+            return;
+        clearTimer();
+        active = false;
+        disposed = true;
+        signal.removeEventListener("abort", stop);
+        try {
+            output.write("\x1b[?25h");
+        }
+        catch { /* terminal is no longer writable */ }
+        onError?.();
+    };
+    const write = (text) => {
+        try {
+            output.write(text);
+            return true;
+        }
+        catch {
+            failed();
+            return false;
+        }
+    };
+    const stop = () => {
+        clearTimer();
+        if (active) {
+            active = false;
+            write("\r\x1b[2K\x1b[?25h");
+        }
+    };
+    signal.addEventListener("abort", stop);
+    output.on("error", failed);
+    return {
+        start(message) {
+            stop();
+            if (disposed || signal.aborted)
+                return;
+            const frames = ["◒", "◐", "◓", "◑"];
+            let frame = 0;
+            const render = () => {
+                const columns = output.columns ?? 80;
+                const text = Array.from(message.replace(/[\r\n\x1b]/g, " ")).slice(0, Math.max(0, columns - 5)).join("");
+                return write(`\r\x1b[2K${frames[frame++ % frames.length]}  ${text}`);
+            };
+            active = true;
+            if (!write("\x1b[?25l") || !render())
+                return;
+            timer = setInterval(render, 80);
+            timer.unref();
+        },
+        stop,
+        dispose() { try {
+            stop();
+        }
+        finally {
+            disposed = true;
+            signal.removeEventListener("abort", stop);
+            output.off("error", failed);
+        } },
+    };
+}

package/dist/onboard-ready.js

@@ -0,0 +1,67 @@
+import { loadConfig } from "./config.js";
+import { loadContract } from "./contract.js";
+const evidenceNames = new Set(["account", "membershipId", "project", "team", "repository", "count", "checkedAt", "expiresAt", "revision", "lag", "cursor", "heartbeatAgeMs", "supervised", "available", "validated", "phaseStarted", "linearComment", "fleetActivity"]);
+const slug = (value) => value && /^[a-z][a-z0-9_]{1,63}$/.test(value) ? value : undefined;
+function cleanCheck(check) {
+    const evidence = Object.fromEntries(Object.entries(check.evidence ?? {}).filter(([key, value]) => evidenceNames.has(key) &&
+        (value === null || typeof value === "string" || typeof value === "boolean" || (typeof value === "number" && Number.isFinite(value)))));
+    return { id: check.id, state: check.state, required: check.required, ...(slug(check.reason) ? { reason: slug(check.reason) } : {}),
+        ...(Object.keys(evidence).length ? { evidence } : {}) };
+}
+/** Receipts describe previous changes. Completion requires current observations. */
+export async function onboardingReadyReport(ctx, deps) {
+    const unavailable = {
+        checks: [{ id: "cloud.setup", state: "unknown", required: true, reason: "cloud_checks_unavailable" }],
+        work: { state: "unknown" },
+    };
+    let observation;
+    try {
+        observation = deps.observe ? await deps.observe(ctx, { teamIds: deps.teamIds }) : unavailable;
+    }
+    catch {
+        observation = unavailable;
+    }
+    const checks = observation.checks.map(cleanCheck);
+    if (deps.localSync && !checks.some(check => check.required && check.id.startsWith("local.")))
+        checks.push({ id: "local.sync", state: "unknown", required: true, reason: "local_sync_unverified" });
+    const work = { state: observation.work.state,
+        ...(observation.work.ticket && /^[A-Za-z][A-Za-z0-9]*-\d+$/.test(observation.work.ticket) ? { ticket: observation.work.ticket } : {}),
+        ...(observation.work.phaseStartedAt && Number.isFinite(Date.parse(observation.work.phaseStartedAt)) ? { phaseStartedAt: observation.work.phaseStartedAt } : {}) };
+    const required = checks.filter(check => check.required);
+    const state = required.some(check => check.state === "fail") || work.state === "not_observed" ? "incomplete"
+        : required.length === 0 || required.some(check => check.state === "unknown") || work.state === "unknown" ? "unknown" : "complete";
+    return { schema: 1, readMode: deps.localSync ? "local" : "cloud", state, checks, work };
+}
+/** The current contract exposes checked project setup, but not fresh starter-ticket proof. */
+export async function observeCloudOnboarding(ctx, scope = {}) {
+    const cfg = loadConfig(ctx.home);
+    if (!cfg?.user)
+        return { checks: [{ id: "signin", state: "fail", required: true, reason: "personal_login_required" }], work: { state: "unknown" } };
+    const { doc, source } = await loadContract(ctx, cfg, { refresh: true });
+    if (source === "cache")
+        return { checks: [{ id: "cloud.setup", state: "unknown", required: true, reason: "cloud_observation_unavailable" }], work: { state: "unknown" } };
+    const checks = [];
+    if (doc.account.id !== cfg.account)
+        return { checks: [{ id: "workspace", state: "fail", required: true, reason: "workspace_mismatch" }], work: { state: "unknown" } };
+    if (!scope.teamIds?.length)
+        return { checks: [{ id: "projects", state: "unknown", required: true, reason: "project_selection_unverified" }], work: { state: "unknown" } };
+    for (const id of new Set(scope.teamIds)) {
+        const team = doc.teams.find(row => row.id === id);
+        if (!team) {
+            checks.push({ id: `team.${id}`, state: "unknown", required: true, reason: "team_selection_unverified", evidence: { team: id } });
+            continue;
+        }
+        const fresh = team.readiness.checkedAt !== null && team.readiness.expiresAt !== null && team.readiness.expiresAt > ctx.now().getTime();
+        if (!fresh || team.readiness.checks.length === 0) {
+            checks.push({ id: `team.${team.id}`, state: "unknown", required: true, reason: "team_check_pending", evidence: { team: team.id } });
+            continue;
+        }
+        for (const check of team.readiness.checks)
+            checks.push({ id: `team.${team.id}.${check.id}`, state: check.state, required: true,
+                reason: slug(check.reason), evidence: { team: team.id, checkedAt: team.readiness.checkedAt, ...(check.count !== undefined ? { count: check.count } : {}) } });
+    }
+    if (!checks.length)
+        checks.push({ id: "projects", state: "unknown", required: true, reason: "project_selection_unverified" });
+    // A project may already be working even with an unknown setup check. This endpoint cannot prove either work state.
+    return { checks, work: { state: "unknown" } };
+}