@catalyst-cloud/cli 0.15.6 → 0.16.1

package/dist/onboard-next.js

@@ -1,9 +1,11 @@
 import { nativeEgressInstallCommands } from "./onboard-runner-egress.js";
+import { GITHUB_CONFIRM_ACCESS } from "./onboard-github-copy.js";
 import { INSTALL_COMMAND, loadConfig, normalizeBaseUrl } from "./config.js";
 import { githubInstallationPage } from "./onboard-permissions.js";
 import { valuesFacts, valuesFix } from "./ready-copy.js";
 /** What a person reads for a step that is not done. Each line ends in an action they can take. */
 const REASONS = {
+    legacy_cleanup_failed: "An earlier Catalyst installation could not be removed. Run catalyst legacy --remove to see the exact item and its blocker, fix that blocker, then run catalyst setup again. Shared data folders are kept.",
     account_identity_unverified: "Your login changed while AI accounts were checked. Run catalyst onboard again to verify your person and workspace.",
     account_inventory_unavailable: "AI accounts could not be read. Run catalyst onboard again to retry.",
     account_inventory_unverified: "The server did not return a fresh supported AI account list. Run catalyst onboard after the server update.",
@@ -52,6 +54,11 @@ const REASONS = {
     local_sync_not_selected: "Using cloud reads. Local sync was not selected.",
     local_sync_capability_unavailable: "Local sync was selected but could not be verified.",
     member_scope: "Your workspace administrator handles this step.",
+    returning_workspace_move_on: "Existing projects were left in place while this computer was set up. Run catalyst ready to review their checks, or catalyst setup --team <TEAM KEY> to repair one.",
+    returning_inventory_unverified: "Setup could not verify this workspace's existing projects. Run catalyst ready to check the workspace, then run catalyst setup again. Its projects have been kept in place.",
+    returning_project_cleanup_requested: "Review the selected project's archive preview before making any change.",
+    returning_project_cleanup_unverified: "Setup could not confirm this project's archive state. Run catalyst project list to inspect it, then run catalyst setup again to review any remaining changes. Do not repeat an archive based on this message alone.",
+    returning_project_cleanup_changed: "This project's repositories changed after the preview. Run catalyst setup again to review its current project list before archiving.",
     member_team_required: "Setup needs your Linear team to check what Catalyst can work on. Run catalyst setup again with --team <KEY>, using your team's key from Linear.",
     onboarding_checks_pending: "Some required checks are still unverified.",
     interrupted: "Setup paused. Run the same command to resume.",
@@ -72,7 +79,7 @@ const REASONS = {
     team_read_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard to resume.",
     team_create_unavailable: "The Linear team could not be created, and nothing was created. Run catalyst onboard to try again, or create the team in Linear and pick it.",
     team_create_unverified: "Setup could not confirm whether the Linear team was created. Check Linear for it before creating it again.",
-    team_create_grant_required: "Your own Linear connection is missing or has lapsed. Reconnect it in Settings → Connected accounts, then run catalyst onboard. Nothing was created.",
+    team_create_grant_required: "Your own Linear connection is missing or has lapsed. Reconnect it with catalyst connections personal linear start and approve the link it prints, then run catalyst onboard. Nothing was created.",
     team_create_identity_unverified: "Your login changed while setup was creating a team. Resume with the original workspace and person.",
     team_choice_required: "Choose an existing team with catalyst onboard --team <team ID or key>.",
     team_selection_unverified: "Your selected Linear team could not be verified. Run catalyst onboard --team <team ID or key> to choose again.",
@@ -100,13 +107,15 @@ const REASONS = {
     verification_pending: "Setup made the change but could not confirm it yet. Run catalyst onboard again to check.",
     automations_compatible: "Nothing to change.",
     workflow_unavailable: "Setup could not read the team's workflow. Run catalyst onboard again to retry.",
+    capacity_context_unverified: "Setup could not confirm this project's registered repositories and its default repository for capacity. Run catalyst ready to see the project checks, then run catalyst setup again. Starting a ticket checks its own repository's admission.",
+    capacity_identity_unverified: "Setup could not confirm your workspace and administrator role for the capacity check. Run catalyst login, then run catalyst setup again.",
     capacity_admission_unverified: "No runner is allowed to take work for this workspace yet. Enroll a self-hosted runner host, or ask Catalyst to enable cloud runners for it. Then run catalyst onboard.",
     capacity_currently_full: "Every runner slot for this repository is in use. Run catalyst onboard again after current work finishes.",
     capacity_unavailable: "Setup could not read runner capacity. Run catalyst onboard again to retry.",
     runner_not_selected: "This setup does not start a runner on this machine. To start one, run catalyst onboard --runner.",
     runner_docker_missing: "A runner needs Docker with Compose (Docker Desktop, OrbStack or Docker Engine), and setup could not reach it. Start Docker, or install it, then run catalyst onboard --runner.",
     runner_identity_unverified: "A workspace owner or administrator enrolls a runner. Sign in as one with catalyst login, then run catalyst onboard --runner.",
-    runner_context_unverified: "Setup could not confirm the selected Linear team. Run catalyst onboard again.",
+    runner_context_unverified: "Setup could not confirm a project for this machine. Keep its existing installation and credentials. Run catalyst setup --runner --team <TEAM KEY> for the project this machine should serve.",
     runner_directory_unavailable: "Setup could not prepare the runner folder in Catalyst's state directory. Check its permissions, then run catalyst onboard again.",
     runner_image_unpinned: "Each runner image must be pinned as name@sha256:<digest>, and Catalyst's runner image is not public yet. Ask Catalyst support to load it here and set CATALYST_RUNNER_IMAGE to the reference they give you. A CATALYST_SUPERVISOR_IMAGE or CATALYST_WATCHDOG_IMAGE override takes the same form. Then run catalyst onboard --runner.",
     runner_image_emulated: "A runner image here is built for another processor, and Catalyst does not run work under emulation. Ask Catalyst support for the image built for this processor, then run catalyst onboard again.",
@@ -114,9 +123,12 @@ const REASONS = {
     runner_session_network_failed: "Docker could not create the catalyst-session-v1 network. Check that Docker is running, then run catalyst onboard again.",
     runner_docker_socket_unreadable: "Setup could not read the group of the Docker socket at /var/run/docker.sock. Check that Docker is running, then run catalyst onboard again.",
     runner_engine_unsupported: "Runner setup needs local Docker Desktop or OrbStack on Mac, or native Linux Docker at /var/run/docker.sock. Select a supported local engine, then run catalyst onboard --runner.",
+    runner_installation_unverified: "Setup found a possible existing machine installation but could not verify its Compose files and identity. Keep its files and credentials. Run docker compose -p catalyst-host logs supervisor to check it, then run catalyst setup --runner again.",
     runner_enrollment_unavailable: "Setup could not read this workspace's runner hosts. Run catalyst onboard again to retry.",
     runner_enrolled_for_other_team: "This runner is enrolled for another Linear team. Keep using that team, or ask your administrator to revoke the old enrollment before setting up this machine for the selected team.",
-    runner_enrollment_stale: "This machine still holds the credential of a runner enrollment that was revoked. Stop the runner with docker compose -p catalyst-host down, remove the credential with docker volume rm catalyst-host_host-credential (this also removes the organization key), then run catalyst onboard --runner.",
+    runner_enrollment_revoked: "Catalyst confirms that this machine's saved enrollment was revoked. Keep its credential and organization key. Ask your workspace administrator to review the enrollment before replacing it, then run catalyst setup --runner.",
+    runner_credential_unverified: "Setup could not read this machine's saved enrollment. Keep its credential and organization key. Run docker compose -p catalyst-host logs supervisor to check the error, then run catalyst setup --runner.",
+    runner_enrollment_stale: "Setup could not match this machine's saved enrollment with Catalyst. Keep its credential and organization key, then run catalyst setup --runner to check again.",
     runner_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard.",
     runner_join_token_unavailable: "Catalyst did not issue a join token for this machine. Run catalyst onboard again to retry.",
     runner_session_network_unavailable: "Docker could not inspect the runner session network. Check engine access and run the same setup command again. Setup has not created a replacement network.",
@@ -138,7 +150,7 @@ const REASONS = {
     runner_needs_runner_flag: "This machine was set up to run Catalyst's work, but its runner is not running or not enrolled. To bring it up, run catalyst onboard --runner.",
     runner_capability_pending: "The runner enrolled but has not reported its capacity yet. Run catalyst onboard again in a minute.",
     runner_admission_unverified: "Setup could not read whether the team's pool admits runner hosts. Run catalyst onboard again to retry.",
-    github_app_permissions_outdated: "GitHub App needs updated permissions. An organization owner on GitHub accepts the pending request on the App's installation page, then run catalyst onboard.",
+    github_app_permissions_outdated: `The existing GitHub App installation needs updated permissions accepted. ${GITHUB_CONFIRM_ACCESS} An organization owner on GitHub opens the App's installation page, chooses Review permissions, then Accept new permissions. Run catalyst onboard afterward.`,
     github_app_repository_missing: "The GitHub App installation cannot reach a repository a project registers. An organization owner on GitHub adds it under the installation's Repository access, then run catalyst onboard.",
     github_app_repository_not_installed: "No GitHub App installation can reach a repository a project registers. A workspace owner or administrator installs the GitHub App on its owner: run catalyst onboard.",
     github_app_permissions_unverified: "The GitHub App installation works, but its granted permissions could not be checked. Run catalyst onboard to try again.",
@@ -246,7 +258,7 @@ function permissionText(step, baseUrl) {
         case "github_app_permissions_outdated":
             if (!url)
                 return undefined;
-            return `GitHub App needs updated permissions${org ? ` on ${org}` : ""}${missing ? `: ${missing}` : ""}. ${github} reviews and accepts the request at ${url}, then run catalyst onboard.`;
+            return `The existing GitHub App installation${org ? ` on ${org}` : ""} needs updated permissions accepted${missing ? `: ${missing}` : ""}. ${GITHUB_CONFIRM_ACCESS} ${github} chooses Review permissions, then Accept new permissions at ${url}. Run catalyst onboard afterward.`;
         case "github_app_repository_missing":
             if (!url || !repository)
                 return undefined;
@@ -336,13 +348,10 @@ export function onboardReasonText(step, context = {}) {
     // A member is told which admin action is left and where an admin takes it.
     if (reason === "member_scope") {
         const key = onboardTeamKey(context.journal);
+        if (step.id === "linear.adopt")
+            return `Only a Catalyst owner or admin can set up the team's Catalyst workflow. Ask one to run catalyst team adopt ${key ?? "<TEAM KEY>"}.`;
         const adminOnly = {
             "linear.workspace": ["connect Linear", "/settings/connections", " and connect it there"],
-            "linear.adopt": [
-                "set up the team's Catalyst workflow",
-                key ? `/settings/linear-teams/${encodeURIComponent(key)}/adopt` : "/settings/linear-teams",
-                "",
-            ],
         };
         const admin = adminOnly[step.id];
         if (admin) {
@@ -373,7 +382,7 @@ export function onboardReasonText(step, context = {}) {
         const where = context.baseUrl
             ? `at ${normalizeBaseUrl(context.baseUrl)}/settings/coding-accounts`
             : "in the web app on the Settings → AI accounts page";
-        return `No AI account in this workspace can take work yet. A workspace owner or administrator checks them ${where}: one may need its key replaced, or may have reached its usage limit. Then run catalyst onboard.`;
+        return `No AI account in this workspace can take work yet. Run catalyst accounts to see which one needs work. A workspace owner or administrator fixes it ${where}, since no command does that yet: one may need its key replaced, or may have reached its usage limit. Then run catalyst onboard.`;
     }
     if (reason === "account_enrollment_required") {
         const where = context.baseUrl
@@ -424,7 +433,7 @@ export function onboardReasonText(step, context = {}) {
         const where = context.baseUrl
             ? `at ${normalizeBaseUrl(context.baseUrl)}/settings/account-keys`
             : "on the web app's Account API keys page";
-        return `The runner is enrolled, but it takes no work without an organization key. A workspace owner or administrator creates one with the mirror:read, mirror:write and mirror:feed scopes ${where} and saves it in a file only they can read. Then run catalyst onboard --runner with CATALYST_RUNNER_ORG_KEY_FILE set to that file.`;
+        return `The runner is enrolled, but it takes no work without an organization key. A workspace owner or administrator runs catalyst onboard --runner on this machine; it mints the key and stores it for the runner. If their cloud cannot mint one yet, they create one with the mirror:read, mirror:write and mirror:feed scopes ${where}, save it in a file only they can read, and run catalyst onboard --runner with CATALYST_RUNNER_ORG_KEY_FILE set to that file.`;
     }
     if (reason === "runner_host_not_ready") {
         const failing = step.evidence?.failing;

package/dist/onboard-project-cleanup.js

@@ -0,0 +1,100 @@
+import { loadConfig, normalizeBaseUrl } from "./config.js";
+import { readExistingOnboardJson } from "./onboard-existing.js";
+import { readReturningProjects } from "./onboard-returning.js";
+const waiting = (reason) => ({ state: "waiting", reason });
+const signature = (project) => JSON.stringify([...(project.repositories ?? [])].sort((a, b) => a.id.localeCompare(b.id)));
+/** Archiving uses the existing reversible project action. Only the explicitly reviewed scope
+ * is changed, after fresh inventory and identity checks. A failed write is never assumed absent. */
+export async function archiveReturningProject(project, ctx, journal, confirm, signal) {
+    const cfg = loadConfig(ctx.home);
+    const sameIdentity = () => {
+        const now = loadConfig(ctx.home);
+        return cfg?.user && now?.user && cfg.account === journal.account &&
+            cfg.user.id === journal.membershipId && now.account === cfg.account &&
+            now.user.id === cfg.user.id && ["owner", "admin"].includes(now.user.role) &&
+            normalizeBaseUrl(now.baseUrl) === journal.baseUrl && normalizeBaseUrl(cfg.baseUrl) === journal.baseUrl;
+    };
+    if (!sameIdentity() || !confirm)
+        return waiting("returning_project_cleanup_unverified");
+    const fresh = await readReturningProjects(ctx, journal, signal);
+    const selected = "projects" in fresh ? fresh.projects.find(p => p.id === project.id) : undefined;
+    if (!selected?.repositories?.length || selected.repositories.length > 64 || !sameIdentity())
+        return waiting("returning_project_cleanup_unverified");
+    const linked = async () => {
+        const names = new Set();
+        const boundedRead = signal ? AbortSignal.any([signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000);
+        for (const row of selected.repositories) {
+            const read = await readExistingOnboardJson(ctx, `/api/v1/me/projects/${encodeURIComponent(row.id)}/repositories`, boundedRead);
+            if ("reason" in read || !read.body || typeof read.body !== "object")
+                return null;
+            const body = read.body;
+            if (!body.project || typeof body.project !== "object" ||
+                !("id" in body.project) || body.project.id !== row.id ||
+                !("teamId" in body.project) || body.project.teamId !== selected.id ||
+                !Array.isArray(body.repositories) || !body.repositories.length || body.repositories.length > 10_000)
+                return null;
+            const returnedNames = new Set();
+            for (const repository of body.repositories) {
+                if (!repository || typeof repository !== "object" || !("fullName" in repository) ||
+                    typeof repository.fullName !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}\/[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$/.test(repository.fullName))
+                    return null;
+                names.add(repository.fullName);
+                returnedNames.add(repository.fullName);
+            }
+            if (!returnedNames.has(row.name))
+                return null;
+        }
+        return [...names].sort();
+    };
+    const linkedNames = await linked();
+    if (!linkedNames || !sameIdentity())
+        return waiting("returning_project_cleanup_unverified");
+    const lines = [
+        `Archive ${selected.name} (${selected.key}) in Catalyst.`,
+        ...linkedNames.map(name => `Repository affected: ${name}.`),
+        "Archiving removes this project’s repository registrations. Mirroring may stop where no other registration keeps a repository active.",
+        "The project and its repository links are kept so it can be reactivated. Linear tickets and GitHub repositories are kept.",
+        "New work may be held when these repositories are no longer registered for this project.",
+    ];
+    if (!(await confirm(selected, lines)))
+        return { state: "done", reason: "returning_project_cleanup_declined" };
+    if (signal?.aborted || !sameIdentity())
+        return waiting("returning_project_cleanup_unverified");
+    const rechecked = await readReturningProjects(ctx, journal, signal);
+    const current = "projects" in rechecked ? rechecked.projects.find(p => p.id === selected.id) : undefined;
+    if (!current || signature(current) !== signature(selected) || !sameIdentity())
+        return waiting("returning_project_cleanup_changed");
+    const recheckedLinks = await linked();
+    if (!recheckedLinks || JSON.stringify(recheckedLinks) !== JSON.stringify(linkedNames) || !sameIdentity())
+        return waiting("returning_project_cleanup_changed");
+    const bearer = cfg?.key || (cfg?.auth && Date.parse(cfg.auth.expiresAt) - ctx.now().getTime() > 30_000
+        ? cfg.auth.accessToken : undefined);
+    if (!bearer)
+        return waiting("returning_project_cleanup_unverified");
+    const bounded = signal ? AbortSignal.any([signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000);
+    for (const row of selected.repositories) {
+        if (bounded.aborted || !sameIdentity())
+            return waiting("returning_project_cleanup_unverified");
+        try {
+            const response = await ctx.fetch(`${journal.baseUrl}/api/v1/me/repositories/${encodeURIComponent(row.id)}/archive`, {
+                method: "POST", redirect: "error", signal: bounded,
+                headers: { authorization: `Bearer ${bearer}`, accept: "application/json", "content-type": "application/json" },
+                body: "{}",
+            });
+            if (response.status !== 200)
+                return waiting("returning_project_cleanup_unverified");
+            const body = await response.json();
+            const returned = body && typeof body === "object" && "repository" in body ? body.repository : null;
+            if (!returned || typeof returned !== "object" || !("id" in returned) || returned.id !== row.id ||
+                !("linearTeamId" in returned) || returned.linearTeamId !== selected.id ||
+                !("status" in returned) || returned.status !== "archived")
+                return waiting("returning_project_cleanup_unverified");
+            journal.changes.push({ kind: "project-archive", label: `Archived ${selected.name}: ${row.name}`,
+                undo: "Reactivate the project from its Catalyst project page." });
+        }
+        catch {
+            return waiting("returning_project_cleanup_unverified");
+        }
+    }
+    return { state: "done" };
+}

package/dist/onboard-returning.js

@@ -0,0 +1,172 @@
+import { loadConfig, normalizeBaseUrl } from "./config.js";
+import { readExistingOnboardJson, readOnboardTeamInventory } from "./onboard-existing.js";
+import { teamCheckCopy } from "./ready-copy.js";
+const object = (v) => v !== null && typeof v === "object" && !Array.isArray(v) ? v : null;
+const repository = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}\/[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$/;
+/** Count configured teams across their repositories, rather than every visible Linear team. */
+export async function readReturningProjects(ctx, journal, signal) {
+    const cfg = loadConfig(ctx.home);
+    if (!cfg?.user || cfg.account !== journal.account || cfg.user.id !== journal.membershipId ||
+        normalizeBaseUrl(cfg.baseUrl) !== journal.baseUrl)
+        return { reason: "returning_inventory_unverified" };
+    const contract = await readExistingOnboardJson(ctx, "/api/v1/agent/contract", signal);
+    if ("reason" in contract)
+        return { reason: "returning_inventory_unverified" };
+    const doc = object(contract.body);
+    if (object(doc?.account)?.id !== cfg.account || !Array.isArray(doc?.routes))
+        return { reason: "returning_inventory_unverified" };
+    const routes = doc.routes.map(object).filter(r => r?.method === "GET" && typeof r.path === "string" &&
+        /^\/api\/v1\/[A-Za-z0-9_/-]+\/tenant\/repositories$/.test(r.path));
+    if (routes.length !== 1)
+        return { reason: "returning_inventory_unverified" };
+    // The contract's mapped teams omit projects that have not adopted a workflow yet. Use the
+    // complete project inventory, including paused and archived rows, and group active rows by team.
+    const read = await readExistingOnboardJson(ctx, routes[0].path, signal);
+    if ("reason" in read)
+        return { reason: "returning_inventory_unverified" };
+    const list = object(read.body);
+    if (list?.canManage !== true || !Array.isArray(list.repositories) || list.repositories.length > 10_000)
+        return { reason: "returning_inventory_unverified" };
+    const inventory = await readOnboardTeamInventory(ctx, signal);
+    const configured = [];
+    const seen = new Set();
+    const clean = (text) => text.replace(/[\u0000-\u001f\u007f-\u009f]/g, "").slice(0, 120);
+    for (const value of list.repositories) {
+        const row = object(value);
+        if (typeof row?.id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.:-]{0,255}$/.test(row.id) || seen.has(row.id) ||
+            typeof row.linearTeamId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(row.linearTeamId) ||
+            typeof row.name !== "string" || !row.name.trim() ||
+            !(row.linearTeamKey === null || typeof row.linearTeamKey === "string") ||
+            !["active", "paused", "archived"].includes(String(row.status)) ||
+            typeof row.githubRepoOwner !== "string" || typeof row.githubRepoName !== "string" ||
+            !repository.test(`${row.githubRepoOwner}/${row.githubRepoName}`))
+            return { reason: "returning_inventory_unverified" };
+        seen.add(row.id);
+        if (row.status === "archived")
+            continue;
+        const savedProject = configured.find(p => p.id === row.linearTeamId);
+        const linked = { id: row.id, name: `${row.githubRepoOwner}/${row.githubRepoName}`, status: row.status };
+        if (savedProject) {
+            savedProject.repositories.push(linked);
+            continue;
+        }
+        const team = "reason" in inventory ? undefined : inventory.teams.find(t => t.id === row.linearTeamId);
+        configured.push({ id: row.linearTeamId, key: team?.key ?? clean(row.linearTeamKey ?? ""),
+            name: team?.name ?? clean(row.name), status: "Readiness could not be checked. Run catalyst ready to check it.", repositories: [linked] });
+    }
+    // Bound the whole readiness summary, including a workspace with many projects.
+    const deadline = new AbortController();
+    const timer = setTimeout(() => deadline.abort(), 30_000);
+    const bounded = signal ? AbortSignal.any([signal, deadline.signal]) : deadline.signal;
+    try {
+        for (let start = 0; start < configured.length && !bounded.aborted; start += 4) {
+            await Promise.all(configured.slice(start, start + 4).map(async (project) => {
+                const read = await readExistingOnboardJson(ctx, `/api/v1/agent/tenant/readiness?team=${encodeURIComponent(project.id)}`, bounded);
+                if ("reason" in read)
+                    return;
+                const row = object(object(read.body)?.readiness);
+                if (row?.teamId !== project.id || !["ready", "degraded", "blocked"].includes(String(row.status)) ||
+                    typeof row.checkedAt !== "number" || !Number.isFinite(row.checkedAt) || row.checkedAt < 0 || row.checkedAt > ctx.now().getTime() ||
+                    !Array.isArray(row.checks) || !row.checks.length || row.checks.length > 100)
+                    return;
+                const checks = row.checks.map(object);
+                if (!checks.every(c => c && typeof c.id === "string" && /^[a-z][a-z0-9_]{0,79}$/.test(c.id) &&
+                    ["pass", "fail", "unknown"].includes(String(c.state))) ||
+                    new Set(checks.map(c => c.id)).size !== checks.length)
+                    return;
+                const unfinished = checks.filter(c => c.state !== "pass");
+                if (row.status === "ready" && !unfinished.length)
+                    project.status = "Ready";
+                else if (unfinished.length)
+                    project.status = unfinished.map(c => teamCheckCopy(cfg.baseUrl, project.key, c.id, c.state, null).line
+                        .replace(`team ${project.key}: `, "")).join(" ");
+            }));
+        }
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    for (const project of configured) {
+        const paused = project.repositories?.filter(r => r.status === "paused") ?? [];
+        if (paused.length)
+            project.status = `Paused: ${paused.map(r => r.name).join(", ")}. ${project.status === "Ready" ? "Readiness checks pass." : project.status}`;
+    }
+    return { projects: configured };
+}
+const PROJECT_STEPS = new Set([
+    "linear.workspace", "linear.personal", "linear.team", "linear.adopt", "linear.automations",
+    "github.install", "github.personal", "github.repos", "projects", "settings", "values", "capacity", "first-ticket", "ready",
+]);
+/** Scope is enforced in the adapters and receipt, so moving on cannot perform project writes. */
+export function returningWorkspaceAdapters(adapters, args, review, message, newProject, active = () => true, cleanup) {
+    if (args.flags.team !== undefined || args.flags.only !== undefined || args.flags.headless === true)
+        return;
+    let mode = "unread";
+    let count = 0;
+    let cleanupProject;
+    const scope = async (ctx, journal, signal, act = false) => {
+        if (!active())
+            return null;
+        if (mode === "unread") {
+            if (!["owner", "admin"].includes(loadConfig(ctx.home)?.user?.role ?? "")) {
+                mode = "continue";
+                return null;
+            }
+            const inventory = await readReturningProjects(ctx, journal, signal);
+            if ("reason" in inventory)
+                mode = "unknown";
+            else {
+                count = inventory.projects.length;
+                if (!count)
+                    mode = "continue";
+                else {
+                    message(`This workspace already has ${count} Catalyst project${count === 1 ? "" : "s"}.`);
+                    for (const p of inventory.projects)
+                        message(`${p.name} (${p.key}): ${p.status}`);
+                    const choice = review ? await review(inventory.projects) : "move-on";
+                    if (!choice || signal?.aborted)
+                        return { state: "waiting", reason: "interrupted" };
+                    if (choice === "move-on")
+                        mode = "move-on";
+                    else if (choice === "new") {
+                        mode = "continue";
+                        newProject();
+                    }
+                    else if ("cleanup" in choice) {
+                        cleanupProject = inventory.projects.find(p => p.id === choice.cleanup);
+                        mode = cleanupProject ? "cleanup" : "unknown";
+                    }
+                    else if (inventory.projects.some(p => p.id === choice.repair)) {
+                        args.flags.team = choice.repair;
+                        mode = "continue";
+                    }
+                    else
+                        mode = "unknown";
+                }
+            }
+        }
+        if (mode === "cleanup") {
+            if (!act)
+                return { state: "pending", reason: "returning_project_cleanup_requested" };
+            if (!cleanup || !cleanupProject)
+                return { state: "waiting", reason: "returning_project_cleanup_unverified" };
+            const result = await cleanup(cleanupProject, ctx, journal, signal);
+            if (result.state !== "done")
+                return result;
+            mode = "move-on";
+        }
+        if (mode === "unknown")
+            return { state: "waiting", reason: "returning_inventory_unverified" };
+        return mode === "move-on" ? { state: "skipped", reason: "returning_workspace_move_on", evidence: { projectCount: count } } : null;
+    };
+    for (const id of PROJECT_STEPS) {
+        const adapter = adapters[id];
+        if (!adapter)
+            continue;
+        adapters[id] = {
+            ...adapter,
+            check: async (ctx, journal, signal) => (mode === "unread" && id !== "linear.workspace" ? null : await scope(ctx, journal, signal)) ?? adapter.check(ctx, journal, signal),
+            ...(adapter.act ? { act: async (ctx, journal, signal) => (mode === "unread" && id !== "linear.workspace" ? null : await scope(ctx, journal, signal, true)) ?? adapter.act(ctx, journal, signal) } : {}),
+        };
+    }
+}