autopilot: address PR #19 review feedback

Why:
- Resolve actionable GitHub review feedback for PR #19.

Changed:
- Closed four review findings with small fail-closed setup fixes: complete lease identity validation, selected-path service-identity retries, blocking fresh setup over existing state-root artifacts, and refreshing the macOS dashboard on an already-ready preview.

Verification:
- npm run agent:complete -- --session-dir [controller artifact: jobs/pr-19/20260825-164548-38b5262d-5f36-4760-a75c-efad32bfa3dc/task-session]
- npm run agent:context -- --paths-file [controller artifact: jobs/pr-19/20260825-164548-38b5262d-5f36-4760-a75c-efad32bfa3dc/actual-paths.txt] --session-dir [controller artifact: jobs/pr-19/20260825-164548-38b5262d-5f36-4760-a75c-efad32bfa3dc/task-session]
- npm run agent:verify -- --profile implementation --paths-file [controller artifact: jobs/pr-19/20260825-164548-38b5262d-5f36-4760-a75c-efad32bfa3dc/task-session/verify/implementation/paths.txt] --session-dir [controller artifact: jobs/pr-19/20260825-164548-38b5262d-5f36-4760-a75c-efad32bfa3dc/task-session]
- npm run agent:verify -- --profile spec-only --paths-file [controller artifact: jobs/pr-19/20260825-164548-38b5262d-5f36-4760-a75c-efad32bfa3dc/task-session/verify/spec-only/paths.txt] --session-dir [controller artifact: jobs/pr-19/20260825-164548-38b5262d-5f36-4760-a75c-efad32bfa3dc/task-session]

Affected:
- .github/workflows/ci.yml
- CHANGELOG.md
- CONTRIBUTING.md
- Casks/simulator-broker.rb
- Formula/simbroker.rb
- README.md
- agent-harness/package-lock.json
- agent-harness/package.json
- app/README.md
- app/Sources/BrokerDashboardStore.swift
- app/Sources/BrokerLocalCommandClient.swift
- app/Sources/BrokerOnboardingCommands.swift
- app/Sources/BrokerServiceClient.swift
- app/Sources/BrokerSetupModels.swift
- app/Sources/BrokerSnapshotLoader.swift
- app/Sources/RootView.swift
- app/Sources/SetupPlanDevicesView.swift
- app/Sources/SetupPlanPrerequisitesView.swift
- app/Sources/SetupPlanSheet.swift
- app/Sources/SharedViews.swift
- app/Tests/BrokerDashboardStoreTests.swift
- app/Tests/BrokerLocalCommandClientTests.swift
- app/Tests/BrokerOnboardingCommandsTests.swift
- app/Tests/BrokerRuntimePathsTests.swift
- app/Tests/BrokerServiceClientTests.swift
- app/Tests/BrokerSnapshotLoaderTests.swift
- broker-core/containment.mjs
- broker-core/error-contract.mjs
- broker-core/index.mjs
- broker-core/simctl.mjs
- broker-core/test/broker-core.test.mjs
- client/bin/simbroker.mjs
- client/command-dispatch.mjs
- client/public-surface.mjs
- client/service/service-client.mjs
- client/setup-preflight.mjs
- client/setup-provisioning-worker.mjs
- client/setup-provisioning.mjs
- client/test/brokerd.test.mjs
- client/test/install-distribution.test.mjs
- client/test/public-surface.test.mjs
- client/test/setup-preflight.test.mjs
- client/test/simbroker.test.mjs
- docs/concepts.md
- docs/getting-started.md
- docs/status.md
- docs/test/front-door.test.mjs
- examples/harness-adoption/README.md
- examples/harness-adoption/sample-consumer-repo/.simulator-broker/project.json
- examples/harness-adoption/sample-consumer-repo/README.md
- packages/simbroker/README.md
- scripts/install_smoke.sh
- scripts/package_distribution.sh
- spec/README.md
- spec/architecture.md
- spec/build-and-test.md
- spec/global-simulator-broker.md
- spec/project-structure.md
- spec/tasks/README.md
- spec/tasks/guided-simbroker-setup.md

Refs:
- #19
- #19 (comment)
- #19 (comment)
- #19 (comment)
- #19 (comment)

Session:
- task-session: [controller artifact: jobs/pr-19/20260825-164548-38b5262d-5f36-4760-a75c-efad32bfa3dc/task-session]
- report: [controller artifact: jobs/pr-19/20260825-164548-38b5262d-5f36-4760-a75c-efad32bfa3dc/report.md]

Author: VladimirBrejcha

CHANGELOG.md

@@ -26,18 +26,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Guided setup binds existing-host confirmation to the requested `--host-id`,
   uses the separate device-type inventory when a runtime omits
   `supportedDeviceTypes`, and fails closed when known-projects or lease/pin
-  JSON cannot be loaded or is not a valid identity record instead of reporting
-  `ready`. Preview probes service identity even when no host is configured yet,
-  so a socket occupied by a different broker is blocked before device creation.
+  JSON cannot be loaded or is not a complete identity record instead of
+  reporting `ready`. A missing host-config with an existing registry, lease,
+  or pin record in the selected state root is blocked rather than treated as
+  a confirmable fresh plan. Preview probes service identity even when no host
+  is configured yet, so a socket occupied by a different broker is blocked
+  before device creation.
   `ready` also requires the app snapshot to be at least as new as
   known-projects, lease/pin records, and the lease/pin directories, and to
   match the current doctor-record set, so deletions are finishing work rather
   than a stale `ready`. Fallback device-type selection is identifier-stable
-  when preferred names are absent. Setup failure recovery commands keep the
-  selected `--host-config`, `--state-root`, and `--service-socket` paths.
-  The macOS app keeps automatic service/snapshot finishing off the first-time
-  review sheet. Setup apply Stop/timeout waits for rollback inventory calls
-  before escalating to SIGKILL.
+  when preferred names are absent. Setup failure recovery commands, including
+  service-identity retries, keep the selected `--host-config`, `--state-root`,
+  and `--service-socket` paths. The macOS app keeps automatic service/snapshot
+  finishing off the first-time review sheet and refreshes the dashboard when
+  setup preview is already `ready`. Setup apply Stop/timeout waits for rollback
+  inventory calls before escalating to SIGKILL.
 - Public CI no longer runs the full-repo home-path leak scan on
   GitHub-hosted runners. Ubuntu (10 minutes) runs skill ownership,
   `test:broker-core`, and `test:harness-adoption`. macOS (15 minutes)

app/Sources/BrokerDashboardStore.swift

@@ -566,7 +566,9 @@ final class BrokerDashboardStore {
         setupPlan = nil
         pendingSetupConfirmation = nil
         if plan.status == .ready {
+          try await requireRefreshAfterMutation()
           setupPhase = .idle
+          lastErrorMessage = nil
           setActionMessage("Setup complete — brokerd is running and all managed simulators are healthy.")
           return
         }

app/Tests/BrokerDashboardStoreTests.swift

@@ -780,6 +780,78 @@ final class BrokerDashboardStoreTests: XCTestCase {
     XCTAssertEqual(store.setupPhase, .idle)
   }
 
+  func testGuidedSetupReadyPreviewRefreshesDashboardBeforeSuccess() async throws {
+    let runtimePaths = BrokerRuntimePaths(
+      stateRoot: URL(fileURLWithPath: "/tmp/simbroker-ready-refresh-state"),
+      hostConfigURL: URL(fileURLWithPath: "/tmp/simbroker-ready-refresh-host.json"),
+      configuredCLIURL: URL(fileURLWithPath: "/tmp/fake-simbroker")
+    )
+    let staleState = BrokerLoadedState(
+      paths: runtimePaths,
+      tooling: BrokerToolingState(cliPath: runtimePaths.configuredCLIURL, hostConfigExists: false, installMetadata: nil),
+      service: nil,
+      snapshot: nil
+    )
+    let readySnapshot = try loadFixture(named: "busy-snapshot")
+    let readyState = BrokerLoadedState(
+      paths: runtimePaths,
+      tooling: BrokerToolingState(cliPath: runtimePaths.configuredCLIURL, hostConfigExists: true, installMetadata: nil),
+      service: BrokerServiceMetadata(
+        hostConfigPath: runtimePaths.hostConfigURL.path,
+        pid: 321,
+        socketPath: "/tmp/simbroker-ready-refresh.sock",
+        startedAt: "2026-04-09T10:00:00Z",
+        stateRoot: runtimePaths.stateRoot.path,
+        transport: "unix-http"
+      ),
+      snapshot: readySnapshot
+    )
+    let loader = SequencedSnapshotLoader(states: [readyState])
+    let localRunner = RecordingLocalCommandRunner()
+    let setupPlan = try makeSetupPlan(
+      status: "ready",
+      confirmationRequired: false,
+      hostConfigured: true,
+      includeRuntime: false,
+      createCount: 0
+    )
+    await localRunner.enqueue(
+      BrokerCLICommandEnvelope(
+        error: nil,
+        exitCode: 0,
+        ok: true,
+        reasonCode: nil,
+        setupPlan: setupPlan,
+        started: nil,
+        status: "ready",
+        unchanged: nil
+      )
+    )
+    let store = BrokerDashboardStore(
+      loader: loader,
+      commandClient: RecordingCommandClient(),
+      localCommandRunner: localRunner,
+      runtimePaths: runtimePaths
+    )
+    store.loadedState = staleState
+
+    XCTAssertEqual(store.startupState, .needsHostBootstrap)
+
+    store.requestGuidedSetup()
+    try await waitUntil {
+      await MainActor.run { store.setupPhase == .idle && store.lastActionMessage != nil }
+    }
+
+    let invocations = await localRunner.invocations()
+    XCTAssertEqual(invocations.count, 1)
+    XCTAssertEqual(store.lastActionMessage, "Setup complete — brokerd is running and all managed simulators are healthy.")
+    XCTAssertEqual(store.startupState, .ready)
+    XCTAssertEqual(store.loadedState?.tooling.hostConfigExists, true)
+    XCTAssertNotNil(store.loadedState?.snapshot)
+    let loadCount = await loader.loadCount()
+    XCTAssertEqual(loadCount, 1)
+  }
+
   func testGuidedSetupAutomaticFinishingDoesNotPresentSetupSheet() async throws {
     let runtimePaths = BrokerRuntimePaths(
       stateRoot: URL(fileURLWithPath: "/tmp/simbroker-auto-finish-state"),

broker-core/index.mjs

@@ -1582,6 +1582,17 @@ function setupStateContainsLeaseOrPinRecords(paths) {
   }
 }
 
+function setupStateContainsExistingBrokerArtifacts(paths) {
+  try {
+    if (fs.existsSync(paths.registryPath) && fs.statSync(paths.registryPath).isFile()) {
+      return true;
+    }
+    return setupStateContainsLeaseOrPinRecords(paths);
+  } catch {
+    return true;
+  }
+}
+
 function setupExistingHostState(paths, inventory, options = {}) {
   let hostConfig;
   try {
@@ -1772,11 +1783,49 @@ function setupExistingHostState(paths, inventory, options = {}) {
   };
 }
 
+function blockedSetupExistingStateWithoutHost(paths, options = {}) {
+  const hostId = requestedSetupHostId(options)
+    ?? slugifyIdentifier(options.hostId ?? defaultHostId(), defaultHostId());
+  const planId = setupPlanFingerprint({
+    configured: false,
+    devices: [],
+    hostConfig: null,
+    hostId,
+    runtime: null,
+  });
+  return {
+    hostConfig: null,
+    preview: {
+      command: "setup",
+      confirmation: { createCount: 0, required: false, reuseCount: 0 },
+      devices: [],
+      host: { action: "keep", configured: false, hostId },
+      mode: "preview",
+      nextSteps: ["simbroker doctor"],
+      ok: true,
+      planId,
+      prerequisites: [{
+        id: "state-root",
+        remediationCommands: ["simbroker doctor"],
+        status: "blocked",
+        summary: "The selected state root already contains broker state and setup will not create a new host over it.",
+      }],
+      runtime: null,
+      schemaVersion: SETUP_SCHEMA_VERSION,
+      service: { action: "blocked", running: false },
+      status: "blocked",
+    },
+  };
+}
+
 function buildSetupPlan(paths, options = {}) {
   const inventory = readSimctlInventory(options);
   if (fs.existsSync(paths.hostConfigPath)) {
     return setupExistingHostState(paths, inventory, options);
   }
+  if (setupStateContainsExistingBrokerArtifacts(paths)) {
+    return blockedSetupExistingStateWithoutHost(paths, options);
+  }
 
   const runtime = selectRuntimeForSetup(inventory, options.iosVersion);
   const hostId = slugifyIdentifier(options.hostId ?? defaultHostId(), defaultHostId());
@@ -2343,10 +2392,28 @@ function listJsonFiles(dirPath) {
     .map(readJson);
 }
 
+function requirePositiveIntegerField(value, name) {
+  const normalized = normalizePositiveInteger(value);
+  if (normalized === null) {
+    throw new BrokerError(`${name} must be a positive integer.`, {
+      field: name,
+      reasonCode: "invalid-config",
+    });
+  }
+  return normalized;
+}
+
 function assertValidLeaseRecord(record) {
   requireObject(record, "lease");
   requireString(record.leaseId, "lease.leaseId");
   requireString(record.alias, "lease.alias");
+  requireString(record.simulatorId, "lease.simulatorId");
+  requireString(record.actorType, "lease.actorType");
+  requireString(record.actorId, "lease.actorId");
+  requireString(record.projectId, "lease.projectId");
+  requireString(record.purposeId, "lease.purposeId");
+  requireString(record.startedAt, "lease.startedAt");
+  requirePositiveIntegerField(record.ownerPid, "lease.ownerPid");
   return record;
 }
 

broker-core/test/broker-core.test.mjs

@@ -1215,6 +1215,71 @@ test("setup blocks an existing host when doctor-relevant state files are malform
   assert.equal(emptyPinBlocked.status, "blocked");
   assert.ok(emptyPinBlocked.prerequisites.some((issue) =>
     issue.id === "leases" && issue.status === "blocked"));
+
+  fs.rmSync(path.join(resolvedPaths.pinsDir, "empty-pin.json"));
+  writeJson(path.join(resolvedPaths.leasesDir, "partial-lease.json"), {
+    alias: "ui-1",
+    leaseId: "partial-lease",
+  });
+  const partialLeaseBlocked = previewSetupBroker(resolvedPaths, {
+    simctlAdapter: paths.simctl.adapter,
+  });
+  assert.equal(partialLeaseBlocked.status, "blocked");
+  assert.ok(partialLeaseBlocked.prerequisites.some((issue) =>
+    issue.id === "leases" && issue.status === "blocked"));
+  assert.throws(() => applySetupBroker(resolvedPaths, {
+    confirmPlanId: partialLeaseBlocked.planId,
+    simctlAdapter: paths.simctl.adapter,
+  }), (error) => error.payload?.reasonCode === "setup-prerequisite-failed");
+  assert.equal(fs.existsSync(path.join(resolvedPaths.leasesDir, "partial-lease.json")), true);
+});
+
+test("setup blocks a missing host config when the state root already has broker records", () => {
+  const paths = makePaths();
+  const resolvedPaths = brokerPaths(paths);
+  fs.mkdirSync(resolvedPaths.stateRoot, { recursive: true });
+  writeJson(resolvedPaths.registryPath, {
+    aliases: {},
+    updatedAt: "2026-01-01T00:00:00.000Z",
+    version: 1,
+  });
+
+  const registryBlocked = previewSetupBroker(resolvedPaths, {
+    hostId: "fresh-over-state",
+    simctlAdapter: paths.simctl.adapter,
+  });
+  assert.equal(registryBlocked.status, "blocked");
+  assert.equal(registryBlocked.confirmation.required, false);
+  assert.ok(registryBlocked.prerequisites.some((issue) =>
+    issue.id === "state-root" && issue.status === "blocked"));
+  assert.throws(() => applySetupBroker(resolvedPaths, {
+    confirmPlanId: registryBlocked.planId,
+    hostId: "fresh-over-state",
+    simctlAdapter: paths.simctl.adapter,
+  }), (error) => error.payload?.reasonCode === "setup-prerequisite-failed");
+  assert.equal(fs.existsSync(paths.hostConfigPath), false);
+
+  fs.rmSync(resolvedPaths.registryPath);
+  fs.mkdirSync(resolvedPaths.leasesDir, { recursive: true });
+  writeJson(path.join(resolvedPaths.leasesDir, "leftover.json"), {
+    alias: "ui-1",
+    leaseId: "leftover",
+  });
+  const leftoverBlocked = previewSetupBroker(resolvedPaths, {
+    simctlAdapter: paths.simctl.adapter,
+  });
+  assert.equal(leftoverBlocked.status, "blocked");
+  assert.ok(leftoverBlocked.prerequisites.some((issue) =>
+    issue.id === "state-root" && issue.status === "blocked"));
+
+  fs.rmSync(path.join(resolvedPaths.leasesDir, "leftover.json"));
+  const emptyLeaseDir = previewSetupBroker(resolvedPaths, {
+    hostId: "fresh-empty-state",
+    simctlAdapter: paths.simctl.adapter,
+  });
+  assert.equal(emptyLeaseDir.status, "changes_required");
+  assert.equal(emptyLeaseDir.confirmation.required, true);
+  assert.equal(emptyLeaseDir.host.configured, false);
 });
 
 test("setup blocks an existing host whose registry marks an alias for repair", () => {

client/bin/simbroker.mjs

@@ -697,8 +697,9 @@ function setupPrerequisiteFromError(error) {
   };
 }
 
-function serviceIdentityRecoveryCommands(error) {
+function serviceIdentityRecoveryCommands(error, paths) {
   const actual = error?.payload?.actual;
+  const retryCommand = setupRecoveryCommand(paths);
   if ([actual?.hostConfigPath, actual?.stateRoot, actual?.socketPath]
     .every((value) => typeof value === "string" && value.length > 0)) {
     return [
@@ -708,10 +709,10 @@ function serviceIdentityRecoveryCommands(error) {
         "--state-root", shellQuoteArgument(actual.stateRoot),
         "--service-socket", shellQuoteArgument(actual.socketPath),
       ].join(" "),
-      "simbroker setup",
+      retryCommand,
     ];
   }
-  return ["simbroker service status --json", "simbroker setup"];
+  return ["simbroker service status --json", retryCommand];
 }
 
 async function buildSetupPreview(paths, options) {
@@ -746,7 +747,7 @@ async function buildSetupPreview(paths, options) {
         prerequisites: [...corePreview.prerequisites, {
           details: error?.payload ?? { error: error?.message ?? String(error) },
           id: "service-identity",
-          remediationCommands: serviceIdentityRecoveryCommands(error),
+          remediationCommands: serviceIdentityRecoveryCommands(error, paths),
           status: "blocked",
           summary: error?.message ?? "The running broker service uses different paths.",
         }],

client/test/simbroker.test.mjs

@@ -622,9 +622,13 @@ test("setup identity blockers provide a stop command for the running service pat
     hostConfigPath: fixture.hostConfigPath,
     stateRoot: fixture.stateRoot,
   }).serviceSocketPath;
+  const selectedPaths = resolveBrokerPaths({
+    hostConfigPath: otherHostConfigPath,
+    stateRoot: fixture.stateRoot,
+  });
   assert.deepEqual(serviceIdentity.remediationCommands, [
     `simbroker service stop --host-config '${fixture.hostConfigPath}' --state-root '${fixture.stateRoot}' --service-socket '${serviceSocketPath}'`,
-    "simbroker setup",
+    `simbroker setup --host-config '${otherHostConfigPath}' --state-root '${fixture.stateRoot}' --service-socket '${selectedPaths.serviceSocketPath}'`,
   ]);
 
   const stopped = spawnSync(process.execPath, [

spec/tasks/guided-simbroker-setup.md

@@ -1,7 +1,7 @@
 # Guided `simbroker setup`
 
 > **Document ID:** `GSB-SETUP-001`
-> **Version:** `1.0.7`
+> **Version:** `1.0.8`
 > **Last Updated:** `2026-08-25`
 > **Status:** `Active`
 > **Owner:** `spec-steward`, `ios-dev`
@@ -186,8 +186,11 @@ Apply performs, in order:
 - Existing invalid/unhealthy host is blocked without repair/replacement,
   lease/pin mutation, or retirement. Invalid known-projects or lease/pin JSON
   is the same class of existing-host failure: diagnose with `simbroker doctor`,
-  do not report `ready`. Valid JSON that is not a lease or pin identity record,
-  such as `{}`, is invalid existing-host state.
+  do not report `ready`. Valid JSON that is not a complete lease or pin
+  identity record, such as `{}` or a lease with only `leaseId` and `alias`,
+  is invalid existing-host state. Setup does not treat a missing host-config
+  as a confirmable fresh plan when the selected state root already contains a
+  registry file or lease/pin JSON.
 - Preview probes the requested service socket even when no host is configured
   yet. A running broker with a different host-config, state-root, or socket
   identity is a `service-identity` blocker and is not confirmable, so apply
@@ -218,10 +221,12 @@ Service/snapshot-only plans apply immediately without a device sheet.
 Automatic finishing progress is tracked on the dashboard without presenting
 the first-time review sheet. Blocked plans show commands and no enabled
 confirm. Success refreshes to the dashboard and says: `Setup complete —
-brokerd is running and all managed simulators are healthy.` Failure of a
-confirmable plan refreshes first, preserves the sheet, and shows completed
-stages and recovery. Automatic finishing failure stays off the sheet and
-surfaces the recovery error on the dashboard.
+brokerd is running and all managed simulators are healthy.` A preview that
+is already `ready` refreshes the current snapshot before reporting that
+success, matching confirmed apply. Failure of a confirmable plan refreshes
+first, preserves the sheet, and shows completed stages and recovery.
+Automatic finishing failure stays off the sheet and surfaces the recovery
+error on the dashboard.
 
 The app accepts only setup schema version 1 and rejects a future or otherwise
 unsupported version before presenting or applying its plan. The `@MainActor
@@ -413,6 +418,7 @@ long-running plan/handoff/evaluation, and a passing `agent:complete`.
 
 | Version | Date | Author | Changes |
 |---|---|---|---|
+| 1.0.8 | 2026-08-25 | `spec-steward`, `ios-dev` | Block partial lease records and missing-host state roots that already contain registry/lease/pin artifacts, keep selected paths on service-identity retries, and refresh the app dashboard on an already-ready setup preview |
 | 1.0.7 | 2026-08-25 | `spec-steward`, `ios-dev` | App Stop/timeout SIGTERM window includes rollback attribution inventory and the extra inventory after an indeterminate create failure |
 | 1.0.6 | 2026-08-25 | `spec-steward`, `ios-dev` | Fail closed on schema-invalid lease/pin JSON, keep fallback device types order-stable, exclude automatic finishing from the setup sheet, treat doctor-record deletions as snapshot finishing work, and preserve selected path overrides in recovery commands |
 | 1.0.5 | 2026-08-25 | `spec-steward`, `ios-dev` | Preview probes service identity on unconfigured hosts, and `ready` requires the snapshot to be at least as new as known-projects and lease/pin JSON |