Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

feat(switchdash): persisted, sequential host setup plan model + runner (CHOO-1809)

switch-worker-louis-remote8aae7f3e93fb
diff --git a/dash/apps/switchdash-desktop/src/main/core/remote-hosts/setup/host-setup-runner.test.ts b/dash/apps/switchdash-desktop/src/main/core/remote-hosts/setup/host-setup-runner.test.ts
new file mode 100644
index 000000000..7cf676398
--- /dev/null
+++ b/dash/apps/switchdash-desktop/src/main/core/remote-hosts/setup/host-setup-runner.test.ts
@@ -0,0 +1,401 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { HostSetupPlan, HostSetupStep } from '@shared/core/remote-hosts/setup';
+import {
+ HostSetupAbortedError,
+ HostSetupRunner,
+ type StepCheckResult,
+ type StepInstallResult,
+} from './host-setup-runner';
+
+function step(id: string, patch: Partial<HostSetupStep> = {}): HostSetupStep {
+ return {
+ id,
+ kind: 'core-dependency',
+ name: id,
+ state: 'pending',
+ outcome: null,
+ version: null,
+ error: null,
+ output: null,
+ optional: false,
+ dependsOn: [],
+ updatedAt: '2026-01-01T00:00:00.000Z',
+ ...patch,
+ };
+}
+
+function plan(steps: HostSetupStep[]): HostSetupPlan {
+ return {
+ sshHost: 'dev-vm',
+ status: 'idle',
+ steps,
+ currentStepId: null,
+ createdAt: '2026-01-01T00:00:00.000Z',
+ updatedAt: '2026-01-01T00:00:00.000Z',
+ };
+}
+
+type Harness = {
+ checks: Record<string, StepCheckResult[]>;
+ installs: Record<string, StepInstallResult>;
+ canInstall?: (id: string) => boolean;
+ reachable?: boolean;
+};
+
+class Unreachable extends Error {}
+
+function makeRunner(harness: Harness) {
+ const saved: HostSetupPlan[] = [];
+ const published: HostSetupPlan[] = [];
+ const installOrder: string[] = [];
+ const inFlight = { count: 0, max: 0 };
+
+ const runner = new HostSetupRunner({
+ sshHost: 'dev-vm',
+ load: async () => null,
+ save: async (p) => void saved.push(structuredClone(p)),
+ publish: (p) => published.push(structuredClone(p)),
+ check: async (s) => {
+ const queue = harness.checks[s.id] ?? [{ outcome: 'satisfied' }];
+ return queue.length > 1 ? queue.shift()! : queue[0]!;
+ },
+ install: async (s) => {
+ installOrder.push(s.id);
+ inFlight.count += 1;
+ inFlight.max = Math.max(inFlight.max, inFlight.count);
+ await Promise.resolve();
+ inFlight.count -= 1;
+ return harness.installs[s.id] ?? { ok: true };
+ },
+ canInstall: (s) => harness.canInstall?.(s.id) ?? true,
+ requireReachable: () => {
+ if (harness.reachable === false) throw new Unreachable('host down');
+ },
+ now: () => new Date('2026-02-02T00:00:00.000Z'),
+ });
+
+ return { runner, saved, published, installOrder, inFlight };
+}
+
+const stateOf = (p: HostSetupPlan, id: string) => p.steps.find((s) => s.id === id)!.state;
+
+describe('HostSetupRunner', () => {
+ it('marks already-satisfied steps satisfied without installing', async () => {
+ const { runner, installOrder } = makeRunner({
+ checks: { git: [{ outcome: 'satisfied', version: '2.43.0' }] },
+ installs: {},
+ });
+
+ const result = await runner.run(plan([step('git')]));
+
+ expect(result.status).toBe('complete');
+ expect(stateOf(result, 'git')).toBe('satisfied');
+ expect(installOrder).toEqual([]);
+ });
+
+ it('installs a missing dependency and verifies it afterwards', async () => {
+ const { runner, installOrder } = makeRunner({
+ checks: { node: [{ outcome: 'missing' }, { outcome: 'satisfied', version: '22.0.0' }] },
+ installs: { node: { ok: true } },
+ });
+
+ const result = await runner.run(plan([step('node')]));
+
+ expect(installOrder).toEqual(['node']);
+ expect(stateOf(result, 'node')).toBe('satisfied');
+ expect(result.steps[0]!.version).toBe('22.0.0');
+ expect(result.status).toBe('complete');
+ });
+
+ it('fails the step when an install reports success but verification disagrees', async () => {
+ // The installer's exit code is a claim; only the re-check is evidence.
+ const { runner } = makeRunner({
+ checks: { node: [{ outcome: 'missing' }, { outcome: 'missing' }] },
+ installs: { node: { ok: true } },
+ });
+
+ const result = await runner.run(plan([step('node')]));
+
+ expect(stateOf(result, 'node')).toBe('failed');
+ expect(result.steps[0]!.error).toContain('still reports "missing" after installing');
+ expect(result.status).toBe('halted');
+ });
+
+ it('installs strictly one at a time, in plan order', async () => {
+ const { runner, installOrder, inFlight } = makeRunner({
+ checks: {
+ git: [{ outcome: 'missing' }, { outcome: 'satisfied' }],
+ node: [{ outcome: 'missing' }, { outcome: 'satisfied' }],
+ tmux: [{ outcome: 'missing' }, { outcome: 'satisfied' }],
+ },
+ installs: {},
+ });
+
+ await runner.run(plan([step('git'), step('node'), step('tmux')]));
+
+ expect(installOrder).toEqual(['git', 'node', 'tmux']);
+ expect(inFlight.max).toBe(1);
+ });
+
+ it('halts on failure, keeps earlier progress, and blocks later steps', async () => {
+ const { runner, installOrder } = makeRunner({
+ checks: {
+ git: [{ outcome: 'satisfied' }],
+ node: [{ outcome: 'missing' }],
+ tmux: [{ outcome: 'missing' }],
+ },
+ installs: { node: { ok: false, error: 'apt-get failed', output: 'E: Unable to locate' } },
+ });
+
+ const result = await runner.run(plan([step('git'), step('node'), step('tmux')]));
+
+ expect(result.status).toBe('halted');
+ expect(stateOf(result, 'git')).toBe('satisfied'); // step 1 is not discarded
+ expect(stateOf(result, 'node')).toBe('failed');
+ expect(stateOf(result, 'tmux')).toBe('blocked'); // never attempted, and says so
+ expect(installOrder).toEqual(['node']); // stopped; tmux was not installed
+ expect(result.currentStepId).toBe('node');
+ });
+
+ it('preserves the failing step error and command output', async () => {
+ const { runner } = makeRunner({
+ checks: { node: [{ outcome: 'missing' }] },
+ installs: { node: { ok: false, error: 'permission denied', output: 'sudo: no tty' } },
+ });
+
+ const result = await runner.run(plan([step('node')]));
+
+ expect(result.steps[0]!.error).toBe('permission denied');
+ expect(result.steps[0]!.output).toBe('sudo: no tty');
+ });
+
+ it('resumes from the failed step without redoing satisfied ones', async () => {
+ // Each runner gets its own check queues — sharing them would let the first
+ // run consume the second's answers and hide whether resume really re-probes.
+ const first = makeRunner({
+ checks: { git: [{ outcome: 'satisfied' }], node: [{ outcome: 'missing' }] },
+ installs: { node: { ok: false, error: 'transient' } },
+ });
+ const halted = await first.runner.run(plan([step('git'), step('node')]));
+ expect(halted.status).toBe('halted');
+
+ // Resume with the persisted plan, exactly as a restart would. node is still
+ // missing, so it must be re-attempted; git is satisfied and must not be.
+ const second = makeRunner({
+ checks: {
+ git: [{ outcome: 'satisfied' }],
+ node: [{ outcome: 'missing' }, { outcome: 'satisfied' }],
+ },
+ installs: { node: { ok: true } },
+ });
+ const resumed = await second.runner.run(halted);
+
+ expect(resumed.status).toBe('complete');
+ expect(second.installOrder).toEqual(['node']); // git was not re-installed
+ });
+
+ it('records unknown — never missing — when a probe throws', async () => {
+ const runner = new HostSetupRunner({
+ sshHost: 'dev-vm',
+ load: async () => null,
+ save: async () => {},
+ publish: () => {},
+ check: async () => {
+ throw new Error('ssh channel closed');
+ },
+ install: async () => ({ ok: true }),
+ canInstall: () => true,
+ requireReachable: () => {},
+ now: () => new Date('2026-02-02T00:00:00.000Z'),
+ });
+
+ const result = await runner.run(plan([step('docker')]));
+
+ expect(result.steps[0]!.outcome).toBe('unknown');
+ expect(result.steps[0]!.state).toBe('failed');
+ expect(result.steps[0]!.error).toContain('ssh channel closed');
+ });
+
+ it('never reports an unverifiable step as satisfied', async () => {
+ const { runner } = makeRunner({
+ checks: { docker: [{ outcome: 'unknown', error: 'could not tell' }] },
+ installs: {},
+ });
+
+ const result = await runner.run(plan([step('docker')]));
+
+ expect(stateOf(result, 'docker')).not.toBe('satisfied');
+ expect(result.status).toBe('halted');
+ });
+
+ it('does not try to install a dependency that is installed but not running', async () => {
+ const { runner, installOrder } = makeRunner({
+ checks: { docker: [{ outcome: 'not-running' }] },
+ installs: {},
+ });
+
+ const result = await runner.run(plan([step('docker')]));
+
+ expect(installOrder).toEqual([]);
+ expect(result.steps[0]!.error).toContain('not running');
+ });
+
+ it('reports "no install command" rather than silently stalling', async () => {
+ const { runner } = makeRunner({
+ checks: { docker: [{ outcome: 'missing' }] },
+ installs: {},
+ canInstall: () => false,
+ });
+
+ const result = await runner.run(plan([step('docker')]));
+
+ expect(result.steps[0]!.state).toBe('failed');
+ expect(result.steps[0]!.error).toContain('no install command');
+ });
+
+ it('continues past a failed optional step', async () => {
+ const { runner } = makeRunner({
+ checks: { gh: [{ outcome: 'missing' }], node: [{ outcome: 'satisfied' }] },
+ installs: { gh: { ok: false, error: 'nope' } },
+ });
+
+ const result = await runner.run(plan([step('gh', { optional: true }), step('node')]));
+
+ expect(stateOf(result, 'gh')).toBe('failed');
+ expect(stateOf(result, 'node')).toBe('satisfied');
+ expect(result.status).toBe('complete'); // optional failure does not block the host
+ });
+
+ it('skipping unblocks the rest of the plan but is not satisfied', async () => {
+ const { runner } = makeRunner({
+ checks: { node: [{ outcome: 'missing' }], tmux: [{ outcome: 'satisfied' }] },
+ installs: { node: { ok: false, error: 'nope' } },
+ });
+
+ const halted = await runner.run(plan([step('node'), step('tmux')]));
+ expect(stateOf(halted, 'tmux')).toBe('blocked');
+
+ const skipped = await runner.skip(halted, 'node');
+
+ expect(stateOf(skipped, 'node')).toBe('skipped');
+ expect(stateOf(skipped, 'tmux')).toBe('pending'); // unblocked
+ expect(skipped.steps.find((s) => s.id === 'node')!.outcome).not.toBe('satisfied');
+ });
+
+ it('aborts as unreachable instead of blaming a dependency', async () => {
+ const { runner, installOrder } = makeRunner({
+ checks: { node: [{ outcome: 'missing' }] },
+ installs: {},
+ reachable: false,
+ });
+
+ await expect(runner.run(plan([step('node')]))).rejects.toBeInstanceOf(HostSetupAbortedError);
+ expect(installOrder).toEqual([]);
+ });
+
+ it('persists and publishes every transition', async () => {
+ const { runner, saved, published } = makeRunner({
+ checks: { node: [{ outcome: 'missing' }, { outcome: 'satisfied' }] },
+ installs: { node: { ok: true } },
+ });
+
+ await runner.run(plan([step('node')]));
+
+ // running → checking → observed → installing → checking → satisfied → complete
+ expect(saved.length).toBeGreaterThanOrEqual(6);
+ expect(published.length).toBe(saved.length);
+ expect(saved.at(-1)!.status).toBe('complete');
+ });
+
+ it('refuses a second concurrent run for the same host', async () => {
+ const { runner } = makeRunner({
+ checks: { node: [{ outcome: 'missing' }, { outcome: 'satisfied' }] },
+ installs: { node: { ok: true } },
+ });
+ const p = plan([step('node')]);
+
+ const first = runner.run(p);
+ await expect(runner.run(p)).rejects.toThrow('already in progress');
+ await first;
+ });
+
+ it('stops mid-run when the host drops', async () => {
+ const harness: Harness = {
+ checks: { git: [{ outcome: 'satisfied' }], node: [{ outcome: 'missing' }] },
+ installs: {},
+ };
+ const reachable = { value: true };
+ const runner = new HostSetupRunner({
+ sshHost: 'dev-vm',
+ load: async () => null,
+ save: async () => {},
+ publish: () => {},
+ check: async (s) => harness.checks[s.id]![0]!,
+ install: async () => ({ ok: true }),
+ canInstall: () => true,
+ requireReachable: () => {
+ if (!reachable.value) throw new Unreachable('dropped');
+ reachable.value = false; // drops after the first step
+ },
+ now: () => new Date('2026-02-02T00:00:00.000Z'),
+ });
+
+ await expect(runner.run(plan([step('git'), step('node')]))).rejects.toBeInstanceOf(
+ HostSetupAbortedError
+ );
+ });
+
+ it('clears a previous error when a step is retried', async () => {
+ const { runner } = makeRunner({
+ checks: { node: [{ outcome: 'missing' }, { outcome: 'satisfied' }] },
+ installs: { node: { ok: true } },
+ });
+ const failed = plan([
+ step('node', { state: 'failed', error: 'old failure', output: 'old output' }),
+ ]);
+
+ const result = await runner.run(failed);
+
+ expect(stateOf(result, 'node')).toBe('satisfied');
+ expect(result.steps[0]!.error).toBeNull();
+ expect(result.steps[0]!.output).toBeNull();
+ });
+});
+
+describe('plan helpers', () => {
+ it('treats a skipped required step as outstanding, not done', async () => {
+ const { isPlanComplete } = await import('@shared/core/remote-hosts/setup');
+ expect(isPlanComplete(plan([step('node', { state: 'skipped' })]))).toBe(false);
+ });
+
+ it('ignores optional steps when deciding completeness', async () => {
+ const { isPlanComplete } = await import('@shared/core/remote-hosts/setup');
+ expect(
+ isPlanComplete(
+ plan([step('node', { state: 'satisfied' }), step('gh', { optional: true, state: 'failed' })])
+ )
+ ).toBe(true);
+ });
+});
+
+describe('runner determinism', () => {
+ it('does not mutate the plan it was given', async () => {
+ const { runner } = makeRunner({ checks: { git: [{ outcome: 'satisfied' }] }, installs: {} });
+ const original = plan([step('git')]);
+ const snapshot = structuredClone(original);
+
+ await runner.run(original);
+
+ expect(original).toEqual(snapshot);
+ });
+
+ it('stamps updatedAt on every changed step', async () => {
+ const { runner } = makeRunner({ checks: { git: [{ outcome: 'satisfied' }] }, installs: {} });
+ vi.useFakeTimers();
+
+ const result = await runner.run(plan([step('git')]));
+
+ expect(result.steps[0]!.updatedAt).toBe('2026-02-02T00:00:00.000Z');
+ vi.useRealTimers();
+ });
+});
diff --git a/dash/apps/switchdash-desktop/src/main/core/remote-hosts/setup/host-setup-runner.ts b/dash/apps/switchdash-desktop/src/main/core/remote-hosts/setup/host-setup-runner.ts
new file mode 100644
index 000000000..a4eb95845
--- /dev/null
+++ b/dash/apps/switchdash-desktop/src/main/core/remote-hosts/setup/host-setup-runner.ts
@@ -0,0 +1,288 @@
+/**
+ * Sequential, resumable setup runner for a remote host (CHOO-1809).
+ *
+ * Runs a host's setup plan one step at a time, persisting after every
+ * transition so a run survives the app closing mid-install. Three rules drive
+ * the design:
+ *
+ * 1. **One step in flight.** Dependencies install one after another, in order,
+ * never concurrently — the old page fired every probe and install
+ * independently and left the user to guess the sequence.
+ * 2. **Halt on failure, hold position.** A failed required step stops the run.
+ * Steps already satisfied stay satisfied, the failure keeps its error and
+ * command output, and untried steps become `blocked` rather than being
+ * discarded. Resuming re-attempts the failure; it does not start over.
+ * 3. **Reachability is not a dependency verdict.** The reachability gate is
+ * consulted before any probing, and an unreachable host aborts the run as
+ * *unreachable* instead of reporting every prerequisite as missing.
+ *
+ * Verification is explicit: after an install we re-check rather than assuming
+ * the installer worked. A step is only `satisfied` on the strength of a fresh
+ * observation.
+ */
+
+import {
+ isInstallableOutcome,
+ isPlanComplete,
+ type DependencyCheckOutcome,
+ type HostSetupPlan,
+ type HostSetupStep,
+ type HostSetupStepState,
+} from '@shared/core/remote-hosts/setup';
+
+/** What a probe observed for one step. */
+export type StepCheckResult = {
+ outcome: DependencyCheckOutcome;
+ version?: string | null;
+ /** Set when the outcome is `unknown` — why we could not tell. */
+ error?: string;
+};
+
+/** Outcome of installing one step. */
+export type StepInstallResult =
+ | { ok: true }
+ | { ok: false; error: string; output?: string | null };
+
+export type HostSetupRunnerDeps = {
+ sshHost: string;
+ /** Load the persisted plan. Null when the host has never been set up. */
+ load: (sshHost: string) => Promise<HostSetupPlan | null>;
+ save: (plan: HostSetupPlan) => Promise<void>;
+ /** Push the plan to the renderer on every transition. */
+ publish: (plan: HostSetupPlan) => void;
+ check: (step: HostSetupStep) => Promise<StepCheckResult>;
+ install: (step: HostSetupStep) => Promise<StepInstallResult>;
+ /** Whether this step can be installed by switchdash at all on this host. */
+ canInstall: (step: HostSetupStep) => boolean;
+ /**
+ * Throws when the host is not reachable. Wired to the central reachability
+ * service (CHOO-1682/1780) — this runner never forms its own verdict.
+ */
+ requireReachable: (sshHost: string) => void;
+ now?: () => Date;
+};
+
+/** Raised when a run is abandoned because the host itself is not reachable. */
+export class HostSetupAbortedError extends Error {
+ constructor(
+ message: string,
+ readonly cause: unknown
+ ) {
+ super(message);
+ this.name = 'HostSetupAbortedError';
+ }
+}
+
+export class HostSetupRunner {
+ private running = false;
+
+ constructor(private readonly deps: HostSetupRunnerDeps) {}
+
+ private now(): string {
+ return (this.deps.now?.() ?? new Date()).toISOString();
+ }
+
+ /**
+ * Run (or resume) the plan. Returns as soon as the plan completes or halts.
+ * Concurrent calls are rejected rather than interleaved — two runs against
+ * one host would break the one-at-a-time guarantee.
+ */
+ async run(plan: HostSetupPlan): Promise<HostSetupPlan> {
+ if (this.running) {
+ throw new Error(`A setup run is already in progress for ${this.deps.sshHost}`);
+ }
+ this.running = true;
+ try {
+ return await this.drive(plan);
+ } finally {
+ this.running = false;
+ }
+ }
+
+ private async drive(initial: HostSetupPlan): Promise<HostSetupPlan> {
+ let plan = await this.transition(initial, { status: 'running' });
+
+ for (const step of plan.steps) {
+ if (step.state === 'satisfied' || step.state === 'skipped') continue;
+
+ // Gate on reachability before every step, not just at the start: a host
+ // can drop mid-run, and continuing would attribute the loss of the
+ // transport to whichever dependency happened to be next in line.
+ try {
+ this.deps.requireReachable(this.deps.sshHost);
+ } catch (error) {
+ plan = await this.transition(plan, { status: 'halted' });
+ throw new HostSetupAbortedError(
+ `Setup for ${this.deps.sshHost} stopped: the host became unreachable.`,
+ error
+ );
+ }
+
+ plan = await this.runStep(plan, step.id);
+ const current = findStep(plan, step.id);
+
+ if (current.state === 'failed' && !current.optional) {
+ return await this.haltAfter(plan, step.id);
+ }
+ }
+
+ return await this.transition(plan, {
+ status: isPlanComplete(plan) ? 'complete' : 'halted',
+ currentStepId: null,
+ });
+ }
+
+ /**
+ * Check one step, install it if that is both needed and possible, then
+ * re-check to verify. Never marks a step satisfied on the strength of an
+ * installer's exit code alone.
+ */
+ async runStep(plan: HostSetupPlan, stepId: string): Promise<HostSetupPlan> {
+ let next = await this.patchStep(plan, stepId, {
+ state: 'checking',
+ error: null,
+ output: null,
+ });
+ next = await this.transition(next, { currentStepId: stepId });
+
+ const checked = await this.observe(next, stepId);
+ const step = findStep(checked, stepId);
+
+ if (step.outcome === 'satisfied') return checked;
+
+ // Nothing we can do automatically — surface the real outcome rather than
+ // pretending an install would help. `not-running` and `unknown` land here.
+ if (!isInstallableOutcome(step.outcome) || !this.deps.canInstall(step)) {
+ return await this.patchStep(checked, stepId, {
+ state: 'failed',
+ error: describeUnactionable(step),
+ });
+ }
+
+ const installing = await this.patchStep(checked, stepId, { state: 'installing' });
+ const result = await this.deps.install(findStep(installing, stepId));
+
+ if (!result.ok) {
+ return await this.patchStep(installing, stepId, {
+ state: 'failed',
+ error: result.error,
+ output: result.output ?? null,
+ });
+ }
+
+ // Verify. An installer reporting success is a claim, not an observation.
+ const verifying = await this.patchStep(installing, stepId, { state: 'checking' });
+ const verified = await this.observe(verifying, stepId);
+ const after = findStep(verified, stepId);
+
+ if (after.outcome === 'satisfied') return verified;
+
+ return await this.patchStep(verified, stepId, {
+ state: 'failed',
+ error:
+ after.outcome === 'unknown'
+ ? `${after.name} was installed but could not be verified afterwards.`
+ : `${after.name} still reports "${after.outcome}" after installing.`,
+ });
+ }
+
+ /** Probe one step and record what was actually observed. */
+ private async observe(plan: HostSetupPlan, stepId: string): Promise<HostSetupPlan> {
+ let result: StepCheckResult;
+ try {
+ result = await this.deps.check(findStep(plan, stepId));
+ } catch (error) {
+ // A probe that throws tells us nothing about the dependency — record
+ // `unknown`, never `missing`.
+ result = {
+ outcome: 'unknown',
+ error: error instanceof Error ? error.message : String(error),
+ };
+ }
+
+ return await this.patchStep(plan, stepId, {
+ outcome: result.outcome,
+ version: result.version ?? null,
+ state: result.outcome === 'satisfied' ? 'satisfied' : 'checking',
+ error: result.error ?? null,
+ });
+ }
+
+ /** Mark the plan halted and block everything downstream of the failure. */
+ private async haltAfter(plan: HostSetupPlan, failedStepId: string): Promise<HostSetupPlan> {
+ const failedIndex = plan.steps.findIndex((s) => s.id === failedStepId);
+ const steps = plan.steps.map((step, index) =>
+ index > failedIndex && (step.state === 'pending' || step.state === 'blocked')
+ ? { ...step, state: 'blocked' as HostSetupStepState, updatedAt: this.now() }
+ : step
+ );
+ return await this.commit({
+ ...plan,
+ steps,
+ status: 'halted',
+ currentStepId: failedStepId,
+ });
+ }
+
+ /**
+ * Move past a step the user has chosen not to fix. Unblocks the rest of the
+ * plan so the run can continue, but is never reported as satisfied.
+ */
+ async skip(plan: HostSetupPlan, stepId: string): Promise<HostSetupPlan> {
+ const skipped = await this.patchStep(plan, stepId, {
+ state: 'skipped',
+ error: null,
+ output: null,
+ });
+ const steps = skipped.steps.map((step) =>
+ step.state === 'blocked' ? { ...step, state: 'pending' as HostSetupStepState } : step
+ );
+ return await this.commit({ ...skipped, steps, status: 'idle' });
+ }
+
+ private async patchStep(
+ plan: HostSetupPlan,
+ stepId: string,
+ patch: Partial<Omit<HostSetupStep, 'id'>>
+ ): Promise<HostSetupPlan> {
+ const steps = plan.steps.map((step) =>
+ step.id === stepId ? { ...step, ...patch, updatedAt: this.now() } : step
+ );
+ return await this.commit({ ...plan, steps });
+ }
+
+ private async transition(
+ plan: HostSetupPlan,
+ patch: Partial<Pick<HostSetupPlan, 'status' | 'currentStepId'>>
+ ): Promise<HostSetupPlan> {
+ return await this.commit({ ...plan, ...patch });
+ }
+
+ /** Persist then publish. Every visible state change goes through here. */
+ private async commit(plan: HostSetupPlan): Promise<HostSetupPlan> {
+ const next = { ...plan, updatedAt: this.now() };
+ await this.deps.save(next);
+ this.deps.publish(next);
+ return next;
+ }
+}
+
+function findStep(plan: HostSetupPlan, stepId: string): HostSetupStep {
+ const step = plan.steps.find((s) => s.id === stepId);
+ if (!step) throw new Error(`Setup step ${stepId} is not part of the plan for ${plan.sshHost}`);
+ return step;
+}
+
+/** Why a step cannot be advanced automatically — stated in terms of what we saw. */
+function describeUnactionable(step: HostSetupStep): string {
+ switch (step.outcome) {
+ case 'not-running':
+ return `${step.name} is installed but not running. Start it on the host, then retry.`;
+ case 'unknown':
+ return step.error ?? `Could not determine whether ${step.name} is available.`;
+ case 'wrong-version':
+ return `${step.name} is installed but too old, and switchdash has no upgrade command for this host.`;
+ default:
+ return `${step.name} is not installed, and switchdash has no install command for this host.`;
+ }
+}
diff --git a/dash/apps/switchdash-desktop/src/shared/core/remote-hosts/setup.ts b/dash/apps/switchdash-desktop/src/shared/core/remote-hosts/setup.ts
new file mode 100644
index 000000000..9edb8d1d4
--- /dev/null
+++ b/dash/apps/switchdash-desktop/src/shared/core/remote-hosts/setup.ts
@@ -0,0 +1,151 @@
+/**
+ * Model of a remote host's setup run (CHOO-1809).
+ *
+ * Onboarding a host used to be a single boolean — a row existed, or it didn't —
+ * with every prerequisite probed independently by whichever component happened
+ * to render. There was no notion of *where a host got to*, so nothing could be
+ * resumed, nothing could be ordered, and a failure halfway through left no
+ * record beyond whatever the UI happened to be holding in memory.
+ *
+ * A setup plan is that missing object: an ordered list of steps, persisted per
+ * host, advanced one at a time. It is the single answer to "what still needs to
+ * happen on this host, and what went wrong last time we tried?".
+ */
+
+import { defineEvent } from '@shared/lib/ipc/events';
+
+/**
+ * What a check actually observed. Deliberately richer than a boolean, because
+ * the interesting failures are not "missing" (CHOO-1803):
+ *
+ * - `satisfied` — present, correct version, and usable.
+ * - `missing` — not installed.
+ * - `not-running` — installed but the daemon/service is not up (Docker being
+ * the motivating case: `docker` on PATH tells you nothing about dockerd).
+ * - `wrong-version` — installed but below the minimum we require.
+ * - `unknown` — **we could not determine this.** A first-class answer, never
+ * collapsed into satisfied. Reporting "fine" for something we failed to
+ * observe is the stale-green bug from CHOO-1780.
+ */
+export type DependencyCheckOutcome =
+ | 'satisfied'
+ | 'missing'
+ | 'not-running'
+ | 'wrong-version'
+ | 'unknown';
+
+/** Outcomes that mean the step's requirement is genuinely met. */
+export function isSatisfiedOutcome(outcome: DependencyCheckOutcome | null): boolean {
+ return outcome === 'satisfied';
+}
+
+/**
+ * Whether an outcome is something installing could plausibly fix. `not-running`
+ * is excluded on purpose — starting a daemon is not installing a package, and
+ * silently running an installer over a stopped service would misreport the
+ * cause.
+ */
+export function isInstallableOutcome(outcome: DependencyCheckOutcome | null): boolean {
+ return outcome === 'missing' || outcome === 'wrong-version';
+}
+
+/**
+ * Where a step sits in its own lifecycle. Each step owns its state — the whole
+ * point of the rewrite is that step 3 failing says nothing about steps 1-2.
+ *
+ * - `pending` — not reached yet.
+ * - `checking` — a probe is in flight.
+ * - `installing` — an install is in flight.
+ * - `satisfied` — verified present after the last observation.
+ * - `failed` — the check or install failed; carries `error` (and `output` when
+ * a command produced any). The run halts here.
+ * - `skipped` — the user chose to move past it. Never rendered as satisfied.
+ * - `blocked` — an earlier required step failed, so this one was never
+ * attempted. Distinct from `pending`: pending means "not yet", blocked means
+ * "not unless something upstream is fixed".
+ */
+export type HostSetupStepState =
+ | 'pending'
+ | 'checking'
+ | 'installing'
+ | 'satisfied'
+ | 'failed'
+ | 'skipped'
+ | 'blocked';
+
+/** What kind of thing a step manages, for rendering and for install routing. */
+export type HostSetupStepKind = 'core-dependency' | 'agent-cli' | 'agent-plugin' | 'gh-auth';
+
+export type HostSetupStep = {
+ /** Stable within a plan. Dependency id for deps; `<agentId>:plugin` for plugins. */
+ id: string;
+ kind: HostSetupStepKind;
+ /** Display name, resolved when the plan is built. */
+ name: string;
+ state: HostSetupStepState;
+ /** The last thing we actually observed. Null until first checked. */
+ outcome: DependencyCheckOutcome | null;
+ /** Detected version, when the probe found one. */
+ version: string | null;
+ /** Why this step failed. Null unless `state === 'failed'`. */
+ error: string | null;
+ /** Raw command output from a failed install — the detail users need. */
+ output: string | null;
+ /**
+ * An optional step does not block the run or the host's usability. `gh` is
+ * the motivating case: it needs an interactive device-flow login that a user
+ * may reasonably defer without the host being unusable.
+ */
+ optional: boolean;
+ /** Steps that must be satisfied before this one is attempted. */
+ dependsOn: string[];
+ /** ISO timestamp of the last state change. */
+ updatedAt: string;
+};
+
+/**
+ * Plan-level status.
+ *
+ * - `idle` — built (or resumed) and waiting for the user to start.
+ * - `running` — a step is in flight.
+ * - `halted` — a required step failed. **Position is held**: satisfied steps
+ * stay satisfied, the failure keeps its error, and untried steps are blocked.
+ * Resuming re-attempts from the failure rather than starting over.
+ * - `complete` — every required step is satisfied or skipped.
+ */
+export type HostSetupPlanStatus = 'idle' | 'running' | 'halted' | 'complete';
+
+export type HostSetupPlan = {
+ sshHost: string;
+ status: HostSetupPlanStatus;
+ steps: HostSetupStep[];
+ /** The step currently in flight, or the one that halted the run. */
+ currentStepId: string | null;
+ createdAt: string;
+ updatedAt: string;
+};
+
+/** The first step that still needs work, in plan order. Null when nothing is left. */
+export function nextActionableStep(plan: HostSetupPlan): HostSetupStep | null {
+ return (
+ plan.steps.find(
+ (step) => step.state === 'pending' || step.state === 'blocked' || step.state === 'failed'
+ ) ?? null
+ );
+}
+
+/** Required steps that are not yet satisfied — what stands between here and done. */
+export function outstandingRequiredSteps(plan: HostSetupPlan): HostSetupStep[] {
+ return plan.steps.filter((step) => !step.optional && step.state !== 'satisfied');
+}
+
+/**
+ * Whether the host is usable for running agents. Optional steps and skipped
+ * steps do not count against it; a step we could not verify does.
+ */
+export function isPlanComplete(plan: HostSetupPlan): boolean {
+ return outstandingRequiredSteps(plan).length === 0;
+}
+
+/** Pushed to the renderer on every plan transition, so the UI never polls. */
+export const hostSetupPlanEventChannel = defineEvent<HostSetupPlan>('remote-hosts:setup-changed');