feat(web): first-run welcome wizard with agent setup and project import

.agents/upstream-review.md

@@ -55,6 +55,7 @@ Historical groups are indexed in the linked archive. This file migration changes
 | Live activity motion parity / `6c583620ff7ad3235b135af7107c0543467eecfa` | Corrects Pylon's rendering of already-classified `c7c1dfe4df` (#9709), `ce4712d5b0` (#9799) and the #444 port of `6cf0c6ea55` (#9093) / `c3b8825bf4` (#9606) | Pylon had diverged: `cdde7f3150` gave every active row the sweeping overlay and deleted `live-tool-shine`, while upstream reserves the overlay for label-only rows (`active && shimmer`, passed only by the Thinking row) and keeps the shine for tool labels. Restores upstream's `shimmer` prop, `animated = active && !failed` guard, row-level observer ref, overlay on worktree setup and compaction, and both CSS utilities byte-identical to upstream. That same commit also deleted `@utility visible-animate-spin` as dead while `spinner.tsx` and `refresh-icon.tsx` still applied it, so every spinner and refresh glyph was static; restored. Preserved: Pylon's `workingStepLabel`, and the `document.hasFocus()` gate AGENTS.md requires and upstream lacks. Cursor unchanged. | [Live activity parity #452](https://github.com/pylon-code/pylon/pull/452); 161 focused tests, web typecheck, scoped lint/format, region diffed against `t3code-upstream/main`. |
 | Skeleton loading pulse / `6c583620ff7ad3235b135af7107c0543467eecfa` | `21b9dda5afb00a33e228a68d2ccc885bba7285dc` (#9448) | Adopted. The shared `Skeleton` drops its swept gradient band for upstream's single stepped opacity pulse, whose keyframes were already byte-identical to the `ghost-pulse` Pylon ran on the pull-request ghosts; `ghost-pulse` is retired and every loading state now uses `animate-skeleton`. Preserve Pylon's `!seed` gate on the detail ghost, so a panel already showing real content does not breathe, and Pylon's own usage fill-in timing. The maintainer chose upstream theming and styling with only the logo staying Pylon's, which settles this kind of visual divergence in upstream's favour by default. Cursor unchanged. | [Skeleton pulse #451](https://github.com/pylon-code/pylon/pull/451); 339 focused tests, web typecheck, scoped lint/format. |
 | Panel links, markdown galleries, shared title model, usage columns, sidebar file drops, terminal link overrides, Codex limit naming and turn token telemetry / `6c583620ff7ad3235b135af7107c0543467eecfa` | Full ten-source list in PR #458, from #9132 through #10060 | Nine adopted; `b5d89038ae72142038dfa8cf69d49b7a607fe98e` is already covered as an empty duplicate of #7892. Turn telemetry stays inert without a Pylon PostHog key, is recorded only after runtime generation and session incarnation fences, and treats Prime, Cursor, Grok and Antigravity usage as unavailable; OpenCode uses the final #10116 step-retention design. Codex limit errors carry the session incarnation and Pylon keeps relaying every rate-limit notification. Preserve Pylon PR detection, environment-scoped PR caches, provider-instance settings writes, hub account keys, older-server window names, change-request row props and terminal external-browser fallback. New product analytics and usage data docs. Cursor unchanged. | [Web panels #458](https://github.com/pylon-code/pylon/pull/458); 1,687 focused tests, six package typechecks (web, server, shared, client-runtime, contracts, mobile), scoped lint/format; upstream UI evidence linked, no local client pass. |
+| First-run welcome wizard, agent setup and transcript import / `6c583620ff7ad3235b135af7107c0543467eecfa` | Full nine-source list in [#459](https://github.com/pylon-code/pylon/pull/459), from #5362 through #10547 | Adopted all nine: the `/welcome` overlay with multi-computer selection, Claude Code and Codex readiness terminals with native installers, repository-grouped project import, server transcript scan/import with provider resume cursors, settings-hydration hardening, and the light-mode and theme follow-ups. Pylon adaptations: ProviderSessionDirectory keeps its commit guard and exact removal beside insert-ignore and imported transcript records; import invariants use Pylon's open-request scan and Pylon-only thread fields; tests use Pylon's rollback revision and provider-instance compare-and-sets; PylonMark and Pylon/Pylon Connect copy; scans skip Pylon runtime-home worktrees; imported projects keep resolving a default model until #9754 lands. Saved client settings decode per value and keep undecodable stored values (T3 Code's `confirmQuit` shape on a shared origin) instead of failing closed; desktop keeps the default quit hold when its settings file is unreadable. Duplicated sign-in: setup uses Pylon's terminal-free `ProviderSignInDialog` for Claude Code and keeps terminals for installs and `codex login`. Setup reopens from the command palette, and one transcript scanner is shared across connections. Prime and Antigravity stay in Settings → Providers with the other opt-in providers. `3faeee49ac67dfd9534369f1e1c627c0356b75ac` (#10832) is excluded and sequenced later. No migration. Cursor unchanged. | [Welcome wizard #459](https://github.com/pylon-code/pylon/pull/459); 1,703 focused tests, seven package typechecks, scoped lint/format and knip. |
 
 ## Deferred register
 

apps/desktop/src/settings/DesktopClientSettings.diagnostics.test.ts

@@ -54,7 +54,7 @@ const readWithLogs = (fileSystemLayer: Layer.Layer<FileSystem.FileSystem>) => {
     const environment = yield* DesktopEnvironment.DesktopEnvironment;
     const settings = yield* DesktopClientSettings.DesktopClientSettings;
     return {
-      result: yield* settings.get,
+      result: yield* Effect.result(settings.get),
       settingsPath: environment.clientSettingsPath,
       records,
     };
@@ -73,12 +73,13 @@ describe("DesktopClientSettings diagnostics", () => {
     Effect.gen(function* () {
       const result = yield* readWithLogs(FileSystem.layerNoop({}));
 
-      assert.isTrue(Option.isNone(result.result));
+      if (result.result._tag !== "Success") return assert.fail("expected a successful read");
+      assert.isTrue(Option.isNone(result.result.success));
       assert.deepEqual(result.records, []);
     }),
   );
 
-  it.effect("logs non-missing filesystem failures with the settings path", () => {
+  it.effect("reports non-missing filesystem failures and logs the settings path", () => {
     const permissionError = PlatformError.systemError({
       _tag: "PermissionDenied",
       module: "FileSystem",
@@ -93,7 +94,12 @@ describe("DesktopClientSettings diagnostics", () => {
         }),
       );
 
-      assert.isTrue(Option.isNone(result.result));
+      if (result.result._tag !== "Failure") return assert.fail("expected a read failure");
+      assert.instanceOf(
+        result.result.failure,
+        DesktopClientSettings.DesktopClientSettingsReadError,
+      );
+      assert.strictEqual(result.result.failure.cause, permissionError);
       assert.equal(result.records.length, 1);
       assert.deepEqual(result.records[0]?.message, [
         "Could not read desktop client settings.",
@@ -103,15 +109,16 @@ describe("DesktopClientSettings diagnostics", () => {
     });
   });
 
-  it.effect("logs malformed settings documents with the settings path", () =>
+  it.effect("reads malformed settings documents as absent and logs the settings path", () =>
     Effect.gen(function* () {
       const result = yield* readWithLogs(
         FileSystem.layerNoop({
           readFileString: () => Effect.succeed("{not-json"),
         }),
       );
 
-      assert.isTrue(Option.isNone(result.result));
+      if (result.result._tag !== "Success") return assert.fail("expected a successful read");
+      assert.isTrue(Option.isNone(result.result.success));
       assert.equal(result.records.length, 1);
       const message = result.records[0]?.message;
       if (!Array.isArray(message)) {

apps/desktop/src/settings/DesktopClientSettings.test.ts

@@ -43,6 +43,7 @@ const clientSettings: ClientSettings = {
   fontSizeTerminal: 12,
   fontSmoothing: true,
   glassOpacity: 80,
+  onboardingCompletedAt: null,
   panelAnimationDurationMs: 0,
   proactivePanelsEnabled: true,
   showSkillsInSlashMenu: false,
@@ -136,6 +137,59 @@ describe("DesktopClientSettings", () => {
     ),
   );
 
+  for (const failure of [
+    { label: "permission", reason: "PermissionDenied" },
+    { label: "I/O", reason: "Unknown" },
+  ] as const) {
+    it.effect(`preserves saved preferences across ${failure.label} read failures and retries`, () =>
+      withClientSettings(
+        Effect.gen(function* () {
+          const environment = yield* DesktopEnvironment.DesktopEnvironment;
+          const fileSystem = yield* FileSystem.FileSystem;
+          const settings = yield* DesktopClientSettings.DesktopClientSettings;
+          const savedSettings = {
+            ...clientSettings,
+            onboardingCompletedAt: "2026-09-05T12:00:00.000Z",
+          };
+          yield* settings.set(savedSettings);
+          const savedContents = yield* fileSystem.readFileString(environment.clientSettingsPath);
+          const cause = PlatformError.systemError({
+            _tag: failure.reason,
+            module: "FileSystem",
+            method: "readFileString",
+            pathOrDescriptor: environment.clientSettingsPath,
+          });
+          let failRead = true;
+          const retryableSettings = yield* DesktopClientSettings.make.pipe(
+            Effect.provideService(
+              FileSystem.FileSystem,
+              FileSystem.FileSystem.of({
+                ...fileSystem,
+                readFileString: (path) =>
+                  Effect.suspend(() =>
+                    failRead ? Effect.fail(cause) : fileSystem.readFileString(path),
+                  ),
+              }),
+            ),
+          );
+
+          const error = yield* retryableSettings.get.pipe(Effect.flip);
+          assert.instanceOf(error, DesktopClientSettings.DesktopClientSettingsReadError);
+          assert.equal(error.operation, "read-file");
+          assert.equal(error.path, environment.clientSettingsPath);
+          assert.strictEqual(error.cause, cause);
+          assert.equal(
+            yield* fileSystem.readFileString(environment.clientSettingsPath),
+            savedContents,
+          );
+
+          failRead = false;
+          assert.deepEqual(yield* retryableSettings.get, Option.some(savedSettings));
+        }),
+      ),
+    );
+  }
+
   it.effect("reports the failed client settings write operation and path", () =>
     withClientSettings(
       Effect.gen(function* () {
@@ -222,7 +276,7 @@ describe("DesktopClientSettings", () => {
     ),
   );
 
-  it.effect("treats malformed client settings documents as absent", () =>
+  it.effect("reads a malformed settings file as no saved settings without rewriting it", () =>
     withClientSettings(
       Effect.gen(function* () {
         const environment = yield* DesktopEnvironment.DesktopEnvironment;
@@ -232,7 +286,95 @@ describe("DesktopClientSettings", () => {
         yield* fileSystem.writeFileString(environment.clientSettingsPath, "{not-json");
 
         assert.isTrue(Option.isNone(yield* settings.get));
+        assert.equal(yield* fileSystem.readFileString(environment.clientSettingsPath), "{not-json");
       }),
     ),
   );
+
+  for (const document of [
+    { label: "direct", contents: '{"fontSizeCode":"large","timestampFormat":"12-hour"}' },
+    {
+      label: "legacy",
+      contents: '{"settings":{"fontSizeCode":"large","timestampFormat":"12-hour"}}',
+    },
+  ]) {
+    it.effect(`keeps readable ${document.label} settings beside an undecodable value`, () =>
+      withClientSettings(
+        Effect.gen(function* () {
+          const environment = yield* DesktopEnvironment.DesktopEnvironment;
+          const fileSystem = yield* FileSystem.FileSystem;
+          const settings = yield* DesktopClientSettings.DesktopClientSettings;
+          yield* fileSystem.makeDirectory(environment.stateDir, { recursive: true });
+          yield* fileSystem.writeFileString(environment.clientSettingsPath, document.contents);
+
+          assert.deepEqual(
+            yield* settings.get,
+            Option.some({
+              ...(yield* decodeClientSettingsJson("{}")),
+              timestampFormat: "12-hour" as const,
+            }),
+          );
+          assert.equal(
+            yield* fileSystem.readFileString(environment.clientSettingsPath),
+            document.contents,
+          );
+        }),
+      ),
+    );
+  }
+
+  it.effect("leaves an undecodable value in the file until that setting changes", () =>
+    withClientSettings(
+      Effect.gen(function* () {
+        const environment = yield* DesktopEnvironment.DesktopEnvironment;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const settings = yield* DesktopClientSettings.DesktopClientSettings;
+        const readDocument = Effect.flatMap(
+          fileSystem.readFileString(environment.clientSettingsPath),
+          decodeRecordJson,
+        );
+        yield* fileSystem.makeDirectory(environment.stateDir, { recursive: true });
+        yield* fileSystem.writeFileString(
+          environment.clientSettingsPath,
+          '{"confirmQuit":"hold","timestampFormat":"12-hour"}',
+        );
+
+        const saved = Option.getOrThrow(yield* settings.get);
+        assert.isTrue(saved.confirmQuit);
+        yield* settings.set({ ...saved, onboardingCompletedAt: "2026-09-10T12:00:00.000Z" });
+        assert.deepInclude(yield* readDocument, {
+          confirmQuit: "hold",
+          timestampFormat: "12-hour",
+          onboardingCompletedAt: "2026-09-10T12:00:00.000Z",
+        });
+
+        yield* settings.set({ ...saved, confirmQuit: false });
+        assert.deepInclude(yield* readDocument, { confirmQuit: false });
+        yield* settings.set({ ...saved, confirmQuit: false, wordWrap: false });
+        assert.deepInclude(yield* readDocument, { confirmQuit: false, wordWrap: false });
+      }),
+    ),
+  );
+
+  it.effect("keeps the default quit hold when settings cannot be read", () =>
+    Effect.gen(function* () {
+      const failing = DesktopClientSettings.DesktopClientSettings.of({
+        get: Effect.fail(
+          new DesktopClientSettings.DesktopClientSettingsReadError({
+            operation: "read-file",
+            path: "/unreadable/client-settings.json",
+            cause: new Error("permission denied"),
+          }),
+        ),
+        set: () => Effect.void,
+      });
+      const disabled = DesktopClientSettings.DesktopClientSettings.of({
+        get: Effect.succeed(Option.some({ ...clientSettings, confirmQuit: false })),
+        set: () => Effect.void,
+      });
+
+      assert.isTrue(yield* DesktopClientSettings.readConfirmQuit(failing));
+      assert.isFalse(yield* DesktopClientSettings.readConfirmQuit(disabled));
+    }),
+  );
 });